Wippersnapper Component Definitions

Welcome! This repository contains JSON definition files and images that allow components and sensors to be used with WipperSnapper, Adafruit IO's no-code IoT service.

Click here to submit suggestions or requests for new Adafruit.io WipperSnapper components >>>

How Does It Work?

Anyone can add a new component to WipperSnapper by writing a small amount of descriptive JSON and adding an image! If accepted, a supported component will:

Appear in this list

Generate a custom web form, like this

Have its current status tracked or controlled, like this

And work seamlessly with the rest of IO, including Dashboards and Triggers!

Repository Structure

components/
├── pin/             # Digital/analog GPIO components (LEDs, buttons, sensors)
├── i2c/             # I2C sensor breakouts (temperature, pressure, humidity, etc.)
├── i2c_output/      # I2C output displays (OLEDs, character LCDs, 7-segment, etc.)
├── display/         # TFT and E-Ink displays
├── ds18x20/         # 1-Wire DS18x20 temperature sensors
├── pixel/           # Addressable LED strips (NeoPixel, DotStar)
├── pwm/             # PWM-controlled devices (dimmable LEDs, buzzers)
├── servo/           # Servo motor controllers
├── uart/            # UART/serial-based sensors
└── sensors.json     # Centralized registry of sensor type definitions

Each component type directory contains:

schema.json — JSON Schema that validates component definitions of that type.
One subdirectory per component, each containing:
- definition.json — The component definition (validated against the parent schema.json).
- An image file (.jpg, .png, or .svg) — A photo or illustration of the component.

Contributing

We have a guide on adding components to this repository on the Adafruit Learning System

Image Requirements

Images included with component definitions are validated by CI and must meet these requirements:

Requirement	Rule
Format	`.jpg`, `.png`, or `.svg` only
Aspect Ratio	4:3
Max Size	400 × 300 pixels
Max File Size	100 KB
Filename	Lowercase only, no uppercase characters

Validation

All pull requests are automatically validated by CI. The validation pipeline checks:

Schema validation — Every definition.json is validated against its component type's schema.json.
Filename rules — No uppercase characters in file or directory names.
Image rules — Format, dimensions, aspect ratio, and file size (see above).
Permission scoping — External contributors may only add or modify definition.json files and images within component subdirectories. Only Adafruit maintainers may modify schema.json or sensors.json.

Common Fields

All component types share these fields (in addition to their type-specific required fields):

Field	Type	Description
`displayName`	string	(required) The human-friendly name of this component. 3–24 characters (up to 30 for some types).
`vendor`	string	(required) Name of the company that makes this component. 3–24 characters.
`published`	boolean	If `true`, the component is visible to all users. If `false`, it is hidden behind a developer toggle.
`description`	string	A brief description of the component's capabilities. 3–255 characters.
`productURL`	string	URL to the component's product page.
`documentationURL`	string	URL to the component's documentation.

Component Formats

Pin

Pin components represent digital or analog GPIO-based devices such as LEDs, buttons, and basic sensors.

Required fields: displayName, vendor, mode, direction

