KNoT Fog Connector AWS IoT

This is a KNoT Fog lib that connects the fog to the cloud service of AWS IoT.

Util Links

• AWS IoT Console Documentation
• Docker Hub Connector Image
• Node
• Erlang
• RabbitMQ

Under Development

• AWS IoT

Quickstart

$ npm run build
$ npm start

Development Environment Setup

In order to test changes made to the supported services, one must setup a development environment and run required services locally. Let it be noted, though, that changes should also be properly tested directly on KNoT Gateway.

Prerequisites

knot-fog-connector requires rabbitMQ to be running. The default access ip and port for RabbitMQ are localhost:5672.

Is interesting to use the docker image to run your tests. The image is placed in Docker Hub. You can access and use it in the link: Docker KNoT Fog Connector Image

Configuration

Configuration is made via a JSON file placed into knot-fog-connector/config/ folder (see config package documentation for more information). Find below, the parameters for such file.

• cloudType String cloud provider name. Currently, only KNOT_CLOUD is supported.
• cloud Object CloudType specific parameters (see below).

KNoT-AWS-IOT

• cloud Object cloud parameters
  • protocol String (Optional) Either 'mqtt' or 'wss' (Default: wss)
  • host String (Required) KNoT AWS IoT hostname
  • port Number (Optional) knot cloud aws iot protocol adapter instance port (Default: 443)
  • keyPath String (Required) path name on the private key
  • certPath String (Required) path name on the certificate permission
  • caPath String (Required) path name on the authentication certificate
  • clientId String (Required) thing name created in aws console
  • region String (Required) region used fo rinstance the project in AWS console
  • debug String (Optional) flago to set debug (Default: false)

{
    "cloudType": "KNOT_AWS_IOT",
    "cloud": {
        "host": "id_for_account.iot.us-east-1.amazonaws.com",
        "port": 443,
        "keyPath": "./certs/private.pem.key",
        "certPath": "./certs/certificate.pem.crt",
        "caPath": "./certs/root-CA.crt",
        "clientId": "thing_name",
        "protocol": "wss",
        "region": "us-east-1",
        "debug": false
    }
}

Understanding a connector

A connector is as a library that exports by default the Connector class. This service will use the library as follows:

import AWSIOTCloudConnector from '@cesarbr/knot-fog-connector-aws-iot';

...
const connector = new AWSIOTCloudConnector(config);
await connector.start();

Methods

constructor(config)

Create the connector using a configuration object that will be loaded from a JSON file and passed directly to this constructor. No work, such as connecting to a service, must be done in this constructor.

Arguments

• config Object configuration parameters defined by the connector

Example

import CustomCloudConnector from '@cesarbr/knot-fog-connector-aws-iot';

const connector = new CustomCloudConnector({
  hostname: 'localhost',
  port: 3000,
  protocol: 'ws',
  ...
});

start(): Promise<Void>

Start the connector. This is the method where initialization procedures, such as connecting to external services, must be done.

Example

import CustomCloudConnector from '@cesarbr/knot-fog-connector-aws-iot';

const connector = new CustomCloudConnector({ ... });
await connector.start();

addDevice(device): Promise<Void>

Add a device to the cloud. Called when a new device is added to the fog.

Arguments

• device Object device specification containing the following properties:
  • id String device ID (KNoT ID)
  • name String device name

Result

• device Object device registered on the cloud.
  • id String device ID (KNoT ID)
  • token String device token

Example

await connector.start();
await connector.addDevice({
  id: '918f2e0f4e19f990',
  name: 'Front door'
});

// {
//   id: '918f2e0f4e19f990',
//   token: '5b67ce6bef21701331152d6297e1bd2b22f91787'
// }

removeDevice(id): Promise<Void>

Remove a device from the cloud. Called when a device is removed from the fog.

Arguments

• id String device ID (KNoT ID)

Example

await connector.start();
await connector.removeDevice('656123c6-5666-4a5c-9e8e-e2b611a2e66b');

authDevice(id, token): Promise<Boolean>

Authenticate a device on the cloud. Called when it's necessary to verify if a device is valid on the cloud provider.

Arguments

• id String device ID (KNoT ID)
• token String device token

Result

• status Boolean response that represents the authentication status (true/false).

Example

await connector.start();
const status = await connector.authDevice(
  'ea9798ed48d73dd0',
  '0c20c12e2ac058d0513d81dc58e33b2f9ff8c83d'
);
console.log(status);
// true

