Cyphal interface

Cyphal, formerly known as UAVCAN until March 2022, is the primary communication protocol supported by this device. For historical reasons, registers related to the Cyphal stack may be named with the uavcan. prefix.

The product utilizes data types from the vendor-specific DSDL namespace zubax. Human-friendly documentation for this and other DSDL namespaces can be viewed online via Nunaweb.

Magnet control is implemented via a dedicated command topic subscription. Status feedback is implemented by publishing feedback messages to a dedicated topic. Fault reset is done by sending an uavcan.node.ExecuteCommand request with the appropriate opcode.

Configuration registers

The following table contains the list of configuration registers that affect the Cyphal interface. Changes to these registers take effect after reboot unless explicitly indicated otherwise.

Register	Type	Default	Unit	Description
uavcan.node.id	natural16	65535 (plug-and-play)		Plug-and-play node-ID allocation
uavcan.can.mtu	natural8	8	byte	Cyphal/CAN
uavcan.can.bitrate	natural32[2]	1000000, 1000000	\(\frac{\text{bit}}{\text{second}}\)	Cyphal/CAN
uavcan.can.count	natural8	(hardware-dependent)		Cyphal/CAN
uavcan.pub.feedback.id	natural16	65535 (disabled)		Feedback
uavcan.pub.feedback.prio	natural8	4 (nominal)		Feedback
uavcan.sub.command.id	natural16	65535 (disabled)		Command

Port summary

Port kind	Port name	Data type	Priority	Period	Timeout	Description
publication		uavcan.node.Heartbeat.1	4 (nominal)	1 s	period	Heartbeat
publication		uavcan.node.port.List	7 (optional)	10 s	period	See Cyphal Specification
publication		uavcan.pnp.NodeIDAllocationData.1	6 (slow)	random	1 s	Only during PnP node-ID allocation
subscription		uavcan.pnp.NodeIDAllocationData.1			0.5 s	ditto
publication	feedback	zubax.fluxgrip.Feedback.1	uavcan.pub.feedback.prio	1 s and on change	1 s	Feedback
subscription	command	zubax.fluxgrip.Command.1			0.5 s	Command
RPC server		uavcan.node.GetInfo.1				Node info
RPC server		uavcan.node.ExecuteCommand.1				Execute command
RPC server		uavcan.register.List.1				Register
RPC server		uavcan.register.Access.1				Register

Plug-and-play node-ID allocation

By default, the local Cyphal node does not have an assigned node-ID; that is, the uavcan.node.id register is set to 65535 (\(FFFF_{16}\)). When this is the case, the device will commence the standard plug-and-play (PnP) node-ID allocation sequence defined in the Cyphal specification.

Once the node-ID allocation is completed, the uavcan.node.id register will be updated with the allocated node-ID value. This value will be saved to non-volatile memory when the device is commanded to restart.

Publications

Heartbeat

The mode field takes the following values:

• OPERATIONAL unless the firmware update is in progress.

• SOFTWARE_UPDATE if a new firmware image is being downloaded; see chapter \ref{sec:bootloader}.

The health field takes the following values:

• NOMINAL if the device is operating correctly.

• ADVISORY if the device is operating correctly but minor issues are detected.

• WARNING if the device is in the fault state and is unable to operate normally.

The vendor_specific_status_code (VSSC) field is split into two orthogonal 4-bit nibbles. The least significant nibble contains the general device status code, while the most significant nibble contains the firmware update process status code.

The interpretation of the general device status code (low VSSC nibble) is as follows:

Low VSSC nibble	Device status
0	Idle, demagnetized
1	Idle, magnetized 🧲
2	Magnetizing
3	Demagnetizing
4	Idle, magnet state unknown
5	Fault: power stage malfunction, or the supply voltage is outside of the operating range (see hardware specification)
6	Fault: power stage sensor error
7	Fault: power stage malfunction
8	Fault: power stage malfunction
9	Fault: power stage sensor error
10 (\(A_{16}\))	Fault: power stage malfunction
11 (\(B_{16}\))	Fault: other
12 (\(C_{16}\))	Reserved
13 (\(D_{16}\))	Reserved
14 (\(E_{16}\))	Reserved
15 (\(F_{16}\))	Fault: invalid configuration

