Merge branch 'master' of http://github.com/ChrSchultz/Arduino-lmic

Author: Christoph Schultz

README.md

@@ -1,10 +1,12 @@
-# Arduino-LMIC library
+# Arduino-LMIC library ("MCCI LoRaWAN LMIC Library")
 
 This repository contains the IBM LMIC (LoRaWAN-MAC-in-C) library, slightly
 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).
 
+> Note on names: the library was originally ported to Arduino by Matthijs Kooijman and Thomas Telkamp, and was named Arduino LMIC. Subsequently, MCCI did a lot of work to support other regions, and ultimately took over maintenance. The Arduino IDE doesn't like two libraries with the same name, so we had to come up with a new name. So in the IDE, it will appear as MCCI LoRaWAN LMIC Library; but all us know it by the primary header file, which is `<arduino_lmic.h>`.
+
 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).
@@ -16,10 +18,11 @@ see the PDF files in the doc subdirectory.
 
 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.
+The examples in this library (apart from the compliance sketch) are somewhat primitive. A very complete cross-platform Arduino application based on the LMIC has been published by Leonel Lopes Parente ([`@lnlp`](https://github.com/lnlp)) as [LMIC-node](https://github.com/lnlp/LMIC-node). That application specifically targets The Things Network.
+
+Although the wrappers in this library are designed to make the LMIC useful in the Arduino environment, the maintainers have tried to be careful to keep the core LMIC code generally useful. For example, I use this library without modification (but with wrappers) on a RISC-V platform in a non-Arduino environment.
 
-[![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) [![Arduino CI](https://img.shields.io/github/workflow/status/mcci-catena/arduino-lmic/Arduino%20CI)](https://github.com/mcci-catena/arduino-lmic/actions)
+[![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/v4.0.0...master) [![Arduino CI](https://img.shields.io/github/workflow/status/mcci-catena/arduino-lmic/Arduino%20CI)](https://github.com/mcci-catena/arduino-lmic/actions)
 
 **Contents:**
 
@@ -288,7 +291,6 @@ If the library is configured for US915 operation, we make the following changes:
 
 - Add the APIs `LMIC_enableChannel()`,
 `LMIC_enableSubBand()`, `LMIC_disableSubBand()`, and `LMIC_selectSubBand()`.
-- Add the constants `MAX_XCHANNELS`.
 - Add a number of additional `DR_...` symbols.
 
 ### Selecting the target radio transceiver
@@ -831,7 +833,7 @@ This library provides several examples.
 
 - [`compliance-otaa-halconfig.ino`](examples/compliance-otaa-halconfig/compliance-otaa-halconfig.ino) is a test sketch that is used for LoRaWAN compliance testing.
 
-- [`helium-us9115.ino`](examples\helium-us915\helium-us915.ino) is a complete example for using the LMIC on the Helium network. It's very similar to the OTAA examples, but sets up the prejoin parameters properly for the initial deployment of Helium LoRaWAN support.
+- [`helium-otaa.ino`](examples/helium-otaa/helium-otaa.ino) is a complete example for using the LMIC on the Helium network. It's very similar to the OTAA examples, but sets up the prejoin parameters properly for the initial deployment of Helium LoRaWAN support.
 
 - [`ttn-otaa-network-time.ino`](examples/ttn-otaa-network-time/ttn-otaa-network-time.ino) demonstrates use of the network time request. Network time requests are not supported by The Things Network as of the time of writing.
 
@@ -1238,9 +1240,24 @@ function uflt12f(rawUflt12)
 
 ## Release History
 
-- HEAD has the following changes.
+- HEAD contains the following changes
+  - Adapt ttn-otaa-network-time example to be compatible with [PaulStoffregen/Time](https://github.com/PaulStoffregen/Time) v1.6.1, which deletes `Time.h` in favor of `TimeLib.h` [#763](https://github.com/mcci-catena/arduino-lmic/issues/763). Version is v4.0.1-pre1.
+
+- v4.0 is a major release; changes are significant enough to be "likely breaking". It includes the following changes.
 
+  - Fix some broken documentation references [#644](https://github.com/mcci-catena/arduino-lmic/issues/644), [#646](https://github.com/mcci-catena/arduino-lmic/pulls/646), [#673](https://github.com/mcci-catena/arduino-lmic/pulls/673).
   - Re-added CI testing, since Travis CI no longer works for us [#647](https://github.com/mcci-catena/arduino-lmic/issues/647); fixed AVR compliance CI compile [#679](https://github.com/mcci-catena/arduino-lmic/issues/679).
+  - Don't use `defined()` in macro definitions [#606](https://github.com/mcci-catena/arduino-lmic/issues/606)
+  - Fix a warning on AVR32 [#709](https://github.com/mcci-catena/arduino-lmic/pulls/709).
+  - Fix Helium link in examples [#715](https://github.com/mcci-catena/arduino-lmic/issues/715), [#718](https://github.com/mcci-catena/arduino-lmic/pulls/718).
+  - Remove `XCHANNEL` support from US region [#404](https://github.com/mcci-catena/arduino-lmic/issues/404)
+  - Assign channels randomly without replacement [#515](https://github.com/mcci-catena/arduino-lmic/issues/515), [#619](https://github.com/mcci-catena/arduino-lmic/issues/619), [#730](https://github.com/mcci-catena/arduino-lmic/issues/730).
+  - Don't allow `LMIC_setupChannel()` to change default channels [#722](https://github.com/mcci-catena/arduino-lmic/issues/722). Add `LMIC_queryNumDefaultChannels()` [#700](https://github.com/mcci-catena/arduino-lmic/issues/700).
+  - Don't accept out-of-range DRs from MAC downlink messages [#723](https://github.com/mcci-catena/arduino-lmic/issues/723)
+  - Adopt semantic versions completely [#726](https://github.com/mcci-catena/arduino-lmic/issues/726).
+  - Implement JoinAccept CFList processing for US/AU [#739](https://github.com/mcci-catena/arduino-lmic/issues/739).
+  - Correct JoinAccept CFList processing for AS923 [#740](https://github.com/mcci-catena/arduino-lmic/issues/740).
+  - Don't compile board config objects when we know for sure they'll not be used; compilers can't always tell [#736](https://github.com/mcci-catena/arduino-lmic/issues/736).
 
 - v3.3.0 is primarily a maintenance and roll-up release.
 
@@ -1328,7 +1345,7 @@ This library started from the IBM V1.5 open-source code.
 
 - [`@ngraziano`](https://github.com/ngraziano) did extensive testing and contributed numerous ADR-related patches.
 
-There are many others, who have contributed code and also participated in discussions, performed testing, reported problems and results. Thanks to all who have participated.
+There are many others, who have contributed code and also participated in discussions, performed testing, reported problems and results. Thanks to all who have participated. We hope to use something like [All Contributors](https://https://allcontributors.org/) to help keep this up to date, but so far the automation isn't working.
 
 ## Trademark Acknowledgements
 

doc/LMIC-v3.3.0.docx

@@ -76,6 +76,8 @@ const lmic_pinmap lmic_pins = {
 // Just like Feather M0 LoRa, but uses SPI at 1MHz; and that's only
 // because MCCI doesn't have a test board; probably higher frequencies
 // will work.
+// /!\ By default Feather 32u4's pin 6 and DIO1 are not connected. Please 
+// ensure they are connected.
 const lmic_pinmap lmic_pins = {
     .nss = 8,
     .rxtx = LMIC_UNUSED_PIN,

doc/LMIC-v3.3.0-redline.pdf renamed to doc/LMIC-v4.0.0-redline.pdf

@@ -95,6 +95,8 @@ const lmic_pinmap lmic_pins = {
 // Just like Feather M0 LoRa, but uses SPI at 1MHz; and that's only
 // because MCCI doesn't have a test board; probably higher frequencies
 // will work.
+// /!\ By default Feather 32u4's pin 6 and DIO1 are not connected. Please 
+// ensure they are connected.
 const lmic_pinmap lmic_pins = {
     .nss = 8,
     .rxtx = LMIC_UNUSED_PIN,

doc/LMIC-v4.0.0.docx

@@ -27,10 +27,15 @@
  * DevEUI and AppKey.
  *
  * Do not forget to define the radio type correctly in config.h.
+ * 
+ * You will need to also install the library github.com/PaulStoffregen/Time;
+ * you need a version that has TimeLib.h.
  *
  *******************************************************************************/
 
-#include <Time.h>
+// requires library: github.com/PaulStoffregen/Time
+#include <TimeLib.h>    // can't use <Time.h> starting with v1.6.1
+
 #include <lmic.h>
 #include <hal/hal.h>
 #include <SPI.h>

doc/LMIC-v3.3.0.pdf renamed to doc/LMIC-v4.0.0.pdf

@@ -1,5 +1,5 @@
 name=MCCI LoRaWAN LMIC library
-version=3.3.0
+version=4.0.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.

examples/raw-feather/raw-feather.ino

@@ -13,6 +13,10 @@ Copyright & License:
 
 */
 
+#if defined(ARDUINO_MCCI_CATENA_4420) || \
+    /* legacy names */ \
+    defined(ARDUINO_CATENA_4420)
+
 #include <arduino_lmic_hal_boards.h>
 #include <Arduino.h>
 
@@ -71,4 +75,6 @@ const HalPinmap_t *GetPinmap_Catena4420(void)
 	return &myPinmap;
 	}
 
-} // namespace Arduino_LMIC;
+} // namespace Arduino_LMIC
+
+#endif