Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Refactor #62

Draft
wants to merge 3 commits into
base: v2
Choose a base branch
from
Draft

Refactor #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
212e8da
Refactor frequency plans definition
htdvisser Jul 28, 2022
152782b
Add validation for modifiers
Feb 2, 2023
5450c88
Convert existing plans to new structure
Feb 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
170 changes: 120 additions & 50 deletions README.md
View file
Open in desktop
Expand Up @@ -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)
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)
Expand All @@ -91,6 +146,21 @@ 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"
}
}
```

Make sure to run `go run . -schema -docs` after changes or additions to the frequency plans. This ensures that the schemas and documentation stay up to date.

### 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.
Expand Down
75 changes: 75 additions & 0 deletions docs/frequency-plans.md
View file
Open in desktop
@@ -0,0 +1,75 @@
# 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)

## [`EU_863_870_ROAMING_DRAFT`](../end-device/EU_863_870_ROAMING_DRAFT.yml): Europe 863-870 MHz, 6 channels for roaming (Draft)

>> European 6 channel plan used by major operators to support LoRaWAN Passive Roaming

![EU_863_870_ROAMING_DRAFT](images/end-device/EU_863_870_ROAMING_DRAFT.svg)

## [`EU_433`](../end-device/EU_433.yml): Europe 433 MHz (ITU region 1)

>> Default frequency plan for worldwide 433MHz

![EU_433](images/end-device/EU_433.svg)

## [`US_902_928_FSB_1`](../end-device/US_902_928_FSB_1.yml): United States 902-928 MHz, FSB 1

>> Default frequency plan for the United States and Canada, using sub-band 1

![US_902_928_FSB_1](images/end-device/US_902_928_FSB_1.svg)

## [`AS_920_923`](../end-device/AS_920_923.yml): Asia 920-923 MHz

>> TTN Community Network frequency plan for Asian countries, using frequencies ≤ 923 MHz

![AS_920_923](images/end-device/AS_920_923.svg)

## `AS_920_923_LBT`: Asia 920-923 MHz with LBT
Based on [AS_920_923](##AS_920_923) and modified by [lbt_80_over_128.yml](../end-device/modifiers/lbt_80_over_128.yml)

>> TTN Community Network frequency plan for Asian countries, using frequencies ≤ 923 MHz with listen-before-talk

![AS_920_923_LBT](images/end-device/AS_920_923_LBT.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)

## [`EU_433`](../gateway/EU_433.yml): Europe 433 MHz (ITU region 1)

>> Default frequency plan for worldwide 433MHz

![EU_433](images/gateway/EU_433.svg)

## [`AS_920_923`](../gateway/AS_920_923.yml): Asia 920-923 MHz

>> TTN Community Network frequency plan for Asian countries, using frequencies ≤ 923 MHz

![AS_920_923](images/gateway/AS_920_923.svg)

## `AS_920_923_LBT`: Asia 920-923 MHz with LBT
Based on AS_920_923 and modified by [lbt_80_over_128.yml](../gateway/modifiers/lbt_80_over_128.yml)


>> TTN Community Network frequency plan for Asian countries, using frequencies ≤ 923 MHz with listen-before-talk

![AS_920_923_LBT](images/gateway/AS_920_923_LBT.svg)