High VSSC nibble	Firmware update status
0	Idle or in progress, depending on the mode field
1	Filesystem error
2	Network remote file read timed out
3	Filesystem error
4	Filesystem error
5	Network remote file read timed out
6	Firmware image file is too large
7	Reserved
8	Reserved
9	Reserved
10 (\(A_{16}\))	Reserved
11 (\(B_{16}\))	Reserved
12 (\(C_{16}\))	Reserved
13 (\(D_{16}\))	Reserved
14 (\(E_{16}\))	Reserved
15 (\(F_{16}\))	Reserved

Definition of uavcan.node.Heartbeat.1.0; extent 12 bytes:

# Abstract node status information.
# This is the only high-level function that shall be implemented by all nodes.
#
# All Cyphal nodes that have a node-ID are required to publish this message to its fixed subject periodically.
# Nodes that do not have a node-ID (also known as "anonymous nodes") shall not publish to this subject.
#
# The default subject-ID 7509 is 1110101010101 in binary. The alternating bit pattern at the end helps transceiver
# synchronization (e.g., on CAN-based networks) and on some transports permits automatic bit rate detection.
#
# Network-wide health monitoring can be implemented by subscribing to the fixed subject.

uint16 MAX_PUBLICATION_PERIOD = 1   # [second]
# The publication period shall not exceed this limit.
# The period should not change while the node is running.

uint16 OFFLINE_TIMEOUT = 3          # [second]
# If the last message from the node was received more than this amount of time ago, it should be considered offline.

uint32 uptime                       # [second]
# The uptime seconds counter should never overflow. The counter will reach the upper limit in ~136 years,
# upon which time it should stay at 0xFFFFFFFF until the node is restarted.
# Other nodes may detect that a remote node has restarted when this value leaps backwards.

Health.1.0 health
# The abstract health status of this node.

Mode.1.0 mode
# The abstract operating mode of the publishing node.
# This field indicates the general level of readiness that can be further elaborated on a per-activity basis
# using various specialized interfaces.

uint8 vendor_specific_status_code
# Optional, vendor-specific node status code, e.g. a fault code or a status bitmask.

@assert _offset_ % 8 == {0}
@assert _offset_ == {56}  # Fits into a single-frame Classic CAN transfer (least capable transport, smallest MTU).
@extent 12 * 8

Feedback

This topic is published to at a low fixed frequency and possibly on change. Applications that do not require the extended status information can subscribe to this topic using primitive types like zubax.primitive.boolean.Scalar.1.

Definition of zubax.fluxgrip.Feedback.1.0; extent 63 bytes:

# Zubax EPM status feedback message.
# This type is a structural subtype of uavcan.primitive.scalar.Bit.

bool magnetized
# True if the magnet is currently turned on.
# The value is a best guess if remagnetization is currently in progress.

int3 remagnetization_state
# -1 -- the magnet is being demagnetized (turning off).
#  0 -- the magnet is idle.
# +1 -- the magnet is being magnetized (turning on).

void4

@assert _offset_ == {8}

uint24[2] cycles_on_off
# The number of magnetization and demagnetization cycles commenced, respectively, since the device was powered on.
# The values are incremented immediately at the commencement of the cycle.

@extent 63 * 8

Subscriptions

Command

The published values are interpreted as specified below; values that are not explicitly listed shall not be used. See Functional description for the state transition logic.

Value	Interpretation
0	OFF
1	ON
2	FORCE

The command subscription can also accept boolean primitives like zubax.primitive.boolean.Scalar.1 or uavcan.primitive.scalar.Bit.1, since falsity is interpreted as zero, and truth as +1. This enables simplified control of the magnet through a simple boolean flag commanding the desired state.

Multiple magnets can subscribe to the same command topic to implement lockstep operation.

Definition of uavcan.primitive.scalar.Integer8.1.0; extent 1 bytes:

