ReduxLib C++ 2023.2.0
No Matches
redux::sensors::canandcolor::Canandcolor Class Reference

#include <Canandcolor.h>

Inheritance diagram for redux::sensors::canandcolor::Canandcolor:

Public Member Functions

 Canandcolor (int canID)
double GetProximity ()
double GetRed ()
double GetGreen ()
double GetBlue ()
double GetWhite ()
CanandcolorColor GetColor ()
CanandcolorDigoutState GetDigoutState ()
CanandcolorFaults GetStickyFaults ()
CanandcolorFaults GetActiveFaults ()
units::celsius_t GetTemperature ()
void ClearStickyFaults ()
void SetPartyMode (uint8_t level)
std::optional< CanandcolorSettingsGetSettings (units::second_t timeout=500_ms)
void SetLampLED (bool lamp)
void StartFetchSettings ()
CanandcolorSettings GetSettingsAsync ()
bool SetSettings (CanandcolorSettings &settings, units::second_t timeout=50_ms)
bool SetDigoutSlot (CanandcolorDigitalOutput digout, uint8_t slotIndex, CanandcolorDigoutSlot &slotConfig, units::second_t timeout=50_ms)
std::optional< CanandcolorDigoutSlotGetDigoutSlot (CanandcolorDigitalOutput digout, uint8_t slotIndex, units::second_t timeout=50_ms)
void ClearAllDigoutSlots (CanandcolorDigitalOutput digout)
std::optional< CanandcolorSettingsResetFactoryDefaults (units::second_t timeout=500_ms)
bool IsPresent (units::second_t timeout=2000_ms)
redux::frames::Frame< double > & GetProximityFrame ()
redux::frames::Frame< CanandcolorColor > & GetColorFrame ()
redux::frames::Frame< CanandcolorDigoutState > & GetDigoutFrame ()
redux::frames::Frame< CanandcolorStatus > & GetStatusFrame ()
void HandleMessage (redux::canand::CanandMessage &msg) override
redux::canand::CanandAddressGetAddress () override
virtual void HandleMessage (CanandMessage &msg)=0
virtual CanandAddressGetAddress ()=0

Protected Attributes

redux::frames::Frame< double > proximity {0.0, 0_ms}
redux::frames::Frame< CanandcolorColorcolor {CanandcolorColor{0.0, 0.0, 0.0, 0.0}, 0_ms}
redux::frames::Frame< CanandcolorDigoutStatedigout {CanandcolorDigoutState{0}, 0_ms}
redux::frames::Frame< CanandcolorStatusstatus {CanandcolorStatus{0, 0, false, 0_degC}, 0_ms}

Additional Inherited Members

- Protected Member Functions inherited from redux::canand::CanandDevice
void SetSettingById (uint8_t settingId, uint8_t *value, uint8_t length)
void HandleSettingRecv (uint8_t settingId, uint64_t settingValue)
std::optional< uint64_t > ConfirmSetSetting (uint8_t settingIdx, uint8_t *payload, uint8_t length, units::second_t timeout)
std::optional< uint64_t > FetchSetting (uint8_t settingIdx, units::second_t timeout)
bool SendCANMessage (uint8_t apiIndex, uint8_t *data, uint8_t length)
template<std::size_t len>
requires (len < 8U)
void SendCANMessage (uint8_t msgId, std::span< std::byte, len > data)
void SendSettingCommand (uint8_t settingCmdIdx)

Detailed Description

Class for the CAN interface of the Canandcolor.

Operations that receive data from the device (proximity, color, faults, temperature) generally do not block. The object receives data asynchronously from the CAN packet receive thread and reads thus return the last data received.

Operations that set settings or change offsets will generally wait for up to 50ms by default as they will usually wait for a confirmation packet to be received in response – unless the blocking timeout is set to zero, in which case the operations will not block.

Example code:

Canandcolor canandcolor{0}; // device id 0 

// Reading the Canandcolor
canandcolor.GetProximity(); // returns a proximity value [0..1). Larger values are distances closer to the sensor.

// these are all bounded [0..1)

// Changing configuration
CanandcolorSettings settings{};
settings.SetProximityFramePeriod(10_ms); // set the proximity frame period to be sent every 10 ms
settings.SetColorFramePeriod(40_ms); // set the position frame period to be sent every 40 ms
settings.SetColorIntegrationPeriod(CanandcolorColorIntegration.kPeriod40Ms); // set the color sensor integration to happen over 80 milliseconds
canandcolor.SetSettings(settings, 50_ms); // apply the new settings to the device, with maximum 50 ms timeout per settings op

