IoT Device Contribution Guide

Welcome to ThingsBoard IoT Hub. This guide walks you through building a device package that end users can install on their ThingsBoard instance in a single click.

A device package is a ZIP file that bundles everything the installation wizard needs: configuration forms, setup instructions, ThingsBoard entity templates (device profiles, dashboards, rule chains), and images. When a user selects your device in IoT Hub, the wizard runs through your package step-by-step to provision the device, create a dashboard, and show the user how to connect the hardware.

Create a free Creator account on the ThingsBoard Creator Portal to start publishing your items.

When a user clicks Install on your device in IoT Hub, the installation wizard performs these actions in order:

1. Displays instructions from your markdown files (prerequisites, wiring, firmware setup).
2. Collects user input via forms you define (device name, Wi-Fi credentials, Device EUI, etc.).
3. Creates ThingsBoard entities from your templates (device profile, device, dashboard, rule chain, integration, gateway).
4. Resolves ${variable} placeholders in subsequent files using form values, created entity IDs, and platform transport settings.
5. Shows post-install instructions with resolved variables (firmware code, verification steps, links to the created dashboard).

Your job as a creator is to describe all of this declaratively in device-info.json.

The fastest way to start is to grab a sample package, edit a few fields, and upload. Pick the one whose connectivity matches your device:

Then:

1. Edit device-info.json — set your device’s name, vendor, description, hardwareType, connectivity, and useCases.
2. Replace the entity templates (device-profile.json, device.json, dashboard.json) with exports from your own ThingsBoard instance. Keep the ${variable} placeholders.
3. Rewrite prerequisites.md and post-install.md for your hardware.
4. Swap in your device photo under images/.
5. Re-zip the contents (not the folder itself) and upload via IoT Hub → + Add new item.

See Package structure if your device supports multiple connectivity options.

The sections below are a complete reference for every part of a device package.

Use this layout when your device supports only one way of connecting. All files live at the ZIP root.

my-device.zip
├── device-info.json          (required — metadata + install steps)
├── overview.md               (optional — long description for the device detail page)
├── images/
│   ├── device-photo.jpg
│   └── wiring-diagram.png
├── prerequisites.md          (shown before install)
├── form.json                 (user input fields)
├── device-profile.json       (ThingsBoard entity template)
├── device.json               (ThingsBoard entity template)
├── dashboard.json            (ThingsBoard entity template)
└── post-install.md           (shown after install)

Use this layout when your device supports several ways of connecting (e.g. a LoRaWAN sensor that works with ChirpStack, TTN, and LORIOT). Shared files go in common/; method-specific files go in per-method subfolders.

my-device.zip
├── device-info.json
├── overview.md
├── images/
│   └── device-photo.jpg
├── common/
│   ├── form.json             (shared fields: device name, Device EUI)
│   ├── device-profile.json
│   ├── device.json
│   └── dashboard.json
├── chirpstack/
│   ├── prerequisites.md
│   ├── form.json             (ChirpStack-specific: server URL, API token)
│   ├── converter.json
│   ├── integration.json
│   └── post-install.md
├── ttn/
│   ├── prerequisites.md
│   ├── form.json             (TTN-specific: region, app ID, API key)
│   ├── converter.json
│   ├── integration.json
│   └── post-install.md
└── loriot/
    ├── prerequisites.md
    ├── form.json
    ├── converter.json
    ├── integration.json
    └── post-install.md

When using Layout B, each install method has a conventional subfolder name. The folder name is referenced from the file and template paths in installSteps — you must match it exactly.

The folder name is purely a path reference — what matters is that the file and template values in installSteps correctly point to existing files in the ZIP. The conventions below avoid collisions when a single device package supports multiple install methods that share a protocol name (e.g. both DIRECT_MQTT and INTEGRATION_MQTT).

Direct transports

ThingsBoard IoT Gateway connectors

ChirpStack (without platform integrations)

ThingsBoard platform integrations

Any file referenced from multiple install methods should live in common/ to avoid duplication:

