App-to-Thing Starter Guide

In the Basic and Advanced Starter guides, the Thing-to-App flow was used in building the pipeline to demonstrate how enriched and processed device data are transmitted to an application. For this tutorial, we will use the App-to-Thing flow to demonstrate how to send messages or commands from an application to a configured device.

Register a Device

For this tutorial, we will also be using the same registered device used in the Basic and Advanced Starter guides. However, we also need to add another device for sending commands to a device group.

Using what you have learned from the Basic Starter Guide, register a new device.

After you have registered the new device, associate a device group to both of your devices to allow you to send messages for the whole group of devices to perform. To associate a device group to devices, perform the following steps:

1. Navigate to Device Groups on the left navigation pane then click New Device Group.
2. Enter a name for your device group then click Create Device Group. After you have successfully created a device group, you can now associate devices to your device group.
3. Navigate to Devices on the left navigation pane.
4. Select the checkbox of your devices then select Actions > Attach Group.

Note: For more information on how to manage devices, refer to the Device Management articles. 

After you have configured your devices, you can proceed on pinning new plugins that we will be using to build the App-to-Thing flow in the pipeline.

Pin Plugins

To demonstrate how to send real-time device data to an application as well as allow the application to send messages and commands to a device or group of devices, pin the Websocket Channel plugin.

1. From the Marketplace page, click the Channel tab.
2. Hover the mouse over the Websocket Channel plugin then click Pin from the pop-up dialog.

After you have pinned the plugin, create an App-to-Thing pipeline.

Build a Pipeline

1. From the navigation menu, select Pipeline Studio then click Create a new Pipeline from the pop-up dialog that displays. The Pipeline Studio page displays with your pinned plugins displayed on the left pane.
2. Using what you have learned from the Basic Starter Guide, drag and drop the MQTT Gateway, Websocket Channel, and Command Relays plugins onto the design canvas then configure each plugin. Note that Command Relay is pinned by default under the Other category and is used to broadcast the command to specific device or group of devices.Note: Configuration details vary from plugin to plugin depending on the details needed to run the functions of the plugin. Refer to the plugin's online help for information on how to configure the plugin.
3. After you have configured the plugins, connect them by dragging the output terminal of one plugin to the input terminal of another plugin as shown from the example below:
4. Click the drop-down menu beside the Save as Draft button then select the Save & Deploy option.
5. From the Save Pipeline dialog, enter a name and description for the pipeline then click Save.

Connect to the Websocket Channel

In order to connect to the Websocket Channel plugin, you must first install a Websocket client simulator. For this tutorial, we will use the Dark WebSocket Terminal.

1. Go to the Chrome Web Store then click Add to Chrome.
2. Click Add app to confirm installation.  
3. After installation, open the Dark WebSocket Terminal chrome application.
4. From the command field below the terminal, enter the generated IP address and port number for the Websocket Channel plugin using the following format:
   

   /connect ws://<Generated Websocket Channel IP Address>:<Generated Websocket Channel Port>/

   Note: To view the generated IP address and port number for Websocket Channel, hover your mouse over the plugin or double-click the plugin.
5. Press Enter or click the arrow icon beside the command field to proceed. If successful, a Connection established message will be displayed in the terminal.

Connect and Send Device Data to MQTT Gateway

After you have connected to the Websocket Channel, you must now connect your device to the MQTT Gateway to be able to send device data. Note that you must create a connection for both of your devices.

1. Open the MQTTBox then click Create MQTT Client.
2. Provide the following MQTT Client Settings:
   • MQTT Client Name - Enter a name for the device connection.
   • MQTT Client ID - Enter the device ID.
   • Protocol - Select the protocol as mqtt/tcp.
   • Host - Enter the IP address and port generated for the Gateway.
3. Click Save to complete your connection. After connection have been established for both of your devices, you must also subscribe these devices in order to view the messages coming from the Websocket Terminal.
4. Open the connection for one of your devices then perform the following steps to subscribe your device:
   • From the Topic to subscribe field, enter the device ID of your device.
   • Click Subscribe.
     Note: Do the same procedure to your other device.
5. After you have subscribed both of your devices, you can start sending device data using any of your device connection by providing the following details:
   • Topic to publish - Enter the Data Topic displayed from the MQTT Gateway plugin. Default value is reekoh/data.
   • Payload Type - Ensure that Strings/JSON/XML/Characters option is selected.
   • Payload - Enter the device data to be sent to the MQTT Gateway plugin. Note that the data must be in JSON format.
6. Click Publish to complete sending the device data to the MQTT Gateway. A Data Received message will be displayed in the Subscription section.

Verify Data

To verify if the data was successfully sent to the MQTT Gateway and was received by the Websocket Channel plugin, open the Dark WebSocket Terminal. If successful, a received message will be displayed in the terminal along with the device data sent from MQTTBox. 

Now that we have verified the device data going to the application, let us now verify the commands or messages coming from the application going to the device using Device ABC and Device XYZ as examples.

Sending Command to a Device 

1. From the Dark WebSocket Terminal, enter a command using the following format:
   

   {"type":"<message event>","command":"<message or command>","targetDevices":"<device ID>","targetDeviceGroups":"<device group device ID>"}

   • type - Message event you specified for the Websocket Channel plugin.
   • command - Any message or command you want to send to the device or the device group.
   • targetDevices - Device ID of the target device.
   • targetDeviceGroups - Device ID of the target device group.
2. Press Enter or click the arrow icon beside the command field to send the command. A confirmation that the command has been sent will be displayed in the terminal. 
   Note: For the purpose of this tutorial, the targetDeviceGroups is left blank.
3. To verify if the command was received by the device, go to the MQTTBox then open the connection for the device. If successful, the command sent from the Dark WebSocket Terminal will be displayed in the Subscription section.

Sending Command to a Device Group

1. Using the same command format, enter your device group command in the Dark WebSocket Terminal. Note that for this scenario, the targetDevices must be blank instead of the targetDeviceGroups so that the command will be sent to all devices associated to the device group instead of a specific device only.
2. Press Enter or click the arrow icon beside the command field to send the command. A confirmation that the command has been sent will be displayed in the terminal.
3. Go to the MQTTBox then open the connection for the devices associated to the device group. If the command was successfully received by the devices, the command sent from Dark WebSocket Terminal will be displayed.
   
   Device ABC
   
   Device XYZ