iot-utilities

Instructions and utilities for using the Control Solutions IOT features.

Note: In order to use these utilities, you will need the appropriate credentials for accessing the service. This package is primarily a development/test tool, so you probably already know this.

The package has been tested with the version of NodeJS contained in the .nvmrc file. The package is intended to work under similar versions of NodeJS and in other Javascript environment, but you should add validation tests if you need that.

Installation

The tool requires a compatible NodeJS installation. The version used for development is stored in the .nvmrc file, though it's likely that other versions within reason will work. With an appropriate NodeJS version active,

For local installation: Clone the github repo, and navigate to the folder using the terminal/command prompt npm i

Commands

Simulation Listener

The listener acts as an MQTT client, and subscribes to the relevant messages for all devices. To use the listener, you will need credentials with appropriate access to AWS. These credentials should be stored in the ./certs/client folder, and be named cert.pem.crt and private.pem.key.

You will also need a file called sim.json in the project folder, which contains the client key:

{
  //...

  "client": {
    "hostName": "{your AWS endpoint}",
    "port": 8883
  }
}

With that configuration in place, you will be ready to run the listener. Use the npm run listen command, and you should successfully connect to the MQTT server, and display incoming messages from any device.

Simulator

The Simulator pretends to be one or more remote devices, and sends MQTT messages to the server.

In order to run the simulation, you will need a file called sim.json in the project folder. This file contains the instructions as to how the simulator should behave under the devices key. An example sim.json file is as follows:

{
  "devices": [
    {
      "id": "MyDevice",
      "serial": "S1715397",
      "ee": "./config/SWEE000282A.ee"
    }
  ],
  // ...
}

For each device there should be a folder in the ./certs folder containing the appropriate credentials in a subfolder named with the ThingId. You will need the private key, called private.pem.key and certificate, cert.pem.crt for each Thing you want to simulate. In this case, to simulate a Thing called MyDevice, you will create a folder in the ./certs folder called MyDevice. In that folder you will put cert.pem.crt and private.pem.key.

For each device, the ee key specifies the path to a .ee file containing the controller's configuration. As a suggestion, these .ee files could be stored in a folder called config and could correspond to specific deployed controller configurations.

The serial key in the device definition is used along with the device .ee file to identify that particular device.

To run the simulation, use the `npm run sim' command. The terminal will output the messages sent to the MQTT broker.

Development

When modifying this package, the recommended editor is Visual Studio Code with TypeScript and ESLint support.

Debug logging is provided by the debug npm package. For instance, to enable debugging of the SimCart (simulator), you would set the DEBUG environment variable to iot:SimCart. On Mac or Linux this would be like export DEBUG=iot:SimCart. Keep in mind setting this environment variable is platform-specific. You might also set it programmatically in ./src/cli.ts for convenience.

When coding wordart, eg: // ┌─┐┌┬┐┬ ┬┌─┐┬─┐ // │ │ │ ├─┤├┤ ├┬┘ // └─┘ ┴ ┴ ┴└─┘┴└─ was done using the kit NPM package exclaim command. npm install -g kit then `kit exclaim --font='Calvin S' "Hello World"

Testing

mocha-based tests are provided and must be updated to reflect any code changes.

To run all the tests, use the npm test command.

To selectively run tests, use a command like ts-mocha test