Canandcolor

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	0x6
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	DISTANCE_OUTPUT	Distance frame
0x1e	COLOR_OUTPUT	Color frame
0x1d	DIGITAL_OUTPUT	Digital output frame
0x1c	CLEAR_STICKY_DIGOUT	Clear sticky digout state
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

DISTANCE_OUTPUT

Periodic frame with the Canandcolor’s raw 16-bit distance output. This distance measurement increases approximately linearly as objects move away from the sensor.

Properties

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

Signals

Signal name	Signal type	Optional	Description
distance	uint16_t	❌	16-bit distance value.

COLOR_OUTPUT

Periodic frame with the Canandcolor’s color sensor output, with up to 20-bit precision. The red/blue/green channels will be left-shifted such that the largest possible sensable value is always closest to 0xfffff.

Properties

Property	Value
API Index	0x1e
Message length	8 bytes
Transmission direction	Device -> robot
Frame period setting	COLOR_FRAME_PERIOD
Default frame period	25 milliseconds

Signals

Signal name	Signal type	Optional	Description
red	uint20_t	❌	Red reading magnitude
green	uint20_t	❌	Green reading magnitude
blue	uint20_t	❌	Blue reading magnitude
period	COLOR_INTEGRATION_PERIOD	❌	Color integration period

DIGITAL_OUTPUT

Periodic frame with the Canandcolor’s digital output state. Digout channel slots are always evaluated, even if the physical digital outputs themselves are disabled.

Properties

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

Signals

Signal name	Signal type	Optional	Description
digout1_state	bool	❌	Digital output state for DIGOUT1
digout2_state	bool	❌	Digital output state for DIGOUT2
digout1_sticky	bool	❌	Sticky digital output state for DIGOUT1
digout2_sticky	bool	❌	Sticky digital output state for DIGOUT1
reserved	pad4_t	❌	Reserved
digout1_cond	digout_cond	❌	DIGOUT1 condition slot flags.
digout2_cond	digout_cond	❌	DIGOUT2 condition slot flags.

CLEAR_STICKY_DIGOUT

Clears the sticky digout state for both digout1 and digout2.

Properties

Property	Value
API Index	0x1c
Message length	0 bytes
Transmission direction	Robot -> device

ENUMERATE

See CanandDevice ENUMERATE.

PARTY_MODE

Configures party mode to the device.

Properties

Property	Value
API Index	0x7
Minimum message length	1 bytes
Maximum message length	8 bytes
Transmission direction	Robot -> device

STATUS

Periodic frame containing status information about the device.

Properties

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

Signals

Signal name	Signal type	Optional	Description
faults	faults	❌	8-bit active faults bitfield
sticky_faults	faults	❌	8-bit sticky faults bitfield
temperature	temperature	❌	16-bit signed temperature
reserved	pad32_t	❌	Reserved bits

CLEAR_STICKY_FAULTS

See CanandDevice CLEAR_STICKY_FAULTS.

REPORT_SETTING

See CanandDevice REPORT_SETTING.

SET_SETTING

See CanandDevice SET_SETTING.

SETTING_COMMAND

See CanandDevice SETTING_COMMAND.

Settings

Setting summary:

