Assets and Bindings

Assets are the heart of Beacon Tower. They represent physical devices, equipment, or logical entities in your IoT system. This page explains how assets work, how they connect to real-world data sources through providers and bindings, and how they fit into the asset graph.

Overview

An asset is an instance of a model that represents something in your system—a temperature sensor, a pump, a production line, or even an abstract entity like a building zone. Assets provide a stable abstraction layer between your application logic and the underlying hardware or data sources.

Key benefits of assets:

Data source abstraction — Swap physical devices without losing historical data or changing application code
Multi-provider support — Source data from multiple providers (Azure IoT Hub, MQTT, imports, etc.)
Graph organization — Assets live in a hierarchical graph structure for flexible organization
DTDL-based — Strong typing via Digital Twin Definition Language models

Asset Anatomy

Every asset has:

Field	Type	Description
`id`	string	Unique identifier (InstanceBti). Example: `"temperatureDevice1"`
`modelId`	string	DTMI of the model. Example: `"dtmi:series200:tempSensor;1"`
`displayName`	string	Human-readable name
`description`	string	Optional description
`bindingData`	object	Provider connection metadata (set during binding)
`authorizationContext`	object	RBAC context for access control

The id is unique across your Beacon Tower instance. The modelId references a model that defines the asset's telemetry, properties, and commands.

Creating Assets

Basic Asset Creation

curl -X POST https://api.beacontower.ai/assets \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "temperatureDevice1",
    "modelId": "dtmi:series200:tempSensor;1",
    "displayName": "Factory Floor Temperature Sensor",
    "description": "Main production area ambient temperature"
  }'

At this point the asset exists in the system, but it's not yet bound to a data source. It won't receive telemetry until you create a binding.

Asset API Endpoints

Method	Endpoint	Description
`GET`	`/assets`	List all assets
`POST`	`/assets`	Create a new asset
`GET`	`/assets/{assetId}`	Get asset details
`PATCH`	`/assets/{assetId}`	Update asset displayName or description
`DELETE`	`/assets/{assetId}`	Delete an asset
`GET`	`/assets/model/{modelId}`	Get all assets of a specific model
`POST`	`/assets/migrate`	Migrate assets between models
`POST`	`/assets/{assetId}/bind`	Bind asset to provider or other assets

See the API Reference for full request/response schemas.

Providers and Provider Clients

Providers

A provider is a data source abstraction—an external service that connects physical devices to Beacon Tower. Common provider types include:

iothub — Azure IoT Hub
import — Batch data imports

Providers are typically managed by infrastructure/operations teams. You normally don't create them manually; they're provisioned as part of your Beacon Tower deployment.

Provider API:

# List providers
GET /providers

# Update provider configuration
PUT /providers/{providerId}

Provider Clients

A provider client represents an individual device connection within a provider. Each physical device has its own client. Clients can be:

Provisioned — Active, can send/receive data
Unprovisioned — Inactive, no data flow

When you create an asset and bind it to a provider, Beacon Tower automatically creates or links to a provider client.

Provider Client API:

# List clients for a provider
GET /providers/{providerId}/clients

# Get client details
GET /providers/{providerId}/clients/{clientId}

# Provision a client (activate)
POST /providers/{providerId}/clients/{clientId}/provision

# Unprovision a client (deactivate)
POST /providers/{providerId}/clients/{clientId}/unprovision

# Invoke direct method on client
POST /providers/{providerId}/clients/{clientId}/directMethod

Provider Templates

Provider templates are reusable configurations for provisioning new clients. Templates define connection parameters, authentication, and metadata so you can quickly spin up new device connections.

# Provider template endpoints
GET /providers/templates/
POST /providers/templates/
PUT /providers/templates/{templateId}
DELETE /providers/templates/{templateId}

Bindings: Connecting Assets to Data

A binding connects an asset's telemetry points (defined in its model) to actual data channels from a provider. Bindings use EndpointBindings to map model telemetry fields to provider data streams.

Binding Descriptions

Bindings are created on models (as binding descriptions), then applied to assets. A model can support multiple binding descriptions—one for each provider type it supports. For example, a temperature sensor model might have:

Binding description for Azure IoT Hub
Binding description for MQTT provider
Binding description for CSV import

Autobind (Recommended)

The autobind operation is the most common way to bind an asset. It automatically creates bindings using a default binding description:

curl -X POST https://api.beacontower.ai/assets/temperatureDevice1/bind \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "autobindRemoteInstanceIds": ["iothub-primary::temp-sensor-001"]
  }'

The remote instance ID format is {providerId}::{clientId}. This call:

Looks up or generates a default binding description for the asset's model
Creates or links to the provider client temp-sensor-001 in provider iothub-primary
Automatically maps telemetry fields from the model to data channels in the provider
Starts flowing telemetry data to the asset

You can also specify multiple remote instances to bind to multiple data sources, or use bindingDescriptions for more control over which binding description to use.

