Canandgyro¶

Message/wire format spec, version 2024-offseason.

The device spec for Redux products will not change in a backwards-incompatible fashion in-season, from the first official release for a given year until after the FIRST Championship.

General properties¶

FRC CAN Device Type	0x4
DBC File	Link
Inherits from	[CanandDevice]

The DBC files assumes a device id of 0. For more information on the CAN device type, see CanandDevice

All value fields are default unsigned little-endian unless otherwise specified.

This document uses the following conventions for notating field types:

Type	Description
bool	Single-bit boolean
float:24	IEEE 754 single-precision float with the least significant 8 bits of mantissa stripped to fit in 3 bytes
float:32	IEEE 754 single-precision (32-bit) float
float:64	IEEE 754 double-precision (64-bit) float
uintN_t	Unsigned integer of bit width N
intN_t	Signed integer of bit width N
padN_t	N bits of padding bits that should be left zero.
uint8_t[N]	N bytes of a byte array

Additionally, when literals are specified for default values,

true and false are defined as bit values 1 and 0 respectively
for a byte array specified as {0x1, 0x2, 0x3, 0x4} the first (index zero) byte is 0x1 and the last is 0x4.

Messages¶

These are the definitions of messages sent over CAN, USB, or other encapsulation mechanisms.

Message summary:

API Index	Message	Description
0x1f	YAW_OUTPUT	Yaw angle frame
0x1e	ANGULAR_POSITION_OUTPUT	Angular position quaternion frame
0x1d	ANGULAR_VELOCITY_OUTPUT	Angular velocity frame
0x1c	ACCELERATION_OUTPUT	Acceleration frame
0x1b	CALIBRATE	Trigger Calibration
0x1a	CALIBRATION_STATUS	Calibration Status
0xb	ENUMERATE	Device enumerate response
0x7	PARTY_MODE	Party mode
0x6	STATUS	Status frame
0x5	CLEAR_STICKY_FAULTS	Clear device sticky faults
0x4	REPORT_SETTING	setting value report from device
0x3	SET_SETTING	update setting on device
0x2	SETTING_COMMAND	setting control command

YAW_OUTPUT¶

Periodic frame with the Canandgyro’s yaw value at full 32-bit float precision in radians.

The period at which this message is broadcasted at is controlled by the YAW_FRAME_PERIOD setting.

Properties

Property	Value
API Index	0x1f
Message length	6 bytes
Transmission direction	Device -> robot
Frame period setting	YAW_FRAME_PERIOD
Default frame period	10 milliseconds

Signals

Signal name	Signal type	Optional	Description
`yaw`	yaw	❌	Yaw value

ANGULAR_POSITION_OUTPUT¶

Periodic frame with an angular position quaternion.

The quaternion is normalized and all values are scaled between -1.0 to 1.0 inclusive with one LSB being 1/32767-th of a magnitude. Users are still encouraged to re-normalize this quaternion if converted to other representations.

The minimum step size of this output when converted to Euler angles is approximately 0.004 degrees.

The period at which this message is broadcasted at is controlled by the ANGULAR_POSITION_FRAME_PERIOD setting.

Properties

Property	Value
API Index	0x1e
Message length	8 bytes
Transmission direction	Device -> robot
Frame period setting	ANGULAR_POSITION_FRAME_PERIOD
Default frame period	20 milliseconds

Signals

Signal name	Signal type	Optional	Description
`w`	quat16	❌	Quaternion w term
`x`	quat16	❌	Quaternion x term
`y`	quat16	❌	Quaternion y term
`z`	quat16	❌	Quaternion z term

ANGULAR_VELOCITY_OUTPUT¶

Periodic frame containing angular velocity.

The period at which this message is broadcasted at is controlled by the ANGULAR_VELOCITY_FRAME_PERIOD setting.

Properties

Property	Value
API Index	0x1d
Message length	6 bytes
Transmission direction	Device -> robot
Frame period setting	ANGULAR_VELOCITY_FRAME_PERIOD
Default frame period	100 milliseconds

Signals

