In WipperSnapper terminology, pin components are digital outputs (i.e.: an LED, a motor), analog inputs (i.e.: a potentiometer or a light sensor), or digital inputs (i.e.: a push-button or a PIR sensor). 

Adding a "pin component" to WipperSnapper involves writing a small amount of descriptive JSON and adding an image. 

Identifying the Type of Pin Component to Use

This guide page uses the Flat Vibration Switch sold in the Adafruit store as an example of a pin component that can be added to WipperSnapper. You will need to modify the instructions to fit the needs/specifications of your component.

The first step is to identify what type of pin component this switch is.

When the vibration switch gets bumped, it acts as a closed switch. In order to get the state of the switch, a microcontroller needs to configure the switch as a digital input as it only reports two states: when the switch is either open ('0') or closed ('1').

So, we'll be creating a digital input pin component as we'll want the vibration switch to send data to WipperSnapper when it reports a boolean state (open or closed).

Add Component JSON

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 Git branch to work within. In this case, name it add-flat-vibration-switch.

Next, navigate to the Wippersnapper_Components/components/pin directory and make a copy of a component with similar functionality. The toggle switch component and the vibration switch both operate the same way and send the same values if they're toggled.

Create a copy of the toggle_switch folder.

Component folder names should use underscores and the name should be lower case (i.e: my_component).

Rename the toggle_switch copy folder to flat_vibration_switch.

Modify Component Definition JSON File

The definition.json file within this folder is known as the definition file, it defines the pin-based WipperSnapper component for use in Adafruit IO. 

Using a text editor, open the toggle switch's definition.json file.

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.

We'll start by changing the displayName from "Toggle Switch" to "Flat Vibration Switch". You should change the displayName to reflect the component you're adding.

At this point, the definition.json file looks like the following.

Next, set the required pin mode field. This field may either be ANALOG or DIGITAL. Since the microcontroller reading a vibration switch will either read a digital 1 or a digital 0 value, its mode is digital.

At this point, the definition.json file looks like the following.

Finally, the last of the required fields is the pin's direction which may be either INPUT or OUTPUT. Data from the vibration switch will be read into the board, so  define an INPUT direction.

The optional autoSelectString field is a hint for automatically looking up pin names. For example, an LED component will automatically select a pin labeled "LED" if the pin exists. 

In the vibration switch case, this field is not required so it can be removed.

The defaultPeriod field describes the default value of the Period field on the "Component Settings" form on WipperSnapper (in seconds). You may leave this as-is.

However, some sensors may take a longer amount of time than the 30-second default to gather readings and this time period may need to be adjusted.

(Optional) Add Component Visualization 

You may (optionally) add some text to the definition file to describe its "look" on the Adafruit IO device interface. 

While optional, a component with visualization not only makes it visually prettier - it adds function! Adafruit IO component visualization includes icons and labels to explain what the component does.

For example, this is a LED switch component without a defined visualization:

And this is a vibration switch component on Adafruit IO with a visualization defined in its definition file.

Adding the following visualization object to your component's definition.json will define its look and feel:

The components visualization type may be either a switch or a button (we're working on adding more component types). Each type is omnidirectional, meaning it may be used as either an output or an input.

The off/onLabel and off/onIcons are specific to the switch component type.

• For an example of how the button component type works, check out the definition.json file for the push button component.

The component's labels (onLabel and offLabel) correspond to its physical state. For example, a vibration sensor when "off" is still (reflected by the offLabel above). When the vibration sensor is activated (by movement or touch), we'll change the onLabel to "Touched".

The component's icons, onIcon and offIcon, correspond to the component's on and off state.

For example, the onIcon is defined as:

"onIcon": "fa6:solid:bell-on"

bell-on is the name of the icon, with a bunch of namespaces in front of it. Let's break it down:

• fa6 means we are using a set of icons called Font Awesome 6
• solid is the style of the icon. There are 4 icon styles to pick from - light, thin, regular and solid.
• bell-on is the name of the icon. 

To find an icon, visit https://fontawesome.com/icons to search for an icon you like. 

Clicking on an icon will show you the various icon styles.

Once you've completed adding the visualization object to the component's definition, you're finished editing its definition. A complete definition.json file should look something like the following.

Add Component Image

Next, you'll need to add an image of your component. It's best to 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 x 300px
  
• Image file's size must be at least 3kb and must not exceed 100kb

For the flat vibration switch, it is the first image from the Adafruit Store product page. Next, this image must be resized. Using a web-based tool such as https://picresize.com is suggested and ensuring the final image is 300px by 300px. 

Add the resized image to the flat_vibration_switch folder and rename it image.png. 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 x 300px
  
• File is between 5kb and 700kb

Commit Your Changes and Push

Next, let's 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

Next, follow this page to submit a pull request to add your component to WipperSnapper.

Submit a Pull Request

Finally, it's time 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!

Click "Create pull request".

The repository will run checks on these files. If the checks pass, Adafruit will review the files. 

For reference, an example of this pull request is here >>>

Testing your Pin Component

As part of our review process, we'll make your component appear under the component picker as "in development". This allows you to test the component before giving us (Adafruit) the final OK.

On your Adafruit IO Device page, open the component picker. Click the "Show Dev" checkbox.

You should see the pin component you just added.

Make sure everything on the form looks okay. Then, create your component and test it out with a device.

Once you've fully tested your component and are satisfied with how it works, let us know in the Pull Request and we'll make it live on Adafruit IO!