mi Copyright 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. eSE100 AWS IoT No part of the software and documentation may GUIDE be reproduced, Release 0.4 transmitted, or translated, in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without prior written permission of eWBM Co., Ltd. eWBM Co., Ltd. makes no warranty of any kind with regard to this material which is delivered as is, including, but not limited to, the implied warranties as to its accuracy or fitness for a particular 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, eSE100 AWS IoT | Release Notes consequential damages in connection with the furnishing, performance or use of the material. The information contained in this document is subject to change without notice. Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 2 eSE100 AWS IoT | Release Notes TABLE OF CONTENT COPYRIGHT .........................................................................................................................................................................1 AUDIENCE .......................................................................................................................................................................................... 4 DOCUMENT REVISION AND REFERENCE .................................................................................................................................................... 4 ABOUT THIS DOCUMENT .....................................................................................................................................................5 ABOUT MS500 CORTEX-M0 PROCESSOR AND CORE PERIPHERALS........................................................................................5 MS500 PROCESSOR FEATURES AND BENEFITS SUMMARY ............................................................................................................................ 5 THE ESE100 AWS IOT DEVELOPMENT ENVIRONMENT ..........................................................................................................5 ESE100 AWS IOT DEVELOPMENT TOOL ................................................................................................................................................. 5 THE ESE100 AWS IOT CONFIGURATION ................................................................................................................................6 ESE100 H/W BLOCK DIAGRAM............................................................................................................................................................. 6 ESE100 AWS IOT S/W ARCHITECTURE BLOCK DIAGRAM .......................................................................................................................... 7 ESE100 DEVELOPMENT BOARD CONFIGURATION ...................................................................................................................................... 9 DEVELOPMENT ENVIRONMENT ............................................................................................................................................................. 10 THE ESE100 PROGRAM ...................................................................................................................................................... 11 ESE100 PROGRAMMERS MODEL .......................................................................................................................................................... 11 AWS IOT SDK API ........................................................................................................................................................................... 12 AWS IOT EXAMPLE APPLICATION DESCRIPTION ................................................................................................................. 15 AWS IOT HUB INSTANCE .................................................................................................................................................................... 15 LAUNCH SAMPLE APPLICATION ............................................................................................................................................................. 17 EXAMPLE CODE ................................................................................................................................................................................. 20 FIGURE 1 ESE100 H/W BLOCK DIAGRAM ............................................................................................................................................... 6 FIGURE 2 AWS IOT BLOCK DIAGRAM ...................................................................................................................................................... 7 FIGURE 3 ESE100 AWS PACKET FLOW ................................................................................................................................................... 7 FIGURE 4 BOARD CONFIGURATION ......................................................................................................................................................... 9 FIGURE 5 MEMORY MAP .................................................................................................................................................................... 11 FIGURE 6 LITTLE-ENDIAN EXAMPLE........................................................................................................................................................ 12 TABLE 1 EACH CHIP OPERATION ROLE ...................................................................................................................................................... 6 TABLE 2 BOOT MODE .......................................................................................................................................................................... 9 TABLE 3 DEVELOPMENT BOARD COMPONENT ........................................................................................................................................... 9 TABLE 5 MEMORY ACCESS BEHAVIOR .................................................................................................................................................... 11 Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 3 eSE100 AWS IoT | Release Notes Audience This document is intended for system software developers, hardware designers, and application developers. Document Revision and Reference Revision History Revision Date 0.1 0.2 0.3 0.4 2018-01-07 2018-02-18 2019-02-28 2019-04-24 Description Draft release AWS AWS Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 4 eSE100 AWS IoT | Release Notes About This Document This Document describes the operation condition between the AWS Server and the eSE100 Client, which was ported using the AWS IoT SDK. Operating Condition for neither Debugging nor Compiler is provided. About MS500 Cortex-M0 processor and core peripherals 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 MS500 Processor Features and Benefits 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 The eSE100 AWS IoT Development Environment This section describes the UAF development environment eSE100 AWS IoT Development Tool DEVELOPMENT TOOL GCC Compiler TOOL CHAIN ARM GCC Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 5 eSE100 AWS IoT | Release Notes The eSE100 AWS IoT Configuration eSE100 H/W Block Diagram Figure 1 eSE100 H/W Block Diagram Table 1 Each chip operation role MS500 Enables the Internet access by network information for W5500 W5500 setting the value of the Enables connection to the Network Via Ethernet IO Provides Socket API to connect MS500 to the Internet Provides encrypted communication with AWS 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 AWS Server using AWS IoT SDK Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 6 eSE100 AWS IoT | Release Notes eSE100 AWS IoT S/W Architecture Block Diagram Figure 2 AWS IoT Block diagram Figure 3 eSE100 AWS Packet Flow Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 7 eSE100 AWS IoT | Release Notes MS500 SDK and mbedTSL support the Transport Layer Security (TLS) Protocol Channel, and AWS IoT SDK may support AWS Protocol Communication. Communication Protocol The TLS Handshake Protocol between eSE100 Client and AWS server establishes the secure communication channel. Once the TLS Channel is established, the eSE100 Client and the AWS Server initiates communication via the MQTT protocol. When the AWS Server protocol pre-requisites are met connection succeed at last. Once connection succeed then Publish-Subscribe protocol initiates according to MQTT Protocol. Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 8 eSE100 AWS IoT | Release Notes eSE100 Development Board Configuration Figure 4 Board Configuration Boot Mode ROM Boot Mode 0x20000000 - 0x2000FFFF Description 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 2 Boot Mode Table 3 Development Board Component Board Component Board Power ON-OFF DC 5V-2A USB-TO-UART Boot Mode RESET Signal Line Communication 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 PAD PA8 (TX) PA9 (RX) GND Description transfer a packet between USB Chip to MS500 < Information > UART port: UART Channel 1 Baud Rate: 115200 Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 9 eSE100 AWS IoT | Release Notes Development Environment For AWS Server Interoperability Testing configure the Operating Condition for AWS IoT Hub. Device ID Registry at AWS IoT Hub identifies the device information. - The AWS IoT Hub Device Provisioning Service Documentation ( https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html ) Use AWS IoT console to monitor the device message and to send the message to the device - AWS IoT Test (On the AWS website only) ( https://console.aws.amazon.com/iot/home ) Serial Port Information for sS2E Status Report - BaudRate : 115200bps - Data : 8bit - Parity : none - Stop : 1bit - Flow Control : none Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 10 eSE100 AWS IoT | Release Notes The eSE100 Program eSE100 Programmers Model This section describes the eSE100 programmers' model. MEMORY STRUCTURE This section describe the eSE100 memory map. Figure 5 Memory Map Table 4 Memory Access behavior Address Range 0x30022000 - 0x30100000 0x30100000 - 0x300C0000 0x20000000 - 0x2000FFFF Memory Region Code User DATA SRAM Description Executable region for program code. Possible to place Data here eSE100 Data are stored for encryption Executable region for data. Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 11 eSE100 AWS IoT | Release Notes 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 AWS IoT SDK API Here are the References for the Main API Items used in the Example Code. Please refer to the AWS site for the APIs and other details introduced here. AWS IoT SDK API : https://github.com/aws/aws-iot-device-sdk-embedded-C/blob/master/README.md aws_iot_mqtt_init(AWS_IoT_Client *pClient, IoT_Client_Init_Params *pInitParams); - Called to initialize the MQTT Client Parameters pClient Reference to the IoT Client pInitParams Pointer to MQTT connection parameters Returns IoT_Error_t Type defining successful/failed API call aws_iot_mqtt_connect(AWS_IoT_Client *pClient, IoT_Client_Connect_Params *pConnectParams); - Called to establish an MQTT connection with the AWS IoT Service This is the outer function which does the validations and calls the internal connect above to perform the actual operation. It is also responsible for client state changes Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 12 eSE100 AWS IoT | Release Notes Parameters pClient Reference to the IoT Client pConnectParams Pointer to MQTT connection parameters Returns An IoT Error Type defining successful/failed connection aws_iot_mqtt_subscribe(AWS_IoT_Client *pClient, const topicNameLen, QoS qos, pApplicationHandler_t *pApplicationHandlerData); - char *pTopicName, uint16_t pApplicationHandler, void Called to send a subscribe message to the broker requesting a subscription to an MQTT topic. This is the outer function which does the validations and calls the internal subscribe above to perform the actual operation. It is also responsible for client state changes Parameters pClient Reference to the IoT Client pTopicName Topic Name to publish to topicNameLen Length of the topic name pApplicationHandler_t Reference to the handler function for this subscription Returns An IoT Error Type defining successful/failed subscription aws_iot_mqtt_unsubscribe(AWS_IoT_Client topicFilterLen); *pClient, const char *pTopicFilter, uint16_t - Called to send an unsubscribe message to the broker requesting removal of a subscription to an MQTT topic. Parameters pClient Reference to the IoT Client pTopicName Topic Name to publish to topicNameLen Length of the topic name Returns An IoT Error Type defining successful/failed unsubscribe call Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 13 eSE100 AWS IoT | Release Notes aws_iot_mqtt_yield(AWS_IoT_Client *pClient, uint32_t timeout_ms); - Called to yield the current thread to the underlying MQTT client. This time is used by the MQTT client to manage PING requests to monitor the health of the TCP connection as well as periodically check the socket receive buffer for subscribe messages. Yield() must be called at a rate faster than the keepalive interval. It must also be called at a rate faster than the incoming message rate as this is the only way the client receives processing time to manage incoming messages. This is the outer function which does the validations and calls the internal yield above to perform the actual operation. It is also responsible for client state changes Parameters pClient Reference to the IoT Client timeout_ms Maximum number of milliseconds to pass thread execution to the client. Returns An IoT Error Type defining successful/failed client processing. If this call results in an error it is likely the MQTT connection has dropped. iot_is_mqtt_connected can be called to confirm. aws_iot_mqtt_publish(AWS_IoT_Client *pClient, const topicNameLen, IoT_Publish_Message_Params *pParams); - char *pTopicName, uint16_t Call is blocking. In the case of a QoS 0 message the function returns after the message was successfully passed to the TLS layer. In the case of QoS 1 the function returns after the receipt of the PUBACK control packet. This is the outer function which does the validations and calls the internal publish above to perform the actual operation. It is also responsible for client state changes Parameters pClient Reference to the IoT Client pTopicName Topic Name to publish to topicNameLen Length of the topic name pParams Pointer to Publish Message parameters Returns An IoT Error Type defining successful/failed publish aws_iot_mqtt_disconnect(AWS_IoT_Client *pClient); - Called to send a disconnect message to the broker. This is the outer function which does the validations and calls the internal disconnect above to perform the actual operation. It is also responsible for client state changes Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 14 eSE100 AWS IoT | Release Notes Parameters pClient Reference to the IoT Client Returns An IoT Error Type defining successful/failed send of the disconnect control packet. - AWS IoT example application description AWS IoT Hub Instance Create an account in Amazon AWS to run the provided example code. Then create a device instance from the AWS IoT Hub Copy everything, including ".com", from REST API endpoint. Add your device to the thing registry. Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 15 eSE100 AWS IoT | Release Notes Download Certification files. Open the aws_iot_config.h file and, in the //Get from console section, update the values for the following: AWS_IOT_MQTT_HOST Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 16 eSE100 AWS IoT | Release Notes Your personal endpoint. AWS_IOT_MY_THING_NAME Your thing name. AWS_IOT_ROOT_CA_FILENAME Your root CA certificate. AWS_IOT_CERTIFICATE_FILENAME Your certificate. AWS_IOT_PRIVATE_KEY_FILENAME Your private key. For example: // Get from console // ================================================= #define AWS_IOT_MQTT_HOST "a22j5sm6o3yzc5.iot.us-east-1.amazonaws.com" #define AWS_IOT_MQTT_PORT 8883 #define AWS_IOT_MQTT_CLIENT_ID "MyRaspberryPi" #define AWS_IOT_MY_THING_NAME "MyRaspberryPi" #define AWS_IOT_ROOT_CA_FILENAME "root-CA.crt" #define AWS_IOT_CERTIFICATE_FILENAME "4bbdc778b9-certificate.pem.crt" #define AWS_IOT_PRIVATE_KEY_FILENAME "4bbdc778b9-private.pem.key" // ================================================= Launch Sample Application Build SDK Example code 1. 2. Download eSE100 SDK Project. The project contains all the required drivers to use the eSE100 board, together with pre-integrated AWS IoT SDK. Unzip the package. Open one of the pre-configured project files available in MS500_BSP_CMSIS/Application/AWS. Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 17 eSE100 3. 4. Move to the MS500_BSP_CMSIS/Application/AWS project. Open file aws_iot_config.h and update connection String (Get from console) 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/AWS/makefile -> run make 5. AWS IoT | Release Notes Upload firmware image 1. Follow the steps below to configure the board. i. ii. iii. iv. Set boot mode to 'UART to QSPI Boot'. 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. 2. Run the MS500 Firmware Initializer program. 3. 4. 5. 6. 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. 7. Check the 'FW Binary' path. Then, click 'FW Image Upload'. Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 18 eSE100 8. 9. 10. 11. AWS IoT | Release Notes 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 12. Check the FW image booting and operation. Verify eSE100 Device Operation following the execution. Attempt an automatic access to AWS Server by running the Sample code. Upon successful connection to AWS, the yellow LED turns on and then turns off. Led Status data is published regularly to the AWS Server. Monitor the operation status of the device through USB to Serial of eSE100. Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 19 eSE100 AWS IoT | Release Notes Example code Example code Description ( main.c file ) Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 20 eSE100 AWS IoT | Release Notes No. 1 Item: Before running AWS IoT SDK, perform platform-specific code for AWS Initialization. No. 2 Item: It is a specific code to connect to AWS Server Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 21 eSE100 AWS IoT | Release Notes No. 3 Item: Yield - Called to yield the current thread to the underlying MQTT client No. 4 Item: Subscribe-Data is sent to the AWS Server No. 5 Item: Called callback function when message received from AWS server. Copyright-(c)2019eWBMCo.,Ltd.Allrightsreserved 22