General Canandcolor Settings

The CanandcolorSettings object is used to reconfigure the Canandcolor.

Creation

Java

// Create a blank object with no values.
// Only values that are changed will be updated on the device.
CanandcolorSettings settings = new CanandcolorSettings();

// Copy the values to a new settings object.
CanandcolorSettings copiedSettings = new CanandcolorSettings(settings);

C++

using namespace redux::sensors::canandcolor;
// Create with no values
// Only values that are changed will be updated on the device.
CanandcolorSettings settings;

// Copy the values to a new settings object via the copy constructor.
CanandcolorSettings copiedSettings{settings};

Values are fetched and updated using the getter and setter functions in CanandcolorSettings.

Caution

Only values updated by the user are changed on the device. Values that are not changed will remain the same.

Writing Settings To The Canandcolor

When you are ready to send and save the settings to the device, you can use Canandcolor.setSettings to transmit the contents of a CanandcolorSettings object to the Canandcolor.

Java

// A canandcolor object with CAN ID 0
Canandcolor canandcolor = new Canandcolor(0);

// Create a new settings object
CanandcolorSettings settings = new CanandcolorSettings();

// Setup some settings to write:

// set lamp LED brightness to 40%
settings.setLampLEDBrightness(0.4);

// Write the settings to the Canandcolor with a timeout of 50 milliseconds per setting.
// By default the settings will be written to flash -- they will persist on reboots.
// If this is not desired, one can use
//
//     settings.setEphemeral(true);
//
// to flag the settings as ephemeral (and not persist in flash on reboot).
canandcolor.setSettings(settings);

C++

using namespace redux::sensors::canandcolor;
// A canandcolor object with CAN ID 0
Canandcolor canandcolor{0};

// Create a new settings object
CanandcolorSettings settings{};

// Setup some settings to write:

// set lamp LED brightness to 40%
settings.SetLampLEDBrightness(0.4);

// Write the settings to the Canandcolor with a timeout of 50 milliseconds per setting.
// By default the settings will be written to flash -- they will persist on reboots.
// If this is not desired, one can use
//
//     settings.SetEphemeral(true);
//
// to flag the settings as ephemeral (and not persist in flash on reboot).
canandcolor.SetSettings(settings);

Fetching Settings From Device

Settings can be fetched from the end device in both a synchronous and asynchronous manner. Due to the synchronous method blocking for 0.15-0.25 seconds, it is recommended to use it only in robot initialization or on a separate thread.

The blocking method, Canandcolor.getSettings will always return a CanandcolorSettings object. The object returned will hold all the settings that were able to be successfully received. To check if all settings were successfully received, use the CanandcolorSettings.allSettingsReceived() method.

The async method, Canandcolor.getSettingsAsync will return the most recent set of settings that have been sent by the device since a preceding Canandcolor.startFetchSettings(). Similarly to getSettings, one can use the CanandcolorSettings.allSettingsReceived() method to check for the receipt of all settings.

The getters on CanandcolorSettings objects either return a value if one was received, or null (Java)/std::nullopt (C++) if one was not.

Synchronous (blocking)

Java

// A Canandcolor object with CAN ID 0
Canandcolor canandcolor = new Canandcolor(0);

// Fetch this Canandcolor's settings.
// This runs with a default timeout of 0.35 seconds.
CanandcolorSettings settings = canandcolor.getSettings();

// Fetch this Canandcolor's settings.
// This runs with a timeout of 0.5 seconds
CanandcolorSettings settingsCustom = canandcolor.getSettings(0.5);