Signal name	Signal type	Optional	Description
`yaw`	angular_velocity	❌	Yaw velocity
`pitch`	angular_velocity	❌	Pitch velocity
`roll`	angular_velocity	❌	Roll velocity

ACCELERATION_OUTPUT¶

Periodic frame containing linear acceleration.

The period at which this message is broadcasted at is controlled by the ACCELERATION_FRAME_PERIOD setting.

Properties

Property	Value
API Index	0x1c
Message length	6 bytes
Transmission direction	Device -> robot
Frame period setting	ACCELERATION_FRAME_PERIOD
Default frame period	100 milliseconds

Signals

Signal name	Signal type	Optional	Description
`z`	acceleration	❌	Z-axis acceleration
`y`	acceleration	❌	Y-axis acceleration
`x`	acceleration	❌	X-axis acceleration

CALIBRATE¶

Manually triggers gyro calibration. This takes about 5 seconds.

Properties

Property	Value
API Index	0x1b
Message length	8 bytes
Transmission direction	Robot -> device

Signals

Signal name	Signal type	Optional	Description
`calibration_type`	CALIBRATION_TYPE	❌	Calibration type
`reserved`	`pad56_t`	❌	Reserved

CALIBRATION_STATUS¶

Sent from the device when calibration completes.

Properties

Property	Value
API Index	0x1a
Message length	8 bytes
Transmission direction	Device -> robot

Signals

Signal name	Signal type	Optional	Description
`reserved`	`pad64_t`	❌	Reserved

ENUMERATE¶

Sent by the device upon an enumerate request, or every 100 milliseconds if the device is stuck in OTA bootloader.

The exact format of enumerate request may vary between communication mediums:

for a CAN bus an enumerate request is a message with an extended (29-bit) arbitration ID of 0xE0000

Properties

Property	Value
API Index	0xb
Message length	8 bytes
Transmission direction	Device -> robot

Signals

Signal name	Signal type	Optional	Description
`serial`	`uint8_t[6]`	❌	Device-unique serial number
`is_bootloader`	`bool`	❌	Device is in bootloader.
`reserved`	`pad15_t`	❌	Reserved

PARTY_MODE¶

Configures party mode to the device.

Non-zero values will prompt the onboard RGB LED of the device to cycle various colors to help identify where it physically sits on a robot.

A zero value stops the cycling.

Properties

Property	Value
API Index	0x7
Minimum message length	1 bytes
Maximum message length	8 bytes
Transmission direction	Robot -> device

Signals

Signal name	Signal type	Optional	Description
`party_level`	`uint8_t`	❌	Party level. 0 disables the strobe, whereas each increased value up to 10 increases strobe period by 50 ms.

STATUS¶

Status frame containing active and sticky fault data as well as temperature.

The period at which this message is broadcasted at is controlled by the STATUS_FRAME_PERIOD setting.

Properties

Property	Value
API Index	0x6
Message length	8 bytes
Transmission direction	Device -> robot
Frame period setting	STATUS_FRAME_PERIOD
Default frame period	100 milliseconds

Signals

Signal name	Signal type	Optional	Description
`faults`	faults	❌	8-bit active faults bitfield
`sticky_faults`	faults	❌	8-bit sticky faults bitfield
`temperature`	temperature	❌	16-bit signed temperature byte in 1/256ths of a Celsius
`reserved`	`pad32_t`	❌	Reserved bits

CLEAR_STICKY_FAULTS¶

Sent to device to clear all sticky faults (sets the sticky faults to 0 until faults become active again)

Properties

Property	Value
API Index	0x5
Minimum message length	0 bytes
Maximum message length	8 bytes
Transmission direction	Robot -> device

Signals

Signal name	Signal type	Optional	Description

REPORT_SETTING¶

Sent to report a setting value from the device.

These messages can be triggered by:

a setting change via the set setting message
the fetch setting value setting command
a reset to factory default setting command
other device-specific mechanisms including device-specific setting commands

The setting flags include information on whether or not the setting set was successful as well as the setting data that was sent.

Sent after a setting change via or on the fetch settings and factory reset Setting changes (as of v2024) will always include the “settings flag” field.

