Overview of LoRaWAN libraries - LMiC, LoRaMAC-node and their variations [HowTo]

The purpose of this topic is to provide an overview of existing LoRaWAN libraries that can be used for the development of nodes (a.k.a. end-devices).

:arrow_right: We need your input - Please help make the list complete. Thanks!

If you know an existing LoRaWAN library that is not yet listed in this topic then PLEASE add a post with information about the library to this topic.

Some guidelines for this thread (topic):

When adding variations (see below) of an already existing library, please only add it to the list if the library was modified for a well documented reason (e.g. to make it run better on a certain microcontroller family like ESP32 or STM32) and that it might be of interest to a wider public.
But do not add any personal copies (e.g. forks you can find on github) that lack a clear description of changes (if any) and (even while public) are only meant for personal use.

For any LoRaWAN library please specify the following information:

At the start of the post please add a clear description of the library (more verbose than for the ‘Description’ property) and try to make clear what makes this library different from its parent, why it is different and/or why it is better. (But don’t make it a ‘search the differences’ exercise for the reader.)

Property Value
Name: <official library name>
(see PlatformIO Libraries registry)
Version: <library version>** (at the time of adding the post)
Frameworks: <supported development frameworks>
(see PlatformIO Frameworks registry)
Platforms: <supported microcontroller families>
(see PlatformIO Development Platforms registry)
Description: <description> (called sentence in library.properties)
URL: <source/repository URL>**
Type: <Port, Variaton, New or dash(-) if unknown>
(Port is substantial, Variation contains only minimal changes)
BaseType: <LMIC or LoRaMac-node>
Parent Name: <parent’s official library name> (dash(-) if not appropriate or unknown)
Parent URL: <parent’s repository URL> (dash(-) if not appropriate or unknown)

Many of above library properties can be found in property files like library.properties or .library.json.

PlatformIO has already defined names for Platforms and Frameworks (many supported). It is practical to use the names already defined and maintained by PlatformIO.
Note: use only lower case and replace spaces by underscores, which is how PlatformIO uses it.

For an example see the next post.


Some background:

There exist at least two major LoRaWAN library implementations that can be used for for end nodes:

  1. IBM’s original LMiC (formerly ‘LoRa MAC in C’) implementation.
  2. Semtech’s LoRaMac-node reference implementation.

I call LMiC and LoRaMac-node base types.

Both base types have been ported to different platforms (microcontroller families) e.g. AVR, SAM, STM32, nRF5x, ESP32 and different development frameworks e.g. Arduino, ARM Mbed etc.

The Arduino framework is popular within maker and hobbyist communities. IBM’s LMiC has been ported to the Arduino framework and is commonly referred to as Arduino LMIC. The first Arduino LMIC implementation was LMIC-Arduino which has long served as the reference implementation but it is no longer maintained. The new reference implementation is MCCI LoRaWAN LMIC library which is improved and actively maintained (see below).

The Arduino framework initially was available only for the AVR family of microcontrollers, but nowadays there are Arduino framework implementations (called Arduino Cores) for many microcontroller families like AVR, SAMD, STM32, ESP32, ESP8266 and nRF5x.
While the Arduino LMIC reference implementations can be used with multiple microcontroller families, there also exist modified versions that are specially adapted for a certain microcontroller. I call these variations (or decendants) of Arduino LMIC and call Arduino LMIC the parent of the decendant.

Many libraries have an official name that is different from the name of their (GitHub) repository. The official library name is important for development tools like PlatformIO which can automatically download libraries if their official name is specified in the platformio.ini project configuration file.

7 Likes

This is IBM’s LMiC library ported to Arduino. This has long time served as the reference implementation for Arduino but is not updated anymore.
My advice is to use the MCCI LoRaWAN LMIC library instead. It has improvements, support for more regions and is actively maintained (read its README.md first). It is mentioned further below.
LMIC-Arduino in some cases may still be a preferable option for memory constrainted 8-bit MCU’s like AVR ATmega328 and ATmega32u4 (used on e.g. Arduino Uno, Nano, Pro Mini etc.)

