Devices

Overview

A device is a managed resource that can be in various lifecycle states and is associated with projects, nodes, and plants. Each device has a specific type, location, and configuration that determines its behavior and capabilities within your IoT ecosystem.

Key Properties

Basic Information

• name (required): A distinguishable name for the device (e.g., “Device-1”)
• description: Human-readable description of the device (e.g., “This is the sensor for the 4th floor of the building”)
• projectId (required): The project this device belongs to
• deviceTypeId: The uuid of the device type that describes this kind of device

Connectivity and Hierarchy

• nodeId: The node (datalogger, gateway, etc.) connected to this device
• plantId: The plant where this device is installed. If the device has a nodeId, both the node and device must have the same plantId
• location: Geographical coordinates of the device

Device Status and Activity

• lastActivityAt: ISO8601 timestamp of the most recent measurement received from the device
• lastCommunicationAt: ISO8601 timestamp of the last communication
• firmwareVersion: Current firmware version (e.g., “v1.0.0”)
• serialNumber: Physical serial number of the device

Organization

• tags: Array of alphanumeric tags for categorization and filtering
• metadata: Custom key-value pairs for additional device information

Device State

Besides storing every measurement as a timeseries, the platform keeps the latest value of each property of a device in its state:

• state: The latest value of each property, e.g. { "temperature": 21.5, "humidity": 48 }
• stateUpdatedAt: For each property, the time of the measurement that set the current value

The state is updated by every measurement received for the device, whether it is sent over MQTT or through the HTTP API. A property’s entry in stateUpdatedAt changes only when its value changes: receiving the same value again does not update it. Measurements for devices that are not registered in the project don’t produce a state.

The state is included when you read a device, and can also be read on its own:

{
  "status": true,
  "data": {
    "state": {
      "temperature": 21.5,
      "humidity": 48
    }
  }
}

To read the current value of a single property:

{
  "status": true,
  "data": 21.5
}

The endpoint responds with 404 Not Found when the device has no value for that property. Both endpoints require the apio.core.devices.read permission.

Assets build their own state from the state of the devices they are mapped to.

Reading Devices

When you read a single device, the response includes its device type in the deviceType field.

Lists of devices can be filtered by any device field, and also by device type fields with the deviceType. prefix:

GET /projects/{projectId}/devices?plantId=my-plant-uuid
GET /projects/{projectId}/devices?deviceType.category=energy-meter

Use the include parameter to embed the node and the plant a device is linked to. They are returned in the includes field of each device:

GET /projects/{projectId}/devices?include=node,plant

Lifecycle Management

Lifecycle Status

The lifecycleStatus field tracks the current operational state of a device. Understanding these states is crucial for proper device management:

Available States

• created: Device has been registered in the system but not yet configured
• provisioned: Device has been configured and is ready for deployment
• active: Device is operational and actively participating in data collection
• maintenance: Device is temporarily offline for maintenance or updates
• suspended: Device operations have been temporarily halted
• decommissioned: Device has been permanently removed from service

State Transitions

Devices typically follow this lifecycle progression:

created → provisioned → active → [maintenance/suspended] → decommissioned

However, devices can transition between maintenance, suspended, and active states as needed based on operational requirements.

Lifecycle Events

The system maintains a complete audit trail of lifecycle changes through the lifecycleEvents array. Each event contains:

• timestamp: When the lifecycle change occurred
• authorId: Who initiated the change
• type: The lifecycle state that was entered

This provides full traceability of device state changes for compliance and operational monitoring.

Changing the Lifecycle Status

To move a device to a new lifecycle status, add a lifecycle event:

{
  "lifecycleEventType": "active"
}

The platform appends the event to lifecycleEvents, with the current time and the account that made the request as authorId, and sets lifecycleStatus to the new value. Unknown types are rejected with 400 Bad Request.

Resource Management

Base Resource Properties

All devices inherit standard resource properties:

• uuid: Unique identifier (auto-generated if not provided)
• createdAt: Resource creation timestamp
• updatedAt: Last modification timestamp
• metadata: Flexible key-value storage for custom attributes

Project Association

Every device must be associated with a project through the projectId field. This enables:

• Access control and permissions management
• Resource organization and billing
• Multi-tenant isolation

Best Practices

Device State

Besides storing every measurement as a timeseries, the platform keeps the latest value of each property of a device in its state:

• state: The latest value of each property, e.g. { "temperature": 21.5, "humidity": 48 }
• stateUpdatedAt: For each property, the time of the measurement that set the current value

The state is updated by every measurement received for the device, whether it is sent over MQTT or through the HTTP API. A property’s entry in stateUpdatedAt changes only when its value changes: receiving the same value again does not update it. Measurements for devices that are not registered in the project don’t produce a state.

The state is included when you read a device, and can also be read on its own:

{
  "status": true,
  "data": {
    "state": {
      "temperature": 21.5,
      "humidity": 48
    }
  }
}

To read the current value of a single property:

{
  "status": true,
  "data": 21.5
}

The endpoint responds with 404 Not Found when the device has no value for that property. Both endpoints require the apio.core.devices.read permission.

Assets build their own state from the state of the devices they are mapped to.

Reading Devices

When you read a single device, the response includes its device type in the deviceType field.

Lists of devices can be filtered by any device field, and also by device type fields with the deviceType. prefix:

GET /projects/{projectId}/devices?plantId=my-plant-uuid
GET /projects/{projectId}/devices?deviceType.category=energy-meter

Use the include parameter to embed the node and the plant a device is linked to. They are returned in the includes field of each device:

GET /projects/{projectId}/devices?include=node,plant

Lifecycle Management

1. Monitor Active Devices: Regularly check devices in “active” state for communication health
2. Planned Maintenance: Use “maintenance” status during scheduled updates or repairs
3. Graceful Decommissioning: Always transition through “suspended” before “decommissioned”
4. Audit Trail: Leverage lifecycle events for compliance and troubleshooting

Device Organization

1. Meaningful Names: Use descriptive names that indicate location or function
2. Consistent Tagging: Implement a standardized tagging strategy for easy filtering
3. Complete Descriptions: Include relevant details about device purpose and location
4. Metadata Usage: Store custom attributes that don’t fit standard fields

Connectivity

1. Plant Consistency: Ensure devices and their associated nodes belong to the same plant
2. Location Accuracy: Maintain precise location data for field service and analytics
3. Type Association: Always specify the correct deviceTypeId for proper data interpretation

Integration Points

Devices integrate with several other platform components:

• Projects: For access control and organization
• Nodes: For data communication pathways
• Plants: For physical location hierarchy
• Device Types: For configuration templates and data schemas
• Data Streams: For telemetry and command flows

Understanding these relationships is essential for effective device management within the broader IoT platform ecosystem.