Skip to main content

Devices

The Device resource represents physical or virtual devices within your IoT infrastructure. Devices are the core entities that collect, process, and transmit data within the APIO platform.

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: Reference to the device type specification (e.g., "acme.energy-meter-500")

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 last activity (downlink or uplink)
  • 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

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.

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​

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.