Properties

Property	Value
API Index	0x4
Message length	8 bytes
Transmission direction	Device -> robot

Signals

Signal name	Signal type	Optional	Description
`address`	Setting index	❌	Setting index to write to
`value`	setting_data	❌	6-byte setting value
`flags`	setting_report_flags	❌	Setting receive status

SET_SETTING¶

Sent to device to change a setting by address.

If the setting exists, a report setting packet will be sent in reply, with the data of the setting echoed back and information on whether or not the setting set succeeded.

Properties

Property	Value
API Index	0x3
Message length	8 bytes
Transmission direction	Robot -> device

Signals

Signal name	Signal type	Optional	Description
`address`	Setting index	❌	Setting index to write to
`value`	setting_data	❌	6-byte setting value
`flags`	setting_flags	❌	Setting flags

SETTING_COMMAND¶

Sent to the device to operate on the settings subsystem.

Devices may add their own setting commands but they will typically at least have:

fetch all settings (id 0x0)
reset all applicable settings to factory default (id 0x1)
fetch setting value (id 0x2)

Most setting commands (e.g. reset to factory default and get all settings) are allowed to have a data length code of 1, however, the fetch setting value command requires a data length of at least 2 bytes to also specify the setting index to fetch.

The most typical use case is likely to fetch a specific setting value; to fetch firmware version for example one might send this packet with the payload {0x2, 0x6} and wait for a report setting to report the setting.

Properties

Property	Value
API Index	0x2
Minimum message length	1 bytes
Maximum message length	8 bytes
Transmission direction	Robot -> device

Signals

Signal name	Signal type	Optional	Description
`control_flag`	SETTING_COMMAND	❌	Setting command index
`setting_index`	Setting index	✅	setting index to fetch

Settings¶

Settings hold and manipulate the configuration of the device.

Most settings are saved to non-volatile flash, are saved on device reboot, are considered both readable and writable, and will be reset to a default value when a reset to factory default setting command is issued.

Some settings are read-only as they contain device or firmare specific infomation such as serial number or firmware version.

Other settings may be write-only as they command the device to do something specific; e.g. update an offset. In practice, settings get used whenever an infrequent (non-periodic) call-response architecture makes sense spec-wise.

Each setting is associated with an 8-bit unsigned setting index byte. Setting data is encoded as 48-bit (6 byte) fields. Both setting index and encoded setting data are sent in set setting and report_setting messages, whereas the fetch setting value setting command only requires an index.

If a type associated with a setting is less than 48 bits wide (e.g. a float32), the rest of the data field during encode/decode can be assumed to be padding and left as zero.

Setting summary:

