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:
A 5 bit device type (devType) that is product specific (the Canandmag is 7 for “gear tooth sensor”)
an 8-bit manufacturer code unique to each vendor (the Redux code is 14 in decimal or 0xE)
10 bits of API identifier
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 Canandmag 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 Canandmag device 4:
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. Canandmag 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 |
---|---|---|---|
|
0 |
8 |
8-bit setting command index |
|
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 |
---|---|---|---|
|
0 |
8 |
Setting index to write to |
|
8 |
48 |
6-byte setting value |
|
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 |
---|---|---|---|
|
0 |
8 |
Setting index that is being transmitted |
|
8 |
48 |
6-byte setting value |
|
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 |
---|---|---|---|
|
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 |
---|---|---|---|
|
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 |
---|---|---|---|
|
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 |