# knot-fog-connector-aws

> KNoT fog connector with AWS IoT Core

Latest version **1.0.1** (published 2019-12-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install knot-fog-connector-aws
pnpm add knot-fog-connector-aws
yarn add knot-fog-connector-aws
bun add knot-fog-connector-aws
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2019-12-10 |
| First published | 2019-12-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 256.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | douglasdssv |

## Links

- npm: https://www.npmjs.com/package/knot-fog-connector-aws
- Repository: https://github.com/CESARBR/knot-fog-connector-iniot
- Homepage: https://github.com/CESARBR/knot-fog-connector-iniot#readme
- Issues: https://github.com/CESARBR/knot-fog-connector-iniot/issues
- npm.io page: https://npm.io/package/knot-fog-connector-aws

## Dependencies (1)

- [aws-iot-device-sdk](https://npm.io/package/aws-iot-device-sdk.md) ^2.2.1

## Recent versions

- 1.0.1 (latest) — 2019-12-10
- 1.0.0 — 2019-12-10

## README

# 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](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html)
* [Docker Hub Connector Image](https://hub.docker.com/r/cesarbr/knot-fog-connector)
* [Node](https://nodejs.org/en/)
* [Erlang](https://www.erlang.org/downloads)
* [RabbitMQ](https://www.rabbitmq.com/#community)

## Under Development

* [AWS IoT](https://github.com/dssv/knot-fog-connector-aws-iot)

## Quickstart

```bash
$ npm run build
$ npm start
```

## Development Environment Setup

In order to test changes made to the [supported services](#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](https://www.rabbitmq.com/) 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](https://hub.docker.com/r/cesarbr/knot-fog-connector)

### Configuration

Configuration is made via a JSON file placed into `knot-fog-connector/config/` folder (see [config](https://www.npmjs.com/package/config) package documentation for more information). Find below, the parameters for such file.

* `cloudType` **String** cloud provider name. Currently, only [KNOT_CLOUD](####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***)

```json
{
    "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:

```javascript
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

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

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

#### start(): Promise&lt;Void&gt;

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

##### Example

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

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

#### addDevice(device): Promise&lt;Void&gt;

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

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

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

```

#### removeDevice(id): Promise&lt;Void&gt;

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

##### Arguments

* `id` **String** device ID (KNoT ID)

##### Example

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

#### authDevice(id, token): Promise&lt;Boolean&gt;

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

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

#### listDevices(): Promise&lt;Object&gt;

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()`](#updateschemaid-schema-promisevoid)

##### Example

```javascript
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&lt;Void&gt;

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

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

#### updateSchema(id, schema): Promise&lt;Void&gt;

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](https://github.com/CESARBR/knot-protocol-source) 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

```javascript
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&lt;Void&gt;

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

```javascript
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&lt;Void&gt;

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

```javascript
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&lt;Void&gt;

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

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

#### onDisconnected(cb): Promise&lt;Void&gt;

Register a callback to handle gateway disconnection.

##### Arguments

* `cb` **Function** event handler.

##### Example

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

#### onReconnected(cb): Promise&lt;Void&gt;

Register a callback to handle gateway reconnection.

##### Arguments

* `cb` **Function** event handler.

##### Example

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

---
_Source: https://npm.io/package/knot-fog-connector-aws · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
