LoRaWAN end device MAC layer for SX1272 and SX1276. Supports LoRaWAN-1.0 and LoRaWAN-1.1

Dependencies:   sx12xx_hal

Dependents:   LoRaWAN-SanJose_Bootcamp LoRaWAN-grove-cayenne LoRaWAN-classC-demo LoRaWAN-grove-cayenne ... more

radio chip selection

Radio chip driver is not included, because two options are available.
If you're using SX1272 or SX1276, then import sx127x driver into your program.
if you're using SX1261 or SX1262, then import sx126x driver into your program.
If you're using NAmote72 or Murata discovery, then you must import only sx127x driver.

application project requirements

This library requires mbed TLS to be enabled.
The file mbed_app.json must be present in the project using this library:

{
    "macros": [ "MBEDTLS_CMAC_C" ]
}

regional PHY selection

All end device configuration is done in Commissioning.h, define desired radio frequency band of operation in this header file.
Commissioning.h is located in the application using this library.

end device provisioning

End device is provisioned by editing Commissioning.h in the application which is using this library
To use LoRaWAN-1.0 OTA: make sure LORAWAN_ROOT_APPKEY is undefined.
To use LoRaWAN-1.1 OTA, define LORAWAN_ROOT_APPKEY.
To select OTA operation, define LORAWAN_JOIN_EUI, then LORAWAN_DEVICE_EUI must be defined, along with root key(s).
To select ABP operation, undefine LORAWAN_JOIN_EUI: then define session keys

LoRaWAN 1.0 nameLoRaWAN 1.1 nameComissioning.h defnedescription
OTADevEUIDevEUILORAWAN_DEVICE_EUIuniquely identifies end device
OTAAppEUIJoinEUILORAWAN_JOIN_EUI
OTAAppKeyNwkKeyLORAWAN_ROOT_NWKKEYroot key for network server
OTA(note 1)AppKeyLORAWAN_ROOT_APPKEYroot key for application server
ABPNwkSKey(note 3)LORAWAN_FNwkSIntKeynetwork session key
ABP(note 2)SNwkSIntKeyLORAWAN_SNwkSIntKeymac layer network integrity key
ABP(note 2)NwkSEncKeyLORAWAN_NwkSEncKeynetwork session encryption key
ABP(note 2)FNwkSIntKeyLORAWAN_FNwkSIntKeyforwarding network session integrity key
ABPAppSKeyAppSKeyLORAWAN_APPSKEYapplication session encryption key

(note 1): LoRaWAN-1.0 OTA uses a single root key for both network server and application server.

In LoRaWAN-1.0 OTA: the single root AppKey is used to generate NwkSkey and AppSKey.
(note 2): In LoRaWAN-1.0 (both OTA and ABP) SNwkSIntKey, NwkSEncKey. FNwkSIntKey are of same value and are collectively known as NwkSKey.
(note 3): LoRaWAN-1.0 uses single network session key, LoRaWAN-1.1 uses 3 network session keys. Both use a unique application session key.


In LoRaWAN-1.1 OTA: the root NwkKey is used to generate SNwkSIntKey, NwkSEncKey, FNwkSIntKey
In LoRaWAN-1.1 OTA: the root AppKey is used to generate AppSKey


in ABP mode, the DevAddr, and session keys are fixed (never change), and frame counters never reset to zero.
ABP operation has no concept of: root keys, or DevEUI or JoinEUI/AppEUI.
in OTA mode, the DevAddr and session keys are assigned at join procedure, and frame counters reset at join.

eeprom

This library includes eeprom driver to support non-volatile storage required by LoRaWAN specification.
Currently eeprom is implemented for STM32L1 family and STM32L0 family.
Writing of values are wear-leveled to increase endurance; each write operation circulates across several memory locations. A read operation returns the highest value found. This simple method is used for sequence numbers which only increase.

value nameused in
DevNonceOTAfor Join request (note 1)
RJcount1OTAfor ReJoin Type 1 request
FCntUpABPuplink frame counter
NFCntDownABPdownlink frame counter
AFCntDownABPdownlink frame counter

AFCntDown is only used in LoRaWAN-1.1 when application payload is present in downlink and FPort > 0.
NFCntDown is used in LoRaWAN-1.1 when FPort is zero in downlink or application payload not present.
NFCntDown is the only downlink frame counter used in LoRaWAN-1.0
(note 1) OTA DevNonce is random number in LoRaWAN-1.0, therefore not stored in eeprom. DevNonce in LoRaWAN-1.1 is forever increasing (non-volatile) number upon each join request,.
RJcount0 is only stored in RAM because the value resets upon new session from JoinAccept, therefore not stored in eeprom.
Frame counters in OTA mode reset upon new session in join request, therefore are stored in RAM instead of eeprom for OTA.

radio driver support

When SX127x driver is used, both SX1272 and SX1276 are supported without defining at compile time. The chip is detected at start-up.
Supported radio platforms:


Alternately, when SX126x driver is imported, the SX126xDVK1xAS board is used.

low-speed clock oscillator selection

LoRaWAN uses 32768Hz crystal to permit low-power operation.
However, some mbed targets might revert to low-speed internal oscillator, which is not accurate enough for LoRaWAN operation.
An oscillator check is performed at initialization; program will not start if internal oscillator is used.
To force LSE watch crystal, add to mbed_app.json

