© 2017 Avnet. All rights reserved. All trademarks and registered trademarks are the property of their respective owners. All specifications are subject to change without notice.

NOTICE OF DISCLAIMER: Avnet is providing this design, code, or information "as is." By providing the design, code, or information as one possible implementation of this feature, application, or standard, Avnet makes no representation that this implementation is free from any claims of infringement. You are responsible for obtaining any rights you may require for your implementation. Avnet expressly disclaims any warranty whatsoever with respect to the adequacy of the implementation, including but not limited to any warranties or representations that this implementation is free from claims of infringement and any implied warranties of merchantability or fitness for a particular purpose.

Zentri to IBM Bluemix Notifications and Visualizations By Bryan Chen

This application demonstrates the Avnet BCM4343W IoT board connected via IBM Watson IoT to additional Bluemix cloud services.

This “Recipe” procedure is partitioned into the following sections:

Requirements:

- Avnet BCM4343W IoT Starter Kit

- ZentriOS SDK, (version 3.2.0.2 or later)

- A Serial console application (such as TeraTerm or Putty) - IBM Bluemix Account

1) Set up your Zentri Application (ZAP) 2) Verify! - Using IBM QuickStart Charting Webpage 3) Set up your Bluemix Environment 4) Create your Bluemix IoT Application 5) Wire your Bluemix Functionality using Node-RED 6) Verify! - Using Node-Red Debug Monitor 7) Register your device in Bluemix Services 8) Create a Custom Dashboard 9) Create Cards for the Dashboard 10) Verify! - Using custom Dashboard Display 11) Create a Device Schema for Email Alerts 12) Create an Email Alert Rule 13) Verify! - Using Email Notification Alerts 14) Configure Cloudant Database Services 15) Configure NodeRED to Connect with Cloudant 16) Verify! – Using Cloudant Databasing

Page 2

Application Description We start by making edits to the C source code to support the onboard light sensor. The ZAP is then compiled and programmed onto the Avnet board. First time execution requires the network credentials to be entered (from the command-line, in serial console) for local WiFi access point, after which the ZAP reboots and connects to IBM Watson IoT’s MQTT broker, which also provides visual verification of the received data on IBM’s Quickstart Charting webpage. The user then defines custom rules and “wiring” from the IoT device to other IBM Bluemix services using Node RED, a visual editor. Node-RED’s built-in debug monitor is used here for further verification. A custom dashboard is implemented using Bluemix’s concept of ‘boards’ and ‘cards’. First, a ‘board’ (dashboard) must be created to host the cards (ie. widgets: line graphs, donut charts, gauges etc.), which then provide multiple options for visualizing the data. Email alerts are set-up by creating a device schema to extract attributes from incoming measurement data. An IF-THEN rule defines a light sensor threshold and destination email address. Shining a light on the light sensor will trigger an email alert to be generated. The native Bluemix application comes with a database service called Cloudant. After proper configuration, a Cloudant node is inserted into the Node RED code to direct data to be collected by the database. Cloudant provides various services for data analysis.

Instructions PART 1 – Bluemix Quickstart Charting

1. Set up your Zentri Application (ZAP)

a. If not already installed, download and install the latest version of ZentriOS (link posted at end of this tutorial).

b. Connect a USB cable from the Avnet BCM4343W IoT Starter Kit to your computer. Select the “ZentriOS” tab on the top bar and click “Setup Device and SDK”. Select the appropriate version when prompted and click “Finish” when complete.

c. To create the program, right click in the project explorer new -> ZentriOS Project.

d. Give it a name and click ‘next’ – you will be directed to the following window. Find the ‘bluemix’ folder under the ‘cloud’ folder and double click to ‘Create Project’ at the bottom. You should now see this in your workspace.

Page 3

e. Because the firmware is written to output ‘temperature’ readings, you will need to edit the code to change the output to ‘light sensor’ readings. Locate line 325 of ‘bluemix.c’ and replace ‘temperature_buffer’ with ‘light_sense_buffer’.

char light_sense_buffer[16];

f. Next, comment out line 330 of the code and replace it with the following code:

uint16_t adc_raw = 0, light_value = 0;

g. Lastly, comment out the if-else statements in lines 340-351 to replace it with the following code. Remember to save your changes.

if (ZOS_FAILED(result, zn_adc_direct_sample(adc, &adc_raw)))

{

ZOS_LOG("Failed to read converted ADC sample! Error code %d", result);

}

else

{

light_value = (4095 - adc_raw);

int_to_str(light_value, light_sense_buffer);

// Publish the converted ADC sample to MQTT queue //

sprintf((char*)settings.message, MQTT_MESSAGE, rssi_buffer, light_sense_buffer);

mqtt_app_publish(NULL);

}

h. Now locate the ‘common.h’ file to change line 16 to the following and save your changes.

#define MQTT_MESSAGE "{\"d\":{\"signal strength\": %s, \"light_sensor\": %s}}"

i. Making sure that you are in the ‘Resource’ perspective, right click on the bluemix project, select “ZentriOS”, then click “Build / Download / Run”.

