Introducing DreamFactory's MQTT Service

MQTT is a communication protocol for the publish-subscribe architecture. You can use DreamFactory as a MQTT client for your IoT projects. It's easy to connect to any MQTT-based message broker using DreamFactory and easily publish and subscribe to any topic.

DreamFactory's MQTT client service is native to the platform, supporting role-based access controls, live API documentation, and more. Once you've configured your MQTT service in DreamFactory, all the configuration details are hidden from any clients who may access it. All configuration is securely stored in your DreamFactory instance database. This provides a simple way to publish and subscribe messages to your MQTT broker.

Configuring the MQTT Service

Configuring a MQTT client service is easy. Start by logging into the admin console, head over to the ‘Services’ tab, and click on the ‘Create’ button on the left sidebar. Use the ‘Service Type’ drop down to select ‘IoT’ -> ‘MQTT Client’, complete the service configuration form, and save it to create your service. Here’s what the MQTT service configuration looks like.

In the ‘Info’ tab, provide basic service information - Name, Label, and Description.

In the ‘Config’ tab, provide the following configuration information:

• Broker Host - String. Required. Host name or IP address of your MQTT broker.
• Broker Port - Integer. Optional. Default 1883. Port number of your MQTT broker.
• Client ID - String. Required. Client ID used for this connection. Make sure this is unique for all of your clients connecting to broker.
• Username - String. Optional. Provide username if your broker requires authentication.
• Password - String. Optional. Provide password for your username if your broker requires authentication.
• Use TLS - Boolean. Default false. Check this if your connection requires TLS.

Once you've configured your MQTT client service, you can publish and subscribe messages on various topics to your MQTT broker. You can also head over to the ‘API Docs’ tab and expand your newly created service to see the API endpoints.

Here “mqtt” is the name of the service that was entered during service configuration. It can be any url-safe string of your choice. Expand each of the endpoints to learn more about them.

Publish Endpoint (POST /mqtt/pub)

Use the publish endpoint (mqtt/pub) to publish a message on a specific topic to the MQTT broker. Here's an example curl call to publish a message:

curl -i -k -X POST https://example.com/api/v2/mqtt/pub -d {“topic” : ”My/Test/Topic”, “message” : ”Hello”}

Subscribe Endpoint (POST /mqtt/sub)

Subscribing to a topic requires a little bit of understanding about how the subscription process works. When you subscribe to one or more topics, a separate process needs to continuously run in the background in order to check for any incoming messages and then handle the messages according to your request.  

Managing the Queue Worker

For this background process to run continuously, you need to run a queue worker process (learn more about DreamFactory and queueing scripts). A queue worker process is a daemon service that you manage on the same server where your DreamFactory instance runs. You can use the Linux supervisor application (or a similar application on other operating systems) to automatically start and manage the lifecycle of this queue worker process.

The queue worker process constantly monitors queue jobs from your DreamFactory instance. When you subscribe to a topic using DreamFactory, a queued job is picked up by the queue worker process. DreamFactory is built on the Laravel framework, so it uses the Laravel queue worker for this purpose. You can learn more about the Laravel queue worker here.

Starting the Queue Worker

To start a queue worker manually, just run the following command in the root directory of your DreamFactory installation:

$ php artisan queue:work

Subscribing to an MQTT Topic

To subscribe to an MQTT topic, make a POST call to the mqtt/sub endpoint. Here is a simple curl example:

$ curl -i -k -X POST https://example.com/api/v2/mqtt/sub -d [{ "topic": "My/Test/Topic", "service": {"endpoint": "apn/push", "verb": "POST", "parameter": [{“api_key” : “abc123”}] } }]

Notice the request payload. When subscribing to a topic, you can provide DreamFactory service information as part of the subscription. When a message arrives on your subscribed topic, DreamFactory will automatically trigger this service and inject the incoming message to this service request as part of the payload by using the key “message”. This gives you all kinds of flexibility in terms of what to do when you receive a message on your subscribed topic. You can always use a custom scripting service or a remote web service to perform some simple or really complex action.

Another thing to notice is that the subscription request payload is an array. This means you can subscribe to multiple topics in one subscription request. However, when you are already subscribed to one or more topics, you cannot add an additional subscription without terminating all your existing subscriptions first. Once you terminate all your existing subscriptions, re-subscribe to one or more topics again.

To terminate all subscriptions, make a DELETE call to the mqtt/sub endpoint.

Lastly, you can view all of your active subscriptions by making a GET call to the mqtt/sub endpoint.

Conclusion

In this post, we covered how to use DreamFactory to connect to any MQTT-based message broker and easily publish and subscribe to any topic. If you'd like to try this feature, contact us to start an on-premise trial, or begin a hosted trial now at https://genie.dreamfactory.com/.