Powered by Blogger.

Tuesday, June 6, 2017

Lesson 18: MQTT Dash Mobile App with Magicblocks.io

Introduction to MQTT

MQTT stands for MQ Telemetry Transport and was designed and developed by IBM in 1999. The term MQ stands to represent IBM's MQ series message queue product line. It was designed to be a lightweight messaging protocol for the publish subscribe model running on top of TCP/IP. The publish subscribe architecture is a common message oriented communication paradigm where there is a broker in the middle for relaying messages to and from clients.

Important facts to note in the above diagram are that

  • Information streams are known as topics
  • A client can publish data to a topic. There can be more than one publisher per topic
  • Multiple clients can subscribe to a topic
  • A Broker in the middle facilitates the brokering or relaying of the messages.

MQTT defines several methods to indicate desired actions during communication
    Waits for a connection to be established with the server.
    Waits for the MQTT client to finish any work it must do, and for the TCP/IP session to disconnect.
    Waits for completion of the Subscribe or UnSubscribe method.
With these basic facts on MQTT in mind, lets see how the mobile application MQTT Dash can be used with magicblocks.io. Please note that MQTT Dash is not an app by magicblocks.io and we should be grateful to its authors for the free software. The objective of this lesson is to learn how we can integrate MQTT Dash with magicblocks.io to use its powerful and flexible user interface so that you can interact with your playground easily.

Step 1

Open your playground and place the 'mqtt' blocks in the input and output categories. These will be useful for communicating with the mobile app. The input node will be used as a data input source to the playground and the output node will act as a data output channel from the playground. To configure:

  • Double click on the MQTT node from Input category
  • Select 'Add new mqtt-broker' from the 'Broker' drop down menu
  • Click on the edit button on the right
  • In the new window that opens subsequently fill
    • Broker - test.mosquitto.org
    • Port - 1883
    • Leave ClientID, username, password as blank
  • Click Add. This will create a MQTT broker node and close the window.
  • In the MQTT in node configuration set the topic in the format magicblocks/{your username}/{topic name}. The topic name can be anything unique in your playground. eg: light1, temperature1.1
  • Click Done. Now your MQTT in node will be configured. You now have a MQTT node that is subscribed to the MQTT broker at test.mosquitto.org with the topic you selected. It is able to receive any message published on that topic to the broker by any client. Please note that test.mosquitto.org is a free service offered by mosquitto.org which is a very popular open source MQTT broker. This is a public broker and anyone will be able to subscribe to your topic and publish to that topic as well. Therefore this exercise is intended to be only a learning exercise on how MQTT works and how to integrate with MQTT dash. Do not utilize the same approach if you are building a real world application. You can use a paid MQTT broker plan by hivemq.com or other providers such as cloudmqtt.com
  • Connect the MQTT In block to a debug block to view the incoming messages in the debug panel

Step 2

 Now that your MQTT node is connected to the broker and is ready to receive messages you will now have to configure your mobile app to connect to the broker and send messages. MQTT dash is capable of both sending and receiving messages. i.e. it can both publish & subscribe to any topic. In this step we will focus only on publishing to the topic that we subscribed our node to in the previous step.

  • Install MQTT Dash on your Android smart phone from the Android playstore. You can find it here.
  • Open your application and click on the + icon in the top right corner to add a connection to an MQTT broker
  • Fill the following fields
    • Name - Any name to identify your connection. eg: My playground
    • Address: test.mosquitto.org
    • Port: 1883
    • You can leave all other fields blank
  • Click the save icon in the top right corner to save your connection. 
  • Back in the home screen you will see the connection 'My playground'. Click on that to go to your dashboard. Your dashboard is fully configurable which gives a lot of flexibility to your application. You can add widgets to control your devices, view stats etc. In this exercise we will see how to add a simple switch which will publish messages to your playground.
  • Click on the + icon in the top right corner to add a widget.
  • Choose type Switch/button
  • Fill the following fields
    • Name - Name to identify your widget. eg: Light 1
    • Topic - the topic that you configured in your MQTT node in the playground. eg: magicblocks/demo_user/light1
    • You can keep the default values in the other fields.
  • Click on the save icon in the top right corner
You will now have a widget on your dash which can publish messages via MQTT which will be received by your playground.

