You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Update docs before releasing 1.0.0
* Version 1.0.0
* Fix Changelog
* Bump relx versions in profiles to 1.0.0
* Use OTP-27 for development deployments
* Adjust TLS option section
* User semver for rebar3 release
---------
Co-authored-by: Luca Succi <luca.succi@stritzinger.com>
-[Option 1. Use the `rebar3_grisp` plugin](#option-1-use-the-rebar3_grisp-plugin)
10
+
-[Option 2. Add `grisp_connect` Manually to your Application](#option-2-add-grisp_connect-manually-to-your-application)
11
+
-[Further Steps](#further-steps)
12
+
-[Check whether the board is connected](#check-whether-the-board-is-connected)
13
+
-[Link your Device to your GRiSP.io Account](#link-your-device-to-your-grispio-account)
14
+
-[Troubleshooting:](#troubleshooting)
15
+
-[Need to Unlink a Device?](#need-to-unlink-a-device)
16
+
-[Environment Options](#environment-options)
17
+
-[`connect`](#connect)
18
+
-[`ntp`](#ntp)
19
+
-[`ws_request_timeout`](#ws_request_timeout)
20
+
-[`ws_ping_timeout`](#ws_ping_timeout)
21
+
-[`logs_interval`](#logs_interval)
22
+
-[`logs_batch_size`](#logs_batch_size)
23
+
-[Custom TLS options](#custom-tls-options)
24
+
-[See all Logs on GRiSP.io](#see-all-logs-on-grispio)
25
+
-[Development](#development)
26
+
-[Local Development](#local-development)
27
+
-[Development on GRiSP Hardware](#development-on-grisp-hardware)
28
+
-[Production on GRiSP Hardware](#production-on-grisp-hardware)
29
+
30
+
5
31
Add this application as a dependency in your GRiSP2 project.
6
-
Your board will connect securely through Mutual TLS to the [GRiSP.io](https://grisp.io) services.
7
-
See the [Board Registration](https://github.com/grisp/grisp_connect/blob/main/Board_Registration.md) guide on how to start using your GRiSP2 board with GRiSP.io
32
+
Your board will connect securely using mTLS to the [GRiSP.io](https://grisp.io) services.
33
+
34
+
# Usage
35
+
36
+
## Option 1. Use the `rebar3_grisp` plugin
37
+
38
+
The `configure` method of the `rebar3_grisp` version >= 2.6.0 will add `grisp_connect` with the needed configurations to your GRiSP application. See [GRiSP Wiki/Use-your-GRiSP-2-board-with-GRiSP.io](https://github.com/grisp/grisp/wiki/Use-your-GRiSP-2-board-with-GRiSP.io).
39
+
40
+
## Option 2. Add `grisp_connect` Manually to your Application
41
+
42
+
Add
43
+
44
+
```erlang
45
+
{dep, [{grisp_connect, "1.0.0"}]}
46
+
```
47
+
48
+
to your `rebar.config` file.
49
+
50
+
If you still need to link your device configure the device linking token in your `sys.config`:
51
+
52
+
```erlang
53
+
[ {grisp_connect, [
54
+
{device_linking_token, <<"...">>}
55
+
]}].
56
+
```
8
57
9
-
## Application env options
58
+
You can find your device linking token on [GRiSP.io/grisp_manager](https://grisp.io/grisp_manager) under "How to Link a Device/Option 2: Manual Linking (Ethernet / Wifi)".
59
+
60
+
You can also skip this configuration and insert the token manually later.
61
+
62
+
# Further Steps
63
+
64
+
## Check whether the board is connected
65
+
66
+
```erlang
67
+
>grisp_connect:is_connected().
68
+
true
69
+
>grisp_connect:ping().
70
+
{ok,<<"pong">>}
71
+
```
72
+
73
+
## Link your Device to your GRiSP.io Account
74
+
75
+
```erlang
76
+
>grisp_connect:link_device(<<"...">>).
77
+
```
78
+
79
+
Or, if your token is configured in the environment:
80
+
81
+
```erlang
82
+
>grisp_connect:link_device().
83
+
```
10
84
11
-
### connect
85
+
### Troubleshooting:
86
+
`grisp_connect:link_device` may fail with the following errors.
87
+
88
+
**Common Errors:**
89
+
90
+
-`token_expired`: regenerate one from the web page
91
+
-`invalid_token`: please double check you typed it correctly
92
+
-`token_undefined`: you called `grisp_connect:link_device/0` without setting `device_linking_token`
93
+
-`disconnected`: check that your board can connect
94
+
-`device_already_linked`: please do not steal GRiSP boards :smirk:
95
+
if you need to unlink a GRiSP board see below...
96
+
97
+
### Need to Unlink a Device?
98
+
99
+
We currently do not expose a public API to unlink a Device. Please reach out to us for assistance.
100
+
101
+
If you encounter any problems or have questions, don't hesitate to contact [support](mailto:grisp@stritzinger.com). Happy coding!
102
+
103
+
# Environment Options
104
+
105
+
### `connect`
12
106
13
107
This option is set to `true` as default. Set it to `false` to prevent automatic connection to GRiSP.io on boot.
14
108
In such case the state machine that maintains the connection can be started manually using `grisp_connect_client:connect()`.
15
109
16
-
### ntp
110
+
### `ntp`
17
111
18
112
An optional NTP client can be started using option `{ntp, true}`.
19
113
Such client is disabled by default (`{ntp, false}`), and is not required to authenticate with GRiSP.io. The client sets the time using `grisp_rtems:clock_set/1`
20
114
21
-
### ws_request_timeout
115
+
### `ws_request_timeout`
22
116
23
117
Accepts an integer that represents time in milliseconds, default value is `5_000`.
24
118
Allows to tweak the timeout of each API request going through the websocket.
25
119
26
-
### ws_ping_timeout
120
+
### `ws_ping_timeout`
27
121
Accepts an integer that represents time in milliseconds, default value is `60_000`.
28
122
Allows to tweak the timeout between expected ping frames from the server.
29
123
If the timeout is exceeded, the socket is closed and a new connection is attempted.
30
124
31
-
### logs_interval
125
+
### `logs_interval`
32
126
33
127
Accepts an integer that represents time in milliseconds, default value is `2_000`.
34
128
Sets the intervall between each log batch dispatch to grisp.io.
35
129
36
-
### logs_batch_size
130
+
### `logs_batch_size`
37
131
38
132
Accepts an integer that represents the maximum number of logs that can be batched together, default value is `100`.
39
133
40
-
##API Usage example
134
+
### Custom TLS options
41
135
42
-
ok = grisp_connect:connect().
43
-
true = grisp_connect:is_connected().
44
-
{ok, <<pong>>} = grisp_connect:ping().
136
+
TLS settings are managed through the [grisp_cryptoauth TLS options](https://github.com/grisp/grisp_cryptoauth?tab=readme-ov-file#configuring-tls-options).
137
+
138
+
grisp_connect sets the following options as default values if no `tls_server_trusted_certs_cb` is setup. Refer to the `grisp_cryptoauth` README in case you want to overrride the default `certifi` CAs.
Once this app is started, it forwards all logs to GRiSP.io without the need of setting up anything. The only logs that we do not catch are the ones generated before `grisp_connect` boots.
49
153
If you want to see ALL logs, even from applications that boot before `grisp_connect`, you need to disable the default logger handler and set the grisp_connect handler as the default one. This involves changing the `kernel` and `grisp_connect` app configuration settings in your sys.config file.
50
154
51
155
You can copy paste these settings. Here we both swap the default logger handler with the grisp_connect logger handler and also request it to print logs to stdout.
156
+
52
157
```erlang
53
158
% sys.config
54
159
[
@@ -76,21 +181,9 @@ You can copy paste these settings. Here we both swap the default logger handler
76
181
]}
77
182
].
78
183
```
79
-
## Custom TLS options
80
184
81
-
TLS settings are managed through the [grisp_cryptoauth](https://github.com/grisp/grisp_cryptoauth?tab=readme-ov-file#configuring-tls-options) TLS options.
185
+
# Development
82
186
83
-
grisp_connect sets the folowing options as default values if no `tls_server_trusted_certs_cb` is setup.
0 commit comments