Setting index	Name	Type	Default value	Readable	Writable	Resets to factory default	Description
0xff	YAW_FRAME_PERIOD	frame_period	10	✅	✅	✅	Yaw angle frame period (ms)
0xfe	ANGULAR_POSITION_FRAME_PERIOD	frame_period	20	✅	✅	✅	Angular position frame period (ms)
0xfd	ANGULAR_VELOCITY_FRAME_PERIOD	frame_period	100	✅	✅	✅	Angular velocity frame period (ms)
0xfc	ACCELERATION_FRAME_PERIOD	frame_period	100	✅	✅	✅	Acceleration frame period (ms)
0xfb	SET_YAW	yaw	n/a	❌	✅	❌	Set yaw
0xfa	SET_POSE_POSITIVE_W	quat_xyz	n/a	❌	✅	❌	Set (normed) quaternion assuming positive W
0xf9	SET_POSE_NEGATIVE_W	quat_xyz	n/a	❌	✅	❌	Set (normed) quaternion assuming negative W
0xf8	GYRO_X_SENSITIVITY	prfloat32	n/a	✅	❌	❌	Gyro X axis sensitivity
0xf7	GYRO_Y_SENSITIVITY	prfloat32	n/a	✅	❌	❌	Gyro Y axis sensitivity
0xf6	GYRO_Z_SENSITIVITY	prfloat32	n/a	✅	❌	❌	Gyro Z axis sensitivity
0xf5	GYRO_X_ZRO_OFFSET	rfloat32	0	✅	✅	❌	Gyro X-axis calibrated ZRO offset
0xf4	GYRO_Y_ZRO_OFFSET	rfloat32	0	✅	✅	❌	Gyro Y-axis calibrated ZRO offset
0xf3	GYRO_Z_ZRO_OFFSET	rfloat32	0	✅	✅	❌	Gyro Z-axis calibrated ZRO offset
0xf2	GYRO_ZRO_OFFSET_TEMPERATURE	rfloat32	25	✅	✅	❌	Temperature at ZRO offset (celsius)
0xe7	TEMPERATURE_CALIBRATION_X_0	rfloat32	0	✅	✅	❌	Temp cal X-axis point 0
0xe6	TEMPERATURE_CALIBRATION_Y_0	rfloat32	0	✅	✅	❌	Temp cal Y-axis point 0
0xe5	TEMPERATURE_CALIBRATION_Z_0	rfloat32	0	✅	✅	❌	Temp cal Z-axis point 0
0xe4	TEMPERATURE_CALIBRATION_T_0	rfloat32	0	✅	✅	❌	Temp cal temperature point 0 (celsius)
0xe3	TEMPERATURE_CALIBRATION_X_1	rfloat32	0	✅	✅	❌	Temp cal X-axis point 1
0xe2	TEMPERATURE_CALIBRATION_Y_1	rfloat32	0	✅	✅	❌	Temp cal Y-axis point 1
0xe1	TEMPERATURE_CALIBRATION_Z_1	rfloat32	0	✅	✅	❌	Temp cal Z-axis point 1
0xe0	TEMPERATURE_CALIBRATION_T_1	rfloat32	0	✅	✅	❌	Temp cal temperature point 1 (celsius)
0x8	DEVICE_TYPE	`uint16_t`	n/a	✅	❌	❌	Device-specific type identifier
0x6	FIRMWARE_VERSION	firmware_version	n/a	✅	❌	❌	Firmware version
0x5	SERIAL_NUMBER	`uint8_t[6]`	n/a	✅	❌	❌	Serial number
0x4	STATUS_FRAME_PERIOD	frame_period	100	✅	✅	✅	Status frame period (ms)
0x3	NAME_2	`uint8_t[6]`	`[0x0, 0x0, 0x0, 0x0, 0x0, 0x0]`	✅	✅	✅	device_name[12:17]
0x2	NAME_1	`uint8_t[6]`	`[0x67, 0x79, 0x72, 0x6f, 0x0, 0x0]`	✅	✅	✅	device_name[6:11]
0x1	NAME_0	`uint8_t[6]`	`[0x43, 0x61, 0x6e, 0x61, 0x6e, 0x64]`	✅	✅	✅	device_name[0:5]
0x0	CAN_ID	can_device_id	`0`	✅	✅	❌	CAN Device ID

YAW_FRAME_PERIOD¶

Period between each transmission of YAW_OUTPUT messages.

A value of 0 disables transmission of the associated message altogether.

Property	Value
Setting index	0xff
Type	frame_period
Default value	10
Readable	✅
Writable	✅
Resets on factory default	✅

ANGULAR_POSITION_FRAME_PERIOD¶

Period between each transmission of ANGULAR_POSITION_OUTPUT messages.

A value of 0 disables transmission of the associated message altogether.

Property	Value
Setting index	0xfe
Type	frame_period
Default value	20
Readable	✅
Writable	✅
Resets on factory default	✅

ANGULAR_VELOCITY_FRAME_PERIOD¶

Period between each transmission of ANGULAR_VELOCITY_OUTPUT messages.

A value of 0 disables transmission of the associated message altogether.

Property	Value
Setting index	0xfd
Type	frame_period
Default value	100
Readable	✅
Writable	✅
Resets on factory default	✅

ACCELERATION_FRAME_PERIOD¶

Period between each transmission of ACCELERATION_OUTPUT messages.

A value of 0 disables transmission of the associated message altogether.

