Skip to content

Skygear IoT Feature Spec

Jump to bottom
Akiroz edited this page Apr 3, 2017 · 15 revisions

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

const skygearIoT = require('skygear-iot');

Properties

  • skygearIoT.device.platform
  • skygearIoT.device.deviceID (iot_device._id or null)
  • skygearIoT.device.loginID (iot_device_login._id or null)

skygearIoT.device is read-only.

Methods

  • skygearIoT.initialize(platform) initializes SDK with a provided platform
  • skygearIoT.registerDevice(user) register this device with provided user, adds role iot-device to user
  • skygearIoT.log(message, attachment) log to skygear portal (with optional object attachment)
  • skygearIoT.reportStatus() report status to the skygear server
  • skygearIoT.getDeviceChannelName() returns pubsub channel for this device

Users and Roles

There are 2 Skygera IoT specific roles:

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

Database Schema

  • iot_device (ACL: public no access)

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

  • iot_device_login (ACL: public no access)

    • device_id (FK: iot_device._id)
    • sdk_version (string)
    • app_version (string)

  • iot_device_status (ACL: public no access)

    • device_id (FK: iot_device._id)
    • login_id (FK: iot_device_login._id)
    • status (online, offline)
    • 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-<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-request-status
    • iot-shutdown
    • iot-restart
{
  action: "",
  ...
}

Lambda

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

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

  • iot:log logs message to the skygear portal

JS SDK Changes

  • Add pubsub subscribe once helper function

Clone this wiki locally