Difference between revisions of "MCU/WISE-1510 SDK"
Line 311: | Line 311: | ||
[[File:WISE-1510-12.png|RTENOTITLE]] | [[File:WISE-1510-12.png|RTENOTITLE]] | ||
+ | |||
+ | == Application Development == | ||
+ | |||
+ | Node APIs were provided to assist user develop applications. There are 2 UART interfaces in WISE-1510. “debug_serial” is used for user development and debug. User can see debug information of sample code via debug_serial. “m2_serial” is the UART interface of M2.com. | ||
+ | |||
+ | [[File:WISE-1510-13.png]] | ||
+ | |||
+ | | ||
+ | |||
+ | === Node API === | ||
+ | |||
+ | <br/>Following show the architecture of the layer of LoRa Node and user application. User can send request to LoRa node via API and got response. Besides, application can also be notified by callback function if some event occurs from LoRa node. | ||
+ | |||
+ | [[File:WISE-1510-14.png]] | ||
+ | |||
+ | The detailed description of APIs can be found in /docs/html/index.html in the released SDK. | ||
+ | |||
+ | === Sample Code for API === | ||
+ | |||
+ | If WISE-1510 was plugged in M2.com carrier board (WISE-DB1500), do below action to enable M2.com carrier board. | ||
+ | |||
+ | [[File:WISE-1510-15.png]]<br/> | ||
+ | |||
+ | Set boud rate of debug_serial and m2_serial. | ||
+ | |||
+ | [[File:WISE-1510-16.png]]<br/>Create sensor thread. | ||
+ | |||
+ | [[File:WISE-1510-17.png]]<br/>Set and apply node configuration. | ||
+ | |||
+ | [[File:WISE-1510-18.png]]<br/>Start LoRa. | ||
+ | |||
+ | [[File:WISE-1510-19.png]]<br/>Start LoRa State loop to start rx/tx data. | ||
+ | |||
+ | [[File:WISE-1510-20.png]] | ||
+ | |||
+ | Deep sleep mode is supported but disabled in default, please enable NODE_DEEP_SLEEP_MODE_SUPPORT if you want to try low power mode. | ||
+ | |||
+ | [[File:WISE-1510-21.png]] | ||
+ | |||
+ | Two API were used to notify user application that LoRa finished transmit or receive action. What you should do is Register callback function in the beginning.<br/> | ||
+ | |||
+ | [[File:WISE-1510-22.png]] | ||
+ | |||
+ | Make sure node successfully joined LoRa gateway. | ||
+ | |||
+ | [[File:WISE-1510-23.png]]<br/>Then, start to run the state machine. If no data need to send, enter deep sleep mode and wait for waking up NODE_ACTIVE_PERIOD_IN_SEC seconds. | ||
+ | |||
+ | [[File:WISE-1510-24.png]] | ||
+ | |||
+ | This example send sensor (Temperature, Humidity) data periodically, user should modify node_get_sensor_data() to implement read sensor data. If Tx complete, node_tx_done_cb() will transfer to NODE_STATE_LOWPOWER and prepare to read/send sensor data again. If LoRa node got downlink data, node_rx_done_cb() will be invoked to get data. Then transfer to NODE_STATE_LOWPOWER.<br/> | ||
+ | |||
+ | [[File:WISE-1510-25.png]] | ||
+ | |||
+ | The detailed description of Sample code can be found in /docs/html/index.html in the released SDK. | ||
+ | |||
+ | Appendix I: Node Setup Parameters | ||
+ | |||
+ | In the sample application, there is a function node_set_config() as below: | ||
+ | |||
+ | [[File:WISE-1510-26.png]] | ||
+ | |||
+ | This function is used to configure all parameters of nodes. Let’s go through them briefly. | ||
+ | |||
+ | #Device EUI (DevEUI) is read from eFuse, and set without any change. | ||
+ | #Two application dependent parameters, application EUI (AppEUI) and application key (APPKey), are set respectively (line 218 and 219). | ||
+ | #Device address (DevAddr) is derived from DevEUI by extracting the last 8 bytes (line 220), and set (line 221). It’s up to users to define the format as long as it matches with gateway’s setting. | ||
+ | #Two session keys: network session key (NwkSKey) and application session key (AppSKey) are set (line 222 and 223). | ||
+ | #So far, all required parameters for node activation are set properly. Then, you can decide to activate the node by either ABP (Activation By Provisioning) or OTAA (Over-The-Air Activation). Here, we set it to ABP (line 224). Please be noted that, only three of the above parameters are used for ABP, including DevAddr, NwkSKey and AppSKey. If you’d like to use OTAA, then change the input parameter of nodeApiSetDevActMode() from 2 to 1. The other three parameters are used for OTAA, including DevEUI, AppEUI, and APPKey are set. | ||
+ | #Select nodes to work with LoRaWAN or Harmony Link by setting the device operating mode (DevOpMode): 1 for Harmony Link* and 2 for LoRaWAN. Here, Harmony Link is selected as the default. (line 225) If you’d like to use LoRaWAN, change it from 1 to 2. | ||
+ | |||
+ | * Harmony Link is Advantech’s proprietary LoRa MAC. | ||
+ | |||
+ | #You can select which class of Node: 1 for Class A, and 3 for Class C. (2 for Class B is reserved for future use.) Here, Class C is selected (line 226). | ||
+ | #The remaining part are used to set radio related parameters, including data rate (DevAdvwiseDataRate), frequency (DevAdvwiseFreq) and transmission power (DevAdvwiseTxPwr) (line 227~229). Please be noted all of RF parameters are region dependent, so you’ve to set their values accordingly. Make sure you DO NOT violate the regional regulation. | ||
+ | |||
+ | After all parameters are configured, be reminded to apply them by nodeApiApplyCfg(). | ||
+ | |||
+ | === Appendix II: Sensor Data Format === | ||
+ | |||
+ | In the sample application, node_get_sensor_data() encodes sensor data according to the following format: | ||
+ | |||
+ | [[File:WISE-1510-27.png]] | ||
+ | |||
+ | ,where | ||
+ | |||
+ | Length: Total TLV length | ||
+ | |||
+ | MsgType: Fixed as 0xc | ||
+ | |||
+ | Multiple TLVs are one or more Tag-Length-Values: tag matches with gateway’s setting, length is sensor data length, and value is sensor data. All octets are in hexadecimal. | ||
+ | |||
+ | For example, LoRa Payload Field setting on WISE-3610 is as below: | ||
+ | |||
+ | [[File:WISE-1510-28.png]] | ||
+ | |||
+ | If temperature is 25.55 Celsius degree, translate decimal 2555 to hexadecimal 9FB. Similarly, if humidity is 60.55%, translate from decimal 6055 to hexadecimal 17A7. The encoded data will be | ||
+ | |||
+ | 0x9 | 0xc | 0x1 | 0x3 | 0x1 | 0x9 | 0xFB | 0x2 | 0x2 | 0x17 | 0xA7 | ||
+ | |||
+ | , where | ||
+ | |||
+ | 0x9: the Total TLV length, included two TLVs | ||
+ | |||
+ | 0xc: the fixed MsgType | ||
+ | |||
+ | 0x1 | 0x3 | 0x1 | 0x9 | 0xFB: the first TLV with tag id (0x1), value length (0x3), and positive (0x1) value (0x9FB) | ||
+ | |||
+ | 0x2 | 0x2 | 0x17 | 0xA7: the second TLV with tag id (0x2), value length (0x2), and unsigned value (0x17A7) | ||
+ | |||
+ | Be reminded temperature “Sign” setting is On, 1 extra byte is required to indicate (0 means negative, and 1 means positive) , but humidity "Sign" setting on gateway is Off, so no extra 1 byte is required. | ||
+ | |||
+ | Users are free to define their own payload field format, but only sensor data encoded according to the above format can be decoded successfully, and displayed on LoRa Dashboard on WISE-3610. |
Revision as of 01:39, 18 April 2017
Contents
Introduction
WISE-1510 is a wireless module integrated with ARM Cortex-M4 Processor and LoRa / LoRaWAN connectivity. This technology is the best solution for Low-Power Wide-Area Network (LPWAN) Applications. LoRaWAN is defined to optimize the power consumption and wide range. Your sensors or applications with low data rate requirement can be achieved years battery lifetime and kilometers long distance connection. Advantech WISE-1510 also provides multi-interfaces for sensor and I/O control. With ARM mbed embedded microprocessor operating system and add-on software stacks, it's convenient to build the application software or sensor algorithm over mbed OS. Data can be quickly and easily acquired and transformed into a different format to communicate with WISE-PaaS or other cloud services. Developer can build their application backbone faster and focus on their applications, value-added services.
Quick Starter of WISE-1510
Debug Port Connection
- Connect debug port FPC cable to WISE-1510 debug port (CN1; on the back of PCB)
- Connect WISE-ED20 debug board to the FPC debug cable.
- Connect USB-to-microUSB cable from WISE-ED20 to the USB port on your PC.
Debug Port Setting
WISE-1510 can communicate with a host server (Windows or Linux) by using serial cables. Common serial communication programs such as Hyper Terminal, Tera Term or PuTTY can be used in this case. The example below describes the serial terminal setup using Hyper Terminal on a Windows host:
- Connect WISE-ED20 with your Windows PC by using a serial cable.
- Open Hyper Terminal on your Windows PC, and select the settings as shown below.
- Press reset (red-frame) button on ED-20.
- Terminal will show the image version
Development Environment Setup
Overview
ARM mbed is used for you to create applications running on WISE-1510. Your application code is written in C++. It uses the application programming interfaces (APIs) that mbed OS provides. These APIs allow your code to work on different microcontrollers in a uniform way. This reduces a lot of the challenges in getting started with microcontrollers and integrating large amounts of software. Besides, we also provide you node APIs which facilitates LoRa node development. Our offline development tool is the mbed CLI, a command-line tool. This requires having a toolchain installed on your computer. mbed CLI is the name of the ARM mbed command-line tool, packaged as mbed-cli, which enables the full mbed workflow: repositories version control, maintaining dependencies, publishing code, updating from remotely hosted repositories and invoking ARM mbed’s own build system and export functions, among other operations. The basic workflow for mbed CLI is to:
- Initialize a new repository, for either a new application (or library) or an imported one.
- Build the application code.
- Test your build.
- Publish your application.
Installation
To install mbed CLI, related tools are required to be installed first. Please refer to the video tutorial. ( https://www.youtube.com/watch?v=cM0dFoTuU14 )
Please follow the steps described in the tutorial video to install mbed CLI.
- Install Python
mbed CLI supports Windows, Linux and Mac OS X operating systems. You can select the OS you prefer to work with. mbed CLI is a Python script, so you’ll need Python to use it. The version 2.7.11 of Python has been verified with mbed CLI.
https://www.python.org/downloads/release/python-2711/
Note: mbed CLI is incompatible with Python 3.
- (Optional) Install Git or Mercurial
If you would like to maintain your source code in repositories, you can continue with the next step. mbed CLI supports both Git and Mercurial repositories, you can install which one you prefer:
Git - version 1.9.5 or later ( https://git-scm.com/ ).
Mercurial - version 2.2.2 or later ( https://www.mercurial-scm.org/ ).
If you don’t want to use repositories, you can just skip it.
- Install gcc
mbed CLI invokes the mbed OS 5 tools for various features, such as compiling, testing and exporting to industry standard toolchains. To compile your code, you will need either a compiler or an IDE:
- Compilers: GCC ARM, ARM Compiler 5, IAR.
- IDE: Keil uVision, DS-5, IAR Workbench.
We select GCC ARM Embedded, so you can install version 4.9 of GCC ARM Embedded ( https://launchpad.net/gcc-arm-embedded ).
Note: Version 5.0 or any other versions above may be incompatible with the tools.
- Install mbed CLI
You can get the latest stable version of mbed CLI from PyPI
<code>$ pip </code>'''install''' mbed-cli
Note: On Linux or Mac, you may need to run with sudo.
Finally, you’ve to extract the source code to the working directory from the SDK we released. The structure of the working directory is as below:
docs/ <-- Documents for SDK
loranode_L443_sdk_R1_0_02/mbed-os/ <-- mbed os
loranode_L443_sdk_R1_0_02/libHLLoraNode.a <-- Harmony Link Lora Node library
loranode_L443_sdk_R1_0_02/node_api.h <-- Node API header file
loranode_L443_sdk_R1_0_02/main.cpp <-- Sample code
Configuration
After the installation of required tool chains, please set up the directory of mbed CLI to link the folder of toolchains which you want to use for compiling the source tree.
You can set the GCC ARM Embedded location via the command as below:
$ mbed config '''--'''</code>'''global''' GCC_ARM_PATH "C:\Program Files\GCC_ARM"
[mbed] C:\</code>Program<code> Files\GCC_ARM now </code>set as global GCC_ARM_PATH
Next, you can select the tool chain and target platform which mbed CLI uses to build applications. Change directory to target mbed program.
$ mbed config target NUCLEO_L443RC </code>
[mbed] NUCLEO_L443RC now set as default target in program "xxxxx" </code>
$ mbed config toolchain GCC_ARM </code>
[mbed] GCC_ARM now set as default toolchain in program "xxxx" </code>
You can see the active mbed CLI configuration via:
$ mbed config --</code>'''list'''
[mbed] </code>'''Global'''<code> config:</code>
GCC_ARM_PATH<code> =C:\</code>'''Program'''<code> Files\GCC_ARM</code>
[mbed] Local config (xxxx):</code>
TOOLCHAIN=GCC_ARM</code>
TARGET=NUCLEO_L443RC</code>
Compilation
mbed CLI uses the current directory as a working context. This means that before calling any mbed CLI command, you must first change to the working directory containing the code. Then, Use the mbed compile command to compile your code:
$ mbed compile -c
Building project xxxxx (NUCLEO_L443RC, GCC_ARM)
Scan: .
Scan: mbed
Scan: env
Compile [ 0.5%]: base64.cpp
Compile [ 1.0%]: oslmic.cpp
…
Compile [100.0%]: node_sapi.cpp
Link: xxxxx
Elf2Bin: xxxxx
+--------------------+--------+-------+-------+
| Module | .text | .data | .bss |
+--------------------+--------+-------+-------+
| Fill | 223 | 16 | 41 |
| Misc | 104316 | 7804 | 5017 |
| drivers | 3592 | 4 | 224 |
| hal | 802 | 0 | 8 |
| platform | 1782 | 4 | 297 |
| rtos | 910 | 4 | 4 |
| rtos/rtx | 7369 | 20 | 6870 |
| targets/TARGET_STM | 19944 | 4 | 1719 |
| Subtotals | 138938 | 7856 | 14180 |
+--------------------+--------+-------+-------+
Allocated Heap: unknown
Allocated Stack: unknown
Total Static RAM memory (data + bss): 22036 bytes
Total RAM memory (data + bss + heap + stack): 22036 bytes
Total Flash memory (text + data + misc): 146794 bytes
Image: ./BUILD/NUCLEO_L443RC/GCC_ARM/xxxxx.bin
Now, you have your application in binary format ready for flashing.
Memory Layout
A basic overview of mbed memory model is as below:
Each thread of execution in the RTOS has a separate stack. When you use the RTOS, before explicitly initializing any additional thread, you will have four separate stacks:
• The stack of the main thread (executing the main function).
• The idle thread executed each time all the other threads are waiting for external or scheduled events. This is particularly useful for implementing energy saving strategies (like sleep).
• The timer thread that executes all the time-scheduled tasks (periodic and nonperiodic).
• The stack of OS scheduler itself (also used by the ISRs).
Stack checking is turned on for all threads, and the kernel will error if an overflow condition is detected.
Partitioning
The content of flash is portioned by boot loader as below:
Boot Loader occupies the first 16 kilo-bytes starting at 0x8000000. LoRa Config partition is used to store LoRa parameters, which occupies no more than 4 kilo-bytes. All user own parameters should be written into User Config partition, for which another 4 kilo-bytes are reserved. Application (Runtime image) partition is where users’ application is stored, up to 224 kilo-bytes can be used.
Flashing Application (Runtime Image)
To flash runtime image, your terminal program needs to support “Y-Modem”.
Tera Term is used for demonstration here.
Step 1. UART port connect via debug board
Connect USB-to-microUSB cable from WISE-ED20 to the USB port on your Windows PC.
Open the corresponding COM port in serial program, ex: Tera Term.
Set baud rate to 115200.
Step 2: Runtime image upgrade mode
Press ‘u’ on the PC keyboard and press reset button on ED-20 debug board.
The terminal will show messages as below.
Press "1" to “Download image to the internal Flash”.
Step 3: Start upgrading via Y modem
Select the run-time image ".bin" file via Y-Modem.
Waiting for run-time image transmission is complete.
After downloading completed, the terminal will show as below.
Step 4: Reset device
Press reset button on ED-20 debug board to reset device.
Testing
Now, you’re ready to test your WISE-1510. The sample application we created is to send sensor data every 5 seconds via LoRa if values are changed. To observe it, you can connect the debug port as described earlier. After reset WISE-1510, the result is shown on your Terminal as below:
Application Development
Node APIs were provided to assist user develop applications. There are 2 UART interfaces in WISE-1510. “debug_serial” is used for user development and debug. User can see debug information of sample code via debug_serial. “m2_serial” is the UART interface of M2.com.
Node API
Following show the architecture of the layer of LoRa Node and user application. User can send request to LoRa node via API and got response. Besides, application can also be notified by callback function if some event occurs from LoRa node.
The detailed description of APIs can be found in /docs/html/index.html in the released SDK.
Sample Code for API
If WISE-1510 was plugged in M2.com carrier board (WISE-DB1500), do below action to enable M2.com carrier board.
Set boud rate of debug_serial and m2_serial.
Set and apply node configuration.
Start LoRa State loop to start rx/tx data.
Deep sleep mode is supported but disabled in default, please enable NODE_DEEP_SLEEP_MODE_SUPPORT if you want to try low power mode.
Two API were used to notify user application that LoRa finished transmit or receive action. What you should do is Register callback function in the beginning.
Make sure node successfully joined LoRa gateway.
Then, start to run the state machine. If no data need to send, enter deep sleep mode and wait for waking up NODE_ACTIVE_PERIOD_IN_SEC seconds.
This example send sensor (Temperature, Humidity) data periodically, user should modify node_get_sensor_data() to implement read sensor data. If Tx complete, node_tx_done_cb() will transfer to NODE_STATE_LOWPOWER and prepare to read/send sensor data again. If LoRa node got downlink data, node_rx_done_cb() will be invoked to get data. Then transfer to NODE_STATE_LOWPOWER.
The detailed description of Sample code can be found in /docs/html/index.html in the released SDK.
Appendix I: Node Setup Parameters
In the sample application, there is a function node_set_config() as below:
This function is used to configure all parameters of nodes. Let’s go through them briefly.
- Device EUI (DevEUI) is read from eFuse, and set without any change.
- Two application dependent parameters, application EUI (AppEUI) and application key (APPKey), are set respectively (line 218 and 219).
- Device address (DevAddr) is derived from DevEUI by extracting the last 8 bytes (line 220), and set (line 221). It’s up to users to define the format as long as it matches with gateway’s setting.
- Two session keys: network session key (NwkSKey) and application session key (AppSKey) are set (line 222 and 223).
- So far, all required parameters for node activation are set properly. Then, you can decide to activate the node by either ABP (Activation By Provisioning) or OTAA (Over-The-Air Activation). Here, we set it to ABP (line 224). Please be noted that, only three of the above parameters are used for ABP, including DevAddr, NwkSKey and AppSKey. If you’d like to use OTAA, then change the input parameter of nodeApiSetDevActMode() from 2 to 1. The other three parameters are used for OTAA, including DevEUI, AppEUI, and APPKey are set.
- Select nodes to work with LoRaWAN or Harmony Link by setting the device operating mode (DevOpMode): 1 for Harmony Link* and 2 for LoRaWAN. Here, Harmony Link is selected as the default. (line 225) If you’d like to use LoRaWAN, change it from 1 to 2.
- Harmony Link is Advantech’s proprietary LoRa MAC.
- You can select which class of Node: 1 for Class A, and 3 for Class C. (2 for Class B is reserved for future use.) Here, Class C is selected (line 226).
- The remaining part are used to set radio related parameters, including data rate (DevAdvwiseDataRate), frequency (DevAdvwiseFreq) and transmission power (DevAdvwiseTxPwr) (line 227~229). Please be noted all of RF parameters are region dependent, so you’ve to set their values accordingly. Make sure you DO NOT violate the regional regulation.
After all parameters are configured, be reminded to apply them by nodeApiApplyCfg().
Appendix II: Sensor Data Format
In the sample application, node_get_sensor_data() encodes sensor data according to the following format:
,where
Length: Total TLV length
MsgType: Fixed as 0xc
Multiple TLVs are one or more Tag-Length-Values: tag matches with gateway’s setting, length is sensor data length, and value is sensor data. All octets are in hexadecimal.
For example, LoRa Payload Field setting on WISE-3610 is as below:
If temperature is 25.55 Celsius degree, translate decimal 2555 to hexadecimal 9FB. Similarly, if humidity is 60.55%, translate from decimal 6055 to hexadecimal 17A7. The encoded data will be
0x9 | 0xc | 0x1 | 0x3 | 0x1 | 0x9 | 0xFB | 0x2 | 0x2 | 0x17 | 0xA7
, where
0x9: the Total TLV length, included two TLVs
0xc: the fixed MsgType
0x1 | 0x3 | 0x1 | 0x9 | 0xFB: the first TLV with tag id (0x1), value length (0x3), and positive (0x1) value (0x9FB)
0x2 | 0x2 | 0x17 | 0xA7: the second TLV with tag id (0x2), value length (0x2), and unsigned value (0x17A7)
Be reminded temperature “Sign” setting is On, 1 extra byte is required to indicate (0 means negative, and 1 means positive) , but humidity "Sign" setting on gateway is Off, so no extra 1 byte is required.
Users are free to define their own payload field format, but only sensor data encoded according to the above format can be decoded successfully, and displayed on LoRa Dashboard on WISE-3610.