Terminal Documentation

The text-based terminal is accessible via the following interfaces of the sensor:

Preface

Connection Details

The sensor uses the following configuration to communicate via the serial interface:

Baud Rate 19200 (RS-232)
Data Bits 8
Stop Bits 1
Parity None
Line Feed 0x0A/LF/\n
Encoding UTF-8

Syntax

The serial console uses color, markup, and font weight to outline how commands can and should be used. As not all terminals support color and font formatting rules you may only see the described markup in your terminal.

Output is formatted as following:

Please mind that all input is case-sensitive. matcher select is not the same as MATCHER SELECT.

matcher select MATCHER set tolerance SHAPE [LIMITS] - set a matcher's tolerance

In the example above the syntax expresses the following command structure:

  1. a required keyword "matcher"
  2. a required keyword "select"
  3. a required variable "MATCHER"
  4. a required keyword "set"
  5. a required keyword "tolerance"
  6. a required variable "SHAPE"
  7. an optional variable "LIMITS"

Output Formats & Message Parsing

When used in automation it’s recommended to use the JSON output format. You can switch between output formats with the set output-format command. The available formats are json and human. Please be advised that human output format is subject to change and is currently not recommended for parsing.

Once a command is executed it will output one or more data packets. Independent of the output format these packets end with a specific two-byte sequence. The first byte indicates if the packet was generated by a successful command and is either 0x20 in case of success or 0x07 in case of a failure. The second byte marks the end of the packet and is guaranteed to be 0x00, the ASCII NUL character.

Nomenclature

The serial interface uses a set of names and identifiers that are closely modelled after the sensors REST API.

UUID

UUID is short for "Universally unique identifier" and is a 36-characters long character sequence with 5 alpha-numeric groups separated by dashes. Most collections use a UUID as unique keys for their items. UUIDs used by the serial interface and the underlying REST API are UUIDv4 as specified in RFC 4122.

Detectable position

The commands for adding and editing a detectable use a parameter called the position.

This value refers to the color property in the REST API and describes the three-dimensional location of the color in the currently activate colorspace. The format regex is ^(\d+(?:\.\d*)?),(\d+(?:\.\d*)?),(\d+(?:\.\d*)?)$ (Example: 3.14,7.6,8).

Common Patterns

Some tasks in the serial interface share common or similar behaviours. These recurring patterns are outlined here.

Collections and the select keyword

Collections are a set of items of a specific type that the sensor controls. Most collections handled by the sensor use a UUID as unique key, by which they can be referenced.

In the context of the serial interface collections can easily be spotted by the use of the "select" keyword followed by a variable as part of the command syntax. Even though collections usually use a UUID or another unique key as identifier, the variable can take other arguments. You may also use a list index, as defined by the corresponding list command for this collection or the special index '-1' to reference the last item of this type that you’ve created.

Property Commands using show [PROPERTY]

Most commands that display detailed information on an object (may it be a collection item or any other resource) using the the show keyword support the output of any of the attributes individually. The help command for the command will show you the allowed choices for the property value.

Differences compared to the REST API

The serial protocol is based on the REST API but there are some differences that are outlined in this section.

Command Reference

access command
handle security related tasks like logins and session management access login USERNAME [PASSWORD] - login with username and password to access privileged commands access logout - logout and invalidate the current session access session - show current session information

device command
device [show] [PROPERTY] [PROPERTY]: id | model_key | model_name | variant | vendor_key | vendor_name

firmware command
The sensor firmware provides the connectivity of the sensor and its services, as well as the functionality of sensor backend. firmware [version] - Show the current firmware version. firmware recovery [show] [PROPERTY] - show information about the recovery firmware [PROPERTY]: channel | created_on | id | name | version firmware recovery restore - Restore the system from the recovery image. All settings are reset to their defaults. firmware recovery upgrade - Store the currently running firmware image as a recovery image. You may use this operation after verifying a successful firmware upgrade.

help command
List and describe all available commands. help [COMMAND]

keypad command
The keypad provides local access to most basic sensor actions. keypad [show] [PROPERTY] - Show the keypad status. [PROPERTY]: lock keypad lock [STATE] - Change the state of the keypad lock mechanism.