Property	Value
Setting index	0xfc
Type	frame_period
Default value	100
Readable	✅
Writable	✅
Resets on factory default	✅

SET_YAW¶

Updates the yaw (Z-axis) rotation with the new sent angular position.

In the firmware, this yaw is achieved by solving for the transformation required to rotate the currently integrated angular position quaternion to the new yaw angle.

For example, where the current quaternion has components \(w + x \hat{\mathbf{i}} + y\hat{\mathbf{j}} + z\hat{\mathbf{k}}\) with existing yaw \(\phi\) and new to-be-set yaw \(\phi_n\) the new quaternion is calculated by the following:

\[\left[\cos\left(\frac{1}{2}(\phi_n - \phi)\right) + \sin\left(\frac{1}{2}(\phi_n - \phi)\right)\hat{\mathbf{k}}\right] \cdot \left(w + x \hat{\mathbf{i}} + y\hat{\mathbf{j}} + z\hat{\mathbf{k}}\right)\]

Property	Value
Setting index	0xfb
Type	yaw
Default value	n/a
Readable	❌
Writable	✅
Resets on factory default	❌

SET_POSE_POSITIVE_W¶

Updates the current pose angular position quaternion, assuming a positive W value.

As settings are only 48 bits wide, only three components of a full normalized quaternion are sent, with the W (real) component being calculated as so (after re-scaling to -1.0 to 1.0 from the integer encoding):

\[w = \sqrt{1.0 - x^2 + y^2 + z^2}\]

If \(x^2 + y^2 + z^2 > 1.0\), the W component is assumed to be 0 and X, Y, and Z are rescaled such the quaternion still has a norm of 1.

Property	Value
Setting index	0xfa
Type	quat_xyz
Default value	n/a
Readable	❌
Writable	✅
Resets on factory default	❌

SET_POSE_NEGATIVE_W¶

Updates the current pose angular position quaternion, assuming a negative W value.

As settings are only 48 bits wide, only three components of a full normalized quaternion are sent, with the W (real) component being calculated as so (after re-scaling to -1.0 to 1.0 from the integer encoding):

\[w = -\sqrt{1.0 - x^2 + y^2 + z^2}\]

If \(x^2 + y^2 + z^2 > 1.0\), the W component is assumed to be 0 and X, Y, and Z are rescaled such the quaternion still has a norm of 1.

Property	Value
Setting index	0xf9
Type	quat_xyz
Default value	n/a
Readable	❌
Writable	✅
Resets on factory default	❌

GYRO_X_SENSITIVITY¶

Read-only factory-calibrated X-axis sensitivity value

Property	Value
Setting index	0xf8
Type	prfloat32
Default value	n/a
Readable	✅
Writable	❌
Resets on factory default	❌

GYRO_Y_SENSITIVITY¶

Read-only factory-calibrated Y-axis sensitivity value

Property	Value
Setting index	0xf7
Type	prfloat32
Default value	n/a
Readable	✅
Writable	❌
Resets on factory default	❌

GYRO_Z_SENSITIVITY¶

Read-only factory-calibrated Z-axis sensitivity value

Property	Value
Setting index	0xf6
Type	prfloat32
Default value	n/a
Readable	✅
Writable	❌
Resets on factory default	❌

GYRO_X_ZRO_OFFSET¶

Property	Value
Setting index	0xf5
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

GYRO_Y_ZRO_OFFSET¶

Property	Value
Setting index	0xf4
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

GYRO_Z_ZRO_OFFSET¶

Property	Value
Setting index	0xf3
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

GYRO_ZRO_OFFSET_TEMPERATURE¶

Saved temperature associated with the saved x/y/z-axis zero-motion angular velocity offset.

If calibration is run with the SAVE_ZRO calibration type, this setting will be updated with the new temperature at the end of calibration.

Property	Value
Setting index	0xf2
Type	rfloat32
Default value	25
Readable	✅
Writable	✅
Resets on factory default	❌

TEMPERATURE_CALIBRATION_X_0¶

Reserved.

Property	Value
Setting index	0xe7
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

