eSE100 Azure IoT Device Guide eSE100 Azure IoT Powered by MS500 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 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 2 | 21 Features 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 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 3 | 21 Block Diagram 1.2. BLOCK DIAGRAM Figure 1. eSE100 H/W Block Diagram Table 1 Each Chip Operation Role MS500 Enables the Internet access by setting the value of the network information for W5500 W5500 Enables connection to the Network Via Ethernet IO Provides Socket API to connect MS500 to the Internet Provides encrypted communication with Azure Server through TLS 1.2 Protocol All received data gets sent to the MS500, and the transmitted data gets passed on to the Internet via MS500. Provides Data Transmission and reception with Azure Server using Azure IoT SDK eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 4 | 21 eSE100 Azure IoT S/W Architecture Block Diagram 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 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 5 | 21 eSE100 Development Board Configuration 1.4. ESE100 DEVELOPMENT BOARD CONFIGURATION Figure 4. Board Configuration Table 2 Boot Mode Boot Mode Description ROM Boot Mode 0x20000000 - 0x2000FFFF Booting is composed of the Boot ROM Area (0x1FFF_E000) Executable region for data. Can also put code here to eSE100 Code are debug Table 3 Development Board Component Board Component Board Power ON-OFF DC 5V-2A USB-TO-UART Boot Mode RESET Description Power of Board is on or off In the Board, permit power Firmware code can download to S-Flash to the boot mode adjust Boot mode of Chip decide Reset the Chip to cold-boot Table 4 PAD Information Signal Line Communication PAD PA8 (TX) PA9 (RX) GND Description transfer a packet between USB Chip to MS500 < Information > UART port: UART Channel 1 Baud Rate: 115200 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 6 | 21 Development Environment 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/enus/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 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 7 | 21 eSE100 Programmers Model 2. THE ESE100 PROGRAM 2.1. ESE100 PROGRAMMERS MODEL 2.1.1. Memory Structure Figure 5. Memory Map Table 5 Memory Access behavior Memory Region Address Range 0x300220000 - 0x30100000 Code 0x30100000 - 0x300C0000 User DATA 0x20000000 - 0x2000FFFF SRAM Description Executable region for program code. eSE100 Data are stored Possible to place Data here for encryption Executable region for data. eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 8 | 21 eSE100 Programmers Model 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 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 9 | 21 Azure IoT SDK API 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/iothubclientll-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/iothubclientll-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/iothubclientll-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-lldowork eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 10 | 21 Azure IoT SDK API 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-lldestroy 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-messageh/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-messageh/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-llsendeventasync 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-messageh/iothubmessage-destroy eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 11 | 21 Azure IoT SDK API 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-messageh/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 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 12 | 21 Azure IoT Hub Instance. 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 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 13 | 21 Azure IoT Hub Instance. 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 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 14 | 21 Azure IoT Hub Instance. Connection string in the eSE100 device is configured in Example code to access Azure. Figure 11. Connection Azure eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 15 | 21 Launch Sample Application 3.2. LAUNCH SAMPLE APPLICATION 3.2.1. Build SDK Example code 1. 2. 3. 4. 5. Download eSE100 SDK Project. The project contains all the required drivers to use the eSE100 board, together with pre-integrated Microsoft Azure IoT SDK. Unzip the package. Open one of the pre-configured project files available in MS500_BSP_CMSIS/Application/Azure. Move to the MS500_BSP_CMSIS/Application/Azure project. 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. 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. iii. iv. 2. Connect your eSE100 I/O board and PC using the USB cable. Turn the eSE100 main board and I/O board switches ON. Check the connected COM port on PC. Run the MS500 Firmware Initializer program. Figure 13. Firmware Initializer Program 3. 4. 5. 6. 7. Check the COM Port and choose the BaudRate. Click 'Connect' to connect the COM Port Select the boot mode to 'QSPI' Input the 'Firmware image' file path for QSPI boot mode. Click the button to select the eSE100 firmware image. Check the 'FW Binary' path. Then, click 'FW Image Upload'. eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 16 | 21 Launch Sample Application 8. 9. 10. 11. The progress bar will update as the FW image uploads. Once the 'FW Image Upload' is complete, a pop-up message on your program will indicate success. Click 'Disconnect' to disconnect the COM Port. Then, remove the power cable. 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 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 17 | 21 Launch Sample Application 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 eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 18 | 21 Example Code 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. eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 19 | 21 Document Revision and Reference DOCUMENT REVISION AND REFERENCE Revision History Revision 0.1 0.3 Date 2019-01-15 2019-02-26 Description 1st Release eSE100 Azure IoTDevice Guide for Consumer Products, Rev. 0.3, 03/2019 20 | 21 COPYRIGHT NOTICE Copyright (c) 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. Copyright - (c) 2019 eWBM Co., Ltd. All rights reserved 21 | 21