Terminal Documentation

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

• RS-232 (SYS connector pins)
• USB (optional)

Preface

Connection Details

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

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:

• lowercase letters indicate a keyword
• uppercase letters indicate a variable
• square brackets indicate an optional keyword or variable
• the [...] character sequence indicates an unlimited number of variables
• optional keywords and variables are colored in grey
• required variables are bold & white

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

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.

• There is no feature parity. The REST API is the primary configuration method for the sensor. Not all features implemented in the REST API are available via the serial interface.
• Some commands like samples stream implement parameters that don’t match the corresponding API endpoint. This may be the case if the behaviour controlled by these parameters is specific to the HTTP or serial protocol.
• While the REST API uses plural resources names like matchers the serial protocol uses singular command names (in this case matcher).
• There is no general /defaults API endpoint implementation available on the serial interface. Instead commands like matcher default set hold_time implement a more fine-grained access.

Command Reference