"installSteps": {
  "CHIRPSTACK": [
    {"type": "SHOW_FORM", "name": "Configuration", "file": "common/form.json"},
    {"type": "DEVICE_PROFILE", "name": "My Sensor", "template": "common/device-profile.json"},
    ...
  ],
  "INTEGRATION_TTN": [
    {"type": "SHOW_FORM", "name": "Configuration", "file": "common/form.json"},
    {"type": "DEVICE_PROFILE", "name": "My Sensor", "template": "common/device-profile.json"},
    ...
  ]
}

The device-info.json file at the ZIP root is the single source of truth for your package. The wizard reads it first and uses it to drive everything else.

{
  "name": "My Temperature Sensor",
  "description": "Wi-Fi temperature sensor with MQTT connectivity.",
  "vendor": "Acme IoT",
  "hardwareType": "Sensor",
  "connectivity": ["Wi-Fi", "MQTT"],
  "useCases": ["Environment Monitoring", "Smart Office"],
  "image": "images/device-photo.jpg",
  "installMethods": ["DIRECT_MQTT"],
  "installSteps": {
    "DIRECT_MQTT": [
      {"type": "SHOW_INSTRUCTION", "name": "Prerequisites", "file": "prerequisites.md"},
      {"type": "SHOW_FORM", "name": "Configuration", "file": "form.json"},
      {"type": "DEVICE_PROFILE", "name": "Acme Temperature Sensor", "template": "device-profile.json"},
      {"type": "DEVICE", "name": "${deviceName}", "template": "device.json"},
      {"type": "DASHBOARD", "name": "Temperature Sensor Monitor", "template": "dashboard.json"},
      {"type": "SHOW_INSTRUCTION", "name": "Setup Complete", "file": "post-install.md"}
    ]
  }
}

• Every key in installSteps must exactly match a value in installMethods.
• All file and template paths are relative to the ZIP root, not to device-info.json.
• The name on DEVICE_PROFILE and DASHBOARD steps must be specific to your device (e.g. "ESP32 PICO KIT", not "Default"; "ESP32 PICO KIT Monitor", not "Check and control device data dashboard"). Users see these names in their ThingsBoard instance.
• The DEVICE step name should use ${deviceName} so the device is named from the form input.

Pick the one that best describes your device. Allowed values: Actuator, AI Accelerator, Analyzer, Camera, Controller, Data Logger, Development Board, Display, Gateway, Meter, PLC, Relay, Sensor, Single Board Computer, Tracker.

If your device doesn’t fit any of these categories, contact us or email iothub@thingsboard.io to request a new hardware type.

List every physical interface and protocol your device supports. The more accurate your tags, the easier users can find your device when browsing.

Wireless: Wi-Fi, Bluetooth, LoRaWAN, Zigbee, Z-Wave, Thread, NB-IoT, LTE-M, Sigfox, NFC, 2G, 3G, 4G, 5G, 6LoWPAN, DigiMesh, UWB.

Wired: Ethernet, RS485, RS232, USB, UART, SPI, I2C, CAN, 1-Wire, 4-20mA, 0-10V, M-Bus, IO-Link, IrDA, Power Line Communication, SDI-12.

Protocols: MQTT, HTTP, HTTPS, CoAP, REST, SNMP, Modbus RTU, Modbus TCP, OPC-UA, BACnet, KNX, WebSocket, TCP/IP, UDP, CANopen, DNP3, EtherCAT, Foundation Fieldbus, HART, IEC 61850, PROFINET, Wireless M-Bus.

Tag your device with all applicable IoT use cases. These are shared across the whole marketplace (widgets, devices), so users browsing by use case will find your device alongside matching content.

Allowed values: Air Quality Monitoring, Asset Tracking, Cold Chain, Drones, Environment Monitoring, Fleet Tracking, Health Care, Industrial Automation, Predictive Maintenance, Robotics, SCADA, Smart Building, Smart City, Smart Energy, Smart Farming, Smart Home, Smart Metering, Smart Office, Smart Retail, Solar Monitoring, Tank Level Monitoring, Waste Management.

Choose one or more methods that describe how the device connects to ThingsBoard. Each method you list must have a matching entry in installSteps.

