Page tree
Skip to end of metadata
Go to start of metadata

Some of the products by Zubax Robotics are equipped with a command line interface (CLI) exposed over a serial port (either a physical UART/RS232, or a virtual serial port over USB, or both) that provides access to device’s internal command shell. This page documents the properties that are shared by CLI-enabled Zubax products.

Normally you would want to read this article in the context of some particular product. Note that if there is a disagreement between this article and the documentation for a specific product, the product documentation should take precedence.

Physical layer

USB parameters

The USB device's vendor name is reported as "Zubax Robotics" or "Zubax". Products that feature a USB CLI use the standard profile USB CDC ACM, also known as VCP or "virtual serial port". USB devices of this class are presented by host OS as a regular serial port, e.g. COMx on Windows, /dev/ttyACMx on Linux.

Note that virtual serial ports are mostly indifferent to the settings of the physical layer, such as baud rate, parity, word size, etc, so when accessing a USB command shell they need not be configured explicitly, unless the documentation specific to your product instructs you otherwise.

USB CDC ACM devices can be used out of the box, without the need to install special drivers, with all major operating systems.

UART/RS232 parameters

Certain products have a physical serial port interface either alongside USB or instead of it. Unless specified otherwise in the product-specific documentation, the physical serial port has the following settings:

ParameterValue
Baud rate115200
Word size8
ParityNone
Number of stop bits1

Certain products allow the user to change the parameters of the serial port. Even if that is the case, by default all serial ports will be configured as shown above.

Command line interface

Parameters

The common CLI parameters are shown below. These are used by default by the vast majority of other hardware products in the industry, as well as by CLI client software such as picocom, minicom, PuTTY, and so on.

ParameterValue
Line endingCR+LF (\r\n)
Remote echoEnabled
Remote line editingEnabled

Identifying the connected device

All products by Zubax Robotics equipped with a command-line interface have one common CLI command: zubax_id. When executed without arguments, it prints a set of device's properties as a flat YAML dictionary (a list of colon-separated key/value pairs). Some of the properties are standard and are guaranteed to be reported by any Zubax product, they are documented below.

KeyValueExample
product_idReversed internet domain name suffixed with the product name in lowercase.'com.zubax.gnss'
product_nameHuman-readable product name. This name is typically used by humans when referring to the product.'Zubax GNSS'
sw_versionSoftware version string in the format <major>.<minor>.'1.12'
hw_versionHardware version string in the format <major>.<minor>.'3.0'
hw_unique_idGlobally unique 128-bit ID of the product encoded in Base64.'NP/TBUNXMDQ5RCJDAAAAAA=='

Most products also report additional properties. Some of them are documented in the following table.

KeyValueExample
sw_vcs_commit

Software version commit identifier from the version control system (VCS) that this version of the software was built from.

For example, short git commit hash.

266365646
sw_build_dateThe date when the current software was built in a human-friendly format.'Dec 9 2016'
bl_version
When the device is running the bootloader for purposes of upgrading its software, this field contains the version number of the bootloader.'2.1'
bl_vcs_commitSame as sw_vcs_commit, but for the bootloader.
266365646
bl_build_dateSame as sw_build_date, but for the bootloader.'Dec 9 2016'
mode

Used to indicate special operating modes. Possible values:

  • (not set) - normal operating mode.
  • 'bootloader' - the device is in the software upgrade mode.
'bootloader'
hw_signature

Certificate of authenticity (CoA) encoded in Base64. The CoA is at most 128 bytes (1024 bits) long.

If this field is missing from the output, that means that the CoA is not installed.

(not shown)

Note that the reported properties are specific to the device, not to the interface, which means that the properties such as product_id, version information, etc., will be reported identically via other supported interfaces, e.g. UAVCAN.

Example output of zubax_id
ChibiOS/RT Shell
ch> zubax_id
product_id   : 'com.zubax.gnss'
product_name : 'Zubax GNSS'
sw_version   : '4.0'
sw_vcs_commit: 266365646
sw_build_date: Apr  9 2017
hw_version   : '2.2'
hw_unique_id : 'NP/TBUNXMDQ5RCJDAAAAAA=='
hw_signature : 'sqKqz6bJCimo3/oy/x3sAbTkwRYA9LaubgUycJwKdxGVtqrqGBRfbQkllBhHaU5l+RIDRqKnxQVSzU7
QIeGuScK3RDfrAT3ke42i+MlTh20+mr+TRV2T9YAu/2q6pq0rSYnbYRqncA1WyGhrGtlEav/K4svfL/jgwNxfE3d/YiI='
ch>

Refer to your product's documentation page for the complete list of product-specific properties and their values.