Refactor frequency plans definition

TheThingsNetwork · Jan 31, 2023 · 212e8da · 212e8da
1 parent 286c44c
commit 212e8da
Show file tree

Hide file tree

Showing 77 changed files with 6,599 additions and 694 deletions.
diff --git a/README.md b/README.md
@@ -8,79 +8,134 @@ Frequency plans are defined for a band. Bands are specified by the LoRa Alliance
 
 ## File Format
 
-Frequency plan are defined in YAML files. Most settings in the frequency plan are optional. When not specifying optional settings, the band defaults are used.
+Frequency plan are defined in YAML files. Most settings in the frequency plan are optional. When not specifying optional settings, the band defaults are used. The definitions are split up into gateway and end-device plans:
 
+gateways:
 ```yml
-band-id: BAND_ID               # ID of the band (needs to match band-id in the index)
+band-id: BAND_ID                # ID of the band (needs to match band-id in the index)
 sub-bands:
-- min-frequency: 868000000     # Minimum frequency (Hz, inclusive)
-  max-frequency: 868600000     # Maximum frequency (Hz, inclusive)
-  duty-cycle: 0.01             # Duty cycle for this sub-band (optional; default: 1)
-  max-eirp: 16.15              # Maximum EIRP for this sub-band (optional; takes precedence over frequency plan's max-eirp)
-uplink-channels:               # List of uplink channels (zero indexed)
-- frequency: 868100000         # Frequency (Hz)
-  min-data-rate: 0             # Mininum data rate index
-  max-data-rate: 5             # Maximum data rate index
-  radio: 0                     # Radio index (see below)
-downlink-channels:             # List of downlink channels (zero indexed)
-- frequency: 868100000
-  min-data-rate: 0
-  max-data-rate: 5
+- min-frequency: 868000000      # Minimum frequency (Hz, inclusive)
+  max-frequency: 868600000      # Maximum frequency (Hz, inclusive)
+  duty-cycle: 0.01              # Duty cycle for this sub-band (optional; default: 1)
+  max-eirp: 16.15               # Maximum EIRP for this sub-band (optional; takes precedence over frequency plan's max-eirp)
+channels:                       # List of  channels (zero indexed)
+- uplink-frequency: 868100000   # Uplink frequency (Hz)
+  downlink-frequency: 868100000 # Downlink frequency (Hz) (optional)
+  min-data-rate: SF7BW125       # Minimum data rate
+  max-data-rate: SF11BW125      # Maximum data rate
+  radio: 0                      # Radio index (see below)
+lora-standard-channel:          # LoRa standard channel (optional)
+  frequency: 863000000
+  data-rate: SF7BW125
+  radio: 0
+fsk-channel:                    # FSK channel (optional)
+  frequency: 868800000
+  data-rate: SF7BW125
   radio: 0
-lora-standard-channel:         # LoRa standard channel (optional)
+time-off-air:                   # Time-off-air (optional)
+  fraction: 0.1                 # Minimum fraction of the emission time (optional)
+  duration: 1s                  # Minimum duration (optional)
+dwell-time:                     # Dwell time (optional)
+  uplinks: true                 # Enabled for uplink (optional)
+  downlinks: true               # Enabled for downlink (optional)
+  duration: 1s                  # Duration (optional)
+listen-before-talk:             # Listen-before-talk (optional)
+  rssi-offset: 0                # RSSI offset (dbm)
+  rssi-target: -80              # RSSI target (dbm)
+  scan-time: 128000             # Scan time (nanoseconds)
+radios:                         # Radio configuration (zero indexed, optional)
+- enable: true                  # Enable the radio
+  chip-type: SX1257             # Chip type
+  frequency: 867500000          # Frequency (Hz)
+  rssi-offset: -166             # RSSI offset (dbm)
+  tx:                           # Radio transmission configuration (optional)
+    min-frequency: 863000000    # Minimum frequency (Hz)
+    max-frequency: 867000000    # Maximum frequency (Hz)
+    notch-frequency: 129000     # Notch frequency 126000..250000 (Hz)
+clock-source: 0                 # Gateway clock source
+max-eirp: 29.15                 # Maximum EIRP (optional; used when sub-bands do not have max-eirp, takes precedence over band's default)
+```
+
+end-device:
+```yml
+band-id: BAND_ID                # ID of the band (needs to match band-id in the index)
+sub-bands:
+- min-frequency: 868000000      # Minimum frequency (Hz, inclusive)
+  max-frequency: 868600000      # Maximum frequency (Hz, inclusive)
+  duty-cycle: 0.01              # Duty cycle for this sub-band (optional; default: 1)
+  max-eirp: 16.15               # Maximum EIRP for this sub-band (optional; takes precedence over frequency plan's max-eirp)
+channels:                       # List of  channels (zero indexed)
+- uplink-frequency: 868100000   # Uplink frequency (Hz)
+  downlink-frequency: 868100000 # Downlink frequency (Hz)
+  min-data-rate: 0              # Minimum data rate index
+  max-data-rate: 5              # Maximum data rate index
+  default: false                # Channel is defined by RP
+lora-standard-channel:          # LoRa standard channel (optional)
   frequency: 863000000
   data-rate: 6
-  radio: 0
-fsk-channel:                   # FSK channel (optional)
+fsk-channel:                    # FSK channel (optional)
   frequency: 868800000
   data-rate: 7
-  radio: 0
-time-off-air:                  # Time-off-air (optional)
-  fraction: 0.1                # Minimum fraction of the emission time (optional)
-  duration: 1s                 # Minimum duration (optional)
-dwell-time:                    # Dwell time (optional)
-  uplinks: true                # Enabled for uplink (optional)
-  downlinks: true              # Enabled for downlink (optional)
-  duration: 1s                 # Duration (optional)
-listen-before-talk:            # Listen-before-talk (optional)
-  rssi-offset: 0               # RSSI offset (dbm)
-  rssi-target: -80             # RSSI target (dbm)
-  scan-time: 128000            # Scan time (nanoseconds)
-radios:                        # Radio configuration (zero indexed, optional)
-- enable: true                 # Enable the radio
-  chip-type: SX1257            # Chip type
-  frequency: 867500000         # Frequency (Hz)
-  rssi-offset: -166            # RSSI offset (dbm)
-  tx:                          # Radio transmission configuration (optional)
-    min-frequency: 863000000   # Minimum frequency (Hz)
-    max-frequency: 867000000   # Maximum frequency (Hz)
-    notch-frequency: 129000    # Notch frequency 126000..250000 (Hz)
-clock-source: 0                # Gateway clock source
-ping-slot:                     # Class B ping slot settings (optional)
+time-off-air:                   # Time-off-air (optional)
+  fraction: 0.1                 # Minimum fraction of the emission time (optional)
+  duration: 1s                  # Minimum duration (optional)
+dwell-time:                     # Dwell time (optional)
+  uplinks: true                 # Enabled for uplink (optional)
+  downlinks: true               # Enabled for downlink (optional)
+  duration: 1s                  # Duration (optional)
+listen-before-talk:             # Listen-before-talk (optional)
+  rssi-offset: 0                # RSSI offset (dbm)
+  rssi-target: -80              # RSSI target (dbm)
+  scan-time: 128000             # Scan time (nanoseconds)
+ping-slot:                      # Class B ping slot settings (optional)
   frequency: 869525000
   min-data-rate: 0
   max-data-rate: 5
-  radio: 0
-ping-slot-default-data-rate: 3 # Default data rate index of class B ping slot (optional)
-rx2-channel:                   # Rx2 channel (optional)
+ping-slot-default-data-rate: 3  # Default data rate index of class B ping slot (optional)
+rx2-channel:                    # Rx2 channel (optional)
   frequency: 869525000
   min-data-rate: 0
   max-data-rate: 5
-  radio: 0
-rx2-default-data-rate: 0       # Default data rate index of Rx2 (optional)
-max-eirp: 29.15                # Maximum EIRP (optional; used when sub-bands do not have max-eirp, takes precedence over band's default)
+rx2-default-data-rate: 0        # Default data rate index of Rx2 (optional)
+max-eirp: 29.15                 # Maximum EIRP (optional; used when sub-bands do not have max-eirp, takes precedence over band's default)
 ```
 