The last two columns of each table show compatibility with installations that run releases before ThingsBoard 4.4, when Community Edition (CE) and Professional Edition (PE) were separate. From 4.4 they are merged into one platform, so the PE or 4.4+ column also covers every ThingsBoard 4.4 and later installation.

Direct transports — device opens a transport connection straight to the platform.

ThingsBoard IoT Gateway connectors — device talks to a ThingsBoard IoT Gateway, which forwards to the platform. One value per Gateway connector.

ChirpStack (without platform integrations)

ThingsBoard platform integrations — uses the platform’s Integrations subsystem. PE or 4.4+

Steps are executed top-to-bottom. The wizard shows an instruction or form to the user, creates a ThingsBoard entity, or both. Output from earlier steps (form values, created entity IDs) becomes available as ${variable} placeholders in later steps.

Shows a markdown page to the user. Use for prerequisites, setup guides, wiring instructions, and post-install verification.

{"type": "SHOW_INSTRUCTION", "name": "Prerequisites", "file": "prerequisites.md"}

Shows a dynamic form. Every field’s key becomes a ${key} variable in all subsequent steps.

{"type": "SHOW_FORM", "name": "Device Settings", "file": "form.json"}

Each entity step takes a template (a JSON file that matches the ThingsBoard REST API format for that entity) and creates the entity. The created entity’s ID, name, and other properties become available as variables (${device.id}, ${dashboard.name}, etc.).

Converter / integration ordering. Any UPLINK_CONVERTER or DOWNLINK_CONVERTER step must appear before the INTEGRATION step in the same install method’s array. The validator rejects packages that put converters after the integration.

This ordering is what makes the wiring automatic: the wizard runs the converter steps first, captures their generated IDs as ${uplinkConverter.id} / ${uplinkConverter.name} and ${downlinkConverter.id} / ${downlinkConverter.name}, then resolves those placeholders in the integration template before creating the integration. The creator does not need to wire converter IDs by hand. Referencing ${uplinkConverter.id} and ${downlinkConverter.id} in the integration template is enough; the wizard fills them in at install time.

"installSteps": {
  "INTEGRATION_TTN": [
    {"type": "SHOW_FORM", "name": "TTN Settings", "file": "ttn/form.json"},
    {"type": "DEVICE_PROFILE", "name": "Acme Sensor", "template": "common/device-profile.json"},
    {"type": "UPLINK_CONVERTER", "name": "Acme Decoder", "template": "ttn/uplink.json"},
    {"type": "DOWNLINK_CONVERTER", "name": "Acme Encoder", "template": "ttn/downlink.json"},
    {"type": "INTEGRATION", "name": "${deviceName} - TTN", "template": "ttn/integration.json"},
    {"type": "DEVICE", "name": "${deviceName}", "template": "common/device.json"},
    {"type": "DASHBOARD", "name": "Monitor", "template": "common/dashboard.json"},
    {"type": "SHOW_INSTRUCTION", "name": "Setup Complete", "file": "ttn/post-install.md"}
  ]
}

For the recommended way to author the converter and integration files, see Integration packages below.

Optional fields on entity steps.

Form files are JSON arrays of field definitions. Every key becomes a ${key} variable after the user submits the form.

[
  {
    "key": "deviceName",
    "label": "Device Name",
    "type": "STRING",
    "defaultValue": "My Sensor",
    "required": true,
    "helpText": "Name for the device in ThingsBoard"
  },
  {
    "key": "wifiPassword",
    "label": "WiFi Password",
    "type": "PASSWORD",
    "required": true
  },
  {
    "key": "baudRate",
    "label": "Baud Rate",
    "type": "SELECT",
    "defaultValue": "9600",
    "options": [
      {"value": "9600", "label": "9600"},
      {"value": "115200", "label": "115200"}
    ]
  },
  {
    "key": "loriotServer",
    "label": "Loriot server",
    "type": "STRING_AUTOCOMPLETE",
    "defaultValue": "eu1",
    "options": ["eu1", "us1", "as1", "eu2", "ap1"]
  },
  {
    "key": "enableTls",
    "label": "Enable TLS",
    "type": "BOOLEAN",
    "defaultValue": true
  },
  {
    "key": "port",
    "label": "Port",
    "type": "INTEGER",
    "defaultValue": 1883
  }
]