Page 4

j. After successful build and download of this application to the hardware, open a serial console application to view the output from the hardware (Make sure the correct COM port is selected, Baud rate = 115200, other settings = 8N1N).

k. You will need to provide the WiFi network settings to your board from this serial console. Start with a mouse click on the console window, press the enter key once to enter command mode, then type “network_up -s” into the console.

l. Locate your network and its ‘#’ on the list that appears. Enter your network number into the console followed by the password. Once connected, type “save” to have the device remember the network.

TROUBLESHOOTING: If you are having issues connecting your board to local WiFi, try utilizing a mobile hotspot instead.

m. Press the reset button on the board or type ‘reboot’ into the console to reboot the program.

n. Store the Device ID (highlighted in figure below) reported by the serial console somewhere accessible for later use.

2. Verify! - Using IBM QuickStart Charting Webpage

a. Verify that your board is publishing correctly at this point by using the IBM QuickStart charting webpage. Simply enter the following link into your browser, accept IBM’s terms of use, then enter your Device ID to view published board readings.

https://quickstart.internetofthings.ibmcloud.com/

Page 5

b. Click on light_sensor (under the Datapoint sources listed), and observe the chart that then displays. (values between 0 and 4000, that change when a shadow is cast on the light sensor, indicate proper operation)

c. Click on signal_strength to have the chart switch to displaying the reported RSSI WiFi signal strength -dBm values. (shielding the wireless module by cupping your hand over it should increase the negative -dBm values reported)

TROUBLESHOOTING: If any negative values appear for the light_sensor reading, check again to see if you modified the code correctly.

Page 6

PART 2 – Node RED Debugging

3. Set up your Bluemix Environment

c. Register and log on to the IBM Bluemix site: https://console.ng.bluemix.net/

d. Make sure the region is selected as “US South” and enter a unique organization name.

e. Next, give a unique name for your first space and click “I’m Ready” when complete.

4. Create your Bluemix IoT Application

c. You should now be redirected to the console page of IBM Bluemix:

https://console.ng.bluemix.net/dashboard/apps/

d. Scroll down and click on the “Take Advantage of IoT” box.

e. Give your application a unique name, leave the rest of the fields as is, then click “create”.

f. Give Bluemix 2-10 minutes to start your application. You will see the status change to indicate this.

Page 7

5. Wire your Bluemix Functionality using Node RED

a. Click on “Visit App URL” next to the name to access the Node RED editor home page.

b. Click through the ‘Secure your Node-RED editor’ dialog, based on your preferences.

c. When complete, click the red “Go to your Node-RED flow editor” button.

d. You should now see two default “flows”. Double click the node called “IBM IoT App In” to edit.

e. Enter in your device ID to the appropriate box and make sure the Authentication is set to “Quickstart”, then press “Done”.

f. In your Node RED flow editor, click the tiny box to the right end of the “IBM IoT App In” Node to create a wire, then drag this wire to connect it to the “Device Payload” node.

Page 8

g. Double click the “Device payload” Node to edit its properties and overwrite all of the pre-existing code with the following:

msg = {payload: JSON.stringify(msg.payload)};

return msg;

h. Edit the “Send to IBM IoT Platform” node and make the highlighted changes (add your own unique Device Id).

6. Verify! - Using Node-Red Debug Monitor

a. Click on the Deploy button (top right corner) to execute your Node-RED changes.

b. Immediately below this button, (2nd tab of Node-RED right-side panel) is the debug monitor which allows you to monitor one or more Debug nodes within your Node RED flow. To begin, make sure your board is currently publishing to Watson IoT (ie. step 2 of this recipe), then click on the ‘debug’ tab.

Page 9

c. You should now see published data in the debug console (what is displayed depends on which debug monitors are enabled). To clear this panel, click on the trash bin icon.

d. The debug monitor displays the JSON info that reaches whichever debug nodes are presently enabled. Enable/Disable debug nodes by clicking the small tab that sticks out right-side of each debug node (grey = OFF, green = ON).

Page 10

PART 3 – Custom Dashboard Display 7. Register your Device in Bluemix Services

a. Go to your Bluemix console page and scroll down to select the appropriate iotf service.

https://new-console.ng.bluemix.net/#all-items

b. Click on “Launch” to access your Bluemix Services dashboard.

c. Hover your mouse over the icons to the left to open up the pop-out menu, then select “Devices”. Click “Add Device” in the top right corner of the screen.

d. Click on “Create device type”, then click “Create device type” again.

Page 11

e. Enter “ZentriDevice” for the Name and add an optional description and click next to skip through rest of the windows until you reach the last page - Metadata. Click “Create” and you should now see a “ZentriDevice” device type.

f. Click “Next” and enter in your “zentri_XXXX” device ID from earlier. Skip through the remaining windows and click the “X” when finished.

8. Create a Custom Dashboard

g. Now you will need to create a new “board” (dashboard). Hover your cursor on the left side of the screen until the pop out menu appears, then select “Boards”. This will load a new page with all of your dashboards - click on “Create New Board” in the top right corner of the screen.

