SlimLoRa - Probably the easiest and smallest footprint LoRaWAN library for Arduino library and EU868.
This library is probably the most easy to use LoRaWAN library. The target is LoRaWAN-1.0.3 specification. It supports OTAA / Join, most important MAC commands - like DR, power, NBtrans, downlinks for user application and session is stored to EEPROM. Applications downlinks are static selectable via #define in SlimLoRa.h. Default is 11 bytes. If you want a complete LoRaWAN library try Radiolib (needs around 52kBytes of program flash), or LMIC (around 36kBytes of program flash).
SlimLoRa needs around 12558 Bytes* (13kBytes). SlimLoRa gives LoRaWAN life to old μCU's like ATmega 328 with 32kBytes of flash.
* in fact, I think the overhead is around 9kBytes.
SlimLoRa MAC response in MAC command via Helium original console.
The majority of the work was done by Hendrik Hagendorn and Ideetron B.V. Thanks to both of them. I ported the library to Arduino, I expanded the most important MAC commands, enabled application downlinks, ACK for confirmed downlinks and corrected the channel for SF7BW250.
- OTAA join with Feather 32u4 EU868 region. Europe only.
- TTN joins - Feather32u4
- Join SF9 on TTN and power 0dBm in different room. Success on 1st window.
- Join SF8 on TTN and power 0dBm in same room. Success on 1st window.
- Join SF7 on TTN and power 0dBm in different room. Success on 1st window.
- Megabrick joins
- FAIL with SF7 and power 13dBm in different room and an antenna.
- Join with SF9 and power 13dBm in different room and an antenna.
- Megabrick joins
- Heliun Joins - Feather32u4
- old console
- Join SF10 with Helium. Success everytime on 1st window but not in first attempt.
- chirpstack Console
- Join SF9 on Helium chripstack outdors. Success on 1st window.
- Join SF8 on Helium chripstack outdors. Success on 1st window in second or third attempt.
- Join SF7 on Helium and power 0dBm in different room. Success on 1st window.
- Megabrick joins
- Join with SF7 and GW power 16dBm in different room and an antenna.
- Join with SF8 and GW power 16dBm in different room and an antenna.
- Megabrick joins
- old console
- TTN joins - Feather32u4
- Downlinks
- Helium on 2nd window (SF12) always works on Chirpstack.
- SetPower
- Deep Sleep
- Restore session from EEPROM (arduino style)
- Downlink for application.
- ACK to confirmed Downlink.
- NbTrans - edit SlimLoRa.h to config.
- Most important MAC commands - more to follow
- Session saved to EEPROM. You only need to join once on the lifetime of the device.
- ADR for Data Rate and TxPower. After join with SF9 in different room from gateway (RSSI -85), TTN sends SF7 (or SF8) ADR command and SlimLoRa conforms.
- NbTrans
- Channel Mask
- RxTimingSetup
- DevStatusAns. Battery status is working, I think margin is fine.
- LinkCheckReq. (Margin and Gateways count).
- DeviceTimeReq. Fractional second on purpose is truncated to cs (centiseconds). 1 = 10ms. I can't undestand how much precise is the timing from LNS. Have to verify with GPS. TTN RX window is 5secs and Helium 1s. So epoch is off by 5 and 1 seconds. If you want to correct epoch, uncomment both
#define SLIM_DEBUG_VARSand#define EPOCH_RX2_WINDOW_OFFSETwith the price of 1768 program flash and 64 less bytes of RAM.
- SF7BW250 is working with TTN but SlimLoRa does not receives the downlink. This DR6 is currently not supported by Helium packet brocker.
- ABP
- AVR style EERPOM
I recommend ARDUINO_EEPROM == 1 in SlimLoRa.h otherwise when you use avr/eeprom.h style and you compile with different options, or if you change part of your sketch relative to EEPROM (EEMEM) the address of the data are changing places! This is a "bug" on avr/eeprom.h. With avr style if you change your sketch, maybe you need to re-join. With arduino eeprom style you don't need to re-join.
Solutions with avr style.
- Solution #1: Erase ALL the EEPROM after uploading the new firmware.
- Solution #2: Hint: You can track the EEPROM addresses with:
avr-objdump -Don .eemem section. - Solution #3: Don't enable keep session.
- Solution #4: use arduino style eeprom in
SlimLoRa.h
-
ADR_ACK_LIMIT, must follow directive on p. 17 based onADR_ACK_DELAY - Duty Cycle. Added GetTXms function to return the TOTAL duration of ALL transmissions. At SF7 1byte reports 45-48ms vs 46ms theoretical at SF8 reports 84ms vs 82ms (theoretical). SF7 5 bytes reports 52ms vs 51.5ms (theoretical). Application HAVE to read the value of GetTXms() after every transmission to check if the the Duty Cycle is respected. I decided to not respect Duty Cycle on SlimLoRa, since if the device is going to Deep Sleep and wakes up via a accelerometer on AVR MCU's freezes the timer0. I think the solution is the RTC or to read a time from GPS.
- Power to the people. Several values made public. Take care to not write them or you may loose access to the network. Instead of using getters I selected to make public some variables.
- MAC Commands.
- Join back-off
- Extern variable for Duty Cycle if the application can provide time.
- Confirmed Uplink
- Make DevNonce random.
- More regions. Currently only EU868 is working.
- Add pin mappings infrastucture for other boards.
- Add compile options for battery status (unable to measure, connected to external power)
- Random delay for TX.
- Duty Cycle per channel.
- Respect Dwell MAC command (only for US902?)
- CFlist only for US and AS?
If you downclock your AVR MCU with clock_prescale_set(clock_div_4) SlimLoRa can adapt the RX timing window to receive the downlinks. Even with clock_prescale_set(clock_div_32) at 500Khz a MegaBrick joins at SF7. Uncomment the #define CATCH_DIVIDER to enable this function.
- Respect Duty Cycle Since AVR on Deep Sleep freezes the timer0. SlimLoRa is unable to know about time.
- Respect Join Back-off (not faster than 36 seconds). Must handle by application. In case of Deep Sleep SlimLoRa can't keep track the time.
- 32-bit Frame Counter.
Download the library and extract to Arduino/libraries folder or install via the library manager of Arduino IDE. For manual install: Rename SlimLoRa-master or SlimLoRa-VERSION to SlimLoRa. Read the details on examples. If something goes bad erase ALL the EEPROM and re-try join.
SlimLoRa changes the data of payload. Don't use payload data for program logic.
You can monitor the duty cycle with the function GetTXms() after every transmission. SlimLoRa will return the duration in ms of the LAST transmission. You have to add this to a variable to your program to keep track the Duty Cycle every day. If you access SlimLoRa via lora object example SlimLoRa lora = SlimLoRa(8); you can also read (don't write) the values lora.slimTotalTXms and lora.slimLastTXms. After one day you have to zero the lora.slimTotalTXms with function lora.ZeroTXms() or lora.slimTotalTXms = 0;. I think I will remove the functions. They need 12 more program flash bytes if used.
If you send MAC request for Time or CheckLink you can read the variables from lora.epoch lora.fracSecond and lora.margin, lora.GwCnt. lora.epoch is greater than 0 if Time from LNS is received. Also lora.GwCnt is greater than 0 if LinkCheck is received.
I have also made some values public like frame counter. Now the application can do something cool stuff like: every X frame counter you can transmit verbose data. So every 20 - 30 uplinks you can send more data. Yes, this can be done on app logic, but one less variable is used like that.
If your project relies on small battery, try to lower SLIMLORA_DRIFT from 2 to 1 or even to 0. There is a danger to not receive downlinks. Verify the behaviour with cold and heat. Make sure your device / network can handle that. With MegaBrick and SLIMLORA_DRIFT 1 I managed to join at with SF7 and receive downlinks in room temperature. Your device / network maybe is not capable of that. 3 and 2 seems to be ok with feather-32u4 for RX2 SF12 at 2s. Join is fine with 2, 3, 4. With drift 1 join fails with feather-32u4, so the best for feather-32u4 is 2 or 3. MegaBrick joins with 1 but fails with 0. So best for MebaBrick is 1 or 2.
| Drift | SF7 | SF12 |
|---|---|---|
| 5 | 100ms | 1100ms |
| 4 | 87ms | 918ms |
| 3 | 66ms | 756ms |
| 2 | 47ms | 558ms |
| 1 | 27ms | 362ms |
If you need to handle array data with EEPROM some helper function getArrayEEPROM, setArrayEEPROM and printHex are public to use them in your program.
#define MAC_REQUESTS enables MAC requests for DeviceTime and LinkCheck. Comment to gain 397 program Flash and 9 bytes of RAM.
#define SLIM_DEBUG_VARS enables a lora.LoRaWANreceived variable to check if you received a MAC command, a downlink, in Join 1st or 2nd windows, or downlink or 1st or 2nd window.
Note:
This library evolved from a fun project LoRa-ATtiny-Node. It was never meant to run on more powerful UCs than an ATtiny85. This fork of the original library tries to support the Arduino ecosystem.
SlimLoRa originated from a code base by Ideentron B.V.. Therefore its structure is similar to the TinyLoRa library. SlimLoRa is very different from LMIC. This does not mean it's better, it's different. E.g. SlimLoRa has no eventing system.
This repository contains the SlimLoRa LoRaWAN library. It uses AES encryption routines originally written by Ideentron B.V.. SlimLoRa is compatible with all radio chips based on the Semtech SX1276 (e.g. HopeRF RFM95).
SlimLoRa implements the ABP and OTAA activation schemes. It has support for downlink messages and the Adaptive Data Rate (ADR) mechanism.
Although the basic things of the LoRaWAN 1.0.3 Class A specification are implemented, this library does not cover the entire specification and thus is not fully LoRaWAN 1.0 compliant. Please verify its behavior before using it on public networks.
It also does not enforce a duty cycle. This must be ensured by the user.
Contents:
- Features
- Requirements and Limitations
- Configuration
- Supported hardware
- Release History
- Contributions
- Trademark Acknowledgements
- License
This library provides a LoRaWAN 1.0 Class A implementation for the EU-868 band.
The library has some support for LoRaWAN 1.1 which is not usable yet.
- Sending uplink packets, not taking into account duty cycles.
- Message encryption and message integrity checking.
- Over-the-Air Activation (OTAA).
- Activation by Personalization (ABP).
- Adaptive Data Rate (ADR).
- Receiving downlink packets in the RX1 and RX2 windows.
- MAC command processing for LinkAdr, RxParamSetup, DevStatus and RxTimingSetup requests.
This library does not implement any kind of event handling. A call to the Join and SendData methods will block for several seconds until the end of the second receive window.
Be sure to put connected sensors into sleep mode before sending data to save energy!
This library started from parts written by Ideetron B.V.. Thanks to Ideetron B.V.!
-
novag (LoRa-ATtiny-Node)
-
Ideentron B.V. - RFM95W_Nexus
LoRa is a registered trademark of Semtech Corporation. LoRaWAN is a registered trademark of the LoRa Alliance.
All other trademarks are the properties of their respective owners.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.