Cyphal v1.0 interface (legacy)

This section documents the legacy Cyphal/CAN v1.0 interface as found in FluxGrip firmware v1.0. Newer firmware releases utilize a significantly improved and simplified Cyphal v1.1 interface.

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.

Values of uavcan.node.id above the maximum node-ID for the current transport (e.g., 127 for Cyphal/CAN) are treated as invalid and will trigger a PnP node-ID allocation at startup.

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

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.

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.

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.

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.

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

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.

---

[1]

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