Setting index	Name	Type	Default value	Readable	Writable	Resets to factory default	Description
0xff	DISTANCE_FRAME_PERIOD	frame_period	20	✅	✅	✅	Distance frame period (ms)
0xfe	COLOR_FRAME_PERIOD	frame_period	25	✅	✅	✅	Color frame period (ms)
0xfd	DIGOUT_FRAME_PERIOD	frame_period	100	✅	✅	✅	Digout frame period (ms)
0xf7	DISTANCE_EXTRA_FRAME_MODE	EXTRA_FRAME_MODE	EARLY_TRANSMIT_ON_CHANGE	✅	✅	✅	Distance extra frame mode
0xf6	COLOR_EXTRA_FRAME_MODE	EXTRA_FRAME_MODE	EARLY_TRANSMIT_ON_CHANGE	✅	✅	✅	Color extra frame mode
0xef	LAMP_BRIGHTNESS	lamp_brightness	36000	✅	✅	✅	Lamp LED brightness
0xee	COLOR_INTEGRATION_PERIOD	COLOR_INTEGRATION_PERIOD	PERIOD_25_ms_RESOLUTION_16_bit	✅	✅	✅	Color integration period
0xed	DISTANCE_INTEGRATION_PERIOD	DISTANCE_INTEGRATION_PERIOD	PERIOD_20_ms	✅	✅	✅	Distance integration period
0xeb	DIGOUT1_OUTPUT_CONFIG	digout_control_config	Type default	✅	✅	✅	Digital output 1 control config
0xea	DIGOUT2_OUTPUT_CONFIG	digout_control_config	Type default	✅	✅	✅	Digital output 2 control config
0xe9	DIGOUT1_MESSAGE_ON_CHANGE	digout_message_trigger	Type default	✅	✅	✅	Digital output 1 send message on change
0xe8	DIGOUT2_MESSAGE_ON_CHANGE	digout_message_trigger	Type default	✅	✅	✅	Digital output 2 send message on change
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	100	✅	✅	✅	Status frame period (ms)
0x0	CAN_ID	can_device_id	0	✅	✅	❌	CAN Device ID

DISTANCE_FRAME_PERIOD

Period between each transmission of DISTANCE_OUTPUT messages.

COLOR_FRAME_PERIOD

Period between each transmission of COLOR_OUTPUT messages.

DIGOUT_FRAME_PERIOD

Period between each transmission of DIGITAL_OUTPUT messages.

LAMP_BRIGHTNESS

Sets the LED brightness for the lamp (white) LED.

COLOR_INTEGRATION_PERIOD

Sets the integration period for the color sensor.

DISTANCE_INTEGRATION_PERIOD

Sets the integration period for the distance sensor.

Types

faults

Flag index	Flag name	Default value	Description
0	power_cycle	0	The power cycle fault flag.
1	can_id_conflict	0	The CAN ID conflict flag.
2	can_general_error	0	The CAN general error flag.
3	out_of_temperature_range	0	The temperature range flag (0-70°C).
4	hardware_fault_distance	0	Hardware fault for distance sensor.
5	hardware_fault_color	0	Hardware fault for color sensor.
6	i2c_bus_recovery	0	The I2C bus recovery flag.

temperature

Temperature as reported to/from the device. 1 LSB = 1/256th of a degree Celsius.

digout_slot

Digout slot represents a digital output slot — a component of programmable digital logic updated at 1000 Hz.

Name	Type	Default value	Description
slot_enabled	bool	false	Enable the digout slot
next_slot_action	NEXT_SLOT_ACTION	TERMINATE_CHAIN	How the slot interacts with the next
invert_value	bool	false	Invert the slot’s value
opcode	SLOT_OPCODE	EQUALS	Opcode
immidiate_additive	int21_t	0	Additive immediate
immidiate_scaling	scaling_factor	255	Scaling immediate
data_source_a	DATA_SOURCE	ZERO	LHS data source
data_source_b	DATA_SOURCE	ZERO	RHS data source

Enums

EXTRA_FRAME_MODE

Enum index	Variant name	Description
0x0	DISABLED	Do not emit extra frames
0x1	EARLY_TRANSMIT_ON_CHANGE	Transmits a frame immediately once readings change

DATA_SOURCE

Enum index	Variant name	Description
0x0	ZERO	Always reads zero
0x1	DISTANCE	Distance reading
0x2	RED	Red reading
0x3	GREEN	Green reading
0x4	BLUE	Blue reading
0x5	HUE	Hue reading
0x6	SATURATION	Saturation reading
0x7	VALUE	Value reading

SETTING_COMMAND

See CanandDevice SETTING_COMMAND. Additional variants for Canandcolor:

Enum index	Variant name	Description
0xff	CLEAR_DIGOUT1	Clear all digout1 slots
0xfe	CLEAR_DIGOUT2	Clear all digout2 slots
0xfd	FETCH_DIGOUT1	Fetch all digout1 slots
0xfc	FETCH_DIGOUT2	Fetch all digout2 slots