Reserved keys. These keys are populated by step output and cannot be used as form field keys: uplinkConverter.id, uplinkConverter.name, downlinkConverter.id, downlinkConverter.name, integration.id, integration.name, integration.httpEndpoint. The validator rejects packages that try to define them.

Add regex validators with custom error messages:

{
  "key": "devEui",
  "label": "Device EUI",
  "type": "STRING",
  "required": true,
  "validators": [
    {"pattern": "^[0-9A-Fa-f]{16}$", "message": "Must be exactly 16 hex characters"}
  ]
}

Multiple validators can be applied to one field — all must pass for the form to be valid.

ThingsBoard generates a complete integration package via the Export to IoT Hub button on the integration detail page. The exported ZIP is self-describing: drop the files into your device package and let the install wizard substitute placeholders at install time. Hand-authoring the integration JSON works, but exporting from a real integration is the canonical path because it produces the right shape and naming on the first try.

For platform integration install methods (INTEGRATION_LORIOT, INTEGRATION_TTN, INTEGRATION_AWS_IOT, etc.), the package places three files alongside the device-side files:

The INTEGRATION step references just one template; the wizard’s SHOW_FORM step still drives the combined form.json:

{"type": "INTEGRATION", "name": "LORIOT Integration", "template": "integration.json"}

The integration type comes from the type field at the top of integration.json. The validator rejects packages with a missing or unknown integration type.

The exporter emits three kinds of placeholders. Keep them verbatim when copying the export into a package.

Form keys that drive a ${secret:…} placeholder receive an 8-character alphanumeric suffix at export time (like loriotToken3KYhD5Wl) to prevent Secret name collisions across separate exports. Do not rename these keys — the placeholder in integration.json and the key field in form.json must match exactly.

The wizard renders one form per SHOW_FORM step. Combine the device-side fields and the integration-side fields into a single form.json, and use group to keep the visual sections from the exporter intact:

[
  {
    "key": "deviceName",
    "label": "Device Name",
    "type": "STRING",
    "defaultValue": "Acme LoRaWAN Sensor",
    "required": true
  },
  {
    "key": "integrationName",
    "label": "Integration name",
    "type": "STRING",
    "defaultValue": "Acme LoRaWAN Sensor - LoRaWAN",
    "required": true,
    "group": "LORIOT Connection"
  },
  {
    "key": "loriotServer",
    "label": "LORIOT server",
    "type": "STRING_AUTOCOMPLETE",
    "defaultValue": "eu1",
    "options": ["eu1", "us1", "as1", "eu2", "ap1"],
    "required": true,
    "group": "LORIOT Connection"
  },
  {
    "key": "loriotAppId",
    "label": "Application ID",
    "type": "STRING",
    "secretSupport": true,
    "secretType": "TEXT",
    "required": true,
    "group": "LORIOT Connection"
  },
  {
    "key": "loriotToken",
    "label": "Application Access Token",
    "type": "PASSWORD",
    "secretSupport": true,
    "secretType": "TEXT",
    "required": true,
    "group": "LORIOT Connection"
  }
]

For each device package using the older split-artifacts format (integration-template.json + integration-form.json):

1. Configure a working integration of the same type in ThingsBoard, then click Export to IoT Hub on the integration detail page. Save the ZIP and unpack it.
2. Delete the old integration-template.json and integration-form.json. Drop the export’s integration.json into the package directory unchanged.
3. Replace uplink_data_converter.json with the export’s uplink.json. Replace downlink_data_converter.json with the export’s downlink.json (if the package supports downlink).
4. Merge form.json. Keep the device-side entries (like deviceName) at the top, then append the export’s entries. Use group fields to preserve the visual layout.
5. Update device-info.json. The INTEGRATION step now references a single template (no form field). Converter step template paths point at uplink.json and downlink.json (no _data_converter suffix).
6. Smoke-test the package end-to-end via the install dialog. Page 1 shows the combined form with grouped sections, page 2 provisions the entities, and page 3 confirms success.

