eSE100 Azure IoT

Device Guide

eSE100 Azure IoT Powered by MS500

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 2 | 21

CONTETNS

Contetns .............................................................................................................................................................................................. 2

1. Introduction ............................................................................................................................................................................ 3

1.1. Features .............................................................................................................................................................................. 3

1.2. Block Diagram ..................................................................................................................................................................... 4

1.3. eSE100 Azure IoT S/W Architecture Block Diagram ............................................................................................................ 5

1.4. eSE100 Development Board Configuration ........................................................................................................................ 6

1.5. Development Environment ................................................................................................................................................. 7

2. The eSE100 Program ............................................................................................................................................................... 8

2.1. eSE100 Programmers Model .............................................................................................................................................. 8

2.2. Azure IoT SDK API .............................................................................................................................................................. 10

3. Azure IoT example Application Description .......................................................................................................................... 13

3.1. Azure IoT Hub Instance. .................................................................................................................................................... 13

3.2. Launch Sample Application ............................................................................................................................................... 16

3.3. Example Code.................................................................................................................................................................... 19

Document Revision and Reference .............................................................................................................................................. 20

Features

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 3 | 21

1. INTRODUCTION

This Document describes the operation condition between the Azure Server and the eSE100 Client, which

was ported using the Azure IoT SDK. Operating Condition for neither Debugging nor Compiler is

provided.

1.1. FEATURES

The Cortex-M0 processor is a high-performance 32-bit processor designed for the IoT microcontroller market. It

offers significant benefits to developers, including:

⚫ Enhanced system debug with an extensive breakpoint

⚫ Low power consumption with integrated sleep modes

⚫ Thumb instruction set combines high code density with 32-bit performance

⚫ Integrated sleep modes for low power consumption

⚫ Hardware driver and fast multiplier

⚫ Provide H/W Cryptographic accelerator

◼ Asymmetric algorithm accelerator

◼ Symmetric algorithm accelerator

Block Diagram

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 4 | 21

1.2. BLOCK DIAGRAM

Figure 1. eSE100 H/W Block Diagram

Table 1 Each Chip Operation Role

MS500 W5500

⚫ Enables the Internet access by setting the value of the

network information for W5500

⚫ Provides encrypted communication with Azure Server through

TLS 1.2 Protocol

⚫ Provides Data Transmission and reception with Azure Server

using Azure IoT SDK

⚫ Enables connection to the Network Via Ethernet IO

⚫ Provides Socket API to connect MS500 to the Internet

⚫ All received data gets sent to the MS500, and the transmitted data gets passed on to the Internet via MS500.

eSE100 Azure IoT S/W Architecture Block Diagram

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 5 | 21

1.3. ESE100 AZURE IOT S/W ARCHITECTURE BLOCK DIAGRAM

Figure 2. Azure IoT Block Diagram

Figure 3. eSE100 Azure Packet Flow

⚫ MS500 SDK and mbedTSL support the Transport Layer Security (TLS) Protocol Channel, and Azure IoT SDK may support Azure Protocol Communication.

⚫ Communication Protocol

◼ The TLS Handshake Protocol between eSE100 Client and Azure server establishes the secure communication channel.

◼ Once the TLS Channel is established, the eSE100 Client and the Azure Server initiates communication via the MQTT protocol.

◼ When the Azure Server protocol pre-requisites are met connection succeed at last. Once connection succeed then Publish-Subscribe protocol initiates according to MQTT Protocol.

eSE100 Development Board Configuration

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 6 | 21

1.4. ESE100 DEVELOPMENT BOARD CONFIGURATION

Figure 4. Board Configuration

Table 2 Boot Mode

Boot Mode Description

ROM Boot Mode Booting is composed of the Boot ROM Area (0x1FFF_E000)

0x20000000 – 0x2000FFFF Executable region for data. Can also put code here to eSE100 Code are debug

Table 3 Development Board Component

Board Component Description

Board Power ON-OFF Power of Board is on or off

DC 5V-2A In the Board, permit power

USB-TO-UART Firmware code can download to S-Flash to the boot mode adjust

Boot Mode Boot mode of Chip decide

RESET Reset the Chip to cold-boot

Table 4 PAD Information

Signal Line PAD Description

Communication

PA8 (TX)

PA9 (RX)

GND

transfer a packet between USB Chip to MS500

< Information >

UART port: UART Channel 1

Baud Rate: 115200

Development Environment

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 7 | 21

1.5. DEVELOPMENT ENVIRONMENT

⚫ For Azure Server Interoperability Testing configure the Operating Condition for Azure IoT Hub. The Device ID Registry at Azure IoT Hub identifies the device information.

