Skip to Content

Devices

IoT device management, firmware updates, and telemetry.

Overview

IoT capabilities are handled by three services:

ServicePortPurpose
device_service8220Device registry, lifecycle
ota_service8221Firmware updates, rollback
telemetry_service8225Metrics collection, analytics

Device Service (8220)

Register Device

curl -X POST "http://localhost:8220/api/v1/devices" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "device_abc123",
    "device_type": "smart_speaker",
    "name": "Living Room Speaker",
    "manufacturer": "Acme",
    "firmware_version": "1.0.0"
  }'

Get Device

curl "http://localhost:8220/api/v1/devices/device_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Device Status

StatusDescription
registeredDevice registered, not yet connected
onlineDevice connected and active
offlineDevice not responding
updatingFirmware update in progress
errorDevice in error state

OTA Service (8221)

Check for Updates

curl "http://localhost:8221/api/v1/ota/check" \
  -H "X-Device-ID: device_abc123" \
  -H "X-Device-Token: dev_token_xyz" \
  -H "X-Firmware-Version: 1.0.0"

Trigger Update

curl -X POST "http://localhost:8221/api/v1/ota/devices/device_abc123/update" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_version": "1.1.0", "force": false}'

Rollback Firmware

curl -X POST "http://localhost:8221/api/v1/ota/devices/device_abc123/rollback" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_version": "1.0.0", "reason": "Stability issues"}'

Telemetry Service (8225)

Send Telemetry

curl -X POST "http://localhost:8225/api/v1/telemetry" \
  -H "X-Device-ID: device_abc123" \
  -H "X-Device-Token: dev_token_xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2024-01-28T10:30:00Z",
    "metrics": {
      "cpu_usage": 45.2,
      "memory_usage": 62.1,
      "temperature": 42.5
    }
  }'

Get Device Telemetry

curl "http://localhost:8225/api/v1/telemetry/device_abc123?from=2024-01-27&to=2024-01-28" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create Alert

curl -X POST "http://localhost:8225/api/v1/telemetry/alerts" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High CPU Alert",
    "device_id": "device_abc123",
    "condition": {"metric": "cpu_usage", "operator": ">", "threshold": 90},
    "actions": [{"type": "notification", "channel": "email"}]
  }'

MQTT Integration

import paho.mqtt.client as mqtt
 
client = mqtt.Client()
client.username_pw_set("device_abc123", "dev_token_xyz")
client.connect("mqtt.example.com", 1883)
 
# Publish telemetry
client.publish(
    "devices/device_abc123/telemetry",
    json.dumps({"cpu_usage": 45.2})
)
 
# Subscribe to commands
client.subscribe("devices/device_abc123/commands")

Python SDK

from isa_user import DeviceClient, OTAClient, TelemetryClient
 
devices = DeviceClient("http://localhost:8220")
ota = OTAClient("http://localhost:8221")
telemetry = TelemetryClient("http://localhost:8225")
 
# Register device
device = await devices.register(
    token=access_token,
    device_id="device_abc123",
    device_type="smart_speaker",
    name="Living Room Speaker"
)
 
# Check for updates
update = await ota.check_update(
    device_id="device_abc123",
    current_version="1.0.0"
)
 
# Get telemetry
metrics = await telemetry.get_metrics(
    token=access_token,
    device_id="device_abc123",
    period="24h"
)

Next Steps

Home