Entity templates are JSON files that match the ThingsBoard REST API format for that entity. Export an entity from ThingsBoard, add ${variable} placeholders for any values that must be dynamic, and save the result.

{
  "name": "Acme Temperature Sensor",
  "type": "DEFAULT",
  "transportType": "MQTT",
  "description": "Device profile for Acme Temperature Sensor with MQTT transport",
  "profileData": {
    "configuration": {"type": "DEFAULT"},
    "transportConfiguration": {
      "type": "MQTT",
      "deviceTelemetryTopic": "v1/devices/me/telemetry",
      "deviceAttributesTopic": "v1/devices/me/attributes"
    }
  }
}

Always reference the created device profile via ${deviceProfile.id}:

{
  "name": "${deviceName}",
  "type": "My Sensor Type",
  "label": "${deviceName}",
  "deviceProfileId": {
    "id": "${deviceProfile.id}",
    "entityType": "DEVICE_PROFILE"
  }
}

Export a dashboard from ThingsBoard (Dashboards → Export), then replace any hardcoded device UUIDs in entity aliases with ${device.id}:

{
  "title": "Acme Temperature Sensor Monitor",
  "configuration": {
    "entityAliases": {
      "device_alias": {
        "alias": "Device",
        "filter": {
          "type": "singleEntity",
          "singleEntity": {
            "id": "${device.id}",
            "entityType": "DEVICE"
          }
        }
      }
    }
  }
}

For boolean and integer values, use bare ${variable} (no quotes):

{
  "enableTls": ${enableTls},
  "port": ${mqtt.port}
}

For string values inside quotes, use ${variable} as normal:

{
  "name": "${deviceName}",
  "baseUrl": "${chirpstackUrl}"
}

By default, ThingsBoard auto-generates an access token for each new device, available as ${device.token}. This works for most use cases and requires no credentials file.

To override the default, add a credentials field to the DEVICE or GATEWAY step pointing to a credentials JSON file:

{
  "type": "DEVICE",
  "name": "${deviceName}",
  "template": "device.json",
  "credentials": "credentials.json"
}

{
  "credentialsType": "MQTT_BASIC",
  "credentialsValue": {
    "clientId": "${deviceName}",
    "userName": "${mqttUsername}",
    "password": "${mqttPassword}"
  }
}

{
  "credentialsType": "ACCESS_TOKEN",
  "credentialsValue": "${customToken}"
}

{
  "credentialsType": "X509_CERTIFICATE",
  "credentialsValue": "${deviceCertificate}"
}

By default, ${gateway.downloadButton} in post-install markdown generates a standard docker-compose.yml from the ThingsBoard backend with the gateway’s host, port, and access token pre-filled.

To provide a custom template with additional ports, volumes, environment variables, or credentials, add a dockerCompose field to the GATEWAY step:

{
  "type": "GATEWAY",
  "name": "${deviceName} Gateway",
  "template": "gateway.json",
  "dockerCompose": "docker-compose.yml"
}

The template is a standard YAML file with ${variable} placeholders. All variables (form values, transport config, entity outputs) are resolved after the gateway is created:

version: '3.4'
services:
  tb-gateway:
    image: thingsboard/tb-gateway:3.8-stable
    container_name: tb-gateway
    restart: always
    # Ports bindings - required by some connectors
    ports:
        - "5000:5000" # Comment if you don't use REST connector and change if you use another port
        # Uncomment and modify the following ports based on connector usage:
#        - "1052:1052" # BACnet connector
#        - "5026:5026" # Modbus TCP connector (Modbus Slave)
#        - "50000:50000/tcp" # Socket connector with type TCP
#        - "50000:50000/udp" # Socket connector with type UDP
    # Necessary mapping for Linux
    extra_hosts:
      - "host.docker.internal:host-gateway"
    # Environment variables
    environment:
      - TB_GW_HOST=${mqtt.host}
      - TB_GW_PORT=${mqtt.port}
      - TB_GW_SECURITY_TYPE=accessToken
      - TB_GW_ACCESS_TOKEN=${gateway.token}
    volumes:
      - tb-gw-config:/thingsboard_gateway/config
      - tb-gw-logs:/thingsboard_gateway/logs
      - tb-gw-extensions:/thingsboard_gateway/extensions

