AWS IoT Device SDK for JavaScript

The thingShadow class wraps a device instance to provide high-level API access to AWS IoT Thing Shadows.

Lifecycle and Operations:

1. Register: You must call register(thingName, [options], [callback]) before performing operations. This subscribes the client to the necessary shadow topics.
   • options.ignoreDeltas: If true, ignores the delta sub-topic.
   • options.persistentSubscribe: If false, the client unsubscribes from operation sub-topics when not performing an operation (improves traffic but slows down operations).
   • options.discardStale: If false, allows receiving messages with old version numbers.
   • options.enableVersioning: If true, sends version numbers with updates to prevent overwriting concurrent changes.
2. Perform Operations: Use update(), get(), or delete(). These return a clientToken (string or number) used to track the operation via 'status' or 'timeout' events.
3. Unregister: Call unregister(thingName) to stop receiving events and unsubscribe from shadow topics.

Core Events:

• 'status': Emitted when update|get|delete completes. Returns (thingName, stat, clientToken, stateObject). stat is either 'accepted' or 'rejected'.
• 'delta': Emitted when a delta is received for a registered shadow. Returns (thingName, stateObject).
• 'foreignStateChange': Emitted when a different client performs an update or delete on the shadow. Returns (thingName, operation, stateObject).
• 'timeout': Emitted when an operation times out. Returns (thingName, clientToken).
• 'message': Emitted for non-shadow MQTT messages. Returns (topic, message).

const shadow = awsIot.thingShadow(device, { operationTimeout: 10000 });

shadow.register('myThing', { ignoreDeltas: false }, (err) => {
  if (!err) {
    const token = shadow.update('myThing', { state: { temperature: 25 } });
    console.log('Update operation token:', token);
  }
});

shadow.on('status', (thingName, stat, clientToken, stateObject) => {
  console.log(`Operation ${clientToken} for ${thingName} was ${stat}`);
});

The Temperature Monitor browser application allows you to monitor a simulated temperature control device.

Prerequisites:

1. Install the Temperature Control Example Application.
2. Configure an Amazon Cognito Identity Pool in the AWS Console.
   • Allow unauthenticated identities to connect.
   • Ensure the unauthenticated IAM role has permissions for required AWS IoT APIs.
   • Obtain the PoolID.

Steps:

1. Edit examples/browser/temperature-monitor/aws-configuration.js and replace poolId and region with your Cognito values.
2. Create the bundle:

   npm run-script browserize examples/browser/temperature-monitor/index.js

3. Start the device simulation (in a separate terminal):

   node examples/temperature-control/temperature-control.js -f ~/certs --test-mode=2 -H <PREFIX>.iot.<REGION>.amazonaws.com

4. Open examples/browser/temperature-monitor/index.html in your browser.

For non-WebSocket connections (using mqtts), you must provide client certificates and private keys. You can specify them in two ways:

1. Using a Certificate Directory

Use the -f or --certificate-dir flag to point to a directory. The SDK will look for files with these exact names:

• certificate.pem.crt: Your AWS IoT certificate
• private.pem.key: Your private key
• root-CA.crt: The root CA certificate

2. Specifying Individual Files

Use specific flags for each file:

• -k, --private-key=FILE: Path to the private key
• -c, --client-certificate=FILE: Path to the client certificate
• -a, --ca-certificate=FILE: Path to the CA certificate

Tip: You can combine -f with individual file flags to avoid using absolute paths in your configuration.

# Example using a directory
node examples/device-example.js -f ~/certs --test-mode=1 -H <PREFIX>.iot.<REGION>.amazonaws.com

# Example using individual files
node examples/device-example.js -k ./key.pem -c ./cert.pem -a ./root.pem

The jobs-agent.js is an example agent that handles standard device management operations via AWS IoT Jobs. It responds to specific JSON job documents.

Supported Operations

systemStatus

Responds with system status information. Document: {"operation": "systemStatus"}

reboot

Attempts to reboot the device. Status is marked IN_PROGRESS until the agent restarts, then updated to SUCCESS. Document: {"operation": "reboot"}

shutdown

Attempts to shutdown the device. Document: {"operation": "shutdown"}

install

Installs files specified in the document. Requires a unique packageName. Document:

{
  "operation": "install",
  "packageName": "uniquePackageName",
  "workingDirectory": "../path",
  "launchCommand": "node app.js",
  "autoStart": "true",
  "files": [
    {
      "fileName": "app.js",
      "fileSource": { "url": "https://s3..." },
      "checksum": { "inline": { "value": "..." }, "hashAlgorithm": "SHA256" }
    }
  ]
}

start, stop, restart

Manages the execution of a previously installed package. Document (start): {"operation": "start", "packageName": "somePackageName"}

node examples/jobs-agent.js -f ~/certs -H <PREFIX>.iot.<REGION>.amazonaws.com -T agentThingName

To use a custom authorizer (registered via Lambda in AWS IoT), set the protocol to wss-custom-auth and provide credentials using one of two methods:

1. Headers: Set the customAuthHeaders option to an object containing your header names and values.
2. Query String: Set the customAuthQueryString option to a string containing key-value pairs.

Note: The custom authorizer must be previously set up in Lambda and registered with AWS IoT.

// Using customAuthHeaders
const device = awsIot.device({
    protocol: 'wss-custom-auth',
    customAuthHeaders: {
        'X-Amz-CustomAuthorizer-Name': 'TestAuthorizer',
        'X-Amz-CustomAuthorizer-Signature': 'signature',
        'TestAuthorizerToken': 'token'
    }
});

// Using customAuthQueryString
const device = awsIot.device({
    protocol: 'wss-custom-auth',
    customAuthQueryString: '?X-Amz-CustomAuthorizer-Name=TestAuthorizer&X-Amz-CustomAuthorizer-Signature=signature&TestAuthorizerToken=token'
});