The LMIC-Arduino library name initially was Arduino-LMIC but was later renamed to LMIC-Arduino.
The official library name can be found in file library.properties. The name of the GitHub repository was not changed and is still called arduino-lmic.

Name: LMIC-Arduino
Version: 1.5.0+arduino-2
Frameworks: arduino
Platforms: atmelavr, atmelsam, espressif8266, intel_arc32, microchippic32, nordicnrf51, teensy, timsp430
Description: Arduino port of the LMIC (LoraWAN-in-C, formerly LoraMAC-in-C) framework provided by IBM.
URL: https://github.com/matthijskooijman/arduino-lmic
Type: Port
BaseType: LMIC
Parent Name: IBM LMiC
Parent URL: -
3 Likes
Names: libmDot, libxDot
Version: 3.1.0
Frameworks: mbed
Platforms: mDot and xDot
Description: Libraries for application development on Multitech Dot hardware
URLs: https://github.com/MultiTechSystems/libmDot-dev-mbed5
https://github.com/MultiTechSystems/libxDot-dev-mbed5
Type: -
BaseType: Proprietary (Closed source)
Parent Name: -
Parent URL: -
1 Like

This library at https://github.com/mcci-catena/arduino-lmic is now the reference implementation of LMiC.

The LMiC library at https://github.com/matthijskooijman/arduino-lmic hasn’t been updated for over a year and the last real code change is even older. In the mean time, Terry Moore from MCCI has been working on a fork of the IBM code and is making incredible progress at fixing many old issues and getting an official certification for the code.

Name: MCCI LoRaWAN LMIC library
Version: 3.0.99
Frameworks: arduino
Platforms: atmelavr, atmelsam, espressif32, espressif8266, intel_arc32, microchippic32, nordicnrf51, nordicnrf52, stm32, stm8, teensy, timsp430
Description: Arduino port of the LMIC (LoraWAN-MAC-in-C) framework provided by IBM.
URL: https://github.com/mcci-catena/arduino-lmic
Type: Port
BaseType: LMIC
ParentName: IBM LMIC framework
Parent URL: https://github.com/things-nyc/arduino-lmic
13 Likes

For the ESP-IDF framework (non-Arduino ESP32 framework):

Name: ttn-esp32
Version: 2.2.2
Frameworks: ESP-IDF
Platforms: espidf
Description: The Things Network device library for ESP-IDF (ESP32) supporting devices with Semtech SX127x chips
URL: https://github.com/manuelbl/ttn-esp32
Type: Port
BaseType: LMIC
Parent Name: MCCI LoRaWAN LMIC library
Parent URL: https://github.com/mcci-catena/arduino-lmic
3 Likes

Version 2.3.2 has been released. It adds support for CMake and PlatformIO, and it integrates the latest LMIC code by MCCI Catena (v2.3.2).

3 Likes

ESP32_LoRaWAN

This is a port of Semtech’s LoRaMac-node LoRaWAN library for the ESP32.
Author: Heltec Automation
This library can be used for Heltec ESP32 LoRa products only.

Name: ESP32_LoRaWAN
Version: 2.0
Frameworks: arduino
Platforms: espressif32
Description: LoRaWAN library for ESP32 + LoRa boards made by heltec
URL: https://github.com/HelTecAutomation/ESP32_LoRaWAN
Type: Port
BaseType: LoRaMac-node
Parent Name: LoRaMac-node
Parent URL: https://github.com/Lora-net/LoRaMac-node

:information_source: Partially propriatary. Some essential parts are obfuscated (compiled to assembly).

“An unique license relate to Chip ID is needed, you can check your license here: http://www.heltec.cn/search/”

lora_device_lib (ldl) is an experimental LoRaWAN implementation. It is not derived from any other libraries.

  • class A only
  • OTAA mode only
  • LoRa modulation only
  • supports ADR and network configurable parameters
  • supports multiple regions
  • supports SX1272 and SX1276 radios
  • has API documentation
  • has an Arduino wrapper for avr types