listDevices(): Promise<Object>

List the devices registered on the cloud for the current gateway.

Result

• devices Array devices registered on the cloud or an empty array. Each device is an object in the following format:
  • id String device ID (KNoT ID)
  • name String device name
  • schema Array schema items, as specified in updateSchema()

Example

await connector.start();
const devices = await connector.listDevices();
console.log(devices);
// [ { id: '656123c6-5666-4a5c-9e8e-e2b611a2e66b', name: 'Front door', schema: [{ sensorId: 1, ... }, ...] },
//   { id: '254d62a9-2118-4229-8b07-5084c4cc3db6', name: 'Back door', schema: [{ sensorId: 1, ... }, ...] } ]

publishData(id, data): Promise<Void>

Publish data as a device. Called when a device publishes data on the fog.

Arguments

• id String device ID (KNoT ID)
• data Array data items to be published, each one formed by:
  • sensorId Number sensor ID
  • value Number|Boolean|String sensor value

Example

await connector.start();
await connector.publishData('656123c6-5666-4a5c-9e8e-e2b611a2e66b', [
  {
    sensorId: 1,
    value: false
  },
  {
    sensorId: 2,
    value: 1000,
  }
]);

updateSchema(id, schema): Promise<Void>

Update the device schema. Called when a device updates its schema on the fog.

Arguments

• id String device ID (KNoT ID)
• schema Array schema items, each one formed by:
  • sensorId Number sensor ID
  • valueType Number semantic value type (voltage, current, temperature, etc)
  • unit Number sensor unit (V, A, W, W, etc)
  • typeId Number data value type (boolean, integer, etc)
  • name String sensor name

Refer to the protocol for more information on the possible values for each field.

NOTE: schema will always contain the whole schema and not a difference from a last update.

Example

await connector.start();
await connector.updateSchema('656123c6-5666-4a5c-9e8e-e2b611a2e66b', [
  {
    sensorId: 1,
    valueType: 0xFFF1, // Switch
    unit: 0, // NA
    typeId: 3, // Boolean
    name: 'Door lock',
  },
  {
    sensorId: 2,
    ...
  }
]);

onDataRequested(cb): Promise<Void>

Register a callback to handle data requests from the cloud. Called when a cloud application requests the last value of a device's sensor.

Arguments

• cb Function event handler defined as cb(id, sensorId) where:
  • id Number device ID (KNoT ID)
  • sensorIds Array IDs of the sensor to send last value (Number)

Example

await connector.start();
await connector.onDataRequested((id, sensorIds) => {
  console.log(`New data from '${sensorIds}' on device '${id}' is being requested`);
  // New data from '1,2' on device '656123c6-5666-4a5c-9e8e-e2b611a2e66b' is being requested
});

onDataUpdated(cb): Promise<Void>

Register a callback to handle data updates from the cloud. Called when a cloud application requests to update a device's actuator.

Arguments

• cb Function event handler defined as cb(id, data) where:
  • id Number device ID (KNoT ID)
  • data Array updates for sensors/actuators, each one formed by:
    • sensorId Number ID of the sensor to update
    • value Number|Boolean|String value to be written

Example

await connector.start();
await connector.onDataUpdated((id, data) => {
  console.log(`Update actuator '${data.sensorId}' on device '${id}' to ${data.value}`);
  // Update actuator '2' on device '656123c6-5666-4a5c-9e8e-e2b611a2e66b' to 1000
});

onDeviceUnregistered(cb): Promise<Void>

Register a callback to handle devices removed from the cloud. Called when a cloud removes a device.

Arguments

• cb Function event handler defined as cb(id) where:
  • id Number device ID (KNoT ID)

Example

await connector.start();
await connector.onDeviceUnregistered((id) => {
  console.log(`Device '${id}' removed`);
  // Device '2' removed
});

onDisconnected(cb): Promise<Void>

Register a callback to handle gateway disconnection.

Arguments

• cb Function event handler.

Example

await connector.start();
await connector.onDisconnected(() => {
  console.log('Disconnected');
});

onReconnected(cb): Promise<Void>

Register a callback to handle gateway reconnection.

Arguments

• cb Function event handler.

Example

await connector.start();
await connector.onReconnected(() => {
  console.log('Reconnected');
});