Fix #454: add V1.0.2 config for US pow2dbm()

US compliance testing doesn't support v1.0.3 devices that support
the extended power range. For squeaky-clean logs, add an option to
select whether we're complying with 1.0.3 or 1.0.2. Do it in a way
that allows generalization to future 1.1 support.

README.md

@@ -42,6 +42,9 @@ requires C99 mode to be enabled by default.
 		- [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, au921](#us915-au921)
@@ -188,10 +191,48 @@ so that your local changes are more clearly separated from
 the distribution files. The Arduino environment doesn't give
 us a better way to do this, unless you change `BOARDS.txt`.
 
-Unlike other ports of the LMIC code, in this port, you should not edit `src/lmic/config.h` to configure this package.
+Unlike other ports of the LMIC code, in this port, you should not edit `src/lmic/config.h` to configure this package. The intention is that you'll edit the `project_config/lmic_project_config.h` (if using the Arduino environment), or change compiler command-line input (if using PlatformIO, make, etc.).
 
 The following configuration variables are available.
 
+### Selecting the LoRaWAN Version
+
+This library implements V1.0.3 of the LoRaWAN specification. However, it can also be used with V1.0.2. The only significant change when selecting V1.0.2 is that the US accepted power range in MAC commands is 10 dBm to 30 dBm; whereas in V1.0.3 the accepted range 2 dBm to 30 dBm.
+
+The default LoRaWAN version, if no version is explicitly selected, is V1.0.3.
+
+`LMIC_LORAWAN_SPEC_VERSION` is defined as an integer reflecting the targeted spec version; it will be set to `LMIC_LORAWAN_SPEC_VERSION_1_0_2` or `LMIC_LORAWAN_SPEC_VERSION_1_0_3`. Arithmetic comparisons can be done on these version numbers: and we guarantee `LMIC_LORAWAN_SPEC_VERSION_1_0_3 > LMIC_LORAWAN_SPEC_VERSION_1_0_2`, but the details of the how the versions are encoded may change, and your code should not rely upon the details.
+
+#### Selecting V1.0.2
+
+In `project_config/lmic_project_config.h`, add:
+
+```c
+#define LMIC_LORAWAN_SPEC_VERSION   LMIC_LORAWAN_SPEC_VERSION_1_0_2
+```
+
+On your compiler command line, add:
+
+```shell
+-D LMIC_LORAWAN_SPEC_VERSION=LMIC_LORAWAN_SPEC_VERSION_1_0_2
+```
+
+#### Selecting V1.0.3
+
+In `project_config/lmic_project_config.h`, add:
+
+```c
+#define LMIC_LORAWAN_SPEC_VERSION    LMIC_LORAWAN_SPEC_VERSION_1_0_3
+```
+
+On your compiler command line, add:
+
+```shell
+-D LMIC_LORAWAN_SPEC_VERSION=LMIC_LORAWAN_SPEC_VERSION_1_0_3
+```
+
+This is the default.
+
 ### Selecting the LoRaWAN Region Configuration
 
 The library supports the following regions:
@@ -210,7 +251,7 @@ The library requires that the compile environment or the project config file def
 
 MCCI BSPs add menu entries to the Arduino IDE so you can select the target region interactively.
 
-The library changes configuration pretty substantially according to the region selected, and this affects the symbols in-scope in your sketches and cpp files. Some of the differences are listed below. This list is not comprehensive, and is subject to change in future major releases.
+The library changes configuration pretty substantially according to the region selected, and this affects the symbols in-scope in your sketches and `.cpp` files. Some of the differences are listed below. This list is not comprehensive, and is subject to change in future major releases.
 
 #### eu868, as923, in866, kr920
 

src/lmic/config.h

@@ -199,4 +199,9 @@
 # define LMIC_ENABLE_event_logging 0        /* PARAM */
 #endif
 
+// LMIC_LORAWAN_SPEC_VERSION
+#if !defined(LMIC_LORAWAN_SPEC_VERSION)
+# define LMIC_LORAWAN_SPEC_VERSION	LMIC_LORAWAN_SPEC_VERSION_1_0_3
+#endif
+
 #endif // _lmic_config_h_

src/lmic/lmic_config_preconditions.h

@@ -203,4 +203,13 @@ Revision history:
 #define CFG_LMIC_EU_like        (!!(CFG_LMIC_REGION_MASK & CFG_LMIC_EU_like_MASK))
 #define CFG_LMIC_US_like        (!!(CFG_LMIC_REGION_MASK & CFG_LMIC_US_like_MASK))
 
+//
+// The supported LMIC LoRaWAAN spec versions. These need to be numerically ordered,
+// so that we can (for example) compare
+//
+//    LMIC_LORAWAN_SPEC_VERSION < LMIC_LORAWAN_SPEC_VERSION_1_0_3.
+//
+#define LMIC_LORAWAN_SPEC_VERSION_1_0_2  0x01000200u
+#define LMIC_LORAWAN_SPEC_VERSION_1_0_3  0x01000300u
+
 #endif /* _LMIC_CONFIG_PRECONDITIONS_H_ */

src/lmic/lmic_us915.c

@@ -68,7 +68,10 @@ uint8_t LMICus915_maxFrameLen(uint8_t dr) {
 }
 
 int8_t LMICus915_pow2dbm(uint8_t mcmd_ladr_p1) {
-        if ((mcmd_ladr_p1 & MCMD_LinkADRReq_POW_MASK) == MCMD_LinkADRReq_POW_MASK)
+        if ((mcmd_ladr_p1 & MCMD_LinkADRReq_POW_MASK) >
+            ((LMIC_LORAWAN_SPEC_VERSION < LMIC_LORAWAN_SPEC_VERSION_1_0_3)
+                        ? US915_LinkAdrReq_POW_MAX_1_0_2
+                        : US915_LinkAdrReq_POW_MAX_1_0_3))
                 return -128;
         else
                 return ((s1_t)(US915_TX_MAX_DBM - (((mcmd_ladr_p1)&MCMD_LinkADRReq_POW_MASK)<<1)));

src/lmic/lorabase_us915.h

@@ -77,6 +77,12 @@ enum {
                                         // on an 64-channel bandplan. See code
                                         // that computes tx power.
 };
+
+enum {
+        US915_LinkAdrReq_POW_MAX_1_0_2 = 0xA,
+        US915_LinkAdrReq_POW_MAX_1_0_3 = 0xE,
+};
+
 enum { DR_PAGE_US915 = 0x10 * (LMIC_REGION_us915 - 1) };
 
 enum { US915_LMIC_REGION_EIRP = 0 };         // region doesn't use EIRP, uses tx power