int8 value
@sealed

RPC servers

Node info

The node name is reported as com.zubax.fluxgrip.

Contact Zubax Robotics for the details on the hardware version numbering and the certificate of authenticity (CoA) validation.

Definition of uavcan.node.GetInfo.1.0; extent 0 / 448 bytes:

# Full node info request.
# All of the returned information shall be static (unchanged) while the node is running.
# It is highly recommended to support this service on all nodes.

@sealed

---

Version.1.0 protocol_version
# The Cyphal protocol version implemented on this node, both major and minor.
# Not to be changed while the node is running.

Version.1.0 hardware_version
Version.1.0 software_version
# The version information shall not be changed while the node is running.
# The correct hardware version shall be reported at all times, excepting software-only nodes, in which
# case it should be set to zeros.
# If the node is equipped with a Cyphal-capable bootloader, the bootloader should report the software
# version of the installed application, if there is any; if no application is found, zeros should be reported.

uint64 software_vcs_revision_id
# A version control system (VCS) revision number or hash. Not to be changed while the node is running.
# For example, this field can be used for reporting the short git commit hash of the current
# software revision.
# Set to zero if not used.

uint8[16] unique_id
# The unique-ID (UID) is a 128-bit long sequence that is likely to be globally unique per node.
# The vendor shall ensure that the probability of a collision with any other node UID globally is negligibly low.
# UID is defined once per hardware unit and should never be changed.
# All zeros is not a valid UID.
# If the node is equipped with a Cyphal-capable bootloader, the bootloader shall use the same UID.

@assert _offset_ == {30 * 8}
# Manual serialization note: only fixed-size fields up to this point. The following fields are dynamically sized.

uint8[<=50] name
# Human-readable non-empty ASCII node name. An empty name is not permitted.
# The name shall not be changed while the node is running.
# Allowed characters are: a-z (lowercase ASCII letters) 0-9 (decimal digits) . (dot) - (dash) _ (underscore).
# Node name is a reversed Internet domain name (like Java packages), e.g. "com.manufacturer.project.product".

uint64[<=1] software_image_crc
# The value of an arbitrary hash function applied to the software image. Not to be changed while the node is running.
# This field can be used to detect whether the software or firmware running on the node is an exact
# same version as a certain specific revision. This field provides a very strong identity guarantee,
# unlike the version fields above, which can be the same for different builds of the software.
# As can be seen from its definition, this field is optional.
#
# The exact hash function and the methods of its application are implementation-defined.
# However, implementations are recommended to adhere to the following guidelines, fully or partially:
#   - The hash function should be CRC-64-WE.
#   - The hash function should be applied to the entire application image padded to 8 bytes.
#   - If the computed image CRC is stored within the software image itself, the value of
#     the hash function becomes ill-defined, because it becomes recursively dependent on itself.
#     In order to circumvent this issue, while computing or checking the CRC, its value stored
#     within the image should be zeroed out.

uint8[<=222] certificate_of_authenticity
# The certificate of authenticity (COA) of the node, 222 bytes max, optional. This field can be used for
# reporting digital signatures (e.g., RSA-1776, or ECDSA if a higher degree of cryptographic strength is desired).
# Leave empty if not used. Not to be changed while the node is running.

@assert _offset_ % 8 == {0}
@assert _offset_.max == (313 * 8)     # At most five CAN FD frames
@extent 448 * 8

Execute command

Commands that are not explicitly listed return STATUS_BAD_COMMAND. Commands whose command code is less than 32768 which are not listed here shall not be invoked; otherwise, permanent hardware damage may occur.

Command	Parameter	Description
0 (vendor-specific)		Clear the latched fault; do nothing if no fault is present.
65530 = STORE_PERSISTENT_STATES		Alias for RESTART.
65532 = FACTORY_RESET		Reset all configuration registers to defaults upon next RESTART.
65533 = BEGIN_SOFTWARE_UPDATE	Firmware image file name	Commence firmware update. The device will remain operational while the firmware is being downloaded.
65535 = RESTART		Restart the device saving the configuration registers.

