Device Registration & Management

This guide explains how to register, provision, and manage IoT devices with the De. platform.

Device Lifecycle

Managing IoT devices within De.IoTB involves several stages throughout the device lifecycle:

1. Registration: Adding device information to the platform
2. Provisioning: Generating credentials and configuring the device
3. Connection: Device connecting to MQTT broker
4. Telemetry: Streaming data from device to platform
5. Commands: Sending instructions from platform to device
6. Monitoring: Tracking device health and performance
7. Maintenance: Updating firmware and configurations
8. Decommissioning: Removing devices from the platform

Device Registration

Before a device can connect to the platform, it must be registered in your workspace.

API-Based Registration

import De from '@de./sdk'

const access = new De.Access({
  workspace: 'your-workspace-id',
  accessToken: 'your-access-token',
  env: 'prod'
})

// Register a new device
const response = await access.request({
  url: '/devices/register',
  method: 'POST',
  body: {
    deviceId: 'tracker_001',        // Unique device identifier
    type: 'gps_tracker',            // Device type
    name: 'Fleet Tracker #1',       // Human-readable name
    description: 'Delivery truck tracker', // Optional description
    info: {
      manufacturer: 'Acme IoT',     // Device manufacturer
      model: 'GPS-Pro-2000',        // Device model
      firmware: '1.2.0',            // Current firmware version
      hardware: 'v2',               // Hardware version
    },
    tags: ['fleet', 'delivery'],    // Optional classification tags
    metadata: {                     // Custom device properties
      vehicleId: 'TRUCK-123',
      installDate: '2025-10-15',
      region: 'Northeast'
    }
  }
})

console.log('Device registered:', response.data)

Batch Registration

For registering multiple devices at once:

const devices = [
  {
    deviceId: 'tracker_001',
    type: 'gps_tracker',
    name: 'Fleet Tracker #1',
    info: { manufacturer: 'Acme IoT', model: 'GPS-Pro-2000' }
  },
  {
    deviceId: 'tracker_002',
    type: 'gps_tracker',
    name: 'Fleet Tracker #2',
    info: { manufacturer: 'Acme IoT', model: 'GPS-Pro-2000' }
  },
  // Additional devices...
]

const response = await access.request({
  url: '/devices/register/batch',
  method: 'POST',
  body: { devices }
})

console.log(`Registered ${response.data.successful} devices`)
console.log(`Failed: ${response.data.failed}`)

Device Provisioning

After registration, devices need credentials to connect to the platform.

Generate Device Credentials

// Generate credentials for a specific device
const credentials = await access.request({
  url: `/devices/${deviceId}/provision`,
  method: 'POST',
  body: {
    authType: 'token',             // 'token' or 'certificate'
    expiryDays: 0,                 // 0 for non-expiring tokens, or specify days
    permissions: {
      telemetryTopics: ['sensors', 'location', 'status'], // Allowed telemetry topics
      commandTopics: ['config', 'reboot']                 // Allowed command topics
    }
  }
})

console.log('Device credentials:', credentials.data)
// Output:
// {
//   username: "ws_abc_dev_123",
//   password: "eyJhbGciOiJIUzI1NiIsIn...",  // Auth token
//   clientId: "dev_123",
//   topics: {
//     subscribe: ["ws_abc/devices/dev_123/commands/#"],
//     publish: ["ws_abc/devices/dev_123/telemetry/#", "ws_abc/devices/dev_123/status"]
//   },
//   expiresAt: null  // or timestamp for expiring tokens
// }

Certificate-Based Provisioning

For higher security requirements:

const certCredentials = await access.request({
  url: `/devices/${deviceId}/provision`,
  method: 'POST',
  body: {
    authType: 'certificate',
    expiryDays: 365,  // Certificate validity period
  }
})

console.log('Device certificates:', certCredentials.data)
// Output:
// {
//   certificate: "-----BEGIN CERTIFICATE-----\nMIIE...",
//   privateKey: "-----BEGIN PRIVATE KEY-----\nMIIE...",
//   caCertificate: "-----BEGIN CERTIFICATE-----\nMIIE...",
//   clientId: "dev_123",
//   topics: { ... }
//   expiresAt: "2027-01-19T12:00:00.000Z"
// }