TEMPERATURE_CALIBRATION_Y_0¶

Reserved.

Property	Value
Setting index	0xe6
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

TEMPERATURE_CALIBRATION_Z_0¶

Reserved.

Property	Value
Setting index	0xe5
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

TEMPERATURE_CALIBRATION_T_0¶

Reserved.

Property	Value
Setting index	0xe4
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

TEMPERATURE_CALIBRATION_X_1¶

Reserved.

Property	Value
Setting index	0xe3
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

TEMPERATURE_CALIBRATION_Y_1¶

Reserved.

Property	Value
Setting index	0xe2
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

TEMPERATURE_CALIBRATION_Z_1¶

Reserved.

Property	Value
Setting index	0xe1
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

TEMPERATURE_CALIBRATION_T_1¶

Reserved.

Property	Value
Setting index	0xe0
Type	rfloat32
Default value	0
Readable	✅
Writable	✅
Resets on factory default	❌

DEVICE_TYPE¶

Read-only device type identifier.

If multiple types of device share the same FRC-CAN device class, e.g. two device variants that do similar things but may or may not have the same message API, this setting can be used to disambiguate between them.

Property	Value
Setting index	0x8
Type	`uint16_t`
Default value	n/a
Readable	✅
Writable	❌
Resets on factory default	❌

FIRMWARE_VERSION¶

Read-only setting value of the device’s firmware version.

Property	Value
Setting index	0x6
Type	firmware_version
Default value	n/a
Readable	✅
Writable	❌
Resets on factory default	❌

SERIAL_NUMBER¶

Read-only setting of the device’s serial number.

Property	Value
Setting index	0x5
Type	`uint8_t[6]`
Default value	n/a
Readable	✅
Writable	❌
Resets on factory default	❌

STATUS_FRAME_PERIOD¶

Period between the transmission of status frame messages in milliseconds. This frame cannot be disabled (as Alchemist uses it to detect devices).

Property	Value
Setting index	0x4
Type	frame_period
Default value	100
Readable	✅
Writable	✅
Resets on factory default	✅

NAME_2¶

Last 6 bytes of the name field.

Having a null byte will terminate the name field at that byte.

All 6 bytes can be non-null and the name will be 18 characters long.

Property	Value
Setting index	0x3
Type	`uint8_t[6]`
Default value	`[0x0, 0x0, 0x0, 0x0, 0x0, 0x0]`
Readable	✅
Writable	✅
Resets on factory default	✅

NAME_1¶

Middle 6 bytes of the device name.

Having a null byte will terminate the name field at that byte.

Property	Value
Setting index	0x2
Type	`uint8_t[6]`
Default value	`[0x67, 0x79, 0x72, 0x6f, 0x0, 0x0]`
Readable	✅
Writable	✅
Resets on factory default	✅

NAME_0¶

First 6 bytes of the device name.

Having a null byte will terminate the name field at that byte.

Property	Value
Setting index	0x1
Type	`uint8_t[6]`
Default value	`[0x43, 0x61, 0x6e, 0x61, 0x6e, 0x64]`
Readable	✅
Writable	✅
Resets on factory default	✅

CAN_ID¶

Sets the 6-bit device id, ranging from 0 to 63. This allows multiple of a device to share a bus.

Defaults to 0 but does not reset on factory resets.

Property	Value
Setting index	0x0
Type	can_device_id
Default value	`0`
Readable	✅
Writable	✅
Resets on factory default	❌

Types¶

Data types associated with messages and/or settings.

frame_period¶

Frame period associated with some periodic data or status frame. 1 LSB equals 1 ms of period, and setting the period to 0 will disable the corresponding frame.

Property	Value
Base type	uint
Bit width	16
Minimum value	0
Maximum value	65535
Default value	0
Conversion factor	1 LSB = \(\frac{1}{1000}\) seconds

status_frame_period¶

Frame period specific to the status frame, as status frames cannot be set to 0 and disabled.

Property	Value
Base type	uint
Bit width	16
Minimum value	1
Maximum value	16383
Default value	1000
Conversion factor	1 LSB = \(\frac{1}{1000}\) seconds

