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
    Connect
    Waits for a connection to be established with the server.
    Disconnect
    Waits for the MQTT client to finish any work it must do, and for the TCP/IP session to disconnect.
    Subscribe
    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




Sunday, January 1, 2017

Lesson 16: Playground-Arduino Blocks

Screenshot_54
Arduino blocks set can be used with Arduino Mega or Arduino Uno with the help of MagicWiFiShield . Following blocks are available,
  • Digital in
  • Analog In
  • Digital Out
  • PWM (Analog Out)
  • Servo
  • Serial In
  • Serial Out
  • DS1820
  • LCD16x2Out

This block set enables you to control individual pins of the Arduino from the playground. The functionality of each block is described below:
How to configure Arduino
To work with arduino blocks you need to upload following sketch to ardunio.Then connect MagicWifiShield to the arduino.
How to attach a device
Every block has a property called Device ID where you need to specify to which device this block belongs to. This is important because you will be working with multiple devices in a typical IoT project. To control a device (eg: Arduino) via the playground you need to add the device as in Lesson 3 and if you have already done so, attach it to the playground according to the description below.
To attach a device ID for the first time, select 'Add new arduino-board' and click the edit button as shown below. If you have already added the device as in Lesson 3, it will be visible to you in the dropdown and you can select the device from there.

Screenshot_55
In the next dialog click the search button which will display all your added devices. Select the device you want to add and click 'Add'. Once you have added a device you can select it from the dropdown in the respective node.
Screenshot_56
Screenshot_57
Every blue color block have property called Pin which will identify specific pin of the Arduino.

1. Digital In


FotorCreated_thumb4
This block will read Input status of a pin. Block need to triggered to get input status. Any input will serve as a trigger. Inject node can be used for this purpose.Input status can be passed to a another block or viewed on the debug window.
  • Configuration:
    • Pin: pin number of the digital pin to read (Required)
    • Name: Any name desired
  • Input
    • Any input. Used as a trigger
  • Output
    • Value of the pin as 1 or 0 in the following format and the pin number as the topic
      • eg: {"payload": 1 , "topic": "2"}
[{"id":"2992d39.d0af72c","type":"inject","z":"ce37cda6.eebb4","name":"","topic":"","payload":"","payloadType":"none","repeat":"1","crontab":"","once":false,"x":458.09942626953125,"y":809.54541015625,"wires":[["390fb40b.32758c"]]},{"id":"390fb40b.32758c","type":"Digital In","z":"ce37cda6.eebb4","name":"","pin":"13","arduino":"","x":618.9545440673828,"y":808.2301073626056,"wires":[[]]},{"id":"b5081d9d.4c3fc","type":"comment","z":"ce37cda6.eebb4","name":"Set MagicWiFiShield ID","info":"","x":622.9601898193359,"y":756.4090270996094,"wires":[]}]

2. Digital Out


FotorCreated2_thumb1
This block is used to set a digital output pin to 1 or 0 based on the input. An input of 1 or true will make the configured pin go HIGH and vice versa
  • Configuration
    • Pin: pin number of the Digital pin to write to
    • Name: Any name desired
  • Input
    • Value to be written to the pin. Accepts 1 (true) or 0 (false)
      • eg: {"payload": 1}
[{"id":"b5081d9d.4c3fc","type":"comment","z":"ce37cda6.eebb4","name":"Set MagicWiFiShield ID","info":"","x":622.9601898193359,"y":756.4090270996094,"wires":[]},{"id":"540c63cd.4951dc","type":"inject","z":"ce37cda6.eebb4","name":"","topic":"","payload":"1","payloadType":"string","repeat":"1","crontab":"","once":false,"x":387.09942626953125,"y":771.54541015625,"wires":[["ec667bf9.daf2f8"]]},{"id":"988aa6e.a7f1658","type":"inject","z":"ce37cda6.eebb4","name":"","topic":"","payload":"0","payloadType":"string","repeat":"1","crontab":"","once":false,"x":387.09942626953125,"y":851.54541015625,"wires":[["ec667bf9.daf2f8"]]},{"id":"ec667bf9.daf2f8","type":"Digital Out","z":"ce37cda6.eebb4","name":"","pin":"13","arduino":"","x":578.9545440673828,"y":813.6846361711994,"wires":[]}]

3. Analog In

Screenshot_10_thumb2
This block will read analog value of the ADC pin of the module. Similar to the digital in block you need to trigger the block to read the value. Any input sent to the block will serve as the trigger.
  • Configuration:
    • Pin: pin number of the analog pin to read (Required)
    • Name: Any name desired
  • Input
    • Any input. Used as a trigger
  • Output
    • Value of the pin from 0 to 1024 and the pin number as the topic with prefix A
      • eg: {"payload": 965, "topic":"A0"}
Notes
  • ADC value range 0-1024
