Canandcolor

Canandcolor-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	0x6
CAN Product ID	0x0
DBC File	Link

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

PROXIMITY_OUTPUT

Periodic frame with a 16-bit proximity field. Values increase as objects move closer to the sensor. Values of 0xffff indicate the sensor has been saturated; that is, the sensed proximity is too close for any clearer reading.

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

Properties

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

Signals

Signal name	Start bit	Bit length	Description
proximity	0	16	16-bit proximity value. This values increases as an object gets closer.

COLOR_OUTPUT

Periodic frame containing the currently read color value in terms of red, green, blue, and white as 16-bit values.

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

Properties

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

Signals

Signal name	Start bit	Bit length	Description
red	0	16	Red reading magnitude
green	16	16	Green reading magnitude
blue	32	16	Blue reading magnitude
white	48	16	White reading magnitude

DIGITAL_OUTPUT

Periodic frame containing the current state of the digital output pads. Additionally contains data for which condition slots are currently true and false (see DIGOUT1_CONFIG)

By factory default, this frame is transmitted onto the bus every 40 ms (via the DIGOUT_FRAME_PERIOD setting). For minimum latency, the digital outputs should probably be wired directly to digital i/o pins on either the Rio or a motor controller instead.

Properties

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

Signals

Signal name	Start bit	Bit length	Description
digout1_state	0	1	Digital output state for DIGOUT1
digout2_state	1	1	Digital output state for DIGOUT2
reserved	2	6	Reserved
digout1_cond	8	16	DIGOUT1 condition slot flags. A value of 1 for bit N means that condition slot is true. Bits are indexed little-endian.
digout2_cond	24	16	DIGOUT2 condition slot flags. A value of 1 for bit N means that condition slot is true. Bits are indexed little-endian.

STATUS

Status frame containing active and sticky fault data as well as temperature.

Properties

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

Signals

Signal name	Start bit	Bit length	Description
faults	0	8	8-bit active faults bitfield
sticky_faults	8	8	8-bit sticky faults bitfield
temperature	16	8	8-bit signed temperature byte in Celsius
reserved	24	40	Reserved bits

Settings

PROXIMITY_FRAME_PERIOD

Period between the transmission of proximity reading CAN frames in milliseconds. A 0 ms value disables transmission altogether.

Note that this does not change the sample rate of the proximity sensor IC (which operates at fastest every 10 ms).

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

COLOR_FRAME_PERIOD

Period between the transmission of color reading CAN frames in milliseconds. A 0 ms value disables transmission altogether.

Note that this does not change the sample rate of the color sensor IC (which operates at most every 40 ms).

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

DIGOUT_FRAME_PERIOD

Period between the transmission of digital output status CAN frames in milliseconds. A 0 ms value disables transmission altogether.

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

FRAME_PERIOD_LATENCY_ADJUST

If enabled and the period duration is less than or equal to the sensor sampling period, ignore any pending duration and immidiately send out the corresponding PROXIMITY_OUTPUT or COLOR_OUTPUT frame. This decreases latency of data but at the cost of CAN utilization, but if one is increasing CAN util with shorter periods, this is likely a desired tradeoff anyway.

The sampling period is 10 ms for the proximity sensor and 40 ms for the color sensor by default and is distinct from the frame period – for more information see COLOR_INTEGRATION_PERIOD and PROXIMITY_SENSOR_CONFIG

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

LAMP_ENABLE

Whether to allow the lamp LED to be powered. This LED can also be physically turned off regardless of setting with the onboard switch.

Leaving this LED on may be useful for measuring the color of objects that do not emit light, or for using the white channnel to estimate very close proximity.

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

COLOR_INTEGRATION_PERIOD

Determines how often the color sensor IC samples new values by adjusting how long it spends integrating (essentially, the sensor’s exposure time).

Longer integration times means values at lower light can be read more accurately, but also means they saturate faster in higher light conditions and overall latency is higher.

There are 6 discrete valid configurations for this, approximately equal to \(40 * 2^{\text{value}}\) milliseconds. Below is a table of them:

Value	Integration period
0x0	40 ms
0x1	80 ms
0x2	160 ms
0x3	320 ms
0x4	640 ms
0x5	1280 ms

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

PROXIMITY_SENSOR_CONFIG

32-bit parameter bitfield for how the proximity sensor IC functions. Attached is a breakdown of bits:

Byte	Bit Index	Description
0	0:1	Sensor sampling period
0	2:3	Integration period
0	4	Integration time base
0	5:7	IR LED current selection
1	8:9	Multi-pulse
1	10	High gain mode
1	11	Sunlight cancellation
2, 3	16:28	Cancellation value

Generally there is some tradeoff between higher power/longer IR pulses being good for longer detection distances but bad at ranges within 1-2 inches of the sensor, although this can be compensated for by using the white channel of the color sensor as an estimation of very close proximity.