# Volumes declaration for configurations, extensions and configuration
volumes:
  tb-gw-config:
    name: tb-gw-config
  tb-gw-logs:
    name: tb-gw-logs
  tb-gw-extensions:
    name: tb-gw-extensions

• Your gateway needs extra ports (e.g. Modbus TCP, BACnet, Socket connector).
• You need additional volumes or bind mounts.
• You want custom environment variables beyond host, port, and accessToken.
• Your gateway uses MQTT Basic credentials and needs to pass clientId, userName, password.

version: '3.4'
services:
  tb-gateway:
    image: thingsboard/tb-gateway:3.8-stable
    container_name: tb-gateway
    # Environment variables
    environment:
      - TB_GW_HOST=${mqtt.host}
      - TB_GW_PORT=${mqtt.port}
      - TB_GW_SECURITY_TYPE=usernamePassword
      - TB_GW_CLIENT_ID=${mqttClientId}
      - TB_GW_USERNAME=${mqttUsername}
      - TB_GW_PASSWORD=${mqttPassword}

When a dockerCompose field is present on the GATEWAY step:

1. After the gateway is created, the template file is read from the ZIP.
2. All ${variable} placeholders are resolved.
3. ${gateway.downloadButton} in post-install markdown serves this custom file as a direct download.
4. No backend API call is made — the file is generated entirely in the browser.

When no dockerCompose field is set, the download button falls back to the standard ThingsBoard-generated docker-compose.yml.

## Launch Gateway

Download the configuration file and start the gateway:

${gateway.downloadButton}

Then run in the same directory:

```bash
docker compose up -d
```

The gateway will connect to **${mqtt.host}:${mqtt.port}**.

Instruction files use standard Markdown with two extensions: ${variable} placeholders and image-gallery helpers.

## Prerequisites

Before you begin, make sure you have:

- **ESP32 Dev Kit** board
- **USB cable** (micro-USB)
- **Arduino IDE** installed

### Step 1: Connect the Board

Connect the board to your computer via USB as shown:

![Wiring Diagram](images/wiring-diagram.png)

> **Note:** Make sure the USB cable supports data transfer, not just charging.

Variables are resolved before rendering. Use them to show user-provided values, created resource names, and platform settings:

## Setup Complete

Your device **${deviceName}** is ready!

Use this token in your firmware:

    ${device.token}

Open the [${dashboard.name}](${dashboard.url}) dashboard to see telemetry.

The device is connected to **${mqtt.host}:${mqtt.port}** via MQTT.

See the full Variable reference for all available variables.

Variables are resolved inside fenced code blocks, which is especially useful for firmware snippets:

```cpp
#define WIFI_SSID     "${wifiSsid}"
#define WIFI_PASSWORD "${wifiPassword}"
#define TOKEN         "${device.token}"
#define TB_SERVER     "${mqtt.host}"
#define TB_PORT       ${mqtt.port}
```

curl -o docker-compose.yml "${gateway.dockerComposeUrl}"
docker compose up -d

Place images anywhere in the ZIP — the images/ folder is recommended.

my-device.zip
├── images/
│   ├── device-photo.jpg
│   ├── wiring-diagram.png
│   └── serial-output.png
├── prerequisites.md
└── post-install.md

Supported formats: .png, .jpg, .jpeg, .gif, .svg.

Use standard Markdown with paths relative to the ZIP root:

![Wiring Diagram](images/wiring-diagram.png)

The wizard resolves these paths to inline base64 data URIs from the ZIP — no external hosting needed.

Display multiple images side-by-side as clickable thumbnails using the gallery helper:

${images.gallery(images/step1-tools.png, images/step2-upload.png, images/step3-verify.png)}

• Paths are comma-separated, relative to the ZIP root.
• Images render as a horizontal row of thumbnails.
• Clicking a thumbnail expands it full-size; clicking again collapses.
• Useful for multistep visual instructions (e.g. IDE menu navigation screenshots).