Device Management API

De.IoTB provides a comprehensive API for managing devices throughout their lifecycle.

Retrieving Device Information

// Get a single device by ID
const device = await access.request({
  url: `/devices/${deviceId}`,
  method: 'GET'
})

console.log('Device details:', device.data)

// List all devices with filtering
const devices = await access.request({
  url: '/devices',
  method: 'GET',
  query: {
    type: 'gps_tracker',           // Filter by type
    status: 'active',              // Filter by status
    tags: 'fleet,delivery',        // Filter by tags
    page: 1,                       // Pagination
    limit: 25,                     // Results per page
    sort: 'lastSeen:desc'          // Sorting
  }
})

console.log(`Found ${devices.data.length} devices`)

Updating Device Information

// Update device details
const updated = await access.request({
  url: `/devices/${deviceId}`,
  method: 'PATCH',
  body: {
    name: 'Updated Device Name',
    info: {
      firmware: '1.3.0',  // Update firmware version
    },
    metadata: {
      region: 'Northwest', // Update custom metadata
      maintainer: 'John Doe'
    },
    tags: ['fleet', 'delivery', 'premium']  // Update tags
  }
})

console.log('Device updated:', updated.data)

Device Status Management

// Activate a device
await access.request({
  url: `/devices/${deviceId}/status`,
  method: 'PATCH',
  body: {
    status: 'active'  // 'active', 'inactive', or 'suspended'
  }
})

// Check device connection status
const status = await access.request({
  url: `/devices/${deviceId}/connection`,
  method: 'GET'
})

console.log('Connection status:', status.data)
// Output:
// {
//   connected: true,
//   lastConnected: "2026-01-19T14:35:22.000Z",
//   lastDisconnected: "2026-01-19T12:20:15.000Z",
//   connectionDuration: 8107,  // seconds
//   ipAddress: "203.0.113.42",
//   protocol: "mqtts"
// }

Decommissioning Devices

// Disable a device (temporary)
await access.request({
  url: `/devices/${deviceId}/status`,
  method: 'PATCH',
  body: { status: 'inactive' }
})

// Permanently delete a device and its data
await access.request({
  url: `/devices/${deviceId}`,
  method: 'DELETE',
  query: {
    purgeData: true  // Set to false to keep historical data
  }
})

Device Groups

Organize devices into logical groups for easier management:

// Create a device group
const group = await access.request({
  url: '/device-groups',
  method: 'POST',
  body: {
    name: 'Delivery Trucks',
    description: 'GPS trackers for the delivery fleet',
    tags: ['fleet', 'logistics'],
    devices: ['tracker_001', 'tracker_002', 'tracker_003']
  }
})

console.log('Group created:', group.data)

// Add devices to a group
await access.request({
  url: `/device-groups/${group.data.id}/devices`,
  method: 'POST',
  body: {
    devices: ['tracker_004', 'tracker_005']
  }
})

// Send command to all devices in a group
await access.request({
  url: `/device-groups/${group.data.id}/commands`,
  method: 'POST',
  body: {
    command: 'reboot',
    parameters: {
      delay: 60,  // seconds
      reason: 'maintenance'
    }
  }
})

Device Shadows

Device shadows provide a virtual representation of device state:

// Get current device shadow
const shadow = await access.request({
  url: `/devices/${deviceId}/shadow`,
  method: 'GET'
})

console.log('Device shadow:', shadow.data)
// Output:
// {
//   reported: {
//     temperature: 23.5,
//     humidity: 45.2,
//     firmware: "1.3.0",
//     lastUpdated: "2026-01-19T15:30:22.000Z"
//   },
//   desired: {
//     firmware: "1.4.0",
//     updateTime: "night",
//     lastUpdated: "2026-01-19T14:00:00.000Z"
//   }
// }

// Update desired device state
await access.request({
  url: `/devices/${deviceId}/shadow`,
  method: 'PATCH',
  body: {
    desired: {
      firmware: '1.4.0',
      updateTime: 'night',
      reportInterval: 300  // seconds
    }
  }
})