// Faults
canandcolor.ClearStickyFaults(); // clears all sticky faults (including the power cycle flag). This call does not block.

// The power cycle flag will always be true on boot until the sticky faults have been cleared, 
// so if this is true the device has rebooted sometime between clearStickyFaults and now.
CanandcolorFaults faults = canandcolor.GetStickyFaults(); // fetches faults
fmt::print("Canandcolor rebooted: {}\n", faults.powerCycle);

// Timestamped data
FrameData<Double> proxFrame = canandcolor.GetProximityFrame().GetFrameData(); // gets current proximity + timestamp together
proxFrame.GetValue(); // fetched position in rotations
proxFrame.GetTimestamp(); // timestamp of the previous position

Constructor & Destructor Documentation

◆ Canandcolor()

redux::sensors::canandcolor::Canandcolor::Canandcolor ( int  canID)

Instantiates a new Canandcolor object. This object will be constant with respect to whatever CAN id assigned to it, so if a device changes id it may change which device this object reads from.

canIDthe device id to use [0..63]

Member Function Documentation

◆ ClearAllDigoutSlots()

void redux::sensors::canandcolor::Canandcolor::ClearAllDigoutSlots ( CanandcolorDigitalOutput  digout)

Clears all configured "slots" on the specified digital output.

digoutthe digital output to clear slots on

◆ ClearStickyFaults()

void redux::sensors::canandcolor::Canandcolor::ClearStickyFaults ( )

Clears sticky faults.

It is recommended to clear this during initialization, so one can check if the device loses power during operation later.

This call does not block, so it may take up to the next status frame (default every 1000 ms) for the sticky faults to be updated. To check for validity, use CanandcolorFaults::FaultsValid() for faults returned by GetStickyFaults()

◆ GetActiveFaults()

CanandcolorFaults redux::sensors::canandcolor::Canandcolor::GetActiveFaults ( )

Returns an object representing currently active faults. Active faults are only active for as long as the error state exists.

CanandcolorFaults of the active faults

◆ GetAddress()

redux::canand::CanandAddress & redux::sensors::canandcolor::Canandcolor::GetAddress ( )

Returns the reference to the CanandAddress representing the combination of CAN bus and CAN device ID that this CanandDevice refers to.

Implementing device subclasses should likely construct a new CanandAddress in their constructor and return it here.

a reference to the CanandAddress for the device.

Implements redux::canand::CanandDevice.

◆ GetBlue()

double redux::sensors::canandcolor::Canandcolor::GetBlue ( )

Blue intensity, normalized [0..1) where 0 is none and 1 is as bright as possible.

blue intensity [0..1)

◆ GetColor()

CanandcolorColor redux::sensors::canandcolor::Canandcolor::GetColor ( )

Returns a CanandcolorColor object which can also convert to HSV.

color object

◆ GetColorFrame()

redux::frames::Frame< CanandcolorColor > & redux::sensors::canandcolor::Canandcolor::GetColorFrame ( )

Returns the color reading frame, which includes CAN timestamp data.

the color reading frame, which will hold timestamped color readings
See also

◆ GetDigoutFrame()

redux::frames::Frame< CanandcolorDigoutState > & redux::sensors::canandcolor::Canandcolor::GetDigoutFrame ( )

Returns the digital output state frame, which includes CAN timestamp data.

the digital output state frame

◆ GetDigoutSlot()