Form fields can show a help image alongside the help text:

{
  "key": "devEui",
  "label": "Device EUI",
  "type": "STRING",
  "required": true,
  "helpText": "16 hex characters from the device label",
  "helpImage": "images/device-label-eui.png"
}

The user clicks a help icon next to the field to expand the image.

• Keep images under 500 KB each — the whole ZIP is stored as a single file.
• PNG for screenshots and diagrams; JPG for device photos.
• Crop tightly to the relevant area.
• Annotate with arrows or highlights to point out important UI elements.
• Use descriptive filenames: chirpstack-api-key.png, not screenshot1.png.

Screenshots are a different thing from the images inside the ZIP described above. Those illustrate the install instructions; screenshots are the gallery shown on your device’s detail page in IoT Hub, and they live on the listing rather than in the package. They are optional, but they let a user see the device and its dashboard before deciding to install.

Upload them in the Screenshots step of the new-item and new-version wizards, or later from the Screenshots tab of the version drawer. The gallery leads with the preview image and then follows your screenshots in the order you arrange them, so the picture users clicked in from is still the first thing they see. Any image in it opens full screen when clicked.

Requirements.

• At least 1280 px wide; 1600×900 is recommended
• 16:9 is the aspect ratio the gallery frame is built for — other ratios are letterboxed, not cropped
• PNG or JPG
• Up to 2 MB per file
• Up to 8 screenshots per listing

Best practices.

• Order them so the one that best explains the device comes first — it is the slide right after the preview image
• Cover both sides of the package: the hardware itself and the dashboard it installs
• Use real telemetry, not an empty dashboard

overview.md is an optional file at the ZIP root that provides the full description for your device’s detail page on IoT Hub. It complements the short description in device-info.json:

• description in device-info.json → shown on browse cards (short, max 512 chars).
• overview.md → shown on the device detail page; pre-fills the “Readme” step in the upload wizard.

Use it to describe hardware specifications, features, and any context a user needs before deciding to install. Standard Markdown is supported, including tables and images.

## ESP32 Dev Kit C V4

The ESP32 Dev Kit C V4 is a compact development board built on the ESP-WROOM-32U module,
featuring a dual-core processor with Wi-Fi and Bluetooth connectivity.

### Features

- Dual-core Xtensa LX6 processor (240 MHz)
- 520 KB SRAM, 4 MB Flash
- Wi-Fi 802.11 b/g/n + Bluetooth 4.2 + BLE
- 34 programmable GPIO pins
- Multiple interfaces: SPI, I2C, UART, ADC, DAC, PWM

### Specifications

| Parameter | Value |
|-----------|-------|
| Operating Voltage | 3.3V |
| Input Voltage | 5V (USB) |
| Clock Speed | 80–240 MHz |
| Flash | 4 MB |

Variables are resolved at the time of step execution and are available in all subsequent markdown files, entity templates, and form help text.

Every form field key is exposed as ${key}. Common examples:

These come from the ThingsBoard platform settings of the installing instance:

Two placeholders render as inline buttons that link to the device’s manufacturer resources. They work in overview.md and in any SHOW_INSTRUCTION markdown.

If the corresponding URL is not set, the placeholder is silently dropped — so it is safe to leave them in your markdown even when only one URL is provided.

## Device Technical Documentation

Download datasheets and manuals for the FMC130.

${product.button} ${datasheet.button}

Before uploading your ZIP, verify each item below.

• name, description, vendor, hardwareType, installMethods, and installSteps are all present
• hardwareType is one of the allowed values
• Every tag in connectivity comes from the allowed list
• Every tag in useCases comes from the allowed list
• installSteps has a key for every value in installMethods
• Every file and template path in installSteps points to a file that actually exists in the ZIP
• image points to an existing file (if provided)

• The DEVICE_PROFILE step name includes the device model (e.g. "Acme Temperature Sensor", not "Default")
• The DASHBOARD step name includes the device model (e.g. "Acme Sensor Monitor", not generic text)
• The title field inside dashboard.json matches the DASHBOARD step name
• The DEVICE step name uses ${deviceName} so the device is named from user input

