{"id":13527662,"url":"https://github.com/aws/aws-iot-device-sdk-js","last_synced_at":"2025-05-14T11:08:51.747Z","repository":{"id":37470273,"uuid":"43452375","full_name":"aws/aws-iot-device-sdk-js","owner":"aws","description":"SDK for connecting to AWS IoT from a device using JavaScript/Node.js","archived":false,"fork":false,"pushed_at":"2024-10-25T22:40:53.000Z","size":478,"stargazers_count":966,"open_issues_count":1,"forks_count":382,"subscribers_count":74,"default_branch":"master","last_synced_at":"2025-04-25T18:19:29.937Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-30T18:52:35.000Z","updated_at":"2025-04-25T15:04:08.000Z","dependencies_parsed_at":"2022-07-21T09:02:43.769Z","dependency_job_id":"1ceb3e78-0f3a-4020-ab96-1b2af621c2cb","html_url":"https://github.com/aws/aws-iot-device-sdk-js","commit_stats":{"total_commits":76,"total_committers":23,"mean_commits":"3.3043478260869565","dds":0.75,"last_synced_commit":"737363f27f0224ee664fafd59bd7efcdbd612e6c"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-iot-device-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-iot-device-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-iot-device-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-iot-device-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/aws-iot-device-sdk-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250869648,"owners_count":21500354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:01:56.137Z","updated_at":"2025-04-27T04:44:14.982Z","avatar_url":"https://github.com/aws.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","SDKs and Samples"],"sub_categories":["IoT SDK"],"readme":"## New Version Available\n\nA new AWS IoT Device SDK is [now available](https://github.com/awslabs/aws-iot-device-sdk-js-v2). It is a complete rework, built to improve reliability, performance, and security. We invite your feedback!\n\nThis SDK will no longer receive feature updates, but will receive security updates.\n\n# AWS IoT SDK for JavaScript\nThe aws-iot-device-sdk.js package allows developers to write JavaScript\napplications which access the AWS IoT Platform via [MQTT or MQTT over the Secure WebSocket Protocol](http://docs.aws.amazon.com/iot/latest/developerguide/protocols.html).  It can be used in Node.js environments as well as in browser applications.\n\n* [Overview](#overview)\n* [Installation](#install)\n* [Mac-Only TLS Behavior](#mac-tls-warning)\n* [Examples](#examples)\n* [API Documentation](#api)\n* [Connection Types](#connections)\n* [Example Programs](#programs)\n* [Browser Applications](#browser)\n* [Troubleshooting](#troubleshooting)\n* [Unit Tests](#unittests)\n* [License](#license)\n* [Support](#support)\n\n\u003ca name=\"overview\"\u003e\u003c/a\u003e\n## Overview\nThis document provides instructions on how to install and configure the AWS\nIoT device SDK for JavaScript, and includes examples demonstrating use of the\nSDK APIs.\n\n### MQTT Connection\nThis package is built on top of [mqtt.js](https://github.com/mqttjs/MQTT.js/blob/master/README.md) and provides three classes: 'device', 'thingShadow' and 'jobs'.  The 'device' class wraps [mqtt.js](https://github.com/mqttjs/MQTT.js/blob/master/README.md) to provide a\nsecure connection to the AWS IoT platform and expose the [mqtt.js](https://github.com/mqttjs/MQTT.js/blob/master/README.md) interfaces upward.  It provides features to simplify handling of intermittent connections, including progressive backoff retries, automatic re-subscription upon connection, and queued offline publishing with configurable drain rate.\n\n### Collection of Metrics\nBeginning with Release v2.2.0 of the SDK, AWS collects usage metrics indicating which language and version of the SDK is being used. This allows us to prioritize our resources towards addressing issues faster in SDKs that see the most and is an important data point. However, we do understand that not all customers would want to report this data by default. In that case, the sending of usage metrics can be easily disabled by set options.enableMetrics to false.\n\n### Thing Shadows\nThe 'thingShadow' class implements additional functionality for accessing Thing Shadows via the AWS IoT\nAPI; the thingShadow class allows devices to update, be notified of changes to,\nget the current state of, or delete Thing Shadows from AWS IoT.  Thing\nShadows allow applications and devices to synchronize their state on the AWS IoT platform.\nFor example, a remote device can update its Thing Shadow in AWS IoT, allowing\na user to view the device's last reported state via a mobile app.  The user\ncan also update the device's Thing Shadow in AWS IoT and the remote device\nwill synchronize with the new state.  The 'thingShadow' class supports multiple\nThing Shadows per mqtt connection and allows pass-through of non-Thing-Shadow\ntopics and mqtt events.\n\n### Jobs\nThe 'jobs' class implements functionality to interact with the AWS IoT Jobs service. The\nIoT Job service manages deployment of IoT fleet wide tasks such as device software/firmware\ndeployments and updates, rotation of security certificates, device reboots, and custom device\nspecific management tasks.\n\nIncluded in this package is an example 'agent'. The agent can be used either as a stand-alone\nprogram to manage installation and maintenance of files and other running processes or it can\nbe incorporated into a customized agent to meet specific application needs.\n\n\u003ca name=\"install\"\u003e\u003c/a\u003e\n## Installation\n\n**NOTE:** AWS IoT Node.js SDK will only support Node version 8.17 or above.\n\nYou can check your node version by\n\n```sh\nnode -v\n```\n\nInstalling with npm:\n\n```sh\nnpm install aws-iot-device-sdk\n```\n\nInstalling from github:\n\n```sh\ngit clone https://github.com/aws/aws-iot-device-sdk-js.git\ncd aws-iot-device-sdk-js\nnpm install\n```\n\n\u003ca name=\"mac-tls-warning\"\u003e\u003c/a\u003e\n## Mac-Only TLS Behavior\n\nPlease note that on Mac, once a private key is used with a certificate,\nthat certificate-key pair is imported into the Mac Keychain.\nAll subsequent uses of that certificate will use the stored private key and\nignore anything passed in programmatically.\n\n\u003ca name=\"examples\"\u003e\u003c/a\u003e\n## Examples\n\n### Device Class\n```js\n// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n// SPDX-License-Identifier: MIT-0\nvar awsIot = require('aws-iot-device-sdk');\n\n//\n// Replace the values of '\u003cYourUniqueClientIdentifier\u003e' and '\u003cYourCustomEndpoint\u003e'\n// with a unique client identifier and custom host endpoint provided in AWS IoT.\n// NOTE: client identifiers must be unique within your AWS account; if a client attempts\n// to connect with a client identifier which is already in use, the existing\n// connection will be terminated.\n//\nvar device = awsIot.device({\n   keyPath: \u003cYourPrivateKeyPath\u003e,\n  certPath: \u003cYourCertificatePath\u003e,\n    caPath: \u003cYourRootCACertificatePath\u003e,\n  clientId: \u003cYourUniqueClientIdentifier\u003e,\n      host: \u003cYourCustomEndpoint\u003e\n});\n\n//\n// Device is an instance returned by mqtt.Client(), see mqtt.js for full\n// documentation.\n//\ndevice\n  .on('connect', function() {\n    console.log('connect');\n    device.subscribe('topic_1');\n    device.publish('topic_2', JSON.stringify({ test_data: 1}));\n  });\n\ndevice\n  .on('message', function(topic, payload) {\n    console.log('message', topic, payload.toString());\n  });\n```\n\n### Thing Shadow Class\n```js\n// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n// SPDX-License-Identifier: MIT-0\nvar awsIot = require('aws-iot-device-sdk');\n\n//\n// Replace the values of '\u003cYourUniqueClientIdentifier\u003e' and '\u003cYourCustomEndpoint\u003e'\n// with a unique client identifier and custom host endpoint provided in AWS IoT cloud\n// NOTE: client identifiers must be unique within your AWS account; if a client attempts\n// to connect with a client identifier which is already in use, the existing\n// connection will be terminated.\n//\nvar thingShadows = awsIot.thingShadow({\n   keyPath: \u003cYourPrivateKeyPath\u003e,\n  certPath: \u003cYourCertificatePath\u003e,\n    caPath: \u003cYourRootCACertificatePath\u003e,\n  clientId: \u003cYourUniqueClientIdentifier\u003e,\n      host: \u003cYourCustomEndpoint\u003e\n});\n\n//\n// Client token value returned from thingShadows.update() operation\n//\nvar clientTokenUpdate;\n\n//\n// Simulated device values\n//\nvar rval = 187;\nvar gval = 114;\nvar bval = 222;\n\nthingShadows.on('connect', function() {\n//\n// After connecting to the AWS IoT platform, register interest in the\n// Thing Shadow named 'RGBLedLamp'.\n//\n    thingShadows.register( 'RGBLedLamp', {}, function() {\n\n// Once registration is complete, update the Thing Shadow named\n// 'RGBLedLamp' with the latest device state and save the clientToken\n// so that we can correlate it with status or timeout events.\n//\n// Thing shadow state\n//\n       var rgbLedLampState = {\"state\":{\"desired\":{\"red\":rval,\"green\":gval,\"blue\":bval}}};\n\n       clientTokenUpdate = thingShadows.update('RGBLedLamp', rgbLedLampState  );\n//\n// The update method returns a clientToken; if non-null, this value will\n// be sent in a 'status' event when the operation completes, allowing you\n// to know whether or not the update was successful.  If the update method\n// returns null, it's because another operation is currently in progress and\n// you'll need to wait until it completes (or times out) before updating the\n// shadow.\n//\n       if (clientTokenUpdate === null)\n       {\n          console.log('update shadow failed, operation still in progress');\n       }\n    });\n});\nthingShadows.on('status',\n    function(thingName, stat, clientToken, stateObject) {\n       console.log('received '+stat+' on '+thingName+': '+\n                   JSON.stringify(stateObject));\n//\n// These events report the status of update(), get(), and delete()\n// calls.  The clientToken value associated with the event will have\n// the same value which was returned in an earlier call to get(),\n// update(), or delete().  Use status events to keep track of the\n// status of shadow operations.\n//\n    });\n\nthingShadows.on('delta',\n    function(thingName, stateObject) {\n       console.log('received delta on '+thingName+': '+\n                   JSON.stringify(stateObject));\n    });\n\nthingShadows.on('timeout',\n    function(thingName, clientToken) {\n       console.log('received timeout on '+thingName+\n                   ' with token: '+ clientToken);\n//\n// In the event that a shadow operation times out, you'll receive\n// one of these events.  The clientToken value associated with the\n// event will have the same value which was returned in an earlier\n// call to get(), update(), or delete().\n//\n    });\n\n```\n### Jobs Class\n```js\n// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n// SPDX-License-Identifier: MIT-0\nvar awsIot = require('aws-iot-device-sdk');\n\n//\n// Replace the values of '\u003cYourUniqueClientIdentifier\u003e' and '\u003cYourCustomEndpoint\u003e'\n// with a unique client identifier and custom host endpoint provided in AWS IoT cloud\n// NOTE: client identifiers must be unique within your AWS account; if a client attempts\n// to connect with a client identifier which is already in use, the existing\n// connection will be terminated.\n//\nvar jobs = awsIot.jobs({\n   keyPath: \u003cYourPrivateKeyPath\u003e,\n  certPath: \u003cYourCertificatePath\u003e,\n    caPath: \u003cYourRootCACertificatePath\u003e,\n  clientId: \u003cYourUniqueClientIdentifier\u003e,\n      host: \u003cYourCustomEndpoint\u003e\n});\n\n//\n// Jobs is built on top of awsIot.device and inherits all of the same functionality.\n//\njobs\n  .on('connect', function() {\n    console.log('connect');\n    device.subscribe('topic_1');\n    device.publish('topic_2', JSON.stringify({ test_data: 1}));\n    });\n\njobs\n  .on('message', function(topic, payload) {\n    console.log('message', topic, payload.toString());\n  });\n\n//\n// To subscribe to job execution events call the subscribeToJobs method which takes\n// a callback that will be invoked when a job execution is available or an error\n// occurs. The job object passed to the callback contains information about the job\n// execution and methods for updating the job execution status. Details covered\n// in the API documentation below.\n//\njobs.subscribeToJobs(thingName, function(err, job) {\n   if (isUndefined(err)) {\n      console.log('default job handler invoked, jobId: ' + job.id.toString());\n      console.log('job document: ' + job.document);\n   }\n   else {\n      console.error(err);\n   }\n});\n\njobs.subscribeToJobs(thingName, 'customJob', function(err, job) {\n   if (isUndefined(err)) {\n      console.log('customJob operation handler invoked, jobId: ' + job.id.toString());\n      console.log('job document: ' + job.document);\n   }\n   else {\n      console.error(err);\n   }\n});\n\n//\n// After calling subscribeToJobs for each operation on a particular thing call\n// startJobNotifications to cause any existing queued job executions for the given\n// thing to be published to the appropriate subscribeToJobs handler. Only needs\n// to be called once per thing.\n//\njobs.startJobNotifications(thingName, function(err) {\n   if (isUndefined(err)) {\n      console.log('job notifications initiated for thing: ' + thingName);\n   }\n   else {\n      console.error(err);\n   }\n});\n\n```\n\n\u003ca name=\"api\"\u003e\u003c/a\u003e\n## API Documentation\n\n  * \u003ca href=\"#device\"\u003e\u003ccode\u003eawsIot.\u003cb\u003edevice()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#thingShadow\"\u003e\u003ccode\u003eawsIot.\u003cb\u003ethingShadow()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#jobs\"\u003e\u003ccode\u003eawsIot.\u003cb\u003ejobs()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#register\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003eregister()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#unregister\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003eunregister()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#update\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003eupdate()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#get\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003eget()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#delete\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003edelete()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#publish\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003epublish()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#subscribe\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003esubscribe()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#unsubscribe\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003eunsubscribe()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#end\"\u003e\u003ccode\u003eawsIot.thingShadow#\u003cb\u003eend()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#subscribeToJobs\"\u003e\u003ccode\u003eawsIot.jobs#\u003cb\u003esubscribeToJobs()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#unsubscribeFromJobs\"\u003e\u003ccode\u003eawsIot.jobs#\u003cb\u003eunsubscribeFromJobs()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#startJobNotifications\"\u003e\u003ccode\u003eawsIot.jobs#\u003cb\u003estartJobNotifications()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#job\"\u003e\u003ccode\u003e\u003cb\u003ejob\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#document\"\u003e\u003ccode\u003ejob#\u003cb\u003edocument\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#id\"\u003e\u003ccode\u003ejob#\u003cb\u003eid\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#operation\"\u003e\u003ccode\u003ejob#\u003cb\u003eoperation\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#status\"\u003e\u003ccode\u003ejob#\u003cb\u003estatus\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#inProgress\"\u003e\u003ccode\u003ejob#\u003cb\u003einProgress()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#failed\"\u003e\u003ccode\u003ejob#\u003cb\u003efailed()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n  * \u003ca href=\"#succeeded\"\u003e\u003ccode\u003ejob#\u003cb\u003esucceeded()\u003c/b\u003e\u003c/code\u003e\u003c/a\u003e\n\n-------------------------------------------------------\n\u003ca name=\"device\"\u003e\u003c/a\u003e\n### awsIot.device(options)\n\nReturns a wrapper for the [mqtt.Client()](https://github.com/mqttjs/MQTT.js/blob/master/README.md#client)\nclass, configured for a TLS connection with the AWS IoT platform and with\narguments as specified in `options`.  The AWSIoT-specific arguments are as\nfollows:\n\n  * `host`: the AWS IoT endpoint you will use to connect\n  * `clientId`: the client ID you will use to connect to AWS IoT\n  * `certPath`: path of the client certificate file\n  * `keyPath`: path of the private key file associated with the client certificate\n  * `caPath`: path of your CA certificate file\n  * `clientCert`: same as `certPath`, but can also accept a buffer containing client certificate data\n  * `privateKey`: same as `keyPath`, but can also accept a buffer containing private key data\n  * `caCert`: same as `caPath`, but can also accept a buffer containing CA certificate data\n  * `autoResubscribe`: set to 'true' to automatically re-subscribe to topics after reconnection (default 'true')\n  * `offlineQueueing`: set to 'true' to automatically queue published messages while offline (default 'true')\n  * `offlineQueueMaxSize`: enforce a maximum size for the offline message queue (default 0, e.g. no maximum)\n  * `offlineQueueDropBehavior`: set to 'oldest' or 'newest' to define drop behavior on a full queue when offlineQueueMaxSize \u003e 0\n  * `drainTimeMs`: the minimum time in milliseconds between publishes when draining after reconnection (default 250)\n  * `baseReconnectTimeMs`: the base reconnection time in milliseconds (default 1000)\n  * `maximumReconnectTimeMs`: the maximum reconnection time in milliseconds (default 128000)\n  * `minimumConnectionTimeMs`: the minimum time in milliseconds that a connection must be maintained in order to be considered stable (default 20000)\n  * `protocol`: the connection type, either 'mqtts' (default), 'wss' (WebSocket/TLS), or 'wss-custom-auth' (WebSocket/TLS with custom authentication).  Note that when set to 'wss', values must be provided for the Access Key ID and Secret Key in either the following options or in environment variables as specified in [WebSocket Configuration](#websockets). When set to 'wss-custom-auth', valid headers must be provided as specified in [Custom Auth](#custom-auth)\n  * `websocketOptions`: if `protocol` is set to 'wss', you can use this parameter to pass additional options to the underlying WebSocket object; these options are documented [here](https://github.com/websockets/ws/blob/master/doc/ws.md#class-wswebsocket).\n  * `filename`: used to load credentials from the file different than the default location when `protocol` is set to 'wss'. Default value is '~/.aws/credentials'\n  * `profile`: used to specify which credential profile to be used when `protocol` is set to 'wss'.  Default value is 'default'\n  * `accessKeyId`: used to specify the Access Key ID when `protocol` is set to 'wss'.  Overrides the environment variable `AWS_ACCESS_KEY_ID` and `AWS_ACCESS_KEY_ID` from `filename` if set.\n  * `secretKey`: used to specify the Secret Key when `protocol` is set to 'wss'.  Overrides the environment variable `AWS_SECRET_ACCESS_KEY`and `AWS_SECRET_ACCESS_KEY`  from `filename` if set.\n  * `sessionToken`: (required when authenticating via Cognito, optional otherwise) used to specify the Session Token when `protocol` is set to 'wss'.  Overrides the environment variable `AWS_SESSION_TOKEN` if set.\n  * `region`: used to specify AWS account region (e.g. 'us-east-1') when `protocol` is set to `wss`. If undefined, a value is derived from `host`.\n  * `customAuthHeaders`: used to specify your custom authorization headers when `protocol` is set to 'wss-custom-auth'. The fields 'X-Amz-CustomAuthorizer-Name', 'X-Amz-CustomAuthorizer-Signature', and the field for your token name are required.\n  * `servername`: used for SNI. If undefined, a value is derived from `host`.\n  * `port`: used to specify which port to connect to. If undefined, 443 or 8883 will be chosen depending on `protocol`.\n  * `customAuthQueryString`: used to specify the token credentials in a query string for custom authorization when `protocol` is set to `wss-custom-auth`. More info can be found [here](https://docs.aws.amazon.com/iot/latest/developerguide/custom-auth.html#custom-auth-websockets).\n  * `keepalive`: used to specify the time interval for each ping request. Default is set to 300 seconds to connect to AWS IoT.\n  * `enableMetrics`: used to report SDK version usage metrics. It is set to true by default. To disable metrics collection, set value to false.\n  * `debug`: set to 'true' for verbose logging (default 'false').\n\nAll certificates and keys must be in PEM format.\n\n`options` also contains arguments specific to mqtt.  See [the mqtt client documentation]\n(https://github.com/mqttjs/MQTT.js/blob/master/README.md#client) for details\nof these arguments. Note, AWS IoT doesn't support retained messages; setting `retain` flag to\n'true' for message publishing, including Last Will and Testament messages, will result in\nconnection termination. For AWS IoT protocol specifics, please visit [here](http://docs.aws.amazon.com/iot/latest/developerguide/protocols.html).\n\nSupports all events emitted by the [mqtt.Client()](https://github.com/mqttjs/MQTT.js/blob/master/README.md#client) class.\n\n\u003ca name=\"updateWebSocketCredentials\"\u003e\u003c/a\u003e\n### awsIot.device#updateWebSocketCredentials(accessKeyId, secretKey, sessionToken, expiration)\n\nUpdate the credentials set used to authenticate via WebSocket/SigV4.  This method is designed to be invoked during the callback of the [getCredentialsForIdentity method](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentity.html#getCredentialsForIdentity-property) in the [AWS SDK for JavaScript](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/index.html).\n\n* `accessKeyId`: the latest Access Key to use when connecting via WebSocket/SigV4\n* `secretKey`: the latest Secret Key to use when connecting via WebSocket/SigV4\n* `sessionToken`: the latest Session Token to use when connecting via WebSocket/SigV4\n* `expiration`: the time this credentials set will expire\n\n-------------------------------------------------------\n\u003ca name=\"thingShadow\"\u003e\u003c/a\u003e\n### awsIot.thingShadow(deviceOptions, thingShadowOptions)\n\nThe `thingShadow` class wraps an instance of the `device` class with additional\nfunctionality to operate on Thing Shadows via the AWS IoT API.  The\narguments in `deviceOptions` include all those in the [device class](#device).\nthingShadowOptions has the addition of the following arguments specific to the `thingShadow` class:\n\n* `operationTimeout`: the timeout for thing operations (default 10 seconds)\n\nSupports all events emitted by the [mqtt.Client()](https://github.com/mqttjs/MQTT.js/blob/master/README.md#client) class; however, the semantics for the\n`message` event are slightly different and additional events are available\nas described below:\n\n### Event `'message'`\n\n`function(topic, message) {}`\n\nEmitted when a message is received on a topic not related to any Thing Shadows:\n* `topic` topic of the received packet\n* `message` payload of the received packet\n\n### Event `'status'`\n\n`function(thingName, stat, clientToken, stateObject) {}`\n\nEmitted when an operation `update|get|delete` completes.\n* `thingName` name of the Thing Shadow for which the operation has completed\n* `stat` status of the operation `accepted|rejected`\n* `clientToken` the operation's clientToken\n* `stateObject` the stateObject returned for the operation\n\nApplications can use clientToken values to correlate status events with the\noperations that they are associated with by saving the clientTokens returned\nfrom each operation.\n\n### Event `'delta'`\n\n`function(thingName, stateObject) {}`\n\nEmitted when a delta has been received for a registered Thing Shadow.\n* `thingName` name of the Thing Shadow that has received a delta\n* `stateObject` the stateObject returned for the operation\n\n### Event `'foreignStateChange'`\n\n`function(thingName, operation, stateObject) {}`\n\nEmitted when a different client's update or delete operation is accepted on\nthe shadow.\n\n* `thingName` name of the Thing Shadow for which the operation has completed\n* `operation` operation performed by the foreign client `update|delete`\n* `stateObject` the stateObject returned for the operation\n\nThis event allows an application to be aware of successful update or\ndelete operations performed by different clients.\n\n### Event `'timeout'`\n\n`function(thingName, clientToken) {}`\n\nEmitted when an operation `update|get|delete` has timed out.\n* `thingName` name of the Thing Shadow that has received a timeout\n* `clientToken` the operation's clientToken\n\nApplications can use clientToken values to correlate timeout events with the\noperations that they are associated with by saving the clientTokens returned\nfrom each operation.\n\n-------------------------------------------------------\n\u003ca name=\"register\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#register(thingName, [options], [callback] )\n\nRegister interest in the Thing Shadow named `thingName`.  The thingShadow class will\nsubscribe to any applicable topics, and will fire events for the Thing Shadow\nuntil [awsIot.thingShadow#unregister()](#unregister) is called with `thingName`.  `options`\ncan contain the following arguments to modify how this Thing Shadow is processed:\n\n* `ignoreDeltas`: set to `true` to not subscribe to the `delta` sub-topic for this Thing Shadow; used in cases where the application is not interested in changes (e.g. update only.) (default `false`)\n* `persistentSubscribe`: set to `false` to unsubscribe from all operation sub-topics while not performing an operation (default `true`)\n* `discardStale`: set to `false` to allow receiving messages with old version numbers (default `true`)\n* `enableVersioning`: set to `true` to send version numbers with shadow updates (default `true`)\n\nThe `persistentSubscribe` argument allows an application to get faster operation\nresponses at the expense of potentially receiving more irrelevant response\ntraffic (i.e., response traffic for other clients who have registered interest\nin the same Thing Shadow).  When `persistentSubscribe` is set to `false`, operation\nsub-topics are only subscribed to during the scope of that operation;\nnote that in this mode, update, get, and delete operations will be much slower;\nhowever, the application will be less likely to receive irrelevant response traffic.\n\nThe `discardStale` argument allows applications to receive messages which have\nobsolete version numbers.  This can happen when messages are received out-of-order;\napplications which set this argument to `false` should use other methods to\ndetermine how to treat the data (e.g. use a time stamp property to know how old/stale\nit is).\n\nIf `enableVersioning` is set to true, version numbers will be sent with each operation.\nAWS IoT maintains version numbers for each shadow, and will reject operations which\ncontain the incorrect version; in applications where multiple clients update the same\nshadow, clients can use versioning to avoid overwriting each other's changes.\n\nIf the `callback` parameter is provided, it will be invoked after registration is complete (i.e., when subscription ACKs have been received for all shadow topics).  Applications should wait until shadow registration is complete before performing update/get/delete operations.\n\n-------------------------------------------------------\n\u003ca name=\"unregister\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#unregister(thingName)\n\nUnregister interest in the Thing Shadow named `thingName`.  The thingShadow class\nwill unsubscribe from all applicable topics and no more events will be fired\nfor `thingName`.\n\n-------------------------------------------------------\n\u003ca name=\"update\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#update(thingName, stateObject)\n\nUpdate the Thing Shadow named `thingName` with the state specified in the\nJavaScript object `stateObject`.  `thingName` must have been previously\nregistered\nusing [awsIot.thingShadow#register()](#register).  The thingShadow class will subscribe\nto all applicable topics and publish `stateObject` on the \u003cb\u003eupdate\u003c/b\u003e sub-topic.\n\nThis function returns a `clientToken`, which is a unique value associated with\nthe update operation.  When a 'status' or 'timeout' event is emitted,\nthe `clientToken` will be supplied as one of the parameters, allowing the\napplication to keep track of the status of each operation.  The caller may\ncreate their own `clientToken` value; if `stateObject` contains a `clientToken`\nproperty, that will be used rather than the internally generated value.  Note\nthat it should be of atomic type (i.e. numeric or string).  This function\nreturns 'null' if an operation is already in progress.\n\n-------------------------------------------------------\n\u003ca name=\"get\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#get(thingName, [clientToken])\n\nGet the current state of the Thing Shadow named `thingName`, which must have\nbeen previously registered using [awsIot.thingShadow#register()](#register).  The\nthingShadow class will subscribe to all applicable topics and publish on the\n\u003cb\u003eget\u003c/b\u003e sub-topic.\n\nThis function returns a `clientToken`, which is a unique value associated with\nthe get operation.  When a 'status or 'timeout' event is emitted,\nthe `clientToken` will be supplied as one of the parameters, allowing the\napplication to keep track of the status of each operation.  The caller may\nsupply their own `clientToken` value (optional); if supplied, the value of\n`clientToken` will be used rather than the internally generated value.  Note\nthat this value should be of atomic type (i.e. numeric or string).  This\nfunction returns 'null' if an operation is already in progress.\n\n-------------------------------------------------------\n\u003ca name=\"delete\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#delete(thingName, [clientToken])\n\nDelete the Thing Shadow named `thingName`, which must have been previously\nregistered using [awsIot.thingShadow#register()](#register).  The thingShadow class\nwill subscribe to all applicable topics and publish on the \u003cb\u003edelete\u003c/b\u003e\nsub-topic.\n\nThis function returns a `clientToken`, which is a unique value associated with\nthe delete operation.  When a 'status' or 'timeout' event is emitted,\nthe `clientToken` will be supplied as one of the parameters, allowing the\napplication to keep track of the status of each operation.  The caller may\nsupply their own `clientToken` value (optional); if supplied, the value of\n`clientToken` will be used rather than the internally generated value.  Note\nthat this value should be of atomic type (i.e. numeric or string).  This\nfunction returns 'null' if an operation is already in progress.\n\n-------------------------------------------------------\n\u003ca name=\"publish\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#publish(topic, message, [options], [callback])\n\nIdentical to the [mqtt.Client#publish()](https://github.com/mqttjs/MQTT.js/blob/master/README.md#publish)\nmethod, with the restriction that the topic may not represent a Thing Shadow.\nThis method allows the user to publish messages to topics on the same connection\nused to access Thing Shadows.\n\n-------------------------------------------------------\n\u003ca name=\"subscribe\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#subscribe(topic, [options], [callback])\n\nIdentical to the [mqtt.Client#subscribe()](https://github.com/mqttjs/MQTT.js/blob/master/README.md#subscribe)\nmethod, with the restriction that the topic may not represent a Thing Shadow.\nThis method allows the user to subscribe to messages from topics on the same\nconnection used to access Thing Shadows.\n\n-------------------------------------------------------\n\u003ca name=\"unsubscribe\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#unsubscribe(topic, [callback])\n\nIdentical to the [mqtt.Client#unsubscribe()](https://github.com/mqttjs/MQTT.js/blob/master/README.md#unsubscribe)\nmethod, with the restriction that the topic may not represent a Thing Shadow.\nThis method allows the user to unsubscribe from topics on the same\nused to access Thing Shadows.\n\n-------------------------------------------------------\n\u003ca name=\"end\"\u003e\u003c/a\u003e\n### awsIot.thingShadow#end([force], [callback])\n\nInvokes the [mqtt.Client#end()](https://github.com/mqttjs/MQTT.js/blob/master/README.md#end)\nmethod on the MQTT connection owned by the `thingShadow` class.  The `force`\nand `callback` parameters are optional and identical in function to the\nparameters in the [mqtt.Client#end()](https://github.com/mqttjs/MQTT.js/blob/master/README.md#end) method.\n\n-------------------------------------------------------\n\u003ca name=\"jobs\"\u003e\u003c/a\u003e\n### awsIot.jobs(deviceOptions)\n\nThe `jobs` class wraps an instance of the `device` class with additional functionality to\nhandle job execution management through the AWS IoT Jobs platform. Arguments in `deviceOptions`\nare the same as those in the [device class](#device) and the `jobs` class supports all of the\nsame events and functions as the `device` class.\n\nThe `jobs` class also supports the following methods:\n\n-------------------------------------------------------\n\u003ca name=\"subscribeToJobs\"\u003e\u003c/a\u003e\n### awsIot.jobs#subscribeToJobs(thingName, [operationName], callback)\n\nSubscribes to job execution notifications for the thing named `thingName`. If\n`operationName` is specified then the callback will only be called when a job\nready for execution contains a property called `operation` in its job document with\na value matching `operationName`. If `operationName` is omitted then the callback\nwill be called for every job ready for execution that does not match another\n`subscribeToJobs` subscription.\n\n* `thingName` name of the Thing to receive job execution notifications\n* `operationName` optionally filter job execution notifications to jobs with a value\n         for the `operation` property that matches `operationName`\n* `callback` - function (err, job) callback for when a job execution is ready for processing or an error occurs\n        - `err` a subscription error or an error that occurs when client is disconnecting\n        - `job` an object that contains  [job](#job) execution information and functions for updating job execution status.\n\n-------------------------------------------------------\n\u003ca name=\"unsubscribeFromJobs\"\u003e\u003c/a\u003e\n### awsIot.jobs#unsubscribeFromJobs(thingName, [operationName], callback)\n\nUnsubscribes from job execution notifications for the thing named `thingName` having\noperations with a value of the given `operationName`. If `operationName` is omitted then\nthe default handler for the thing with the given name is unsubscribed.\n\n* `thingName` name of the Thing to cancel job execution notifications for\n* `operationName` optional name of previously subscribed operation names\n* `callback` - function (err) callback for when the unsubscribe operation completes\n\n-------------------------------------------------------\n\u003ca name=\"startJobNotifications\"\u003e\u003c/a\u003e\n### awsIot.jobs#startJobNotifications(thingName, [callback])\n\nCauses any existing queued job executions for the given thing to be published\nto the appropriate subscribeToJobs handler. Only needs to be called once per thing.\n\n* `thingName` name of the Thing to cancel job execution notifications for\n* `callback` - function (err) callback for when the startJobNotifications operation completes\n\n-------------------------------------------------------\n\u003ca name=\"job\"\u003e\u003c/a\u003e\n## job\nObject that contains job execution information and functions for updating job execution status.\n\n-------------------------------------------------------\n\u003ca name=\"document\"\u003e\u003c/a\u003e\n### job.document\nThe JSON document describing details of the job to be executed eg.\n```\n{\n    \"operation\": \"install\",\n    \"otherProperty\": \"value\",\n    ...\n}\n```\n-------------------------------------------------------\n\u003ca name=\"id\"\u003e\u003c/a\u003e\n### job.id\nReturns the job id.\n\n-------------------------------------------------------\n\u003ca name=\"operation\"\u003e\u003c/a\u003e\n### job.operation\nReturns the job operation from the job document. Eg. 'install', 'reboot', etc.\n\n-------------------------------------------------------\n\u003ca name=\"status\"\u003e\u003c/a\u003e\n### job.status\nReturns the current job status according to AWS Orchestra.\n```\n{\n    \"status\":\"IN_PROGRESS|QUEUED\",\n    \"statusDetails\": {\n        \"progress\":\"50%\"\n    }\n}\n```\n-------------------------------------------------------\n\u003ca name=\"inProgress\"\u003e\u003c/a\u003e\n### job.inProgress([statusDetails],[callback])\nUpdate the status of the job execution to be IN_PROGRESS for the thing associated with the job.\n\n* `statusDetails` optional document describing the status details of the in progress job e.g.\n```\n{\n    \"string\": \"string\",\n    \"progress\": \"50%\"\n}\n```\n* `callback` - function(err) optional callback for when the operation completes, err is null if no error occurred\n\n-------------------------------------------------------\n\u003ca name=\"failed\"\u003e\u003c/a\u003e\n### job.failed([statusDetails],[callback])\nUpdate the status of the job execution to be FAILED for the thing associated with the job.\n\n* `statusDetails` optional document describing the status details of the in progress job e.g.\n```\n{\n    \"string\": \"string\",\n    \"progress\": \"0%\"\n}\n```\n* `callback` - function(err) optional callback for when the operation completes, err is null if no error occurred\n\n-------------------------------------------------------\n\u003ca name=\"succeeded\"\u003e\u003c/a\u003e\n### job.succeeded([statusDetails],[callback])\nUpdate the status of the job execution to be SUCCESS for the thing associated with the job.\n\n* `statusDetails` optional document describing the status details of the in progress job e.g.\n```\n{\n    \"string\": \"string\",\n    \"progress\": \"100%\"\n}\n```\n* `callback` - function(err) optional callback for when the operation completes, err is null if no error occurred\n\n\u003ca name=\"connections\"\u003e\u003c/a\u003e\n## Connection Types\n\nThis SDK supports three types of connections to the AWS IoT platform:\n\n* MQTT over TLS with mutual certificate authentication using port 8883\n* MQTT over WebSocket/TLS with SigV4 authentication using port 443\n* MQTT over WebSocket/TLS using a custom authorization function to authenticate\n\nThe default connection type is MQTT over TLS with mutual certificate authentication; to\nconfigure a WebSocket/TLS connection, set the `protocol` option to `wss` when instantiating\nthe [awsIot.device()](#device) or [awsIot.thingShadow()](#thingShadow) classes. To use custom auth,\nset the `protocol` option to `wss-custom-auth`.\n\n\u003ca name=\"custom-auth\"\u003e\u003c/a\u003e\n### Custom Authorization Configuration\n\nTo use custom authorization, you must first set up an authorizer function in Lambda and register it\nwith IoT. Once you do, you will be able to authenticate using this function. There are two ways to use custom auth:\n* set the `customAuthHeaders` option to your headers object when instantiating the [awsIotDevice()](#device)\nor [awsIot.thingShadow()](#thingShadow) classes. The headers object is an object containing the header name\nand values as key-value pairs:\n\n```js\n    {\n        'X-Amz-CustomAuthorizer-Name': 'TestAuthorizer',\n        'X-Amz-CustomAuthorizer-Signature': 'signature',\n        'TestAuthorizerToken': 'token'\n    }\n```\n* set the `customAuthQueryString` option to your headers object when instantiating the [awsIotDevice()](#device) class. The query string is a string containing the values as key-value pairs:\n\n```js\n    '?X-Amz-CustomAuthorizer-Name=TestAuthorizer\u0026X-Amz-CustomAuthorizer-Signature=signature\u0026TestAuthorizerToken=token'\n```\n\n\n\u003ca name=\"programs\"\u003e\u003c/a\u003e\n## Example Programs\n\nThe 'examples' directory contains several programs which demonstrate usage\nof the AWS IoT APIs:\n\n* device-example.js: demonstrate simple MQTT publish and subscribe\noperations.\n\n* [echo-example.js](#echoExample): test Thing Shadow operation by echoing all delta\nstate updates to the update topic; used in conjunction with the [AWS\nIoT Console](https://console.aws.amazon.com/iot) to verify connectivity\nwith the AWS IoT platform.\n\n* thing-example.js: use a Thing Shadow to automatically synchronize\nstate between a simulated device and a control application.\n\n* thing-passthrough-example.js: demonstrate use of a Thing Shadow with\npasthrough of standard MQTT publish and subscribe messages.\n\n* temperature-control/temperature-control.js: an interactive device simulation which uses\nThing Shadows.\n\n* [jobs-example.js](#jobsExample): receive example job execution messages and update\njob execution status.\n\n* [jobs-agent.js](#jobsAgent): example agent to handle standard operations such as reboot,\nreport system status, and shutdown. It also handles installation of files including but not\nlimited to configuration files, program updates and security certificates. It also can install\nand launch other programs and manage their executions (start, stop and restart).\n\nThe example programs use command line parameters to set options.  To see\nthe available options, run the program and specify the '-h' option as\nfollows:\n\n```sh\nnode examples/\u003cEXAMPLE-PROGRAM\u003e -h\n```\n**NOTE:**  You have to use the certificate created in the same region as your host end point.\nYou will also need to use unique custom endpoint with '-H' command line option when connect examples to IoT cloud.\n\u003ca name=\"websockets\"\u003e\u003c/a\u003e\n### WebSocket Configuration\n\nThe example programs can be configured to use a WebSocket/TLS connection to\nthe AWS IoT platform by adding '--protocol=wss' to the command line to\noverride the default setting of 'mqtts'.\n\n```sh\n  -P, --protocol=PROTOCOL          connect using PROTOCOL (mqtts|wss)\n```\n\nWhen using a WebSocket/TLS connection, you have the following options to set credentials.\n#### Export variables to system environment\n\n```sh\nexport AWS_ACCESS_KEY_ID=[a valid AWS access key ID]\nexport AWS_SECRET_ACCESS_KEY=[a valid AWS secret access key]\n```\n#### Load IAM credentials from shared credential file\nThe default shared credential file is located in `~/.aws/credentials` for Linux\nusers and `%UserProfile%\\.aws\\credentials` for Windows users. This could be\nconfigured using AWS CLI [visit the AWS CLI home page.](https://aws.amazon.com/cli/)\nAlternatively, you could provide credential file in different path or another profile by specifying in the `awsIot.device(options)` .\n\nThe values of `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` must contain valid\nAWS Identity and Access Management (IAM) credentials.  For more information about AWS\nIAM, [visit the AWS IAM home page.](https://aws.amazon.com/iam/)\n\n\u003ca name=\"certificates\"\u003e\u003c/a\u003e\n### Certificate Configuration\n\nWhen not configured to use a WebSocket/TLS connection, the example programs\nrequire a client certificate and private key (created using either the [AWS\nIoT Console](https://console.aws.amazon.com/iot) or the\n[AWS IoT CLI](https://aws.amazon.com/cli/)) in order to authenticate with\nAWS IoT.  Each example program uses command line options to specify the\nnames and/or locations of certificates as follows:\n\n#### Specify a directory containing default-named certificates\n\n```sh\n  -f, --certificate-dir=DIR        look in DIR for certificates\n```\n\nThe --certificate-dir (-f) option will read all certificate and key files from the\ndirectory specified.  Default certificate/key file names are as follows:\n\n* certificate.pem.crt: your AWS IoT certificate\n* private.pem.key: the private key associated with your AWS IoT certificate\n* root-CA.crt: the root CA certificate [(available from the AWS documentation here)](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs)\n\n#### Specify certificate names and locations individually\n\n```sh\n  -k, --private-key=FILE           use FILE as private key\n  -c, --client-certificate=FILE    use FILE as client certificate\n  -a, --ca-certificate=FILE        use FILE as CA certificate\n```\n\nThe '-f' (certificate directory) option can be combined with these so that\nyou don't have to specify absolute pathnames for each file.\n\n\u003ca href=\"configurationFile\"\u003e\u003c/a\u003e\n#### Use a configuration file\n\nThe [AWS IoT Console](https://console.aws.amazon.com/iot) can generate JSON\nconfiguration data specifying the parameters required to connect a device\nto the AWS IoT Platform.  The JSON configuration data includes pathnames\nto certificates, the hostname and port number, etc...  The command line\noption '--configuration-file (-F)' is used when reading parameters from a\nconfiguration file.\n\n```sh\n  -F, --configuration-file=FILE    use FILE (JSON format) for configuration\n```\n\nThe configuration file is in JSON format, and may contain the following\nproperties:\n\n* host - the host name to connect to\n* port - the port number to use when connecting to the host (8883 for AWS IoT with client certificate)\n* clientId - the client ID to use when connecting\n* privateKey - file containing the private key\n* clientCert - file containing the client certificate\n* caCert - file containing the CA certificate\n* thingName - thing name to use\n\n##### Tips for using JSON configuration files\n* _The '-f' (certificate directory) and '-F' (configuration file) options\ncan be combined so that you don't have to use absolute pathnames in the\nconfiguration file._\n* _When using a configuration file to run any of the example programs other\nthan [echo-example.js](#echoExample), you **must** specify different client\nIDs for each process using the '-i' command line option._\n\n### device-example.js\n\ndevice-example.js is run as two processes which communicate with one\nanother via the AWS IoT platform using MQTT publish and subscribe.\nThe command line option '--test-mode (-t)' is used to set which role\neach process performs.  It's easiest to run each process in its own\nterminal window so that you can see the output generated by each.  Note\nthat in the following examples, all certificates are located in the\n~/certs directory and have the default names as specified in the\n[Certificate Configuration section](#certificates).\n\n#### _Terminal Window 1_\n```sh\nnode examples/device-example.js -f ~/certs --test-mode=1 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n```\n\n#### _Terminal Window 2_\n```sh\nnode examples/device-example.js -f ~/certs --test-mode=2 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n```\n\n### thing-example.js\nSimilar to device-example.js, thing-example.js is also run as two\nprocesses which communicate with one another via the AWS IoT platform.\nthing-example.js uses a Thing Shadow to synchronize state between the\ntwo processes, and the command line option '--test-mode (-t)' is used\nto set which role each process performs.  As with device-example.js,\nit's best to run each process in its own terminal window or on separate\nhosts.  In this example, the example programs are configured to use\nWebSocket/TLS connections to the AWS IoT platform as specified in the\n[WebSocket Configuration](#websockets).\n\n#### _Terminal Window 1_\n```sh\nnode examples/thing-example.js -P=wss --test-mode=1 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n```\n\n#### _Terminal Window 2_\n```sh\nnode examples/thing-example.js -P=wss --test-mode=2 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n```\n\n### thing-passthrough-example.js\nSimilar to thing-example.js, thing-passthrough-example.js is also run\nas two processes which communicate with one another via the AWS IoT platform.\nthing-passthrough-example.js uses a Thing Shadow to synchronize state\nfrom one process to another, and uses MQTT publish/subscribe to send\ninformation in the other direction.  The command line option '--test-mode (-t)'\nis used to set which role each process performs.  As with thing-example.js,\nit's best to run each process in its own terminal window.  Note\nthat in the following examples, all certificates are located in the\n~/certs directory and have the default names as specified in the\n[Certificate Configuration section](#certificates).\n\n#### _Terminal Window 1_\n```sh\nnode examples/thing-passthrough-example.js -f ~/certs --test-mode=1 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n```\n\n#### _Terminal Window 2_\n```sh\nnode examples/thing-passthrough-example.js -f ~/certs --test-mode=2 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n```\n\n\u003ca name=\"echoExample\"\u003e\u003c/a\u003e\n### echo-example.js\necho-example.js is used in conjunction with the\n[AWS IoT Console](https://console.aws.amazon.com/iot) to verify\nconnectivity with the AWS IoT platform and to perform interactive\nobservation of Thing Shadow operation.  In the following example, the\nprogram is run using the configuration file '../config.json', and\nthe certificates are located in the '~/certs' directory.  Here, the\n'-f' (certificate directory) and '-F' (configuration file) options\nare combined so that the configuration file doesn't need to contain\nabsolute pathnames.\n\n```sh\nnode examples/echo-example.js -F ../config.json -f ~/certs --thing-name testThing1\n```\n\n\u003ca name=\"temp-control\"\u003e\u003c/a\u003e\n### temperature-control.js\ntemperature-control.js is an interactive simulation which demonstrates\nhow Thing Shadows can be used to easily synchronize applications\nand internet-connected devices.\n\nLike thing-example.js, temperature-control.js runs in two\nseparate terminal windows and is configured via command-line options;\nin the following example, all certificates are located in the ~/certs\ndirectory and have the default names as specified in the\n[Certificate Configuration section](#certificates).  The process running\nwith '--test-mode=2' simulates an internet-connected temperature control\ndevice, and the process running with '--test-mode=1' simulates a mobile\napplication which is monitoring/controlling it.  The processes may be\nrun on different hosts if desired.\n\n#### _Installing Dependencies_\ntemperature-control.js\nuses the [blessed.js](https://github.com/chjj/blessed) and [blessed-contrib.js](https://github.com/yaronn/blessed-contrib) libraries to provide an\ninteractive terminal interface; it looks best on an 80x25 terminal with a\nblack background and white or green text and requires UTF-8 character\nencoding.  You'll need to install these libraries in the examples/temperature-control\ndirectory as follows:\n\n```sh\ncd examples/temperature-control\nnpm install\n```\n\n#### _Running the Simulation - Terminal Window 1_\n```sh\nnode examples/temperature-control/temperature-control.js -f ~/certs --test-mode=1 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n```\n![temperature-control.js, 'mobile application' mode](https://s3.amazonaws.com/aws-iot-device-sdk-js-supplemental/images/temperature-control-mobile-app-mode.png)\n\n#### _Running the Simulation - Terminal Window 2_\n```sh\nnode examples/temperature-control/temperature-control.js -f ~/certs --test-mode=2 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n```\n![temperature-control.js, 'device' mode](https://s3.amazonaws.com/aws-iot-device-sdk-js-supplemental/images/temperature-control-device-mode.png)\n\n#### _Using the simulation_\nThe simulated temperature control device has two controls; _Setpoint_ and\n_Status_.  _Status_ controls whether or not the device is active, and\n_Setpoint_ controls the interior temperature the device will attempt to\nachieve.  In addition, the device reports the current interior and exterior\ntemperatures as well as its operating state (_heating_, _cooling_, or\n_stopped_).\n\nTwo Thing Shadows are used to connect the simulated device and mobile\napplication; one contains the controls and the other contains the\nmeasured temperatures and operating state.  Both processes can update the\ncontrols, but only the device can update the measured temperatures and\nthe operating state.\n\nControlling the simulation is done using the \u003ckbd\u003eup\u003c/kbd\u003e,\n\u003ckbd\u003edown\u003c/kbd\u003e, \u003ckbd\u003eleft\u003c/kbd\u003e, \u003ckbd\u003eright\u003c/kbd\u003e, and\n\u003ckbd\u003eEnter\u003c/kbd\u003e keys as follows:\n\n* \u003ckbd\u003eup\u003c/kbd\u003e increase the Setpoint\n* \u003ckbd\u003edown\u003c/kbd\u003e decrease the Setpoint\n* \u003ckbd\u003eleft\u003c/kbd\u003e move left on the menu bar\n* \u003ckbd\u003eright\u003c/kbd\u003e move right on the menu bar\n* \u003ckbd\u003eEnter\u003c/kbd\u003e select the current menu option\n\n##### Operating State\n\nThe operating state of the device is indicated by the color of the\nInterior temperature field as follows:\n\n* Red: _heating_\n* Cyan: _cooling_\n* White: _stopped_\n\nThe following example shows the temperature control simulation in 'device' mode\nwhile the operating state is 'heating'.\n\n![temperature-control.js, 'device' mode, 'heating' operating state](https://s3.amazonaws.com/aws-iot-device-sdk-js-supplemental/images/temperature-control-device-mode-heating.png)\n\n##### Log\n\nThe log window displays events of interest, e.g. network connectivity,\n_Status_ toggles, re-synchronization with the Thing Shadow, etc...\n\n##### Menu Options\n\n* Mode: Toggle the device _Status_.  _Status_ can be controlled from both\nthe simulated device and the mobile application.\n* Network: Toggle the network connectivity of the device or mobile\napplication; this can be used to observe how both sides re-synchronize\nwhen connectivity is restored.\n\nIn this example, the mobile application is disconnected from the network.  Although it has\nrequested that the Setpoint be lowered to 58 degrees, the command can't be sent to\nthe device as there is no network connectivity, so the operating state still shows as\n'stopped'.  When the mobile application is reconnected to the network, it will attempt\nto update the Thing Shadow for the device's controls; if no control changes have been\nmade on the device side during the disconnection period, the device will synchronize to\nthe mobile application's requested state; otherwise, the mobile application will re-\nsynchronize to the device's current state.\n\n![temperature-control.js, 'mobile application' mode, network disconnected](https://s3.amazonaws.com/aws-iot-device-sdk-js-supplemental/images/temperature-control-mobile-app-mode-network-disconnected.png)\n\n##### Exiting the Simulation\n\nThe simulation can be exited at any time by pressing \u003ckbd\u003eq\u003c/kbd\u003e,\n\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003ec\u003c/kbd\u003e, or by selecting 'exit' on the menu bar.\n\n\u003ca name=\"jobsExample\"\u003e\u003c/a\u003e\n### jobs-example.js\njobs-example.js, like the [echo-example.js](#echoExample) can receive messages via the [AWS IoT Console](https://console.aws.amazon.com/iot)\nto verify connectivity with the AWS IoT platform. But it can also receive and process job\nexecutions initiated through the AWS IoT device jobs management platform. See the AWS IoT\nJobs documentation [here](https://aws.amazon.com/documentation/iot/) for more information on creating and deploying jobs.\n\n#### _Running the jobs-example_\n```sh\nnode examples/jobs-example.js -f ~/certs -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com -T thingName\n```\n\n\n\u003ca name=\"jobsAgent\"\u003e\u003c/a\u003e\n### jobs-agent.js\njobs-agent.js can be run on a device as-is or it can be modified to suit specific use cases.\nExample job documents are provided below. For more information see the AWS IoT connected device\nmanagement documentation [here](https://aws.amazon.com/documentation/iot/).\n#### _Running the jobs-agent_\n```sh\nnode examples/jobs-agent.js -f ~/certs -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com -T agentThingName\n```\n#### _Using the jobs-agent_\n##### systemStatus operation\nThe jobs-agent will respond to the AWS IoT jobs management platform with system status\ninformation when it receives a job execution notification with a job document that looks like this:\n```\n {\n  \"operation\": \"systemStatus\"\n }\n```\n##### reboot operation\nWhen the jobs-agent receives a reboot job document it will attempt to reboot the device it is\nrunning on while sending updates on its progress to the AWS IoT jobs management platform.\nAfter the reboot the job execution status will be marked as IN_PROGRESS until the jobs-agent\nis also restarted at which point the status will be updated to SUCCESS. To avoid manual steps\nduring reboot it is suggested that device be configured to automatically start the jobs-agent\nat device startup time. Job document format:\n```\n {\n  \"operation\": \"reboot\"\n }\n```\n##### shutdown operation\nWhen the jobs-agent receives a shutdown job document it will attempt to shutdown the device.\n```\n {\n  \"operation\": \"shutdown\"\n }\n```\n##### install operation\nWhen the jobs-agent receives an install job document it will attempt to install the files specified\nin the job document. An install job document should follow this general format.\n```\n {\n  \"operation\": \"install\",\n  \"packageName\": \"uniquePackageName\",\n  \"workingDirectory\": \"../jobs-example-directory\",\n  \"launchCommand\": \"node jobs-example.js -f ~/certs -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com -T thingName\",\n  \"autoStart\": \"true\",\n  \"files\": [\n    {\n      \"fileName\": \"jobs-example.js\",\n      \"fileVersion\": \"1.0.2.10\",\n      \"fileSource\": {\n        \"url\": \"https://some-bucket.s3.amazonaws.com/jobs-example.js\"\n      },\n      \"checksum\": {\n        \"inline\": {\n          \"value\": \"9569257356cfc5c7b2b849e5f58b5d287f183e08627743498d9bd52801a2fbe4\"\n        },\n        \"hashAlgorithm\": \"SHA256\"\n      }\n    },\n    {\n      \"fileName\": \"config.json\",\n      \"fileSource\": {\n        \"url\": \"https://some-bucket.s3.amazonaws.com/config.json\"\n      }\n    }\n  ]\n}\n```\n* `packageName`: Each install operation must have a unique package name. If the packageName\nmatches a previous install operation then the new install operation overwrites the previous one.\n* `workingDirectory`: Optional property for working directory\n* `launchCommand`: Optional property for launching an application/package. If omitted copy files only.\n* `autoStart`: If set to true then agent will execute launch command when agent starts up.\n* `files`: Specifies files to be installed\n  * `fileName`: Name of file as written to file system\n  * `fileSource.url`: Location of file to be downloaded from\n  * `checksum`: Optional file checksum\n    * `inline.value`: Checksum value\n    * `hashAlgorithm`: Checksum hash algorithm used\n##### start operation\nWhen the jobs-agent receives a start job document it will attempt to startup the specified package.\n```\n {\n  \"operation\": \"start\",\n  \"packageName\": \"somePackageName\"\n }\n```\n##### stop operation\nWhen the jobs-agent receives a stop job document it will attempt to stop the specified package.\n```\n {\n  \"operation\": \"stop\",\n  \"packageName\": \"somePackageName\"\n }\n```\n##### restart operation\nWhen the jobs-agent receives a restart job document it will attempt to restart the specified package.\n```\n {\n  \"operation\": \"restart\",\n  \"packageName\": \"somePackageName\"\n }\n```\n\n\u003ca name=\"browser\"\u003e\u003c/a\u003e\n## Browser Applications\nThis SDK can be packaged to run in a browser using [browserify](http://browserify.org/) or [webpack](https://webpack.js.org/), and includes helper scripts and example application code to help you get started writing browser applications that use AWS IoT.\n\n### Background\nBrowser applications connect to AWS IoT using [MQTT over the Secure WebSocket Protocol](http://docs.aws.amazon.com/iot/latest/developerguide/protocols.html).  There are some important differences between Node.js and browser environments, so a few adjustments are necessary when using this SDK in a browser application.\n\nWhen running in a browser environment, the SDK doesn't have access to the filesystem or process environment variables, so these can't be used to store credentials.  While it might be possible for an application to prompt the user for IAM credentials, the [Amazon Cognito Identity Service](https://aws.amazon.com/cognito/) provides a more user-friendly way to retrieve credentials which can be used to access AWS IoT.  The [temperature-monitor](#temperature-monitor-browser-example) browser example application illustrates this use case.\n\n### Using SDK with browserify\n#### Installing browserify\nThis SDK could also work with web applications using `browserify`. First, you'll need to make sure that `browserify` is installed.  The following instructions and the scripts in this package assume that it is installed globally, as with:\n\n```sh\nnpm install -g browserify\n```\n\n#### Browser Application Utility\nThis SDK includes a utility script called `scripts/browserize.sh`.  This script can create a browser bundle containing both the [AWS SDK for JavaScript](https://aws.amazon.com/sdk-for-browser/) and this SDK, or you can use it to create application bundles for browser applications,   like the ones under the `examples/browser` directory.  For Windows user who does not want to use bash shell, the SDK also includes batch file `windows-browserize.bat` which does the same job as `browserize.sh` but able to run in Windows CMD. To create the combined AWS SDK browser    bundle, run this command in the SDK's top-level directory:\n\n```sh\nnpm run-script browserize\n```\nThis command will create a browser bundle in `browser/aws-iot-sdk-browser-bundle.js`.  The browser bundle makes both the `aws-sdk` and `aws-iot-device-sdk` modules available so that you can `require` them from your browserified application bundle.\n\n**NOTE**: For Windows user who running scripts in CMD, since batch script file does not work well with NPM package script, Windows user could just call script directly to replace `npm run-script browserize`. This also applies for example applications demonstrated below.\n\n```sh\n.\\scripts\\windows-browserize.bat\n```\n\n#### Creating Application Bundles\nYou can also use the `scripts/browserize.sh` script to browserify your own applications and use them with the AWS SDK browser bundle.  For example, to prepare the [temperature-monitor](#temperature-monitor-browser-example) browser example application for use, run this command in the SDK's top-level directory:\n\n```sh\nnpm run-script browserize examples/browser/temperature-monitor/index.js\n```\n\nThis command does two things.  First, it creates an application bundle from `examples/browser/temperature-monitor/index.js` and places it in `examples/browser/temperature-monitor/bundle.js`.  Second, it copies the `browser/aws-iot-sdk-browser-bundle.js` into your application's directory where it can be used, e.g.:\n\n```html\n\u003cscript src=\"aws-iot-sdk-browser-bundle.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"bundle.js\"\u003e\u003c/script\u003e\n```\n\n\u003ca name=\"temperature-monitor-browser-example\"\u003e\u003c/a\u003e\n#### Temperature Monitor Browser Example Application\nThis SDK includes a companion browser application to the [Temperature Control Example Application](#temp-control).  The browser application allows you to monitor the status of the simulated temperature control device.\n\n1. Follow the instructions to install the [Temperature Control Example Application](#temp-control)\n\n1. In order for the browser application to be able to authenticate and connect to AWS IoT, you'll need to configure a Cognito Identity Pool.  In the [Amazon Cognito console](https://console.aws.amazon.com/cognito/), use Amazon Cognito to create a new identity pool, and allow unauthenticated identities to connect.  Obtain the `PoolID` constant. Make sure that the policy attached to the [unauthenticated role](https://console.aws.amazon.com/iam/home?#roles) has permissions to access the required AWS IoT APIs.  More information about AWS IAM roles and policies can be found [here](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html).\n\n1. Edit `examples/browser/temperature-monitor/aws-configuration.js`, and replace the values of `poolId` and `region` with strings containing the ID of the Cognito Identity Pool and your AWS region (e.g., `'us-east-1'`) from the previous step.\n\n1. Create the application browser bundle by executing the following command in the top-level directory of the SDK:\n\n    ```sh\n    npm run-script browserize examples/browser/temperature-monitor/index.js\n    ```\n1. Start an instance of the device simulation using:\n\n    ```sh\n    node examples/temperature-control/temperature-control.js -f ~/certs --test-mode=2 -H \u003cPREFIX\u003e.iot.\u003cREGION\u003e.amazonaws.com\n    ```\n  _NOTE_: _Although the above example shows connecting using a certificate/private key set, you can use any of the command line options described in the [Example Programs Section](#programs)._\n\n1. Open `examples/browser/temperature-monitor/index.html` in your web browser.  It should connect to AWS IoT and began displaying the status of the simulated temperature control device you started in the previous step.  If you change the device's settings, the browser window should update and display the latest status values.\n\n\u003ca name=\"lifecycle-event-monitor-browser-example\"\u003e\u003c/a\u003e\n#### Lifecycle Event Monitor Browser Example Application\nThis SDK includes a browser application which demonstrates the functionality of [AWS IoT lifecycle events](http://docs.aws.amazon.com/iot/latest/developerguide/life-cycle-events.html).  AWS IoT generates lifecycle events whenever clients connect or disconnect; applications can monitor these and take action when clients connect or disconnect from AWS IoT.  Follow these instructions to run the application:\n\n1. In order for the browser application to be able to authenticate and connect to AWS IoT, you'll need to configure a Cognito Identity Pool.  In the [Amazon Cognito console](https://console.aws.amazon.com/cognito/), use Amazon Cognito to create a new identity pool, and allow unauthenticated identities to connect.  Obtain the `PoolID` constant. Make sure that the policy attached to the [unauthenticated role](https://console.aws.amazon.com/iam/home?#roles) has permissions to access the required AWS IoT APIs.  More information about AWS IAM roles and policies can be found [here](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html).\n\n1. Edit `examples/browser/lifecycle/aws-configuration.js`, and replace the values of `poolId` and `region` with strings containing the ID of the Cognito Identity Pool and your AWS region (e.g., `'us-east-1'`) from the previous step.\n1. Create the application browser bundle by executing the following command in the top-level directory of the SDK:\n\n    ```sh\n    npm run-script browserize examples/browser/lifecycle/index.js\n    ```\n\n1. Open `examples/browser/lifecycle/index.html` in your web browser.  After connecting to AWS IoT, it should display 'connected clients'.\n1. Start programs which connect to AWS IoT (e.g., [the example programs in this package](#programs)).  Make sure that these programs are connecting to the same AWS region that your Cognito Identity Pool was created in.  The browser application will display a green box containing the client ID of each client which connects; when the client disconnects, the box will disappear.\n1. If a DynamoDB table named `LifecycleEvents` exists in your account and has a primary key named `clientId`, the lifecycle event browser monitor browser application will display the client ID contained in each row.  By updating this table using an [AWS IoT rule](http://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) triggered by [lifecycle events](http://docs.aws.amazon.com/iot/latest/developerguide/life-cycle-events.html), you can maintain a persistent list of all of the currently connected clients within your account.\n\n\u003ca name=\"mqtt-explorer-browser-example\"\u003e\u003c/a\u003e\n#### MQTT Explorer Browser Example Application\nThis SDK includes a browser application which implements a simple interactive MQTT client.  You can use this application to subscribe to a topic and view the messages that arrive on it, or to publish to a topic.  Follow these instructions to run the application:\n\n1. In order for the browser application to be able to authenticate and connect to AWS IoT, you'll need to configure a Cognito Identity Pool.  In the [Amazon Cognito console](https://console.aws.amazon.com/cognito/), use Amazon Cognito to create a new identity pool, and allow unauthenticated identities to connect.  Obtain the `PoolID` constant. Make sure that the policy attached to the [unauthenticated role](https://console.aws.amazon.com/iam/home?#roles) has permissions to access the required AWS IoT APIs.  More information about AWS IAM roles and policies can be found [here](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html).\n\n1. Edit `examples/browser/mqtt-explorer/aws-configuration.js`, and replace the values of `poolId` and `region` with strings containing the ID of the Cognito Identity Pool and your AWS region (e.g., `'us-east-1'`) from the previous step.\n1. Create the application browser bundle by executing the following command in the top-level directory of the SDK:\n\n    ```sh\n    npm run-script browserize examples/browser/mqtt-explorer/index.js\n    ```\n\n1. Open `examples/browser/mqtt-explorer/index.html` in your web browser.  After connecting to AWS IoT, it should display input fields allowing you to subscribe or publish to a topic.  By subscribing to '#', for example, you will be able to monitor all traffic within your AWS account as allowed by the policy associated with the unauthenticated role of your Cognito Identity Pool.\n\n#### Reducing Browser Bundle Size\nAfter your application development is complete, you will probably want to reduce the size of the browser bundle.  There are a couple of easy techniques to do this, and by combining both of them you can create much smaller browser bundles.\n\n##### Eliminate unused features from the AWS SDK\n\n1. The [AWS SDK for JavaScript](https://github.com/aws/aws-sdk-js) allows you to install only the features you use in your application.  In order to use this feature when preparing a browser bundle, first you'll need to remove any existing bundle that you've already created:\n\n    ```sh\n    rm browser/aws-iot-sdk-browser-bundle.js\n    ```\n\n2. Define the AWS features your application uses as a comma-separated list in the `AWS_SERVICES` environment variable.  For example, the [MQTT Explorer example](#mqtt-explorer-browser-example) uses only AWS Cognito Identity, so to create a bundle containing only this feature, do:\n\n    ```sh\n    export AWS_SERVICES=cognitoidentity\n    ```\n    For a list of the AWS SDK feature names, refer to the [_features subdirectory_ of the AWS SDK for JavaScript](https://github.com/aws/aws-sdk-js/tree/master/features).  As another example, if your application uses Cognito Identity, DynamoDB, S3, and SQS, you would do:\n\n    ```sh\n    export AWS_SERVICES=cognitoidentity,dynamodb,s3,sqs\n    ```\n\n3. Create the browser app and bundle, e.g. for the [MQTT Explorer example](#mqtt-explorer-browser-example), do:\n\n    ```sh\n    npm run-script browserize examples/browser/mqtt-explorer/index.js\n    ```\n\n#### Uglify the bundle source\n\n[Uglify](https://www.npmjs.com/package/uglify) is an npm utility for minimizing the size of JavaScript source files.  To use it, first install it as a global npm package:\n\n```sh\nnpm install -g uglify\n```\n\nOnce installed, you can use it to reduce the bundle size:\n\n```sh\nuglify -s ./browser/aws-iot-sdk-browser-bundle.js -o ./browser/aws-iot-sdk-browser-bundle-min.js\n```\nAfter you've created the minimized bundle, you'll need to make sure that your application loads this version rather than the non-minimized version, e.g:\n\n```html\n\u003cscript src=\"aws-iot-sdk-browser-bundle-min.js\"\u003e\u003c/script\u003e\n```\n##### Optimization results\nBy using both of the above techniques for the [MQTT Explorer example](#mqtt-explorer-browser-example), the bundle size can be reduced from 2.4MB to 615KB.\n\n\u003ca name=\"troubleshooting\"\u003e\u003c/a\u003e\n\n### Using SDK with webpack\nIn order to work with webpack, you have to create a webpack package. You can put your file dependencies in `entry.js` and output it as `bundle.js`. An example is provided in the location `./examples/browser/mqtt-webpack`\n\n```sh\ncd ./examples/browser/mqtt-webpack\nnpm install\n./node_modules/.bin/webpack --config webpack.config.js\n```\nThe `index.html` will load the output file `bundle.js` and execute functions defined in `entry.js`. This duplicates the example of mqtt-explore above which loaded SDK into web browser using browserify.\n\n## Troubleshooting\n\nIf you have problems connecting to the AWS IoT Platform when using this SDK or\nrunning the example programs, there are a few things to check:\n\n* _Region Mismatch_:  You have to use the certificate created in the same\nregion as your host end point.\n* _Duplicate Client IDs_:  Within your AWS account, the AWS IoT platform\nwill only allow one connection per client ID.  Many of the example programs\nrun as two processes which communicate with one another.  If you don't\nspecify a client ID, the example programs will generate random client IDs,\nbut if you are using a [JSON configuration file](#configurationFile), you'll\nneed to explictly specify client IDs for both programs using the '-i' command\nline option.\n* _Invalid NPM Version_:  To run the browserize.sh script which prepares the browser example applications, you'll need to use npm version 3.  This is because browserize.sh expects package dependencies to be handled using the npm version 3 strategy, which is [different than the strategy used in npm version 2](https://docs.npmjs.com/how-npm-works/npm3).  If you're having trouble running the browser application examples, make sure that you're using npm version 3.  You can check your npm version with `npm -v`.\n\n\u003ca name=\"unittests\"\u003e\u003c/a\u003e\n## Unit Tests\n\nThis package includes unit tests which can be run as follows:\n\n```sh\nnpm test\n```\n\nRunning the unit tests will also generate code coverage data in the 'reports'\ndirectory.\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n## License\n\nThis SDK is distributed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0), see LICENSE.txt and NOTICE.txt for more information.\n\u003ca name=\"suport\"\u003e\u003c/a\u003e\n## Support\nIf you have technical questions about AWS IoT Device SDK, use the [AWS IoT Forum](https://forums.aws.amazon.com/forum.jspa?forumID=210).\nFor any other questions on AWS IoT, contact [AWS Support](https://aws.amazon.com/contact-us).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-iot-device-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Faws-iot-device-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-iot-device-sdk-js/lists"}