IoT Calculated Field Contribution Guide

Welcome to ThingsBoard IoT Hub. This guide walks you through contributing a calculated field that end users can install on their ThingsBoard instance in a single click.

A calculated field contribution is a single JSON file that you export from ThingsBoard and upload through IoT Hub. When a user clicks Install on your calculated field, the platform imports it onto a device, asset, or profile of their choice, where it starts computing derived values from live telemetry.

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

When a user installs your calculated field from IoT Hub:

1. The platform downloads your calculated field JSON file.
2. The user picks the target — a device, an asset, or a device/asset profile — directly in the installation dialog.
3. The calculated field is created on that target and immediately starts processing live telemetry — every incoming message runs through your formula or script and the computed result is saved back as a new telemetry key or attribute.

A calculated field contribution is self-contained — the formula, script, or rule is entirely in the configuration object. End users do not need to install dependencies or write code.

1. In your ThingsBoard instance, create and test your calculated field on a device, asset, or profile.
2. Export it as a JSON file — see Export the calculated field.
3. Go to IoT Hub → + Add new item. A four-step wizard walks you through the rest:
   • Upload — upload your exported JSON. The platform recognizes it as a calculated field automatically and pre-fills the Name.
   • Listing — fill in the listing metadata (see Fill in the listing). Name is pre-filled from the JSON, Icon and Color are filled automatically based on the calculated field type (you can change them), and Description contains a fill-in template. Categories, Use Cases, and the supported ThingsBoard version must be selected manually.
   • Readme — the editor is pre-filled with the recommended readme structure. Replace each placeholder section with your documentation (see Readme content).
   • Review & Submit — verify everything and submit the version for review.

The sections below are a complete reference for each step.

1. In your ThingsBoard instance, go to the Calculated fields page.
2. Locate your calculated field in the list.
3. Click the Export button (download icon) in the field’s row.
4. Save the resulting .json file — this is your upload file.

The exported file is a complete calculated field definition and requires no further editing to be valid.

A valid calculated field file is a JSON object with three required fields — name, type, and configuration.

Before uploading:

• Leave configurationVersion as exported — do not change this value.
• In debugSettings, make sure failuresEnabled is true and allEnabled is false.
  Every installed copy will then record a debug event on calculation failure (helping users understand why no output appears) without the overhead of tracking every calculation.

{
  "name": "Dew Point",
  "type": "SIMPLE",
  "configurationVersion": 0,
  "debugSettings": {
    "failuresEnabled": true,
    "allEnabled": false,
    "allEnabledUntil": 0
  },
  "configuration": {
    "type": "SIMPLE",
    "arguments": {
      "t": {
        "refEntityKey": {
          "key": "temperature",
          "type": "TS_LATEST"
        }
      },
      "h": {
        "refEntityKey": {
          "key": "humidity",
          "type": "TS_LATEST"
        }
      }
    },
    "expression": "t - ((100 - h) / 5)",
    "output": {
      "type": "TIME_SERIES",
      "name": "dewPoint",
      "decimalsByDefault": 2,
      "strategy": {
        "type": "IMMEDIATE",
        "ttl": 0,
        "saveTimeSeries": true,
        "saveLatest": true,
        "sendWsUpdate": true,
        "processCfs": true
      }
    },
    "useLatestTs": false
  }
}

The configuration object varies by calculated field type. Common fields across most types:

See the ThingsBoard Calculated Fields documentation for full per-type configuration schemas.

The Listing step of the upload wizard collects the fields shown on the browse card and detail page. Name, Icon, and Color are autofilled from your JSON (Icon and Color derived from type); everything else you set here. Version and changelog are set per upload — see Versioning and checksum.

The type field must be one of: SIMPLE, SCRIPT, GEOFENCING, PROPAGATION, RELATED_ENTITIES_AGGREGATION, ENTITY_AGGREGATION.

Pick one or more categories that describe what your calculated field does. Allowed values: Aggregation, Custom Formula, Energy, Environmental, Geospatial, Predictive, Statistical.

Pick one or more IoT domains where your calculated field is useful. These are shared across the whole marketplace.

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.

