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

Property	Value
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

REPORT_SETTING

Sent to report a setting value from the device.

These messages can be triggered by:

• A setting change via SET_SETTING
• 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 (Enum)	❌	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 firmware specific information 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 \text{ 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

Period between each transmission of POSITION_OUTPUT messages.

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

VELOCITY_FRAME_PERIOD

Period between each transmission of VELOCITY_OUTPUT messages.

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

RAW_POSITION_FRAME_PERIOD

Period between each transmission of RAW_POSITION_OUTPUT messages.

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 to zero.

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.

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 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.

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.

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.

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.

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

Property	Value
Base type	uint
Bit width	16
Minimum value	0
Maximum value	65535
Default value	0
Conversion factor	1 LSB = 1/1000 seconds

status_frame_period

Property	Value
Base type	uint
Bit width	16
Minimum value	1
Maximum value	16383
Default value	1000
Conversion factor	1 LSB = 1/1000 seconds

can_device_id

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

setting_flags

See CanandDevice setting_flags

setting_report_flags

See CanandDevice setting_report_flags

firmware_version

See CanandDevice firmware_version

faults

Property	Value
Base type	bitset
Bit width	8

Flags:

Flag index	Flag name	Default value	Description
0	power_cycle	0	The power cycle fault flag, which is set to true when the encoder first boots.
1	can_id_conflict	0	The CAN ID conflict flag, which is set to true if there is a CAN id conflict.
2	can_general_error	0	The CAN general error flag, which will raise if the device encounters a CAN fault.
3	out_of_temperature_range	0	The temperature range flag (0-70°C).
4	hardware_fault	0	The hardware fault flag.
5	magnet_out_of_range	0	The magnet out of range flag.
6	under_volt	0	The undervolt flag.

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

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

relative_position

Property	Value
Base type	sint
Bit width	32
Minimum value	-2147483648
Maximum value	2147483647
Default value	0
Conversion factor	1 LSB = 1/16384 rotation

absolute_position

Property	Value
Base type	uint
Bit width	14
Minimum value	0
Maximum value	16383
Default value	0
Conversion factor	1 LSB = 1/16384 rotation

magnet_status

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

velocity_window

Property	Value
Base type	uint
Bit width	8
Minimum value	1
Maximum value	255
Default value	100
Conversion factor	1 LSB = 1/4 millisecond

Enums

SETTING_COMMAND

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.
0x1	RESET_FACTORY_DEFAULT	Reset all resettable settings to factory default.
0x2	FETCH_SETTING_VALUE	Requests to fetch a single setting from device.
0xff	RESET_FACTORY_DEFAULT_KEEP_ZERO	Reset to factory defaults, but keep encoder zero offset