Introduction
This documentation offers a comprehensive guide to integrating our CrystalMQ broker or any MQTT broker of your choice with a mobile application on Android. It covers fundamental tasks such as establishing connections, subscribing to topics, unsubscribing, and exchanging messages. By following these steps, you can seamlessly implement MQTT communication within your mobile applications.
Pre-requisites
Before proceeding, ensure you have :
- A smartphone or tablet with Android OS
- An MQTT broker of your choice
- Any MQTT client app from the Play Store. (For this documentation, we've used IoT MQTT Panel as an example).
- An active internet connection on your device.
Downloading the mobile app
First, download and install the IoT MQTT Panel app from the Play Store.
- Open the Google Play Store on your android device.
- Search for " IoT MQTT Panel" app.
- Tap "Install" to download and install the app.
Steps to connect the IoT MQTT Panel to an MQTT Broker
Step 1 : Open the IoT MQTT Panel App
Once installed, open the IoT MQTT Panel app on your android device.
Step 2: Add a New Broker
- On the app's main screen, tap the 'Setup a Connection' to create a connection to communicate with MQTT broker.
- Enter the following details:
- Connection Name: Give a name to your broker connection (e.g., "Home MQTT Broker").
- Client ID : Enter a unique client ID (e.g., AndroidClient1). This ID should be unique to each device connecting to the broker.
- Broker Web/IP Address : Enter the hostname or IP address of your MQTT broker (e.g., crystalmq.bevywise.com).
- Port: Enter the port number of the MQTT broker (default is 1883 for unencrypted communication or 8883 for encrypted communication).
- Network Protocol : Choose the required network protocol among TCP, TCP-SSL, Websocket, and Websocket-SSL. Upon choosing the network protocol, the port number will be changed accordingly.
Step 3 : Add Dashboard
There should be atleast one dashboard to setup the connection.
- Click on the '+' symbol to get the 'Add Dashboard' window.
- Enter the 'Dashboard Name' in the appropriate space.
- Hit the 'Save' button to get your created dashboard.
Step 4: Configure Additional Settings (Optional)
Tap on Additional options to configure additional settings:
- Username: If your broker requires authentication, enter the username here.
- Password: If your broker requires authentication, enter the password here.
- Auto Connect : This option enables the client to automatically reconnect to the broker after any network disruptions cause a disconnection.
- Keep Alive: MQTT uses a keep-alive mechanism to maintain client-broker connections. Adjust the keepalive parameter to control how frequently the client sends PINGREQ messages to the broker. Set the keep-alive interval in seconds (default is 60).
- Clean Session: This feature allows you to start fresh with no stored state on the broker. Enable or disable the clean session as per your requirement (By default, clean session is enabled).
- Last Will and Testament (LWT): Implement the Last Will and Testament feature to have the broker publish a predefined message if the client unexpectedly disconnects. This ensures subscribers are informed about the client’s status. Configure the LWT message settings if needed.
- Notify on disconnect : This allows you to receive a notification whenever the client disconnects from the broker due to any errors.
Step 4: Save and Connect
Once you have entered all the necessary details, tap the Create button to save your connection.
Tap on the broker entry you just created to initiate the connection.
Step 5: Add a Panel to Subscribe to Topics
1 .After connecting to the broker, you can add panels to subscribe to topics and view messages.
2 .Tap the + icon and choose the type of panel you want to add (e.g., Text Panel, Switch Panel).
3 .Configure the panel:
- Name: Enter a name for the panel.
- Topic: Enter the topic you want to subscribe to (e.g., home/temperature).
- QoS: Set the Quality of Service level (default is 0).
Tap Save to add the panel.
Step 6: Publish Messages
- To publish messages to a topic, tap the Publish tab.
- Enter the topic and message payload.
- Tap Publish to send the message.
You have now successfully connected the IoT MQTT Panel app on your Android device to an MQTT broker. You can start subscribing to topics to receive messages and publish messages to communicate with other devices or services in your IoT network.