Toggle switch and you will see 0 and 1 messages appearing on your debug panel in the playground. Pretty neat right?

Step 3

By now you are able to publish from the mobile app and receive that message via the subscribed mqtt node in the playground. You can play around the app to customize the icons, widget and lots of other stuff. In this step learn how to publish from the playground and subscribe from the app.

  • Double click on the MQTT Output node
  • Now that you have already created a MQTT broker in Step 1 you can just select the broker in the dropdown menu.
  • Set the topic. eg: magicblocks/demo_user/temperature1
  • Leave other fields blank and click Done
  • Connect around 3 other inject nodes to send data to the MQTT output node

Now you have a setup to publish to the MQTT broker.

Step 4

In this step we will setup a widget in the MQTT dash to display the simulated temperature values we are sending.
  • Add a new widget of type 'Range/Progress'
  • Fill the following fields
    • Name: Any name you prefer eg: Temperature
    • Topic: the topic you configured in the MQTT Output node
    • Set Min & Max value to 10 & 50 to help see the variation more vividly
    • Leave all other fields in the default value
    • Click on the save icon
  • Now you will see the new widget on your dashboard
  • Click on the inject nodes in the playground and see your gauge getting updated instantly!

There are many many customizations you can do in MQTT dash. Its time to play on your own figure out the capabilities of MQTT dash. Stay in touch for future updates

Download App

Monday, June 5, 2017

Lesson 17: Device API

Magicblocks.io's device control API gives the developer more flexibility than ever before. The device API adds on to the rich set of features which are already offered by magicblocks.io as a visual design tool, data visualization tool and remote management tool.
Few facts to note about the device API are:

  • REST based API (running over HTTP)
  • Fully distributed system where your API is completely independent of other users giving security and isolation
  • Your playground should be up and running for you to use the API. If the playground is down or if the subscription has expired you will not be able to use the API.
With that in mind lets dive in!

Step 1

Login to your magicblocks.io account and go to the 'Manage Apps' page from the navigation bar.

You will see the API URL. This is the URL endpoint where your API is available. Simply this is the URL which you should call via HTTP to control your device. This URL will depend on your user account which means that each magicblocks.io account will have a unique API URL.

Step 2
To consume the API you should first create an application. To do so click on the 'New app' button and enter the details of your application. 

Fill in the above details to create your applications
  • Name of your application
  • Short description of your application. Both of them are for informative puposes.
  • API key - This is the key for consuming the API. It is important that this API key is held confidentially as this would be the authenticator for the API. You will need this in the next step
Save the changes and you are good to go!

Step 3

Now that you have created an application its time to start on the API calls. You will need to use a tool like postman which you find here. You can also find this as an add-on in the Chrome app store here. We will be using this tool in the rest of this lesson. After installing and opening postman select or fill out the following info:
  •  URL -  this is the endpoint URL for the operation you are intending to execute. The URL will take the form of : {API URL}/{device ID}/{operation name}/{args}. eg: http://c1.magicblocks.io:30002/device/id2-1476325874361/digitalOut/13/0 where
    • API URL - http://c1.magicblocks.io:30002/device 
      • This is displayed in your 'Manage Apps' window as seen in Step 1
    • device ID - id2-1476325874361 
      • This is the ID of the device you want to access
    • operation name - digitalOut
      • This is the operation you want to execute. You can find the list of available operations and the required arguments below.
    • args - 13 & 0
      • These are the parameters required for the operation. These parameters depend on the operation that is called and you will find the available operations the required arguments below
  • HTTP method - This is the HTTP method used to invoke the operation. This will depend on the operation you are executing. It can be one of
    • GET
    • POST
    • DELETE
    • PUT
  • API Key - This is the API key of your application which you created in the previous step. Go to 'Headers' tab and you will see a table with columns named 'key', 'value' & description. Enter 'api_key' under the 'key' column and the API Key in the 'value' column as shown below.
  • Body - You might need to send information in the body of the API call depending on the operation. If so click on the 'Body' tab below and enter the information according to the format defined in the list below. 

After setting all the parameters click on 'Send' and you will be able to call the magicblocks.io device API.

