Canandcoder

Canandcoder-specific CAN messages and settings.

Note

This extends the CanandDevice spec including all CAN messages, settings, and setting commands.

Tip

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

CAN messages

General properties

FRC CAN Device Type	0x7
CAN Product ID	0x0
DBC File	Link

The DBC file assumes a device id of 0. For more information on the CAN device type and product ID, see CanandDevice

POSITION_OUTPUT

Periodic frame with relative position and absolute position registers read by the encoder. For both relative (unwrapped) and absolute position, one encoder tick is 1/16384-th of a rotation. Pressing the onboard zero button will set both registers to zero.

By factory default, this frame is transmitted onto the bus every 20 ms (via the POSITION_FRAME_PERIOD setting).

Properties

Property	Value
API Index	0x1f
Message length	6 bytes
Tx direction	Device -> robot

Signals

Signal name	Start bit	Bit length	Description
relative_position	0	32	32-bit signed relative position in 1/16384-ths of a rotation. This value does not persist on reboots.
magnet_status	32	2	2-bit magnet status. If both bits are zero, the magnet is in range.
absolute_position	34	14	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 fram containing the currently calculated velocity. As of firmware v2023, the velocity is calculated using a rolling average of differences, the width of which is configured in the VELOCITY_WINDOW setting.

By factory default, this frame is transmitted onto the bus every 20 ms (via the VELOCITY_FRAME_PERIOD setting).

Properties

Property	Value
API Index	0x1e
Message length	3 bytes
Tx direction	Device -> robot

Signals

Signal name	Start bit	Bit length	Description
velocity	0	22	Velocity as a 22-bit signed integer. One velocity tick corresponds to 1/1024th of a rotation per second.
magnet_status	22	2	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 through the RAW_POSITION_FRAME_PERIOD_ setting.

Properties

Property	Value
API Index	0x1d
Message length	6 bytes
Tx direction	Device -> robot

Signals

Signal name	Start bit	Bit length	Description
raw_position	0	14	14-bit raw absolute position in 1/16384-ths of a rotation.
magnet_status	14	2	2-bit magnet status. If both bits are zero, the magnet is in range.
timestamp	16	32	32-bit sensor reading timestamp in microseconds since device boot.

Settings

ZERO_OFFSET

The encoder’s absolute zero offset used for both the CAN and PWM outputs.

When read, this will return the current zero offset value (unsigned 14-bit) where absolute position = (raw position - zero offset)

The zero offset can be updated in one of two ways. Sending a value from 0-16383 will directly change the zero offset. However, sending a value (new_value) | 0x10000 (just the new value with the 3rd setting set byte set to 1) will update the zero offset such that absolute_position = new_value, which is used by setPosition() in the vendordep.

Property	Value
Setting Index	0xff
Factory default value	n/a
Value range	n/a
Mutability	Read/write

VELOCITY_WINDOW

Width of the velocity window determining how many samples are included in the velocity filter’s moving average.

The velocity window ranges from 1 to 255. Samples are added every 250 us, so the maximum width (255 samples) corresponds to 63.75 ms, and minimum width uses the last difference estimate from up to 250 us ago.

Property	Value
Setting Index	0xfe
Factory default value	100
Value range	[1, 255]
Mutability	Read/write

POSITION_FRAME_PERIOD

Period between the transmission of position CAN frames in milliseconds. A 0 ms value disables transmission altogether. Sending a 0ms value while transmission is already disabled will manually prompt the device to respond witn a single position frame.

Property	Value
Setting Index	0xfd
Factory default value	20
Value range	[0, 65535]
Mutability	Read/write

VELOCITY_FRAME_PERIOD

Period between the transmission of velocity CAN frames in milliseconds. A 0 ms value disables transmission altogether. Sending a 0ms value while transmission is already disabled will manually prompt the device to respond witn a single velocity frame.

Property	Value
Setting Index	0xfc
Factory default value	20
Value range	[0, 65535]
Mutability	Read/write

RAW_POSITION_FRAME_PERIOD

Period between the transmission of raw position CAN frames in milliseconds. A 0 ms value disables transmission altogether. Sending a 0ms value while transmission is already disabled will manually prompt the device to respond witn a single raw position frame.

Property	Value
Setting Index	0xfb
Factory default value	0
Value range	[0, 65535]
Mutability	Read/write

INVERT_DIRECTION

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

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

0 is counter clockwise is positive, 1 is clockwise is positive.

Property	Value
Setting Index	0xfa
Factory default value	0
Value range	[0, 1]
Mutability	Read/write

RELATIVE_POSITION

Not a true persistent setting: can be used to update the value of the relative position broadcasted by the CAN position frame. This defaults to 0 on startup.

Writing to this settings index with a signed 32-bit value will update the relative position to the new value in the payload, using the lowest 32 bits as a signed integer. One unit here is 1/16384-ths of a rotation.

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

Property	Value
Setting Index	0xf9
Factory default value	0
Value range	[-2147483648, 2147483647]
Mutability	Write-only

DISABLE_ZERO_BUTTON

Whether pressing the onboard zeroing button should be disabled or not.

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

Property	Value
Setting Index	0xf8
Factory default value	0
Value range	[0, 1]
Mutability	Read/write

Setting commands

RESET_FACTORY_DEFAULT_KEEP_ZERO

Resets the encoder to factory default settings, but will keep the encoder’s zero offset intact.

Property	Value
Setting command index	0xff