Have ideas to improve npm?Join in the discussion! »

    aws-mqtt

    1.0.0 • Public • Published

    AWS IoT MQTT client

    NPM

    This module implements a client to connect to AWS IoT MQTT broker using WebSockets. It can be used in a browser as well as in Node.js environment.

    The main class exported from this package is a subclass of MqttClient and exposes the same API. What this package adds is the following:

    • AWS IoT broker url signing logic
    • Refreshing of credentials and re-signing url on re-connects
    • Custom WebSocket stream implementation that is more efficient then out of the box mqtt.js/websocket-stream combo (this package handles corking/uncorking of the stream, whereas websocket-stream sends a separate frame per each byte written)
    • Validated connection options that work with AWS MQTT broker
    • Pins versions of mqtt and aws-signature-v4 to a known tested combo, in the past lax version constraints broke this package
    • NodeClient that works in node (need to install ws separately)

    Motivation

    Up until now an implementation of a realtime in-browser application required the use of either an external service (e.g Pusher, PubNub) or roll your own servers (e.g. using socket.io) that maintain connections with browsers and need scaling to respond to the changes in number of active users. Using AWS IoT MQTT broker as the realtime backend provides a low cost scalable service for your application.

    Disclaimer

    AWS documentation does not explicitly promote the use of IoT MQTT broker as a general purpose pub/sub broker. Only the use case of IoT devices communication is explicitly described. While technically there is nothing preventing general purpose browsers and servers connecting to the broker (such as implemented by this library), AWS may change its terms of service or implement some broker constraints to prevent such use case. Use at your own risk.

    Usage

    npm install aws-sdk aws-mqtt --save

    when using in a node environment (not browser), install WebSocket implementation, e.g. ws

    npm install ws --save

    In Browser

    The example below assumes the use of Babel/Webpack. aws-sdk now officially supports bundling with webpack, with a few things to know.

    import AWS from 'aws-sdk/global'
    import AWSMqttClient from 'aws-mqtt'
    AWS.config.region = 'us-east-1' // your region
    AWS.config.credentials = ... // See AWS Setup and Security below 
     
    const client = new AWSMqttClient({
      region: AWS.config.region,
      credentials: AWS.config.credentials,
      endpoint: '...iot.us-east-1.amazonaws.com', // NOTE: get this value with `aws iot describe-endpoint`
      expires: 600, // Sign url with expiration of 600 seconds
      clientId: 'mqtt-client-' + (Math.floor((Math.random() * 100000) + 1)), // clientId to register with MQTT broker. Need to be unique per client
      will: {
          topic: 'WillMsg',
          payload: 'Connection Closed abnormally..!',
          qos: 0,
          retain: false
      } 
    })
     
    client.on('connect', () => {
      client.subscribe('/myTopic')
    })
    client.on('message', (topic, message) => {
      console.log(topic, message)
    })
    client.on('close', () => {
      // ...
    })
    client.on('offline', () => {
      // ...
    })

    The client object in the above example is a subclass of MqttClient class from MQTT.js. For events and API see the docs.

    In Node.js

    The same usage as in browser, but require a different module - require('aws-mqtt/lib/NodeClient') instead of require('aws-mqtt'). ws also needs to be installed.

    Install ws if you don't have it installed yet

    npm install ws@^6.0.0
    // in node v6.x
    const AWS = require('aws-sdk')
    const AWSMqttClient = require('aws-mqtt/lib/NodeClient')
     
    AWS.config.region = 'us-east-1' 
    AWS.config.credentials = ... 
     
    const client = new AWSMqttClient({
      region: AWS.config.region,
      credentials: AWS.config.credentials,
      endpoint: '...iot.us-east-1.amazonaws.com', // NOTE: get this value with `aws iot describe-endpoint`
      clientId: 'mqtt-client-' + (Math.floor((Math.random() * 100000) + 1)), // clientId to register with MQTT broker. Need to be unique per client
      will: {
        topic: 'WillMsg',
        payload: 'Connection Closed abnormally..!',
        qos: 0,
        retain: false
      } 
    })
     

    In AWS Lambda functions

    Creating a NodeClient instance will set up internal timers and the node.js process will not exit until you call client.end(). This is fine if you are developing a long running server app that subscribes and/or publishes messages. For ephemeral functions, such as AWS Lambda, this approach will cause the function invocation to timeout.

    To publish a single message to a topic and disconnect - require publishMessage and use it like this:

    const AWS = require('aws-sdk')
    const publishMessage = require('aws-mqtt/lib/publishMessage')
     
    AWS.config.region = 'us-east-1' 
    AWS.config.credentials = ... 
     
    const config = {
      region: AWS.config.region,
      credentials: AWS.config.credentials,
      endpoint: '...iot.us-east-1.amazonaws.com' 
    }
     
    // publish returns a Promise
    publishMessage(config, '/myTopic', 'my message').then(console.log, console.error)

    Using MQTT will

    The will option will send a message by the broker automatically when the client disconnect badly. For more information of how to use it, look the mqtt.Client option on the MQTT.js documentation.

    AWS Setup and Security

    There is an example CloudFormation template and deploy script to simplify creation of Cognito Identity Pool.

    First, the required primer on AWS JavaScript Configuration. There are multiple ways to configure AWS based on the use case. For example for usage in a web browser by un-authenticated users, the best practice is to use Cognito Identity. When Cognito Identity Pool is created, it's assigned an IAM role that is used by un-authenticated users. That role needs to be given minimum required permissions (principle of least privilege). In the case of IoT MQTT broker, that means restricting un-authenticated user to subscribe to specific topics or publish to specific topics. Read more on AWS IoT Policies.

    An example of policy statement for an un-authenticated user (tweak as you see fit, note the use of iot:ClientId to dynamically limit the topics):

    {
        "Version": "2012-10-17",
        "Statement": [{
            "Effect": "Allow",
            "Action": ["iot:Connect"],
            "Resource": ["*"]
        }, {
            "Effect": "Allow",
            "Action":["iot:Subscribe"],
            "Resource": ["arn:aws:iot:us-east-1:<...>:topic/foo/bar"]
        }, {
            "Effect": "Allow",
            "Action": ["iot:Publish"],
            "Resource": ["arn:aws:iot:us-east-1:<...>:topic/foo/bar/${iot:ClientId}"]
        }]
    }

    Quick example using Cognito Identity un-authenticated users approach

    Create a Cognito Identity Pool in AWS (under Cognito Federated Identities)

    Image of Step1

    Accept default create IAM roles for authenticated and un-authenticated identities

    Image of Step2

    Go to IAM Roles and find the role for the un-authenticated role created for the identity pool

    Image of Step3

    Edit the inline policy to allow access to connect, subscribe and publish to IoT message broker. Note: the policy shown below is very open for an un-authenticated user, you can start with that to make sure things work, and then tighten it up.

    Image of Step4

    Get the Identity Pool ID you just created:

    aws cognito-identity list-identity-pools --max-results=5

    Use the Identity Pool ID in you app credentials:

    AWS.config.region = '...' // e.g us-west-2
    AWS.config.credentials = new AWS.CognitoIdentityCredentials({
      IdentityPoolId: '...'
    })

    Pass AWS.config.credentials to AWSMqtt connect methods.

    Examples

    In ./examples folder there are two example projects:

    • chat - The minimalistic example of using AWSMqtt in browser with Webpack
    • node-publisher - contains two examples
      1. timePublisher.js - how to connect to AWS IoT MQTT broker, subscribe and publish messages
      2. publish.js - how to publish one message and disconnect, e.g. node publish.js "/chat" Hello

    Before running any of the examples, copy examples/config.example.js to examples/config.js and fill in your values.

    Frequently asked questions

    Memory leak

    If your browser is reporting a memory leak, this could be caused by your cleanup strategy of event listeners. By default, most browsers allow 10 event listeners to listen to a single emitting event from a singular source. So, if you have more than 10 listeners for an event (ie client.on('message'), where message is the event), then you will get this error. If your client is disconnecting, or reconnecting, we recommend that you cleanup the old event listeners with client.removeAllListeners('EVENT') (where EVENT could be message, or other), or client.removeListener('EVENT', fn).

    Frequently disconnecting

    There are a few reasons why your client may be disconnecting unexpectedly. Here are a few cases:

    • clientId in the connect configuration MUST be unique across each client. If clients A and B use the same clientId, then when B tries to connect, client A will get disconnected (by the broker). Because this package attempts to reconnect you when disconnected, client A will reconnect, which will cause client B to disconnect. And an infinite cycle ensues. Note that clientId, if not passed in the config, will use 'mqtt-client-' + (Math.floor((Math.random() * 100000) + 1)) to generate a "unique" clientId. If you are passing in clientId to override the default, make sure it is unique.
    • Permissions with AWS IAM could be set up incorrectly.

    Install

    npm i aws-mqtt

    DownloadsWeekly Downloads

    1,068

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    266 kB

    Total Files

    36

    Last publish

    Collaborators

    • avatar