can_device_id¶

The CAN device id used by the device. As specified by the FRC-CAN spec, this comprises the least significant 6 bits of the CAN id.

Property	Value
Base type	uint
Bit width	8
Minimum value	0
Maximum value	63
Default value	0

setting_flags¶

Information set on the set settings message.

Setting the ephemeral bit makes the setting not save to non-volatile memory and not persist on reboot, if applicable.

Sending multiple messages with the synch hold message will queue them for application on device until a message with the bit unset and the number of messages expected to be in the queue (in synch_msg_count) is set.

If the number of settings in the queue equals the number of settings in synch_message_count, all settings are applied and a report settings message with the commit_success bit is set. Otherwise, none of them are applied and the commit success bit is unset.

Original Canandmags do not support the synch hold mechanism.

Property	Value
Base type	struct
Bit width	8

Signals:

Name	Type	Default value	Description
`ephemeral`	`bool`	`false`	Whether the setting should be set ephemeral
`synch_hold`	`bool`	`false`	Whether the setting should be held until the next synch barrier
`reserved_0`	`pad2_t`	`0`	Reserved
`synch_msg_count`	`uint4_t`	`0`	Synch message count

setting_report_flags¶

Bits set by the report setting message to indicate success or failure

Property	Value
Base type	bitset
Bit width	8

Flags:

Flag index	Flag name	Default value	Description
0	set_success	0	Whether the setting set/fetch was successful
1	commit_success	0	Whether the setting synch commit was successful

firmware_version¶

Firmware version reported by the device.

Property	Value
Base type	struct
Bit width	32

Signals:

Name	Type	Default value	Description
`firmware_patch`	`uint8_t`	`0`	Firmware version patch number
`firmware_minor`	`uint8_t`	`0`	Firmware version minor number
`firmware_year`	`uint16_t`	`0`	Firmware version year

rfloat32¶

An IEEE single-precision float32 that cannot be NaN or infinite.

Property	Value
Base type	float
Bit width	32
Minimum value	n/a
Maximum value	n/a
Default value	0

pfloat32¶

An IEEE single-precision float32 that must be non-negative but may be NaN or infinite.

Property	Value
Base type	float
Bit width	32
Minimum value	0.0
Maximum value	n/a
Default value	0

prfloat32¶

An IEEE single-precision float32 that must be non-negative AND cannot be NaN or infinite.

Property	Value
Base type	float
Bit width	32
Minimum value	0.0
Maximum value	n/a
Default value	0

lfloat32¶

An IEEE single-precision float32 constrained between 0 and 1 inclusive.

Property	Value
Base type	float
Bit width	32
Minimum value	0.0
Maximum value	1.0
Default value	0

temperature¶

Temperature as reported to/from the device. 1 LSB = 1/256th of a degree Celsius.

Property	Value
Base type	sint
Bit width	16
Minimum value	-32768
Maximum value	32767
Default value	0
Conversion factor	1 LSB = \(\frac{1}{256}\) deg C

temp_cal_point¶

Temperature calibration point.

This is used to represent zero-offset values for each angular XYZ axis at different temperatures. Onboard temperature compensation will then use these values to account for the effect on temperature on the gyro IC.

Property	Value
Base type	struct
Bit width	48

Signals:

Name	Type	Default value	Description
`temperature_point`	temperature	0	Temperature point
`offset`	rfloat32	0	Offset at the temperature

quat16¶

A component of a normalized quaternion as a 16-bit signed fixed-point integer. -1.0 corresponds to -32767 while +1.0 corresponds to +32767.

Property	Value
Base type	sint
Bit width	16
Minimum value	-32767
Maximum value	32767
Default value	0

quat_xyz¶

A compacted representation of a normalized quaternion with just three axes, used to fit in less bytes. Combined with external information about the sign of the W component, the original quaternion is recovered by considering that \(|w| = \sqrt{1.0 - (x^2 + y^2 + z^2)}\)

Property	Value
Base type	struct
Bit width	48

Signals:

