rrivctl commands

Overview

This document defines a set of commands offered by the rrivctl command line interface to configure devices compliant with the rriv hardware serial interface.

Command documentation conventions:

• <required>

• [optional]

• {...} json blob

RRIV compatible devices are configured using declarative commands as

<command> <object> {key: value, key:value}

or

{command: <command>, object: <object>, key: value, key: value}

Commands common to most objects are as follows:

set

Creates or updates a resource.

get

Gets current parameters of a resource

remove

Removes a resource

list

Lists all resources of a particular type

calibrate

Performs an (optionally implemented) calibration on a resource

Datalogger

set datalogger

Synopsis

set datalogger [option] <property> <value>

Description

Sets parameters relevant to the entire datalogger. These may be set individually, or read from a json file to set multiple parameters in one command invocation.

Setting a parameter individually: set datalogger logger_name water2

Use the -f option to load multiple parameters from a stored file: set datalogger -f configurations/stored_datalogger.json

All datalogger parameters

Parameter	Data Type	Description
logger_name	string	a name for the logger
site_name	string	site code
deployment_identifier	string	identify a deployment
interactive_logging_interval	int	seconds to wait between measurements during interactive logging
sleep_interval	int	minutes between wakes while deployed
start_up_delay	int	minutes to wait between wakeup and measurement sensor initialization
bursts_per_cycle	int	number of bursts to run during each measurement cycle
burst_interval	int	minutes between burst cycle initialization
enable_telemetry	bool	enable or disable LoRaWAN telemetry
mode	string	changes the mode the datalogger is in. normally called as a single parameter command

Datalogger modes

Mode	Description
interactive	Moves to interactive mode, which allows configuration
field	Moves immediately to deployment, sleeps the devices and awaits the next measurement cycle

Example datalogger configuration file

{	
	"logger_name" : "my device",
	"site_name" : "OAK2:,
	"deployment_identifier" : "X12",
	"interactive_logging_interval" : 10,
	"sleep_interval" : 1,
	"start_up_delay" : 1,
	"bursts_per_cycle" : 10,
	"burst_interval" : 2,
	"enable_telemetry" : true
}

get datalogger

Synopsis

rrivctl get datalogger

Description

Get datalogger configuration. This command returns all datalogger configuration parameters as a JSON blob.

Sensor

Commands to configure installed sensors.

set sensor

Synopsis

 set sensor <sensor_id> -f <FILE>

Description

Creates or updates a sensor configuration. If a sensor with the provided id is currently configured, it is updated. Otherwise, a new sensor configuration is created.

The JSON blob can contain some or all configuration parameters for indicated sensor driver. "type" specifies the kind of sensor installed and its corresponding driver, and is required when creating a new sensor.

Example (for generic analog sensor):

{	
	"type":"generic_analog",
	"burst_size":10,
	"adc_select":"internal",
	"sensor_port":1,
}

get sensor

Synopsis

get sensor <sensor_id>

Description

Get a sensor configuration, corresponding to the id. When called with a parameter argument, returns just the parameter requested. Otherwise returns the entire JSON blob.

If id is not specified, returns a JSON array containing all sensor configurations.

get sensor also supports an aggregate property 'calibration' which returns all calibration parameters only

{
	'high_val': 5,
	'low_val': 2,
	'high_read': 2000,
	'low_read' : 300,
	'm': 2,
	'b': 0.2
}

remove sensor

Synopsis

remove sensor <sensor_id>  

Description

Remove the sensor configuration matching the corresponding id

list sensor

Synopsis

list sensor 

Description

List all configured sensors

calibrate sensor

Synopsis

calibrate sensor <id> <subcommand> [params...]

Description

Subcommands to perform calibration steps on individual sensors. These subcommands are used to set, view, and remove calibration points, and to perform the fit as implemented by the sensor driver. The basic workflow is to add the number of calibration points required by the sensor driver, and then perform a fit.\

Example calibration workflow

