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.

Most entities can be created directly in the Edge UI — for example, go to Entities → Devices to add a device. Customers, **Users**, and Entity views are exceptions that must be created on the server and then assigned to Edge. Customers and **Users** are managed centrally because they control access across Edge instances. Entity views are managed centrally because they are projections that may reference entities from multiple sources.

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 cloud_events table and sent to the server once the connection is restored. The queue is bounded by available local storage.

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.