Calculated fields are displayed in the catalog with a Material Icon on a colored background instead of a preview image. When you upload your JSON, the platform picks a default icon and color based on the calculated field type. You can keep the default or change it in the Listing step.

Icon. Pick a Material Icon that visually represents the field’s purpose. The icon picker shows a curated list of icons relevant to calculated fields (e.g. calculate, functions, analytics, trending_up). You can also search the full Material Icons set.

Good icon choices:

• Math expressions → calculate, functions
• Script-based → code, terminal
• Geospatial → share_location, location_on, my_location
• Propagation → account_tree, merge_type
• Aggregation → hub, functions, summarize, analytics

Color. Pick a hex color for the icon background. The picker provides 24 presets and a custom color picker.

The defaults follow the catalog conventions — blue for simple math, purple for scripts, green for geofencing, teal for propagation, orange and slate for aggregations. Keep your custom color in a similar family so the catalog stays visually consistent.

The Readme step of the upload wizard collects the long-form documentation shown on your calculated field’s detail page. It is written in standard Markdown. The editor comes pre-filled with the recommended structure — the same four sections all official ThingsBoard templates follow. Replace each placeholder with your content.

1. # Who it's for — the audience and the questions they’re asking, one short paragraph
2. # What it does — what the field reads, the computation it performs, and where it writes the result. Include the formula or algorithm so users can verify correctness. Optionally add a diagram image (SVG or PNG) that visually explains the computation — paste it directly into the readme editor
3. # How to set up (optional) — include only when the field needs prerequisites at install time: relations, server attributes, a specific target entity or profile. Numbered steps, ending with how to verify it works
4. # How to customize — a bulleted list. Each bullet starts with the user’s goal in bold — what the user wants to achieve, not the control they will touch (e.g. **To use different telemetry keys**, **To rename the output key**). After the goal, a dash and the exact field or setting to change

Example:

# Who it's for

HVAC engineers, facility managers, and dashboard authors asking
"how close is this room to condensation?", "will moisture form on
the cold-storage walls?", "why is mold appearing in the corners?" —
when temperature and humidity sensors report raw values but the
question is about dew point.

# What it does

Reads the `temperature` (°C) and `humidity` (%) telemetry and
computes the approximate dew point using the simplified Magnus
formula: `dewPoint = temperature - ((100 - humidity) / 5)`. The
result is saved as a new `dewPoint` time series key on the same
entity. The formula is accurate to about ±1 °C while humidity stays
above 50%. If either input is missing, no output is produced.

# How to customize

- **To use different telemetry keys** — change the **Time series key**
  on the `t` and `h` arguments to match what your devices publish.
- **To rename the output key** — change the output **Time series key**
  from `dewPoint` to your domain key.
- **To improve accuracy at low humidity** — switch to a `SCRIPT`
  calculated field with the full Magnus-Tetens formula.

Each calculated field version is identified by a semver string (e.g. 1.0.0) plus a changelog entry, and an SHA-256 checksum computed from:

• name
• type
• configuration (the entire configuration object as JSON)

This means any change to the formula, script, arguments, or output configuration changes the checksum and requires bumping the version. Changes to description, icon, or color do not change the checksum.

Always bump the version when uploading a changed calculated field JSON.

• name is non-empty and descriptive
• type is one of SIMPLE, SCRIPT, GEOFENCING, PROPAGATION, RELATED_ENTITIES_AGGREGATION, ENTITY_AGGREGATION
• configuration is a valid object for the declared type
• All arguments reference existing telemetry or attribute keys, or provide a default value where applicable
• debugSettings has failuresEnabled: true and allEnabled: false

• Minimum ThingsBoard version is set appropriately
• Icon and color have been picked to reflect the calculation

• Explains who the calculated field is for and the problem it solves
• Describes which telemetry or attributes the CF reads and what value it writes
• Documents the relations or entity hierarchy required (where applicable)
• Lists customization options (telemetry keys, default thresholds, runtime attribute overrides)

• Calculated field has been tested on a real device or asset

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 calculated field runs correctly, the JSON is valid and properly configured, and the listing and readme give users enough context to evaluate and use the field.

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.

• Calculated Fields — how end users discover and install a calculated field