Canandmag¶

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	0x7
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	POSITION_OUTPUT	Position frame
0x1e	VELOCITY_OUTPUT	Velocity frame
0x1d	RAW_POSITION_OUTPUT	Raw position frame
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

POSITION_OUTPUT¶

Periodic frame with relative position and absolute position registers read by the device.

Absolute and relative position operate (mostly) independently; absolute position has a persistent zero offset that is subtracted from the raw zero reading and is limited to a single rotation whereas relative position always initializes to 0 on boot and counts across multiple turns.

Both absolute and relative position have their outputs set to 0 when the zero button is pressed for 2 seconds, and both absolute and relative position will always count up and count down in the same direction at the same rate.

The absolute position value is also what gets sent over PWM, and so will also be affected by the zero offset.

For both relative (unwrapped) and absolute position, one device tick is 1/16384-th of a rotation.

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

Properties

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

Signals

Signal name	Signal type	Optional	Description
`relative_position`	relative_position	❌	32-bit signed relative position in 1/16384-ths of a rotation. This value does not persist on reboots.
`magnet_status`	magnet_status	❌	2-bit magnet status. If both bits are zero, the magnet is in range.
`absolute_position`	absolute_position	❌	14-bit unsigned absolute position in 1/16384-ths of a rotation. The zero offset of the absolute encoder will preserve through reboots.

VELOCITY_OUTPUT¶

Periodic frame containing the currently calculated velocity.

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

Properties

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

Signals

Signal name	Signal type	Optional	Description
`velocity`	velocity	❌	Velocity as a 22-bit signed integer. One velocity tick corresponds to 1/1024th of a rotation per second.
`magnet_status`	magnet_status	❌	2-bit magnet status. If both bits are zero, the magnet is in range.

RAW_POSITION_OUTPUT¶

Periodic frame containing a raw absolute reading that does not account for the zero offset or inversion settings. Additionally includes a reading timestamp in milliseconds and magnet status data.

By factory default, this frame is disabled (0 ms) – it needs to be explicitly enabled to be used.

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

Properties

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

Signals

Signal name	Signal type	Optional	Description
`raw_position`	absolute_position	❌	14-bit raw absolute position in 1/16384-ths of a rotation.
`magnet_status`	magnet_status	❌	2-bit magnet status. If both bits are zero, the magnet is in range.
`timestamp`	`uint32_t`	❌	32-bit sensor reading timestamp in microseconds since device boot.

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¶

Periodic 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	1000 milliseconds

Signals

