d11-react-native-mqtt

Message Queuing Telemetry Transport (MQTT) is a lightweight, efficient, and reliable messaging protocol designed for low-bandwidth, high-latency, or unreliable networks.

MQTT operates on a publish/subscribe pattern, facilitating the decoupling of message senders (publishers) from message receivers (subscribers). This is achieved through the utilization of a central component known as a message broker, which orchestrates communication between publishers and subscribers.

This package provides MQTT functionality for React Native applications.

Internally, this package leverages HiveMQTT for Android and CocoaMQTT for iOS, ensuring seamless integration and optimal performance across both platforms.

• Contribution guidelines: CONTRIBUTING.md
• License: MIT
• MQTT resources:
  • MQTT Essentials
  • MQTT 5.0

Features

• API flavor:

  • Asynchronous API

• Backpressure support:

  • QoS 1 and 2
  • QoS 0 (dropping incoming messages, if necessary)
  • Bringing MQTT flow control and reactive pull backpressure together

• Transports:

  • TCP
  • SSL/TLS

• Automatic and configurable thread management

• Automatic and configurable reconnect handling

• Lifecycle listeners

  • When connected
  • When disconnected or connection failed

Minimum Supported Version

This project requires the following minimum versions to function properly:

• Java: JDK 8 or higher
• iOS: iOS 12.0 or higher
• Android: API level 24 (Android 7.0) or higher

Installation

using NPM
npm install @d11/react-native-mqtt

using Yarn
yarn add @d11/react-native-mqtt

General configuration

| Variable Name | Description | Default value | |:---------------:|:--------------------------------------------------------------------------------------------:|---------------| | topic | A topic is a UTF-8 encoded string that is the basis for message routing in the MQTT protocol | None | | clientId | The unique identifier of the MQTT client | None | | host | The host name or IP address of the MQTT server | None | | port | The port of the MQTT server | None | | keepAlive | Keep the connection alive for mentioned time in seconds. | 60 sec | | cleanSession | A flag to create new session or use old session while connecting | true | | backoffTime | Time to wait before retrying connection | 2 sec | | maxBackoffTime | Max time to wait before retrying connection | 60 sec | | jitter | Jitter is used to add randomness into backoff time | 1 | | enableSslConfig | A boolean indicating whether SSL/TLS configuration should be enabled | false | | autoReconnect | A boolean to determine auto reconnection | None | | retryCount | An integer to determine retry count | None |

Quality of Service (QoS)

| Enum Name | Description | |:-------------:|:---------------------------------------------------------------------:| | AT_MOST_ONCE | QoS for at most once delivery as per the capabilities of the network. | | AT_LEAST_ONCE | QoS for ensuring at least once delivery. | | EXACTLY_ONCE | QoS for ensuring exactly once delivery. |

Creation of clients

import { createMqttClient, MqttConfig } from "@d11/react-native-mqtt";
import { MqttClient } from "@d11/react-native-mqtt/dist/Mqtt/MqttClient";

export const createMqtt = (mqttConfig: MqttConfig): MqttClient => {
  const client = createMqttClient({
      clientId: mqttConfig.clientId,
      host: mqttConfig.host,
      port: mqttConfig.port,
      options: {
        password: '',
        enableSslConfig: false,
        autoReconnect: true,
        maxBackoffTime: mqttConfig.maxBackoffTime,
        retryCount: mqttConfig.connectRetryCount,
        cleanSession: mqttConfig.cleanSession,
        keepAlive: mqttConfig.keepAlive,
        jitter: mqttConfig.jitter,
        username: '',
      },
  });
  return client;
}

Example

import * as React from 'react';
import { StyleSheet, View, Text, Button } from 'react-native';
import { createMqtt } from './components/create-mqtt';
import { MqttClient } from '@d11/react-native-mqtt/dist/Mqtt/MqttClient';
import { MqttConfig } from "@d11/react-native-mqtt";

const mqttConfig: MqttConfig =  {
  "clientId": "mqttx_0121",
  "cleanSession": true,
  "host": "dummy.mqttx.com",
  "jitter": 1, 
  "keepAlive": 60,
  "maxBackoffTime": 60,
  "port": 8883,
  "retryCount": 3
}

enum MqttQos {
  AT_MOST_ONCE = 0,
  AT_LEAST_ONCE = 1,
  EXACTLY_ONCE = 2,
}

export default function App() {
  const [client, setClient] = React.useState<MqttClient | undefined>(undefined);

  const createMqttClient = () => {
    const newClient = createMqtt(MqttConfig);
    setClient(newClient);
  };

  const connectMqtt = () => {
    if (client) {
      client.connect();
    }
  };

  const disconnectMqtt = () => {
    if (client) {
      client.disconnect();
    }
  };

  const subscribeMQTT = () => {
    if(client){
      client.subscribe({
        topic: "sample_topic",
        qos: MqttQos.AT_LEAST_ONCE,
        onSuccess: (ack) => {
          console.log(`MQTT Subscription Success: ${ack}`);
        },
        onError: (error) => {
          console.log(`MQTT Subscription Failed: ${error}}`);
        },
        onEvent: ({ payload }) => {
          console.log(`MQTT Subscription data: ${payload}`);
        }
      })
    }
  }

  return (
    <View style={styles.container}>
      <Button
        title="Create Mqtt"
        color={'green'}
        onPress={createMqttClient}
      />
      <Button
        title="Connect Mqtt"
        color={'green'}
        onPress={connectMqtt}
      />
      
      <Button
        title="Subscribe MQTT"
        color={'green'}
        onPress={subscribeMQTT}
      />
      <Button
        title="Disconnect Mqtt"
        color={'red'}
        onPress={disconnectMqtt}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  }
});

