Lorawan-stack: Document device types OTAA, ABP and Multicast

Removed irrelevant sections for issue of type "question"

Ref #890

Q: Is there a possibility to send multicast messages with webhook?

A: Yes, the stack supports registering Class C multicast sessions as any other end device with the --multicast flag. This is described in our Getting Started: https://github.com/TheThingsNetwork/lorawan-stack/blob/master/doc/gettingstarted.md#creating-a-device

Q: Is there a possibility to send firmware downlink data as multicast messages to many nodes (for the application) using webhooks?

A: Yes, the multicast session is registered as any other device, so you can schedule downlink to it in the exact same way as you would for a normal device.

Q: Is there some docs/info for this?

A: Not more than is currently in the Getting Started.

@rvolosatovs @adriansmares IIRC you guys did testing with Class C and with Multicast, right? Should we write a nice documentation page about that?

If yes, then let's wait for #401 before doing it.

@htdivsser - thanks for reply. I saw it on getting started.

The syntax of webhook (url) is :
curl http://localhost:1885/api/v3/as/applications/ap2/webhooks/fwup/devices/dv1/down/push -X POST -H 'Authorization: Bearer NNSXS.CLCIYOYYEDPLJSSWRNMYS5KCDI45HOE6M3WZIDY.E6DXAAZ4HSX2V6VL7C3244HGNKBO24SEROTXOZURJHWWOMWZQSPA' --data '{"downlinks":[{"frm_payload":"vu8=","f_port":15,"priority":"NORMAL"}]}'

There is single device name specified for downlink target

So what is the syntax of webhook enforcing multicast message to multiple devices?

The idea is that you register a single "pseudo-device" representing a multicast group that contains multiple physical devices. When using the webhook to schedule downlink to the multicast group, you target it at this pseudo-device.

As you can see in the Getting Started, the registration of such a pseudo-device is essentially the same as for an ABP device. The DevAddr is the Multicast address, the NwkSKey is the McNwkSKey and the AppSKey is the McAppSKey.

Since we haven't implemented Remote Multicast Setup yet, the multicast session on the device side still needs to be set up by the application layer.

@htdvisser thanks.
Does multicast pseudo-device have to be ABP?
I hope it not colide with accessing real end-devices directly?

I can't find anything about creation pseudo-device and add devices to this "group" in getting started you've mentioned.

I've also checked:
ttn-lw-cli --help
ttn-lw-cli end-devs --help
ttn-lw-cli dev --help
and can't see "intuitive" description for pseudo devices and groups.

Can you supply commands, to achieve this?

@ecities Multicast devices have to be ABP, since they do not send uplinks and hence do not support OTAA flow by definition
Register the device same way you would an ABP device, but add the multicast flag.

@rvolosatovs thanks
Multicast devices have to be ABP, since they do not send uplinks and hence do not support OTAA flow by definition
So We have to choose only one of ??:
-standard dev with otta (class A or C)
-multicast dev with abp (class C) - flag created at device creation and can't be removed. Can't uplink data at all.

Or maybe there is workaround eg: add devices to 2 different apps?
1) for normal (uplink/downlink) work (ap1)
2) for multicast downlink only (ap2)
_But it seams to have problems with access rights - we've reported issue here_

Register the device same way you would an ABP device, but add the multicast flag.

Maybe an example:
Lets say I have 2 devices (dev1, dev2 with the same McNwkSKey, McAppSKey and maybe dev-addr)
ttn-lw-cli end-devices create app1 dev1 \
--frequency-plan-id EU_863_870 \
--lorawan-version 1.0.2 \
--lorawan-phy-version 1.0.2-b \
--abp \
--session.dev-addr 00E4304D \
--session.keys.app-s-key.key A0CAD5A30036DBE03096EB67CA975BAA \
--session.keys.nwk-s-key.key B7F3E161BC9D4388E6C788A0C547F255 \
--multicast

ttn-lw-cli end-devices create app1 dev2 \
--frequency-plan-id EU_863_870 \
--lorawan-version 1.0.2 \
--lorawan-phy-version 1.0.2-b \
--abp \
--session.dev-addr 00E4304D \
--session.keys.app-s-key.key A0CAD5A30036DBE03096EB67CA975BAA \
--session.keys.nwk-s-key.key B7F3E161BC9D4388E6C788A0C547F255 \
--multicast

Is it right?

and want to send multicast message to both of them with webhook.
It's still not clear for me what would be URL for webhook ?
http://localhost:1885/api/v3/as/applications/ap2/webhooks/fwup/devices/00E4304D/down/push

Is this correct?

Or maybe:

http://localhost:1885/api/v3/as/applications/ap2/webhooks/fwup/devices/dev1/down/push

and it will be received by other devices with the same security settings where
--session.keys.app-s-key.key A0CAD5A30036DBE03096EB67CA975BAA
--session.keys.nwk-s-key.key B7F3E161BC9D4388E6C788A0C547F255

??

A multicast device registered in lorawan-stack may represent arbitrary number of physical devices.
So let's say you had 5 devices you want to operate in Multicast mode - then you'd provision all 5 of your physical devices to use:

• identical DevAddr(e.g. 00E4304D)
• identical session keys(e.g. A0CAD5A30036DBE03096EB67CA975BAA and A0CAD5A30036DBE03096EB67CA975BAA for AppSKey and NwkSKey respectively).

Then you'd register a single device in lorawan-stack with the DevAddr and session keys you chose and multicast flag set.
Let's say you called the device you just created dev1 and app name is app1.
Let's say you then proceed to push a downlink for dev1 in app app1(please see the documentation on various ways to do that), then the lorawan-stack would schedule a single downlink for device with DevAddr 00E4304D.
The single downlink would be received by all devices matching DevAddr 00E4304D, i.e. all 5(ideally) devices you provisioned above.

Note, that some physical devices are able to actually participate in multiple sessions simultaneously.
Let's assume you have 5 such devices and you want them to operate as OTAA, while also being a part of multicast group:

1. You would register each device as a separate OTAA device with each it's own device ID. (so, register 5 devices - 1 per each physical device)
2. You would register a single device as a multicast device with a distinct device ID.(so, register 1 device - 1 per each multicast group)

The key to understand here is that registered multicast device may represent multiple physical devices, however all of these physical devices have to share the DevAddr and session keys.

@rvolosatovs thanks a lot for very good "step-by-step" explanation, which eliminates most of assumptions

I think it's worth to be copied to Getting started manual or multicast documentation as this is not so obvious in practice

Regards,

Robert

@ecities you're welcome, glad I could help!
@adriansmares can you pick this up?

@adriansmares suggesting that we explain a bit in more detail what OTAA, ABP and Multicast devices are, especially the latter.

I'm trying to create --multicast device (command copied from getting started example)

ttn-lw-cli end-devices create ap3 lldv3 \
--frequency-plan-id EU_863_870 \
--lorawan-version 1.0.2 \
--lorawan-phy-version 1.0.2-b \
--abp \
--session.dev-addr 11E4304D \
--session.keys.app-s-key.key A0CAD5A30036DBE03096EB67CA975BAA \
--session.keys.nwk-s-key.key B7F3E161BC9D4388E6C788A0C547F255 \
--multicast

and got a message:
unknown flag: --multicast

ttn-lw-cli version
The Things Network Command-line Interface: ttn-lw-cli
Version: 3.0.3
Go version: go1.12.5
OS/Arch: linux/amd64

Please wait for v3.1.0 or build master from source, see DEVELOPMENT.md.