Enhancement of Quito

source repository: https://github.com/6d7a/quito

1. upgrade react-native to 0.73
2. upgrade CocoaMQTT to 2.1.6
3. use MqttCocoaAsyncSocket instead of CocoaAsyncSocket
4. fix exapmle project bug

---

Quito

A TCP-capable MQTT client for React Native. The module provides a Typescript API for native MQTT clients on iOS and Android.

• on Android, quito relies on Paho
• on iOS, quito uses CocoaMQTT

The module provides both promise- and callback-based methods to interact with the native clients.

This libraries owes a lot to davesters' and SudoPlz' respective libraries, so thank you :100:

Installation

1npm install react-native-mqtt-clients

To make an unencrypted connection to an MQTT broker, make sure a consuming android application allows cleartext traffic, either generally by setting the android:usesCleartextTraffic flag in the application field of the AndroidManifest.xml, or by adding a security configuration.

Usage

The module provides promise- and callback-based methods to interact with the native clients.

Callback-based usage

1import { MqttClient, MqttOptionsBuilder } from 'react-native-mqtt-clients';
2
3// build a config using the MqttOptionsBuilder
4const config = new MqttOptionsBuilder()
5  .uri('tcp://test.mosquitto.org:1883')
6  .clientId('quito-test-client')
7  .build();
8
9const MqttClient = new MqttClient(config);
10
11MqttClient.init() // call init() to create native client and set up native event listeners
12  .then(() => {
13    // Subscribing to event callbacks
14    MqttClient.on(MqttEvent.CONNECTING, () => {
15      // called when client is connecting
16    });
17    MqttClient.on(MqttEvent.CONNECTED, () => {
18      // called when client is connected
19    });
20    MqttClient.on(MqttEvent.SUBSCRIBED, (topic: string) => {
21      // called when client has subscribed to a topic
22    });
23    MqttClient.on(MqttEvent.UNSUBSCRIBED, (topic: string) => {
24      // called when client has unsubscribed from a topic
25    });
26    MqttClient.on(
27      MqttEvent.MESSAGE_RECEIVED,
28      (topic: string, payload: Uint8Array) => {
29        // called when client has received a message
30      }
31    );
32    MqttClient.on(
33      MqttEvent.MESSAGE_PUBLISHED,
34      (topic: string, payload: Uint8Array) => {
35        // called when client has sent a message
36      }
37    );
38    MqttClient.on(MqttEvent.DISCONNECTED, () => {
39      // called when client has disconnected
40    });
41    MqttClient.on(MqttEvent.CONNECTION_LOST, (error?: Error) => {
42      // called when client has unexpectedly lost its connection to the broker
43    });
44    MqttClient.on(MqttEvent.EXCEPTION, (error: Error) => {
45      // called when client encountered an error
46    });
47    MqttClient.on(MqttEvent.CLOSED, (error?: Error) => {
48      // called when client was closed
49    });
50    MqttClient.on(MqttEvent.CONNECTION_COMPLETE, (serverURI: string, reconnect: boolean) => {
51      // called when client was connected or reconnected
52    });
53
54    // connecting to the MQTT broker
55    MqttClient.connect();
56
57    // subscribing to a message topic
58    // both a single topic or an array of topics are supported
59    MqttClient.subscribe([
60      {
61        topic: 'first/topic',
62        qos: 2, // Quality of Service
63      },
64      {
65        topic: 'second/topic',
66        qos: 1,
67      },
68    ]);
69
70    // unsubscribing from a message topic
71    // both a single topic string or an array of topic strings are supported
72    MqttClient.unsubscribe('first/topic');
73
74    // publishing a message
75    MqttClient.publish(
76      'first/topic',
77      Buffer.from('This is a test message!'),
78      0, // Quality of service
79      false // whether the message should be retained
80    );
81
82    // checking client connection
83    MqttClient.isConnected().then((isConnected: Boolean) => {
84      // process connection state
85    });
86
87    // shutting down client
88    MqttClient.end();
89  });

Promise-based usage