API Operations
  • List all devices - Get a list of all the devices and their details 
    • URL - {API URL}/list
      • eg: http://c1.magicblocks.io:30002/device/list
    • HTTP method - GET
    • Request body  - blank
    • Response - JSON formatted string containing a list of all available devices in the format {"Device ID":{"name":"Device name","status":"device status"}}
      • eg: {"1461552825753":{"name":"ATMega1","status":"Active"},"1461552825754":{"name":"uSeeker","status":"Active"}}
  • Get Device Status - Get the availability of a device
    • URL - {API URL}/{device ID}/status
      • eg: http://c1.magicblocks.io:30002/device/1461552825753/status
    • HTTP method - GET
    • Request body - blank
    • Response - JSON formatted string with following parameters
      • responseCode : possible values
        • 200 - device online
        • 410 - device offline
        • 404 - device not found. check if device ID in valid.
      • response
        • deviceId: your device ID
        • status : possible values
          • online
          • offline
  • Get Device Class - Get the device class of a given device. This query will enable your application to query the type of the device and assume its capabilities.
    • URL - {API URL}/{device ID}/class
      • eg: http://c1.magicblocks.io:30002/device/1461552825753/class
    • HTTP method - GET
    • Request body - blank
    • Response- JSON formatted string with following parameters
      • responseCode: possible values
        • 200 - device query successful
        • 410 - device offline
        • 404 - device not found. check if device ID is valid
      • response: if the device is online it will give a JSON formatted string with the device capabilities with following main parameters
        • mainClass - product or development board
          • DEV - development board
          • PROD - Deployment ready product
        • subClass - type of device
          • eg: MGW for magic WiFi
        • version - firmware version
        • description - description of the device
        • operations -supported operations, the HTTP methods used to access the operations and the pins they are available on. This will differ from device to device.
          • eg: status, class, digitalOut, analogOut
  • Digital Out - Write to a digital I/O pin as high or low
    • URL - {API URL}/{device ID}/digitalOut/{pin number}/{value}
      • pin number - the pin you want to write to
      • value - 
        • 0 - LOW
        • 1 - HIGH
    • HTTP method : POST
    • Request body - blank
    • Response body
      • responseCode 
        • 200 - success
  • Analog Out - Write to a analog PIN as PWM
    • URL - {API URL}/{device ID}/analogOut/{pin number}/{value}
      • pin number - the pin you want to write to
      • value -the PWM % you want to set. Should be a value between 0 and 100
    • HTTP method : POST
    • Request body - blank
    • Response body
      • responseCode 
        • 200 - success
  • Digital In - Read from a digital I/O pin 
    • URL - {API URL}/{device ID}/digitalIn/{pin number}
      • pin number - the pin you want to read from
    • HTTP method : GET
    • Request body - blank
    • Response body
      • responseCode 
        • 200 - success
      • response
        • device ID
        • pin
        • value
          • 0 - LOW
          • 1 - HIGH
  • Analog In - Read from a analog pin using the ADC 
    • URL - {API URL}/{device ID}/analogIn/{pin number}
      • pin number - the pin you want to read from
    • HTTP method : GET
    • Request body - blank
    • Response body
      • responseCode 
        • 200 - success
      • response
        • device ID
        • pin
        • value - a value between 0 and 1023
  • Serial Out - Write a data payload to the Serial port of the device
    • URL - {API URL}/{device ID}/serialOut
    • HTTP method : POST
    • Request body - JSON formatted string with the following parameters
      • payload - This is the data that you want to write to the serial port. This data should be base64 encoded. You can send any ASCII or binary sequence
        • eg: {"payload":"dGVzdA=="}
    • Response body
      • responseCode 
        • 200 - success
  • Serial In - Read from the Serial port of the device. This is an asynchronous method where you register a callback URL and you can receive data on your callback URL. You only need to call this once in your application. However this is an idempotent operation which means multiple invokations will not have any difference
    • URL - {API URL}/{device ID}/serialIn
    • HTTP method : POST
    • Request body - JSON formatted string with the following parameters
      • callback - this is the URL in your application that you want to be called when data is received on the Serial Port. The callback URL call will be as follows:
        • HTTP method: POST
        • Request body: 
          • body: 
            • responseCode
              • 200
            • device ID
            • payload - Base64 encoded data received on Serial port
    • Response body
      • responseCode 
        • 200 - success