Definition of uavcan.node.ExecuteCommand.1.3; extent 300 / 48 bytes:

# Instructs the server node to execute or commence execution of a simple predefined command.
# All standard commands are optional; i.e., not guaranteed to be supported by all nodes.

uint16 command
# Standard pre-defined commands are at the top of the range (defined below).
# Vendors can define arbitrary, vendor-specific commands in the bottom part of the range (starting from zero).
# Vendor-specific commands shall not use identifiers above 32767.

uint16 COMMAND_RESTART = 65535
# Reboot the node.
# Note that some standard commands may or may not require a restart in order to take effect; e.g., factory reset.

uint16 COMMAND_POWER_OFF = 65534
# Shut down the node; further access will not be possible until the power is turned back on.

uint16 COMMAND_BEGIN_SOFTWARE_UPDATE = 65533
# Begin the software update process using uavcan.file.Read. This command makes use of the "parameter" field below.
# The parameter contains the path to the new software image file to be downloaded by the server from the client
# using the standard service uavcan.file.Read. Observe that this operation swaps the roles of the client and
# the server.
#
# Upon reception of this command, the server (updatee) will evaluate whether it is possible to begin the
# software update process. If that is deemed impossible, the command will be rejected with one of the
# error codes defined in the response section of this definition (e.g., BAD_STATE if the node is currently
# on-duty and a sudden interruption of its activities is considered unsafe, and so on).
# If an update process is already underway, the updatee should abort the process and restart with the new file,
# unless the updatee can determine that the specified file is the same file that is already being downloaded,
# in which case it is allowed to respond SUCCESS and continue the old update process.
# If there are no other conditions precluding the requested update, the updatee will return a SUCCESS and
# initiate the file transfer process by invoking the standard service uavcan.file.Read repeatedly until the file
# is transferred fully (please refer to the documentation for that data type for more information about its usage).
#
# While the software is being updated, the updatee should set its mode (the field "mode" in uavcan.node.Heartbeat)
# to MODE_SOFTWARE_UPDATE. Please refer to the documentation for uavcan.node.Heartbeat for more information.
#
# It is recognized that most systems will have to interrupt their normal services to perform the software update
# (unless some form of software hot swapping is implemented, as is the case in some high-availability systems).
#
# Microcontrollers that are requested to update their firmware may need to stop execution of their current firmware
# and start the embedded bootloader (although other approaches are possible as well). In that case,
# while the embedded bootloader is running, the mode reported via the message uavcan.node.Heartbeat should be
# MODE_SOFTWARE_UPDATE as long as the bootloader is runing, even if no update-related activities
# are currently underway. For example, if the update process failed and the bootloader cannot load the software,
# the same mode MODE_SOFTWARE_UPDATE will be reported.
# It is also recognized that in a microcontroller setting, the application that served the update request will have
# to pass the update-related metadata (such as the node-ID of the server and the firmware image file path) to
# the embedded bootloader. The tactics of that transaction lie outside of the scope of this specification.

uint16 COMMAND_FACTORY_RESET = 65532
# Return the node's configuration back to the factory default settings (may require restart).
# Due to the uncertainty whether a restart is required, generic interfaces should always force a restart.

uint16 COMMAND_EMERGENCY_STOP = 65531
# Cease activities immediately, enter a safe state until restarted.
# Further operation may no longer be possible until a restart command is executed.

uint16 COMMAND_STORE_PERSISTENT_STATES = 65530
# This command instructs the node to store the current configuration parameter values and other persistent states
# to the non-volatile storage. Nodes are allowed to manage persistent states automatically, obviating the need for
# this command by committing all such data to the non-volatile memory automatically as necessary. However, some
# nodes may lack this functionality, in which case this parameter should be used. Generic interfaces should always
# invoke this command in order to ensure that the data is stored even if the node doesn't implement automatic
# persistence management.

uint16 COMMAND_IDENTIFY = 65529
# This command instructs the node to physically identify itself in some way--e.g., by flashing a light or
# emitting a sound. The duration and the nature of the identification process is implementation-defined.
# This command can be useful for human operators to match assigned node-ID values to physical nodes during setup.

