Golioth client Python library

This is a basic Golioth client library.

Install

This package is not yet published in PyPI. It can be installed directly from GitHub with the following command:

pip install git+https://github.com/golioth/python-golioth-tools@v0.6.5

Alternatively you can clone this repo and then run the following at the repo root:

pip install .

If you plan on editing / development of this package, consider using -e (--editable) parameter when installing it.

CLI

This package installs with CLI script called golioth. There are various commands implemented, which can be listed by using --help argument such as:

$ golioth --help
Usage: golioth [OPTIONS] COMMAND [ARGS]...

Options:
  -c, --config-path PATH  Path to goliothctl configuration
  --api-key TEXT          Api key
  --help                  Show this message and exit.

Commands:
  call         Call RPC method on device.
  certificate  Certificates related commands.
  device       Device related commands.
  logs         Logging service related commands.
  settings     Settings service related commands.

or for each subcommand like golioth logs --help.

Configuration

golioth CLI tool is just complementary tool to goliothctl (for now). Hence it uses it's configuration format. goliothctl default configuration file is at ~/.golioth/.goliothctl.yaml.

Default hosted (api.golioth.io) backend

golioth CLI can reuse credentials stored in goliothctl's ~/.golioth/.goliothctl.yaml configuration file. Make sure that goliothctl is already logged in with:

$ goliothctl login

If that is true, then golioth CLI will reuse such access token for authorization.

Default hosted (api.golioth.io) backend - using API key

An alternative approach is to use generated API keys. This can be achieved with goliothctl apikeys create:

$ goliothctl apikeys create
id:"SOME_ID"  key:"MY_KEY" type:API_KEY

or an existing key can be listed at any point with:

$ goliothctl apikeys list
id:"SOME_ID"  key:"MY_KEY"  policy_id:"SOME_POLICY_ID"  roles:"apikey" type:API_KEY

Then to use such API key use --api-key MY_KEY. As an example, invoke following command to list devices with Python CLI tool:

$ golioth --api-key MY_KEY device list
[
    {
        'id': 'device-id',
        'hardwareIds': ['device-hardware-id'],
        'name': 'device-name',
        'createdAt': '2022-11-15T14:40:48.243Z',
        'updatedAt': '2022-11-15T14:40:48.243Z',
        'tagIds': [],
        'data': None,
        'lastReport': None,
        'status': '-',
        'metadata': {'status': '-', 'lastReport': None, 'lastSeenOnline': None, 'lastSeenOffline': None, 'lastSettingsStatus': None},
        'enabled': True
    }
]

Self-hosted backend

With self-hosted backend there is no API key authentication required by default. However a separate configuration file might be useful with following contents:

apiurl: http://localhost:9090
projectid: one

assuming that self-hosted Golioth server runs on localhost using port 9090. project: one defines default project to be used. Such configuration is exactly what is generated by running:

goliothctl --apiUrl "http://localhost:9090" config set projectId one

when using goliothctl. Above configuration file can be used both with goliothctl -c myconfig.yaml or with this package CLI golioth -c myconfig.yaml.

Example - list last 10 log entries

$ golioth logs tail -n 10
[2022-10-27 16:46:06.400946+00:00] <ERR> golioth_logging Err: 1928
[2022-10-27 16:46:11.411925+00:00] <ERR> golioth_logging Err: 1929
[2022-10-27 16:46:16.422354+00:00] <INF> golioth_logging Counter hexdump
[2022-10-27 16:46:21.431396+00:00] <DBG> golioth_logging Log 2: 1931
[2022-10-27 16:46:26.441428+00:00] <DBG> golioth_logging Log 2: 1932
[2022-10-27 16:46:31.450970+00:00] <DBG> golioth_logging Debug info! 1933
[2022-10-27 16:46:36.462141+00:00] <INF> golioth_logging Counter hexdump
[2022-10-27 16:46:41.470900+00:00] <WRN> golioth_logging Warn: 1935
[2022-10-27 16:46:46.481341+00:00] <DBG> golioth_logging Log 2: 1936
[2022-10-27 16:46:51.491666+00:00] <WRN> golioth_logging Warn: 1937

Example - list last 15 log entries with "Zephyr shell" format

$ golioth logs tail -n 15 --format zephyr
[02:41:54.420,000] <dbg> golioth_logging: func_1: Log 1: 1939
[02:41:59.430,000] <inf> golioth_logging: Counter hexdump
                                          94 07 00 00
[02:42:04.440,000] <wrn> golioth_logging: Warn: 1941
[02:42:09.450,000] <inf> golioth_logging: Counter hexdump
                                          96 07 00 00
[02:42:14.460,000] <dbg> golioth_logging: main: Debug info! 1943
[02:42:19.470,000] <wrn> golioth_logging: Warn: 1944
[02:42:24.480,000] <err> golioth_logging: Err: 1945
[02:42:29.490,000] <err> golioth_logging: Err: 1946
[02:42:34.500,000] <err> golioth_logging: Err: 1947
[02:42:39.510,000] <dbg> golioth_logging: func_1: Log 1: 1948
[02:42:44.520,000] <dbg> golioth_logging: func_1: Log 1: 1949
[02:42:49.530,000] <dbg> golioth_logging: func_2: Log 2: 1950
[02:42:54.540,000] <err> golioth_logging: Err: 1951
[02:42:59.550,000] <wrn> golioth_logging: Warn: 1952
[02:43:04.560,000] <inf> golioth_logging: Counter hexdump
                                          a1 07 00 00

Example - monitor new log entries in realtime

$ golioth logs tail -n 0 -f
[2022-10-27 16:48:51.731504+00:00] <DBG> golioth_logging Log 2: 1961
[2022-10-27 16:48:51.731665+00:00] <WRN> golioth_logging Warn: 1961
[2022-10-27 16:48:51.730948+00:00] <DBG> golioth_logging Debug info! 1961
[2022-10-27 16:48:51.731932+00:00] <ERR> golioth_logging Err: 1961
[2022-10-27 16:48:51.731163+00:00] <DBG> golioth_logging Log 1: 1961
[2022-10-27 16:48:51.732176+00:00] <INF> golioth_logging Counter hexdump
[2022-10-27 16:48:56.741363+00:00] <WRN> golioth_logging Warn: 1962
[2022-10-27 16:48:56.740810+00:00] <DBG> golioth_logging Log 1: 1962
[2022-10-27 16:48:56.740592+00:00] <DBG> golioth_logging Debug info! 1962
[2022-10-27 16:48:56.741046+00:00] <DBG> golioth_logging Log 2: 1962
[2022-10-27 16:48:56.741875+00:00] <INF> golioth_logging Counter hexdump
[2022-10-27 16:48:56.741612+00:00] <ERR> golioth_logging Err: 1962

Example - call method multiply (implemented in samples/rpc/)

$ golioth call -d nrf52 multiply 3 1.5
{'value': 4.5}