Add The Things Gateway connection guide #1368

KrishnaIyer · 2019-09-19T17:01:57Z

Summary

Adds the first item for #1140 .

Changes

Create a generic structure.
Add content for TTG.

Notes for Reviewers

Please comment on the structure and style here. Once this PR is merged and we agree on something, please follow the same structure for other gateways @mjamescompton , @adriansmares.
I've added a couple of TODOs that need some clarification.

Release Notes

Added documentation to connect The Things Gateway.

htdvisser

I'm not really a big fan of these bullet point lists in our documentation, can we maybe make it more of an actual guide/story?

htdvisser · 2019-09-20T07:41:36Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+    weight: 2
+---
+
+The Things Gateway is an MQTT based single channel LoRaWAN gateway. The technical specifications can be found in [the official documentation](https://www.thethingsnetwork.org/docs/gateways/gateway/). This page guides you to connect it to a The Things Stack instance.


The Things Gateway is not single-channel

connect it to The Things Stack

No need to mention it's MQTT here

More clear name pending, see out-of-band comms

htdvisser · 2019-09-20T07:42:31Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+
+## Preparation
+
+* User account on a The Things Stack instance with rights to create Gateways and API Keys.


"a The Things Stack instance" sounds weird. Can we just use "The Things Stack" everywhere?

Use numbered lists

htdvisser · 2019-09-20T07:43:34Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+* Login to your The Things Stack instance via the CLI/console.
+* Create a new gateway with the desired `Gateway ID` and choose the correct frequency plan for your device. The EUI field can be left blank.
+  * For details on using the CLI/Console, refer to the [getting started](../../getting-started/) section.
+* Create an API Key with Gateway Link Rights (TODO: needs more info?). Copy and save the key for later use.


Doesn't the Getting Started already have details for this? Otherwise I think it would be better to add it there.

Should we have another checkbox in the Create Gateway page that allows you to create a link API key for this gateway ? This streamlines the guide a lot.

Link to Create gateway in Console getting started. You can create an anchor and link to it

htdvisser · 2019-09-20T07:45:25Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+  * Choose the WiFi network from the drop down and enter a password if necessary.
+* Click the `Show Advanced Options` button and enter the following fields
+  * Account Server: The URL of your stack's identity server. This is of the form `https://<your-domain-or-ip>:<port>`.
+  * (TODO: How to make this URL generic?)


We use https://thethings.example.com in the getting started guide.

Is the port mandatory? No, right?

nope. That's for non 443. Added a note.

htdvisser · 2019-09-20T07:48:02Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+
+* Login to your The Things Stack instance via the CLI/console.
+* Create a new gateway with the desired `Gateway ID` and choose the correct frequency plan for your device. The EUI field can be left blank.
+  * For details on using the CLI/Console, refer to the [getting started](../../getting-started/) section.


Use the relref shortcode for the link

Consider {{< ref "/guides/getting-started" >}} to avoid relative path coupling.

htdvisser · 2019-09-20T07:56:47Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+* The gateway will now expose a WiFi Access Point whose SSID is of the form `TheThings-Gateway-xxxxx`.
+  * Connect to this network using a mobile phone/computer.
+* In a web browser, navigate to http://192.168.84.1/. A sample page is shown below.
+{{< figure src="ttg-config-window.png" alt="TTG Configuration Window" >}}


Maybe nice if we do screenshots the same way as in Getting Started:

(Chrome)

Activate Developer Tools

Toggle Device Toolbar (⌘⇧M)

In the Device Toolbar: select "Laptop with HiDPI screen" (add it if not already there)

In the Device Toolbar: ⠇ -> Capture Screenshot

(Firefox)

Enter Responsive Design Mode

In the Device Toolbar: select "Laptop with HiDPI screen" (add it if not already there)

In the Device Toolbar: Take a screenshot of the viewport

While at it, let's add these steps to the instructions?

For <insert-connection-key>, can we put there explicitly the gateway API key for linking?

adriansmares

Added a couple of comments - I also agree that it should look more story telling akin to the other guides.

adriansmares · 2019-09-20T08:17:12Z

doc/content/guides/connecting-gateways/_index.md

+---
+title: "Connecting Gateways"
+description: ""
+weight: 3


We are in a sort of chicken-and-egg situation, but I think the weight should be higher.

This section should also be mentioned in the getting started in the Create gateway section.

This should go after Getting Started indeed

adriansmares · 2019-09-20T08:21:27Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+* Login to your The Things Stack instance via the CLI/console.
+* Create a new gateway with the desired `Gateway ID` and choose the correct frequency plan for your device. The EUI field can be left blank.
+  * For details on using the CLI/Console, refer to the [getting started](../../getting-started/) section.
+* Create an API Key with Gateway Link Rights (TODO: needs more info?). Copy and save the key for later use.


Should we have another checkbox in the Create Gateway page that allows you to create a link API key for this gateway ? This streamlines the guide a lot.

rvolosatovs · 2019-09-23T09:18:59Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+* While the gateway is powered on, hold the pink reset button for 5 seconds (until each of the 5 LEDs illuminate).
+  * This erases the existing configuration on the gateway.
+* The gateway will now expose a WiFi Access Point whose SSID is of the form `TheThings-Gateway-xxxxx`.
+  * Connect to this network using a mobile phone/computer.


SSID password missing

This is more generic to the gateway and is documented in the general setup guide and is independent of the stack.
https://www.thethingsnetwork.org/docs/gateways/gateway/#activating-the-gateway

johanstokking · 2019-09-23T09:39:18Z

doc/content/guides/connecting-gateways/_index.md

+---
+title: "Connecting Gateways"
+description: ""
+weight: 3


This should go after Getting Started indeed

johanstokking · 2019-09-23T09:42:06Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+    weight: 2
+---
+
+The Things Gateway is an MQTT based single channel LoRaWAN gateway. The technical specifications can be found in [the official documentation](https://www.thethingsnetwork.org/docs/gateways/gateway/). This page guides you to connect it to a The Things Stack instance.


No need to mention it's MQTT here

More clear name pending, see out-of-band comms

johanstokking · 2019-09-23T09:43:00Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+The Things Gateway is an MQTT based single channel LoRaWAN gateway. The technical specifications can be found in [the official documentation](https://www.thethingsnetwork.org/docs/gateways/gateway/). This page guides you to connect it to a The Things Stack instance.
+
+
+## Preparation


Prerequisites

johanstokking · 2019-09-23T09:43:17Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+
+## Preparation
+
+* User account on a The Things Stack instance with rights to create Gateways and API Keys.


Use numbered lists

johanstokking · 2019-09-23T09:45:40Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+
+## Registration
+
+* Login to your The Things Stack instance via the CLI/console.


"Login to The Things Stack via ..."

johanstokking · 2019-09-23T09:51:41Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+* While the gateway is powered on, hold the pink reset button for 5 seconds (until each of the 5 LEDs illuminate).
+  * This erases the existing configuration on the gateway.
+* The gateway will now expose a WiFi Access Point whose SSID is of the form `TheThings-Gateway-xxxxx`.
+  * Connect to this network using a mobile phone/computer.


What else? Tablet not supported? Should we mention the device at all?

johanstokking · 2019-09-23T09:52:02Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+  * Account Server: The URL of your stack's identity server. This is of the form `https://<your-domain-or-ip>:<port>`.
+  * (TODO: How to make this URL generic?)
+  * Gateway Key: The API Key created earlier.
+* Click `Save` when done.


johanstokking · 2019-09-23T09:52:36Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+* Click the `Show Advanced Options` button and enter the following fields
+  * Account Server: The URL of your stack's identity server. This is of the form `https://<your-domain-or-ip>:<port>`.
+  * (TODO: How to make this URL generic?)
+  * Gateway Key: The API Key created earlier.


Gateway Key

johanstokking · 2019-09-23T09:52:54Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+  * (TODO: How to make this URL generic?)
+  * Gateway Key: The API Key created earlier.
+* Click `Save` when done.
+* This will apply the setting and reboot the gateway. If all have been followed correctly, your gateway will connect to your stack instance.


will connect to The Things Stack

johanstokking · 2019-09-23T09:53:44Z

doc/content/guides/connecting-gateways/thethingsgateway/_index.md

+
+## Troubleshooting
+
+* If the gateway doesn't connect to the backend after a few minutes, disconnect and reconnect the power supply to power-cycle it.


does not

connect to The Things Stack

"power-cycle the gateway" ?

KrishnaIyer · 2019-09-23T17:17:00Z

I disagree with both @htdvisser and @adriansmares. I think having clear bullets is more readable for setup guides. But I've modified this to be consistent with the rest of the documentation.

htdvisser · 2019-09-24T09:10:53Z

doc/content/guides/connecting-gateways/thethingskickstartergateway/_index.md

+The gateway will now expose a WiFi Access Point whose SSID is of the form `TheThings-Gateway-xxxxx`, to which you can connect.
+
+In a web browser, navigate to http://192.168.84.1/. A sample page is shown below.
+{{< figure src="ttg-config-window.png" alt="TTG Configuration Window" >}}


We don't use "TTG"

htdvisser · 2019-09-24T09:13:04Z

doc/content/guides/connecting-gateways/thethingskickstartergateway/_index.md

+
+Login to The Things Stack via the CLI/console.
+
+Create a new gateway with the desired `Gateway ID` and choose the correct frequency plan for your device. The EUI field can be left blank. For details on using the CLI/Console, refer to the [getting started]({{< ref "/guides/getting-started" >}}) section.


Make Gateway ID bold instead of code

IIRC there were some extra restrictions for the ID, because the gateway's web ui does some validation on it. So either we need to fix that, or we need to tell users what those restrictions are.

Yeah we have an issue for that. Minimum of 6 characters. I think it's easier right now to just document it than updating the gateway firmware.

adriansmares

Approved.

I understand that the list type guides are straight to the point compared to story type guides, but keep in mind that they are shorter because they have some implicit knowledge attached to them. Since this documentation is not only for professionals, it is good to keep it in this format.

KrishnaIyer added the documentation This involves writing user documentation label Sep 19, 2019

KrishnaIyer added this to the September 2019 milestone Sep 19, 2019

KrishnaIyer requested review from htdvisser, johanstokking, adriansmares and mjamescompton September 19, 2019 17:01

KrishnaIyer self-assigned this Sep 19, 2019

KrishnaIyer mentioned this pull request Sep 19, 2019

Document connecting popular gateways #1140

Closed

25 tasks

htdvisser reviewed Sep 20, 2019

View reviewed changes

adriansmares reviewed Sep 20, 2019

View reviewed changes

rvolosatovs reviewed Sep 23, 2019

View reviewed changes

johanstokking reviewed Sep 23, 2019

View reviewed changes

KrishnaIyer added 2 commits September 23, 2019 18:07

doc: Add The Things Gateway guide

f3b3710

doc: Add section for gateway API Key creation

6a1f1dc

KrishnaIyer force-pushed the feature/1140-ttgc branch from a53fc48 to 3eab954 Compare September 23, 2019 17:15

KrishnaIyer requested a review from bafonins as a code owner September 23, 2019 17:15

KrishnaIyer requested review from htdvisser, adriansmares, johanstokking and rvolosatovs September 23, 2019 17:18

doc: Make ttkg consistent with other docs

ad4c083

KrishnaIyer force-pushed the feature/1140-ttgc branch from 3eab954 to ad4c083 Compare September 24, 2019 07:51

KrishnaIyer removed the request for review from bafonins September 24, 2019 07:56

htdvisser reviewed Sep 24, 2019

View reviewed changes

doc: Add additional restrictions for ID

bfaedbd

KrishnaIyer requested a review from htdvisser September 24, 2019 11:29

adriansmares approved these changes Sep 24, 2019

View reviewed changes

htdvisser approved these changes Sep 24, 2019

View reviewed changes

KrishnaIyer merged commit bad3d35 into feature/gateway-documentation Sep 24, 2019

KrishnaIyer deleted the feature/1140-ttgc branch September 24, 2019 11:44

htdvisser mentioned this pull request Nov 21, 2019

Add The Things Gateway connection guide #1619

Merged


		## Preparation

		* User account on a The Things Stack instance with rights to create Gateways and API Keys.

		The Things Gateway is an MQTT based single channel LoRaWAN gateway. The technical specifications can be found in [the official documentation](https://www.thethingsnetwork.org/docs/gateways/gateway/). This page guides you to connect it to a The Things Stack instance.


		## Preparation


		## Registration

		* Login to your The Things Stack instance via the CLI/console.


		## Troubleshooting

		* If the gateway doesn't connect to the backend after a few minutes, disconnect and reconnect the power supply to power-cycle it.


		Login to The Things Stack via the CLI/console.

		Create a new gateway with the desired `Gateway ID` and choose the correct frequency plan for your device. The EUI field can be left blank. For details on using the CLI/Console, refer to the [getting started]({{< ref "/guides/getting-started" >}}) section.

Add The Things Gateway connection guide #1368

Add The Things Gateway connection guide #1368

Conversation

KrishnaIyer commented Sep 19, 2019 • edited by htdvisser

Summary

Changes

Notes for Reviewers

Release Notes

htdvisser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adriansmares left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KrishnaIyer commented Sep 23, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adriansmares left a comment

Choose a reason for hiding this comment

KrishnaIyer commented Sep 19, 2019 •

edited by htdvisser