// Fetch the status frame period from the received settings
// This will be either a double (seconds) or null if the status frame period
// was not successully received.
if (settings.getStatusFramePeriod() != null) {
    System.out.printf("Status frame period: %f
", settings.getStatusFramePeriod());
} else {
    System.out.println("getStatusFramePeriod returned null :/");
}

C++

using namespace redux::sensors::canandcolor;
// A Canandcolor object with CAN ID 0
Canandcolor canandcolor{0};

// Fetch this Canandcolor's settings
// This runs with a default timeout of 0.35 seconds
CanandcolorSettings settings = canandcolor.GetSettings();

// Fetch the status frame period from the received settings
// This will be either a double (seconds) or null if the status frame period
// was not successully received.
if (settings.GetStatusFramePeriod()) {
    fmt::print("Status frame period: {}
", settings.GetStatusFramePeriod());
} else {
    fmt::print("GetStatusFramePeriod returned std::nullopt :/");
}

Asynchronous (non-blocking)

Java

// A Canandcolor object with CAN ID 0
Canandcolor canandcolor = new Canandcolor(0);

// Start the settings fetch
canandcolor.startFetchSettings();

// ...spend some period of time waiting for settings...

CanandcolorSettings settings = canandcolor.getSettingsAsync();
if (settings.allSettingsReceived()) {
    // We now know all settings have been received
    // ...do things with the settings object here...
}

C++

using namespace redux::sensors::canandcolor;
// A Canandcolor object with CAN ID 0
Canandcolor canandcolor{0};

// Start the settings fetch
canandcolor.StartFetchSettings();

//...spend some period of time waiting for settings...

CanandcolorSettings settings = canandcolor.GetSettingsAsync();
if (settings.AllSettingsReceived()) {
    // We now know all settings have been received
    // ...do things with the settings object here...
}

Settings

Status Frame Period

The status frame period is the time between status packets being sent by the Phosphorus Canandcolor over the CAN Bus. By default, this value is 1 second, meaning a status packet is sent every 1000 milliseconds. Lower values will mean packets get sent more frequently, but will correspondingly increase CAN bus utilization. This value cannot be set to zero or disabled. The maximum value of this value is 16.383 seconds (16383 milliseconds). This value is set with a resolution of 0.001 seconds (1 millisecond).

Default value: 1 second

Minimum value: 1 second

Maximum value: 16.383 seconds

Note

So what does the status frame actually do? The status frame carries information about the active faults (problems) with the device, its internal temperature reading, and some other general status information. This packet cannot be disabled as it is used for diagnostics and other critical functions.

FIRST® Robotics Competition

The CAN 2.0B bus in the FIRST® Robotics Competition operates at a rate of 1 Mbit/s, or 125000 bytes per second. To estimate CAN usage, you can multiply the size of the CAN packet by its send frequency in hertz, and divide that by 125000. CAN packets have 8 bytes of overhead. For example, a status packet is 6 bytes of data, so the full packet is 14 bytes. At 0.020 seconds, or 50 times a second, this takes up 700 / 125000 or 0.56% of the CAN bus.

Java

// Sets the status frame period to 1 second
settings.setStatusFramePeriod(1);

C++

// Sets the status frame period to 1 second
settings.SetStatusFramePeriod(1_s);

Proximity Frame Period

The proximity frame period is the time between proximity packets being sent by the Phosphorus Canandcolor over the CAN Bus. By default, this value is 0.010 seconds, meaning a proximity packet is sent every 10 milliseconds (for a total of 100 times a second).

This frame period supports aligning the frame to the integration period, which will automatically transmit early when new sensor data is available. In this mode, the frame period is the maximum allowed latency between packets.

Lower values will mean packets get sent more frequently, but will correspondingly increase CAN bus utilization. This value can be set to 0, which disables the proximity output. The maximum value of this value is 65.535 seconds (65535 milliseconds). This value is set with a resolution of 0.001 seconds (1 millisecond).

Default value: 0.010 seconds

Minimum value: 0 seconds (disables proximity output)

Maximum value: 65.535 seconds

Java

// Sets the proximity frame period to 10 milliseconds
settings.setProximityFramePeriod(0.010);

//Optional, aligns the proximity sensor frames to the integration period
//This will cause the sensor to immediately transmit new data when available.
settings.setAlignProximityFramesToIntegrationPeriod(true);

C++

// Sets the proximity frame period to 10 milliseconds
settings.SetProximityFramePeriod(10_ms);

//Optional, aligns the proximity sensor frames to the integration period
//This will cause the sensor to immediately transmit new data when available.
settings.SetAlignProximityFramesToIntegrationPeriod(true);

Color Frame Period

The color frame period is the time between color packets being sent by the Phosphorus Canandcolor over the CAN Bus. By default, this value is 0.040 seconds, meaning a color packet is sent every 40 milliseconds (for a total of 25 times a second).

This frame period supports aligning the frame to the integration period, which will automatically transmit early when new sensor data is available. In this mode, the frame period is the maximum allowed latency between packets.

Lower values will mean packets get sent more frequently, but will correspondingly increase CAN bus utilization. This value can be set to 0, which disables the color output. The maximum value of this value is 65.535 seconds (65535 milliseconds). This value is set with a resolution of 0.001 seconds (1 millisecond).

Default value: 0.040 seconds

Minimum value: 0 seconds (disables color output)

Maximum value: 65.535 seconds

Java

// Sets the color frame period to 40 milliseconds
settings.setColorFramePeriod(0.040);

//Optional, aligns the color sensor frames to the integration period
//This will cause the sensor to immediately transmit new data when available.
settings.setAlignColorFramesToIntegrationPeriod(true);

C++

// Sets the color frame period to 40 milliseconds
settings.SetColorFramePeriod(40_ms);

//Optional, aligns the color sensor frames to the integration period
//This will cause the sensor to immediately transmit new data when available.
settings.SetAlignColorFramesToIntegrationPeriod(true);

Digout Frame Period

The digout frame period is the time between digital output status packets being sent by the Phosphorus Canandcolor over the CAN Bus.

The digout packets contain the status of the two digital output lines.

This frame supports emitting packets early on state change. This allows the user code to immediately react to changes in the digital output state instead of needing to wait for the next frames.

By default, this value is 0.100 seconds, meaning a digout packet is sent every 100 milliseconds (for a total of 10 times a second).

Lower values will mean packets get sent more frequently, but will correspondingly increase CAN bus utilization. This value can be set to 0, which disables the digout packet. The maximum value of this value is 65.535 seconds (65535 milliseconds). This value is set with a resolution of 0.001 seconds (1 millisecond).

Note

Disabling the digout packet does NOT disable the digital pins, and adjusting the period of this packet does not change the rate at which the digital pads update.

Default value: 0.100 seconds

Minimum value: 0 seconds (disables digout output)

Maximum value: 65.535 seconds

Java

// Sets the digout frame period to 40 milliseconds
settings.setDigoutFramePeriod(0.040);

//Optional: Tells the device to early transmit a digital output packet if the status changes at all
//This example shows setting it for digital output 1
settings.setDigoutFrameTrigger(DigoutChannel.Index.kDigout1, DigoutFrameTrigger.kRisingAndFalling);

C++

// Sets the digout frame period to 40 milliseconds
settings.SetDigoutFramePeriod(40_ms);

//Optional: Tells the device to early transmit a digital output packet if the status changes at all
//This example shows setting it for digital output 1
settings.setDigoutFrameTrigger(DigoutChannel::Index::kDigout1, DigoutFrameTrigger::kRisingAndFalling);

Set Lamp LED

Turns the onboard lamp LED on or off.

Note

The onboard LED switch must be in the ENABLE position for this to turn the lamp on and off.

Default value: false

Java

// Turn on lamp
settings.setLampLED(true);

C++

// Turn on lamp
settings.SetLampLED(true);

Set Lamp LED Brightness

Sets the brightness of the onboard lamp LED. The lamp can still be turned on and off via setLampLED and the onboard switch. A value of 1.0 is full brightness, and a value of 0.0 is minimum brightness (off). For example, a value of 0.5 will be half of max brightness.

Default value: 1.0

Java

// Set lamp to full brightness
settings.setLampLEDBrightness(1.0);

C++

// Turn on lamp
settings.SetLampLEDBrightness(1.0);

Proximity Sensor Config

See: Canandcolor Proximity Settings

Color Sensor Config

See: Canandcolor Color Settings

Digital Output Config

See: Canandcolor Digital Ports