Add Component JSON Definition

This page assumes you've followed the instructions on the Get Setup page and have the WipperSnapper_Components repository forked and locally cloned.

First, create a branch to work within. In our case, we'll name it add-mcp9808.

Next, navigate to the Wippersnapper_Components/components/i2c directory. Create a new folder named mcp9808.

Within the mcp9808 folder, add a new file named definition.json. This will hold the definition of the physical sensor for the WipperSnapper website.

JSON files are written as pairs of keys and values, separated by a semicolon.

The first key/value pair in the JSON definition is displayName, which is the human-friendly name of a component. This field is required

The next key/value pair is published. This pair should be set to false until the component driver is distributed with a release of WipperSnapper.

{
    "displayName": "MCP9808",
    "published": false,
}

Each I2C device has a unique address to identify it by. We have a list of I2C addresses on this page. If it's not on that page, check the sensor's datasheet. 

According to its documentation, the Adafruit MCP9808's I2C addresses can range from 0x18 to 0x1C.

These addresses are listed within the i2cAddresses field in the JSON definition:

{
    "displayName": "MCP9808",
    "i2cAddresses": [ "0x18", "0x19", "0x1A", "0x1C" ],
}

Add an Image of the Sensor

Next, you'll need to add an image of the sensor. It is recommended to obtain a photo of the component from the manufacturer's website.

First, make sure your image adheres to the following specifications: 

  • The Image file's extension can be any one of: jpg, jpeg, gif, png, svg
  • The image file's dimensions must not exceed 400px by 300px
  • The image file's proportions / aspect ratio (Width : Height) must be 4:3
  • The image file's size must be at least 3kb and must not exceed 100kb

For this example, we are using the first image from the Adafruit Store product page.

Next, this image must be resized. It is suggested to use a web-based tool such as https://picresize.com and ensure the final image is 400px x 300px. 

Add the resized image to the mcp9808 folder and rename it image.EXTENSION. You may need to delete the existing file, there should only be one file named image.EXTENSION in this folder.

You may also delete the optional animation.gif file within this folder if you are not planning to add one.

(Optional) Add an Animation GIF

This step is optional due to the amount of work required to produce an animation. The optional animation.gif file also must adhere to the following specifications:

  • File must ALWAYS be .gif
  • File dimensions must be a maximum of 400px by 300px and at 4:3 ratio
  • File is between 5kb and 700kb

The Ruiz brothers have a video on how to create a spinning board animation below:

Commit Your Changes and Push

Next, add all these changes to your fork. Add your components using the git add command.

Typing git status shows the files you're about to add.

Then, commit the files by typing git commit -m "adding new component"

And push to your forked repository, git push yourRepo add-component-name

Submit a Pull Request

Finally, submit a pull request to add the component to WipperSnapper!

After you've pushed the updated files to your branch, navigate to https://github.com/adafruit/Wippersnapper_Components/pulls and click "Compare & pull request".

Give your pull request a name and a description. Make it as descriptive as possible and click "Create pull request".

The repository will run checks on these files. If the checks pass, Adafruit will review the files. When approved, they'll be automatically added to WipperSnapper and available under the component picker along with the form options you added to the definition.json file.

For reference, the pull request above is located here

This guide was first published on Mar 10, 2022. It was last updated on Jul 16, 2024.

This page (Add the Definition JSON) was last updated on May 17, 2024.

Text editor powered by tinymce.