u-connectXpress · IoT Cloud Connectivity . Application Note Abstract This Application note provides information how to configure and on setup connection for the most popular cloud

u-connectXpress IoT Cloud Connectivity Application Note

Abstract

This Application note provides information on how to configure and setup connection for the most popular cloud services such as IBM, Amazon Web Services (AWS), and Azure using u-connectXpress software.

www.u-blox.com UBX-19010078 - R02

http://www.u-blox.com/

u-connectXpress - Application Note

UBX-19010078 - R02 Document Information Page 2 of 28

Document Information Title u-connectXpress

Subtitle IoT Cloud Connectivity

Document type Application Note

Document number UBX-19010078

Revision and date R02 30-Oct-2019

Disclosure Restriction

This document applies to the following products: Product name Software version PCN reference

ODIN-W260 7.0.x onwards N/A

ODIN-W262 7.0.x onwards N/A

NINA-W131 2.1.x onwards N/A




u-blox or third parties may hold intellectual property rights in the products, names, logos and designs included in this document. Copying, reproduction, modification or disclosure to third parties of this document or any part thereof is only permitted with the express written permission of u-blox. The information contained herein is provided “as is” and u-blox assumes no liability for its use. No warranty, either express or implied, is given, including but not limited to, with respect to the accuracy, correctness, reliability and fitness for a particular purpose of the information. This document may be revised by u-blox at any time without notice. For the most recent documents, visit www.u-blox.com. Copyright © u-blox AG.


UBX-19010078 - R02 Contents Page 3 of 28

Contents Document Information ................................................................................................................................ 2

Contents .......................................................................................................................................................... 3

1 Configuring IBM IoT Platform (with client certificate) .............................................................. 4 1.1 Cloud server configuration ........................................................................................................................ 4 1.2 Setup steps .................................................................................................................................................. 6

2 Configuring IBM IoT Platform (with username and password) .............................................. 7 2.1 Cloud server configuration ........................................................................................................................ 7 2.2 Setup steps .................................................................................................................................................. 9

3 Configuring AWS IoT Core ............................................................................................................... 10 3.1 Cloud server configuration ......................................................................................................................10 3.2 Setup steps ................................................................................................................................................12

4 Configuring Azure IoT Hub ............................................................................................................... 14 4.1 Cloud server configuration ......................................................................................................................14 4.2 Setup steps ................................................................................................................................................16

Appendix ....................................................................................................................................................... 18

A Glossary ................................................................................................................................................. 18

B Monitoring messages to/from the cloud .................................................................................... 19 B.1 In IBM IoT Platform ...................................................................................................................................19

B.1.1 Device-to-cloud .................................................................................................................................19 B.1.2 Cloud-to-device .................................................................................................................................20

B.2 In AWS IoT Core .........................................................................................................................................21 B.2.1 Device-to-cloud .................................................................................................................................21 B.2.2 Cloud-to-device .................................................................................................................................23

B.3 In Azure IoT Hub ........................................................................................................................................24 B.3.1 Device-to-cloud .................................................................................................................................24 B.3.2 Cloud-to-device .................................................................................................................................25

C Generating certificates ..................................................................................................................... 26 C.1 Generating CA certificate ........................................................................................................................26 C.2 Generating client side certificate ..........................................................................................................26

Related documents ................................................................................................................................... 27

Revision history .......................................................................................................................................... 27

Contact .......................................................................................................................................................... 28


UBX-19010078 - R02 Configuring IBM IoT Platform (with client certificate) Page 4 of 28

1 Configuring IBM IoT Platform (with client certificate)

1.1 Cloud server configuration 1. Add a device of Device Type “Device”. For example, as shown in the screenshot below, the device

is given the Device ID – “device1”.

2. Generate client side certificate (see Appendix section - C.2 Generating client side certificate) where Common Name (CN) is set in the format d:deviceType:deviceId.

For example CN = d:device:device1

3. Upload the CA certificate that was used to sign the device’s client certificate.



4. Set Connection Security Level to “TLS with Client Certificate”.