uint8[<=uavcan.file.Path.2.0.MAX_LENGTH] parameter
# A string parameter supplied to the command. The format and interpretation is command-specific.
# The standard commands do not use this field (ignore it), excepting the following:
#   - COMMAND_BEGIN_SOFTWARE_UPDATE

@extent 300 * 8

---

uint8 STATUS_SUCCESS        = 0     # Started or executed successfully
uint8 STATUS_FAILURE        = 1     # Could not start or the desired outcome could not be reached
uint8 STATUS_NOT_AUTHORIZED = 2     # Denied due to lack of authorization
uint8 STATUS_BAD_COMMAND    = 3     # The requested command is not known or not supported
uint8 STATUS_BAD_PARAMETER  = 4     # The supplied parameter cannot be used with the selected command
uint8 STATUS_BAD_STATE      = 5     # The current state of the node does not permit execution of this command
uint8 STATUS_INTERNAL_ERROR = 6     # The operation should have succeeded but an unexpected failure occurred
uint8 status
# The result of the request.

uint8[<=46] output
# Any output that could be useful that has the capability to convey detailed information.
# Users can send commands and receive specific data, like device status or measurements back in a streamlined manner.
# The standard commands should leave this field empty unless explicitly specified otherwise.

@extent 48 * 8

Register

Helpful Yakut commands:

y r 125 uavcan.sub.command.id 1001            # Assign the command topic ID to 1001 on node 125
y r 125 uavcan.sub.command.id                 # Just read the register
y rl 125                                      # Read all register names on node 125
y rl 125 | y --yaml rb -omp 125 > config.yaml # Save all mutable persistent registers of node 125 into a YAML file
y rb 125 < config.yaml                        # Restore the registers from the YAML file

Definition of uavcan.register.List.1.0; extent 2 / 256 bytes:

# This service allows the caller to discover the names of all registers available on the server
# by iterating the index field from zero until an empty name is returned.
#
# The ordering of the registers shall remain constant while the server is running.
# The ordering is not guaranteed to remain unchanged when the server node is restarted.

uint16 index

@sealed

---

Name.1.0 name
# Empty name in response means that the index is out of bounds, i.e., discovery is finished.

@sealed

Definition of uavcan.register.Access.1.0; extent 515 / 267 bytes:

