Skygear IoT Feature Spec

Devices

Each IoT device must provide a platform interface object to the SDK:

{
  action: { // platform specific action, all optional.
    shutdown: async function() {}
    restart: async function() {}
  },
  // return a string that is unique to the hardware
  // could be SoC model + serial number
  deviceSecret: string
  appVersion: string
}

Each device has:

• a deviceSecret provided by the hardware
• a deviceID after registration
• a loginID after logging in (like a session ID)

SDK API

API Doc: https://doc.esdoc.org/github.com/SkygearIO/iot-SDK-JS/

Users and Roles

There are 2 Skygera IoT specific roles:

• iot-device can call device-specific lambdas.
• iot-manager can read/write iot_* tables and send messages to devices using a lambda.

Database Schema

• iot_device (ACL: public = no, iot-manager = rw)

  • _id (skygear user id)
  • secret (string)
  • class (string)
  • active (bool, true unless the device has been de-registered)

• iot_device_login (ACL: public = no, iot-manager = rw

  • deviceID (FK: iot_device._id)
  • sdkVersion (string)
  • appVersion (string)

• iot_device_status (ACL: public = no, iot-manager = rw)

  • deviceID (FK: iot_device._id)
  • loginID (FK: iot_device_login._id)
  • status (online, offline)
  • metadata (JSON)
  • ip (string)

Determining Device Status

A device is online iff the latest iot_device_status record is created within X minutes of the current time AND the status field is online.

PubSub

• iot-request-status a channel for the server to globally request status reports from all devices subscribing to it.

• iot-<SHA256(deviceSecret)> a secure channel for the server to send messages to a device, payload must be an object with atleast 1 key: "action". Some pre-defined actions are:

  • iot-shutdown
  • iot-restart

{
  action: "",
  ...
}

Lambda

• iot:add-device-role() adds the role iot-device to the request user

• iot:report-status({deviceID: "", loginID: "", status: "online"}) used by devices to report its current status

• iot:device-publish([deviceID, data]) (requires either master key OR iot-manager role) publish messages to device's secure channels

• iot:log(message) logs message to the skygear portal

JS SDK Changes

• Add pubsub subscribe once helper function