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