This section provides guidelines for configuring MAC settings for end devices from the CLI.
Command-line interface only
The instructions below use the command-line interface (CLI).
MAC Settings and MAC State
MAC settings on The Things Stack are configurable per end device. To configure persistent MAC settings, make changes to
mac-settings.desired_<parameter>. Updates to
mac-settings.desired_<parameter> take effect on device creation, after OTAA join or ABP FCnt reset, ResetInd, or after MAC state reset.
mac-settings.<parameter> represents what the Network Server believes is configured on the end device, and should not be changed, unless the device does not conform to the LoRaWAN specification. It may however be necessary to set
mac-settings.RX1_delay for ABP devices where this is not configured as part of activation.
mac-state can be used to test MAC settings in the current session. To update settings for testing in the current session, make changes to the
mac-state.desired_parameters.<parameter>. Updates to the
mac-state.desired_parameters.<parameter> are applied on the next uplink, and lost on reset.
The expected procedure for testing and updating settings is:
mac-state.desired_parameters.<parameter>to see changes in the current session
- Test that everything works as expected
mac-settings.desired_<parameter>to make the change permanent
See how this applies to the Rx1 delay parameter in the example below. If no settings are provided on device creation or unset, defaults are first taken from the device Frequency Plan if available, and finally from Network Server Configuration.
Example: Configure Rx1 Delay
Note:The Things Stack configures the
Rx1Delayto 5 seconds by default to accomodate for high latency backhauls and/or peering with Packet Broker, so this is the recommended configuration. For demonstration purposes, in this example we use 6 seconds.
To see Rx1 delay change in the current session, modify the
ttn-lw-cli end-devices update --application-id <application-id> --device-id <device-id> --mac-state.desired-parameters.rx1-delay RX_DELAY_6
The Network Server will schedule an
RxTimingSetupReq MAC command to communicate a new
Rx1Delay of 6 seconds to the device. The end device will answer with an
RxTimingSetupAns MAC command in the next uplink. The Network Server will then start using the
Rx1Delay of 6 seconds for scheduling downlinks. For this change to take effect, the end device does not need to perform a re-join.
To make the Rx1 delay change persistent upon end device re-join, modify the
ttn-lw-cli end-devices update --application-id <application-id> --device-id <device-id> --mac-settings.desired-rx1-delay RX_DELAY_6
The Rx1 delay change will take effect only after the end device performs a re-join, i.e. in the new session. The
Rx1Delay of 6 seconds will be communicated to the device during join procedure via Join-accept downlink message.
If the end device does not conform to the LoRaWAN Specification and has a custom Rx1 delay configured in it (6 seconds in this example), modify the
ttn-lw-cli end-devices update --application-id <application-id> --device-id <device-id> --mac-settings.rx1-delay RX_DELAY_6
The Network Server will start using the
Rx1Delay of 6 seconds for downlink communication with the end device.
Available MAC Settings
Run the following command to get a list of all available MAC settings and available parameter values:
ttn-lw-cli end-devices set --help
You can also refer to the End Device API Reference page for documentation on the available MAC settings and MAC state parameters.
Class Specific Settings
Settings that are useful based on device class are:
Class A ABP:
Some additional examples are included below. All settings are available at the End Device API Reference page and can be viewed using the
ttn-lw-cli end-devices set --help command.
Configure Factory Preset Frequencies for ABP Devices
To tell The Things Stack which frequencies are configured in an ABP device, set the
mac-settings.factory-preset-frequencies parameter. For example, to configure a device using the default EU868 frequencies, use the following command:
ttn-lw-cli devices update <app-id> <device-id> --mac-settings.factory-preset-frequencies 868100000,868300000,868500000,867100000,867300000,867500000,867700000,867900000
Note:For ABP devices,
mac-settings.factory-preset-frequenciesshould be specified on
device createor the settings will only take effect after MAC reset.
Set Duty Cycle
To change the duty cycle, set the
desired-max-duty-cycle parameter. For example, to set the duty cycle to 0.098%, use the following command:
ttn-lw-cli end-devices set <app-id> <device-id> --mac-settings.desired-max-duty-cycle DUTY_CYCLE_1024
See the End Device API Reference for available fields and definitions of constants.
DUTY_CYCLE_1024 represents 1/1024 ≈ 0.098%.
To enable ADR, set the
ttn-lw-cli end-devices set <app-id> <device-id> --mac-settings.use-adr=true
See the Adaptive Data Rate section for detailed information on configuring ADR parameters and ADR margin using MAC settings.
Set RX1 Delay
The RX1 delay of end devices is set to 5 second by default. To change it, set the
ttn-lw-cli end-devices set <app-id> <device-id> --mac-settings.desired-rx1-delay RX_DELAY_5
Unset MAC settings
The CLI can also be used to unset MAC settings (so that the default ones are used):
ttn-lw-cli end-devices set <app-id> <device-id> --unset mac-settings.rx1-delay
Session and MAC State Reset
Resetting session and MAC state for OTAA devices will wipe out all session and MAC data, and the end device will need to perform a rejoin on The Things Stack network. For ABP devices, only MAC state gets reset, while session keys, DevAddr and downlink queue are preserved.
Session and MAC state can be reset through the Console - navigate to your end device’s General settings tab, scroll down to the Network layer section, press the Reset session and MAC state button and confirm.
To reset session and MAC state using the CLI:
ttn-lw-cli end-devices reset --application-id <application-id> --device-id <device-id>