Document `mac-settings` and `mac-state` commands

[benolayinka]

Summary

There is currently no CLI guide for updating device parameters using API commands from https://github.com/TheThingsNetwork/lorawan-stack/blob/develop/doc/content/reference/api/end_device.md

There is also confusion about the difference between mac-state and mac-settings endpoints. https://github.com/TheThingsIndustries/lorawan-stack-support/issues/48

Why do we need this ?

To provide a standard way to configure mac settings on devices.

What is already there? What do you see now?

https://github.com/TheThingsNetwork/lorawan-stack/blob/develop/doc/content/reference/api/end_device.md

What is missing? What do you want to see?

A guide

How do you propose to document this?

I'll write the documentation. @rvolosatovs can you clarify the mac-state vs mac-settings thing and recommend a way for configuring these settings?

Can you do this yourself and submit a Pull Request?

Yes

[rvolosatovs]

See https://github.com/TheThingsIndustries/lorawan-stack-support/issues/48#issuecomment-651779700

mac-settings are only effective on device creation or after MAC state reset (e.g. after OTAA join or ABP FCnt reset, or ResetInd MAC command) mac-state changes are volatile and only apply to the active session - once the MAC state is reset, all modifications are lost

[benolayinka]

See TheThingsIndustries/lorawan-stack-support#48 (comment)

mac-settings are only effective on device creation or after MAC state reset (e.g. after OTAA join or ABP FCnt reset, or ResetInd MAC command) mac-state changes are volatile and only apply to the active session - once the MAC state is reset, all modifications are lost

Okay. The MACState API Docs say it is read-only. This isn't true? 

[rvolosatovs]

Not anymore indeed

[benolayinka]

Okay. One last question @rvolosatovs :)

For the mac-settings, what's the difference between setting --mac-settings.rx1-delay and --mac-settings.desired-rx1-delay? the MAC settings is only applied on a join anyway, right?

And for mac-state, what does setting mac-state.desired-parameters do, if the state is lost after a reset? When does desired become current?

[rvolosatovs]

For OTAA --mac-settings.rx1-delay probably does not make much sense, but it does for ABP, where there's no explicit join procedure, and, hence NS needs to know what the current Rx1Delay of the device is.

And for mac-state, what does setting mac-state.desired-parameters do, if the state is lost after a reset? When does desired become current?

It triggers MAC commands being sent by NS, see https://github.com/TheThingsIndustries/lorawan-stack-support/issues/48#issuecomment-651779700

Regarding

When does desired become current?

Specifically, for most commands NS sends a MAC request to the device and then device responds with a confirmation that it received the initial request and applied the changes - that's when the "desired" becomes current.

[benolayinka]

closed by #2928