matcher command
A matcher specifies the sensor behaviour based on the sensor input. A matcher contains multiple detectables (colors) and the desired sensor behaviour (e.g. output states and hold time) that should be applied when one of the colors is detected. matcher [list] - show the list of configured matchers for the detection profile matcher add [OUTPUT_PATTERN] - add a matcher to the detection profile matcher remove all - remove all matchers matcher select MATCHER [show] [PROPERTY] - show detailed information about a matcher [PROPERTY]: hold_time | name | num_detectables | output_pattern | reset_output_after_hold_time_expired | signal_color | tolerance | uuid matcher select MATCHER remove - remove a single matcher matcher select MATCHER set name NAME - set a matcher's name matcher select MATCHER set hold_time DURATION - set a matcher's hold time matcher select MATCHER set output_pattern BITMASK - set a matcher's output bitmask matcher select MATCHER set tolerance SHAPE [LIMITS] - set a matcher's tolerance SHAPE: One of the shapes defined by the API. box | cylinder | infinite | sphere [LIMITS]: A string describing the limits of the tolerance (e.g. "2r" for a sphere, "4h/6r" for a cylinder, or "1/2/3" for a box). Optional for infinite, but required for every other shape. Whenever a new matcher is created a few properties are set to predefined default values. You can change these defaults to your liking in order to reduce the number of changes needed afterwards. matcher default [show] [PROPERTY] - Display matcher default values [PROPERTY]: hold_time | tolerance matcher default set hold_time DURATION - set the default hold time for new matchers matcher default set tolerance SHAPE [LIMITS] - set the default tolerance for new matchers SHAPE: One of the shapes defined by the API. box | cylinder | infinite | sphere [LIMITS]: A string describing the limits of the tolerance (e.g. "2r" for a sphere, "4h/6r" for a cylinder, or "1/2/3" for a box). Optional for infinite, but required for every other shape. Multiple detectables can belong to a matcher. Each detectable represents a position within the currently active colorspace. matcher select MATCHER detectable [list] - List all detectables belonging to a matcher. matcher select MATCHER detectable remove all - Remove the detectables belonging to a matcher. matcher select MATCHER detectable add [POSITION] - Add a detectable to a matcher. Sample the current detectable, if no position is given. [POSITION]: A position in the current color space. Expected format: 23.918,6,17.29113 matcher select MATCHER detectable select DETECTABLE [show] [PROPERTY] - show detailed information about a detectable [PROPERTY]: matcher | position | rgb | uuid matcher select MATCHER detectable select DETECTABLE remove - Remove a single detectable from a matcher. matcher select MATCHER detectable select DETECTABLE set position POSITION - Modify the detectable's position in the colorspace. POSITION: A position in the current color space. Expected format: 23.918,6,17.29113

network command
The network configuration allows the use of network-based sensor features (e.g. API or the web interface). network [list] - Show the connection state and active addresses of all network interfaces. network reset - Reset the network configuration to its factory default. network select INTERFACE [show] [PROPERTY] - Show the connection state and active addresses of a network interface. [PROPERTY]: ipv4_addresses | ipv4_config | ipv6_addresses | ipv6_config | link | mac | name network select INTERFACE set ipv4 dhcp - Request a dynamically assigned IP address (via DHCP) for a network interface. network select INTERFACE set ipv4 static ADDRESS [GATEWAY] - Define a static IPv4 address for the network interface. network select INTERFACE set ipv4 disabled - Disable IPv4 connectivity for the network interface. network select INTERFACE set ipv6 auto - Enable IPv6 state-less auto network configuration (SLAAC) for the interface. network select INTERFACE set ipv6 dhcp - Request a dynamically assigned IP address (via DHCPv6) for a network interface. network select INTERFACE set ipv6 static ADDRESS [GATEWAY] - Define a static IPv6 address for the network interface. network select INTERFACE set ipv6 disabled - Disable IPv6 connectivity for the network interface.

repeat command
Conveniently execute a command multiple times (e.g. following changes of the color sampling results). repeat REPETITIONS DELAY [ARGUMENTS [...]] - Repeat a single command for a number of times with a given delay. You may stop execution with CTRL-C. REPETITIONS: number of repetitions, 0 for infinite DELAY: delay in seconds, 0 for no delay

sample command
Request sample results from the sensor. sample [show] [PROPERTY] - Show the current color sample. [PROPERTY]: color | detection | output_pattern | timestamp | trigger sample stream [COUNT] [FREQUENCY] - Retrieve a continuous stream of color samples from the sensor [COUNT]: number of records to retrieve, default 0 for infinite [FREQUENCY]: speed of samples in hertz, default infinite

sensor command
Sensor settings influence the sampling and processing of sensor signals. Changed settings may invalidate previously sampled detectables. sensor colorspace [show] - Show the currently configured colorspace. sensor colorspace list - List available colorspaces. sensor colorspace set COLORSPACE - Switch to a different colorspace. sensor autogain [SAMPLE_RATE] [TARGET_LEVEL] - Perform the autogain procedure in order to adjust the sensor to the current optical environment (distance, light intensity, target appearance). sensor white-reference reset - Reset the white reference to the factory default. The factory default works well with a commonly used optical path (fiber and optics). Use the factory default if a proper white reference target is not available. sensor white-reference sample - Sample a new white reference from the current target. The target should be neutral white. This may improve the calculation of absolute color values within the given colorspace.

set command
Change properties of the console interface. set echo STATE - enable/disable any output of prompts or typed text STATE: off | on set output-format FORMAT - switch the response output format FORMAT: human | json

system command
Interact with the system hosting the sensor. system settings reset - Reset all settings to their factory defaults. system hostname [show] - Show the system's hostname. system hostname set HOSTNAME - Define the hostname of the system. system timezones [list] - List all timezones supported by the system system time [show] [PROPERTY] - Show the system's current time settings [PROPERTY]: now | timezone system time set now TIME - Set the system's current time in ISO8601 format. system time set timezone TIMEZONE - Set the system's timezone system reboot - Reboot the device.