# Registers are strongly-typed named values used to store the configuration parameters of a node.
# This service is used to write and read a register.
#
#
#   READ/WRITE BEHAVIORS
#
# The write operation is performed first, unless skipped by sending an empty value in the request.
# The server may attempt to convert the type of the supplied value to the correct type if there is a type mismatch
# (e.g. uint8 may be converted to uint16); however, servers are not required to perform implicit type conversion,
# and the rules of such conversion are not explicitly specified, so this behavior should not be relied upon.
#
# On the next step the register will be read regardless of the outcome of the write operation. As such, if the write
# operation could not be performed (e.g. due to a type mismatch or any other issue), the register will retain its old
# value. By evaluating the response the caller can determine whether the register was written successfully.
#
# The write-read sequence is not guaranteed to be atomic, meaning that external influences may cause the register to
# change its value between the write and the subsequent read operation. The caller is responsible for handling that
# case properly.
#
# The timestamp provided in the response corresponds to the time when the register was read. The timestamp may
# be empty if the server does not support timestamping or its clock is not (yet) synchronized with the network.
#
# If only read is desired, but not write, the caller shall provide a value of type 'empty'. That will signal the server
# that the write operation shall be skipped, and it will proceed to read the register immediately.
#
# If the requested register does not exist, the write operation will have no effect and the returned value will be
# empty. Existing registers should not return 'empty' when read since that would make them indistinguishable from
# nonexistent registers.
#
#
#   REGISTER DEFINITION REQUIREMENTS
#
# Registers shall never change their type or flags as long as the server is running. Meaning that:
#   - Mutability and persistence flags cannot change their states.
#   - Read operations shall always return values of the same type and same dimensionality.
#     The dimensionality requirement does not apply to inherently variable-length values such as strings and
#     unstructured chunks.
#
# Register name should contain only:
#   - Lowercase ASCII alphanumeric characters (a-z, 0-9)
#   - Full stop (.)
#   - Low line (underscore) (_)
# With the following limitations/recommendations:
#   - The name shall not begin with a decimal digit (0-9).
#   - The name shall neither begin nor end with a full stop.
#   - A low line shall not be followed by a non-alphanumeric character.
#   - The name should contain at least one full stop character.
# Other patterns and ASCII characters are reserved for special function registers (introduced below).
#
#
#   ENVIRONMENT VARIABLES
#
# This section applies only to software nodes executed in a high-level operating system that supports environment
# variables or an equivalent mechanism.
#
# When a software node is launched, it is usually necessary to provide some of its configuration information early,
# particularly that which is related to Cyphal networking, before the node is started. Environment variables offer
# a convenient way of addressing this. Software nodes that support the register interface should evaluate the
# available environment variables during initialization and update their registers (whether they are stored in
# a persistent storage or in memory) accoringly. This should be completed before the first register read access.
#
# A register name is mapped to an environment variable name as follows:
#   - the name is upper-cased;
#   - full stop characters are replaced with double low line characters.
# For example: 'motor.inductance_dq' is mapped to 'MOTOR__INDUCTANCE_DQ'.
#
# Register values are represented in environment variables as follows:
#   - string:                         utf-8 or platform-specific
#   - unstructured:                   as-is
#   - bit, integer*, natural*, real*: space-separated decimals
#
# If an environment variable matches the name of an existing register but its value cannot be converted to the
# register's type, an error should be raised.
#
# If an environment variable does not match the name of any register, it may be ignored. However, if the implementation
# can reliably deduce the type and purpose of the register, it may create one automatically. This provision is to
# support applications where the register schema may be altered by configuration.
#
#
#   SPECIAL FUNCTION REGISTERS
#
# The following optional special function register names are defined:
#   - suffix '<' is used to define an immutable persistent value that contains the maximum value
#     of the respective register.
#   - suffix '>' is like above, used to define the minimum value of the respective register.
#   - suffix '=' is like above, used to define the default value of the respective register.
#   - prefix '*' is reserved for raw memory access (to be defined later).
# Examples:
#   - register name "system.parameter"
#   - maximum value is contained in the register named "system.parameter<" (optional)
#   - minimum value is contained in the register named "system.parameter>" (optional)
#   - default value is contained in the register named "system.parameter=" (optional)
#
# The type and dimensionality of the special function registers containing the minimum, maximum, and the default
# value of a register shall be the same as those of the register they relate to.
#
# If a written value exceeds the minimum/maximum specified by the respective special function registers,
# the server may either adjust the value automatically, or to retain the old value, depending on which behavior
# suits the objectives of the application better.
# The values of registers containing non-scalar numerical entities should be compared elementwise.
#
#
#   STANDARD REGISTERS
#
# The following table specifies the register name patterns that are reserved by the specification for
# common functions. These conventions are not mandatory to follow, but implementers are recommended to adhere because
# they enable enhanced introspection capabilities and simplify device configuration and diagnostics.
#
#   REGISTER NAME PATTERN                               TYPE            FLAGS                   RECOMMENDED DEFAULT
# =====================================================================================================================
#
#   uavcan.node.id                                      natural16[1]    mutable, persistent     65535 (unset/PnP)
#
# Contains the node-ID of the local node. Values above the maximum valid node-ID for the current transport
# indicate that the node-ID is not set; if plug-and-play is supported, it will be used by the node to obtain an
# automatic node-ID. Invalid values other than 65535 should be avoided for consistency.
#
# ---------------------------------------------------------------------------------------------------------------------
#
#   uavcan.node.description                             string          mutable, persistent     (empty)
#
# User/integrator-defined, human-readable description of this specific node.
# This is intended for use by a system integrator and should not be set by the manufacturer of a component.
# For example: on a quad-rotor drone this might read "motor 2" for one of the ESC nodes.
#
# ---------------------------------------------------------------------------------------------------------------------
#
#   uavcan.pub.PORT_NAME.id                             natural16[1]    mutable, persistent     65535 (unset, invalid)
#   uavcan.sub.PORT_NAME.id                             ditto           ditto                   ditto
#   uavcan.cln.PORT_NAME.id                             ditto           ditto                   ditto
#   uavcan.srv.PORT_NAME.id                             ditto           ditto                   ditto
#
# Publication/subscription/client/server port-ID, respectively. These registers are configured by the system integrator
# or an autoconfiguration authority when the node is first connected to a network.
#
# The "PORT_NAME" defines the human-friendly name of the port, which is related to the corresponding function
# or a network service supported by the node. The name shall match the following POSIX ERE expression:
#
#   [a-zA-Z_][a-zA-Z0-9_.]*
#
# The names are defined by the vendor of the node. The user/integrator is expected to understand their meaning and
# relation to the functional capabilities of the node by reading the technical documentation provided by the vendor.
#
# A port whose port-ID register is unset (invalid value) remains inactive (unused); the corresponding function may
# be disabled. For example, a register named "uavcan.pub.measurement.id" defines the subject-ID of a measurement
# published by this node; if the register contains an invalid value (above the maximum valid subject-ID),
# said measurement is not published.
#
# The same name is used in other similar registers defined below. Network introspection and autoconfiguration tools
# will expect to find a register of this form for every configurable port supported by the node.
#
# ---------------------------------------------------------------------------------------------------------------------
#
#   uavcan.pub.PORT_NAME.type                           string          immutable, persistent   N/A
#   uavcan.sub.PORT_NAME.type                           ditto           ditto                   ditto
#   uavcan.cln.PORT_NAME.type                           ditto           ditto                   ditto
#   uavcan.srv.PORT_NAME.type                           ditto           ditto                   ditto
#
# Publication/subscription/client/server full data type name and dot-separated version numbers, respectively.
# These registers are set by the vendor once and typically they are to remain unchanged (hence "immutable").
# The "PORT_NAME" defines the human-friendly name of the port as specified above.
# For example, a register named "uavcan.pub.measurement.type" may contain "uavcan.si.sample.angle.Quaternion.1.0".
#
# ---------------------------------------------------------------------------------------------------------------------
#
#   uavcan.diagnostic.*
#
# Prefix reserved for future use.
#
# ---------------------------------------------------------------------------------------------------------------------
#
#   uavcan.can.bitrate                                  natural32[2]    implementation-defined  implementation-defined
#   uavcan.can.iface                                    string          mutable, persistent     implementation-defined
#
# These registers are only relevant for nodes that support Cyphal/CAN.
#
# uavcan.can.bitrate defines the CAN bus bit rate: the first value is the arbitration bit rate, the second is the
# data phase bit rate. Nodes that support only Classic CAN should ignore the second value. Nodes that support CAN FD
# should initialize in the Classic CAN mode (MTU 8 bytes, BRS flag not set) if the values are equal. If CAN bitrate
# is not configurable or is always auto-detected, this register may be omitted or made immutable; otherwise it should
# be mutable and persistent.
#
# uavcan.can.iface is only relevant for software nodes or nodes that are capable of using different CAN interfaces.
# The value is a space-separated list of CAN interface names to use. The name format is implementation-defined
# (for example, "can0").
#
# ---------------------------------------------------------------------------------------------------------------------
#
#   uavcan.udp.*
#
# Prefix reserved for future use.
#
# ---------------------------------------------------------------------------------------------------------------------#
#
#   uavcan.serial.*
#
# Prefix reserved for future use.
#
# ---------------------------------------------------------------------------------------------------------------------