1import { MqttCliet, MqttOptionsBuilder } from 'react-native-mqtt-clients';
2
3// build a config using the MqttOptionsBuilder
4const config = new MqttOptionsBuilder()
5  .uri('tcp://test.mosquitto.org:1883')
6  .clientId('quito-test-client')
7  .build();
8
9const MqttClient = new MqttClient(config);
10
11await MqttClient.init(); // call init() to create native client and set up native event listeners
12
13// Most message callbacks are redundant
14// when using the Promise-based API
15MqttClient.on(
16  MqttEvent.MESSAGE_RECEIVED,
17  (topic: string, payload: Uint8Array) => {
18    // called when client has received a message
19  }
20);
21MqttClient.on(MqttEvent.CONNECTION_LOST, (error?: Error) => {
22  // called when client has unexpectedly lost its connection to the broker
23});
24MqttClient.on(MqttEvent.EXCEPTION, (error: Error) => {
25  // called when client encountered an error
26});
27
28// connecting to the MQTT broker
29try {
30  await MqttClient.connectAsync();
31} catch (e: any) {
32  // handle error
33}
34
35// subscribing to a message topic
36// both a single topic or an array of topics are supported
37try {
38  await MqttClient.subscribeAsync([
39    {
40      topic: 'first/topic',
41      qos: 2, // Quality of Service
42    },
43    {
44      topic: 'second/topic',
45      qos: 1,
46    },
47  ]);
48} catch (e: any) {
49  // handle error
50}
51
52// unsubscribing from a message topic
53// both a single topic string or an array of topic strings are supported
54try {
55  await MqttClient.unsubscribeAsync('first/topic');
56} catch (e: any) {
57  // handle error
58}
59
60// publishing a message
61try {
62  await MqttClient.publishAsync(
63    'first/topic',
64    Buffer.from('This is a test message!'),
65    0, // Quality of service
66    false // whether the message should be retained
67  );
68} catch (e: any) {
69  // handle error
70}
71
72// checking client connection
73const isConnected = await MqttClient.isConnected();
74
75// shutting down client
76try {
77  await MqttClient.endAsync();
78} catch (e: any) {
79  // handle error
80}

Mqtt Options

Use the MqttOptionsBuilder to generate a config for the MQTT client. The following options for configuring the MQTT client are available:

• clientId: string - Identifier used in the communication with the MQTT bromker
• username: string - Username used to authenticate the client against the broker
• password: string - Password used to authenticate the client against the broker
• keepaliveSec: number - Maximum time interval in seconds between control packets
• connectionTimeout: number - Maximum time interval the client will wait for the network connection to the MQTT broker to be established
• will: Will - MQTT message that the broker will send, should the client connect ungracefully.
  • topic: string - Topic the will will be published to
  • payload: string - Message of the will Base64-encoded
  • qos: QoS - quality of service of the will
  • retain: boolean - Indicates whether the will should be retained
• tls: boolean - Whether the client will secure the connection to the broker using TLS. Depending on the host platform, the options vary.
  • On Android: If tls == true, at least the broker's CA certificate android_caBase64 is required. If the broker expects the client to present a certificate as well, the shared android_caBase64 plus android_certificateBase64, keyStoreKey, and keyStorePassword options become mandatory
  • On iOS: If tls == true and no ios_certKeyP12Base64 is provided, broker certificates will not be validated. If tls == true and ios_certKeyP12Base64 is provided, the client wil authenticate using the contained crypto.
• ios_certKeyP12Base64: String - Base64-encoded PKCS12 archive containing client certificate and key
• android_caBase64: String - Base64-encoded CA certificate (DER) used by the MQTT broker
• android_certificateBase64: String - Base64-encoded self-signed X509 certificate (DER) of the client
• android_privateKeyBase64: string - Base64-encoded RSA private key of the client
• keyStorePassword: string - Password used in creating the client's keystore
• cleanSession: boolean - When set to true, the broker will open a non-persistent connection, during which it will not store any subscription information or undelivered messages for the client
• protocol: Protocol - Identifies the protocol used in the connection to the broker
• protocolVersion: number - Identies the MQTT version used in the connection to the broker
• reconnectPeriod: number - Time interval to elapse before a client will attempt to reconnect an unexpectedly disconnected client
• host: string - Host name of the MQTT broker to connect to
• port: number - Port number of the MQTT broker to connect to