From 6455542e2ea8c0a3f14bea17386cf71043486ce4 Mon Sep 17 00:00:00 2001 From: Leonel Lopes Parente Date: Fri, 23 Apr 2021 19:57:20 +0200 Subject: [PATCH] Update README.md --- README.md | 161 +++++++++++++++++++++++++++++------------------------- 1 file changed, 86 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 645c079..7869778 100644 --- a/README.md +++ b/README.md @@ -49,10 +49,12 @@ One example to rule them all - [6.3 Distance to gateway](#63-distance-to-gateway) - [7 Additional information](#7-additional-information) - [7.1 External libraries](#71-external-libraries) - - [7.2 Not yet tested](#72-not-yet-tested) -- [8 Example Output](#8-example-output) + - [7.2 Known issues](#72-known-issues) + - [7.3 Not yet tested](#73-not-yet-tested) +- [8 Example output](#8-example-output) - [8.1 Serial Monitor](#81-serial-monitor) - [8.2 Display](#82-display) +- [9 Release History](#9-release-history) ## 1 Introduction @@ -206,36 +208,44 @@ The following status information is shown: At the start: -- Timeout countdown value while waiting for serial port to become ready is shown on the display. -*This value is only shown for boards where `WAITFOR_SERIAL_SECONDS_DEFAULT` is defined in the BSF with a value unequal to 0.* +- Timeout countdown value while waiting for serial port to become ready is shown on the display. This value is only shown for boards where `WAITFOR_SERIAL_SECONDS_DEFAULT` is defined in the BSF with a value unequal to 0. In the header: - Program title "LMIC-node". - Device-id. -- DoWork job time interval (DO_WORK_INTERVAL_SECONDS). -- If OTAA or ABP activation is used *(serial port only)*. +- Used LMIC library. MCCI or Classic. On display only an asterisk will be shown if Classic is used. +- If OTAA or ABP activation is used. On display only ABP will be shown if used. +- LMIC debug level if > 0. *(on serial port only)* +- DoWork job time interval (DO_WORK_INTERVAL_SECONDS). On display 'interval' label is abbreviated to "I". + +When joined: + +- Network-id. *(on serial port only, MCCI LMIC only)* +- Device address. *(on serial port only, MCCI LMIC only)* +- Sessions keys *(son erial port only, MCCI LMIC only)* Continuously: - During transmission of uplink and downlink messages a transmit symbol will be shown in the top-right of the display. -- A notification when the doWork job is started. -- A notification when the counter is read, with its value. +- A notification when the doWork job is started. *(on serial port only)* +- A notification when input data was collected *(on serial port only)* +- Message with Counter value. On display label is abbreviated to "Ctr". - A notification "packet queued" when an uplink message is scheduled. - A notification if a packet cannot be scheduled because transmission or reception of another message is still pending. - An error message if scheduling of an uplink message failed. - Events generated by the LMIC library (e.g. EV_JOINED, EV_TXCOMPLETE). -- When event EV_TXCOMPLETE is received the uplink and downlink framecounters are printed. +- When event EV_TXCOMPLETE is received the frame counters are printed. - For each downlink message the following will be shown: - Message that downlink was received - RSSI and SNR values - Frame port number - - If data was received the length is shown - - If data was received the data is shown as a sequence of byte vales *(serial port only)* - - Message if reset-counter command was received + - If data was received, length of data + - If data was received, the data is shown as as byte *(serial port only)* + - Message if reset-counter command was received *(serial port only*) - Notification when counter is reset. -For events and notification a timestamp (`ostime`) will be shown. +For events and notifications a timestamp (`ostime`) will be shown. LMIC uses values of the type ostime_t to represent time in ticks. The rate of these ticks defaults to 32768 ticks per second (but may be configured at compile time to any value between 10000 ticks per second and 64516 ticks per second). #### 3.3.2 LED @@ -310,9 +320,7 @@ Tip: For testing purposes it is possible to create two different devices in the This is only used for boards with 8-bit AVR MCU. - **[env:_\_]** - Board specific sections (called _Environments_ in PlatformIO terminology). E.g. [env:lolin32]. - A board specific section contains settings that are specific for one type of board. - It contain settings like which LMIC library to use and program options like USE_SERIAL, USE_LED and USE_DISPLAY. + Board specific sections (called _Environments_ in PlatformIO terminology). E.g. [env:lolin32]. A board specific section contains settings that are specific for one type of board. It contain settings like which LMIC library to use and program options like USE_SERIAL, USE_LED and USE_DISPLAY. Comments in platformio.ini start with a semicolon ( ; ) character. To uncomment a line remove the semicolon prefix. To comment a line add a semicolon prefix. @@ -429,7 +437,7 @@ bool boardInit(InitType initType) Payload formatter functions are located in the `payload-formatters` folder. #### 3.10.1 Uplink decoder -LMIC-node comes with a JavaScript payload formatter function for decoding the uplink messages so the counter value gets displayed in 'Live data' on the TTN Console. The `decodeUplink()` function can be found in file `lmic-node-uplink-formatters.js` located in the `payload-formatters` folder and is shown below: +LMIC-node comes with a JavaScript payload formatter function for decoding the uplink messages so the counter value gets displayed in 'Live data' on the TTN Console. The `decodeUplink()` function can be found in folder `payload-formatters` in file `lmic-node-uplink-formatters.js`. ```js function decodeUplink(input) { @@ -504,18 +512,23 @@ default_envs = ```ini [common] + monitor_speed = 115200 build_flags = -D DO_WORK_INTERVAL_SECONDS=60 - ; -D ABP_ACTIVATION ; Use ABP instead of OTAA activation + ; -D ABP_ACTIVATION ; Use ABP instead of OTAA activation ; - ; -D WAITFOR_SERIAL_SECONDS=10 ; Can be used to override the default value (10) - ; Only used for boards with default set to != 0 in BSF + ; -D WAITFOR_SERIAL_SECONDS=10 ; Can be used to override the default value (10) + ; Only used for boards with default set to != 0 in BSF + ; + ; -D STM32_POST_INITSERIAL_DELAY_MS=1500 ; Workaround for STM32 boards. Can be used + ; to override value (milliseconds) in BSF + lib_deps = - olikraus/U8g2 ; OLED display library - lnlp/EasyLed ; LED library + olikraus/U8g2 ; OLED display library + lnlp/EasyLed ; LED library ``` **monitor_speed** @@ -539,6 +552,10 @@ A positive value will wait with a countdown delay (visible on display) for the n Be aware that the serial port must not only be ready but also a serial monitor needs to be connected. The countdown gives some time to start the serial monitor if not already started. A timeout value prevents that the node waits indefinitely if not connected to a computer. It will continue when the countdown ends. +**STM32_POST_INITSERIAL_DELAY_MS** +For STM32 boards a delay is inserted after initializing the serial port. This is a workaround to prevent that the first output send to the serial port gets lost. +This value is defined in STM32 boards BSF but can be overridden in platformio.ini. + ### 4.3 LoRaWAN library settings #### 4.3.1 MCCI LoRaWAN LMIC library settings @@ -569,8 +586,6 @@ build_flags = -D DISABLE_PING -D DISABLE_BEACONS - ; If LMIC_DEBUG_LEVEL is set to value > 0 then LMIC_PRINTF_TO will - ; be automatically set to serial (do not set it explicitly). ; -D LMIC_DEBUG_LEVEL=1 ; 0, 1 or 2 ; -D CFG_sx1272_radio=1 ; Use for SX1272 radio @@ -593,7 +608,7 @@ build_flags = ; -D CFG_us915=1 ``` -**Regional setting** +**Regional setting** --- Regional settings --- is where the regional setting needs to be selected. Uncomment the line with the appropriate region setting (and comment the other region settings). Only one region may be selected. By default CFG_eu868 (Europe) is selected. @@ -609,8 +624,9 @@ For more information see the MCCI LoRaWAN LMIC library documentation. #### 4.3.2 IBM LMIC framework settings ```ini +[classic_lmic] ; IMPORTANT: -; This library was recently deprecated and is no longer maintained. +; This library was recently DEPRECATED and is no longer maintained. ; It is not fully LoRaWAN compliant (e.g. in handling of MAC commands) ; and is therefore less suitable for use with The Things Network V3. ; @@ -639,12 +655,13 @@ build_flags = -D DISABLE_BEACONS ``` -**Region, radio and debug settings CANNOT be changed in platformio.ini.** -**When making changes to `config.h` these must be changed separately per board!** +**Region, radio and debug settings CANNOT be changed in `platformio.ini`.** +**When making changes to `config.h` these must be changed separately per board!** File `config.h` is located in these folders: `.pio/libdeps//IBM LMIC framework/src/lmic` -These settings cannot be changed in platformio.ini because they are 'hardcoded' in config.h which is located in a library source code location. -These settings must be changed separately per board because the way PlatformIO handles libraries (a copy of each library is added for each board). +Above settings cannot be changed in platformio.ini because they are defined in config.h in the library source code. The settings must be changed separately per board because PlatformIO downloads libraries separately for each board. + +**Do NOT use ABP activation when using the IBM LMIC framework library. On The Things Network V3 this will cause a downlink message for EVERY uplink message because it does properly handle MAC commands.** ### 4.4 Board specific settings @@ -655,28 +672,24 @@ Example board section for BSFrance LoRa32u4 II board: ```ini [env:lora32u4II] ; BSFrance LoRa32u4 II (ATmega32u4) -; Depending on the version this board may require additional wiring for DIO1. -; lmic-node will not work with MCCI LMIC for this board because not enough memory. -; Therefore Classic LMIC is hardcoded here (independent of setting in [common]). -; No onboard display. -; This is an 8-bit MCU with limited memory, therefore IBM LMIC framework library is used. +; Board versions 1.0 to 1.2 require manual wiring of DIO1 to GPIO5 +; 8-bit AVR MCU with limited memory, therefore IBM LMIC framework is used +; No display platform = atmelavr board = lora32u4II framework = arduino monitor_speed = ${common.monitor_speed} lib_deps = ${common.lib_deps} - ${classic_lmic.lib_deps} - ; ${mcci_lmic.lib_deps} ; MCCI LMIC better LoRaWAN compliance but uses more memory + ${classic_lmic.lib_deps} ; [Deprecated] IBM LMIC Framework build_flags = ${common.build_flags} - ${classic_lmic.build_flags} - ; ${mcci_lmic.build_flags} ; MCCI LMIC better LoRaWAN compliance but uses more memory + ${classic_lmic.build_flags} ; [Deprecated] IBM LMIC Framework -D BSFILE=\"boards/lora32u4II.h\" -D MONITOR_SPEED=${common.monitor_speed} -D USE_SERIAL -D USE_LED - ; -D USE_DISPLAY ; Requires external I2C OLED display + ; -D USE_DISPLAY ; Requires external I2C OLED display ``` Example board section for Blue Pill board with external LoRa module: @@ -684,7 +697,8 @@ Example board section for Blue Pill board with external LoRa module: ```ini [env:bluepill_f103c8] ; Bluepill F103C8 (64k) (STMF103C8T6) -; Select the upload protocol to use below. +; Select preferred upload protocol below +; No display platform = ststm32 board = bluepill_f103c8 framework = arduino @@ -702,49 +716,35 @@ build_flags = -D MONITOR_SPEED=${common.monitor_speed} -D USE_SERIAL -D USE_LED - ; -D USE_DISPLAY ; Requires external I2C OLED display + ; -D USE_DISPLAY ; Requires external I2C OLED display ``` By default all USE\_ options for a board are enabled. If the option is not enabled by default then it is either not supported (e.g. due to hardware conflict) or in case of USE_DISPLAY requires an external display to be connected. The USE_DISPLAY option can then be enabled after the display is connected. Each of these options uses memory. In case of memory constrainted 8-bit boards disabling some of these option may free some memory for other use (e.g. use MCCI LIMIC library or enable LMIC debugging). -**USE_SERIAL** +**USE_SERIAL** If enabled status output will be send to the serial port to be viewed on serial monitor. -**USE_LED** +**USE_LED** If enabled it will use the onboard LED. The board will be lit during Tx/Rx transmission and is off otherwise. For some boards the onboard LED cannot be used because of a hardware conflict, because the LED type is not supported (e.g. WS2812 RGB LED) or because there is no onboard user LED. If the onboard LED cannot be used then this option is disabled by default and the line will be commented to make this clear. -**USE_DISPLAY** +**USE_DISPLAY** If enabled status output will be send to the display. -**upload_protocol** +**upload_protocol** For some boards it may be necessary to change the upload protocol, e.g. for bluepill change it from `stlink` to `serial` if firmware is uploaded via USB to serial adapter instead of using a STLink programmer. **LMIC library** By default all boards with 32-bit MCU are configured to use the MCCI LoRaWAN LMIC library (MCCI LMIC) because this is the library to use. It is the most LoRaWAN compliant LMIC library for Arduino and it is actively maintained. - By default all boards with 8-bit MCU are configured to use the IBM LMIC framework library (Classic LMIC). These boards have limited memory capacity and Classic LMIC uses less memory than MCCI LMIC. From LoRaWAN compliance and improved functionality perspective MCCI LMIC is preferred but with MCCI LMIC it is not possible to use all LMIC-node features on these 8-bit boards. - - Two use an LMIC library two entries are required, one for `lib_deps` and one for `build_flags`. For the 8-bit boards these are included for both the Classic LMIC and MCCI LMIC libraries but the ones for MCCI LMIC are disabled (commented). - To use the MCCI LMIC library instead of the Classic LMIC library, the entries for Classic LMIC must be disabled (commented) and the entries for MCCI LMIC must be enabled. - -```ini -lib_deps = - ${classic_lmic.lib_deps} - ; ${mcci_lmic.lib_deps} ; MCCI LMIC better LoRaWAN compliance but uses more memory -build_flags = - ${classic_lmic.build_flags} - ; ${mcci_lmic.build_flags} ; MCCI LMIC better LoRaWAN compliance but uses more memory -``` + By default all boards with 8-bit MCU are configured to use the IBM LMIC framework library (Classic LMIC). These boards have limited memory capacity and Classic LMIC uses less memory than MCCI LMIC. Because of better LoRaWAN compliance and improved functionality MCCI LMIC is preferred but there is not enough memory to use LMIC-node with MCCI LMIC on these boards. The other entries in the board sections should stay unchanged. -See PlatformIO documentation for other possible platformio.ini options. - ### 4.5 Board Support Files -Each BSF contains the following settings. Values shown here are examples and need not to be defined for each board. +Each BSF contains the following settings. Except for DEVICEID_DEFAULT these settings are not enabled for each board. Values shown are examples. ```cpp #define DEVICEID_DEFAULT "pro-mini" // Default deviceid value @@ -764,11 +764,11 @@ Each BSF contains the following settings. Values shown here are examples and nee If no `DEVICEID` is defined and no `ABP_DEVICEID` is defined when ABP activation is used then `DEVICEID_DEFAULT` is used. There is no need to change this value in the BSP. `DEVICEID` and `ABP_DEVICEID` can be defined in file `lorawan-keys.h` where they are kept nicely together the LoRaWAN keys of the same device. -**WAITFOR_SERIAL_SECONDS_DEFAULT** +**WAITFOR_SERIAL_SECONDS_DEFAULT** Defines the default value used for the 'wait for serial' timeout. This value is only defined in the BSP for boards where USB support is integrated into the MCU. It has no use for other boards. If there is need to change this value then don't change the default value in the BSP and change `WAITFOR_SERIAL_SECONDS` in the `[common]` section in `platformio.ini` instead. -**LMIC_CLOCK_ERROR_PPM** +**LMIC_CLOCK_ERROR_PPM** Setting this value will cause LMIC timing to be less strict. This is only needed for some boards (usually 8-bit AVR based boards). This value should normally not be changed especially for 32-bit MCU boards. If there are any issues with timing then increasing this value could possibly help. All boards supported by LMIC-node have already been tested and for boards that need it LMIC_CLOCK_ERROR_PPM is already enabled with a value that has proven to be sufficient. @@ -783,20 +783,22 @@ In `platformio.ini`: **Step 1a**: Select exactly one supported board by uncommenting the line with its board-id and name. -**Step 1b**: Comment the line starting with `` to disable the guard. +**Step 1b**: Comment the guard line to disable it. This is the line that starts with ``. ### 5.2 Select your LoRaWAN region -When using **MCCI LMIC** (set as default for 32-bit boards): -**Step 2:** In platformio.ini select you LoRaWAN region. +For MCCI LMIC (default for 32-bit boards): +**Step 2:** In `platformio.ini` select you LoRaWAN region. +or +For Classic LMIC (default for 8-bit boards): +**Step 2**: In `config.h` select your LoRaWAN region (if not CFG_eu868). See [IBM LMIC framework settings](#432-ibm-lmic-framework-settings) for details. -When using **Classic LMIC** (set as default for 8-bit boards): -**Step 2**: If your region is not CFG_eu868, select your region in config.h. See [IBM LMIC framework settings](#432-ibm-lmic-framework-settings). +*If you are not sure which of the above to select then check the section for your board in `platformio.ini`.* ### 5.3 Provide the LoRaWAN keys for your node -**Step 3a**: If this has not been done before: In the `keyfiles` folder copy file `lorawan-keys_example.h` to `lorawan-keys.h`. +**Step 3a**: If this is the first time: In the `keyfiles` folder copy file `lorawan-keys_example.h` to `lorawan-keys.h`. **Step 3b**: In file `lorawan-keys.h` add the LoRaWAN keys for the device that were copied from the TTN Console. @@ -818,7 +820,7 @@ The node will be running but to be able to see the counter value in uplink messa **Step 5**: In the TTN Console, add the `decodeUplink()` JavaScript function as uplink payload formatter to the device. As formatter type select `JavaScript` and the function must be pasted in the field `Formatter parameter`. -The `decodeUplink()` JavaScript function can be found in file `lmic-node-uplink-formatters.js` which is located in folder `payload-formatters`. +The `decodeUplink()` function can be found in folder `payload-formatters` in file `lmic-node-uplink-formatters.js`. When this function is installed, the counter value will be shown in uplink messages in 'Live data' on the TTN Console. @@ -834,8 +836,8 @@ For boards with MCU with built-in USB support LMIC-node by default waits with a ### 6.2 Antenna -- **The antenna should always be connected when the device is powered!** -Powering the board while the antenna is disconnected may damage the LoRa radio. +- **The antenna should always be connected when the device is powered!** + Powering the board with antenna disconnected may damage the LoRa radio. - For best results the antenna should be used in upright (vertical) position. @@ -856,7 +858,11 @@ The following external libraries are used: | U8g2 | Display | https://github.com/olikraus/u8g2 | | EasyLed | LED | https://github.com/lnlp/EasyLed | -### 7.2 Not yet tested +### 7.2 Known issues + +The MCCI LoRaWAN LMIC library has a problem with SerialUSB on the Arduino Zero (USB) board. +When defining `LMIC_DEBUG_LEVEL` with a value > 0, `LMIC_PRINTF_TO` will automatically be set to `serial` (which automatically points to SerialUSB) but no debug information arrives on the serial monitor. If `LMIC_PRINTF_TO` is set to `SerialUSB` in `platformio.ini` (`-D LMIC_PRINTF_TO=SerialUSB`) then the compiler gives an error that something is missing in the MCCI LMIC library. So it is currently not possible to print MCCI LMIC debug information for this board. +### 7.3 Not yet tested All supported boards have been tested except for below boards for which hardware was not available. These boards should work but some may need some extra attention (see _remarks_ below). @@ -878,7 +884,7 @@ _Lolin D32 Pro was tested which is very similar._ _T-Beam V1.1 may work by using board-id ttgo_tbeam_v1 but this has not been tested. It is currently unknown what the differences between V1.1 and V1.0 are._ -## 8 Example Output +## 8 Example output Below are some examples of status output from serial monitor and display. ### 8.1 Serial Monitor @@ -889,6 +895,11 @@ To be added. To be added.
+## 9 Release History + +- **v1.0.0 Initial release** + - First release of LMIC-node. + --- Copyright (c) 2021 Leonel Lopes Parente