@d11/react-native-mqtt v0.0.3

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

Quality of Service (QoS)

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