Generally speaking:

  • It has similar memory requirements to LMIC but fewer features
  • It has not been conformance tested
  • It is designed to be managed by the network rather than the application
  • It is unproven
Name lora_device_lib
Version 0.1.5
Frameworks none, arduino
Platforms atmelavr
Description An experimental LoRaWAN device implementation
Link https://github.com/cjhdev/lora_device_lib
Type New
BaseType lora_device_lib
ParentName -
ParentLink -
1 Like

Agreed, it’s definately the new LMiC reference.

1 Like

Maybe a stuped question, but how far are the two libraries LMIC-Arduino and MCCI LoRaWAN LMIC compatible with each other? In other words: What should I do to switch from the first to the second one?

To start, read the MCCI LoRaWAN LMIC library README.md. :wink:

In a nutshell:

  • You can use it as a drop in replacement, but
  • You will have to configure your region (default set to CFG_us915 instead of CFG_eu868).
    This is done in project_config/lmic_project_config.h (in library source), see README.md.
  • In addition more events have been added which should/can be handled.
  • This library uses a bit more memory than LMIC-Arduino, but in many cases that will only be relevant when using memory constrainted MCU’s like 8-bit AVR ATmega328 and ATmega32u4.
1 Like

I can’t wait. But… if both libraries are used are there no conflicts? Have I remove the old one?

Thanks and regards…

Of course you can only have one. They are by and large the same code, trying to use the same resources. It would probably not even be possible to build a project with both due to name conflicts alone.

Good question but I don’t have an answer at hand.
When using Arduino IDE the libraries may/will possibly conflict, but I have no experience with it in this case.
I am using PlatformIO where I can specify in the project configuration file which libraries (and which one of the LMIC libraries) I want to use. Even when both libraries are present this does not give any conflict (but that is probably due to the working of PlatformIO).

You may try to include arduino_lmic.h instead of lmic.h to use the MCCI LoRaWAN LMIC library.
That was specially added (but I’m not sure if that is sufficient to prevent a library conflict in the Arduino IDE).

It would be nice if you could test that and post your experiences here.

Both their official library names in library.properties and their source location URL’s are different.
But I expect that it will conflict because it is lmic.h that is included in the application and not the library name. But also see my remark above.

Basic MAC

From the creators of Basic Station that powers the TTIG gateway, Basic MAC is a portable implementation of the LoRa Alliance’s LoRaWAN specification in the C programming language. It is a fork of IBM’s LMiC library, and supports multiple regions, which are selectable at compile and/or run time. It can handle Class A, Class B, and Class C devices.

Documentation

The full documentation is available at https://doc.sm.tc/mac.

Name: Basic MAC
Version: 2.x
Frameworks: gcc-arm-embedded
Platforms: The reference hardware platform is the B-L072Z-LRWAN1 STM32 LoRa Discovery kit
Description: A portable implementation of LoRaWAN in the C programming language
URL: https://github.com/lorabasics/basicmac
Type: Port
BaseType: LMIC
Parent Name: IBM LMiC
Parent URL: -

And promising, @matthijskooijman might be picking up work for an Arduino port:

I’ve found @LacunaSpace willing to sponsor work on a BasicMac port for Arduino. I’ve got a basic version working somewhat […]

2 Likes

Now at version 0.2.1.

Changes since 0.1.5:

  • LoRaWAN 1.1 support*
  • Improved documentation (including a porting guide)
  • Deferred duty cycle feature for redundant unconfirmed data
  • Improved key handling (security module abstraction)
  • New MAC commands
    • DeviceTimeReq/Ans
    • ADRParamSetupReq/Ans

*328P Arduino wrapper limited to LoRaWAN 1.0 for simplicity.

Name lora_device_lib
Version 0.2.1
Frameworks none, arduino
Platforms any, atmelavr
Description An experimental LoRaWAN device implementation
Link https://github.com/cjhdev/lora_device_lib
Type New
BaseType lora_device_lib
ParentName -
ParentLink -
1 Like