Field	Type	Description
`mode`	string	`DIGITAL` or `ANALOG`.
`direction`	string	`INPUT` or `OUTPUT`.
`autoSelectString`	string	A hint for automatically looking up appropriate pin names. 3–24 characters.
`selectPullUp`	boolean	If `true`, the user can select pull-up or pull-down options.
`pull`	string	Pull setting: `UP` or `DOWN`.
`selectReadMode`	boolean	If `true`, the user can select the read mode between pin value and voltage.
`analogReadMode`	string	For `ANALOG` mode: `PIN_VALUE` or `PIN_VOLTAGE`. Acts as a default if `selectReadMode` is `true`.
`defaultPeriod`	number	Default polling period in seconds (30–86400). If present, the form allows the user to set a period.
`forceOnPeriod`	boolean	If `true`, the user must specify a period (it won't be optional).
`visualization`	object	Specifies the UI widget. See Pin Visualization Types.

Pin Visualization Types

The visualization object requires a type field. Allowed types:

switch — A toggle switch. Optional fields: offLabel, offIcon, onLabel, onIcon (strings).
button — A push button. Optional fields: pressedLabel, unpressedLabel (strings).
slider — A slider control. No additional fields.

Example: LED (digital output with switch)

{
  "displayName": "LED",
  "vendor": "Generic",
  "mode": "DIGITAL",
  "direction": "OUTPUT",
  "visualization": {
    "type": "switch",
    "offIcon": "fa6:regular:lightbulb",
    "onIcon": "fa6:solid:lightbulb-on"
  }
}

Example: Push Button (digital input)

{
  "displayName": "Push Button",
  "vendor": "Generic",
  "mode": "DIGITAL",
  "direction": "INPUT",
  "defaultPeriod": 30,
  "selectPullUp": true,
  "visualization": {
    "type": "button"
  }
}

Example: Potentiometer (analog input with slider)

{
  "displayName": "Potentiometer",
  "vendor": "Generic",
  "mode": "ANALOG",
  "direction": "INPUT",
  "defaultPeriod": 60,
  "analogReadMode": "PIN_VALUE",
  "selectReadMode": true,
  "visualization": {
    "type": "slider"
  }
}

I2C

I2C components represent sensor breakouts connected via the I2C bus. Each component can expose one or more sensor subcomponents (e.g. a BME280 exposes temperature, humidity, pressure, and altitude).

Required fields: displayName, vendor, i2cAddresses, subcomponents

Field	Type	Description
`i2cAddresses`	array	List of I2C addresses as hex strings (e.g. `"0x77"`).
`subcomponents`	array	List of sensor subcomponents. Each item is either a sensor type string or an object (see below).

I2C Subcomponent Format

Each subcomponent can be a simple sensor type string (e.g. "ambient-temp") or an object with:

Field	Type	Description
`displayName`	string	(required) Human-friendly name of the sensor. 3–30 characters.
`sensorType`	string	(required) One of the supported Sensor Types.
`type`	string	A unique lookup string for this sensor and its parent component. 3–24 chars.
`defaultPeriod`	number	Default polling period in seconds (1–86400).

Example: BME280 (multiple subcomponents)

{
  "displayName": "BME280",
  "vendor": "Bosch",
  "i2cAddresses": ["0x77", "0x76"],
  "subcomponents": [
    "ambient-temp",
    "ambient-temp-fahrenheit",
    "humidity",
    "pressure",
    "altitude"
  ]
}

Example: SEN55 (subcomponents as objects with custom display names)

{
  "displayName": "SEN55",
  "vendor": "Sensirion",
  "i2cAddresses": ["0x69"],
  "subcomponents": [
    { "displayName": "Temperature", "sensorType": "ambient-temp" },
    { "displayName": "Temperature (°F)", "sensorType": "ambient-temp-fahrenheit" },
    { "displayName": "Humidity", "sensorType": "humidity" },
    { "displayName": "PM1.0 Std", "sensorType": "pm10-std" },
    { "displayName": "PM2.5 Std", "sensorType": "pm25-std" },
    { "displayName": "PM10.0 Std", "sensorType": "pm100-std" },
    { "displayName": "VOC Index", "sensorType": "voc-index" },
    { "displayName": "NOx Index", "sensorType": "nox-index" }
  ]
}

I2C Output

I2C output components represent I2C-connected display devices such as character LCDs, 7-segment displays, alphanumeric displays, and OLEDs.

Required fields: displayName, vendor, outputType, i2cAddresses

Field	Type	Description
`i2cAddresses`	array	List of supported I2C addresses as hex strings (e.g. `"0x3C"`).
`outputType`	string	One of: `CHARLCD`, `7SEG`, `ALPHANUM`, `OLED`.
`charLcdColumns`	number	Number of columns for a character LCD (0–128). Used when `outputType` is `CHARLCD`.
`charLcdRows`	number	Number of rows for a character LCD (0–16). Used when `outputType` is `CHARLCD`.
`ledBackpackAlignment`	string	Text alignment for LED backpack displays: `LEFT` or `RIGHT`.
`ledBackpackBrightness`	number	Brightness level for LED backpack displays (0–15).
`oledWidth`	number	OLED display width in pixels (0–128). Used when `outputType` is `OLED`.
`oledHeight`	number	OLED display height in pixels (0–64). Used when `outputType` is `OLED`.
`textSize`	string	Font size for OLED displays: `SZ_DEFAULT` or `SZ_LARGE`.

Example: 16x2 Character LCD

{
  "displayName": "16x2 Character Display",
  "vendor": "Adafruit",
  "i2cAddresses": ["0x20", "0x21", "0x22", "0x23", "0x24", "0x25", "0x26", "0x27"],
  "outputType": "CHARLCD",
  "charLcdColumns": 16,
  "charLcdRows": 2
}

Example: 128x64 OLED

{
  "displayName": "128x64 OLED (Default)",
  "vendor": "Adafruit",
  "i2cAddresses": ["0x3D", "0x3C"],
  "outputType": "OLED",
  "oledWidth": 128,
  "oledHeight": 64,
  "textSize": "SZ_DEFAULT"
}

Display

Display components represent SPI-connected TFT and E-Ink (EPD) screens.

Required fields: displayName, vendor, displayType

The displayType object is required and contains:

Field	Type	Description
`type`	string	(required) Display type: `epd` (E-Paper) or `tft`.
`driver`	string	(required) Driver: `epd_ssd1680`, `epd_ili0373`, `tft_st7789`, or `unspecified`.
`spiEpd`	object	Optional SPI bus config for EPD displays (`{ "bus": <int> }`).
`spiTft`	object	Optional SPI bus config for TFT displays (`{ "bus": <int> }`).
`epdConfig`	object	EPD-specific config (see below). Required fields: `mode`, `width`, `height`, `textSize`.
`tftConfig`	object	TFT-specific config (see below). Required fields: `width`, `height`, `rotation`, `textSize`.

EPD config (epdConfig):

Field	Type	Description
`mode`	string	Display mode: `unspecified`, `grayscale4`, or `mono`.
`width`	integer	Display width in pixels (min 1).
`height`	integer	Display height in pixels (min 1).
`textSize`	integer	Default text size (scale of 8×5 px font).

TFT config (tftConfig):

Field	Type	Description
`width`	integer	Display width in pixels (min 1).
`height`	integer	Display height in pixels (min 1).
`rotation`	integer	Screen rotation: `0`, `1`, `2`, or `3`.
`textSize`	integer	Default text size (scale of 8×5 px font).

Example: TFT display

{
  "displayName": "1.14\" TFT LCD Display",
  "vendor": "Adafruit",
  "description": "Adafruit 1.14\" 240x135 Color TFT Display + MicroSD Card Breakout - ST7789",
  "displayType": {
    "type": "tft",
    "driver": "tft_st7789",
    "tftConfig": {
      "height": 240,
      "width": 135,
      "rotation": 3,
      "textSize": 3
    }
  }
}

Example: E-Ink display

{
  "displayName": "MagTag - 2.9\" E-Ink Display",
  "vendor": "Adafruit",
  "description": "Adds the Adafruit MagTag's 2.9\" E-Ink display to your project.",
  "displayType": {
    "type": "epd",
    "driver": "unspecified",
    "epdConfig": {
      "mode": "unspecified",
      "width": 296,
      "height": 128,
      "textSize": 3
    }
  }
}

DS18x20

DS18x20 components represent 1-Wire temperature sensors (e.g. DS18B20).

Required fields: displayName, vendor, subcomponents, sensorResolution

Field	Type	Description
`subcomponents`	array	Temperature sensor types. Each item must match `ambient-temp` or `ambient-temp-fahrenheit`.
`sensorResolution`	number	Desired sensor read resolution in bits (9–12).

Example: DS18B20

{
  "displayName": "DS18B20",
  "vendor": "Generic",
  "subcomponents": ["ambient-temp", "ambient-temp-fahrenheit"],
  "sensorResolution": 12
}

Pixel

Pixel components represent addressable LED strips such as NeoPixels and DotStars.

Required fields: displayName, vendor, pixelsType, defaultPixelsOrder

Field	Type	Description
`pixelsType`	string	`NEOPIXEL` or `DOTSTAR`.
`defaultPixelsOrder`	string	Color ordering: `GRB`, `GRBW`, `RGB`, `RGBW`, or `BRG`.
`autoSelectString`	string	Pin name hint for automatic selection. 3–24 characters.

Example: NeoPixel

{
  "displayName": "NeoPixel",
  "vendor": "Generic",
  "pixelsType": "NEOPIXEL",
  "defaultPixelsOrder": "GRB",
  "autoSelectString": "neopixel"
}

PWM

PWM components represent pulse-width-modulation-controlled devices such as dimmable LEDs, RGB LEDs, and buzzers.

Required fields: displayName, vendor, pwmSetting

Field	Type	Description
`pwmSetting`	string	`fixedFrequency` (variable duty cycle) or `variableFrequency` (fixed duty cycle).
`visualization`	object	Specifies the UI widget. See PWM Visualization Types.

PWM Visualization Types

switch-pwm — A toggle switch. Optional fields: offLabel, offIcon, onLabel, onIcon.
button — A push button. Optional fields: pressedLabel, unpressedLabel.
slider-pwm — A slider control. No additional fields.
color-picker — A color picker (used for RGB LEDs). No additional fields.

Example: Dimmable LED

{
  "displayName": "Dimmable LED",
  "vendor": "Generic",
  "pwmSetting": "fixedFrequency",
  "visualization": {
    "type": "slider-pwm"
  }
}

Example: RGB LED

{
  "displayName": "RGB LED",
  "vendor": "Generic",
  "pwmSetting": "fixedFrequency",
  "visualization": {
    "type": "color-picker"
  }
}

Servo

Servo components represent servo motor controllers.

Required fields: displayName, vendor, frequency, minPulseWidth, maxPulseWidth

Field	Type	Description
`frequency`	number	PWM signal frequency in Hz (40–200, default 50).
`minPulseWidth`	number	Minimum pulse width in microseconds.
`maxPulseWidth`	number	Maximum pulse width in microseconds.
`visualization`	object	Only supported type: `slider-servo`.

Example: Generic Servo

{
  "displayName": "Generic Servo",
  "vendor": "Generic",
  "frequency": 50,
  "minPulseWidth": 500,
  "maxPulseWidth": 2500,
  "visualization": {
    "type": "slider-servo"
  }
}

UART

UART components represent serial-bus-based sensors such as air quality monitors.

Required fields: displayName, vendor, subcomponents, baudRate

Field	Type	Description
`subcomponents`	array	List of sensor subcomponents. Each item is either a sensor type string or an object (see below).
`baudRate`	number	UART baud rate in bps (1200–256000).
`inverted`	boolean	If `true`, TX/RX signals on the UART bus are inverted.

UART Subcomponent Format

UART subcomponents follow the same pattern as I2C subcomponents — either a simple sensor type string (e.g. "pm25-std") or an object — with these differences:

Field	Type	Description
`displayName`	string	(required) Human-friendly name of the sensor. 3–24 characters.
`sensorType`	string	(required) One of the supported Sensor Types.
`type`	string	A unique lookup string for this sensor and its parent component. 3–24 chars.
`defaultPeriod`	number	Default polling period in seconds (30–86400). Note: minimum is 30, not 1 as in I2C.

Example: PMS5003 Air Quality Sensor

{
  "displayName": "pms5003",
  "vendor": "PLANTOWER",
  "subcomponents": [
    "pm10-std",
    "pm25-std",
    "pm100-std",
    "pm10-env",
    "pm25-env",
    "pm100-env"
  ],
  "baudRate": 9600,
  "inverted": false
}

Sensor Types

Sensor type strings are used in the subcomponents arrays of I2C, UART, and DS18x20 components. The centralized registry of display names and default polling periods is in components/sensors.json.

Every sensor type in sensors.json has a defaultPeriod of 900 seconds (15 minutes). This is the polling interval used unless a subcomponent's own defaultPeriod field overrides it (see I2C Subcomponent Format and UART Subcomponent Format).

Sensor Type	Display Name
`unspecified`	Unspecified
`accelerometer`	Accelerometer
`magnetic-field`	Magnetic Field Sensor
`orientation`	Orientation Sensor
`gyroscope`	Gyroscope
`light`	Light Sensor
`pressure`	Pressure Sensor
`proximity`	Proximity Sensor
`gravity`	Gravity Sensor
`acceleration`	Acceleration Sensor
`rotation`	Rotation Sensor
`humidity`	Humidity Sensor
`ambient-temp`	Temperature Sensor (°C)
`ambient-temp-fahrenheit`	Temperature Sensor (°F)
`object-temp`	Thermocouple Temperature (°C)
`object-temp-fahrenheit`	Thermocouple Temperature (°F)
`voltage`	Voltage Sensor
`current`	Current
`color`	Color
`raw`	Raw Data
`pm10-std`	PM1.0 Standard
`pm25-std`	PM2.5 Standard
`pm100-std`	PM10.0 Standard
`pm10-env`	PM1.0 Environmental
`pm25-env`	PM2.5 Environmental
`pm100-env`	PM10.0 Environmental
`co2`	CO2
`gas-resistance`	Total VOC
`altitude`	Altitude (Relative)
`lux`	Light Sensor (Lux)
`eco2`	Estimated CO2
`unitless-percent`	Unitless Percentage
`voc-index`	Volatile Organic Compounds Index
`nox-index`	Nitrogen Oxides Index
`tvoc`	Total Volatile Organic Compounds

Name		Name	Last commit message	Last commit date
Latest commit History 774 Commits
.github		.github
components		components
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Wippersnapper Component Definitions

How Does It Work?

Appear in this list

Generate a custom web form, like this

Have its current status tracked or controlled, like this

And work seamlessly with the rest of IO, including Dashboards and Triggers!

Repository Structure

Contributing

Image Requirements

Validation

Common Fields

Component Formats

Pin

Pin Visualization Types

I2C

I2C Subcomponent Format

I2C Output

Display

DS18x20

Pixel

PWM

PWM Visualization Types

Servo

UART

UART Subcomponent Format

Sensor Types

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Wippersnapper Component Definitions

How Does It Work?

Appear in this list

Generate a custom web form, like this

Have its current status tracked or controlled, like this

And work seamlessly with the rest of IO, including Dashboards and Triggers!

Repository Structure

Contributing

Image Requirements

Validation

Common Fields

Component Formats

Pin

Pin Visualization Types

I2C

I2C Subcomponent Format

I2C Output

Display

DS18x20

Pixel

PWM

PWM Visualization Types

Servo

UART

UART Subcomponent Format

Sensor Types

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Packages