1.2 Setup steps 1. Upload the IBM IoT server certificate; the certificate can be downloaded from the following URL:

https://github.com/ibm-watson-iot/iot-python/blob/master/src/wiotp/sdk/messaging.pem

AT+USECMNG=0,0,<internal_name>,<data_size>

See u-connect AT Commands Manual [1] for additional information.

2. Upload the client key and client certificate generated as mentioned in step [2].

(certificate) AT+USECMNG=0,1,<internal_name>,<data_size>

(private key) AT+USECMNG=0,2,<internal_name>,<data_size>

3. Set up a network connection. Example (Wi-Fi):

AT+UWSC=configuration_id>,<param_tag>,<param_val1>[,<param_val2>,...,<param_valn>]

AT+UWSCA=config_id>,<action>

4. Connect to the IBM IoT Platform using MQTT; see the u-connectXpress MQTT Application Note [2] for additional information.

at+udcp=mqtt://orgId.messaging.internetofthings.ibmcloud.com:8883/?ca=server_cert &cert=device_cert&privKey=device_key&pt=iot-2/evt/event_id/fmt/format_string

where:

orgId = your organization ID on the IBM IoT Platform, which can be found in the top right corner when logged in to the IBM IoT Platform:

server_cert = the internal name given to the IBM IoT server certificate when uploaded to the module.

device_cert = the internal name given to the client certificate when uploaded to the module.

device_key = the internal name given to the client private key when uploaded to the module.

event_id = any string that is valid in MQTT

format_string = any string that is valid in MQTT, used by IBM IoT Platform to define the content type of the message payload ("json", "xml", "txt", and "csv")

Example:

at+udcp=mqtt://uyvwsd.messaging.internetofthings.ibmcloud.com:8883/?ca=messaging.pem&cert=device.crt&privKey=device.key&pt=iot-2/evt/ubx_test/fmt/txt

Monitor the connection status as mentioned in Appendix B.1.1

5. Switch to Data mode and send data to/from the IBM IoT Platform, monitor the transferred data as mentioned in Appendix B.1.



UBX-19010078 - R02 Configuring IBM IoT Platform (with username and password) Page 7 of 28

2 Configuring IBM IoT Platform (with username and password)

2.1 Cloud server configuration 1. Add a device of Device Type and enter a unique name for the same. In this example, the device is

given the Device ID – “device2”. Note the auto-generated authentication token.



2. If Default Rule of Connection Security is not set to “TLS with Client Certificate”, it is possible to set a Custom Rule for a specific Device Type (in this case, devicewithtoken, as created in step [1]).



2.2 Setup steps 1. Upload the IBM IoT server certificate; this certificate can be downloaded from the following URL:



See the u-connect AT Commands Manual [1] for additional information.