Sensor sampling period

There isn’t much reason to increase this above the default 10 ms, except for very marginal power consumption reasons (<50 mA).

Default value is (0, 0) or (10 ms)

Bit 1	Bit 0	Integration period
0	0	10 ms
0	1	20 ms
1	0	40 ms
1	1	80 ms

Integration period and time base

This determines how long of an IR pulse is used to sense values. Longer pulses can sense farther distances but mean the sensor saturates at closer distances to the IC. It’s recommended to leave the time base bit set to 1 for greater sensitivity.

Default value is the max value of (1, 1, 1) or 400 μs

Time base bit	Period bit 1	Period bit 0	Pulse width (μs)
1	0	0	50 μs
1	0	1	100 μs
1	1	0	200 μs
1	1	1	400 μs
0	0	0	25 μs
0	0	1	50 μs
0	1	0	100 μs
0	1	1	200 μs

IR LED current selection

Determines how much current gets dumped into the IR LED and thus its intensity. Higher intensities can detect longer ranges but come at the tradeoff of close range saturation.

Default is max intensity (1, 1, 1) = 20 mA

Bit 2	Bit 1	Bit 0	IR LED current
0	0	0	6 mA
0	0	1	8 mA
0	1	0	10 mA
0	1	1	12 mA
1	0	0	14 mA
1	0	1	16 mA
1	1	0	18 mA
1	1	1	20 mA

Multi-pulse

Determines how many IR LED pulses get sent out during proximity reads. More pulses detect longer distances but may saturate the sensor at closer distances.

Default is (1, 1) = 8 pulses

Bit 1	Bit 0	Pulses
0	0	1
0	1	2
1	0	4
1	1	8

High gain mode

Enables or disables high gain mode (defaults 0)

Sunlight cancellation

Enables or disables sunlight cancellation (defaults 0)

May be useful for use on open air baseball fields with painfully loud speakers.

Cancellation value

Offset subtracted from proximity readings to account for ambient IR values (defaults 0).

May be useful for multiple IR-based proximity sensors nearby.

Property	Value
Setting Index	0xec
Factory default value	1020
Value range	[0, 268435456]
Mutability	Read/write

DIGOUT1_CONTROL_CONFIG

Specifies global parameters on the digital output DIGOUT1.

Byte	Bit index	Description
0	0	0 = Disable digout, 1 = Enable output on digital output 1
0	1	0 = normally open (outputs high when condition is true), 1 = normally closed (outputs low when condition is true)
0	2	0 = output according to digout slots, 1 = output a PWM value
0	3	Reserved
0	4	Bit 0 of PWM data source (see Digout Opcode Data Sources)
0	5	Bit 1 of PWM data source
0	6	Bit 2 of PWM data source
0	7	Bit 3 of PWM data source

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

DIGOUT2_CONTROL_CONFIG

Specifies global parameters on the digital output DIGOUT2.

Byte	Bit index	Description
0	0	0 = Disable digout, 1 = Enable output on digital output 2
0	1	0 = normally open (outputs high when condition is true), 1 = normally closed (outputs low when condition is true)
0	2	0 = output according to digout slots, 1 = output a PWM value
0	3	Reserved
0	4	Bit 0 of PWM data source (see Digout Opcode Data Sources)
0	5	Bit 1 of PWM data source
0	6	Bit 2 of PWM data source
0	7	Bit 3 of PWM data source

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

LAMP_BRIGHTNESS

How bright the lamp LED should be, from 0 (off) to 16384 (max brightness, the default).

The actual brightness of the LED is not linear to the brightness value as it’s just the PWM duty cycle.

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

DIGOUT1_CONFIG

The settings indexes 0xd0-0xdf are all boolean condition slots for digital output 1 (DIGOUT1) where 0xd0 is slot 0 and 0xdf is slot 15. Each slot represents an individual condition that contributes to the digital output’s value (they can be true or false)

Slots can specify the next slot a settings index up (e.g. for 0xd0 the next slot is 0xd1) is ANDed or ORed with it to form a clause, or can specify it does not join and thus terminates a clause. These can be chained to form clauses of multiple conditions. Each clause must be true for the output to be true (they are all ANDed together.)

Slots are evaluated from the lowest setting index counting up from slot 0 until slot 15.

Byte	Bits within byte	Name	Description
0	0	Slot enabled	1 = enabled, 0 = disabled. Disabled slots in a clause pass through the previous slot’s state.
0	1-2	Clause join	00 = terminate clause, 01 = OR with next slot for clause, 10 = XOR with next slot, 11 = AND with next.
0	3	Invert value	1 = Result is NOTed, 0 = don’t invert the result
0	4-7	Reserved
1	0-7	Opcode	See Digout Opcodes
2	0-7	Argument 1 byte 0	See Digout Opcodes
3	0-7	Argument 1 byte 1	See Digout Opcodes
4	0-7	Argument 2 byte 0	See Digout Opcodes
5	0-7	Argument 2 byte 1	See Digout Opcodes

