AWS IoT thingShadow Helper Library

Overview

Helper library which aims to simplify the usage of not so intuitive AWS IoT thingShadow API. The library is designed as a wrapper around aws-iot-device-sdk and it targets thingShadow API only.

This library provides more intuitive, promise based API for thingShadow's "register"/"unregister", "get", "update" and "delete" operations.

Install

npm install aws-iot-device-sdk
npm install aws-iot-shadow-helper

Usage Examples

const AWSIoT = require('aws-iot-device-sdk');
const ShadowHelper = require('aws-iot-shadow-helper');

// see aws-iot-device-sdk for details about thingShadow setup
const thingShadow = AWSIoT.thingShadow({
  region: 'add-region-here',
  clientId: 'test-client-id',
  protocol: 'wss',
  maximumReconnectTimeMs: 3000,
  debug: true,
  accessKeyId: '',
  secretKey: '',
  sessionToken: ''
});

ShadowHelper.init(thingShadow);

async function shadowUsageSample() {
    // register
    await ShadowHelper.registerThingAsync('my-thing');

    // now you can listen to standard "delta" event for shadow updates

    // get
    let myThing = await ShadowHelper.getThingAsync('my-thing');

    // update
    await ShadowHelper.updateThingAsync(thingName, {
      state: {
        desired: {
          myThingState: 'new state'
        }
      }
    });

    // delete
    await ShadowHelper.deleteThingAsync('my-thing');

    // unregister
    ShadowHelper.unregisterThing('my-thing')
}

API Docs

• ShadowHelper.init
• ShadowHelper.registerThingAsync
• ShadowHelper.unregisterThing
• ShadowHelper.getThingAsync
• ShadowHelper.updateThingAsync
• ShadowHelper.deleteThingAsync

ShadowHelper.init(thingShadow : awsIoT.thingShadow) : void

Initialize ShadowHelper with the instance of awsIot.thingShadow class. The rest of ShadowHelper's API can be used immediately after initialization.

ShadowHelper.registerThingAsync(thingName: string, [options]: Object): Promise<void>

Promisified version of awsIot.thingShadow#register method. Additionally, it is extended to resolve the promise in the case when given thingName is already registered. Now, it is transparent if a thingName is already registered or not. Original API doesn't invoke a callback if thingName is already registered and there is no way to detect if it is registered or not.

See the original API docs for information about input parameters.

ShadowHelper.unregisterThing(thingName: string): void

If a thingName is registered with ShadowHelper.registerThingAsync API, this method has to be used to unregister it, in order to clean internal state.

See the original API docs for more information.

ShadowHelper.getThingAsync(thingName: string): Promise

Promisified version of awsIot.thingShadow#get method. Instead of returning a clientToken, this API returns a promise which is resolved or rejected depending on the operation outcome ... as usual. It completely abstracts away logic related to clientToken, so you don't need to worry about.

ShadowHelper.updateThingAsync(thingName: string, stateObj: object): Promise

Promisified version of awsIot.thingShadow#update method. Instead of returning a clientToken, this API returns a promise which is resolved or rejected depending on the operation outcome ... as usual. It completely abstracts away logic related to clientToken, so you don't need to worry about.

ShadowHelper.deleteThingAsync(thingName: string): Promise

Promisified version of awsIot.thingShadow#delete method. Instead of returning a clientToken, this API returns a promise which is resolved or rejected depending on the operation outcome ... as usual. It completely abstracts away logic related to clientToken, so you don't need to worry about.