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

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

Configuration

A file called sim.json must exist in the working folder. This file contains configuration variables, as well as paths to other configuration files. The contents of the file are documented by the SimConfig interface. In summary the file contains

• The connection information to the MQTT server under the 'client' key
• Information about all devices to be simulated under the 'devices' key
• A path to the config folder, which contains additional files needed for certificates, simulated device configuration, etc

A simple example of a sim.json file would be:

{
  "CONFIG_DIR": "./config",
  "devices": [
    {
      "id": "<the unique ID for the device",
      "ee": "<path to motor controller configuration file",
      "serial": "<specify the serial number of the simulated motor controller>",
      "fence": "<path from CONFIG_DIR to a .geojson file specifying the geofencing boundary",
      "cert": "<path from CONFIG_DIR to the certificate used by the device",
      "key": "<path from CONFIG_DIR to the key used by the device"
      "disable": false
    }
  ],

  "client": {
    "hostName": "<MQTT endpoint",
    "port": 8883,
    "name": "Client",
    "cert": "<path from CONFIG_DIR to the certificate used by the listener",
    "key": "<path from CONFIG_DIR to the key used by the listener"

  }
}

Commands

Simulation Listener

The listener acts as an MQTT client, and subscribes to the relevant device messages. The listener can either listen to ALL devices (which could be a lot of messages), or you can have it focus on a specific device (which is useful if you are working with a broker shared by several developers). When you manage only a single device, you have additional options such as sending commands to the device.

To listen to all clients: npm run listen

To listen and manage client 'test-1': npm run mange test-1

When managing a device, you can press keys to trigger certain actions. For example, 'h' sends a horn command to the unit. 'b' sends the boundary file for that unit.

Simulator

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

Each device to be simulated must be specified in the sim.json file and have a unique ID (eg corresponding to a Thing name)

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.