Kit setup

Overview

These example applications demonstrate how Nordic's IPv6 stack and the smartCoAP library can be used to talk to a cloud service. A protocol extension for CoAP enables CoAP clients to observe resources and retrieve updates from a server about changes in the representation of a resource. In Exosite's service a dataport corresponds to a resource.

One of the example applications can periodically update the state of a dataport, while the other one can receive notifications about these updates. A dataport in Exosite's service is uniquely identified with the following parameters through the CoAP API of the service:

• dataport alias;
• Client Interface Key (CIK).

These parameters need to be hardcoded in the main.c file of both applications. After creating an Exosite account, use your private CIK to update the examples. For a more detailed description, please study the documentation of Exosite's CoAP API.

Note

To communicate with the cloud service, IPv6 global connectivity is required for the applications.

The setup of the example applications is presented in Figure 1.

Figure 3: Setup of the Exosite example applications.

The result of message exchanges is transmitted through the serial device and a terminal program (for example PUTTY) can be used to monitor the COM port of each development kit through a terminal session.

The sequence of messages exchanged between the example applications and the servers is shown in Figure 2.

Figure 2: Message Sequence Chart.

Data Source Application

This application serves as a data source sending periodic updates with simulated data to a resource in the cloud service.

The hostname of the Exosite server and the IPv6 address of a DNS server are hardcoded in main.c. Pressing Button 1 once enables periodic updates of the dataport on the server with simulated data. Before the first update, the hostname of the server is resolved to an IPv6 address. Once the response from the DNS server is received, a CoAP POST request is sent.

The result of the CoAP requests is transmitted through the serial device and a terminal program (for example PUTTY) can be used to monitor the COM port through a terminal session. If the request is successful, a new datapoint is registered on the server and appears in the widget on the web interface (Figure 3).

Figure 3: Datapoints on the web interface.

Common module dependency and usage

This section summarizes the usage of nRF5x resources and common modules in the examples apart from the IoT 6lowpan and IPv6 stack library.

Module	Inclusion/Usage	Description
Timer	2	Two timers are used one for IoT timer, and second for buttons
Buttons	1	Buttons are used for initiating CoAP requests. See Button assignments section for details.
LEDs	4	LEDs are used to indicate the application states. See LED assignments section for details.
Adv Data Encoder	Yes	The device name used is 'ExositeDataSrc', IPSP Service UUID is included in the UUID list.
Scheduler	Yes	Scheduler is used for processing stack events.
UART Trace	Included not enabled	Tracing is included but not enabled by default.

Setup

The source code and project files of the example can be found in the following folder:
<InstallFolder>/examples/iot/cloud/coap/data_source

LED assignments

LED 1	LED 2	LED 3	LED 4
Blinking	Off	Off	Off	Device advertising as BLE peripheral.
On	Blinking	Off	Off	BLE link established, IPv6 interface down.
Off	On	Off	Off	IPv6 interface up, periodic requests disabled.
Off	On	Blinking	Off	Device busy: DNS query sent, hostname resolution in progress.
Off	On	On	Off	Periodic CoAP POST requests enabled.
Off	On	On	Blinking	Device busy: CoAP request sent, awaiting response.
On	On	On	On	Assertion failure in the application.

Button assignments

Button 1
Toggle periodic CoAP requests.

Note

If commissioning is enabled, additional LED and Button assignments are made.

Testing

See Connecting devices to the router for a list of relevant Linux commands.

1. Compile and program the application. Observe that the device is advertising.
2. Prepare the Linux router device by initializing the 6LoWPAN module.
3. Discover the advertising device by using the hcitool lescan command.
4. Connect to the discovered device from the Linux console using the Bluetooth 6LoWPAN connect command.
5. Check if the connected state is reflected by the LEDs (LED 2 is ON).
6. Ensure that the kit has an IPv6 Internet connection.
7. Push Button 1 on the kit and keep an eye on your terminal window.
8. Observe that the result of the hostname resolution is displayed. If the response is delayed, LED 3 will be blinking. If the hostname resolution was successful, periodic CoAP requests will be sent.
9. Observe that the CoAP responses are displayed. If a response is delayed, LED 4 will be blinking.
10. Check the widget on the Exosite Portal's web interface to see new datapoints plotted.
11. Push Button 1 again on the kit.
12. Observe that LED 3 is off and no more CoAP requests are sent.
13. Disconnect from the device by using the Bluetooth 6LoWPAN disconnect command.
14. Observe that LED 1 is blinking and that the device is advertising.

Observer Application

This application observes a resource in the cloud service.

The hostname of the Exosite server and the IPv6 address of a DNS server are hardcoded in main.c. Pressing Button 1 once sends a subscription request to the dataport on the server. Before the first subscription, the hostname of the server is resolved to an IPv6 address. Once the response from the DNS server is received, a CoAP GET request with the Observe option is sent. If the subscription is successful, the server will send a notification to the kit each time the dataport is updated by the data source application. The value from each notification is printed in a new line to give a representation of the data. The following is an example of a UART log excerpt:

