Document LoRa Basics Station CUPS forwarding

[adriansmares]

Summary

We should document LoRa Basics Station CUPS forwarding - the why and the how.

Why do we need this ?

In order to show users how to redirect gateways to other Gateway Servers using CUPS. This is very relevant for the remote control of the gateway.

What is already there? What do you see now?

Generic description of CUPS and LNS.

What is missing? What do you want to see?

A new section for CUPS redirection.

How do you propose to document this?

1. Explain situations in which this is applicable.

• This applies to gateways using the LoRa Basics Station forwarder, which are configured to do CUPS with a The Things Stack instance.
• To users which want to move their gateway connections from one instance (for example TTSCE) to another (for example, TTSC).

2. Explain how to achieve this:

• One needs to register the gateway in the target instance (i.e. TTSC if you migrate from TTSCE).
• Then one needs to create an LNS key in the target instance. The LNS key is a gateway API key with linking rights.
• Then one needs to set the LNS key from the target instance in the source instance (i.e. TTSCE if you migrate to TTSC).
• Optional: invalidate the LNS key in the source instance, either by deleting it or by removing the linking right.
• Finally, the gateway server address of the target instance must be set as gateway server address in the source instance.
• Yes, these are exactly the same steps as the CUPS setup tutorial, but the keys are in different servers.

Upon the next CUPS request, the gateway will reconnect from the old instance to the new instance. Normally a CUPS request is sent every 24 hours, but there is another way to speed this up:

1. Starting from v3.28.2, changing the gateway server address will force the gateway to reconnect. This is not instant - it takes on average 10 minutes after the change occurred.
2. If one invalidates the source LNS key, Basic Station will automatically do a CUPS lookup before the 24 hour window, during which it will pick up the new gateway server address and LNS key (which now point to the target instance).

I heavily recommend testing this between staging1 and TTSC(E), with a gateway which is not a TTIG. Most gateways on staging1 are CUPS enabled, so feel free to ask for details.

Can you do this yourself and submit a Pull Request?

Can review.

[KrishnaIyer]

@nejraselimovic: Please pick this up when you have time.

[nejraselimovic]

Hey, I've been working on testing this, I'm using RAK2245 gw, trying to migrate from TTSS to TTC, and I have some questions:

• You haven't mentioned this in steps above but I had to change TC_KEY variable (that carries LNS key) in gateway config to the new LNS key value (of the target instance), but I haven't had to change CUPS_KEY or CUPS_URI (source instance values). Is this expected? I'm a bit confused by this and term "remote gateway control", i.e. my thoughts are, if I need to change TC_KEY, I could also change URI and not mess around on TTS. Or changing TC_KEY shouldn't be required here? I think I'm missing something here but not sure what. If changing TC_KEY shouldn't be required, then I'm not sure what else I could be doing wrong.
• I disabled forwarding uplinks to Packet Broker, but I still see them being forwarded on Live data. Do you know why?

[adriansmares]

• You haven't mentioned this in steps above but I had to change TC_KEY variable (that carries LNS key) in gateway config to the new LNS key value (of the target instance), but I haven't had to change CUPS_KEY or CUPS_URI (source instance values). Is this expected? I'm a bit confused by this and term "remote gateway control", i.e. my thoughts are, if I need to change TC_KEY, I could also change URI and not mess around on TTS. Or changing TC_KEY shouldn't be required here? I think I'm missing something here but not sure what. If changing TC_KEY shouldn't be required, then I'm not sure what else I could be doing wrong.

As a general remark, CUPS itself deals with the LNS configuration - both the credentials (the API key in our case), and the address (the gateway server address) are provided to the gateway as part of CUPS, and the gateway updates them and stores them 'while doing CUPS'.

In general when I configure a gateway using Basics Station I leave the LNS (i.e. TC) address and credentials empty, and provide only CUPS settings (the URL, and the API key). The gateway is then expected to retrieve the settings via CUPS. So yes, I believe the TC_KEY and TC_URI shouldn't be provided here in the first place - it should be all CUPS only.

I disabled forwarding uplinks to Packet Broker, but I still see them being forwarded on Live data. Do you know why?

There are two behaviors here:

1. Gateway settings are retrieved only when the gateway connects, and no changes are done while the gateway is connected.
2. A gateway will not be disconnected due to settings changes immediately - there is a delay of up to 10 minutes until the gateway reconnects.

A corollary of the above is that after you change the settings, some time will have to pass until the gateway disconnects, then upon connecting the new settings will be used and you can expect the packets to no longer be forwarded.