Merge pull request #634 from mcci-catena/issue633

Prepare for V3.3.0 release

.github/ISSUE_TEMPLATE/00-support-request.md

@@ -7,14 +7,19 @@ assignees: terrillmoore
 
 ---
 
+**Consider raising support questions on the forum first**
+
+There is a discussion site, [forum.mcci.io](https://forum.mcci.io), which includes a [category focused on the Arduino LMIC](https://forum.mcci.io/c/device-software/arduino-lmic/5). Unless you're sure that your problem is a bug in the LMIC, it would be great if you can try for help there first. That will keep issues focused on work that needs to be done by the developers.
+
 **Describe your question or issue**
-A clear and concise description of the problem you're facing and what you'd like help with.
+
+Please give a clear and concise description of the problem you're facing and what you'd like help with.
 
 **Environment**
 
-This information is all important; it's hard to help without a complete set of answers.
+This information is very important; it's hard to help without a complete set of answers.
 
-- Version of LMIC being used: 
+- Version of LMIC being used. If using the latest github mainline, let us know, otherwise state the version.
 - Version of Arduino IDE being used:
 - Network provider (The Things Network, Swisscom, ChirpStack, etc.)
 - Region (EU868, US915, etc.)

.github/ISSUE_TEMPLATE/bug_report.md → .github/ISSUE_TEMPLATE/10-bug_report.md

@@ -9,28 +9,32 @@ assignees: terrillmoore
 
 **Describe the bug**
 
-A clear and concise description of what the bug is. _If you're not sure it's a bug, please file a Support Request instead._ A bug is a problem in the code, where you do something that the documentation says should work, but doesn't; _and_ you have reason to believe it's not working due to a defect in the code.
+A clear and concise description of what the bug is. _If you're not sure it's a bug, please consider opening a discussion at [forum.mcci.io](https://forum.mcci.io/c/device-software/arduino-lmic/5), or file a Support Request instead._ A bug is a problem in the code, where you do something that the documentation says should work, but doesn't; _and_ you have reason to believe it's not working due to a defect in the code.
 
 Wireless is tricky; if in doubt, start with a support request, rather than a bug report.
 
 **Environment**
 
-- Version of LMIC being used: 
-- Version of Arduino IDE being used:
+- Version of LMIC being used. If using the latest GitHub mainline, let us know, otherwise state the version.
+- Version of Arduino IDE being used.
 - Network provider (The Things Network, Swisscom, ChirpStack, etc.)
 - Region (EU868, US915, etc.)
 - Board (MCCI Catena, Adafruit Feather M0, Heltec, etc.)
 - CPU (AVR, STM32L0, etc.)
 - Radio (HopeRF, SX1276, etc.)
 
 **To Reproduce**
+
 Steps to reproduce the problem.
 
 **Expected behavior**
+
 A clear and concise description of what you expected to happen.
 
 **Screenshots**
+
 If applicable, add screenshots to help explain your problem.
 
 **Additional context**
+
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/30-doc_issue.md

@@ -0,0 +1,22 @@
+---
+name: Documentation issue
+about: Report a problem in the documentation
+title: ''
+labels: docs
+assignees: terrillmoore
+
+---
+
+Thanks for your contribution!
+
+**What document is involved?**
+
+If this is an existing document, please include the full path to the file.
+
+If there's a need for a new document, please suggest the places in existing docs that should link to it.
+
+Make sure you mention the version, and please also check the current version at GitHub, to be sure that the problem hasn't already been corrected for a pending release.
+
+**What changes are needed?**
+
+Indicate the changes you think are needed. Explicit help is always better. File a PR with your changes if possible!

.travis.yml

@@ -326,6 +326,7 @@ script:
  - _notstm32l0 ||  arduino --verify --board $(_stm32l0opts 'mcci_catena_4618' us915  ) $MCCI_STM32_OPTS $PWD/examples/raw-halconfig/raw-halconfig.ino
  - _notstm32l0 ||  arduino --verify --board $(_stm32l0opts 'mcci_catena_4630' us915  ) $MCCI_STM32_OPTS $PWD/examples/raw-halconfig/raw-halconfig.ino
  - _notstm32l0 ||  arduino --verify --board $(_stm32l0opts 'mcci_catena_4801' us915  ) $MCCI_STM32_OPTS $PWD/examples/raw-halconfig/raw-halconfig.ino
+ - _notstm32l0 ||  arduino --verify --board $(_stm32l0opts 'mcci_catena_4802' us915  ) $MCCI_STM32_OPTS $PWD/examples/raw-halconfig/raw-halconfig.ino
 
  - _notstm32l0 ||  { _projcfg COMPILE_REGRESSION_TEST CFG_us915 CFG_sx1276_radio && arduino --verify --board $(_stm32l0opts 'mcci_catena_4551' projcfg) $MCCI_STM32_OPTS $PWD/examples/ttn-otaa-halconfig-us915/ttn-otaa-halconfig-us915.ino ; }
  - _notstm32l0 ||  { _projcfg COMPILE_REGRESSION_TEST CFG_us915 CFG_sx1276_radio && arduino --verify --board $(_stm32l0opts 'mcci_catena_4610' projcfg) $MCCI_STM32_OPTS $PWD/examples/ttn-otaa-halconfig-us915/ttn-otaa-halconfig-us915.ino ; }
@@ -335,6 +336,7 @@ script:
  - _notstm32l0 ||  { _projcfg COMPILE_REGRESSION_TEST CFG_us915 CFG_sx1276_radio && arduino --verify --board $(_stm32l0opts 'mcci_catena_4618' projcfg) $MCCI_STM32_OPTS $PWD/examples/ttn-otaa-halconfig-us915/ttn-otaa-halconfig-us915.ino ; }
  - _notstm32l0 ||  { _projcfg COMPILE_REGRESSION_TEST CFG_us915 CFG_sx1276_radio && arduino --verify --board $(_stm32l0opts 'mcci_catena_4630' projcfg) $MCCI_STM32_OPTS $PWD/examples/ttn-otaa-halconfig-us915/ttn-otaa-halconfig-us915.ino ; }
  - _notstm32l0 ||  { _projcfg COMPILE_REGRESSION_TEST CFG_us915 CFG_sx1276_radio && arduino --verify --board $(_stm32l0opts 'mcci_catena_4801' projcfg) $MCCI_STM32_OPTS $PWD/examples/ttn-otaa-halconfig-us915/ttn-otaa-halconfig-us915.ino ; }
+ - _notstm32l0 ||  { _projcfg COMPILE_REGRESSION_TEST CFG_us915 CFG_sx1276_radio && arduino --verify --board $(_stm32l0opts 'mcci_catena_4802' projcfg) $MCCI_STM32_OPTS $PWD/examples/ttn-otaa-halconfig-us915/ttn-otaa-halconfig-us915.ino ; }
 
 
  ### end of file ###

README.md

@@ -5,17 +5,21 @@ modified to run in the Arduino environment, allowing using the SX1272,
 SX1276 transceivers and compatible modules (such as some HopeRF RFM9x
 modules and the Murata LoRa modules).
 
-This library mostly exposes the functions defined by LMIC, it makes no
+Information about the LoRaWAN protocol is summarized in [LoRaWAN-at-a-glance](doc/LoRaWAN-at-a-glance.pdf). Full information is available from the [LoRa Alliance](https://lora-alliance.org).
+
+A support forum is available at [forum.mcci.io](https://forum.mcci.io/c/device-software/arduino-lmic/5).
+
+The base Arduino library mostly exposes the functions defined by LMIC. It makes no
 attempt to wrap them in a higher level API that is more in the Arduino
 style. To find out how to use the library itself, see the examples, or
-see the PDF file in the doc subdirectory.
+see the PDF files in the doc subdirectory.
 
-The [MCCI `arduino-lorawan`](https://github.com/mcci-catena/arduino-lorawan) library provides a higher level, more Arduino-like wrapper which may be useful.
+A separate library, [MCCI `arduino-lorawan`](https://github.com/mcci-catena/arduino-lorawan), provides a higher level, more Arduino-like wrapper which may be useful.
 
 This library requires Arduino IDE version 1.6.6 or above, since it
 requires C99 mode to be enabled by default.
 
-[![GitHub release](https://img.shields.io/github/release/mcci-catena/arduino-lmic.svg)](https://github.com/mcci-catena/arduino-lmic/releases/latest) [![GitHub commits](https://img.shields.io/github/commits-since/mcci-catena/arduino-lmic/latest.svg)](https://github.com/mcci-catena/arduino-lmic/compare/v3.2.0...master) [![Build Status](https://travis-ci.com/mcci-catena/arduino-lmic.svg?branch=master)](https://travis-ci.com/mcci-catena/arduino-lmic)
+[![GitHub release](https://img.shields.io/github/release/mcci-catena/arduino-lmic.svg)](https://github.com/mcci-catena/arduino-lmic/releases/latest) [![GitHub commits](https://img.shields.io/github/commits-since/mcci-catena/arduino-lmic/latest.svg)](https://github.com/mcci-catena/arduino-lmic/compare/v3.3.0...master) [![Build Status](https://travis-ci.com/mcci-catena/arduino-lmic.svg?branch=master)](https://travis-ci.com/mcci-catena/arduino-lmic)
 
 **Contents:**
 
@@ -33,75 +37,78 @@ requires C99 mode to be enabled by default.
 <!-- TOC depthFrom:2 updateOnSave:true -->
 
 - [Installing](#installing)
+- [Getting Help](#getting-help)
+	- [If it's not working](#if-its-not-working)
+	- [If you've found a bug](#if-youve-found-a-bug)
 - [Features](#features)
 - [Additional Documentation](#additional-documentation)
-	- [PDF/Word Documentation](#pdfword-documentation)
-	- [Adding Regions](#adding-regions)
-	- [Known bugs and issues](#known-bugs-and-issues)
-		- [Timing Issues](#timing-issues)
-		- [Working with MCCI Murata-based boards](#working-with-mcci-murata-based-boards)
-		- [Event-Handling Issues](#event-handling-issues)
+        - [PDF/Word Documentation](#pdfword-documentation)
+        - [Adding Regions](#adding-regions)
+        - [Known bugs and issues](#known-bugs-and-issues)
+                - [Timing Issues](#timing-issues)
+                - [Working with MCCI Murata-based boards](#working-with-mcci-murata-based-boards)
+                - [Event-Handling Issues](#event-handling-issues)
 - [Configuration](#configuration)
-	- [Selecting the LoRaWAN Version](#selecting-the-lorawan-version)
-		- [Selecting V1.0.2](#selecting-v102)
-		- [Selecting V1.0.3](#selecting-v103)
-	- [Selecting the LoRaWAN Region Configuration](#selecting-the-lorawan-region-configuration)
-		- [eu868, as923, in866, kr920](#eu868-as923-in866-kr920)
-		- [us915, au915](#us915-au915)
-	- [Selecting the target radio transceiver](#selecting-the-target-radio-transceiver)
-	- [Controlling use of interrupts](#controlling-use-of-interrupts)
-	- [Disabling PING](#disabling-ping)
-	- [Disabling Beacons](#disabling-beacons)
-	- [Enabling Network Time Support](#enabling-network-time-support)
-	- [Rarely changed variables](#rarely-changed-variables)
-		- [Changing debug output](#changing-debug-output)
-		- [Getting debug from the RF library](#getting-debug-from-the-rf-library)
-		- [Selecting the AES library](#selecting-the-aes-library)
-		- [Defining the OS Tick Frequency](#defining-the-os-tick-frequency)
-		- [Setting the SPI-bus frequency](#setting-the-spi-bus-frequency)
-		- [Changing handling of runtime assertion failures](#changing-handling-of-runtime-assertion-failures)
-		- [Disabling JOIN](#disabling-join)
-		- [Disabling Class A MAC commands](#disabling-class-a-mac-commands)
-		- [Disabling Class B MAC commands](#disabling-class-b-mac-commands)
-		- [Disabling user events](#disabling-user-events)
-		- [Disabling external reference to `onEvent()`](#disabling-external-reference-to-onevent)
-		- [Enabling long messages](#enabling-long-messages)
-		- [Enabling LMIC event logging calls](#enabling-lmic-event-logging-calls)
-		- [Special purpose](#special-purpose)
+        - [Selecting the LoRaWAN Version](#selecting-the-lorawan-version)
+                - [Selecting V1.0.2](#selecting-v102)
+                - [Selecting V1.0.3](#selecting-v103)
+        - [Selecting the LoRaWAN Region Configuration](#selecting-the-lorawan-region-configuration)
+                - [eu868, as923, in866, kr920](#eu868-as923-in866-kr920)
+                - [us915, au915](#us915-au915)
+        - [Selecting the target radio transceiver](#selecting-the-target-radio-transceiver)
+        - [Controlling use of interrupts](#controlling-use-of-interrupts)
+        - [Disabling PING](#disabling-ping)
+        - [Disabling Beacons](#disabling-beacons)
+        - [Enabling Network Time Support](#enabling-network-time-support)
+        - [Rarely changed variables](#rarely-changed-variables)
+                - [Changing debug output](#changing-debug-output)
+                - [Getting debug from the RF library](#getting-debug-from-the-rf-library)
+                - [Selecting the AES library](#selecting-the-aes-library)
+                - [Defining the OS Tick Frequency](#defining-the-os-tick-frequency)
+                - [Setting the SPI-bus frequency](#setting-the-spi-bus-frequency)
+                - [Changing handling of runtime assertion failures](#changing-handling-of-runtime-assertion-failures)
+                - [Disabling JOIN](#disabling-join)
+                - [Disabling Class A MAC commands](#disabling-class-a-mac-commands)
+                - [Disabling Class B MAC commands](#disabling-class-b-mac-commands)
+                - [Disabling user events](#disabling-user-events)
+                - [Disabling external reference to `onEvent()`](#disabling-external-reference-to-onevent)
+                - [Enabling long messages](#enabling-long-messages)
+                - [Enabling LMIC event logging calls](#enabling-lmic-event-logging-calls)
+                - [Special purpose](#special-purpose)
 - [Supported hardware](#supported-hardware)
 - [Pre-Integrated Boards](#pre-integrated-boards)
 - [PlatformIO](#platformio)
 - [Manual configuration](#manual-configuration)
-	- [Power](#power)
-	- [SPI](#spi)
-	- [DIO pins](#dio-pins)
-	- [Reset](#reset)
-	- [RXTX](#rxtx)
-	- [RXTX Polarity](#rxtx-polarity)
-	- [Pin mapping](#pin-mapping)
-		- [Advanced initialization](#advanced-initialization)
-		- [HalConfiguration_t methods](#halconfiguration_t-methods)
-		- [LoRa Nexus by Ideetron](#lora-nexus-by-ideetron)
+        - [Power](#power)
+        - [SPI](#spi)
+        - [DIO pins](#dio-pins)
+        - [Reset](#reset)
+        - [RXTX](#rxtx)
+        - [RXTX Polarity](#rxtx-polarity)
+        - [Pin mapping](#pin-mapping)
+                - [Advanced initialization](#advanced-initialization)
+                - [HalConfiguration_t methods](#halconfiguration_t-methods)
+                - [LoRa Nexus by Ideetron](#lora-nexus-by-ideetron)
 - [Example Sketches](#example-sketches)
 - [Timing](#timing)
-	- [Controlling protocol timing](#controlling-protocol-timing)
-	- [`LMIC_setClockError()`](#lmic_setclockerror)
-	- [Interrupts and Arduino system timing](#interrupts-and-arduino-system-timing)
+        - [Controlling protocol timing](#controlling-protocol-timing)
+        - [`LMIC_setClockError()`](#lmic_setclockerror)
+        - [Interrupts and Arduino system timing](#interrupts-and-arduino-system-timing)
 - [Downlink data rate](#downlink-data-rate)
 - [Encoding Utilities](#encoding-utilities)
-	- [sflt16](#sflt16)
-		- [JavaScript decoder](#javascript-decoder)
-	- [uflt16](#uflt16)
-		- [uflt16 JavaScript decoder](#uflt16-javascript-decoder)
-	- [sflt12](#sflt12)
-		- [sflt12f JavaScript decoder](#sflt12f-javascript-decoder)
-	- [uflt12](#uflt12)
-		- [uflt12f JavaScript decoder](#uflt12f-javascript-decoder)
+        - [sflt16](#sflt16)
+                - [JavaScript decoder](#javascript-decoder)
+        - [uflt16](#uflt16)
+                - [uflt16 JavaScript decoder](#uflt16-javascript-decoder)
+        - [sflt12](#sflt12)
+                - [sflt12f JavaScript decoder](#sflt12f-javascript-decoder)
+        - [uflt12](#uflt12)
+                - [uflt12f JavaScript decoder](#uflt12f-javascript-decoder)
 - [Release History](#release-history)
 - [Contributions](#contributions)
 - [Trademark Acknowledgements](#trademark-acknowledgements)
 - [License](#license)
-	- [Support Open Source Hardware and Software](#support-open-source-hardware-and-software)
+        - [Support Open Source Hardware and Software](#support-open-source-hardware-and-software)
 
 <!-- /TOC -->
 <!-- markdownlint-restore -->
@@ -120,6 +127,16 @@ To install this library:
 
 For more info, see [https://www.arduino.cc/en/Guide/Libraries](https://www.arduino.cc/en/Guide/Libraries).
 
+## Getting Help
+
+### If it's not working
+
+Ask questions at [`forum.mcci.io`](https://forum.mcci.io/c/device-software/arduino-lmic/5). Wireless is tricky, so don't be afraid to ask. The LMIC has been used successfully in a lot of applications, but it's common to have problems getting it working. To keep the code size down, there are not a lot of debugging features, and the features are not always easy to use.
+
+### If you've found a bug
+
+Raise a GitHub issue at [`github.com/mcci-catena/arduino-lmic`](https://github.com/mcci-catena/arduino-lmic/issues/).
+
 ## Features
 
 The LMIC library provides a fairly complete LoRaWAN Class A and Class B
@@ -462,7 +479,7 @@ The following boards are pre-integrated.
 - Adafruit [Feather 32u4 LoRa 900 MHz][1] (SX1276)
 - Adafruit [Feather M0 LoRa 900 MHz][2] (SX1276)
 - MCCI Catena 4410, 4420, [4450][3], [4460][4] and [4470][5] boards (based on Adafruit Feather boards plus wings) (SX1276)
-- MCCI Catena 4551, [4610][6], 4611, [4612][7], 4617, [4618][7a], 4630, and [4801][8] boards (based on the Murata CMWX1ZZABZ-078 module) (SX1276)
+- MCCI Catena 4551, [4610][6], 4611, [4612][7], 4617, [4618][7a], 4630, [4801][8] and 4802[12] boards (based on the Murata CMWX1ZZABZ-078 module) (SX1276)
 - [TTGo LoRa32 V1][10] (based on the ESP32)
 - [Heltec WiFi LoRa 32 V2][11] (based on the ESP32)
 
@@ -477,6 +494,7 @@ The following boards are pre-integrated.
 [8]: https://store.mcci.com/collections/lorawan-iot-and-the-things-network/products/catena-4801
 [10]: https://makeradvisor.com/tools/ttgo-lora32-sx1276-esp32-oled/
 [11]: https://heltec.org/project/wifi-lora-32/
+[12]: https://store.mcci.com/collections/lorawan-iot-and-the-things-network/products/catena-4802
 
 > To help you know if you have to worry, we'll call such boards "pre-integrated" and prefix each section with suitable guidance.
 
@@ -1220,6 +1238,12 @@ function uflt12f(rawUflt12)
 
 ## Release History
 
+- v3.3.0 is primarily a maintenance and roll-up release.
+
+   - Added [LoRaWAN-at-a-glance](doc/LoRaWAN-at-a-glance.pdf) and a [state diagram of the LMIC](doc/LMIC-FSM.pdf).
+   - Several PRs from Matthijs Kooijman to improve compatibility with the original Arduino LMIC ([#608](https://github.com/mcci-catena/arduino-lmic/issue/608), [#609](https://github.com/mcci-catena/arduino-lmic/issue/609)).
+   - Numerous documentation improvements contributed by the community ([#431](https://github.com/mcci-catena/arduino-lmic/issue/), [#612](https://github.com/mcci-catena/arduino-lmic/issue/612), [#614](https://github.com/mcci-catena/arduino-lmic/issue/614), [#625](https://github.com/mcci-catena/arduino-lmic/issue/625)).
+
 - v3.2.0 has the following changes:
 
   - [#550](https://github.com/mcci-catena/arduino-lmic/issue/550) fixes debug prints in `ttn-otaa.ino`.

library.properties

@@ -1,5 +1,5 @@
 name=MCCI LoRaWAN LMIC library
-version=3.2.0
+version=3.3.0
 author=IBM, Matthijs Kooijman, Terry Moore, ChaeHee Won, Frank Rose
 maintainer=Terry Moore <[email protected]>
 sentence=Arduino port of the LMIC (LoraWAN-MAC-in-C) framework provided by IBM.

src/arduino_lmic_hal_boards.h

@@ -35,6 +35,7 @@ const HalPinmap_t *GetPinmap_Catena4617();
 const HalPinmap_t *GetPinmap_Catena4618();
 const HalPinmap_t *GetPinmap_Catena4630();
 const HalPinmap_t *GetPinmap_Catena4801();
+const HalPinmap_t *GetPinmap_Catena4802();
 const HalPinmap_t* GetPinmap_ttgo_lora32_v1();
 const HalPinmap_t* GetPinmap_heltec_lora32();
 const HalPinmap_t* GetPinmap_Disco_L072cz_Lrwan1();