ESP32-PaxCounter/lib/arduino-lmic-mcci-v2.2.2/HOWTO-ADD-REGION.md

Adding a new region to Arduino LMIC

This variant of the Arduino LMIC code supports adding additional regions beyond the eu868 and us915 bands supoprted by the original IBM LMIC 1.6 code.

This document sketches how to add a new region.

Planning

Determine the region/region category

Compare the target region (in the LoRaWAN regional specification) to the EU868 and US915 regions. There are three possibilities.

1. the region is like the EU region. There are a limited number of channels (up to 8), and only a small number of channels are used for OTAA join operations. The response masks refer to individual channels, and the JOIN-response can send frequencies of specific channels to be added.

2. The region is like the US region. There are many channels (the US has 64) with fixed frequences, and the channel masks refer to subsets of the fixed channels.

3. The region is not really like either the EU or US. At the moment, it seems that CN470-510MHz (section 2.6 of LoRaWAN Regional Parameters spec V1.0.2rB) falls into this category.

Bandplans in categories (1) and (2) are easily supported. Bandplans in category (3) are not supoprted by the current code.

Check whether the region is already listed in lmic_config_preconditions.h

Check src/lmic/lmic_config_preconditions.h and scan the LMIC_REGION_... definitions. The numeric values are assigned based on the subchapter in section 2 of the LoRaWAN 1.0.2 Regional Parmaters document. If your symbol is already there, then the first part of adaptation has already been done. There will already be a corresponding CFG_... symbol. But if your region isn't supported, you'll need to add it here.

• LMIC_REGION_myregion must be a distinct integer, and must be less than 32 (so as to fit into a bitmask)

Make the appropriate changes in lmic_config_preconditions.h

• LMIC_REGION_SUPPORTED is a bit mask of all regions supported by the code. Your new region must appear in this list.
• CFG_LMIC_REGION_MASK is a bit mask that, when expanded, returns a bitmask for each defined CFG_... variable. You must add your CFG_myregion symbol to this list.
• CFG_region evaluates to the LMIC_REGION_... value for the selected region (as long as only one region is selected). The header files check for this, so you don't have to.
• CFG_LMIC_EU_like_MASK is a bitmask of regions that are EU-like, and CFG_LMIC_US_like_MASK is a bitmask of regions that are US-like. Add your region to the appropriate one of these two variables.

Document your region in config.h

You'll see where the regions are listed. Add yours.

Document your region in README.md

You'll see where the regions are listed. Add yours.

Add the definitions for your region in lorabase.h

• If your region is EU like, copy the EU block. Document any duty-cycle limitations.
• if your region is US like, copy the US block.
• As appropriate, copy lorabase_eu868.h or lorabase_us915.h to make your own lorabase_myregion.h. Fill in the symbols.

At time of writing, you need to duplicate some code to copy some settings from ..._CONFIG_SYMBOL to the corresponding CONFIG_SYMBOL; and you need to put some region-specific knowledge into the lorabase.h header file. The long-term direction is to put all the regional knowledge into the region-specific header, and then the central code will just copy. The architectural impulse is that we'll want to be able to reuse the regional header files in other contexts. On the other hand, because it's error prone, we don't want to #include files that aren't being used; otherwise you could accidentally use EU parameters in US code, etc.

• Now's a good time to test-compile and clean out errors introduced. You'll still have problems compiling, but they should look like this:

  lmic.c:29: In file included from
  
  lmic_bandplan.h: 52:3: error: #error "maxFrameLen() not defined by bandplan"
     # error "maxFrameLen() not defined by bandplan"
  
  lmic_bandplan.h: 56:3: error: #error "pow2dBm() not defined by bandplan"
     # error "pow2dBm() not defined by bandplan"
  

Edit lmic_bandplan.h

The next step is to add the region-specific interfaces for your region.

Do this by editing lmic_bandplan.h and adding the appropriate call to a (new) region-specific file lmic_bandplan_myregion.h, where "myregion" is the abbreviation for your region.

Then, if your region is eu868-like, copy lmic_bandplan_eu868.h to create your new region-specific header file; otherwise copy lmic_bandplan_us915.h.

Create lmic_myregion.c

Once again, you will start by copying either lmic_eu868.c or lmic_us915.c to create your new file. Then touch it up as necessary.

General Discussion

• You'll find it easier to do the test compiles using the example scripts in this directory, rather than trying to get all the Catena framework going too. On the other hand, working with the Catena framework will expose more problems.

Addding the region to the Arduino_LoRaWAN library

In Arduino_LoRaWAN_ttn.h:

• Add a new class with name Arduino_LoRaWAN_ttn_myregion, copied either from the Arduino_LoRaWAN_ttn_eu868 class or the Arduino_LoRaWAN_ttn_us915 class.
• Extend the list of #if defined(CFG_eu868) etc to define Arduino_LoRaWAN_REGION_TAG to the suffix of your new class if CFG_myregion is defined.

Then copy either ttn_eu868_netbegin.cpp/ttn_eu868_netjoin.cpp or ttn_us915_netbegin.cpp/ttn_us915_netjoin.cpp to make your own file(s) for the key functions.