GRiSP.io Client Library for GRiSP. This library enables secure communication between your GRiSP2 board and the GRiSP.io services using Mutual TLS (mTLS). To get started, add this application as a dependency in your GRiSP2 project.
grisp_updater_grisp2,
make sure to add grisp_updater_grisp2 as a dependency in your project as well.
- grisp_connect
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.
Add
{dep, [{grisp_connect, "1.0.0"}]}to your rebar.config file.
If you still need to link your device configure the device linking token in your sys.config:
[ {grisp_connect, [
{device_linking_token, <<"...">>}
]}].You can find your device linking token on GRiSP.io/grisp_manager under "How to Link a Device/Option 2: Manual Linking (Ethernet / Wifi)".
You can also skip this configuration and insert the token manually later.
> grisp_connect:is_connected().
true
> grisp_connect:ping().
{ok,<<"pong">>}> grisp_connect:link_device(<<"...">>).Or, if your token is configured in the environment:
> grisp_connect:link_device().grisp_connect:link_device may fail with the following errors.
Common Errors:
token_expired: regenerate one from the web pageinvalid_token: please double check you typed it correctlytoken_undefined: you calledgrisp_connect:link_device/0without settingdevice_linking_tokendisconnected: check that your board can connectdevice_already_linked: please do not steal GRiSP boards 😏 if you need to unlink a GRiSP board see below...
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. Happy coding!
This option is set to true as default. Set it to false to prevent automatic connection to GRiSP.io on boot.
In such case the state machine that maintains the connection can be started manually using grisp_connect_client:connect().
An optional NTP client can be started using option {ntp, true}.
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.
The default NTP servers to use can be overridden by setting the grisp_connect
option: {ntp_servers, ["ntp1.server.foo", "ntp2.server.foo"]}. For every NTP
requests, a server address will be picked randomly from the list.
The default refresh period in seconds can be overridden by setting the
grisp_connect option: {ntp_refresh_period, 1024}.
Accepts an integer that represents time in milliseconds, default value is 5_000.
Allows to tweak the timeout of each API request going through the websocket.
Accepts an integer that represents time in milliseconds, default value is 60_000.
Allows to tweak the timeout between expected ping frames from the server.
If the timeout is exceeded, the socket is closed and a new connection is attempted.
Accepts an integer that represents time in milliseconds, default value is 2_000.
Sets the intervall between each log batch dispatch to grisp.io.
Accepts an integer that represents the maximum number of logs that can be batched together, default value is 100.
To be able to connect securely with our backend you need to correctly setup certificates and keys access through grisp_keychain enviroment.
This can variate greatly depending on the platfrom and usecase of your deployment. To correctly setup a new project, please use our rebar3_grisp plugin.
TLS settings are fetched through the grisp_keychain app. This app defaults to use a simple file filesystem access and requires additional informations to locate the certificates.
In this example we use grisp_keychain alone. Relying on free filesystem access.
We are using certifi CAs and a device certificate and key we have in priv.
% Example sys.config
[
...
{grisp_keychain, [
{api_module, grisp_keychain_filesystem}, % default
{tls_server_trusted_certs_cb, {certifi, cacerts, []}},
{client_certs, {priv, myapp, "certs/device.pem"}},
{client_key, {priv, myapp, "certs/device.key"}}
]}
]For production usecases we are developing backends to securely access certificates and keys.
For example: if you are using GRiSP2 you will need grisp_cryptoauth to use secrets held by the secure element. See the grisp_cryptoauth TLS options to customize them. A simple configuration that uses secure element certs and certifi as CA provider will look like this:
% Example sys.config
[
...
{grisp_keychain, [
{api_module, grisp_cryptoauth}
]},
{grisp_cryptoauth, [
{tls_server_trusted_certs_cb, {certifi, cacerts, []}}
]}
]Note: we do not depend on certifi, make sure it is added to your deps in case you want to use it.
grisp_connect will ignore cert_expired errors during certificate path validation. This should only be used for development. Default is false.
% Example sys.config
[
...
{grisp_keychain, [
...
{allow_expired_certs, true},
...
]}
]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.
If you want to see ALL logs, even from applications that boot before grisp_connect, you need to add the log handler in the kernel configuration and disable the one defined in the grisp_connect application configuration. This involves changing the kernel and grisp_connect app configuration settings in your sys.config file.
You can copy paste these settings:
% sys.config
[
{kernel, [
{logger_level, notice},
{logger, [
{handler, default, logger_std_h, #{
level => notice,
filter_default => log,
filters => [
% Filter out supervisor progress reports so TLS certificates
% are not swamping the console if the level is set to info...
{disable_progress, {fun logger_filters:progress/2, stop}}
]
}}
{handler, grisp_connect_log_handler, grisp_connect_logger_bin, #{
level => notice,
filter_default => log,
formatter => {grisp_connect_logger_bin, #{}},
filters => [
% Filter out supervisor progress reports so TLS certificates
% are not swamping grisp.io if level is set to info...
{disable_progress, {fun logger_filters:progress/2, stop}}
]
}
}
]}
]},
{grisp_connect, [
% Disable the log handler defined in grisp_connect application default
% configuration, as it was explicitly started in kernel configuration
% in order to catch the log entries before grisp_connect is started.
{logger, []}
]}
]}
].To simplify the log on the device while still sending full log reports to griso.io, use grisp_connect_log log formatter with single-line in the default log handler:
{handler, default, logger_std_h, #{
level => notice,
formatter => {grisp_connect_log, #{
legacy_header => false,
single_line => true,
description_only => true
}},
filter_default => log,
filters => [
% Filter out supervisor progress reports so TLS certificates
% are not swamping the console if the level is set to info...
{disable_progress, {fun logger_filters:progress/2, stop}}
]
}}
Add an entry in your local hosts file so the domain www.seawater.local points to your local development server.
Make sure you have the proper certificates under prinv/server and priv/client. Refer to the backend private docs on how to generate the certificates.
Start a local development shell:
rebar3 as local shell
Run tests:
rebar3 ct
To run the tests it might be necessary that you clean out the _build folder in case you compiled with another profile before:
rm -rf _build
Add an entry in the grisp hosts file so the domain www.seawater.local points to your local development server.
e.g. using ifconfig command (MacOS and older linux):
echo "$(ifconfig | grep 'inet ' | grep -v 127.0.0.1 | awk '{ print $2 }' | head -n 1) www.seawater.local" >> grisp/default/common/deploy/files/etc/hosts
]
e.g. using ip command (Newer linux):
echo "$(ip addr show | grep 'inet ' | grep -v 127.0.0.1 | awk '{print $2}' | cut -d/ -f1 | head -n 1) www.seawater.local" >> grisp/default/common/deploy/files/etc/hosts
To deploy the release, configure rebar3_grisp's deploy configuration in rebar.config and then run:
rebar3 as dev grisp deploy
To deploy on GRiSP hardware for production, configure rebar3_grisp's deploy configuration in rebar.config and then run:
rebar3 as prod grisp deploy