CanandDevice

Base CAN/settings spec shared for all CAN Redux Devices.

Tip

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

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

Summary of the CAN address scheme and packet format

Redux CAN devices conform to the 29-bit FRC CAN message address scheme, with a very specific rearrangement of the API identifier/class field. A full CAN arbitration id that actually gets put on the bus can be broken down into four components:

1. A 5 bit device type (devType) that is product specific (the Canandcoder is 7 for “gear tooth sensor”)

2. an 8-bit manufacturer code unique to each vendor (the Redux code is 14 in decimal or 0xE)

3. 10 bits of API identifier

4. a 6-bit device number (devId) that is user-configurable so you can have multiple of a device on a bus – this is what the “CAN Id” in robot code and vendor tuners usually refer to.

The WPILib docs elaborates on this in a bit more detail. Of note is that it breaks down the 10-bit API identifier into a 6-bit API class and 4-bit API index.

Redux products, however, break it down into a 5 bit product API ID (prodID) that is generally product specific (the Canandcoder prodId is 0) and a 5 bit API index (apiIndex), which actually gets used for a device’s CAN API.

The breakdown can be seen in the diagram provided below for a Party Mode packet sent to Canandcoder device 4:

Based on diagram from: WPILib Docs

Summary of the settings scheme

Redux CAN device have a series of settings that are up to 6 bytes in length, that are managed using the SET_SETTING, SETTING_COMMAND, and REPORT_SETTING CAN messages. Exact format and functionality of each setting field is generally device dependent.

Sending a SET_SETTING packet, if successful, will trigger a REPORT_SETTING message as a reply to confirm the transaction. The SETTING_COMMAND packet can be used to either report all settings over the CAN bus or to reset back to default settings.

CAN messages

SETTING_COMMAND

Sent to device to execute a command on the settings subsystem. Packet length is variable depending on command but is at least 1 byte. Canandcoder firmwares older than v2023.1.0 will only support setting command packets with a 1 byte data length code.

Properties

Property	Value
API Index	0x2
Message length	2 bytes
Tx direction	Robot -> device

Signals

Signal name	Start bit	Bit length	Description
control_flag	0	8	8-bit setting command index
data	8	8	Optional data field – used for setting index in FETCH_SETTING_VALUE

SET_SETTING

Sent to device to change a setting by address. Will result in a REPORT_SETTING packet sent in reply.

As of v2024 firmwares, setting flags can be included in the 8th byte to change behavior. Here’s a list of valid setting flags:

Index	Setting flag
0x1	Ephemeral (do not write to flash)

Properties

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

Signals

Signal name	Start bit	Bit length	Description
address	0	8	Setting index to write to
value	8	48	6-byte setting value
flags	56	8	Set setting flags

REPORT_SETTING

Reports a setting value from the device. Sent after a setting change, on the FETCH_SETTINGS command, or a factory reset. Setting changes (as of v2024) will always include the “settings flag” field.

Properties

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

Signals

Signal name	Start bit	Bit length	Description
address	0	8	Setting index that is being transmitted
value	8	48	6-byte setting value
flags	56	8	Setting receive status (optional, 0=success, 1=invalid value)

CLEAR_STICKY_FAULTS

Sent to device to clear all sticky faults (sets the faults to 0 until new faults get raised)

Properties

Property	Value
API Index	0x5
Message length	1 bytes
Tx direction	Robot -> device

Signals

Signal name	Start bit	Bit length	Description
unused	0	8	This field is currently unused.

STATUS

Periodic frame containing status information about the device.

Typically this contains active and sticky faults as well as device temperature. The actual breakdown by bits will vary from device to device – consult their pages for more information.

By factory default, this frame is transmitted onto the bus every 1000 ms (via the STATUS_FRAME_PERIOD setting). Generally this frame cannot be disabled as Alchemist use this to detect the existence of devices.

Properties

Property	Value
API Index	0x6
Message length	8 bytes
Tx direction	Device -> robot

Signals

Signal name	Start bit	Bit length	Description
dev_specific	0	64	Device-specific status data. See device pages for more information.

PARTY_MODE

Configures party mode to the device, which will cycle the onboard LED various colors to help identify where it physically sits on a CAN network.

Properties

Property	Value
API Index	0x7
Message length	1 bytes
Tx direction	Robot -> device

Signals

Signal name	Start bit	Bit length	Description
party_level	0	8	Party level. 0 disables the strobe, whereas each increased value up to 10 increases strobe period by 50 ms.

Settings

CAN_ID

Sets the 6-bit device id, ranging from 0 to 63. Defaults to 0 but does not reset on factory resets. This allows multiple of a device to share a bus.

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

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
Factory default value	n/a
Value range	n/a
Mutability	Read/write

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
Factory default value	n/a
Value range	n/a
Mutability	Read/write

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 simply be 18 characters long.

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

STATUS_FRAME_PERIOD

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

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

SERIAL_NUMBER

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

Property	Value
Setting Index	0x5
Factory default value	n/a
Value range	n/a
Mutability	Read-only

FIRMWARE_VERSION

Read-only setting value of the device’s firmware version. Byte 0 is patch version, byte 1 is minor version, and bytes 2-3 are year – all unsigned little-endian.

Property	Value
Setting Index	0x6
Factory default value	n/a
Value range	n/a
Mutability	Read-only

Setting commands

FETCH_SETTINGS

Fetches all settings from device via a series of REPORT_SETTING packets (each about 15 ms apart or less)

Property	Value
Setting command index	0x0

RESET_FACTORY_DEFAULT

Resets the device to factory default settings, and reports the new settings in response. CAN IDs are not reset.

Property	Value
Setting command index	0x1

FETCH_SETTING_VALUE

Fetches a single setting value. The data field (second byte) in the SETTING_COMMAND packet is used for the setting index.

Property	Value
Setting command index	0x2