@mangar2/mqttclient/README.md

communicates with a MQTT-Style HTTP broker

<!-- This file is generated by jsmddoc version 0.1 -->

# Abstract

Provides a standard client to communicate with the mqtt broker

## Contents

- [Meta](#Meta)
- [Type definitions](#Type-definitions)
- [Class MqttClient](#Class-MqttClient)
  - [Parameters](#MqttClient-Parameters)
  - [Members](#MqttClient-Members)
  - [Methods](#MqttClient-Methods)
    - [_createMemoryUsageMessage](#_createMemoryUsageMessage)
    - [close](#close)
    - [isShuttingDown](#isShuttingDown)
    - [on](#on)
    - [publish](#publish)
    - [reconnect](#reconnect)
    - [registerCloseFunction](#registerCloseFunction)
    - [registerRecipient](#registerRecipient)
    - [registerSender](#registerSender)
    - [run](#run)
    - [updateSubscriptions](#updateSubscriptions)

## Meta

| | |
| --- | --- |
| **File** | mqttclient.js |
| **Abstract** | Provides a standard client to communicate with the mqtt broker |
| **Author** | Volker Böhm |
| **Copyright** | Copyright ( c ) 2020 Volker Böhm |
| **License** | This software is licensed under the GNU LESSER GENERAL PUBLIC LICENSE Version 3 . It is furnished "as is" , without any support , and with no warranty , express or implied , as to its usefulness for any purpose . |

## Type definitions

### LogPattern {Object}

| Name | Type | Description |
| ---- | ---- | ------- |
| `topic` | `string` | log topic pattern | |
| `module` | `string` | module to log , "send" , "receive" or "all" ( for all modules ) | |
| `level` | `number` | log level for the pattern | |

## Callback definitions

### PollCallback

Callback to retrieve messages to be sent to the mqtt broker

#### PollCallback returns

| Type | Description |
| ---- | ----------- |
| `Array.<Message>, Message` | messages to send to the broker |

## Class MqttClient

`new MqttClient(options)`

Creates a standard mqtt client , connects and subscribes to the broker

### MqttClient Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `options` | `Object` | options to provide for connection | |

#### options properties

| Name | Type | Attribute | Default | Description |
| ---------- | ------------ | ------------ | ------------ | ----------------- |
| `clientId` | `string` |  |  | unique id of the client | |
| `broker` | `Object` |  |  | information of the broker to connect to | |
| `listener` | `number` |  |  | port this client will listen to | |
| `version` | `string` | optional | '1 . 0' | interface version | |
| `keepAliveInSeconds` | `string` | optional |  | connection keep alive time in seconds | |
| `clean` | `boolean` | optional | true | clean the broker session on disconnect | |
| `retry` | `number` |  |  | amount of retries to send messages to the broker | |
| `log` | `Array.<LogPattern>` |  |  | logging settings | |

#### broker properties

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `host` | `string` | hostname of the broker | |
| `port` | `number` | port of the broker | |

### MqttClient Members

| Name | Type | description |
| ------------ | ------------ | ------------ |
| `connected` | `boolean` | Connection status . true , iff connected |
| `token` | `Object.<send:string, receive:string>` | Send and receive token to be used to communicate with the mqtt broker |
| `version` | `string` | Gets/Sets the interface version to use |

### MqttClient Methods

#### _createMemoryUsageMessage

`_createMemoryUsageMessage () => {Message}`

Creates a message showing the memory usage

##### _createMemoryUsageMessage returns

| Type | Description |
| ---- | ----------- |
| `Message` | the memory usage message with the topic $SYS/ [ clientId ] /memory usage |

#### close

`async close ()`

closes the client by shutting down all services and loops

#### isShuttingDown

`isShuttingDown () => {boolean}`

checks , if the client is shutting down . Every loop must stop once isShuttingDown is true

##### isShuttingDown returns

| Type | Description |
| ---- | ----------- |
| `boolean` | true , iff shutting down |

#### on

`on (event, callback)`

Sets a callback .

##### on Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `event` | `string` | supports 'shutdown' | |
| `callback` | `function` |  | |

##### on throws

| Type | Description |
| ---- | ----------- |
| `Error` | if the event is not supported |
| `Error` | if the callback is not 'function' |

#### publish

`publish (message, serviceName)`

Publishes a message to the broker

##### publish Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `message` | `Message` | message to publish | |
| `serviceName` | `string` | name of the publishing service | |

#### message properties

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `qos` | `number` | quality of service ( 0 , 1 , 2 ) | |
| `retain` | `boolean` | true to create a retain message | |

#### reconnect

`async reconnect ()`

Connects and subscribes to the broker

#### registerCloseFunction

`registerCloseFunction (closeFunction)`

Registers close functions . It will be called when the client close function is called

##### registerCloseFunction Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `closeFunction` | `function` | function to be called on close commands | |

#### registerRecipient

`async registerRecipient (serviceName, subscriptions, callback)`

Registeres a recipient

##### registerRecipient Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `serviceName` | `string` | name of the subscribing service | |
| `subscriptions` | `Object` | subscription entries of format { topic : qos , topic : qos , . . . } | |
| `callback` | `function` | function to send received messages to | |

##### registerRecipient throws

| Type | Description |
| ---- | ----------- |
| `Error` | If subscriptions are not well formatted or callback is not a function |

#### registerSender

`registerSender (intervalInMilliseconds, callback)`

Registeres a service sending messages in intervals . The service must provide a function ( callback ) without parameters returing an array of messages . The messages will then be sent to the broker

##### registerSender Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `intervalInMilliseconds` | `number` | interval in milliseconds to call the senders callback | |
| `callback` | `PollCallback` | function to call | |

#### run

`async run ()`

Starts the mqttclient . Opens the listener and connects to the broker

#### updateSubscriptions

`async updateSubscriptions (serviceName, subscriptions)`

Updates the subscriptions

##### updateSubscriptions Parameters

| Name | Type | Description |
| ---------- | ------------ | ----------------- |
| `serviceName` | `string` | name of the subscribing service | |
| `subscriptions` | `Object` | subscription entries of format { topic : qos , topic : qos , . . . } | |

##### updateSubscriptions throws

| Type | Description |
| ---- | ----------- |
| `Error` | If subscriptions are not well formatted |