[{"id":"b5081d9d.4c3fc","type":"comment","z":"ce37cda6.eebb4","name":"Set MagicWiFiShield ID","info":"","x":622.9601898193359,"y":756.4090270996094,"wires":[]},{"id":"7de26fe6.97ca1","type":"inject","z":"ce37cda6.eebb4","name":"","topic":"","payload":"1","payloadType":"none","repeat":"1","crontab":"","once":false,"x":436.09942626953125,"y":797.54541015625,"wires":[["173bd9b1.b34b46"]]},{"id":"173bd9b1.b34b46","type":"Analog In","z":"ce37cda6.eebb4","name":"","pin":"0","arduino":"","x":596.9601898193359,"y":797.0511169433594,"wires":[[]]}]

4. PWM (Analog Write)

Screenshot_11_thumb2
This block outputs PWM signal from the selected pin
  • Configuration:
    • Pin: pin number for the PWM signal (Required)
    • Name: Any name desired
  • Input
    • value from 0 to 100
      • eg: {"payload": 55}
[{"id":"b5081d9d.4c3fc","type":"comment","z":"ce37cda6.eebb4","name":"Set MagicWiFiShield ID","info":"","x":622.9601898193359,"y":756.4090270996094,"wires":[]},{"id":"9870769e.7c4558","type":"inject","z":"ce37cda6.eebb4","name":"","topic":"","payload":"150","payloadType":"string","repeat":"1","crontab":"","once":false,"x":427.09942626953125,"y":800.54541015625,"wires":[["30605786.7b12c8"]]},{"id":"30605786.7b12c8","type":"PWM","z":"ce37cda6.eebb4","name":"","pin":"13","arduino":"","x":602.9601898193359,"y":801.4942932128906,"wires":[]}]

5. Servo


Screenshot_14_thumb2

This block can be used to control a servo motor with the MagicWiFi module.
  • Configuration:
    • Pin: pin number to which servo motor is attached (Required)
    • Name: Any name desired
  • Input
    • value from 0 to 180 translating from 0 degrees to 180 degrees for servo motor shaft rotation.
      • eg: {"payload" : 120}
[{"id":"b5081d9d.4c3fc","type":"comment","z":"ce37cda6.eebb4","name":"Set MagicWiFiShield ID","info":"","x":622.9601898193359,"y":756.4090270996094,"wires":[]},{"id":"5ba60a66.066754","type":"inject","z":"ce37cda6.eebb4","name":"","topic":"","payload":"0","payloadType":"string","repeat":"1","crontab":"","once":false,"x":400.09942626953125,"y":759.54541015625,"wires":[["a57faf7b.d036f"]]},{"id":"273e4568.eb5b4a","type":"inject","z":"ce37cda6.eebb4","name":"","topic":"","payload":"90","payloadType":"string","repeat":"1","crontab":"","once":false,"x":400.09942626953125,"y":839.54541015625,"wires":[["a57faf7b.d036f"]]},{"id":"a57faf7b.d036f","type":"SERVO","z":"ce37cda6.eebb4","name":"","pin":"12","arduino":"","x":593.9545440673828,"y":808.8692980364337,"wires":[]}]

6. Serial In

Screenshot_15_thumb2

The Serial In block will output anything written to the RX1 of the Arduino Mega module at 115200 baud. You do not need to trigger the module as the data will be delivered in real time.
  • Configuration:
    • Name: Any name desired
  • Output
    • data read from the serial RX0 pin of the MagicWiFi module and the topic as 0x63 to indicate a serial read
      • eg: {"payload": "Your Serial Data Buffer","topic": 0x63}
[{"id":"b5081d9d.4c3fc","type":"comment","z":"ce37cda6.eebb4","name":"Set MagicWiFiShield ID","info":"","x":622.9601898193359,"y":756.4090270996094,"wires":[]},{"id":"902df20b.29dd5","type":"debug","z":"ce37cda6.eebb4","name":"","active":true,"console":"false","complete":"false","x":768.0994262695312,"y":806.54541015625,"wires":[]},{"id":"6f554e89.762f2","type":"Serial In","z":"ce37cda6.eebb4","arduino":"","x":539.9545440673828,"y":806.3096008300781,"wires":[["902df20b.29dd5"]]}]

7. Serial Out



Screenshot_16_thumb2


The serial out block will write anything you send to the TX1 of the Arduino Mega at 115200 baud.
  • Configuration:
    • Name: Any name desired
  • Input
    • data to be written to the serial pin
      • eg:
        • To write a string ==> {"payload": "Your Serial Data to be sent"}
        • To write a byte buffer ==> {"payload": buffername}
[{"id":"b5081d9d.4c3fc","type":"comment","z":"ce37cda6.eebb4","name":"Set MagicWiFiShield ID","info":"","x":622.9601898193359,"y":756.4090270996094,"wires":[]},{"id":"c471d62.9aab828","type":"inject","z":"ce37cda6.eebb4","name":"","topic":"","payload":"Hello","payloadType":"string","repeat":"","crontab":"","once":false,"x":393.09942626953125,"y":798.54541015625,"wires":[["41b1f794.58bef8"]]},{"id":"41b1f794.58bef8","type":"Serial Out","z":"ce37cda6.eebb4","x":586.9545135498047,"y":800.1249694824219,"wires":[]}]