# 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:
№ | Type | Message | Topic name | Rate |
---|---|---|---|---|
1 | pub | uavcan.si.sample.voltage.Scalar.1.0 | crct.5v | 2 Hz |
2 | pub | uavcan.si.sample.voltage.Scalar.1.0 | crct.vin | 2 Hz |
3 | pub | uavcan.si.sample.temperature.Scalar.1.0 | crct.dev_temp | 2 Hz |
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: UDRAL and DS015. You should use only one interface at the same time.
The following interface is based on UDRAL:
№ | Type | Message | Topic name | Rate |
---|---|---|---|---|
1 | pub | PointStateVarTs.0.1 (opens new window) | gps.zubax.point (geodetic position and velocity) | 5-10 Hz |
2 | pub | uavcan.si.sample.angle.Scalar (opens new window) | gps.zubax.yaw (not supported yet) | 5-10 Hz |
3 | pub | uavcan.primitive.scalar.Integer16 | gps.zubax.sats | 5-10 Hz |
4 | pub | uavcan.primitive.scalar.Integer16 | gps.zubax.status | 5-10 Hz |
5 | pub | uavcan.primitive.scalar.Integer16 | gps.zubax.pdop | 5-10 Hz |
The following interface is based on DS015 proposal:
№ | Type | Message | Topic name | Rate |
---|---|---|---|---|
1 | pub | ds015.service.gnss.Gnss.0.1 (opens new window) | gps.ds015.gnss | 5-10 Hz |
2 | pub | ds015.service.gnss.Covariance.0.1 (opens new window) | gps.ds015.cov | 5-10 Hz |
3 | pub | uavcan.time.SynchronizedTimestamp.1.0 (opens new window) | gps.time_utc | 5-10 Hz |
The following features are not implemented yet, but they will appear soon:
№ | Type | Message | Topic name |
---|---|---|---|
1 | pub | ds015.service.gnss.RelativePosition.0.1 (opens new window) | gps.ds015.relpos (not yet) |
2 | sub | probably String.1.0 (opens new window) | gps.rtk |
3 | sub | probably String.1.0 (opens new window) | gps.moving_baseline |
Barometer service
Barometer service is based on BMP280 (opens new window) sensor.
№ | Type | Message | Topic name | Rate |
---|---|---|---|---|
1 | pub | uavcan.si.sample.pressure.Scalar.1.0 | baro.press | 30 Hz |
2 | pub | uavcan.si.sample.temperature.Scalar.1.0 | baro.temp | 30 Hz |
Magnetometer service
Magnetometer service is based on RM3100 (opens new window) sensor.
№ | Type | Message | Topic name | Rate |
---|---|---|---|---|
1 | pub | uavcan.si.sample.magnetic_field_strength.Vector3.1.0 | mag | 75 Hz |
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.
№ | Type | Message | Topic name |
---|---|---|---|
1 | pub | uavcan.metatransport.serial.Fragment.0.2 (opens new window) | gps.ubx_rx |
2 | sub | uavcan.metatransport.serial.Fragment.0.2 (opens new window) | gps.ubx_tx |
# 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. 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 (bench test)
Before mounting on a real vehicle, especially when using the node for the first time, it is recommended to test the node and perform configuration on a bench using Yakut (opens new window) cli or Yukon (opens new window) gui.
This section provides a step-by-step checklist to test most features and configure essential parameters.
# Step 1. Connect the Device
Upon connection, the node should blink with a blue color. For bench testing and configuration, refer to the connection scheme below:
In this setup:
- The
gnss_mag_baro
node connects to a CAN sniffer via a JST-GH 4 connector. - The sniffer then connects to a PC via USB, which also powers the node.
Note: Alternatively, in a vehicle you may want to connect the node via Molex CAN connector.
# 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.
# Using Yakut CLI
Run the following command:
yakut monitor
You should see the output similar to the one shown below:
# Using Yukon GUI
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.
# Step 4: Configure and Read the Data
# 1. Register 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"
}
}
# 2. GNSS Data Retrieval
# Set up the register for GNSS data:
y r 50 uavcan.pub.ds015.gps.gnss.id 2001
After this, if you run yakut register-list 50
, you'll find the register changed.
# Start listening to the GNSS data:
yakut subscribe 2001
Or, the shorter version:
y s 2001
Position the antenna by a window to detect satellites.
Output Example:
status: {status: 3, mode: 0, sub_mode: 0, jamming_state: 0, spoofing_state: 0}
time_week_ms: 564101000
time_week: 2280
point:
latitude: 1.036692266636593
longitude: 0.43040356342810226
altitude: {meter: 45.83700561523438}
velocity:
meter_per_second: [0.0020000000949949026, 0.003000000026077032, -0.03799999877810478]
yaw: {radian: 0.0}
horizontal_accuracy: 0.68701171875
vertical_accuracy: 1.1513671875
speed_accuracy: 0.218017578125
yaw_accuracy: {radian: 1.499834418296814}
hdop: 1.01953125
vdop: 1.01953125
num_sats: 22
Note: Latitude and longitude values are in radians. Convert to degrees by multiplying by (180/π)
.
# 3. Magnetic Field Data Retrieval
y r 50 uavcan.pub.zubax.mag.id 4000
y s 4000
Output Example:
timestamp: {...}
ampere_per_meter: [...]
# 4. Barometric Pressure Data Retrieval
y r 50 uavcan.pub.zubax.baro.press.id 5001
y s 5001
Output Example:
timestamp: {...}
pascal: 100701.0703125
# 5. Temperature Data Retrieval
y r 50 uavcan.pub.zubax.baro.temp.id 5002
y s 5002
Output Example:
timestamp: {...}
kelvin: 308.5393371582031
# 6. Circuit Status Data Retrieval
Configure the ports:
y r 50 uavcan.pub.crct.5v.id 4006
y r 50 uavcan.pub.crct.temp.id 4007
y r 50 uavcan.pub.crct.vin.id 4008
Listen to the data:
y s 4006
# or
y s 4007
# or
y s 4008
Outputs Examples:
timestamp: {...}
volt: 5.10432243347168
timestamp: {...}
kelvin: 298.0
timestamp: {...}
volt: 4.712674140930176
# Step 5: Try Node Control Commands
Issue a restart command:
y cmd 50 restart
Note: Receiving Timed out while waiting for response from node 50
is expected, as the node restarts immediately.
Reset to defaults (Attention: registers configuration would be reset):
y cmd 50 factory
# 5.4. 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 |
uavcan.sub.baro.temp.id | uavcan.si.sample.temperature.Scalar.1.0 |
4. Verification
# 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).
1. GNSS configuration
To enable GNSS you should configure the following PX4 Cyphal ports: udral.gps.0
, udral.gps.pdop.0
, udral.gps.sats.0
and udral.gps.status.0
.
2. Magnetometer
To enable magnetometer, you should configure the following PX4 Cyphal ports: udral.mag.0
.
On the picture below the first instance is related to Cyphal magnetometer.
3. Barometer
To enable magnetometer and barometer, you should configure the following PX4 Cyphal registers: udral.baro.0
.
# 5.6. 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.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 |