Digout Opcodes

• All values are little endian (lower byte contains least significant half).

• Opcodes and the affine scalar value are unsigned 8 bit values.

• Immidiates and time values are unsigned 16-bit values.

• Affine offsets are signed 2’s complement 16-bit values.

• Data source indexes are 4-bit constants.

  • For the immediate instructions (opcode 0-4), they are in the lower 4 bits of argument 1 byte 0.

  • For the affine compare instructions (opcode 8-12), see Affine comparison opcodes

Opcode	Name	Arg 1 byte 0	Arg 1 byte 1	Arg 2 byte 0	Arg 2 byte 1	Description
0	Equals immediate	Data source (s1)	unused	immediate lsb	immediate msb	s1 == imm
1	Less than immediate	Data source (s1)	unused	immediate lsb	immediate msb	s1 < imm
2	Greater than immediate	Data source (s1)	unused	immediate lsb	immediate msb	s1 > imm
3	Less than or eq immediate	Data source (s1)	unused	immediate lsb	immediate msb	s1 <= imm
4	Greater than or eq immediate	Data source (s1)	unused	immediate lsb	immediate msb	s1 >= imm
5	Reserved
6	Reserved
7	Reserved
8	Equals with affine	Data sources (s1 | (s2 << 4))	Affine scale	Offset lsb	Offset msb	See Affine comparison opcodes
9	Less than with affine	Data sources (s1 | (s2 << 4))	Affine scale	Offset lsb	Offset msb	See Affine comparison opcodes
10	Greater than with affine	Data sources (s1 | (s2 << 4))	Affine scale	Offset lsb	Offset msb	See Affine comparison opcodes
11	Less than or eq with affine	Data sources (s1 | (s2 << 4))	Affine scale	Offset lsb	Offset msb	See Affine comparison opcodes
12	Greater than or eq with affine	Data sources (s1 | (s2 << 4))	Affine scale	Offset lsb	Offset msb	See Affine comparison opcodes
13	Reserved
14	Reserved
15	Reserved
16	Reserved
16	Previous slot true for past n milliseconds	Time (ms) lsb	Time (ms) msb	unused	unused	If the first slot, always return false
17	Previous clause true for past n milliseconds	Time (ms) lsb	Time (ms) msb	unused	unused	if a singleton clause, always return false

Digout Opcode Data Sources

These determine which 16-bit data register value to pull from in for each slot.

Index	Data source
0	Proximity
1	Red
2	Green
3	Blue
4	White
5	Hue
6	Sat
7	Value

Affine comparison opcodes

Affine comparison opcodes (indices 8, 9, 10, 11, and 12) pull from two data sources, encoded as having the lower four bits of arg1 byte 0 be the first source and the upper four bits being the second source:

arg_1[0] = index(s_1) | (index(s_2) << 4)

The operation scales the value from the first data source s1 and adds it to a signed offset before comparing it to s2 so the opcode will evaluate:

\[\min\left(\max\left(s_1 \frac{\text{affine}}{255} + \text{offset}, 0\right), 2^{16}-1\right) \text{[compare op]} s_2\]

where compare op is the comparison operator corresponding to that opcode.

DIGOUT2_CONFIG

Exactly the same as DIGOUT1_CONFIG except the settings indices are 0xc0 for the first slot and 0xcf for the last slot, and the output goes to DIGOUT2.

Setting commands

CLEAR_DIGOUT1

Clear all digout1 condition slots (see DIGOUT1_CONFIG for more info about condition slots)

Property	Value
Setting command index	0xff

CLEAR_DIGOUT2

Clear all digout2 condition slots (see DIGOUT1_CONFIG for more info about condition slots)

Property	Value
Setting command index	0xfe

Faults

These faults are reported in the active and sticky bitfields in the STATUS frame. All faults will affect the active and sticky fields – that is, an active fault will also set its corresponding sticky index to true, and the sticky fault will stay true even after the fault is no longer active until cleared.

POWER_CYCLE

Bit index: 0

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.

CAN_ID_CONFLICT

Bit index: 1

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.

CAN_GENERAL_ERROR

Bit index: 2

The CAN general error flag, which will raise if the device cannot RX packets reliably. This is usually due to wiring issues, such as a shorted CAN bus.

OUT_OF_TEMPERATURE_RANGE

Bit index: 3

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.

HARDWARE_FAULT_PROXIMITY

Bit index: 4

The hardware fault flag corresponding to the proximity 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.

HARDWARE_FAULT_COLOR

Bit index: 5

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.