h. Enter a name for your board and an optional description.

i. Click on “Next” when complete and then click on create. Your newly created board should now appear accordingly.

9. Create Cards for the Dashboard

j. To view the data coming from your board, you will need to create “cards”. Double click on your board and add a new card.

Page 12

k. Select “Realtime chart” under “Devices”.

l. You should see the registered device under the devices tab - select it and click “Next”.

m. Click “Connect new data set”.

n. Fill in the fields as follows.

Page 13

o. Choose a Size, Title, Description and Color Scheme for your Line Graph then continue. Size L or XL is recommended for better viewing.

p. Repeat this exercise creating an additional card (this time choose the gauge widget) for

RSSI Signal Strength.

10. Verify! - Using custom Dashboard Display

a. Once your card is set up, try applying a light on the light sensor of the Avnet board to test your dashboard display! Change the timing increment on the bottom left of the line chart.

Page 14

PART 4 – Email Notification Alerts 11. Create a Device Schema for Email Alerts

a. Hover your cursor on left side of the screen until the pop-out menu appears, then select “Devices” .

b. Select the “Manage Schemas” tab on the top menu to create a device schema.

c. Click “Add Schema” In the top right corner, select “ZentriDevice” for your device type and press “Next”.

d. Click on “Add Property” and then select the “From Connected” tab, which will automatically import published properties. Check the box next to the “light_sensor” property and click ‘Finish’. This will allow the light sensor property to trigger alerts.

12. Create an Email Alert Rule

a. Hover your cursor over the icons to the left of the page to open the pop-up menu again. Select “Rules” and then click on “Create Cloud Rule”.

b. Enter a name for your rule, an optional description and select the “ZentriDevice” schema in the “Applies to:” box.

c. Click next when complete and you should see an “IF/THEN” Diagram. Click on the “New Condition” box and “Select Property” to choose the property for the condition, then click

Page 15

on the triangle icon next to “d” to open up a drop-down list of additional nested properties – select the “light_sensor” property.

d. Leave the operator as “>” and enter a reasonable value for the “Value:” box to compare whether the light is on or off.

e. Now select the “New action” box to create a response to the IF condition. Click on “Add Action” and give your action a unique name and description, then select “send email” for “Type”. Press “Next” when complete.

f. Edit the subject line if you wish, and select “Specific People” under the “To” header. Enter the email address you wish the notification to be sent to (You can also include additional CC email addresses).

Page 16

g. When complete, press ‘finish’ and double click the name of your action to select it. Click on “save” and “activate” on the top right corner of the main rule menu to start your email alert application.

13. Verify! - Using Email Notification Alerts

a. Hover your cursor over the left pop-out bar to go back to “Boards”. Select the “Rule-Centric Analytics” board.

b. You will now see several pre-built cards that display rule-related information. Shine a light on the light sensor to trigger the email notification rule and see how these cards react.

Page 17

c. Check your email to see the incoming notifications on changes to the light level. You may need to check your spam folder.

Page 18

PART 5 – Cloudant Databasing 14. Configure Cloudant Database Services

a. Hover your cursor on the left side of the screen until the pop out menu appears, then select “Extensions”. This will load new various extensions you can add to your application. Click on “Setup” under “Historical Data Storage”.

b. Select your application and a confirmation image should display like so. Click Done.

15. Configure NodeRED to connect with Cloudant

a. Now return to your NodeRED flow and insert the Cloudant end node into your flow in the following manner. This will store incoming data into your Cloudant database (the other Cloudant node is for retrieving stored data).

b. Configure your node with the following properties: Select the service you enabled earlier through extensions, enter ‘nodered’ for the Database and give your node a unique name. Hit “Deploy” when complete.

Page 19

16. Verify! – using Cloudant Databasing

a. Make sure your board is powered, then access your Cloudant Database by going back to console page to select the Cloudant service for your application.

b. Click on “Launch” to access your database on the following page. Select the Databases tab – you should only see one database called “nodered”.

c. Select “nodered” and you will see a list of entries corresponding to the messages published by your board. To view these entries in further detail, click on the pencil icon to the top right corner.

Page 20

d. You should now see the JSON code directly published by your board:

LINKS:

Avnet BCM4343W IoT Starter Kit: http://cloudconnectkits.org

ZentriOS SDK Download: https://docs.zentri.com/zentrios/wz/latest/sdk/user-guide/getting-started IBM Watson IoT QuickStart webpage: https://quickstart.internetofthings.ibmcloud.com/# IBM Bluemix Console Page https://new-console.ng.bluemix.net/

Author: Bryan Chen

With a passion for robotics and home automation, Bryan is a part-time EE/CS intern within Avnet's engineering team, while busy with full-time final year UCLA Electrical Engineering studies, focused on signals and systems.

He is a key contributor of reference designs, having published multiple applications using Avnet's versatile BCM4343W Wi-Fi & BT/BLE SoC module, taking-on challenging connectivity designs with BLE, cloud platforms and Alexa voice interfacing.

Page 21

Revision History

Date Version Revision

20 June 17 01 Initial Release