Device Monitoring

De.IoTB provides tools for monitoring device health and performance:

// Get device health metrics
const health = await access.request({
  url: `/devices/${deviceId}/health`,
  method: 'GET'
})

console.log('Device health:', health.data)
// Output:
// {
//   status: "healthy",
//   uptime: 259200,         // seconds
//   batteryLevel: 87,       // percent
//   signalStrength: 78,     // percent
//   lastHeartbeat: "2026-01-19T15:58:22.000Z",
//   diagnostics: {
//     memoryUsage: 64.2,    // percent
//     cpuUsage: 12.5,       // percent
//     storage: 45.8,        // percent
//     temperature: 42       // degrees C
//   }
// }

// Get device telemetry stats
const stats = await access.request({
  url: `/devices/${deviceId}/stats`,
  method: 'GET',
  query: {
    period: '24h'  // '1h', '24h', '7d', '30d'
  }
})

console.log('Telemetry stats:', stats.data)
// Output:
// {
//   messagesReceived: 2880,
//   dataVolume: 1450000,      // bytes
//   averageMessageSize: 503,  // bytes
//   averageInterval: 30,      // seconds
//   errorRate: 0.02,          // percent
//   batteryTrend: -0.5        // percent per hour
// }

Bulk Operations

For managing large device fleets efficiently:

// Bulk status update
await access.request({
  url: '/devices/bulk/status',
  method: 'PATCH',
  body: {
    deviceIds: ['tracker_001', 'tracker_002', 'tracker_003'],
    status: 'inactive'
  }
})

// Bulk command execution
await access.request({
  url: '/devices/bulk/commands',
  method: 'POST',
  body: {
    deviceIds: ['tracker_001', 'tracker_002', 'tracker_003'],
    command: 'config',
    parameters: {
      reportInterval: 60,
      powerMode: 'balanced'
    }
  }
})

// Bulk tag management
await access.request({
  url: '/devices/bulk/tags',
  method: 'POST',
  body: {
    deviceIds: ['tracker_001', 'tracker_002', 'tracker_003'],
    addTags: ['maintenance'],
    removeTags: ['active-fleet']
  }
})

Device Registry Schema

The De.IoTB device registry follows this data model:

interface Device {
  id: string                // System-generated ID
  workspace: string         // Workspace identifier
  deviceId: string          // User-provided device ID (unique within workspace)
  
  type: string              // Device type
  name: string              // Human-readable name
  description?: string      // Optional description
  
  status: 'active' | 'inactive' | 'suspended' | 'deprecated'
  
  info: {
    manufacturer: string
    model: string
    firmware: string
    hardware: string
    serialNumber?: string
    manufactureDate?: string
  }
  
  credentials: {
    type: 'token' | 'certificate'
    clientId: string
    username?: string
    passwordHash?: string
    certificate?: string
    expiresAt?: string
  }
  
  topics: {
    subscribe: string[]     // Topics the device can subscribe to
    publish: string[]       // Topics the device can publish to
  }
  
  connectivity: {
    protocol: 'mqtt' | 'mqtts' | 'ws' | 'wss' | 'http' | 'https'
    lastConnected?: string
    lastDisconnected?: string
    ipAddress?: string
    connected: boolean
  }
  
  location?: {
    lat: number
    lng: number
    accuracy?: number
    timestamp: string
  }
  
  tags: string[]
  
  metadata: Record<string, any>   // Custom device properties
  
  createdAt: string
  updatedAt: string
}

Security Best Practices

1. Unique Identifiers: Use globally unique identifiers for each device
2. Credential Rotation: Rotate device credentials periodically
3. Principle of Least Privilege: Limit device permissions to only necessary topics
4. Certificate-Based Auth: Use certificates for critical infrastructure
5. Secure Provisioning: Implement secure provisioning workflows
6. Monitoring: Track unusual connection patterns or behavior
7. Decommissioning: Properly revoke credentials when retiring devices

Next Steps

• Device Connectivity
• Telemetry Data Collection
• Command & Control Operations
• Active Rules Engine