rrivctl calibrate sensor TEMP point 12.3   # set a calibration point at 12.3°  
rrivctl calibrate sensor TEMP point 25.3   # set a calibration point at 25.3°
rrivctl calibrate sensor list              # list calibration points        
rrivctl calibrate sensor fit               # perform the calibration fit
rrivctl watch                              # watch outputs on the console

Subcommand: point

Sets a calibration point

calibrate sensor <sensor_id> point <value>

Subcommand: list

Lists all the calibration points currently registered

calibrate sensor <sensor_id> list

Subcommand: fit

Calculates fit based on calibration points that have been registered, and stores the fit.

calibrate sensor <sensor_id> fit 

Board

The commands access features of the board itself and firmware metadata

This consists of three types of commands

• get/set commands in the standard that report hardware properties.

• warranty/license shorthands for human operators on the serial connection

• debugging shorthands for human developers on the serial connection

This is a custom namespace at the top level.

get board

Synopsis

rrivctl get board [version,epoch]

Description

Get the parameters specific to the board

Parameter	Data Type	Description	Response
epoch	integer	Epoch time	seconds (integer)
version	json	board and firmware versions	{ "hv":"0.4.2", "fv":firmware_version, "br":branch, "ref":gitref }

set board

Synopsis

rrivctl set board epoch <epoch_time>

Description

Set real time clock epoch time

Device

Commands relevant to the entire device

get device

Get details about the device, including unique identifiers and hardware assignment status.

rrivctl get device

{
"gpio_bound": {
"gpio1": "",
"gpio2": "",
"gpio3": "disabled",
"gpio4": "disabled",
"gpio5": "",
"gpio6": "",
"gpio7": "",
"gpio8": "",
"usart": ""
},
"serial_number": "A0000",
"uid": "FF325D93737554657136931"
}

Watch

watch

Synopsis

rrivctl watch [OPTIONS]

Description

Watch data output and optionally log to an output file.

Logs output from measurement cycle and telemetry events to the console. Exit watch mode using Control-C. Note that other commands cannot be sent to the device while watch is running.

Watch output is in CSV format and contains all sensor values currently configured to measure.

Options:

-d, --debug enabled debugging output (default: false) -f, --file name of a file to output sensor data to -p, --path <serial_path> serial path of the RRIV device --project a project name for organizing watch files\

Connect

connect

Synopsis

rrivctl connect

Description

Opens the USB serial connection with the rriv board and firmware.

Cheat Sheet

rrivctl connect

rrivctl get datalogger

rrivctl set datalogger <parameter> <value>
 
rrivctl list sensor

rrivctl set sensor <sensor_id> -f <filename.json>
rrivctl get sensor <sensor_id>

rrivctl remove sensor <sensor_id>

rrivctl calibrate sensor <sensor_id> point <value>

rrivctl calibrate sensor <sensor_id> list

rrivctl calibrate sensor <sensor_id> fit

rrivctl get board version

rrivctl get board epoch

rrivctl set board epoch <epoch_time>



rrivctl get device 

rrivctl watch

Library Subcommand Set

library save

Synopsis

rrivctl library save <sensor|datalogger|device> <library_name> [source_reference]
      [-s|--sensor-id sensor_id] 
      [-f|--filename filename.json]
      [--update]

Description

Saves a sensor, datalogger, or full device configuration with a name for future reuse. The first argument to the save subcommand is configuration type, which determines the type of configuration to save.

The configuration to be saved can read from several sources: a json file, the attached device, the history of any device in the rriv database. When the -f option is specified, the configuration is loaded and saved from the referenced file, without any changes to any attached device. When -f is not specified, configuration is read from a device attached over USB. Configuration type sensor requires the -s option if -f is not specified, in order to indicate which sensor configuration to read from the attached device.

Libraries are automatically versioned when additional saves are processed against the same library name. The --update flag must be specified to save to a pre-existing tag.

Library names are unique to the user, and the same library name cannot be used in multiple configuration types.

Options

--attached

Read configuration from the currently attached device. This option is the default behavior.

-d, --device-id

Get the configuration to tag from device other than the currently attached device.

-f, --filename

Specify a json file containing configuration to save.

-s, --sensor_id