std::optional< CanandcolorDigoutSlot > redux::sensors::canandcolor::Canandcolor::GetDigoutSlot ( CanandcolorDigitalOutput  digout,
uint8_t  slotIndex,
units::second_t  timeout = 50_ms 

Fetches a digout slot's configuration.

These condition slots are used to determine the value of the digital outputs. For more information on how these slots work, see

digoutdigital output associated with the slot to fetch from
slotIndexThe index of the slot to fetch from (0-15)
timeoutThe timeout to wait for the slot to be retrieved (default 50_ms, set to 0_s to not block)
std::optional with CanandcolorDigoutSlot object on success, nullopt on failure

◆ GetDigoutState()

CanandcolorDigoutState redux::sensors::canandcolor::Canandcolor::GetDigoutState ( )

Returns a CanandcolorDigoutState object representing the current state of the digital outputs.

color object

◆ GetGreen()

double redux::sensors::canandcolor::Canandcolor::GetGreen ( )

Green intensity, normalized [0..1) where 0 is none and 1 is as bright as possible.

green intensity [0..1)

◆ GetProximity()

double redux::sensors::canandcolor::Canandcolor::GetProximity ( )

Gets the currently sensed proximity normalized between [0..1]. Proximity decreases as objects get further away from the sensor face and increases as they approach the sensor. Proximities that are too close will saturate at 1.0.

Note that proximity is not given a unit as different materials and sensor configurations can greatly vary how proximity translates to actual distance. It is generally presumed that users will have to finetune specific thresholds for applications anyway and units may not be meaningful or accurate.

proximity value (range [0..1])

◆ GetProximityFrame()

redux::frames::Frame< double > & redux::sensors::canandcolor::Canandcolor::GetProximityFrame ( )

Returns the proximity reading frame.

the proximity reading frame, which will hold the current proximity in the same units as GetProximity()
See also

◆ GetRed()

double redux::sensors::canandcolor::Canandcolor::GetRed ( )

Red intensity, normalized [0..1) where 0 is none and 1 is as bright as possible.

red intensity [0..1)

◆ GetSettings()

std::optional< CanandcolorSettings > redux::sensors::canandcolor::Canandcolor::GetSettings ( units::second_t  timeout = 500_ms)

Fetches the Canandcolor's current configuration in a blocking manner. This function will block for at least about 0.2-0.3 seconds waiting for the device to reply, so it is best to put this in a teleop or autonomous init function, rather than the main loop.

timeoutmaximum number of seconds to wait for settings before giving up
std::optional with CanandcolorSettings representing the device's configuration, or nullopt on timeout.

◆ GetSettingsAsync()

CanandcolorSettings redux::sensors::canandcolor::Canandcolor::GetSettingsAsync ( )

Non-blockingly returns a CanandcolorSettings object of the most recent known settings values received from the device.

Most users will probably want to use Canandcolor::GetSettings instead.

One can call this after a Canandcolor::StartFetchSettings() call, and use CanandcolorSettings::AllSettingsReceived() to check if/when all values have been seen. As an example:

// somewhere in an init function
Canandcolor canandcolor{0};

// ...
// somewhere in a loop function

if (canandcolor.GetSettingsAsync().AllSettingsReceived()) {
  // do something with the settings object
  fmt::print("Canandcolor lamp enable: {}\n", canandcolor.GetSettingsAsync().GetLampEnable());

If this is called after Canandcolor::SetSettings(CanandcolorSettings), this method will return a settings object where only the fields where the device has echoed the new values back will be populated. To illustrate this, consider the following:

 // somewhere in a loop 
canandcolor.SetSettings(new CanandcolorSettings().setProximityFramePeriod(0.100));
canandcolor.GetSettingsAsync().GetProximityFramePeriod(); // will likely return nullopt as the device hasn't confirmed the previous transaction

// after up to ~300 ms...
canandcolor.GetSettingsAsync().GetProximityFramePeriod(); // will likely return 100 ms
CanandcolorSettings object of known settings

◆ GetStatusFrame()

redux::frames::Frame< CanandcolorStatus > & redux::sensors::canandcolor::Canandcolor::GetStatusFrame ( )

Returns the current status frame, which includes CAN timestamp data. FrameData objects are immutable.

the current status frame, as a CanandcolorStatus record.

◆ GetStickyFaults()

CanandcolorFaults redux::sensors::canandcolor::Canandcolor::GetStickyFaults ( )

Returns sticky faults. Sticky faults are the active faults, except once set they do not become unset until ClearStickyFaults() is called.

CanandcolorFaults of the sticky faults.

◆ GetTemperature()

units::celsius_t redux::sensors::canandcolor::Canandcolor::GetTemperature ( )

Get onboard device temperature readings in degrees Celsius.

temperature in degrees Celsius

◆ GetWhite()

double redux::sensors::canandcolor::Canandcolor::GetWhite ( )

White intensity, normalized [0..1) This can be used as a proxy for proximity at ranges too close for the normmal proximity sensor to give useful values.

absolute position in fraction of a rotation [0..1)

◆ HandleMessage()

void redux::sensors::canandcolor::Canandcolor::HandleMessage ( redux::canand::CanandMessage msg)

A callback called when a Redux CAN message is received and should be parsed. Subclasses of CanandDevice should override this to update their internal state accordingly.

HandleMessage will be called on all Redux CAN packets received by the vendordep that match the CanandAddress returned by CanandDevice::GetAddress().

msga reference to a CanandMessage representing the received message. The message may not have lifetime outside the function call.

Implements redux::canand::CanandDevice.

◆ IsPresent()

bool redux::sensors::canandcolor::Canandcolor::IsPresent ( units::second_t  timeout = 2000_ms)

Checks whether or not the device has sent a message within the last timeout seconds.

timeoutwindow to check for message updates in seconds (default 2000 ms)
true if there has been a message within the last timeout seconds, false if not

◆ ResetFactoryDefaults()

std::optional< CanandcolorSettings > redux::sensors::canandcolor::Canandcolor::ResetFactoryDefaults ( units::second_t  timeout = 500_ms)

Resets the Canandcolor to factory defaults.

timeouthow long to wait for the new settings to be confirmed by the device in seconds (suggested at least 0.35 seconds)
std::optional with CanandcolorSettings object if successful, nullopt on confirmation timeout or if timeout is 0

◆ SetDigoutSlot()

bool redux::sensors::canandcolor::Canandcolor::SetDigoutSlot ( CanandcolorDigitalOutput  digout,
uint8_t  slotIndex,
CanandcolorDigoutSlot slotConfig,
units::second_t  timeout = 50_ms 

Sets an indexed slot on a Canandcolor digital output.

These condition slots are used to determine the value of the digital outputs. For more information on how these slots work, see

digoutThe digital output associated with the slot to write
slotIndexThe index of the slot to write to (0-15)
slotConfigThe actual slot data (see CanandcolorDigoutSlot)
timeoutThe timeout to wait for a confirmation message (default 50_ms, set to 0_s to not block)
whether or not the slot update was successful

◆ SetLampLED()

void redux::sensors::canandcolor::Canandcolor::SetLampLED ( bool  lamp)

Sets whether or not the onboard lamp LED is to be powered.

The LED can also be physically turned off regardless of setting with the onboard switch.

The LED is useful for measuring the color of objects that do not themselves emit light (e.g. most game pieces) or for using the white channel to estimate very close proximity.

By factory default the lamp is enabled.

lampwhether to enable or disable the lamp LED

◆ SetPartyMode()

void redux::sensors::canandcolor::Canandcolor::SetPartyMode ( uint8_t  level)

Controls "party mode" – an device identification tool that blinks the onboard LED various colors at a user-specified strobe period. The strobe period of the LED will be (50 milliseconds * level). Setting this to 0 disables party mode.

This function does not block.

levelthe party level value to set.

◆ SetSettings()

bool redux::sensors::canandcolor::Canandcolor::SetSettings ( CanandcolorSettings settings,
units::second_t  timeout = 50_ms 

Applies the settings from a CanandcolorSettings object to the device. For more information, see the CanandcolorSettings class documentation.

settingsthe CanandcolorSettings to update the device with
timeoutmaximum time in seconds to wait for each setting to be confirmed (default 50 ms). Set to 0 to not check (and not block).
true if successful, false if a setting operation timed out

◆ StartFetchSettings()

void redux::sensors::canandcolor::Canandcolor::StartFetchSettings ( )

Tells the Canandcolor to begin transmitting its settings; once they are all transmitted (after ~200-300ms), the values can be retrieved from Canandcolor::GetSettingsAsync()

Member Data Documentation

◆ color

redux::frames::Frame<CanandcolorColor> redux::sensors::canandcolor::Canandcolor::color {CanandcolorColor{0.0, 0.0, 0.0, 0.0}, 0_ms}

internal Frame variable holding current color state

◆ digout

redux::frames::Frame<CanandcolorDigoutState> redux::sensors::canandcolor::Canandcolor::digout {CanandcolorDigoutState{0}, 0_ms}

internal Frame variable holding current digital output state

◆ proximity

redux::frames::Frame<double> redux::sensors::canandcolor::Canandcolor::proximity {0.0, 0_ms}

internal Frame variable holding current proximity state

◆ status

redux::frames::Frame<CanandcolorStatus> redux::sensors::canandcolor::Canandcolor::status {CanandcolorStatus{0, 0, false, 0_degC}, 0_ms}

internal Frame variable holding current status value state

The documentation for this class was generated from the following file: