:warning: This library is deprecated, see the README for alternatives.
:warning: This library is deprecated, see the README for alternatives.
:warning: This repository is no longer maintained. The recommended alternative is the MCCI version of LMIC, which is based on this one, but has seen much improvements over the years, has much better documentation and is mostly a drop-in replacement. If you need support for the SX126x, you can consider Lacuna's port of BasicMAC, which is based on a parallel development based on the original LMIC. Only when you have very tight constraints on RAM or flash should this version still be considered.
See this post for more details and background.
This repository contains the IBM LMIC (LoraMAC-in-C) library, slightly modified to run in the Arduino environment, allowing using the SX1272, SX1276 tranceivers and compatible modules (such as some HopeRF RFM9x modules).
This 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.
This library requires Arduino IDE version 1.6.6 or above, since it requires C99 mode to be enabled by default.
To install this library:
For more info, see https://www.arduino.cc/en/Guide/Libraries
The LMIC library provides a fairly complete LoRaWAN Class A and Class B implementation, supporting the EU-868 and US-915 bands. Only a limited number of features was tested using this port on Arduino hardware, so be careful when using any of the untested features.
What certainly works:
What has not been tested:
If you try one of these untested features and it works, be sure to let us know (creating a github issue is probably the best way for that).
A number of features can be configured or disabled by editing the
config.h file in the library folder. Unfortunately the Arduino
environment does not offer any way to do this (compile-time)
configuration from the sketch, so be careful to recheck your
configuration when you switch between sketches or update the library.
At the very least, you should set the right type of transceiver (SX1272 vs SX1276) in config.h, most other values should be fine at their defaults.
This library is intended to be used with plain LoRa transceivers, connecting to them using SPI. In particular, the SX1272 and SX1276 families are supported (which should include SX1273, SX1277, SX1278 and SX1279 which only differ in the available frequencies, bandwidths and spreading factors). It has been tested with both SX1272 and SX1276 chips, using the Semtech SX1272 evaluation board and the HopeRF RFM92 and RFM95 boards (which supposedly contain an SX1272 and SX1276 chip respectively).
This library contains a full LoRaWAN stack and is intended to drive these Transceivers directly. It is not intended to be used with full-stack devices like the Microchip RN2483 and the Embit LR1272E. These contain a transceiver and microcontroller that implements the LoRaWAN stack and exposes a high-level serial interface instead of the low-level SPI transceiver interface.
This library is intended to be used inside the Arduino environment. It should be architecture-independent, so it should run on "normal" AVR arduinos, but also on the ARM-based ones, and some success has been seen running on the ESP8266 board as well. It was tested on the Arduino Uno, Pinoccio Scout, Teensy LC and 3.x, ESP8266, Arduino 101.
This library an be quite heavy, especially if the fairly small ATmega
328p (such as in the Arduino Uno) is used. In the default configuration,
the available 32K flash space is nearly filled up (this includes some
debug output overhead, though). By disabling some features in config.h
(like beacon tracking and ping slots, which are not typically needed),
some space can be freed up. Some work is underway to replace the AES
encryption implementation, which should free up another 8K or so of
flash in the future, making this library feasible to run on a 328p
microcontroller.
To make this library work, your Arduino (or whatever Arduino-compatible board you are using) should be connected to the transceiver. The exact connections are a bit dependent on the transceiver board and Arduino used, so this section tries to explain what each connection is for and in what cases it is (not) required.
Note that the SX1272 module runs at 3.3V and likely does not like 5V on its pins (though the datasheet is not say anything about this, and my transceiver did not obviously break after accidentally using 5V I/O for a few hours). To be safe, make sure to use a level shifter, or an Arduino running at 3.3V. The Semtech evaluation board has 100 ohm resistors in series with all data lines that might prevent damage, but I would not count on that.
The SX127x transceivers need a supply voltage between 1.8V and 3.9V.
Using a 3.3V supply is typical. Some modules have a single power pin
(like the HopeRF modules, labeled 3.3V) but others expose multiple power
pins for different parts (like the Semtech evaluation board that has
VDD_RF, VDD_ANA and VDD_FEM), which can all be connected together.
Any GND pins need to be connected to the Arduino GND pin(s).
The primary way of communicating with the transceiver is through SPI (Serial Peripheral Interface). This uses four pins: MOSI, MISO, SCK and SS. The former three need to be directly connected: so MOSI to MOSI, MISO to MISO, SCK to SCK. Where these pins are located on your Arduino varies, see for example the "Connections" section of the Arduino SPI documentation.
The SS (slave select) connection is a bit more flexible. On the SPI slave side (the transceiver), this must be connect to the pin (typically) labeled NSS. On the SPI master (Arduino) side, this pin can connect to any I/O pin. Most Arduinos also have a pin labeled "SS", but this is only relevant when the Arduino works as an SPI slave, which is not the case here. Whatever pin you pick, you need to tell the library what pin you used through the pin mapping (see below).
The DIO (digitial I/O) pins on the transceiver board can be configured for various functions. The LMIC library uses them to get instant status information from the transceiver. For example, when a LoRa transmission starts, the DIO0 pin is configured as a TxDone output. When the transmission is complete, the DIO0 pin is made high by the transceiver, which can be detected by the LMIC library.
The LMIC library needs only access to DIO0, DIO1 and DIO2, the other DIOx pins can be left disconnected. On the Arduino side, they can connect to any I/O pin, since the current implementation does not use interrupts or other special hardware features (though this might be added in the feature, see also the "Timing" section).
In LoRa mode the DIO pins are used as follows:
In FSK mode they are used as follows::
Both modes need only 2 pins, but the tranceiver does not allow mapping them in such a way that all needed interrupts map to the same 2 pins. So, if both LoRa and FSK modes are used, all three pins must be connected.
The pins used on the Arduino side should be configured in the pin mapping in your sketch (see below).
The transceiver has a reset pin that can be used to explicitely reset it. The LMIC library uses this to ensure the chip is in a consistent state at startup. In practice, this pin can be left disconnected, since the transceiver will already be in a sane state on power-on, but connecting it might prevent problems in some cases.
On the Arduino side, any I/O pin can be used. The pin number used must be configured in the pin mapping (see below).
The transceiver contains two separate antenna connections: One for RX and one for TX. A typical transceiver board contains an antenna switch chip, that allows switching a single antenna between these RX and TX connections. Such a antenna switcher can typically be told what position it should be through an input pin, often labeled RXTX.
The easiest way to control the antenna switch is to use the RXTX pin on the SX127x transceiver. This pin is automatically set high during TX and low during RX. For example, the HopeRF boards seem to have this connection in place, so they do not expose any RXTX pins and the pin can be marked as unused in the pin mapping.
Some boards do expose the antenna switcher pin, and sometimes also the SX127x RXTX pin. For example, the SX1272 evaluation board calls the former FEM_CTX and the latter RXTX. Again, simply connecting these together with a jumper wire is the easiest solution.
Alternatively, or if the SX127x RXTX pin is not available, LMIC can be configured to control the antenna switch. Connect the antenna switch control pin (e.g. FEM_CTX on the Semtech evaluation board) to any I/O pin on the Arduino side, and configure the pin used in the pin map (see below). It is not entirely clear why would not want the transceiver to control the antenna directly, though.
As described above, most connections can use arbitrary I/O pins on the Arduino side. To tell the LMIC library about these, a pin mapping struct is used in the sketch file.
For example, this could look like this:
lmic_pinmap lmic_pins = {
.nss = 6,
.rxtx = LMIC_UNUSED_PIN,
.rst = 5,
.dio = {2, 3, 4},
};The names refer to the pins on the transceiver side, the numbers refer
to the Arduino pin numbers (to use the analog pins, use constants like
A0). For the DIO pins, the three numbers refer to DIO0, DIO1 and DIO2
respectively. Any pins that are not needed should be specified as
LMIC_UNUSED_PIN. The nss and dio0 pin is required, the others can
potentially left out (depending on the environments and requirements,
see the notes above for when a pin can or cannot be left out).
The name of this struct must always be lmic_pins, which is a special name
recognized by the library.
This board uses the following pin mapping:
const lmic_pinmap lmic_pins = {
.nss = 10,
.rxtx = LMIC_UNUSED_PIN,
.rst = LMIC_UNUSED_PIN, // hardwired to AtMega RESET
.dio = {4, 5, 7},
};This library currently provides three examples:
ttn-abp.ino shows a basic transmission of a "Hello, world!" message
using the LoRaWAN protocol. It contains some frequency settings and
encryption keys intended for use with The Things Network, but these
also correspond to the default settings of most gateways, so it
should work with other networks and gateways as well. This example
uses activation-by-personalization (ABP, preconfiguring a device
address and encryption keys), and does not employ over-the-air
activation.
Reception of packets (in response to transmi
No open issues yet, or sync has not completed.