{
    "macros": [ "MBEDTLS_CMAC_C" ],
    "target_overrides": {
        "<your-target>": {
            "target.lse_available": true
        }
    }
}
Committer:
Wayne Roberts
Date:
Mon Aug 20 14:09:49 2018 -0700
Revision:
12:0f28f2e7c35e
Parent:
11:ce1317758488
add 8 hybrid channel sets for us915 band

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Wayne Roberts 11:ce1317758488 1 #include "lorawan_board.h"
Wayne Roberts 0:6b3ac9c5a042 2
Wayne Roberts 5:4e9d41359897 3
Wayne Roberts 0:6b3ac9c5a042 4 // Assumes 0 <= max <= RAND_MAX
Wayne Roberts 0:6b3ac9c5a042 5 // Returns in the closed interval [0, max]
Wayne Roberts 0:6b3ac9c5a042 6 long random_at_most(long max) {
Wayne Roberts 0:6b3ac9c5a042 7 unsigned long
Wayne Roberts 0:6b3ac9c5a042 8 // max <= RAND_MAX < ULONG_MAX, so this is okay.
Wayne Roberts 0:6b3ac9c5a042 9 num_bins = (unsigned long) max + 1,
Wayne Roberts 0:6b3ac9c5a042 10 num_rand = (unsigned long) RAND_MAX + 1,
Wayne Roberts 0:6b3ac9c5a042 11 bin_size = num_rand / num_bins,
Wayne Roberts 0:6b3ac9c5a042 12 defect = num_rand % num_bins;
Wayne Roberts 0:6b3ac9c5a042 13
Wayne Roberts 0:6b3ac9c5a042 14 long x;
Wayne Roberts 0:6b3ac9c5a042 15 do {
Wayne Roberts 0:6b3ac9c5a042 16 //x = random();
Wayne Roberts 0:6b3ac9c5a042 17 x = rand();
Wayne Roberts 0:6b3ac9c5a042 18 }
Wayne Roberts 0:6b3ac9c5a042 19 // This is carefully written not to overflow
Wayne Roberts 0:6b3ac9c5a042 20 while (num_rand - defect <= (unsigned long)x);
Wayne Roberts 0:6b3ac9c5a042 21
Wayne Roberts 0:6b3ac9c5a042 22 // Truncated division is intentional
Wayne Roberts 0:6b3ac9c5a042 23 return x/bin_size;
Wayne Roberts 0:6b3ac9c5a042 24 }
Wayne Roberts 0:6b3ac9c5a042 25
Wayne Roberts 0:6b3ac9c5a042 26 void memcpyr( uint8_t *dst, const uint8_t *src, uint16_t size )
Wayne Roberts 0:6b3ac9c5a042 27 {
Wayne Roberts 0:6b3ac9c5a042 28 dst = dst + ( size - 1 );
Wayne Roberts 0:6b3ac9c5a042 29 while( size-- )
Wayne Roberts 0:6b3ac9c5a042 30 {
Wayne Roberts 0:6b3ac9c5a042 31 *dst-- = *src++;
Wayne Roberts 0:6b3ac9c5a042 32 }
Wayne Roberts 0:6b3ac9c5a042 33 }
Wayne Roberts 0:6b3ac9c5a042 34
Wayne Roberts 0:6b3ac9c5a042 35 void
Wayne Roberts 5:4e9d41359897 36 #ifdef ENABLE_VT100
Wayne Roberts 0:6b3ac9c5a042 37 print_buf(const uint8_t* const buf, uint8_t len, const char* txt, uint8_t row)
Wayne Roberts 0:6b3ac9c5a042 38 {
Wayne Roberts 5:4e9d41359897 39 uint8_t i;
Wayne Roberts 5:4e9d41359897 40 vt.SetCursorPos(row, 1 );
Wayne Roberts 0:6b3ac9c5a042 41 vt.printf("%s: ", txt);
Wayne Roberts 0:6b3ac9c5a042 42 for (i = 0; i < len; i++)
Wayne Roberts 0:6b3ac9c5a042 43 vt.printf("%02x ", buf[i]);
Wayne Roberts 5:4e9d41359897 44 vt.printf("\e[K");
Wayne Roberts 0:6b3ac9c5a042 45 #else
Wayne Roberts 5:4e9d41359897 46 print_buf(const uint8_t* const buf, uint8_t len, const char* txt)
Wayne Roberts 5:4e9d41359897 47 {
Wayne Roberts 0:6b3ac9c5a042 48 uint8_t i;
Wayne Roberts 0:6b3ac9c5a042 49 pc.printf("%s: ", txt);
Wayne Roberts 0:6b3ac9c5a042 50 for (i = 0; i < len; i++)
Wayne Roberts 0:6b3ac9c5a042 51 pc.printf("%02x ", buf[i]);
Wayne Roberts 0:6b3ac9c5a042 52 pc.printf("\r\n");
Wayne Roberts 0:6b3ac9c5a042 53 #endif /* ENABLE_VT100 */
Wayne Roberts 0:6b3ac9c5a042 54 }
Wayne Roberts 0:6b3ac9c5a042 55
Wayne Roberts 0:6b3ac9c5a042 56 bool ValueInRange( int8_t value, int8_t min, int8_t max )
Wayne Roberts 0:6b3ac9c5a042 57 {
Wayne Roberts 0:6b3ac9c5a042 58 if( ( value >= min ) && ( value <= max ) )
Wayne Roberts 0:6b3ac9c5a042 59 {
Wayne Roberts 0:6b3ac9c5a042 60 return true;
Wayne Roberts 0:6b3ac9c5a042 61 }
Wayne Roberts 0:6b3ac9c5a042 62 return false;
Wayne Roberts 0:6b3ac9c5a042 63 }
Wayne Roberts 0:6b3ac9c5a042 64