From a20c54a4bd6d0377becc90e764dc6fe4c5082adb Mon Sep 17 00:00:00 2001 From: Luca Succi Date: Fri, 23 Feb 2024 10:58:48 +0100 Subject: [PATCH 1/3] Add markdown guide to link a device --- LINKING.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +++ 2 files changed, 79 insertions(+) create mode 100644 LINKING.md diff --git a/LINKING.md b/LINKING.md new file mode 100644 index 0000000..a394efc --- /dev/null +++ b/LINKING.md @@ -0,0 +1,75 @@ +# How To link your GRiSP2 Board to your GRiSP.io account + +## Get yourself a GRiSP.io device linking token + + +1. Login or Register on [GRiSP.io](https://grisp.io) +2. Request a new Linking Token on the [GRiSP Manager](https://grisp.io/grisp-manager/) web view +3. Use the user-friendly binary application or try to manually link your board as explained below + +## Use the grisp_auto_link binary package + +If you do not want to write code we provide a zip file that can be extracted on a Fat32 SD card. +This zip contains a deployed release of [grisp_auto_link](https://github.com/grisp/grisp_auto_link) application, +customized with your linking token. You then just need to put the SD card in your board and connect it with an ethernet cable to the internet. The application will connect the board for you and you will be able to see it in the GRiSP Manager web view. You will find the download button near your token on GRiSP Manager the webpage. + +## Manually link your board + +You are free to use the grisp_io API in your code or procede manually while connected by serial or remote shell to the erlang shell running on the board. + +1. Follow the [GRiSP Wiky](https://github.com/grisp/grisp/wiki) +to create your GRiSP2 application project and learn how to deploy + + - **Optional:** if you do not want to type the device_linking_token at runtime +you can add it to the application env variables in your release config (e.g. `config/sys.config`) + ``` + [ + {grisp_io, [ + {device_linking_token, <<"...">>} + ]} + ]. + ``` + Copy in there the Linking Token you precedently generated on the web page. +2. Follow the tutorial until you are able to deploy your app on the board. + + +By default grisp_io application connects on boot, it will keep tryng until it succedes. + +3. Make sure your board is able to connect to the internet +4. Connect via serial or remote_shell to the erlang shell on the board. +5. In the erlang shell: verify connection to GRiSP.io +``` + > grisp_io:is_connected(). + true +``` +6. Check if your board is registered or not. `pong` means that is already linked, +`pang` means that is not linked with any account. +``` + > grisp_io:ping(). + {ok, <<"pang">>} +``` +7. Send a linking request providing the Linking Token as binary argument in the call. +``` + > grisp_io:link_device(<<"my_long_and_unique_token">>). + {ok, <<"ok">>} +``` +- If you did set the token in the grisp_io env you can just use the shorter call. +``` + > grisp_io:link_device(). + {ok, <<"ok">>} +``` +8. Checkout [GRiSP Manager](https://grisp.io/grisp-manager/) device view to spot +your device. Now you will be able to monitor its activities from GRiSP.io + +Possible errors during linking: +- `token_expired`: regenerate one from the web page +- `invalid_token`: please double check you typed it correctly +- `token_undefined`: you called `grisp_io:link_device/0` without setting `device_linking_token` +- `disconnected`: check that your board can connect +- `device_already_linked`: please do not steal GRiSP boards :smirk: + if you need to unlink a GRiSP board see below... + +## Unlink a Device + +We currently do not expose a public API to unlink a GRiSP device. +If you need to unlink your board please contact: grisp@stritzinger.com diff --git a/README.md b/README.md index a45750a..7fb1a71 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ GRiSP.io Client Library for GRiSP +Add this application as a dependency in your GRiSP2 project. +Your board will connect securely through Mutual TLS to the [GRiSP.io](https://grisp.io) services. +See this [LINKING](https://github.com/grisp/grisp_io/blob/main/LINKING.md) guide on how to start using your GRiSP2 board with GRiSP.io + ## Application env options ### connect From 31cd525a80218dbb885e5ed89daa1a281d245eae Mon Sep 17 00:00:00 2001 From: Luca Succi Date: Fri, 23 Feb 2024 16:01:29 +0100 Subject: [PATCH 2/3] Add LINKING guide to ex_doc --- LINKING.md | 19 ++++++++++--------- rebar.config | 1 + 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/LINKING.md b/LINKING.md index a394efc..6557438 100644 --- a/LINKING.md +++ b/LINKING.md @@ -21,15 +21,16 @@ You are free to use the grisp_io API in your code or procede manually while conn to create your GRiSP2 application project and learn how to deploy - **Optional:** if you do not want to type the device_linking_token at runtime -you can add it to the application env variables in your release config (e.g. `config/sys.config`) - ``` - [ - {grisp_io, [ - {device_linking_token, <<"...">>} - ]} - ]. - ``` - Copy in there the Linking Token you precedently generated on the web page. +you can add it to the application env variables in your release confi. (e.g. `config/sys.config`) +Copy in there the Linking Token you precedently generated on the web page. +``` +[ + {grisp_io, [ + {device_linking_token, <<"...">>} + ]} +]. +``` + 2. Follow the tutorial until you are able to deploy your app on the board. diff --git a/rebar.config b/rebar.config index 69ac2bc..3779c70 100644 --- a/rebar.config +++ b/rebar.config @@ -35,6 +35,7 @@ {extras, [ {"CHANGELOG.md", #{title => "Changelog"}}, {"README.md", #{title => "Overview"}}, + {"LINKING.md", #{title => "Device Linking"}}, {"LICENSE", #{title => "License"}} ]}, {main, "README.md"}, From 89e8d9d5e7ccef3c4f72ac4957cd5dc577cb20a2 Mon Sep 17 00:00:00 2001 From: Luca Succi Date: Fri, 23 Feb 2024 17:56:23 +0100 Subject: [PATCH 3/3] Rephrase more professionally --- Board_Registration.md | 74 +++++++++++++++++++++++++++++++++++++++++ LINKING.md | 76 ------------------------------------------- rebar.config | 2 +- 3 files changed, 75 insertions(+), 77 deletions(-) create mode 100644 Board_Registration.md delete mode 100644 LINKING.md diff --git a/Board_Registration.md b/Board_Registration.md new file mode 100644 index 0000000..9d54e5c --- /dev/null +++ b/Board_Registration.md @@ -0,0 +1,74 @@ + +# Register Your GRiSP2 Board with GRiSP.io + +Welcome! This guide walks you through linking your GRiSP2 board to your GRiSP.io account. Begin with obtaining a unique linking token, then choose between automatic or manual registration based on your preference. + +## Obtain Your Device Linking Token + +To start, you'll need a unique token: + +1. **Log In or Sign Up:** Navigate to [GRiSP.io](https://grisp.io) and access your account or create a new one. +2. **Get Your Token:** Visit the [GRiSP Manager](https://grisp.io/grisp-manager/) to request a new Linking Token by clicking on **Link Device**. This token is crucial for the next steps in both automatic and manual registration methods. + +--- + +With your token ready, select one of the following options to register your GRiSP2 board: + +## Option 1: Automatic Linking with grisp_auto_link + +For a hassle-free experience: + +- **Download the Binary Package:** Look for the [grisp_auto_link](https://github.com/grisp/grisp_auto_link) zip file on the GRiSP Manager page under the **Link Device** section. It comes pre-configured with your linking token. +- **Prepare Your SD Card:** Extract the zip file onto a Fat32 formatted SD card and insert it into your GRiSP2 board. +- **Initiate Automatic Registration:** Connect your board to the internet via an ethernet cable. It will automatically link to your GRiSP.io account, which you can verify on the GRiSP Manager. + +## Option 2: Manual Linking (For Advanced Users) + +If you prefer a hands-on approach or need custom setup: + +1. **Project Setup:** Follow the [GRiSP Wiki](https://github.com/grisp/grisp/wiki) for instructions on creating and deploying your GRiSP2 application. Before proceeding, ensure `grisp_io` is added to your project's dependencies. This is a crucial step for manual linking. + + - **Optional Configuration:** To streamline the process, include the device_linking_token in your project's release configuration (`config/sys.config`): + ```erlang + [ + {grisp_io, [ + {device_linking_token, <<"your_token_here">>} + ]} + ]. + ``` + + This allows you to skip manually entering the token in the future. + +2. **Deploy Your Application:** After setting up, make sure your board is connected to the internet. You can verify that your board connected to GRiSP.io executing: + ```erlang + > grisp_io:is_connected(). + true + ``` + +3. **Manually Link Your Board:** Access the Erlang shell on your board. To link, execute: + ```erlang + > grisp_io:link_device(<<"your_unique_token">>). + ``` + Or, if your token is pre-configured in the environment, run: + ```erlang + > grisp_io:link_device(). + ``` + +4. **Check Registration Status:** A successfull request returns `{ok, <<"ok">>}`. Confirm your device's registration on the [GRiSP Manager](https://grisp.io/grisp-manager/) page. Your device should appear under the **Devices** section. :tada: + +### Troubleshooting: +`grisp_io:link_device/*` may fail with the following errors. +#### **Common Errors:** +- `token_expired`: regenerate one from the web page +- `invalid_token`: please double check you typed it correctly +- `token_undefined`: you called `grisp_io:link_device/0` without setting `device_linking_token` +- `disconnected`: check that your board can connect +- `device_already_linked`: please do not steal GRiSP boards :smirk: + if you need to unlink a GRiSP board see below... + + +## Need to Unlink a Device? + +We currently do not expose a public API to unlink a Device. Please reach out to us for assistance. + +If you encounter any problems or have questions, don't hesitate to contact [support](mailto:grisp@stritzinger.com). Happy coding! diff --git a/LINKING.md b/LINKING.md deleted file mode 100644 index 6557438..0000000 --- a/LINKING.md +++ /dev/null @@ -1,76 +0,0 @@ -# How To link your GRiSP2 Board to your GRiSP.io account - -## Get yourself a GRiSP.io device linking token - - -1. Login or Register on [GRiSP.io](https://grisp.io) -2. Request a new Linking Token on the [GRiSP Manager](https://grisp.io/grisp-manager/) web view -3. Use the user-friendly binary application or try to manually link your board as explained below - -## Use the grisp_auto_link binary package - -If you do not want to write code we provide a zip file that can be extracted on a Fat32 SD card. -This zip contains a deployed release of [grisp_auto_link](https://github.com/grisp/grisp_auto_link) application, -customized with your linking token. You then just need to put the SD card in your board and connect it with an ethernet cable to the internet. The application will connect the board for you and you will be able to see it in the GRiSP Manager web view. You will find the download button near your token on GRiSP Manager the webpage. - -## Manually link your board - -You are free to use the grisp_io API in your code or procede manually while connected by serial or remote shell to the erlang shell running on the board. - -1. Follow the [GRiSP Wiky](https://github.com/grisp/grisp/wiki) -to create your GRiSP2 application project and learn how to deploy - - - **Optional:** if you do not want to type the device_linking_token at runtime -you can add it to the application env variables in your release confi. (e.g. `config/sys.config`) -Copy in there the Linking Token you precedently generated on the web page. -``` -[ - {grisp_io, [ - {device_linking_token, <<"...">>} - ]} -]. -``` - -2. Follow the tutorial until you are able to deploy your app on the board. - - -By default grisp_io application connects on boot, it will keep tryng until it succedes. - -3. Make sure your board is able to connect to the internet -4. Connect via serial or remote_shell to the erlang shell on the board. -5. In the erlang shell: verify connection to GRiSP.io -``` - > grisp_io:is_connected(). - true -``` -6. Check if your board is registered or not. `pong` means that is already linked, -`pang` means that is not linked with any account. -``` - > grisp_io:ping(). - {ok, <<"pang">>} -``` -7. Send a linking request providing the Linking Token as binary argument in the call. -``` - > grisp_io:link_device(<<"my_long_and_unique_token">>). - {ok, <<"ok">>} -``` -- If you did set the token in the grisp_io env you can just use the shorter call. -``` - > grisp_io:link_device(). - {ok, <<"ok">>} -``` -8. Checkout [GRiSP Manager](https://grisp.io/grisp-manager/) device view to spot -your device. Now you will be able to monitor its activities from GRiSP.io - -Possible errors during linking: -- `token_expired`: regenerate one from the web page -- `invalid_token`: please double check you typed it correctly -- `token_undefined`: you called `grisp_io:link_device/0` without setting `device_linking_token` -- `disconnected`: check that your board can connect -- `device_already_linked`: please do not steal GRiSP boards :smirk: - if you need to unlink a GRiSP board see below... - -## Unlink a Device - -We currently do not expose a public API to unlink a GRiSP device. -If you need to unlink your board please contact: grisp@stritzinger.com diff --git a/rebar.config b/rebar.config index 3779c70..5a1e4bd 100644 --- a/rebar.config +++ b/rebar.config @@ -35,7 +35,7 @@ {extras, [ {"CHANGELOG.md", #{title => "Changelog"}}, {"README.md", #{title => "Overview"}}, - {"LINKING.md", #{title => "Device Linking"}}, + {"Board_Registration.md", #{title => "Board Registration"}}, {"LICENSE", #{title => "License"}} ]}, {main, "README.md"},