API Support

• createMqttClient: A function that returns an instance of MqttClient with the given input config.

createMqttClient: (config: MqttConfig) => MqttClient
const client = createMqttClient(config)

type MqttConfig = {
  clientId: string;
  host: string;
  port: number;
  options?: MqttOptions;
}

type MqttOptions = {
  keepAlive?: number;
  cleanSession?: boolean;
  username?: string;
  password?: string;
  maxBackoffTime?: number;
  backoffTime?: number;
  jitter?: number;
  enableSslConfig?: boolean;
  autoReconnect?: boolean;
  retryCount?: number;
}

• connect: connects to MQTT server with auto-reconnect and retry support.

connect(options?: MqttOptions) => void

client.connect()

• setOnConnectCallback: Performs an action after connection is established.

type onConnectCallback = (ack: MqttEventsInterface[MQTT_EVENTS.CONNECTED_EVENT]) => void

client.setOnConnectCallback(onConnectCallback)

MQTT_EVENTS {
  CONNECTED_EVENT = 'connected',
  DISCONNECTED_EVENT = 'disconnected',
  SUBSCRIPTION_EVENT = 'subscription_event',
  SUBSCRIPTION_SUCCESS_EVENT = 'subscribe_success',
  SUBSCRIPTION_FAILED_EVENT = 'subscribe_failed',
}

• setOnConnectFailureCallback: Sets a callback for handling connection failure events.

type onConnectFailureCallback = (mqtt5ReasonCode: Mqtt5ReasonCode) => void

client.setOnConnectFailureCallback(onConnectFailureCallback)

Mqtt5ReasonCode {
  BAD_USER_NAME_OR_PASSWORD = 134,
  NOT_AUTHORIZED = 135,
  BAD_AUTHENTICATION_METHOD = 140,
  NORMAL_DISCONNECTION = 0,
  DEFAULT = -1,
}

• setOnErrorCallback: Sets a callback for handling error events.

type onErrorCallback = (ack: MqttEventsInterface[MQTT_EVENTS.ERROR_EVENT]) => void

client.setOnErrorCallback(onErrorCallback)

• setOnDisconnectCallback: Sets a callback for handling client disconnect events.

type onDisconnectCallback = (mqtt5ReasonCode: DisconnectCallback['mqtt5ReasonCode'],
options: DisconnectCallback['options']) => void

client.setOnDisconnectCallback(onDisconnectCallback)

• connectInterceptor: Method to intercept connection options and may modify or override them.

type connectInterceptor?: (options?: MqttOptions) => Promise<MqttConnect | undefined>

client.connectInterceptor()

• reconnectInterceptor: Method to intercept connection options and may modify or override them.

type reconnectInterceptor?: (mqtt5ReasonCode?: Mqtt5ReasonCode) => Promise<MqttConnect | undefined>

client.reconnectInterceptor()

• setOnReconnectInterceptor: PerformS an action everytime before reconnect after first connect fails.

type reconnectInterceptor = (
  mqtt5ReasonCode?: Mqtt5ReasonCode
) => Promise<MqttConnect | undefined>

client.setOnReconnectInterceptor(reconnectInterceptor)

• setOnConnectFailureCallback: Sets a callback for handling connection failure events.

type onConnectFailureCallback = (mqtt5ReasonCode: Mqtt5ReasonCode) => void

client.setOnConnectFailureCallback(onConnectFailureCallback)

• getConnectionStatus: Gets the current connection status.

getConnectionStatus: () => string
const status = client.getConnectionStatus();

• getCurrentRetryCount: Gets the current retry count.

getConnectionStatus: () => number
const status = client.getCurrentRetryCount();

• subscribe: Subscribes to a topic with onEvent, onSuccess , onError callbacks support.

subscribe: ({ topic, qos, onEvent, onSuccess, onError}: Subscribe) => void

client.subscribe({
  topic,
  qos,
  onEvent,
  onSuccess,
  onError,
})

type Subscribe = {
  topic: string;
  qos?: MqttQos;
  onEvent: (
    payload: MqttEventsInterface[MQTT_EVENTS.SUBSCRIPTION_EVENT]
  ) => void;
  onSuccess?: (
    ack: MqttEventsInterface[MQTT_EVENTS.SUBSCRIPTION_SUCCESS_EVENT]
  ) => void;
  onError?: (
    error: MqttEventsInterface[MQTT_EVENTS.SUBSCRIPTION_FAILED_EVENT]
  ) => void;
}

• disconnect: Disconnects with MQTT server.

disconnect: () => void

client.disconnect();

• remove: Removes particular client.

remove: () => void

client.remove();

How does it work?

Running example app

# install all packages
yarn

# for android
yarn example android

# for ios
yarn example ios

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT