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¶

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 which is broadcast over CAN
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 until sensor reading ability drops off.

The period at which this message is broadcasted at is controlled by the DISTANCE_FRAME_PERIOD setting.

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. Actual correspondance to real-world units is config and surface-dependent.

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 the one closest to 0xfffff. For example, if the color sensor is configured in 25 ms/16 bit mode, the output values are left-shifted by 4 bits such that 0xffff0 is the largest senseable magnitude, rather than 0xffff.

The color integration period is returned in the leftover 4 bits of the packet.

The period at which this message is broadcasted at is controlled by the COLOR_FRAME_PERIOD setting.

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, including digout slots for both channels (both overall evaluation and individual slot conditions). Digout channel slots are always evaluated, even if the physical digital outputs themselves are disabled – this allows them to be also be used as programmable interrupt flags for CAN-only usage.

The sticky flags raise whenever digout1 or digout2 have evaluated to true since the last time they have been cleared. This can be used to check if a sensor condition has ever been true between robot loop iterations.

The period at which this message is broadcasted at is controlled by the DIGOUT_FRAME_PERIOD setting.

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. A value of 1 for bit N means that condition slot is true. Bits are indexed little-endian.
`digout2_cond`	digout_cond	❌	DIGOUT2 condition slot flags. A value of 1 for bit N means that condition slot is true. Bits are indexed little-endian.

CLEAR_STICKY_DIGOUT¶

Clears the sticky digout state for both digout1 and digout2 associated with the digital output packet.

Properties

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

Signals

Signal name	Signal type	Optional	Description

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 1 enables it.

STATUS¶

Periodic frame containing status information about the device.

This contains active and sticky faults as well as temperature, although the temperature reading is best described as a general approximation.