• device.json uses ${deviceProfile.id} for the deviceProfileId (not a hardcoded UUID)
• dashboard.json replaces every hardcoded entity UUID with ${device.id} (or relevant entity variable)
• Non-string variables in templates are unquoted: "port": ${mqtt.port} (not "port": "${mqtt.port}")

• Post-install firmware code uses ${device.token}, not placeholders like YOUR_ACCESS_TOKEN
• Post-install firmware code uses ${mqtt.host} / ${mqtt.port}, not hardcoded demo.thingsboard.io or 1883
• Wi-Fi credentials in firmware code use ${wifiSsid} / ${wifiPassword}
• Post-install references the dashboard via ${dashboard.name}, not a hardcoded title
• No manual “create device” or “import dashboard” steps — the wizard handles those

• Every form field has key, label, and type
• SELECT fields have options with value and label for every option
• Fields that require a specific format (Device EUI, IP address, etc.) have regex validators with a clear message
• Sensible defaultValue is set where appropriate

• Device photo is present in images/ and referenced from device-info.json
• Every image referenced from markdown exists in the ZIP
• Image paths in markdown are relative (e.g. images/photo.png), not absolute URLs
• Images are under 500 KB each

• Every screenshot meets the screenshot requirements
• They are arranged so the one that best explains the device comes first

• Shared files live in common/, method-specific files live in their respective subfolder
• Each install method key in installSteps matches an entry in installMethods
• Folder names follow the conventions in the folder mapping table

• Minimum ThingsBoard version is set appropriately

• Documents the device hardware specs
• Explains how to connect the device using each supported install method
• Lists the telemetry keys the device publishes and any required attributes
• Includes a pre-built dashboard that visualizes device telemetry and key metrics

• Device package installs cleanly and the device reports telemetry on a real ThingsBoard instance
• Preview image shows the actual device, not a generic placeholder

When you upload a new version, pair the version bump with a changelog entry — a short note that tells users exactly what changed since the previous version, so they can decide whether, and how, to upgrade.

Summarize what changed since the previous version: new features, bug fixes, breaking changes, and any migration notes users need to know.

Group your entry under these headings, and include only the ones that apply:

• Lead with the user impact. Describe what the user can now do, or what no longer breaks — not how you implemented it.
• Be specific. Name the exact keys, fields, settings, or outputs that changed. “Renamed the output key from temp to temperature” is actionable; “improved naming” is not.
• One change per bullet. Keep each item to a single, scannable line.
• Flag breaking changes loudly. If an upgrade can disrupt an installed copy, say so explicitly and pair it with a migration note.

Pair every entry with a semantic version bump — patch (1.0.1) for fixes, minor (1.1.0) for backward-compatible features, major (2.0.0) for breaking changes.

## 2.0.0

### Breaking changes
- Renamed the output key from `temp` to `temperature` to match the
  ThingsBoard telemetry convention.

### Migration notes
- Update any dashboards, alarm rules, or downstream calculated fields
  that read the `temp` key to read `temperature` instead.

### New features
- Added an optional `humidity` argument; when present, the formula
  now also computes a `dewPoint` output.

### Bug fixes
- Fixed missing output when the input telemetry arrived as a string
  instead of a number.

Once you complete the upload wizard and click Submit, your version enters the IoT Hub review queue. The ThingsBoard team checks every submission before it goes live.

To see the current status of your submission, open the Creator Portal and go to Items. Find your item in the list and click the Manage Versions icon in its row. The Versions page lists every version you have uploaded with a Status column that updates in real time.

Reviewers verify that the submission meets the same criteria as the Pre-Upload Checklist: the package installs cleanly, entity templates are correct, instructions are complete and accurate, images are present, and the listing and readme give users enough context to evaluate and use the device.

The Status column will show Rejected. Open the version details to read the reviewer’s comment, which explains specifically what needs to be fixed.

To resubmit:

1. Fix the reported issues in your local package.
2. Return to Items → Manage Versions for your item.
3. Click + Upload new version and complete the wizard with the corrected package.

• IoT Device Library — how end users discover and install a device package