# 5. Cyphal interface
This page is about Cyphal related details such as interface, supported features, registers, configuration and usage examples and software versions. For general information please refer 1. General, for hardware-related details, including the connection example scheme, please refer to the Hardware page: L1 GPS NEO-M8, L1/L2 RTK GPS ZED-F9P or Magnetometer RM3100.
# 5.1. Cyphal interface
This node interacts with the following data types:
Common for any node
| № | Type | Message | Rate |
|---|---|---|---|
| 1 | pub | uavcan.node.Heartbeat (opens new window) | 1 Hz |
| 2 | pub | uavcan.node.port.List (opens new window) | 0.2 Hz |
| 3 | RPC-service | uavcan.node.GetInfo (opens new window) | |
| 4 | RPC-service | uavcan.node.ExecuteCommand * (opens new window) | |
| 5 | RPC-service | uavcan.register.List (opens new window) | |
| 6 | RPC-service | uavcan.register.Access (opens new window) |
Here ExecuteCommand supports COMMAND_RESTART=65535, COMMAND_FACTORY_RESET=65532 and COMMAND_STORE_PERSISTENT_STATES=65530.
Circuit status service
Like any other RaccoonLab node, this node also supports the Circuit status service. It uses the following subjects:
| № | Data type and topic name | Description |
|---|---|---|
| 1 | uavcan.si.sample.voltage.Scalar.1.0 vouavcan.pub.crct.5v.id | The node publishes 5V voltage with 2 Hz frequency |
| 2 | uavcan.si.sample.voltage.Scalar.1.0 uavcan.pub.crct.vin.id | The node publishes VIn voltage with 2 Hz frequency |
| 3 | uavcan.si.sample.temperature.Scalar.1.0 uavcan.pub.crct.dev_temp.id | The node publishes temperature with 2 Hz frequency |
GNSS service
GNSS service is based on either u-blox L1 NEO-M8 (opens new window) or L1/L2 ZED-F9P (opens new window) gnss module.
It supports 2 interfaces: DS015 and UDRAL. You should use only one interface at the same time.
The following interface is based on DS015 proposal (opens new window):
| № | Data type and topic name | Description |
|---|---|---|
| 1 | ds015.service.gnss.Gnss.0.1 (opens new window) uavcan.pub.gps.ds015.gnss.id | Mainly based on NavPvt, 5-10 Hz |
| 2 | ds015.service.gnss.Covariance.0.1 (opens new window) uavcan.pub.gps.ds015.cov.id | Auxilliary, based on NavCov, 5-10 Hz |
| 3 | uavcan.time.SynchronizedTimestamp.1.0 (opens new window) uavcan.pub.gps.time_utc.id | Auxilliary, 5-10 Hz |
The following features are not implemented yet, but they will appear soon:
| № | Data type and topic name | Description |
|---|---|---|
| 1 | ds015.service.gnss.RelativePosition.0.1 (opens new window) uavcan.pub.gps.ds015.relpos.id | Not implemented yet |
| 2 | Probably String.1.0 (opens new window) uavcan.sub.gps.rtk.id | Not implemented yet |
| 3 | Probably String.1.0 (opens new window) uavcan.sub.gps.moving_baseline.id | Not implemented yet |
The following interface is based on UDRAL:
| № | Data type and topic name | Description |
|---|---|---|
| 1 | PointStateVarTs.0.1 (opens new window) uavcan.pub.gps.zubax.point.id | Geodetic position and velocity, 5-10 Hz |
| 2 | uavcan.primitive.scalar.Integer16 (opens new window) uavcan.pub.gps.zubax.sats.id | Number of satellites, 5-10 Hz |
| 3 | uavcan.primitive.scalar.Integer16 (opens new window) uavcan.pub.gps.zubax.status.id | Fix status, 5-10 Hz |
| 4 | uavcan.primitive.scalar.Real32 (opens new window) uavcan.pub.gps.zubax.pdop.id | Position (3D) dilution of precision, 5-10 Hz |
Barometer service
Barometer service is based on BMP280 (opens new window) sensor.
| № | Data type and topic name | Description |
|---|---|---|
| 1 | uavcan.si.sample.pressure.Scalar.1.0 (opens new window) uavcan.pub.zubax.baro.press.id | 10 Hz |
| 2 | uavcan.si.sample.temperature.Scalar.1.0 uavcan.pub.zubax.baro.temp.id | 10 Hz |
Magnetometer service
Magnetometer service is based on RM3100 (opens new window) sensor.
| № | Data type and topic name | Description |
|---|---|---|
| 1 | uavcan.si.sample.magnetic_field_strength.Vector3.1.1 (opens new window) | uavcan.pub.zubax.mag.id |
Serial formwarder for UBLOX
Serial forwarder is an optional service that can be used for manual configuration of GNSS module.
Normally, you don't need to use this service because configuration is started automatically.
If you want a custom configuration, you can either run a script to send the required commands or even forward serial over CAN with ublox center.
Serial formwarder significantly occupies CAN-bus, so it is recommended to disable it during the flight.
| № | Data type and topic name | Description |
|---|---|---|
| 1 | uavcan.metatransport.serial.Fragment.0.2 (opens new window) uavcan.pub.gps.ubx_rx.id | Node publishes data from ublox |
| 2 | uavcan.metatransport.serial.Fragment.0.2 (opens new window) uavcan.sub.gps.ubx_tx.id | Node publishes data to ublox |
# 5.2. Cyphal Registers
Beside the standard uavcan.*.<subject>.id and uavcan.*.<subject>.type registers related to
each subject, the node also have the following registers:
| № | Register | Note | Description |
|---|---|---|---|
| 0 | uavcan.node.id | Reboot required | Node ID |
| 1 | uavcan.node.name | Reboot required | Node custom name |
| 2 | gps.baudrate | Custom baudrate. By default, 921600. Normally, you don't need to change it. | |
| 3 | gps.config | Reboot required | The state of the configuration state machine* |
| 4 | gps.test | Bool | Enable or disable self test (in this mode the device sends mock coordinates) |
gps.config. Normally, you don't need to use this parameter. If you feel that ublox is not correctly configured, you can check the datails on the 7. Ublox setup page.
You can get the list of registers, read and write them using Yakut (opens new window) cli or Yukon (opens new window) gui.
# 5.3. Getting started with Yakut
Before mounting on a real vehicle, especially when using the node for the first time, we recommended performing bench testing with Yakut (opens new window).
# Step 1. Connect the Device
The easiest way is to connect a gnss_mag_baro node to a CAN-sniffer via JST-GH 4 connector as shown below:
Alternatively, in a vehicle you may want to connect the node via Molex CAN connector.
Upon connection, the node should blink with a blue color. Check GNSS LED meaning for details.
# Step 2. Configure the Environment
For details about how to configure the environment, it is recommended to iether refer to the yukon (opens new window) and yakut (opens new window) instructions or to refer to our Cyphal usage instruction.
# Step 3. Monitor the Node
Assuming you have correctly connected the Cyphal node to a CAN sniffer and prepared the environment, you can now monitor node's status.
Run the following command:
y mon # yakut monitor
You should see the output similar to the one shown below:
On the first 3 lines we see online nodes:
- 50 - our gnss node,
- 127 - yakut node (127 is usually used by debug tools).
Other lines are about individual port stats: rate, bandwidth, publishers, subscribers, etc.
# Step 4. Try Node Control Commands
The node supports a few commands which can be usefull during the configuration. Study them in the following code snippet:
# You can always reset the node to the factory settings
# Attention: registers configuration would be reset
y cmd 50 factory # or 65532
# The node doesn't automatically save the registers to the persistent values
# You can save them with the following command
y cmd 50 65530
# Some register changes (for example node ID) have an effect only after restart.
# You can restart the node:
y cmd 50 restart # or 65535
Receiving
Timed out while waiting for response from node 50is expected, as the node restarts immediately.
# Step 5. Configure and retrieve GNSS Data
Position the antenna by a window to detect satellites.
Let's configure the main GNSS DS015 topic and subscribe on the topic:
# Configure the main GNSS DS015 topic
y r 50 uavcan.pub.ds015.gps.gnss.id 2005
# Subscribe on the topic:
yakut subscribe 2005
# Save the config and reboot the node
y cmd 50 65530
y cmd 50 restart
TIP
Latitude and longitude values are in radians. Convert to degrees by multiplying by (180/π).
# Step 6. Configure and retrieve Magnetic Field Data
Let's configure the magnetometer topic and subscribe on it:
# Read the current value of port-ID and then assign it if disabled (65535)
y r 50 uavcan.pub.zubax.mag.id
y r 50 uavcan.pub.zubax.mag.id 2402
# Subscribe on the topic:
y s 2402
# Save the config and reboot the node
y cmd 50 65530
y cmd 50 restart
# Step 7. Configure and retrieve Barometer Data
Let's configure the barometers topics and subscribe on them:
# Read the current values of identifiers
y r 50 uavcan.pub.zubax.baro.press.id
y r 50 uavcan.pub.zubax.baro.temp.id
# 65535 means disabled, so let's configure it
y r 50 uavcan.pub.zubax.baro.press.id 3000
y r 50 uavcan.pub.zubax.baro.temp.id 3001
# Subscribe on the pressure topic:
y s 3000
y s 3001
# Save the config and reboot the node
y cmd 50 65530
y cmd 50 restart
# Step 8. Configure and retrieve Circuit Status Data
Let's configure the barometers topics and subscribe on them:
# Configure ports:
y r 50 uavcan.pub.crct.5v.id 4000
y r 50 uavcan.pub.crct.temp.id 4001
y r 50 uavcan.pub.crct.vin.id 4002
# Subscribe on them:
y sub 4000
y sub 4001
y sub 4002
# Step 9. Advanced configuration
# Check the registers list:
yakut register-list 50 | jq
Hint: Use jq for JSON in-terminal formatting. Install with sudo apt install jq.
# Retrieve the values of these registers:
yakut register-list 50, | yakut register-batch | jq
Or, using the shorter version:
y rl 50, | y rb | jq
Output:
Click for example
{
"50": {
"gps.baudrate": 921600,
"gps.config": 2,
"gps.test": 0,
"system.internal": 1,
"system.name": "co.raccoonlab.gps_mag_baro",
"uavcan.node.description": "",
"uavcan.node.id": 50,
"uavcan.pub.crct.5v.id": 65535,
"uavcan.pub.crct.5v.type": "uavcan.si.sample.voltage.Scalar.1.0",
"uavcan.pub.crct.temp.id": 65535,
"uavcan.pub.crct.temp.type": "uavcan.si.sample.temperature.Scalar.1.0",
"uavcan.pub.crct.vin.id": 65535,
"uavcan.pub.crct.vin.type": "uavcan.si.sample.voltage.Scalar.1.0",
"uavcan.pub.ds015.gps.cov.id": 65535,
"uavcan.pub.ds015.gps.cov.type": "ds015.service.gnss.Covariance.0.1",
"uavcan.pub.ds015.gps.gnss.id": 65535,
"uavcan.pub.ds015.gps.gnss.type": "ds015.service.gnss.Gnss.0.1",
"uavcan.pub.ds015.gps.relpos.id": 65535,
"uavcan.pub.ds015.gps.relpos.type": "ds015.service.gnss.RelativePosition.0.1",
"uavcan.pub.gps.time_utc.id": 65535,
"uavcan.pub.gps.time_utc.type": "uavcan.time.SynchronizedTimestamp.1.0",
"uavcan.pub.gps.ubx_tx.id": 65535,
"uavcan.pub.gps.ubx_tx.type": "uavcan.metatransport.serial.Fragment.0.2",
"uavcan.pub.zubax.baro.press.id": 65535,
"uavcan.pub.zubax.baro.press.type": "uavcan.si.sample.pressure.Scalar",
"uavcan.pub.zubax.baro.temp.id": 65535,
"uavcan.pub.zubax.baro.temp.type": "uavcan.si.sample.temperature.Scalar",
"uavcan.pub.zubax.gps.pdop.id": 65535,
"uavcan.pub.zubax.gps.pdop.type": "uavcan.primitive.scalar.Real32",
"uavcan.pub.zubax.gps.point.id": 65535,
"uavcan.pub.zubax.gps.point.type": "reg.zubax.physics.kinematics.geodetic.PointStateVarTs",
"uavcan.pub.zubax.gps.sats.id": 65535,
"uavcan.pub.zubax.gps.sats.type": "uavcan.primitive.scalar.Integer16",
"uavcan.pub.zubax.gps.status.id": 65535,
"uavcan.pub.zubax.gps.status.type": "uavcan.primitive.scalar.Integer16",
"uavcan.pub.zubax.gps.yaw.id": 65535,
"uavcan.pub.zubax.gps.yaw.type": "uavcan.si.sample.angle.Scalar",
"uavcan.pub.zubax.mag.id": 65535,
"uavcan.pub.zubax.mag.type": "uavcan.si.sample.magnetic_field_strength.Vector3.1.1",
"uavcan.sub.gps.ubx_rx.id": 65535,
"uavcan.sub.gps.ubx_rx.type": "uavcan.metatransport.serial.Fragment.0.2"
}
}
# 5.4. Yukon usage
Alternatively, you can use the Yukon GUI to monitor the node. Simply launch the Yukon GUI and navigate to the Monitor window. An example of this window is presented below:
When monitoring, look for the GNSS node on the bus.
By default, its name should be co.raccoonlab.gps_mag_baro.
Note: Remember the node ID (number) of the GNSS node. While this guide uses 50 as an example in subsequent steps, you should use the node ID that corresponds to your setup.
# 5.5. PX4 integration
WARNING
PX4 support is a "work in progress". It doesn't officilly support GNSS, magnetomer or barometer. It is expected to use the branch with few additional features (opens new window).
PX4 supports the following gps, magnetometer and barometer related topics:
| PX4 parameter | Cyphal Data type and topic | Description |
|---|---|---|
| UCAN1_GPS0_SUB | ds015.service.gnss.Gnss.0.1 (opens new window) uavcan.sub.udral.gps.0.id | Main GNSS DS015 topic |
| UCAN1_GPSC00_SUB | ds015.service.gnss.Covariance.0.1 (opens new window) uavcan.sub.udral.cov.0.id | Covariance |
| UCAN1_MAG0_SUB | uavcan.si.sample.magnetic_field_strength.Vector3.1.1 (opens new window) uavcan.sub.udral.mag.0.id | Magnetic Field |
| UCAN1_BAROP0_SUB | uavcan.si.sample.pressure.Scalar.1.0 (opens new window) uavcan.sub.udral.baro.pressure.0.id | Barometer pressure |
| UCAN1_BAROT0_SUB | uavcan.si.sample.temperature.Scalar.1.0 (opens new window) uavcan.sub.udral.baro.temperature.0.id | Barometer temperature |
1. GNSS configuration
Assing the same port-ID for PX4-autopilot and GNSS node:
y r 1 uavcan.sub.udral.gps.0.id 2001
y r 50 uavcan.pub.ds015.gps.gnss.id 2001
Here, 1 is the autopilot node ID, 50 is GNSS_MAG_BARO id, 2001 is the desired port-ID. Replace this values with what you need.
Alternatively, you can assign PX4 port-ID via QGC throught UCAN1_GPS0_SUB parameter.
2. Magnetometer
Assing the same port-ID for PX4-autopilot and Magnetometer node:
y r 1 uavcan.sub.udral.mag.0.id 2402
y r 50 uavcan.pub.zubax.mag.id 2402
Alternatively, you can assign PX4 port-ID via QGC throught UCAN1_MAG0_SUB parameter.
On the picture below the first instance is related to Cyphal magnetometer.
3. Barometer
Assing the same port-ID for PX4-autopilot and Magnetometer node:
y r 1 uavcan.sub.udral.baro.pressure.0.id 2403
y r 1 uavcan.sub.udral.baro.temperature.0.id 2404
y r 50 uavcan.pub.zubax.baro.press.id 2403
y r 50 uavcan.pub.zubax.baro.temp.id 2404
Alternatively, you can assign PX4 port-ID via QGC throught UCAN1_BAROT0_SUB, UCAN1_BAROP0_SUB parameters.
4. Check other topics
Be careful, different topics should not have the same port ID. You may need to check setpoint and readiness topics:
| PX4 parameter | Cyphal Data type and topic | Description |
|---|---|---|
| UCAN1_ESC_PUB | reg.udral.service.actuator.common.sp/* (opens new window) uavcan.pub.udral.esc.0.id | Setpoint topic |
| UCAN1_READ_PUB | reg.udral.service.common.Readiness.0.1 uavcan.pub.udral.readiness.0.id | Readiness topic |
# 5.6. Ardupilot integration
WARNING
Ardupilot doesn't officially support Cyphal. It is expected to use the custom cyphal branch of ardupilot (opens new window).
1. GPS configuration
At least the following Ardupilot parameters should be configured:
| Parameter | Value | Description |
|---|---|---|
| GPS_TYPE | 26 | means Cyphal |
The following Ardupilot Cyphal registers should have the same port identifiers as GPS:
| Register | Type |
|---|---|
| uavcan.sub.gps.point.id | reg.zubax.physics.kinematics.geodetic.PointStateVarTs.0.1 |
| uavcan.sub.gps.sats.id | uavcan.primitive.scalar.Integer16.1.0 |
| uavcan.sub.gps.status.id | uavcan.primitive.scalar.Integer16.1.0 |
| uavcan.sub.gps.pdop.id | uavcan.primitive.scalar.Integer16.1.0 |
It is recommended to verify the correctness of the configuration with Yukon as shown below:
2. Magnetometer configuration
The following Ardupilot Cyphal registers should have the same port identifiers as Magnetometer:
| Register | Type |
|---|---|
| uavcan.sub.mag.id | uavcan.si.sample.magnetic_field_strength.Vector3.1.0 |
3. Barometer configuration
The following Ardupilot Cyphal registers should have the same port identifiers as Barometer:
| Register | Type |
|---|---|
| uavcan.sub.baro.pres.id | uavcan.si.sample.pressure.Scalar.1.0 (opens new window) |
| uavcan.sub.baro.temp.id | uavcan.si.sample.temperature.Scalar.1.0 |
4. Verification
# 5.7. Software versions
GNSS hardware v3 (stm32g0):
| Version | Description |
|---|---|
| v1.5.1_45c1de7 (opens new window) Sep 11, 2023 | - A few fixes related to violation of the Cyphal standard |
| v1.5.0_d3939cc (opens new window) Aug 24, 2023 | - Add DS015 topics - Add covariance from NavPvtCov - Add status from NavPvtStatus - Add auto configuration - Add UDRAL prefix to related topics - Add LEDs meaning based on GNSS health and mode - Add serial forwarder - Add baudrate parameter |
| v1.4.0_52df65ce (opens new window) Jun 19, 2023 | - Fix default name |
| v1.3.0_b54968b (opens new window) Apr 26, 2023 | - First release for ZED-F9P - Fix port.List issue - Add diagnostic.Record |
GNSS hardware v2 (stm32f103):
| Version | Description |
|---|---|
| v1.6.5_c78d47c3 (opens new window) Dec 19, 2023 | - Improve GNSS configuration - Improve self-diagnostics - Improve LED meaning system |
| v1.5.6_c440c82 (opens new window) Oct 05, 2023 | - A few fixes related to violation of the Cyphal standard |
| v1.2.14_b4e042b (opens new window) Feb 23, 2023 | Knows issues: port.List sometimes is not correct. - Add Barometer and external RGB LED - Add port.List - Add hardware version - Extend git hash length to 64 bit - Few fixes |
| v1.1.3_5fe78e3 (opens new window) Dec 01, 2022 | - Fix mag scaling (use teslas instead of gausses) |
| v1.0.5_1d52004 (opens new window) Oct 31, 2022 | - Improve gps accuracy |
| v1.0.1_47a71fd (opens new window) Oct 23, 2022 | - Initial version |