- Azure IoT Hub Device Provisioning Service Documentation (https://docs.microsoft.com/en-us/azure/iot-dps/)

- Azure Service : https://portal.azure.com/

⚫ Use Device Explorer Twin to monitor the device message and to send the message to the device

Device Explorer Twin (Windows OS Only)

- How to use Device Explorer

(https://github.com/Azure/azure-iot-sdk-csharp/tree/master/tools/DeviceExplorer)

- Setup Device Explorer (https://github.com/Azure/azure-iot-sdks/releases)

⚫ Serial Port Information for eSE100 Status Report

- BaudRate : 115200bps

- Data : 8bit

- Parity : none

- Stop : 1bit

- Flow Control : none

eSE100 Programmers Model

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 8 | 21

2. THE ESE100 PROGRAM

2.1. ESE100 PROGRAMMERS MODEL

2.1.1. Memory Structure

Figure 5. Memory Map

Table 5 Memory Access behavior

Address Range Memory

Region Description

0x300220000 – 0x30100000 Code Executable region for program code. Possible to place Data here

0x30100000 – 0x300C0000 User DATA eSE100 Data are stored for encryption

0x20000000 – 0x2000FFFF SRAM Executable region for data.

eSE100 Programmers Model

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 9 | 21

2.1.2. eSE100 Packet Memory Endianness

Little-Endian Format

The eSE100 stores the least significant byte of a word at the lowest-numbered byte, and the most significant byte at

the highest-numbered byte

Figure 6. Little-endian Example

Azure IoT SDK API

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 10 | 21

2.2. AZURE IOT SDK API

Here are the References for the Main API Items used in the Example Code.

Please refer to the MS site for the APIs and other details introduced here.

API information can be searched by putting API name in "Filter by title" search window.

Azure IoT SDK API : https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/

⚫ IoTHubClient_LL_CreateFromConnectionString

- Creates a IoT Hub client for communication with an existing IoT Hub using the specified

connection string parameter.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-client-ll-h/iothubclient-ll-createfromconnectionstring

⚫ IoTHubClient_LL_SetOption

- This API sets a runtime option identified by parameter optionName to a value pointed

to by value. optionName and the data type value is pointing to are specific for every

option.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-client-ll-h/iothubclient-ll-setoption

⚫ IoTHubClient_LL_SetMessageCallback

- Sets up the message callback to be invoked when IoT Hub issues a message to the device.

This is a blocking call.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-client-ll-h/iothubclient-ll-setmessagecallback

⚫ IoTHubClient_LL_DoWork

- This function is meant to be called by the user when work (sending/receiving) can be

done by the IoTHubClient.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-client-ll-h/iothubclient-ll-

dowork

Azure IoT SDK API

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 11 | 21

⚫ IoTHubClient_LL_Destroy

- Disposes of resources allocated by the IoT Hub client. This is a blocking call.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-client-ll-h/iothubclient-ll-

destroy

⚫ IoTHubMessage_CreateFromByteArray

- Creates a new IoT hub message from a byte array. The type of the message will be set to

IOTHUBMESSAGE_BYTEARRAY.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-message-

h/iothubmessage-createfrombytearray

⚫ IoTHubMessage_Properties

- Gets a handle to the message's properties map. Note that when sending messages via

the HTTP transport, the key names in the map must not contain spaces.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-message-

h/iothubmessage-properties

⚫ Map_AddOrUpdate

- Adds/updates a key/value pair to the map.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/map-h/map-addorupdate

⚫ IoTHubClient_LL_SendEventAsync

- Asynchronous call to send the message specified by eventMessageHandle.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-client-ll-h/iothubclient-ll-

sendeventasync

⚫ IoTHubMessage_Destroy

- Frees all resources associated with the given message handle.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-message-

h/iothubmessage-destroy

Azure IoT SDK API

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 12 | 21

⚫ IoTHubMessage_GetByteArray

- Fetches a pointer and size for the data associated with the IoT hub message handle. If the

content type of the message is not IOTHUBMESSAGE_BYTEARRAY then the function

returns IOTHUB_MESSAGE_INVALID_ARG.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-message-

h/iothubmessage-getbytearray

⚫ Map_GetInternals

- Retrieves the complete list of keys and values from the map in values and keys. Also

writes the size of the list in count.

- https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/map-h/map-getinternals

Azure IoT Hub Instance.

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 13 | 21

3. AZURE IOT EXAMPLE APPLICATION DESCRIPTION

3.1. AZURE IOT HUB INSTANCE.

⚫ Create an account in Microsoft Azure to run the provided example code. Then create a device instance from the Azure IoT Hub

⚫ Copy the Connection String information of the IoT Hub Browser from the Azure Portal

Figure 7. Azure Portal

⚫ Download and Run the Microsoft Device Explorer Twin. Then enter the IoT Hub Connection String copied from the Azure Portal.

Figure 8. Microsoft Device Explorer

Azure IoT Hub Instance.

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 14 | 21

⚫ Check the registered Device ID.

Figure 9. Checking the Device ID

⚫ Wait for received message event from the registered Device ID

Figure 10. Received Message from Device ID

Azure IoT Hub Instance.

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 15 | 21

⚫ Connection string in the eSE100 device is configured in Example code to access Azure.

Figure 11. Connection Azure

Launch Sample Application

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 16 | 21

3.2. LAUNCH SAMPLE APPLICATION

3.2.1. Build SDK Example code

1. Download eSE100 SDK Project. The project contains all the required drivers to use the eSE100 board, together with

pre-integrated Microsoft Azure IoT SDK.

2. Unzip the package. Open one of the pre-configured project files available

in MS500_BSP_CMSIS/Application/Azure.

3. Move to the MS500_BSP_CMSIS/Application/Azure project.

4. Open file AzureTest.c and update connectionString with the credentials retrieved once completed device

registration in IoT Hub. You have also to set mac-address by replacing DEFAULT_MAC to open file eSE100_init.c for

using gateway.

5. Build the project according to the ARM-GCC make. In MS500_BSP_CMSIS/Application/Azure/makefile -> run make

⚫ Upload firmware image

1. Follow the steps below to configure the board.

i. Set boot mode to 'UART to QSPI Boot'.

Figure 12. Select Boot Mode

ii. Connect your eSE100 I/O board and PC using the USB cable. iii. Turn the eSE100 main board and I/O board switches ON. iv. Check the connected COM port on PC.

2. Run the MS500 Firmware Initializer program.

Figure 13. Firmware Initializer Program

3. Check the COM Port and choose the BaudRate. 4. Click 'Connect’ to connect the COM Port 5. Select the boot mode to 'QSPI' 6. Input the 'Firmware image' file path for QSPI boot mode. Click the button to select the eSE100 firmware

image. 7. Check the 'FW Binary' path. Then, click 'FW Image Upload’.

Launch Sample Application

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 17 | 21

8. The progress bar will update as the FW image uploads. 9. Once the 'FW Image Upload' is complete, a pop-up message on your program will indicate success. 10. Click 'Disconnect’ to disconnect the COM Port. Then, remove the power cable. 11. Change the set for the boot mode to 'ROM Boot' Then connect your eSE100 board and power cable for

board booting

Figure 14. Boot Mode Setting

12. Check the FW image booting and operation.

⚫ Verify eSE100 Device Operation following the execution. Attempt an automatic access to Azure Server by

running the Sample code. Upon successful connection to Azure, the yellow LED turns on and then turns

off. Led Status data is published regularly to the Azure Server. Monitor the operation status of the device

through USB to Serial of eSE100.

Figure 15. Azure Server Sample Code

Launch Sample Application

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 18 | 21

Executing Device Explore Twin Program as shown in the picture below, Data transmitted from eSE100

Device can be monitored.

Figure 16. Event Monitored from Device Explorer Twin

Example Code

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 19 | 21

3.3. EXAMPLE CODE

⚫ Example code Description ( AzureTest.c file )

Figure 17. Example Code

No. 1 Item: Before running Azure IoT SDK, perform platform-specific code for Azure Initialization.

No. 2 Item: It is a specific code to connect to Azure Server

◼ IoTHubClient_LL_CreateFromConnectionString : It is a code to set the device

connection string for connection to Azure Server

◼ IoTHubClient_LL_SetMessageCallback registers ReceiveMessageCallback code to

process data received from server

No. 3 Item: Data is sent to the Azure Server

No. 4 Item: Socket IO related work at the Azure IoT SDK. The code handles the transfer operation of the

'Socket API' each time it is called.

Document Revision and Reference

eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 20 | 21

DOCUMENT REVISION AND REFERENCE

Revision History

Revision Date Description

0.1 2019-01-15 1st Release

0.3 2019-02-26

Copyright - © 2019 eWBM Co., Ltd. All rights reserved 21 | 21

COPYRIGHT NOTICE

Copyright © 2019 eWBM Co., Ltd. All rights reserved.

This document is the copyrighted work of eWBM Co., Ltd. and is owned by eWBM Co., Ltd. It is provided as a

reference for the sole purpose of MS500 microcontroller based system design.

No part of the software and documentation may be reproduced, transmitted, or translated, in any form or by

any means, electronic, mechanical, manual, optical, or otherwise, without prior written permission of eWBM

Co., Ltd.

NO WARRANTY NOTICE

eWBM Co., Ltd. makes no warranty of any kind in regard to this material which is delivered to you as is,

including, but not limited to, the implied warranties as to its accuracy or fitness for a specific purpose. Any use of

this technical documentation or the information contained therein is at the risk of the user. eWBM Co., Ltd. shall

not be liable for errors contained therein or for incidental consequential damages in connection with the

furnishing, performance or use of the material.