AT+UWSC=configuration_id>,<param_tag>,<param_val1>[,<param_val2>,...,<param_valn>


3. Connect to the IBM IoT Platform using MQTT; see the u-connectXpress MQTT Application Note [2] for additional information.

at+udcp=mqtt://orgId.messaging.internetofthings.ibmcloud.com:8883/?ca=server_cert&client=d:orgId:device_type:device_id&user=use-token-auth&passwd=authentication_token&pt=iot-2/evt/event_id/fmt/format_string

where:


server_cert = the internal name given to the IBM IoT server certificate when uploaded to the module.

device_type = the Device Type set to the device in IBM IoT Platform

device_id = the Device ID set to the device in IBM IoT Platform

authentication_token = the token generated while creating the device in the IBM IoT Platform as mentioned in step [1]

event_id = any string that is valid in MQTT

format_string = any string that is valid in MQTT, used by the IBM IoT Platform to define the content type of the message payload ("json", "xml", "txt", and "csv")

Example:

at+udcp=mqtt://xxxx.messaging.internetofthings.ibmcloud.com:8883/?ca=messaging.pem&client=d:uyvwsd:devicewithtoken:device2&user=use-token-auth&passwd=XXXXXX&pt=iot-2/evt/test/fmt/txt

Monitor the connection status as per the instructions mentioned in Appendix B.1

4. Switch to Data mode and send data to/from the IBM IoT Platform; monitor the transferred data as mentioned in Appendix B.1.



UBX-19010078 - R02 Configuring AWS IoT Core Page 10 of 28

3 Configuring AWS IoT Core

3.1 Cloud server configuration 1. Create a Thing (IoT Core \ Manage \ Things), this is a representation and record of the physical

device to be connected to the cloud. Give the Thing a name, for example “device1”. Create Thing without certificate (the certificate will be created later).

2. Create certificate using AWS IoT’s CA. Download the certificate, public key, private key, and the server certificate for AWS IoT.

3. Create a policy, which allows the certificate holder to publish to all topics and subscribe to all topic filters. Enable Advanced mode and copy and paste the following policy statement:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:*", "Resource": "*" } ] }



4. Attach the previously created policy to the previously created certificate.

5. Attach the previously created thing to the previously created certificate.



6. Activate the certificate.

3.2 Setup steps 1. Upload the AWS IoT server certificate; the certificate can be downloaded from the following URL:

https://www.amazontrust.com/repository/AmazonRootCA1.pem


See the u-connect AT Commands Manual [1] for additional information.

https://www.amazontrust.com/repository/AmazonRootCA1.pem









4. Connect to AWS IoT using MQTT; see the u-connectXpress MQTT Application Note [2] for additional information.

at+udcp=mqtt://endpoint:8883/?ca=server_cert&cert=device_cert&privKey=device_key&pt=publish_topic&st=subscribe_topic

where:

endpoint = your unique address to connect the Thing to AWS IoT, which can be found under Manage / Things / thing_name / Interact / HTTPS, the address is the same as the Rest API endpoint:

server_cert = the internal name given to the AWS IoT server certificate when uploaded to the module.

device_cert = the internal name given to the client certificate when uploaded to the module

device_key = the internal name given to the client private key when uploaded to the module

publish_topic = any topic that is valid in MQTT and module

subscribe_topic = any topic that is valid in MQTT and module

Example:

at+udcp=mqtt://abcdefghijkl-ats.iot.eu-west-2.amazonaws.com:8883/?ca=AmazonRootCA1.pem&cert=device.crt&privKey=device.key&pt=test/pt&st=test/st

5. Switch to Data mode and send data to/from the AWS IoT server; monitor the transferred data as mentioned in Appendix B.1.2.


UBX-19010078 - R02 Configuring Azure IoT Hub Page 14 of 28

4 Configuring Azure IoT Hub

4.1 Cloud server configuration 1. Go to the IoT Devices tool in the Explores section and click “Add” to register a new device. Enter a

Device ID, for example “device1” and set the Authentication type to “X.509 CA Signed”.

2. Generate client side certificate (see Appendix section C.2) where Common Name (CN) is set to the Device ID of the device.

3. Upload the CA certificate that was used to sign the device’s client certificate.



4. Click on the certificate that you added in the previous step. In the Certificate Details pane, click Generate Verification Code button, generate a certificate using the uploaded CA certificate (see Appendix C.2) where CN is set to the Verification Code.



5. Upload the generated certificate from previous step to the Verification Certificate in the Certificate Details pane and click “Verify”. The STATUS of the CA certificate changes to Verified.

4.2 Setup steps 1. Upload the Azure IoT Hub server certificate; the certificate can found in the Azure-iot-sdk-c

repository:

https://github.com/Azure/azure-iot-sdk-c/blob/master/certs/certs.c

Create a local file that contains the DigiCert Baltimore Root certificate by copying the certificate information from certs.c. Include the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, remove the " marks at the beginning and end of every line, and remove the \r\n characters at the end of every line.


See u-connect AT Commands Manual [1] for additional information.







4. Connect to Azure IoT Hub using MQTT; see the u-connectXpress MQTT Application Note [2] for additional information.

at+udcp=mqtt://iothubhostname:8883/?client=device_id&user=iothubhostname/device_id&ca=server_cert&cert=device_cert&privKey=device_key&pt=devices/device_id/messages/events/

https://github.com/Azure/azure-iot-sdk-c/blob/master/certs/certs.c



☞ To receive messages from the Azure IoT Hub, a device should subscribe to the topic: devices/device_id/messages/devicebound/#. The # wildcard is not supported by ODIN-W26-7.0.0; so only the device-to-cloud messages should be tested.

where:

iothubhostname = can be found under Overview / Hostname:

device_id = the Device ID set to the device in Azure IoT Hub

server_cert = the internal name given to the Azure IoT Hub server certificate when uploaded to the module.

device_cert = the internal name given to the client certificate when uploaded to the module.

device_key = the internal name given to the client private key when uploaded to the module.

Example:

at+udcp=mqtt://xxxx-test-hub-1.azure-devices.net:8883/?client=device1&user=xxxx-test-hub-1.azure-devices.net/device1&ca=DigiCertBaltimoreRoot.cer&cert=device1.crt&privKey=device1.key&pt=devices/device1/messages/events/

5. Switch to Data mode and send data to/from the Azure IoT server; monitor the transferred data as mentioned in Appendix B.3.


UBX-19010078 - R02 Appendix Page 18 of 28

Appendix

A Glossary Abbreviation Definition

API Application Programming Interface

AWS Amazon Web Services

CA Certificate Authority

CN Common Name

CSR Certificate Signing Request

IoT Internet of Things

MQTT Message Queuing Telemetry Transport

TLS Transport Layer Security

Table 1: Explanation of the abbreviations and terms used



B Monitoring messages to/from the cloud

B.1 In IBM IoT Platform

B.1.1 Device-to-cloud

Monitoring connection events in Device / Browse / [device1] / Logs:

Monitoring device-to-cloud messages in Device / Browse / [device1] / Recent Events:



B.1.2 Cloud-to-device

Monitoring device-to-cloud messages with a module acting as an Application:

1. Generate an API key for an Application with “Standard Application” permission. Note the auto-generated authentication token.

2. Connect the module as an Application to the IBM IoT Platform using MQTT; see the u-connectXpress MQTT Application Note [2] for additional information.

at+udcp=mqtt://orgId.messaging.internetofthings.ibmcloud.com:1883/?client=a:orgId:name&user=api_key&passwd=authentication_token&pt=iot-2/type/device_type/id/device_id/cmd/command_id/fmt/format_string



where:


name = any string that is valid in MQTT

api_key = the API Key of the application in IBM IoT Platform

authentication_token = the token generated when creating the application in IBM IoT Platform

device_type = the Device Type of the device to monitor

device_id = the Device ID of the device to monitor

command_id = any string that is valid in MQTT, the device to monitor need to configure the subscribe topic to the same command id

format_string = any string that is valid in MQTT, used by IBM IoT Platform to define the content type of the message payload ("json", "xml", "txt", and "csv")

Example:

at+udcp=mqtt://uyvwsd.messaging.internetofthings.ibmcloud.com:1883/?client=a:uyvwsd:app1&user=a-uyvwsd-zesbja19tw&passwd=+aDj%26PnJrTUN-9Nh2r&pt=iot-2/type/devicewithtoken/id/device2/cmd/ubx_test/fmt/txt

3. Switch to Data mode and send data to the device to monitor.

B.2 In AWS IoT Core The AWS IoT includes an MQTT client that can be used to monitor the MQTT messages sent by a connected Thing as well as send messages to a connected Thing.


1. Go to ”Test” to connect the MQTT client to the AWS IoT server. Subscribe to the topic on which the Thing publishes, for example ubx_test/pt.



2. Monitor the device-to-cloud messages.




1. Use the AWS IoT console to publish a message. Go to “Test” to start/connect the MQTT client to the AWS IoT server. Choose Publish to the topic on which the Thing subscribes, for example ubx_test/st.

2. Monitor the AWS-to-Device messages.



B.3 In Azure IoT Hub The Device Explorer tool can be used to monitor messages between the device and the Azure IoT Hub. A pre-built version of the Device Explorer for Windows can be downloaded from the following URL. In this URL, scroll down for the SetupDeviceExplorer.msi

https://github.com/Azure/azure-iot-sdk-csharp/releases

In the Device Explorer tool, go to the Configuration tab and add the Connection String for your IoT Hub.

The Connection String can be found in the IoT Hub; go to Settings / Shared access policies and click the iothubowner Policy.


1. In the Device Explorer tool, go to the Data tab and select the Device ID of the device to monitor (for example “device1”) and click “Monitor” button.

https://github.com/Azure/azure-iot-sdk-csharp/releases




1. In the Device Explorer tool, go to the “Message to Device” tab and select the Device ID of the device to send message to (for example “device1”). Type a message in the Message text box and click “Send”.

2. Monitor the Cloud-to-Device messages.



C Generating certificates

C.1 Generating CA certificate The openssl command-line tool can be used to create a self-signed CA certificate:

1. Generate key for CA:

openssl genrsa -out rootCA.key 2048

2. Generate self-sign CA certificate:

openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem

Fill the necessary information (none of them are mandatory).

3. We know have a self-signed CA certificate (rootCA.pem) and its private key (rootCA.key).

C.2 Generating client side certificate Using the openssl command-line tool and a self-signed CA (see Appendix section C.1) certificate, we can create a self-signed client certificate:

1. Generate private key for the client:

openssl genrsa -out client.key 2048

2. Generate a Certificate Signing Request (CSR) to generate client certificate:

openssl req -new -key client.key -out client.csr

Fill in the information details, for most cloud services the Common Name (CN) is the only mandatory field.

3. Generate the certificate:

openssl x509 -req -in client.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out client.crt -days 500 -sha256

4. We know have a self-signed client certificate (client.crt) and its client private key (client.key).


UBX-19010078 - R02 Related documents Page 27 of 28

Related documents [1] u-connect AT commands manual, doc. no. UBX-14044127 [2] u-connectXpress MQTT application note, doc. no. UBX-19005066 [3] u-connectXpress user Guide, doc. no. UBX-16024251

Revision history Revision Date Name Comments

R01 19-Mar-2019 cmag Initial release.

R02 30-Oct-2019 flun Included NINA-W13 v2.1.x, NINA-W15 v1.0.x as applicable products.

Removed references to ODIN-W2 in the text, where also applicable to NINA-W1 products. Added links to related documents.

https://www.u-blox.com/sites/default/files/u-connect-ATCommands-Manual_%28UBX-14044127%29.pdf

https://www.u-blox.com/sites/default/files/u-connectXpress-MQTT_ApplicationNote_%28UBX-19005066%29.pdf

https://www.u-blox.com/sites/default/files/u-connectXpress_UserGuide_%28UBX-16024251%29.pdf


UBX-19010078 - R02 Contact Page 28 of 28

Contact For complete contact information, visit us at www.u-blox.com.

u-blox Offices

North, Central and South America

u-blox America, Inc.

Phone: +1 703 483 3180 E-mail: [email protected]

Regional Office West Coast:


Technical Support:


Headquarters Europe, Middle East, Africa

u-blox AG

Phone: +41 44 722 74 44 E-mail: [email protected] Support: [email protected]

Asia, Australia, Pacific

u-blox Singapore Pte. Ltd.

Phone: +65 6734 3811 E-mail: [email protected] Support: [email protected]

Regional Office Australia:

Phone: +61 2 8448 2016 E-mail: [email protected] Support: [email protected]

Regional Office China (Beijing):


Regional Office China (Chongqing):


Regional Office China (Shanghai):


Regional Office China (Shenzhen):


Regional Office India:


Regional Office Japan (Osaka):


Regional Office Japan (Tokyo):


Regional Office Korea:


Regional Office Taiwan:


http://www.u-blox.com/

mailto:[email protected]



























Documents

u-connectXpress · IoT Cloud Connectivity . Application Note Abstract This Application note provides information how to configure and on setup connection for the most popular cloud