Signal name	Signal type	Optional	Description
`faults`	faults	❌	8-bit active faults bitfield
`sticky_faults`	faults	❌	8-bit sticky faults bitfield
`temperature`	`int8_t`	❌	8-bit signed temperature byte in Celsius
`reserved`	`pad40_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	ZERO_OFFSET	zero_offset	Type default	✅	✅	✅	Encoder zero offset
0xfe	VELOCITY_WINDOW	velocity_window	100	✅	✅	✅	Velocity window width (value*250us)
0xfd	POSITION_FRAME_PERIOD	frame_period	20	✅	✅	✅	Position frame period (ms)
0xfc	VELOCITY_FRAME_PERIOD	frame_period	20	✅	✅	✅	Velocity frame period (ms)
0xfb	RAW_POSITION_FRAME_PERIOD	frame_period	0	✅	✅	✅	Raw position frame period (ms)
0xfa	INVERT_DIRECTION	`bool`	0	✅	✅	✅	Invert direction (0=ccw, 1=cw)
0xf9	RELATIVE_POSITION	relative_position	n/a	❌	✅	❌	Set relative position value
0xf8	DISABLE_ZERO_BUTTON	`bool`	0	✅	✅	✅	Disable the zero button
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	status_frame_period	1000	✅	✅	✅	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]`	`[0x6d, 0x61, 0x67, 0x0, 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

ZERO_OFFSET¶

This setting is used to update the absolute position broadcasted by the position message and over PWM.

Absolute position is calculated as:

\[\text{absolute position} = (\text{raw IC reading} - \text{saved zero offset}) \mod (1 rotation)\]

with some additional logic to handle direction inversion.

There are two methods to updating the absolute position:

updating the zero offset (saved in flash) subtracted from the raw encoder IC reading directly
taking a new intended absolute encoder reading and calculating the zero offset required to read the new value

The former has some niche uses but the latter is by far the most common application (e.g. to zero the encoder position).

This setting can update the zero offset via either approach via the position bit. If the position bit is set, the sent value is treated as a new absolute position, but if unset, the sent value is treated as a new zero offset.

If this setting is read from, the zero offset is always returned with the position bit unset.

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

VELOCITY_WINDOW¶

Controls the number of samples used to average in the velocity window. Samples occur once every 250 microseconds.

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

POSITION_FRAME_PERIOD¶

:frame_period:msg_position_output

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

VELOCITY_FRAME_PERIOD¶

:frame_period:msg_velocity_output

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

RAW_POSITION_FRAME_PERIOD¶

:frame_period:msg_raw_position_output

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

INVERT_DIRECTION¶

This setting whether counter clockwise or clockwise relative to the Canandmag’s sensor face (the side opposite its LED) should be positive for position (both relative and absolute) and velocity.

This will additionally invert the direction of the absolute PWM output as well.

False (0) means counter clockwise is positive, true (1) specifies clockwise is positive.

This setting affects the direction of both absolute and relative position.

Property	Value
Setting index	0xfa
Type	`bool`
Default value	0
Readable	✅
Writable	✅
Resets on factory default	✅

RELATIVE_POSITION¶

This setting can be used to update the value of the relative position broadcasted by the periodic position frame.

This current position register does not have an offset saved to non-volatile flash but is rather initialized to 0 on device boot and updated as the encoder IC reading changes.

Writing to this settings with a signed 32-bit integer will update the current relative position to the new value in the payload, using the lowest 32 bits as a signed integer.

Reading from this settings index is not valid and will produce 0xffffffffffff – use the periodic position frame to read relative position data instead.

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

DISABLE_ZERO_BUTTON¶

This setting controls whether the onboard zero button functions.

By default, this setting is set to false (0). Pressing the zero button for 2 seconds will set both absolute and relative position values

When the zero button is enabled (when this setting is set to 0), pressing it for 2 seconds will set both absolute and relative position values to zero for both CAN and PWM, and pressing the button for 15 seconds will reset the device to factory default settings.

When the zero button is disabled (when this setting is set to 1), inputs to the button will be completely ignored – factory resets and zeroing must be performed over CAN or other supported message layers.

Property	Value
Setting index	0xf8
Type	`bool`
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	status_frame_period
Default value	1000
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	`[0x6d, 0x61, 0x67, 0x0, 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

faults¶

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 encoder first boots. Clearing sticky faults and then checking this flag can be used to determine if the encoder 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 encoder 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 encoder is not between 0-70 degrees Celsius. This may be of concern if the encoder 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	magnet_out_of_range	The magnet out of range flag, which will raise if the measured shaft’s magnet is not detected. This will match the encoder’s LED shining red in normal operation.
6	under_volt	The undervolt flag, which will raise if the encoder is experiencing brownout conditions.

zero_offset¶

Data encapsulated by the zero offset setting.

If sent with the position bit set, the offset_or_position field is treated as an absolute position.

If sent with the position bit unset, the offset_or_position field updates zero offset directly.

On operations that report settings, the read setting is always the zero offset.

Property	Value
Base type	struct
Bit width	15

Signals:

Name	Type	Default value	Description
`offset_or_position`	absolute_position	`0`	Zero offset or position
`position_bit`	`bool`	0	True to set position instead of a zero offset.

velocity¶

Message velocity value

Property	Value
Base type	sint
Bit width	22
Minimum value	-2097152
Maximum value	2097151
Default value	0
Conversion factor	1 LSB = \(\frac{1}{1024}\) rotation/second

relative_position¶

Relative position value

Property	Value
Base type	sint
Bit width	32
Minimum value	-2147483648
Maximum value	2147483647
Default value	0
Conversion factor	1 LSB = \(\frac{1}{16384}\) rotation

absolute_position¶

Absolute position value

Property	Value
Base type	uint
Bit width	14
Minimum value	0
Maximum value	16383
Default value	0
Conversion factor	1 LSB = \(\frac{1}{16384}\) rotation

magnet_status¶

Magnet status; if both bits are zero, the device magnet is in range. Magnet status usually updates slowly (on the order of seconds).

Property	Value
Base type	uint
Bit width	2
Minimum value	0
Maximum value	3
Default value	0

velocity_window¶

Number of samples used to average in the velocity window. Samples occur once every 250 microseconds.

Property	Value
Base type	uint
Bit width	8
Minimum value	1
Maximum value	255
Default value	100
Conversion factor	1 LSB = \(\frac{1}{4}\) millisecond

Enums¶

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

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.
0xff	RESET_FACTORY_DEFAULT_KEEP_ZERO	Reset to factory defaults, but keep encoder zero offset