I2C is a popular protocol that uses two wires to communicate with sensors (often called I2C devices). If you need a quick overview (or refresher!) of how I2C works, read through this guide page.

The following page(s) will go over the process of adding your favorite I2C sensor.

You will need to follow this page first, then the "Adding an I2C Component Driver" page after.

The process of adding I2C components is more involved than adding a pin component and you'll be asked to write some C++ code. If you haven't written C++ before - don't worry - this guide will walk you through the process and provide examples.

As an example, the following uses the MCP9808 High Accuracy I2C Temperature Sensor Breakout for this guide since it's a simple breakout that only reports temperature data.

Keep in mind that some I2C breakouts have multiple sensors which report multiple types of data (such as temperature, humidity, altitude, etc.). The more types of data reported by a sensor, the more involved its I2C component driver code will be.

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 the displayName, which is the human-friendly name of a component. This field is required. 

{
    "displayName": "MCP9808",
}

{
    "displayName": "MCP9808",
}

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" ],
}

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

Next, add the list of subcomponents. These are all the sensors on the I2C device.

The MCP9808 breakout only has an ambient temperature sensor. There are two types of ambient temperature sensors on the list of sensor types - "ambient-temp" and "ambient-temp-fahrenheit". The ambient-temp sensor type tells Adafruit IO that a sensor on this breakout will send ambient temperature data back in degree Celsius. Adding ambient-temp-fahrenheit to the list of subcomponents will allow a user on Adafruit IO to select between having the sensor return the temperature in either degree Celsius or degree Fahrenheit. 

The final .JSON file for this sensor is below (and here it is on GitHub)

{
  "displayName": "MCP9808",
  "i2cAddresses": [ "0x18", "0x19", "0x1A", "0x1C" ],
  "subcomponents": [ "ambient-temp", "ambient-temp-fahrenheit" ]
}

{
  "displayName": "MCP9808",
  "i2cAddresses": [ "0x18", "0x19", "0x1A", "0x1C" ],
  "subcomponents": [ "ambient-temp", "ambient-temp-fahrenheit" ]
}

Add Component Image

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

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

• Image file's extension can be any one of: jpg, jpeg, gif, png, svg
  
• Image file's dimensions must be 300px by 300px
  
• Image file's size must be at least 3kb and must not exceed 100kb

Below is the first image from the Adafruit Store product page.

Next, this image must be resized. It is suggested using a web-based tool such as https://picresize.com and ensuring the final image is 300px by 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 Component Animation

This step is optional due to the amount of work required to produce an animation. The Ruiz brothers have a video on how to create a spinning board animation below:

The optional animation.gif file also must adhere to the following specifications:

• File must ALWAYS be .gif
  
• File dimensions must be 300px by 300px
  
• File is between 5kb and 700kb

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, to 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.