Name.1.0 name
# The name of the accessed register. Shall not be empty.
# Use the List service to obtain the list of registers on the node.

Value.1.0 value
# Value to be written. Empty if no write is required.

@sealed

---

uavcan.time.SynchronizedTimestamp.1.0 timestamp
# The moment of time when the register was read (not written).
# Zero if the server does not support timestamping.

bool mutable
# Mutable means that the register can be written using this service.
# Immutable registers cannot be written, but that doesn't imply that their values are constant (unchanging).

bool persistent
# Persistence means that the register retains its value permanently across power cycles or any other changes
# in the state of the server, until it is explicitly overwritten (either via Cyphal, any other interface,
# or by the device itself).
#
# The server is recommended to manage persistence automatically by committing changed register values to a
# non-volatile storage automatically as necessary. If automatic persistence management is not implemented, it
# can be controlled manually via the standard service uavcan.node.ExecuteCommand. The same service can be used
# to return the configuration to a factory-default state. Please refer to its definition for more information.
#
# Consider the following examples:
#   - Configuration parameters are usually both mutable and persistent.
#   - Diagnostic values are usually immutable and non-persisient.
#   - Registers that trigger an activity when written are typically mutable but non-persisient.
#   - Registers that contain factory-programmed values such as calibration coefficients that can't
#     be changed are typically immutable but persistent.