Specify the sensor id, required when reading sensor configuration from a device over USB

-t, --time YYYY:MM:DD[-HH:MM}

Specify the timestamp for a configuration stored in history for either the currently attached device or another device the user has access to in the rriv database, and tag this historical configuration with the specified tag.

library apply

Synopsis

rrivctl library apply <sensor|datalogger|device> <library_name[:version]> 
      [-s|--sensor-id sensor_id]

Description

Applies a saved library configuration to the attached device, as specified by saved library name and an optional version. The first argument to the save subcommand is configuration type, which indicated the type of configuration to look up in the library.

Repositories have an optional owner prefix, as [owner:]<library)name>, which specified the owner of the repository. When owner is not specified, the current user is used as the owner.

Options

-s, --sensor_id

Optionally a sensor id to create or update when applying a tagged sensor configuration. If this option is not set, then a sensor id is automatically generated.

library publish

Synopsis

rrivctl library publish <library_name> 

Description

Makes a sensor, datalogger, or device configuration available for use by other users via the library apply subcommand. The library to publish must be a pre-existing saved library in the user's account. Versions are computed automatically, as monotonically increasing integers.

Options

-n, --note

Store a descriptive note with the published version

library list

Synopsis

rrivctl library list <sensor|datalogger|device> [library_name] 
     [--filter filter_string]

Description

List contents of configuration tags and repositories.

When sensor, datalogger, or device configuration type list is specified, then all libraries belonging to the current user are displayed. The format for display is: | configuration type | library_name | note |

When library name is specified, then all library versions and their corresponding notes are listed.

Libraries have an optional owner prefix, as [owner:]<library_name>, which specified the owner of the repository. When owner is not specified, the current user is used as the owner.

Options

-f, --filter filter_string Filter library names for a specified string

library get

Synopsis

rrivctl library get <sensor|datalogger|device> <library_name[:version]>

Description

Query and display library configurations, but do not apply to any attached device.

The first argument specifies the configuration type.

The second argument is the name of the library, with an optional version number. If the version number is not specified, then the latest version is shown.

Output of history get may be redirected to a file in order to store the configuration as a json file, for instance rrivctl library get datalogger wetland > wetland_datalogger.json

History Subcommand Set

history list

Synopsis

rrivctl history list <sensor|datalogger|device> 
        [-d,--device-id device_id] [-s,--sensor-id sensor_id]
        [-n entries]

Description

List history of configuration changes for sensor, datalogger, or device configurations.

Output is tabluar, showing the time of the configuration change followed by the configuration changes made.

Options

-d, --device-id

The device to list configuration history for. If this option is not specified then the history of the currently attached device is listed.

-n

The number of entries to show at once.

-s, --sensor_id

Specify the sensor id, required when listing sensor configuration history

history get

Synopsis

rrivctl history get <sensor|datalogger|device> <YYYY:MM:DD>[THH:MM]
        [-d,--device-id device_id] [-s,--sensor-id sensor_id]
      

Description

Show the full sensor, datalogger, or device configuration on a given date and time

Specifying a date is mandatory, however time is optional. If a time is not specified then the configuration display should be the most recent configuration before the the start of the specified date.

Output of history get can be redirected to a file in order to store the configuration as a json file, for instance rrivctl history get device wetland 2024-11-01T12:00 > desert_device.json

Options

-d, --device-id

The device to list configuration history for. If this option is not specified then the history of the currently attached device is listed.

-s, --sensor_id

Specify the sensor id, required when listing sensor configuration history

history apply

Synopsis

rrivctl history apply <sensor|datalogger|device> <YYYY:MM:DD>[THH:MM] [-d,--device-id device_id] [-s,--sensor-id sensor_id]
      

Description

Apply the full sensor, datalogger, or device configuration from a given date and time to the currently attached device. Historical configurations to apply can be queried from either the currently attached device or any other device the user has access to.

Options

-d, --device-id

The device history to query to get the configuration to apply. If this option is not specified then the history of the currently attached is used to query the configuration to apply.

-s, --sensor_id

Specify the sensor id, required when listing sensor configuration history