[APPL]: Response to subscription request received.
[APPL]: Response Code : 69
[APPL]:                                  *
[APPL]:                                         *
[APPL]:                                                *
[APPL]:                                                    *
[APPL]:                                                     *
[APPL]:                                                    *
[APPL]:                                                *
[APPL]:                                         *
[APPL]:                                  *
[APPL]:                           *
[APPL]:                    *
[APPL]:                *
[APPL]:               *
[APPL]:                *
[APPL]:                    *
[APPL]:                           *
[APPL]:                                  *

Note

The application expects the dataport values in the notifications to be integers in the range of -20 to +20.

Common module dependency and usage

This section summarizes the usage of nRF5x resources and common modules in the examples apart from the IoT 6lowpan and IPv6 stack library.

Module	Inclusion/Usage	Description
Timer	2	Two timers are used one for IoT timer, and second for buttons
Buttons	1	Buttons are used for initiating CoAP requests. See Button assignments section for details.
LEDs	4	LEDs are used to indicate the application states. See LED assignments section for details.
Adv Data Encoder	Yes	The device name used is 'ExositeObserver', IPSP Service UUID is included in the UUID list.
Scheduler	Yes	Scheduler is used for processing stack events.
UART Trace	Included not enabled	Tracing is included but not enabled by default.

Setup

The source code and project files of the example can be found in the following folder:
<InstallFolder>/examples/iot/cloud/coap/observer

LED assignments

LED 1	LED 2	LED 3	LED 4
Blinking	Off	Off	Off	Device advertising as BLE peripheral.
On	Blinking	Off	Off	BLE link established, IPv6 interface down.
Off	On	Off	Off	IPv6 interface up, periodic requests disabled.
Off	On	Blinking	Off	Device busy: DNS query sent, hostname resolution in progress.
Off	On	On	Off	Observing dataport resource.
Off	On	On	Blinking	Device busy: CoAP request sent, awaiting response.
On	On	On	On	Assertion failure in the application.

Button assignments

Button 1
Start observing resource.

Note

If commissioning is enabled, additional LED and Button assignments are made.

Testing

See Connecting devices to the router for a list of relevant Linux commands.

Ensure that the dataport in the cloud service is updated repeatedly by the data source application. If only one kit is available, use the code below to start a simple Python program that updates the dataport through Exosite's HTTP API. The dataport can also be updated manually through Exosite Portal's web interface.

import httplib
import urllib
import time

SERVER_HOSTNAME = r'm2.exosite.com'
HTTP_PORT       = 80
URL             = r'/onep:v1/stack/alias' 
CIK             = <Your CIK here as a string>
DATAPORT_ALIAS  = <Your dataport alias here as a string>
HEADERS         = {'X-Exosite-CIK': CIK, 'content-type': 'application/x-www-form-urlencoded; charset=utf-8'}

if __name__ == '__main__':
    data_offset  = 20
    n_datapoints = 0
    data_value   = 0
    data_sign    = 1
    while True:
        conn = httplib.HTTPConnection(SERVER_HOSTNAME, HTTP_PORT)
        params = urllib.urlencode({DATAPORT_ALIAS: str(data_value-data_offset)})
        conn.request('POST', URL, params, HEADERS)
        res = conn.getresponse()
        print res.status, res.reason # Expected: 204 No Content
        n_datapoints += 1
        if (n_datapoints == 50):
            break
        data_value += (data_sign * 4)
        if ((data_value % (20 + data_offset)) == 0):
            data_sign = data_sign * -1
        time.sleep(1.1) # There should be at least 1 sec delay between requests.
    conn.close()

Test steps:

1. Compile and program the application. Observe that the device is advertising.
2. Prepare the Linux router device by initializing the 6LoWPAN module.
3. Discover the advertising device by using the hcitool lescan command.
4. Connect to the discovered device from the Linux console using the Bluetooth 6LoWPAN connect command.
5. Check if the connected state is reflected by the LEDs (LED 2 is ON).
6. Ensure that the kit has an IPv6 Internet connection.
7. Push Button 1 on the kit and keep an eye on your terminal window.
8. Observe that the result of the hostname resolution is displayed. If the response is delayed, LED 3 will be blinking. If the hostname resolution was successful, a CoAP GET request with the Observe option will be sent.
9. Observe that the CoAP response to the subscription request is displayed. If a response is delayed, LED 4 will be blinking.
10. Update the dataport repeatedly as described above.
11. Observe that for each dataport update a notification is received and the value in the notification is displayed as described above.
12. Disconnect from the device by using the Bluetooth 6LoWPAN disconnect command.
13. Observe that LED 1 is blinking and that the device is advertising.