# @telecomsante/mqtt-client

> kickass mqtt client

Latest version **2.2.0** (published 2018-11-16) · UNLICENCED license · 0 weekly downloads

## Install

```sh
npm install @telecomsante/mqtt-client
pnpm add @telecomsante/mqtt-client
yarn add @telecomsante/mqtt-client
bun add @telecomsante/mqtt-client
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2018-11-16 |
| First published | 2018-05-17 |
| Weekly downloads | 0 |
| License | UNLICENCED |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 30.3 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Télécom Santé |
| Maintainers | fablec, fduros, gitlab-telecomsante |
| Keywords | mqtt, terminal, companion |

## Links

- npm: https://www.npmjs.com/package/@telecomsante/mqtt-client
- Repository: git@gitlab.com:telecomsante/mqtt-ctl/mqtt-client
- npm.io page: https://npm.io/package/@telecomsante/mqtt-client

## Dependencies (3)

- [uuid](https://npm.io/package/uuid.md) 3.3.2
- [async-mqtt](https://npm.io/package/async-mqtt.md) 1.0.1
- [jsonschema](https://npm.io/package/jsonschema.md) 1.2.4

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 2.2.0 (latest) — 2018-11-16
- 2.1.2 — 2018-09-07
- 2.1.1 — 2018-05-18
- 2.1.0 — 2018-05-17

## README

# mqtt-client

![node](https://img.shields.io/badge/node-6.x-blue.svg)
![node](https://img.shields.io/badge/node-8.x-blue.svg)
![version](https://img.shields.io/badge/version-2.2.0-green.svg)


[![pipeline status](https://gitlab.com/telecomsante/mqtt-ctl/mqtt-client/badges/develop/pipeline.svg)](https://gitlab.com/telecomsante/mqtt-ctl/mqtt-client/commits/develop)
[![coverage report](https://gitlab.com/telecomsante/mqtt-ctl/mqtt-client/badges/develop/coverage.svg?job=test:unit)](https://gitlab.com/telecomsante/mqtt-ctl/mqtt-client/commits/develop)

mqtt-client is a kickass library which provide client and service to manage mqtt topics.

## Pre-requisites

* node >= 6.0.0

## Installation

```sh
npm install @telecomsante/mqtt-client
```

## Client

A client can subscribe and publish to many topics.

### Example

* Create, subscribe and listen to messages:

```javascript
const MQTTClient = require('@telecomsante/mqtt-client').client;

const options = {
  url: 'mqtt://mosquitto',
  username: 'admin',
  password: 'admin'
};

const client = new MQTTClient(options);
client.on('message', (topic, value) => console.log('message', topic, value));
client.on('error', error => console.log('error', error));
client.subscribe(['terminal/vlc/#', 'terminal/sound/volume']);
```

* Send a value

```javascript
client.setValue('terminal/test', 4);
```

* Close the client

```javascript
client.close().then(() => console.log('close successfully'));
```

### API

#### new MQTTClient(options)

Create a MQTTClient and connect to the mqtt server.
For the options, take a look at https://github.com/mqttjs/MQTT.js#client

Default options:

```javascript
const defaultOpts = {
  url: 'mqtt://localhost:1883',
  keepalive: 10000,
  clean: true
}
```

##### Event 'connect' -> function()

Emit when the client is connected to the mqtt server.

##### Event 'error' -> function(error)

Emit when a mqtt error appears.

##### Event 'close' -> function()

Emit after a mqtt disconnection

##### Event 'message' -> function(topic, value)

Emit when a value in the subscribed topics is changed.

#### client.subscribe([topics]) -> Promise

The client subscribes to the given topics.

MQTT topic wildcard characters are supported (+ - for single level and # - for multi level).

#### client.unsubscribe([topics]) -> Promise

The client unsubscribes to the given topics

#### client.setValue(topic, value) -> Promise

The client publishes the value to the request topic.

Example:

```javascript
client.setValue('terminal/sound/volume', 50);
```

Will set the value in the ```req/terminal/sound/volume``` topic.

#### client.close(force) -> Promise

Close the current client connection

## Service

A service manages two mqtt topics:

* A read only topic(```terminal/sound/volume```) for the clients.
* A request topic(```req/terminal/sound/volume```) for the clients.

The service subscribes to the change in the request topic and updates the read only topic at his convenience.

### Example

* Create and listen to messages:

```javascript
const MQTTService = require('@telecomsante/mqtt-client').service;

const options = {
  url: 'mqtt://mosquitto',
  username: 'admin',
  password: 'admin'
};

const jsonschema = {
  "type": "object",
  "properties": {
    "volume": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

const service = new MQTTService(options, 'terminal/sound/#', jsonschema);
service.on('message', (key, value) => console.log('message', key, value));
service.on('error', error => console.log('error', error));
```

* Send a value

```javascript
service.setValue('volume', 4);
```

By default, when a service send a value, this value is retained by the MQTT server. It may happen that we don't want the value to be retained, so in this case :

```javascript
service.setValue('volume', 4, false);
```

* Close the service

```javascript
service.close().then(() => console.log('close successfully'));
```

### API

#### new MQTTService(options, topic, jsonSchema)

Create a MQTTService and connect to the mqtt server.
For the options, take a look at https://github.com/mqttjs/MQTT.js#client

Default options:

```javascript
const defaultOpts = {
  url: 'mqtt://localhost:1883',
  keepalive: 10000,
  clean: true
}
```

The service manages the topic with the terminal or companion prefixes.

The json schema represents the structure of the tree managed by the service

##### Event 'connect' -> function()

Emit when the service is connected to the mqtt server.

##### Event 'error' -> function(error)

Emit when a mqtt error appears.

##### Event 'close' -> function()

Emit after a mqtt disconnection

##### Event 'message' -> function(key, value)

Emit when a value in the request topic is changed.

If the ```req/terminal/sound/volume``` value is changed and the managed topic is ```req/terminal/sound/#```:

```
key = 'sound'
value = the new value
```

#### service.setValue(key, value) -> Promise

The service publishes the value to the managed topic.

Example:

If the managed topic is ```req/terminal/sound/#```

```javascript
service.setValue('volume', 50);
```

Will set the value in the ```/terminal/sound/volume``` topic.

#### service.close(force) -> Promise

Close the current service connection

## Development

Before commit, run the tests and the linter:

* Tests

```sh
npm run test
```

* linter

```sh
npm run lint
```

---
_Source: https://npm.io/package/@telecomsante/mqtt-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._