Binding Description IDs

Binding description IDs follow the format btbi:{modelId}:{bindingName};{version}. If no custom binding description exists, Beacon Tower generates a default one automatically when you use autobind. You can also create custom binding descriptions for complex scenarios:

Multiple provider types (IoT Hub, MQTT, imports)
Custom field mappings or transformations
Unit conversions or calculations during data transfer

Multiple Assets, One Data Source

Multiple assets can bind to the same provider client. This is useful for:

Logical partitioning — Different applications see the same device as different assets with different access controls
Multi-tenancy — Same physical device serves multiple customers
Calculated assets — Virtual assets that aggregate or transform data from real devices

Asset Commands and Properties

Assets can have commands (invoke actions on the device) and properties (device state).

Commands

# Invoke a command on an asset
curl -X POST https://api.beacontower.ai/assets/temperatureDevice1/commands/reboot \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout": 30
  }'

Commands are defined in the asset's model and are passed through to the bound provider client.

Desired Properties

Set desired properties (what you want the device state to be):

# Update desired properties
curl -X PUT https://api.beacontower.ai/assets/temperatureDevice1/properties/desired \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reportingInterval": 60,
    "alertThreshold": 85.0
  }'

Reported Properties

Get current device state as reported by the device:

# Get reported properties
curl -X GET https://api.beacontower.ai/assets/temperatureDevice1/properties/reported \
  -H "X-API-Key: YOUR_API_KEY"

The Asset Graph

Assets are organized in a graph structure using ArangoDB. The graph allows you to model hierarchical and relational structures:

Buildings → Floors → Rooms → Equipment
Sites → Production Lines → Machines → Sensors
Custom hierarchies for your domain

Graph Relationships

Edges connect nodes to assets, assets to assets, or assets to dashboards. The primary relationship type is CONTAINS:

Node "Building A" --CONTAINS--> Asset "HVAC System"
Asset "HVAC System" --CONTAINS--> Asset "Temperature Sensor"

Graph API

# Create an edge (link two entities)
curl -X POST https://api.beacontower.ai/graph/edges \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromType": "node",
    "fromId": "building-a",
    "toType": "asset",
    "toId": "temperatureDevice1",
    "relation": "CONTAINS"
  }'

# Find edges
POST /graph/edges/find

# Delete an edge
DELETE /graph/edges/{edgeId}

See Also: Trees for hierarchical organization patterns using the asset graph.

Complete Example: Create and Bind an Asset

Here's a full workflow to create an asset and bind it to an IoT Hub provider:

# 1. Create the asset
curl -X POST https://api.beacontower.ai/assets \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pump-west-wing-01",
    "modelId": "dtmi:factory:pump;2",
    "displayName": "West Wing Pump #1",
    "description": "Primary coolant circulation pump"
  }'

# 2. Autobind to a provider
curl -X POST https://api.beacontower.ai/assets/pump-west-wing-01/bind \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "autobindRemoteInstanceIds": ["iothub-factory::pump-hw-serial-7823"]
  }'

# 3. Add to graph under a node
curl -X POST https://api.beacontower.ai/graph/edges \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromType": "node",
    "fromId": "west-wing",
    "toType": "asset",
    "toId": "pump-west-wing-01",
    "relation": "CONTAINS"
  }'

Now the asset:

Exists in the system with a stable identity (pump-west-wing-01)
Receives telemetry from physical device pump-hw-serial-7823 via IoT Hub
Is organized under the west-wing node in your asset graph
Can be queried for telemetry and timeseries data

Key Takeaways

Assets are abstractions — They decouple application logic from physical devices, making it easy to swap hardware or aggregate data from multiple sources.
Providers connect devices — Providers and provider clients manage the actual data connections; assets consume that data via bindings. See Telemetry Ingestion for the exact message format and headers.
Autobind is your friend — For most use cases, POST /assets/{assetId}/bind does the heavy lifting automatically.
Graph organization is flexible — Use nodes and edges to model any hierarchical or relational structure.
Models define the contract — Assets get their telemetry, properties, and commands from DTDL models.

Next Steps

Models and DTDL — Define asset schemas with Digital Twin Definition Language
Telemetry and Timeseries — Query and analyze asset data
Trees — Organize assets in hierarchical structures
API Reference — Full REST API documentation

For hands-on experience, follow the Getting Started guide to create your first asset via the API.

Overview​

Asset Anatomy​

Creating Assets​

Basic Asset Creation​

Asset API Endpoints​

Providers and Provider Clients​

Providers​

Provider Clients​

Provider Templates​

Bindings: Connecting Assets to Data​

Binding Descriptions​

Autobind (Recommended)​

Binding Description IDs​

Multiple Assets, One Data Source​

Asset Commands and Properties​

Commands​

Desired Properties​

Reported Properties​

The Asset Graph​

Graph Relationships​

Graph API​

Complete Example: Create and Bind an Asset​

Key Takeaways​

Next Steps​