This frame cannot be disabled.

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 byte in 1/256ths of a Celsius
`reserved`	`pad32_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

Signals

Signal name	Signal type	Optional	Description

REPORT_SETTING¶

Sent to report a setting value from the device.

These messages can be triggered by:

a setting change via the set setting message
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	❌	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 firmare specific infomation 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	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 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
0xd0	DIGOUT1_CONFIG_0	digout_slot	Type default	✅	✅	✅	Digout1 config slot 0
0xcf	DIGOUT1_CONFIG_1	digout_slot	Type default	✅	✅	✅	Digout1 config slot 1
0xce	DIGOUT1_CONFIG_2	digout_slot	Type default	✅	✅	✅	Digout1 config slot 2
0xcd	DIGOUT1_CONFIG_3	digout_slot	Type default	✅	✅	✅	Digout1 config slot 3
0xcc	DIGOUT1_CONFIG_4	digout_slot	Type default	✅	✅	✅	Digout1 config slot 4
0xcb	DIGOUT1_CONFIG_5	digout_slot	Type default	✅	✅	✅	Digout1 config slot 5
0xca	DIGOUT1_CONFIG_6	digout_slot	Type default	✅	✅	✅	Digout1 config slot 6
0xc9	DIGOUT1_CONFIG_7	digout_slot	Type default	✅	✅	✅	Digout1 config slot 7
0xc8	DIGOUT1_CONFIG_8	digout_slot	Type default	✅	✅	✅	Digout1 config slot 8
0xc7	DIGOUT1_CONFIG_9	digout_slot	Type default	✅	✅	✅	Digout1 config slot 9
0xc6	DIGOUT1_CONFIG_10	digout_slot	Type default	✅	✅	✅	Digout1 config slot 10
0xc5	DIGOUT1_CONFIG_11	digout_slot	Type default	✅	✅	✅	Digout1 config slot 11
0xc4	DIGOUT1_CONFIG_12	digout_slot	Type default	✅	✅	✅	Digout1 config slot 12
0xc3	DIGOUT1_CONFIG_13	digout_slot	Type default	✅	✅	✅	Digout1 config slot 13
0xc2	DIGOUT1_CONFIG_14	digout_slot	Type default	✅	✅	✅	Digout1 config slot 14
0xc1	DIGOUT1_CONFIG_15	digout_slot	Type default	✅	✅	✅	Digout1 config slot 15
0xc0	DIGOUT2_CONFIG_0	digout_slot	Type default	✅	✅	✅	Digout2 config slot 0
0xbf	DIGOUT2_CONFIG_1	digout_slot	Type default	✅	✅	✅	Digout2 config slot 1
0xbe	DIGOUT2_CONFIG_2	digout_slot	Type default	✅	✅	✅	Digout2 config slot 2
0xbd	DIGOUT2_CONFIG_3	digout_slot	Type default	✅	✅	✅	Digout2 config slot 3
0xbc	DIGOUT2_CONFIG_4	digout_slot	Type default	✅	✅	✅	Digout2 config slot 4
0xbb	DIGOUT2_CONFIG_5	digout_slot	Type default	✅	✅	✅	Digout2 config slot 5
0xba	DIGOUT2_CONFIG_6	digout_slot	Type default	✅	✅	✅	Digout2 config slot 6
0xb9	DIGOUT2_CONFIG_7	digout_slot	Type default	✅	✅	✅	Digout2 config slot 7
0xb8	DIGOUT2_CONFIG_8	digout_slot	Type default	✅	✅	✅	Digout2 config slot 8
0xb7	DIGOUT2_CONFIG_9	digout_slot	Type default	✅	✅	✅	Digout2 config slot 9
0xb6	DIGOUT2_CONFIG_10	digout_slot	Type default	✅	✅	✅	Digout2 config slot 10
0xb5	DIGOUT2_CONFIG_11	digout_slot	Type default	✅	✅	✅	Digout2 config slot 11
0xb4	DIGOUT2_CONFIG_12	digout_slot	Type default	✅	✅	✅	Digout2 config slot 12
0xb3	DIGOUT2_CONFIG_13	digout_slot	Type default	✅	✅	✅	Digout2 config slot 13
0xb2	DIGOUT2_CONFIG_14	digout_slot	Type default	✅	✅	✅	Digout2 config slot 14
0xb1	DIGOUT2_CONFIG_15	digout_slot	Type default	✅	✅	✅	Digout2 config slot 15
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)
0x3	NAME_2	`uint8_t[6]`	`[0x0, 0x0, 0x0, 0x0, 0x0, 0x0]`	✅	✅	✅	device_name[12:17]
0x2	NAME_1	`uint8_t[6]`	`[0x63, 0x6f, 0x6c, 0x6f, 0x72, 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

DISTANCE_FRAME_PERIOD¶

Period between each transmission of DISTANCE_OUTPUT messages.

A value of 0 disables transmission of the associated message altogether.

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

COLOR_FRAME_PERIOD¶

Period between each transmission of COLOR_OUTPUT messages.

A value of 0 disables transmission of the associated message altogether.

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

DIGOUT_FRAME_PERIOD¶

Period between each transmission of DIGITAL_OUTPUT messages.

A value of 0 disables transmission of the associated message altogether.

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

DISTANCE_EXTRA_FRAME_MODE¶

Sets the extra frame mode for distance sensor messages.

Property	Value
Setting index	0xf7
Type	EXTRA_FRAME_MODE
Default value	EARLY_TRANSMIT_ON_CHANGE
Readable	✅
Writable	✅
Resets on factory default	✅

COLOR_EXTRA_FRAME_MODE¶

Sets the extra frame mode for color sensor messages.

Property	Value
Setting index	0xf6
Type	EXTRA_FRAME_MODE
Default value	EARLY_TRANSMIT_ON_CHANGE
Readable	✅
Writable	✅
Resets on factory default	✅

LAMP_BRIGHTNESS¶

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

Property	Value
Setting index	0xef
Type	lamp_brightness
Default value	`36000`
Readable	✅
Writable	✅
Resets on factory default	✅

COLOR_INTEGRATION_PERIOD¶

Sets the integration period for the color sensor.

Property	Value
Setting index	0xee
Type	COLOR_INTEGRATION_PERIOD
Default value	PERIOD_25_ms_RESOLUTION_16_bit
Readable	✅
Writable	✅
Resets on factory default	✅

DISTANCE_INTEGRATION_PERIOD¶

Sets the integration period for the distance sensor.

Property	Value
Setting index	0xed
Type	DISTANCE_INTEGRATION_PERIOD
Default value	PERIOD_20_ms
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_OUTPUT_CONFIG¶

Sets up how the physical DIG-1 GPIO pin should act.

This pin does not support PWM output.

Property	Value
Setting index	0xeb
Type	digout_control_config
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_OUTPUT_CONFIG¶

Sets up how the physical DIG-2 GPIO pin should act.

Property	Value
Setting index	0xea
Type	digout_control_config
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_MESSAGE_ON_CHANGE¶

Sets how extra digout messages should be sent when the value of digout channel 1 changes.

Property	Value
Setting index	0xe9
Type	digout_message_trigger
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_MESSAGE_ON_CHANGE¶

Sets how extra digout messages should be sent when the value of digout channel 2 changes.

Property	Value
Setting index	0xe8
Type	digout_message_trigger
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_0¶

Digout slot channel 1 index 0

Property	Value
Setting index	0xd0
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_1¶

Digout slot channel 1 index 1

Property	Value
Setting index	0xcf
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_2¶

Digout slot channel 1 index 2

Property	Value
Setting index	0xce
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_3¶

Digout slot channel 1 index 3

Property	Value
Setting index	0xcd
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_4¶

Digout slot channel 1 index 4

Property	Value
Setting index	0xcc
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_5¶

Digout slot channel 1 index 5

Property	Value
Setting index	0xcb
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_6¶

Digout slot channel 1 index 6

Property	Value
Setting index	0xca
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_7¶

Digout slot channel 1 index 7

Property	Value
Setting index	0xc9
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_8¶

Digout slot channel 1 index 8

Property	Value
Setting index	0xc8
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_9¶

Digout slot channel 1 index 9

Property	Value
Setting index	0xc7
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_10¶

Digout slot channel 1 index 10

Property	Value
Setting index	0xc6
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_11¶

Digout slot channel 1 index 11

Property	Value
Setting index	0xc5
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_12¶

Digout slot channel 1 index 12

Property	Value
Setting index	0xc4
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_13¶

Digout slot channel 1 index 13

Property	Value
Setting index	0xc3
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_14¶

Digout slot channel 1 index 14

Property	Value
Setting index	0xc2
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT1_CONFIG_15¶

Digout slot channel 1 index 15

Property	Value
Setting index	0xc1
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_0¶

Digout slot channel 2 index 0

Property	Value
Setting index	0xc0
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_1¶

Digout slot channel 2 index 1

Property	Value
Setting index	0xbf
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_2¶

Digout slot channel 2 index 2

Property	Value
Setting index	0xbe
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_3¶

Digout slot channel 2 index 3

Property	Value
Setting index	0xbd
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_4¶

Digout slot channel 2 index 4

Property	Value
Setting index	0xbc
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_5¶

Digout slot channel 2 index 5

Property	Value
Setting index	0xbb
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_6¶

Digout slot channel 2 index 6

Property	Value
Setting index	0xba
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_7¶

Digout slot channel 2 index 7

Property	Value
Setting index	0xb9
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_8¶

Digout slot channel 2 index 8

Property	Value
Setting index	0xb8
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_9¶

Digout slot channel 2 index 9

Property	Value
Setting index	0xb7
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_10¶

Digout slot channel 2 index 10

Property	Value
Setting index	0xb6
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_11¶

Digout slot channel 2 index 11

Property	Value
Setting index	0xb5
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_12¶

Digout slot channel 2 index 12

Property	Value
Setting index	0xb4
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_13¶

Digout slot channel 2 index 13

Property	Value
Setting index	0xb3
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_14¶

Digout slot channel 2 index 14

Property	Value
Setting index	0xb2
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DIGOUT2_CONFIG_15¶

Digout slot channel 2 index 15

Property	Value
Setting index	0xb1
Type	digout_slot
Default value	Type default
Readable	✅
Writable	✅
Resets on factory default	✅

DEVICE_TYPE¶

Read-only device type identifier.

If multiple types of device share the same FRC-CAN device class, e.g. two device variants that do similar things but may or may not have the same message API, this setting can be used to disambiguate between them.

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 frame 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	100
Readable	✅
Writable	✅
Resets on factory default	✅

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

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.

Having a null byte will terminate the name field at that byte.

Property	Value
Setting index	0x2
Type	`uint8_t[6]`
Default value	`[0x63, 0x6f, 0x6c, 0x6f, 0x72, 0x0]`
Readable	✅
Writable	✅
Resets on factory default	✅

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
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. This allows multiple of a device to share a bus.

Defaults to 0 but does not reset on factory resets.

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¶

Frame period associated with some periodic data or status frame. 1 LSB equals 1 ms of period, and setting the period to 0 will disable the corresponding frame.

Property	Value
Base type	uint
Bit width	16
Minimum value	0
Maximum value	65535
Default value	0
Conversion factor	1 LSB = \(\frac{1}{1000}\) seconds

status_frame_period¶

Frame period specific to the status frame, as status frames cannot be set to 0 and disabled.

Property	Value
Base type	uint
Bit width	16
Minimum value	1
Maximum value	16383
Default value	1000
Conversion factor	1 LSB = \(\frac{1}{1000}\) seconds

can_device_id¶

The CAN device id used by the device. As specified by the FRC-CAN spec, this comprises the least significant 6 bits of the CAN id.

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

setting_flags¶

Information set on the set settings message.

Setting the ephemeral bit makes the setting not save to non-volatile memory and not persist on reboot, if applicable.

Sending multiple messages with the synch hold message will queue them for application on device until a message with the bit unset and the number of messages expected to be in the queue (in synch_msg_count) is set.

If the number of settings in the queue equals the number of settings in synch_message_count, all settings are applied and a report settings message with the commit_success bit is set. Otherwise, none of them are applied and the commit success bit is unset.

Original Canandmags do not support the synch hold mechanism.

Property	Value
Base type	struct
Bit width	8

Signals:

Name	Type	Default value	Description
`ephemeral`	`bool`	`false`	Whether the setting should be set ephemeral
`synch_hold`	`bool`	`false`	Whether the setting should be held until the next synch barrier
`reserved_0`	`pad2_t`	`0`	Reserved
`synch_msg_count`	`uint4_t`	`0`	Synch message count

setting_report_flags¶

Bits set by the report setting message to indicate success or failure

Property	Value
Base type	bitset
Bit width	8

Flags:

Flag index	Flag name	Default value	Description
0	set_success	0	Whether the setting set/fetch was successful
1	commit_success	0	Whether the setting synch commit was successful

firmware_version¶

Firmware version reported by the device.

Property	Value
Base type	struct
Bit width	32

Signals:

Name	Type	Default value	Description
`firmware_patch`	`uint8_t`	`0`	Firmware version patch number
`firmware_minor`	`uint8_t`	`0`	Firmware version minor number
`firmware_year`	`uint16_t`	`0`	Firmware version year

rfloat32¶

An IEEE single-precision float32 that cannot be NaN or infinite.

Property	Value
Base type	float
Bit width	32
Minimum value	n/a
Maximum value	n/a
Default value	0

pfloat32¶

An IEEE single-precision float32 that must be non-negative but may be NaN or infinite.

Property	Value
Base type	float
Bit width	32
Minimum value	0.0
Maximum value	n/a
Default value	0

prfloat32¶

An IEEE single-precision float32 that must be non-negative AND cannot be NaN or infinite.

Property	Value
Base type	float
Bit width	32
Minimum value	0.0
Maximum value	n/a
Default value	0

lfloat32¶

An IEEE single-precision float32 constrained between 0 and 1 inclusive.

Property	Value
Base type	float
Bit width	32
Minimum value	0.0
Maximum value	1.0
Default value	0

faults¶

Property	Value
Base type	bitset
Bit width	8

Flags:

Flag index	Flag name	Description
0	power_cycle	The power cycle fault flag, which is set to true when the device first boots. Clearing sticky faults and then checking this flag can be used to determine if the device rebooted.
1	can_id_conflict	The CAN ID conflict flag, which is set to true if there is a CAN id conflict. In practice, you should physically inspect the device to ensure it’s not flashing blue.
2	can_general_error	The CAN general error flag, which will raise if the device encounters a CAN fault during operation. If communication with the device still functions, this will not register as an active fault for long if at all. This may raise due to wiring issues, such as an intermittently shorted CAN bus.
3	out_of_temperature_range	The temperature range flag, which will raise if the device is not between 0-70 degrees Celsius. This may be of concern if the device is near very active motors.
4	hardware_fault_distance	The hardware fault flag corresponding to the distance sensor IC, which will raise if a hardware issue is detected. Generally will raise if the device’s controller cannot read the physical sensor itself.
5	hardware_fault_color	The hardware fault flag corresponding to the color sensor IC, which will raise if a hardware issue is detected. Generally will raise if the device’s controller cannot read the physical sensor itself.
6	i2c_bus_recovery	The I2C bus recovery flag, which will raise when the device needs to completely restart the I2C bus. This fault flag should not be active for very long; if it is stuck as an active fault, that may indicate a hardware issue.

temperature¶

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

Property	Value
Base type	sint
Bit width	16
Minimum value	-32768
Maximum value	32767
Default value	0
Conversion factor	1 LSB = \(\frac{1}{256}\) deg C

digout_cond¶

Property	Value
Base type	bitset
Bit width	16

Flags:

Flag index	Flag name	Description
0	slot0	Slot 0
1	slot1	Slot 1
2	slot2	Slot 2
3	slot3	Slot 3
4	slot4	Slot 4
5	slot5	Slot 5
6	slot6	Slot 6
7	slot7	Slot 7
8	slot8	Slot 8
9	slot9	Slot 9
10	slot10	Slot 10
11	slot11	Slot 11
12	slot12	Slot 12
13	slot13	Slot 13
14	slot14	Slot 14
15	slot15	Slot 15

lamp_brightness¶

Lamp LED brightness, scalable from 0 (off) to 1.0 (full brightness)

Property	Value
Base type	uint
Bit width	16
Minimum value	0
Maximum value	36000
Default value	36000
Conversion factor	1 LSB = \(\frac{1}{36000}\) max brightness

digout_control_config¶

Controls how a physical digital output should act.

Only DIGOUT2 supports PWM output; if DIGOUT1 is configured to PWM mode, nothing will happen.

Property	Value
Base type	struct
Bit width	44

Signals:

Name	Type	Default value	Description
`output_config`	DIGOUT_OUTPUT_CONFIG	DISABLED	Enable digout pad
`pwm_data_source`	DATA_SOURCE	ZERO	The data source to use in PWM mode.
`reserved`	`pad32_t`	`0`	Reserved

digout_message_trigger¶

Controls when a digout state message should be sent during a digout state transition.

Even if the physical digital outputs GPIOs are not enabled for use, digout slots are still evaluated and digout state messages on condition change can still be sent.

This allows the Canandcolor to send digout alerts over a bus like CAN within a millisecond of detecting a state change.

Property	Value
Base type	struct
Bit width	2

Signals:

Name	Type	Default value	Description
`positive_edge`	`bool`	`false`	Send digout message on positive edge (false->true)
`negative_edge`	`bool`	`false`	Send digout message on negative edge (true->false)

digout_slot¶

Digout slot. Represents a digital output slot – a component of programmable digital logic updated at 1000 Hz to evaluate sensor conditions fast.

The basic concept of digital output slots are that they let the Canandcolor detect and analyze things independent of and faster than the typical core robot control loop, as well as give signals to other control electronics (e.g. motor limit switch inputs).

For example, a game element moving through a robot’s indexer really fast may need a fast reaction from control electronics in order for an internal mechanical handoff to work. Digout slots can be used to detect when an element passes by and have the Canandcolor immidiately output a digital signal and/or a CAN message indicating that it has seen an element.

There are two independently-operated digout “channels” each with 16 individual “slots”. Each “slot” evaluates individual conditions about the current sensor readings e.g. comparing red and blue channels or or comparing the proximity sensor against a known constant proximity.

These slots can be composed together with boolean conditions to evaluate to an overall boolean condition (the channel’s value). This channel value can be outputted over CAN via the digital output message and/or the associated physical digital output pin. Combined with output trigger configuration, this can be used for interrupt-driven CAN operation.

Individual digout slots (numbered 0 to 15 inclusive) are composed of the following components:

A boolean enabled field; if disabled, the slot always evaluates to true
How the slot “chains” with the next slot (next slot action)
A boolean indicating whether the slot should apply a logical NOT to its currently evaluated condition
The comparison operation to execute. If the evaluated expression could go negative, it saturates at 0.
A “left hand side”, “A” or “LHS” data source
A “right hand side”, “B” or “RHS” data source that can be scaled or added to before comparing with the LHS value.
An 8-bit unsigned “scaling immidiate” used to scale the RHS data source
A 21-bit signed “additive immidiate” added to the scaled RHS data source

Digout slots can be grouped into “chains” by specifying their next slot action field. Each chain is comprised of adjacent slots that are joined together with an AND, OR, XOR, until a slot specifies termination. Each chain must be true for the overall digital output value to be true, and this behavior can be used to gate entire expressions around time requirements (e.g. for debouncing reasons)

Property	Value
Base type	struct
Bit width	48

Signals:

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

scaling_factor¶

Scaling factor. Value of the RHS data source gets multiplied with ([affine_scale_value] + 1) / 256.

Zero is not representable here because the zero data source should be used instead if that is desired.

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

Enums¶

Enums associated with messages and/or settings. The backing type is always an unsigned int of some specified width.

EXTRA_FRAME_MODE¶

Extra frame period modes to minimize sensor latency. The sensors on the Canandcolor update relatively slowly due to their integrating nature. This means periodic frames may not always have the most recent data.

For example, by default, the color sensor IC updates every 25 ms and is broadcast every 25 ms. If the last sensor IC update happens at t = 0 ms but the next frame period broadcast happens at t = 10 ms, the data will be 10 milliseconds behind.

These options can address this problem in various ways:

DISABLED leaves it be, relying on the standard frame period interface.
EARLY_TRANSMIT_ON_CHANGE makes it such that if the frame period is not disabled, the frame will be broadcasted early and the frame period timer is reset. In the above example, this would broadcast the color frame at t = 0 ms, and the next color frame is scheduled for t = 25 ms instead of 35 ms.

This option generally increases bus utilization.

Property	Value
Bit width	8
Default enum	EARLY_TRANSMIT_ON_CHANGE

Enum variants:

Enum index	Variant name	Description
0x0	DISABLED	Do not emit extra frames beyond those specified in the frame period
0x1	EARLY_TRANSMIT_ON_CHANGE	Transmits a frame immidiately once readings change

DIGOUT_OUTPUT_CONFIG¶

Digout output configuration

Property	Value
Bit width	8
Default enum	DISABLED

Enum variants:

Enum index	Variant name	Description
0x0	DISABLED	Disable output on this pin
0x1	DIGOUT_LOGIC_ACTIVE_HIGH	Use digital logic pin, output 3.3v on true and 0v on false
0x2	DIGOUT_LOGIC_ACTIVE_LOW	Use digital logic pin, output 0v on true and 3.3v on false
0x3	DUTY_CYCLE_OUTPUT	Output a duty cycle on this pin. Only works on DIG-2

SLOT_OPCODE¶

Digout slot opcode specifying which value to evaluate

Property	Value
Bit width	7
Default enum	EQUALS

Enum variants:

Enum index	Variant name	Description
0x0	EQUALS	true if `a = b * (imm_scaling + 1) / 256 + (imm_additive)`
0x1	LESS_THAN	true if `a < b * (imm_scaling + 1) / 256 + (imm_additive)`
0x2	GREATER_THAN	true if `a > b * (imm_scaling + 1) / 256 + (imm_additive)`
0x3	LESS_THAN_OR_EQUALS	true if `a <= b * (imm_scaling + 1) / 256 + (imm_additive)`
0x4	GREATER_THAN_OR_EQUALS	true if``a >= b * (imm_scaling + 1) / 256 + (imm_additive)``
0x5	PREV_SLOT_TRUE	true if previous slot true for `b * (imm_scaling + 1) / 256 + (imm_additive)` milliseconds
0x6	PREV_CLAUSE_TRUE	true if previous joined-slot-chain true for `b * (imm_scaling + 1) / 256 + (imm_additive)` milliseconds

NEXT_SLOT_ACTION¶

How the digout slot interacts with the next numbered slot by index (e.g. slot 0 to slot 1)

Property	Value
Bit width	2
Default enum	TERMINATE_CHAIN

Enum variants:

Enum index	Variant name	Description
0x0	TERMINATE_CHAIN	Do not interact with the next slot
0x1	OR_WITH_NEXT_SLOT	Logical OR with next slot
0x2	XOR_WITH_NEXT_SLOT	Logical XOR with next slot
0x3	AND_WITH_NEXT_SLOT	Logical AND with next slot

DATA_SOURCE¶

Data source for digital outputs (usable in digout slots or for PWM configuration)

Property	Value
Bit width	4
Default enum	ZERO

Enum variants:

Enum index	Variant name	Description
0x0	ZERO	Always reads zero; can be used to compare only to additive immidate0
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

COLOR_INTEGRATION_PERIOD¶

Color integration period. This also determines the output resolution of the color channels. Shorter integration periods increase responsiveness at the cost of sensitivity to light, as there is less time for light to collect on the sensor.

In general, robotics applications favor shorter integration periods, so 25 ms is set as the default.

Readings are always polled every 25 ms or 40 Hz.

Property	Value
Bit width	4
Default enum	PERIOD_25_ms_RESOLUTION_16_bit

Enum variants:

Enum index	Variant name	Description
0x0	PERIOD_400_ms_RESOLUTION_20_bit	400 ms - 20 bit resolution
0x1	PERIOD_200_ms_RESOLUTION_19_bit	200 ms - 19 bit resolution
0x2	PERIOD_100_ms_RESOLUTION_18_bit	100 ms - 18 bit resolution
0x3	PERIOD_50_ms_RESOLUTION_17_bit	50 ms - 17 bit resolution
0x4	PERIOD_25_ms_RESOLUTION_16_bit	25 ms - 16 bit resolution

DISTANCE_INTEGRATION_PERIOD¶

Distance integration period. This determines how long the sensor spends collecting IR light to determine a distance reading, which also determines its update rate. Longer integration periods increase sensitivity, but shorter integration periods have faster update rates.

The default configuration is configured for an update rate of 20 ms.

Property	Value
Bit width	4
Default enum	PERIOD_20_ms

Enum variants:

Enum index	Variant name	Description
0x0	PERIOD_5_ms	5 millisecond period
0x1	PERIOD_7p5_ms	7.5 millisecond period
0x2	PERIOD_10_ms	10 millisecond period
0x3	PERIOD_12p5_ms	12.5 millisecond period
0x4	PERIOD_15_ms	15 millisecond period
0x5	PERIOD_17p5_ms	17.5 millisecond period
0x6	PERIOD_20_ms	20 millisecond period
0x7	PERIOD_40_ms	40 millisecond period

SETTING_COMMAND¶

These are setting commands issued via the setting command message.

The fetch setting command and reset factory settings command are common to all Redux devices.

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 of all indexes
0x1	RESET_FACTORY_DEFAULT	Reset all resettanble settings to factory default, and broadcast all setting values via report setting messages.
0x2	FETCH_SETTING_VALUE	Requests to fetch a single setting from device, with its value reported via the report setting message. This requires the use of the second byte to specify the setting index to fetch.
0xff	CLEAR_DIGOUT1	Clear all digout1 slots
0xfe	CLEAR_DIGOUT2	Clear all digout2 slots
0xfd	FETCH_DIGOUT1	Fetch all digout1 slots and settings
0xfc	FETCH_DIGOUT2	Fetch all digout2 slots and settings