-An index of frequency plans is in `frequency-plans.yml`:
+An index of frequency plans is in `frequency-plans.yml`. This can take two forms depending on if it is a root frequency plan definition, or if it is a plan definition that modifies an existing plan.
 
+Base plan definition
+```yml
+end-device-descriptions:
+  - id: EU_863_870           # ID of the frequency plan
+    band-id: EU_863_870      # ID of the LoRaWAN band (needs to match band-id in the definition)
+    name: Region 863-870 MHz # Name of the frequency plan, ending with frequency ranges
+    description: Default frequency plan for Europe # Description of the frequency plan
+    base-frequency: 868      # Base frequency in MHz for hardware support (433, 470, 868, 915 or 2450)
+    country-codes: []        # List of 2-digit ISO country codes for countries where this plan can be used
+    file: EU_863_870.yml     # Filename of the plan residing in the `end-device` folder
+    endorsed: true
+
+gateway-descriptions:
+  - id: EU_863_870           # ID of the frequency plan
+    band-id: EU_863_870      # ID of the LoRaWAN band (needs to match band-id in the definition)
+    name: Region 863-870 MHz # Name of the frequency plan, ending with frequency ranges
+    description: Default frequency plan for Europe # Description of the frequency plan
+    base-frequency: 868      # Base frequency in MHz for hardware support (433, 470, 868, 915 or 2450)
+    country-codes: []        # List of 2-digit ISO country codes for countries where this plan can be used
+    file: EU_863_870.yml     # Filename of the plan residing in the `gateway` folder
+    endorsed: true
+```
+
+Inherited definition
 ```yml
 - id: EU_863_870_TTN       # ID of the frequency plan
   band-id: EU_863_870      # ID of the LoRaWAN band (needs to match band-id in the definition)
   base-id: EU_863_870      # ID that this frequency plan extends (refers to id of another frequency plan)
   name: Region 863-870 MHz # Name of the frequency plan, ending with frequency ranges
-  base-frequency: 868      # Base frequency in MHz for hardware support (433, 470, 868 or 915)
+  description: Default frequency plan for Europe # Description of the frequency plan
+  base-frequency: 868      # Base frequency in MHz for hardware support (433, 470, 868, 915 or 2450)
   country-codes: []        # List of 2-digit ISO country codes for countries where this plan can be used
-  file: EU_863_870.yml     # File of the frqeuency plan definition
+  modifiers: []            # Filename of the modifier residing in the respective `end-device/modifiers` or `gateway/modifiers` folder.
+  endorsed: true
 ```
 
 > Country codes are taken from the [LoRaWAN Regional Parameters 1.0.1 Specification](https://lora-alliance.org/sites/default/files/2020-06/rp_2-1.0.1.pdf)
@@ -91,6 +146,19 @@ Thank you for your interest in building this thing together with us. We're reall
 
 The Things Stack uses the `github.com/TheThingsNetwork/lorawan-frequency-plans` as default source for fetching frequency plans. Therefore, contributing to this open source repository makes frequency plans automatically available to Stack deployments with default settings. You can contribute by submitting pull requests. Are you new to GitHub? That's great! [Read here about pull requests](https://help.github.com/articles/about-pull-requests/). Please also use the editor settings as defined in `.editorconfig`.
 
+There are json schemas available for all configuration files. These define files structure and make it easier to fill them in. To enable them in `VSCode` add the following to your `settings.json` file. 
+```json
+{
+  "yaml.schemas": {
+    "schema.json": "frequency-plans.yml",
+    "end-device/schema.json": "end-device/*.yml",
+    "end-device/modifiers/schema.json": "end-device/modifiers/*.yml",
+    "gateway/schema.json": "gateway/*.yml",
+    "gateway/modifiers/schema.json": "gateway/modifiers/*.yml"
+  }
+}
+```
+
 ### Local Regulations
 
 When submitting a new frequency plan or making changes to an existing frequency plan, please make sure that the band is allowed to be used in the concerning region and that settings respect regional regulations. When submitting a pull request for a new region, please upload or link to a document that describes the local regulations.

diff --git a/disable_dwell_time.yml b/disable_dwell_time.yml
diff --git a/docs/frequency-plans.md b/docs/frequency-plans.md
@@ -0,0 +1,26 @@
+# LoRaWAN Frequency Plans for The Things Stack
+
+# End device frequency plans
+
+## [`EU_863_870`](../end-device/EU_863_870.yml): Europe 863-870 MHz 
+
+>> Default frequency plan for Europe
+
+![EU_863_870](images/end-device/EU_863_870.svg)
+
+## `EU_863_870_TTN`: Europe 863-870 MHz
+Based on [EU_863_870](##EU_863_870) and modified by [rx2_default_data_rata_3.yml](../end-device/modifiers/rx2_default_data_rata_3.yml)
+
+
+>> TTN Community Network frequency plan for Europe, using SF9 for RX2
+
+![EU_863_870_TTN](images/end-device/EU_863_870_TTN.svg)
+
+# Gateway frequency plans
+
+
+## [`EU_863_870`](../gateway/EU_863_870.yml): Europe 863-870 MHz 
+
+>> Default frequency plan for Europe
+
+![EU_863_870](images/gateway/EU_863_870.svg)