Name	Type	Description
`x`	quat16	Quaternion x term
`y`	quat16	Quaternion y term
`z`	quat16	Quaternion z term

yaw¶

Yaw frame data. The absolute (single-turn) yaw is broadcast in radians between -pi inclusive and pi exclusive. Counterclockwise is positive and clockwise is negative.

The wraparound component counts the number of rotations past the wraparound point at ±pi. A full multiturn yaw can be computed by taking \(\text{yaw} + \text{wraparound} * 2\pi\)

Property	Value
Base type	struct
Bit width	48

Signals:

Name	Type	Default value	Description
`yaw`	`float32_t`	`0.0`	Yaw angle (f32 between [-pi..pi) radians)
`wraparound`	`int16_t`	`0`	Wraparound counter

angular_velocity¶

Angular velocity value.

Property	Value
Base type	sint
Bit width	16
Minimum value	-32768
Maximum value	32767
Default value	0
Conversion factor	1 LSB = \(\frac{2000}{32767}\) deg/s

acceleration¶

Acceleration value.

Property	Value
Base type	sint
Bit width	16
Minimum value	-32768
Maximum value	32767
Default value	0
Conversion factor	1 LSB = \(\frac{1}{2048}\) gravities

faults¶

Fault flags as used in active faults and sticky faults.

Active faults will keep each flag set only as long as they are currently an active condition, while sticky faults will latch them to true once set until cleared via the clear sticky faults message.

Property	Value
Base type	bitset
Bit width	8

Flags:

Flag index	Flag name	Description
0	power_cycle	The power cycle fault flag, which is set to true when the device first boots. Clearing sticky faults and then checking this flag can be used to determine if the device rebooted.
1	can_id_conflict	The CAN ID conflict flag, which is set to true if there is a CAN id conflict. In practice, you should physically inspect the device to ensure it’s not flashing blue.
2	can_general_error	The CAN general error flag, which will raise if the device encounters a CAN fault during operation. If communication with the device still functions, this will not register as an active fault for long if at all. This may raise due to wiring issues, such as an intermittently shorted CAN bus.
3	out_of_temperature_range	The temperature range flag, which will raise if the device is not between 0-70 degrees Celsius. This may be of concern if the device is near very active motors.
4	hardware_fault	The hardware fault flag, which will raise if a hardware issue is detected. Generally will raise if the device’s controller cannot read the physical sensor itself.
5	calibrating	The calibration status flag, which will raise if the device is currently calibrating.
6	angular_velocity_saturation	The angular velocity saturation flag, which triggers on saturation of angular velocity.
7	acceleration_saturation	The acceleration saturation flag, which triggers on saturation of acceleration.

Enums¶

Enums associated with messages and/or settings. The backing type is always an unsigned int of some specified width.

CALIBRATION_TYPE¶

Type of calibration to be run, as specified by the calibration packet.

Normal calibration updates the zero-movement offset without saving it to flash to seed the next on-boot calibration. Save-zro calibration will save it to flash.

Temp calibration variants will report the current temperature and offset values on calibration completion for a client to consider if those values should be written back via the settings interface.

Property	Value
Bit width	8
Default enum	NORMAL

Enum variants:

Enum index	Variant name	Description
0x0	NORMAL	Normal calibration routine
0x1	SAVE_ZRO	Save ZRO at calibration complete
0x2	TEMP_CAL_0	Temperature calibrate slot 0
0x3	TEMP_CAL_1	Temperature calibrate slot 1

SETTING_COMMAND¶

These are setting commands issued via the setting command message.

The fetch setting command and reset factory settings command are common to all Redux devices.

Property	Value
Bit width	8
Default enum

Enum variants:

Enum index	Variant name	Description
0x0	FETCH_SETTINGS	Fetch all settings from device via a series of report setting messages of all indexes
0x1	RESET_FACTORY_DEFAULT	Reset all resettanble settings to factory default, and broadcast all setting values via report setting messages.
0x2	FETCH_SETTING_VALUE	Requests to fetch a single setting from device, with its value reported via the report setting message. This requires the use of the second byte to specify the setting index to fetch.