Lorawan-stack: Document connecting popular gateways

[johanstokking]

Summary

Document connecting popular gateways

Why do we need this?

For people to know how to connect their gateway using official documentation, on a per-gateway model basis

What is already there? What do you see now?

No documentation

What is missing? What do you want to see?

Documentation for phase 1 (UDP-based gateways):

• [x] Cisco IXM
• [x] Lorix One
• [ ] RAK7240
• [x] Ursalink
• [ ] ST - P-NUCLEO-LRWAN2
• [x] Laird Sentrius RG1xx
• [ ] Kerlink iBTS Compact
• [ ] Kerlink iFemtocell
• [x] Kerlink IoT Station – #1631 @rvolosatovs is assigned
• [x] MultiTech Conduit AEP – #1793 but needs fix
• [ ] MultiTech Conduit mlinux - #2733
• [x] MikroTik Routerboard - #1964
• [x] Tektelic Kona Micro (Terminal) #1742
• [x] Tektelic Kona Micro (GUI) and small follow up (https://github.com/TheThingsNetwork/lorawan-stack/pull/1742#pullrequestreview-335910258)
• [ ] Tektelic Kona Pico
• [x] The Things Kickstarter Gateway - @KrishnaIyer @adriansmares
• [x] NASys LoRaWAN Outdoor Gateway - @neoaggelos #1765
• [ ] The Things Outdoor Gateway

Documentation for phase 2 (Basic Station gateways):

• [x] Basic Station common #2594
• [ ] The Things Indoor Gateway TTI issue #2088

Documentation for phase 3 (existing gateways that are getting Basic Station support):

• [ ] Cisco IXM with Basic Station
• [ ] MultiTech Conduit AEP with Basic Station
• [x] Laird Sentrius with Basic Station
• [x] Lorix One with Basic Station
• [x] Ursalink with Basic Station

For the UDP gateways (everything expect TTIG for now), please use the JSON configuration using GCS.

This is a URL that people need to build manually.

How do you propose to implement this?

• Make sure you have a stock version of these gateways. If we don't have one, please let me know and we'll get one. You can also start with copying docs from https://www.thethingsnetwork.org/docs/gateways
• Probably refer to a common section about creating a gateway and UDP configuration
• Add a guide in the docs, one file for each gateway brand and/or model, depending on how it looks

Can you do this yourself and submit a Pull Request?

Will review

[johanstokking]

Looped in @adriansmares for support as well. Please coordinate accordingly.

[johanstokking]

Added Cisco IXM

[johanstokking]

See also existing documentation on https://www.thethingsnetwork.org/docs/gateways/

This should act as a _reference_; that documentation has grown over time and does not follow one style or structure.

Please start with defining a style and structure and align all gateway documentation with that.

[KrishnaIyer]

@adriansmares, @mjamescompton and @johanstokking:

• I've created a feature branch for this feature/gateway-documentation. Please target all PRs to this branch.
• The first candidate is here: https://github.com/TheThingsNetwork/lorawan-stack/pull/1368

[johanstokking]

@MathieuMonneret I updated the original comment.

@adriansmares can you share how we build the GCS link based on cluster name and gateway ID?

[neoaggelos]

I added the NASYS outdoor gateway on the list, I could get that. Will create an issue and start working on the documentation later.

[johanstokking]

What is the status here @MathieuMonneret ?

[MathieuMonneret]

I actually have a doubt regarding the GatewayEUI I need to make sure once I am back at the office. Otherwise, the configuration is exactly the same as V2, just a link to ttn docs should be sufficient, same for registration. Also registration needs to happen after configuration, which doesn't really follow the generic template.

[htdvisser]

My comment https://github.com/TheThingsNetwork/lorawan-stack/pull/1765#discussion_r360807466 in the NASYS PR may also be relevant for other gateways, so reposting it here:

With v3 we can automatically configure gateways with not only server parameters, but also with its frequency plan:

$ curl -H "Authorization: Bearer NNSXS.<snip>.<snip>" https://thethings.example.com/api/v3/gcs/gateways/your-gateway-id/semtechudp/global_conf.json

@rvolosatovs wrote a nice script for Kerlink Wirnet gateways (in https://github.com/TheThingsNetwork/kerlink-station-firmware), maybe we can do the same for other gateways?

[johanstokking]

I wonder if we should put effort in generalizing that script, because of the platform differences. Kerlink already has two configuration files, MultiTech has a different clksource, Tektelic is likely different as they don't use reference design. Then, these guys are all working on Basic Station support which hopefully ends the era of UDP configuration at all. I know I'm being very optimistic here.

@MathieuMonneret the gateway EUI is provided by the gateway maker and this depends on the gateway. Some gateways ignore the EUI in the config file and have their packet forwarder report one, some gateways have a (platform specific) script to read the EUI, etc.

It is very similar to V2 anyway. This is unrelated to AppEUIs.

[loganmc10]

I am trying to follow the instructions to join a TTN kickstarter gateway, the gateway won't join. The message in the logs say:

duration=18.325µs error=error:pkg/errors/web:unknown (Not Found) message=Not Found method=GET namespace=web remote_addr=x.x.x.x:5256 request_id=01DWWA895FS8RVNWRQC1PWRPQP status=404 url=/api/v2/gateways/ttn-ks-gateway?filter=ttn

ttn-ks-gateway is the name of the gateway

Am I doing something wrong? The gateway seems to be trying to reach api/v2, but I think the server is only serving api/v3

[KrishnaIyer]

@loganmc10: This is not the right issue. Could you please create a separate issue for this mentioning the value of the Account Server that you used?

[neoaggelos]

@johanstokking NASys gateway also uses a fork of the semtech packet forwarder, with some vendor-specific configuration options . Perhaps having a generic script would be more trouble than it's worth? also see my comment at #1765

I wonder if we should put effort in generalizing that script, because of the platform differences. Kerlink already has two configuration files, MultiTech has a different clksource, Tektelic is likely different as they don't use reference design. Then, these guys are all working on Basic Station support which hopefully ends the era of UDP configuration at all. I know I'm being very optimistic here.

[anush0247]

@KrishnaIyer We added documentation for MultiTech Conduit AEP gateway

As we don't have feature/gateway-documentation we targeted #1793 to master branch.

[laurensslats]

@benolayinka can we revisit this list and see what gateway documentation we still want to add?

Suggesting to:

• Look at the Kerlink documentation, we might be able to improve the quality
• Tektelic gateways with Basics Station
• RAK with UDP & Basics Station

[johanstokking]

Please open issues specific for gateway models.