This repository contains Adafruit and user-submitted description models of hardware for use with Adafruit.io.
These hardware description models (HDMs) are similar in concept to IoT "digital twins", virtual representations of physical development boards. They contain everything Adafruit.io needs to know about the device connecting to it.
If you do not see the board you want to use with Adafruit IO on this repository, follow this how-to guide on the Adafruit Learning System for full instructions about adding a board to this repository.
https://learn.adafruit.com/how-to-add-a-new-board-to-wippersnapper/overview
A hardware description model (HDM) describes the contents (information, properties, physical components) of a development board.
Information related to the hardware including the hardware's name, description and unique identifiers.
| Property | Required | Data Type | description |
|---|---|---|---|
| boardName | Yes | String | Hardware name |
| mcuName | Yes | String | Microcontroller name |
| mcuRefVoltage | Yes | Float | Microcontroller's maximum voltage reference, in Volts. |
| displayName | Yes | String | Adafruit IO Device name |
| description | No | String | Device description |
| productURL | Yes | String | Link to board's homepage. |
| documentationURL | Yes | String | Link to board's documentation. |
A boardName MAY ONLY contain lower case ASCII letters, numbers, and the dash character (“-”).
Components are ports such as digital pins or analog pins. These components are defined within the components array.
Each hardware component is defined by adding the following to the .json description file:
| Property | Required | Data Type | description |
|---|---|---|---|
| name | yes | string | Component type. Components connected to hardware externally are prefixed by external_ |
| displayName | yes | string | Human-readable display name for Adafruit IO |
| dataType | yes | string | Expected data type from component |
| max_resolution | no | int16 | Max resolution of an analog component, in bits |
The following properties are set by the WipperSnapper web application. You do not need to define these values:
| Property | Required | Data Type | description |
|---|---|---|---|
| mode | no | int16 | Component mode. See mode for type descriptions. |
| direction | no | bool | Defines the direction of a component, either input (0) or output (1). |
| pull | no | bool | Defines the pull direction of a component, either up (0) or down (1). |
| period | no | float | Number of milliseconds between measurements. |
Hardware exposing the I2C bus may add an i2cPorts array to its HDM.
The following HDM snippet defines an I2C interface on port 0 with a SDA GPIO pin of 34 and a SCL GPIO pin of 33.
"i2cPorts": [
{
"i2cPortId": "0",
"SDA": 34,
"SCL": 33
}
],
Example hardware descriptions can be found in the boards/ directory.
magic.json is an Adafruit IO export of a board's built-in component configuration (for example onboard buttons, LEDs, displays, and sensors). It is validated by /boards/magic_schema.json in this repository.
For new or updated boards, prefer configuring built-in components in Adafruit IO first, then exporting the generated magic.json, instead of hand-authoring this file. This avoids schema drift and keeps component settings aligned with what Adafruit IO actually supports.
Top-level required fields:
| Property | Type | Description |
|---|---|---|
exportVersion |
string | Version of the export format. |
exportedBy |
string | Exporting vendor. Must be "Adafruit". |
exportedAt |
string | Timestamp when the file was exported (typically an ISO 8601 UTC timestamp from Adafruit IO, e.g. 2023-11-13T19:41:29.465Z). |
exportedFromDevice |
object | Source board metadata for the export. |
components |
array | Exhaustive list of built-in components and their settings. |
exportedFromDevice requires:
| Property | Type | Description |
|---|---|---|
board |
string | Board name the export came from. |
firmwareVersion |
string | WipperSnapper firmware version at export time. |
Each entry in components must include:
| Property | Type | Description |
|---|---|---|
name |
string | Human-readable component name. |
type |
string | WipperSnapper component type identifier (for example push_button, dimmable_led, neopixel, or lc709203f:voltage). |
Component entries then include one specific configuration shape (for example pin, I2C, PWM, pixel, DS18X20, UART, servo, or display), as defined by the oneOf variants in /boards/magic_schema.json.
For concrete examples, see existing files such as:
/boards/feather-esp32s3/magic.json/boards/funhouse/magic.json/boards/pyportal-tinyusb/magic.json
Similar to the components repos component definition schema, it is possible to specify the User Interface controls / visual options for each component by using the visualization property.
This can allow icons and button labels to be better customised, as well as the choice of control type itself.
See the Pin & PWM visualization types in the readme, or the examples, in the components repo.
It is best to configure the component via the settings cog in the IO website, before exporting that configuration, rather than manually define the appropriate fields + values.