Entities

An entity is a core object in ThingsBoard — a physical device, a logical grouping like an asset, or a platform construct like a dashboard or rule chain. ThingsBoard Edge supports the subset of entities relevant for edge computing.

• Devices: Physical IoT devices like sensors, actuators, and controllers.
• Assets: Real-world objects used to group and manage the IoT ecosystem, like machines, buildings, or factories.
• Customers: Organizations assigned to specific devices and assets.
• Users: People who manage and interact with Edge resources.
• Alarms: Alerts triggered by anomalies or predefined conditions.
• Dashboards: Visualizations of telemetry and device data.
• Entity views: Read-only projections of a device or asset that expose only a defined subset of telemetry and attributes.
• Rule chains: Local data processing and automation logic.

Devices and Assets use configuration templates called Device Profiles and Asset Profiles, respectively. Profiles define the data model, default rule chain, and dashboard for all entities of that type.

Devices, assets, entity views, dashboards, device and asset profiles, rule chains, users, and scheduler events can be created directly in the Edge UI and are pushed to the server. For example, go to Devices & assets > Devices to add a device. Customers, entity groups, roles, integrations, data converters, and OTA packages are created on the server only and assigned to the Edge: they control access and configuration across Edge instances.

Attributes are structured data associated with an entity — like device model, location, or authentication token. They are stored in the local database and used for visualization, analysis, rule logic, and integration with external services.

On Edge, attributes are particularly useful for storing static device configuration — like an IP address or installation site — that does not change with each telemetry reading. They can also be assigned to the Edge instance itself and used as placeholders in rule chains to differentiate behavior across multiple Edge deployments. For details, see Edge attributes.

Telemetry is time-series data collected from IoT devices and processed by the rule chain. It is stored as key-value pairs:

• Key: Identifies the measurement type, like temperature, humidity, or voltage.
• Value: Contains the reading as a number or string.

{
  "temperature": 25.4,
  "humidity": 45,
  "status": "ON"
}

By default, Edge synchronizes telemetry with the server. During a connectivity outage, telemetry is queued locally (in the ts_kv_cloud_event table, or in the tb_cloud_event_ts Kafka topic) and sent to the server once the connection is restored. Queued events older than the cloud event TTL (SQL_TTL_CLOUD_EVENTS_TTL, about 30 days by default) are deleted.

Relations define connections between two entities and model real-world hierarchies — for example, a building asset that contains multiple sensor devices. Relations are used to group entities for dashboards, filter data by hierarchy, and enrich telemetry in rule chains by fetching attributes from a related entity.

Each relation has two parameters:

• Direction:
  • Outbound (From): The relation originates from the entity — the entity is the source.
  • Inbound (To): The relation points to the entity — the entity is the recipient.
• Relation type:
  • Contains: The entity is part of another entity.
  • Manages: The entity is responsible for another entity.