{ DreamFactory: 'Blog' }

Introducing DreamFactory's MQTT Service

Posted by Arif Islam

Wed, Aug 9, 2017

DreamFactory 2.8 introduces the MQTT Client Service. As you may know, MQTT is a communication protocol for the publish-subscribe architecture. You can now 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, with role-service-access, live API documentation, and more. Once you've configured your MQTT client service in DreamFactory, all the configuration details are hidden from your client. 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 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.

mqtt-one.png

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.

mqtt-two.png

mqtt-three.png

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.

mqtt-four.png

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 http://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.  

For this background process to run continuously, you need to run a queue worker process. A queue worker process is simply a daemon service that you start up and run 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. To start a queue worker manually, just run the following command in the root directory of your DreamFactory installation:

php artisan queue:work

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

curl -i -k -X POST http://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 here. When you subscribe 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, simply 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.

In this post, we quickly covered how to use DreamFactory to connect to any MQTT-based message broker and easily publish and subscribe to any topic. Check out the community forum to discuss or let us know what you think in the comments! 

Get started with DreamFactory with a free hosted DreamFactory development environment. Or, download and run it on the server, cloud, or desktop of your choice.

REST API Product Updates

Weekly Digest