README.md

serverless-iot-offline

Serverless plugin that emulates AWS IoT service. Manages topic subscriptions, lifecycle events, thing shadow management and rule engine with limited SQL syntax support.

Prerequisites

Redis installed.
Serverless framework 1.x

Installation

Add serverless-iot-offline to your project:
npm install --save-dev serverless-iot-offline
Then inside yur serverless.yml file add following entry to the plugins section: serverless-iot-offline. If there is no plugin section you will need to add it to the file.
Example:

plugins:
  - serverless-iot-offline

or if you are using serverless-offline plugin:

plugins:
  - serverless-iot-offline
  - serverless-offline

If you are using serverless-offline v5.12.1 and below, use serverless-iot-offline@0.1.4 for comaptibility.

Usage and command line options

Make sure redis-server is started.
If you are using serverless-offline you can run:
sls offline start
Otherwise run:
sls iot start

CLI options:

--port                -p  # Port to listen on. Default: 1883
--httpPort            -h  # Port for WebSocket connections. Default: 1884
--noStart             -n  # Prevent Iot broker (Mosca MQTT brorker) from being started (if you already have one)
--skipCacheValidation -c  # Tells the plugin to skip require cache invalidation. A script reloading tool like Nodemon might then be needed (same as serverless-offline)

Above options could be added through serverless.yml file:

custom:
  iot:
    start:
      port: 1880
    redis:
      host: 'localhost'
      port: 6379
      db: 12
    # path to initial shadows
    # it is used to seed redis database with preconfigured shadows
    seedShadows: ./shadows.json
    # optional seedPolicies path
    seedPolicies: ./policy.json

Example of shadows.json file which will seed redis with 2 shadows:

{
  "thingName1": {
    "state": {
      "reported": {
        "some_prop": "hello"
      }
    }
  },
  "thingName2": {
    "state": {
      "reported": {}
    }
  }
}

Contributing

Local implementation of AWS IoT service has a minimum of SQL syntax support and primarily we need help with that.
To get a better understanding of what SQL syntax we are supporting see documentation and testData.js file.
Checkout contributing guidelines.

Credits and inspiration

This plugin was inspired by Tradle's serverless-iot-local project

Licence

MIT