Claim gateways using a QR code

KrishnaIyer commented 2 weeks ago

Summary

Claim gateways using a QR code.

Current Situation

We can currently claim gateways using an EUI and an owner token.

Why do we need this? Who uses it, and when?

Users with a gateway QR code can claim it. This is very similar to claiming end devices.

Proposed Implementation

Backend:

Introduce a GatewayQRCodeGenerator service similar to the EndDeviceQRCodeGenerator with one single method Parse.
- The input would be ParseGatewayQRCodeRequest which is a copy of ParseEndDeviceQRCodeRequest, adjusted for gateways.
- I think the response can be a ClaimGatewayRequest with the AuthenticatedIdentifiers filled; @johanstokking to confirm.
For the actual implementation, we can introduce a new format for this; I propose ttigw001 with the rest of the interfaces/parsing fully adapted from the TR005 implementation.

Frontend:

Introduce a scan QR Code option in the gateway onboarding flow. I think we can replicate the end device onboarding UX; cc: @kschiffer
Use the ParseGatewayQRCodeRequest RPC, which will return a ClaimGatewayRequest with only the identifiers filled. Fill the rest of the fields (ex: Gateway ID, frequency plans etc) as with the current claiming flow and make a request to claim the gateway.

Contributing

[ ] I can help by doing more research.
[ ] I can help by implementing the feature after the proposal above is approved.
[X] I can help by testing the feature before it's released.

Validation

[ ] The feature is tested in a staging environment.
[ ] The feature is documented in The Things Stack Documentation

Code of Conduct

[X] I agree to follow TTN's Community Code of Conduct.

vlasebian commented 2 weeks ago

The ttigw001 is going to be identical to the TR005? Or will it be slightly different?

KrishnaIyer commented 2 weeks ago

Identical in what way?

vlasebian commented 2 weeks ago

Will the implementation be the same?

johanstokking commented 1 week ago

Commented on the PR, that's easier I think.

vlasebian commented 1 week ago

Currently, the request for this endpoint looks like this (the format id is specified as a path argument, or it defaults to a format):

message ParseGatewayQRCodeRequest {
  string format_id = 1 [(validate.rules).string = {
    pattern: "^[a-z0-9](?:[-]?[a-z0-9]){2,}$|^$",
    max_len: 36
  }];
  // Raw QR code contents.
  bytes qr_code = 2 [(validate.rules).bytes = {
    min_len: 10,
    max_len: 1024
  }];
}

From what I understand, the QR code will contain a URL. Will the URL be encoded when sending it to this endpoint in the qr_code field? Because if it's plain text, it will not pass the validation. What I mean is if it's simply sent like this:

{ "qr_code": "https://ttig.pro/c/ec656efffe000128/abcdef123456" }

The endpoint will return the following error:

{"code":3, "message":"proto: (line 1:14): invalid value for bytes type: \"https://ttig.pro/c/ec656efffe000128/abcdef123456\""}

So the URL probably has to be in a base64 encoded form before passing it to the request. Does that make sense? Or would it be better to just change the type of the request field?

@johanstokking

(I left a comment here not in the issue because it might be relevant for fe too)

johanstokking commented 1 week ago

So the URL probably has to be in a base64 encoded form before passing it to the request. Does that make sense? Or would it be better to just change the type of the request field?

Yeah I'm a bit conflicted on this. If we use bytes for the end device QR code, then let's do that here as well. Indeed when using JSON it'd be base64 encoded.

TheThingsNetwork / lorawan-stack