Start from a device payload

You know what your device sends. This page shows how to describe that data to your AI agent so that the agent creates the correct keys, units, and demo data. Each section has a prompt that you can copy and change.

Before you start, set up the CLI and start your agent in the project folder. See Getting Started.

Paste the JSON that your device sends. Say what the device is and what you want to see:

My greenhouse sensor sends {"temperature": 24.1, "humidity": 68, "soilMoisture": 31, "battery": 87} every 10 minutes. Create the device and show the values on a dashboard.

The agent uses the JSON keys as the key names in ThingsBoard. Your device must send the same key names later, so do not rename them in the prompt.

When the request names one or two kinds of devices and no customers, users, or sites, the agent makes a quick build. It shows the line “Quick build: …” and creates everything without questions. Say “full solution” if you want to review the design first.

ThingsBoard saves each top-level key of the JSON as one key. If your device sends {"env": {"t": 22.5, "rh": 41}}, ThingsBoard saves one key env with a JSON value. Charts, alarm thresholds, and demo data need separate keys, like temperature and humidity.

Tell the agent what each nested value means and which unit it has:

My air sensor sends {"env": {"t": 22.5, "rh": 41}, "bat": 93} every 5 minutes. env.t is the temperature in °C, env.rh is the relative humidity in %, and bat is the battery level in %. Add a calculated field that reads env and writes temperature and humidity as separate keys. Show temperature, humidity, and bat on a dashboard.

A script calculated field can read a JSON value and write several keys. The emulator sends demo JSON values for env, and the calculated field makes temperature and humidity from them.

Write the unit after each value. The agent adds the unit and a value range to each key, and the dashboard shows the units.

If the device sends a unit that you do not want to show, ask for a conversion. The agent adds a calculated field that writes the converted value to a new key:

My freezer sensor sends {"tempF": 1.4, "doorOpen": false} every minute. tempF is the temperature in Fahrenheit. Add a calculated field that converts it to Celsius as tempC, and show tempC on the dashboard.

The demo data contains only the keys that the device sends, like tempF. The calculated field makes tempC from it. tb push <name> --run-tasks also calculates tempC for the demo history.

ThingsBoard keeps two kinds of data:

• Telemetry: Values that change over time, like temperature or battery level. ThingsBoard keeps the history.
• Attributes: Values that change rarely, like the firmware version, the serial number, or a fixed location. ThingsBoard keeps only the latest value.

The agent sorts the keys itself: sensor readings become telemetry, and hardware information and settings become attributes. To be sure, say which values are static. The agent sets demo values for these attributes on each device.

Add the interval to the prompt, like “every 5 minutes”. The agent uses it for the demo data. If you do not give an interval, the demo data has one value every 30 minutes. A short interval also works: seven days at one value per minute is about 10,000 values for each key.

The demo history covers seven days by default. Ask for another period if you need it, like “30 days of history”. The maximum is 90 days.

Give each device type its own line with its payload. Say how many devices of each type you want:

Create a solution for my cold room:
- 3 temperature probes, each sends {"temperature": 3.2} every 5 minutes. Firmware version is a static value.
- 1 door sensor, sends {"open": true} when the door opens or closes.
- 1 power meter, sends {"power": 1.8, "energy": 1520.4} every 15 minutes. power is in kW, energy is the total in kWh.
Show all devices on one dashboard.

With one or two device types, the agent makes a quick build. With three or more device types, the agent uses the full design flow. It can ask a few questions and shows the design before it creates the files. See Example: smart retail solution.

The agent saves each step as a git commit. Nothing goes to ThingsBoard until you approve a deployment, unless your request already asks to deploy or to show the data on a dashboard.

The agent writes the files to solutions/<name>/. Open these files to check the keys:

If a key name or a unit is wrong, tell the agent. The agent changes only the affected files and keeps the IDs:

In the greenhouse solution, soilMoisture is in %, not in m³/m³. Change the unit and the value range.

• Add alarms with your agent: thresholds, severities, and durations.
• Example: smart retail solution: bigger solutions, design approvals, and updates.
• MQTT telemetry API: the payload formats that ThingsBoard accepts.