void6

Value.1.0 value
# The value of the register when it was read (beware of race conditions).
# Registers never change their type and dimensionality while the node is running.
# Empty value means that the register does not exist (in this case the flags should be cleared/ignored).
# By comparing the returned value against the write request the caller can determine whether the register
# was written successfully, unless write was not requested.
# An empty value shall never be returned for an existing register.

@sealed

Transports

Cyphal/CAN

A single or doubly-redundant CAN bus interface is available in some hardware models. The primary interface is labeled CAN0 and the redundant, if available, is labeled CAN1.

Important

Firmware revisions prior to v1.3 do not support CAN FD; only Classic CAN is supported. Do not attempt to use CAN FD with these firmware revisions.

The value of register uavcan.can.count reflects the number of CAN interfaces that are actually used in the application. If a redundant CAN interface is available but only one is used, the used interface shall be strictly CAN0, and the count register shall be set to 1, thereby disabling CAN1. If set to zero, the device will no longer be possible to contact via Cyphal/CAN.

The CAN bitrates are configured via register uavcan.can.bitrate, where the first value sets the arbitration phase bitrate and the second value sets the data phase bitrate. If the configured bitrate is not supported, the device will automatically revert to the default value, which is 1 Mbps for both arbitration and identification phases (i.e., BRS disabled).

The CAN MTU is set via uavcan.can.mtu; the only valid values are 8 and 64 bytes. Setting MTU to 8 bytes and both arbitration and data phase bitrates to the same value will disable CAN FD and select Classic CAN instead, which enables compatibility with legacy CAN networks. The Classic CAN compatibility is enabled by default to simplify deployment; the CAN FD support needs to be enabled explicitly if necessary.

The device does not support automatic CAN configuration detection. The factory-default CAN parameters are as follows: 1 Mbps for both arbitration and data phase bitrates, MTU 8 bytes, Classic CAN mode.

The device automatically recovers from the bus-off and error-passive states following the CAN bus specification.

For the CAN hardware specifications, please refer to your product documentation.

“On CAN bus topology and termination” provides recommendations on the usage of CAN bus in relevant applications.

CAN bus LED indicators

Devices equipped with CAN bus interfaces may contain two LED indicators per CAN interface, labeled RX and TX.

While the CAN controller resides in the error-active state[1], the RX LED illuminates briefly upon successful receipt of a valid CAN frame accepted by the hardware filters; similarly, a TX LED illuminates briefly when the device successfully transmits a CAN frame with acknowledgement.

In the error-passive state, the TX LED blinks rapidly continuously, while the RX LED continues to operate normally. This choice reflects the fact that in the error-passive state the device can only receive CAN frames, but cannot transmit them.

In the bus-off state, both RX and TX indicators blink rapidly. This choice reflects the fact that in the bus-off state the device cannot transmit or receive CAN frames.

Cyphal/UDP via SPE 10BASE-T1S

Please contact Zubax Robotics.

---

[1]

Per ISO 11898-1, the error-active state is the normal operating state of the CAN controller.