#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 ()

CanandcolorColorData	GetColor ()

digout::DigoutSlotState	GetDigoutState ()

CanandcolorFaults	GetStickyFaults ()

CanandcolorFaults	GetActiveFaults ()

units::celsius_t	GetTemperature ()

void	ClearStickyFaults ()

void	SetPartyMode (uint8_t level)

CanandcolorSettings	GetSettings (units::second_t timeout=500_ms, units::second_t missingTimeout=50_ms, uint32_t attempts=3)

void	SetLampLED (bool lamp)

void	SetLampLEDBrightness (double brightness)

void	StartFetchSettings ()

CanandcolorSettings	GetSettingsAsync ()

CanandcolorSettings	SetSettings (CanandcolorSettings &settings, units::second_t timeout=50_ms, uint32_t attempts=3)

bool	SetDigoutSlot (CanandcolorDigout digout, uint8_t slotIndex, const digout::DigoutSlot &slotConfig, units::second_t timeout=50_ms)

std::optional< digout::DigoutSlot >	GetDigoutSlot (CanandcolorDigout digout, uint8_t slotIndex, units::second_t timeout=50_ms)

void	ClearAllDigoutSlots (CanandcolorDigout digout)

CanandcolorSettings	ResetFactoryDefaults (units::second_t timeout=500_ms)

redux::frames::Frame< double > &	GetProximityFrame ()

redux::frames::Frame< CanandcolorColorData > &	GetColorFrame ()

redux::frames::Frame< digout::DigoutSlotState > &	GetDigoutFrame ()

redux::frames::Frame< CanandcolorStatus > &	GetStatusFrame ()

void	HandleMessage (redux::canand::CanandMessage &msg) override

redux::canand::CanandAddress &	GetAddress () override

std::string	GetDeviceClassName () override

redux::canand::CanandFirmwareVersion	GetMinimumFirmwareVersion () override

Public Member Functions inherited from redux::canand::CanandDevice
virtual void	HandleMessage (CanandMessage &msg)=0

virtual CanandAddress &	GetAddress ()=0

bool	IsConnected (units::second_t timeout=2_s)

virtual std::string	GetDeviceClassName ()

std::string	GetDeviceName ()

virtual void	PreHandleMessage (CanandMessage &msg)

void	CheckReceivedFirmwareVersion ()

virtual CanandFirmwareVersion	GetMinimumFirmwareVersion ()

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)

Protected Attributes
redux::frames::Frame< double >	proximity {0.0, 0_ms}

redux::frames::Frame< CanandcolorColorData >	color {CanandcolorColorData{0.0, 0.0, 0.0, 0.0}, 0_ms}

redux::frames::Frame< digout::DigoutSlotState >	digout {digout::DigoutSlotState{0}, 0_ms}

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

redux::canand::CanandSettingsManager< CanandcolorSettings >	stg {*this}

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)
canandcolor.GetRed();
canandcolor.GetGreen();
canandcolor.GetBlue();
canandcolor.GetWhite();
 
 
// 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.SetColorConfig(CanandcolorColorPeriod::k40ms); // 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
redux::frames::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.

Parameters

canID the device id to use [0..63]

Member Function Documentation

◆ ClearAllDigoutSlots()

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

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

Parameters

digout the 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.

Returns: CanandcolorFaults of the active faults

◆ GetAddress()

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

overridevirtual

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.

Returns: 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.

Returns: blue intensity [0..1)

◆ GetColor()

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

Returns a CanandcolorColorData object which can also convert to HSV.

Returns: color object

◆ GetColorFrame()

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

inline

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

Returns: the color reading frame, which will hold timestamped color readings

See also: Frame

◆ GetDeviceClassName()

std::string redux::sensors::canandcolor::Canandcolor::GetDeviceClassName ( )

inlineoverridevirtual

Returns a canonical class-wide device name.

Returns: std::string of a device type name

Reimplemented from redux::canand::CanandDevice.

◆ GetDigoutFrame()

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

inline

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

Returns: the digital output state frame

◆ GetDigoutSlot()

std::optional< digout::DigoutSlot > redux::sensors::canandcolor::Canandcolor::GetDigoutSlot	(	CanandcolorDigout	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 https://docs.reduxrobotics.com/canandcolor/programming/digital-ports.html

Parameters

digout	digital output associated with the slot to fetch from
slotIndex	The index of the slot to fetch from (0-15)
timeout	The timeout to wait for the slot to be retrieved (default 50_ms, set to 0_s to not block)

Returns: std::optional with DigoutSlot object on success, nullopt on failure

◆ GetDigoutState()

digout::DigoutSlotState redux::sensors::canandcolor::Canandcolor::GetDigoutState ( )

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

Returns: 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.

Returns: green intensity [0..1)

◆ GetMinimumFirmwareVersion()

redux::canand::CanandFirmwareVersion redux::sensors::canandcolor::Canandcolor::GetMinimumFirmwareVersion ( )

inlineoverridevirtual

Returns the minimum firmware version this vendordep requires.

Returns: minimum firmware version

Reimplemented from redux::canand::CanandDevice.

◆ 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.

Returns: proximity value (range [0..1])

◆ GetProximityFrame()

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

inline

Returns the proximity reading frame.

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

See also: Frame

◆ GetRed()

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

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

Returns: red intensity [0..1)

◆ GetSettings()

CanandcolorSettings redux::sensors::canandcolor::Canandcolor::GetSettings	(	units::second_t	timeout = `500_ms`,
		units::second_t	missingTimeout = `50_ms`,
		uint32_t	attempts = `3`
	)

inline

Fetches the Canandcolor's current configuration in a blocking manner. This function will block for at up to 0.5 seconds waiting for the device to reply, so it is best to put this in an init function, rather than the main loop.

Parameters

timeout	maximum number of seconds to wait for settings before giving up
missingTimeout	maximum number of seconds to wait for each settings retry before giving up
attempts	number of attempts to try and fetch values missing from the first pass

Returns: Received set of CanandcolorSettings of device configuration.

◆ GetSettingsAsync()

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

inline

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};
canandcolor.StartFetchSettings();
 
// ...
// somewhere in a loop function
 
if (canandcolor.GetSettingsAsync().AllSettingsReceived()) {
  // do something with the settings object
  fmt::print("Canandcolor lamp enabled: {}\n", *canandcolor.GetSettingsAsync().GetLampLED());
}

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 an init function
Canandcolor canandcolor{0};
 
CanandcolorSettings stg{};
stg.SetProximityFramePeriod(0.1_s);
canandcolor.SetSettings(stg);
canandcolor.StartFetchSettings();
 
// right after the fetch...
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

Returns: CanandcolorSettings object of known settings

◆ GetStatusFrame()

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

inline

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

Returns: 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.

Returns: CanandcolorFaults of the sticky faults.

◆ GetTemperature()

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

Get onboard device temperature readings in degrees Celsius.

Returns: 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.

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

◆ HandleMessage()

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

overridevirtual

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().

Parameters

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

Implements redux::canand::CanandDevice.

◆ ResetFactoryDefaults()

CanandcolorSettings redux::sensors::canandcolor::Canandcolor::ResetFactoryDefaults ( units::second_t timeout = 500_ms )

inline

Resets the device to factory defaults, and then wait for all settings to be broadcasted back.

Parameters

timeout how long to wait for the new settings to be confirmed by the device in seconds (suggested at least 0.35 seconds)

Returns: CanandcoderSettings object of received settings. Use AllSettingsReceived to verify success.

◆ SetDigoutSlot()

bool redux::sensors::canandcolor::Canandcolor::SetDigoutSlot	(	CanandcolorDigout	digout,
		uint8_t	slotIndex,
		const digout::DigoutSlot &	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 https://docs.reduxrobotics.com/canandcolor/programming/digital-ports.html

Parameters

digout	The digital output associated with the slot to write
slotIndex	The index of the slot to write to (0-15)
slotConfig	The actual slot data (see DigoutSlot)
timeout	The timeout to wait for a confirmation message (default 50_ms, set to 0_s to not block)

Returns: 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.

This value does not persist on device reboot! Use CanandcolorSettings.SetLampLED and Canandcolor.SetSettings to set this persistently.

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.

Parameters

lamp	whether to enable or disable the lamp LED

◆ SetLampLEDBrightness()

void redux::sensors::canandcolor::Canandcolor::SetLampLEDBrightness ( double brightness )

Sets the brightness of the onboard lamp LED.

This value does not persist on device reboot! Use CanandcolorSettings.SetLampLEDBrightness and Canandcolor.SetSettings to set this persistently.

By factory default this setting is set to max brightness (1.0)

Parameters

brightness scaled brightness from 0.0 (off) to 1.0 (max brightness)

◆ 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.

Parameters

level the party level value to set.

◆ SetSettings()

CanandcolorSettings redux::sensors::canandcolor::Canandcolor::SetSettings	(	CanandcolorSettings &	settings,
		units::second_t	timeout = `50_ms`,
		uint32_t	attempts = `3`
	)

inline

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

Example:

CanandcolorSettings stg;
Canandcolor color{0};
// After configuring the settings object...
 
CanandcolorSettings failed = color.SetSettings(stg); 
if (failed.IsEmpty()) {
    // success
} else {
    // handle failed settings
}

Parameters

settings	the CanandcolorSettings to update the device with
timeout	maximum time in seconds to wait for each setting to be confirmed (default 50 ms). Set to 0 to not check (and not block).
attempts	the maxinum number of attempts to write each individual settings

Returns: CanandcolorSettings object of unsuccessfully set settings.

◆ StartFetchSettings()

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

inline

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<CanandcolorColorData> redux::sensors::canandcolor::Canandcolor::color {CanandcolorColorData{0.0, 0.0, 0.0, 0.0}, 0_ms}

protected

internal Frame variable holding current color state

◆ digout

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

protected

internal Frame variable holding current digital output state

◆ proximity

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

protected

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}

protected

internal Frame variable holding current status value state

◆ stg

redux::canand::CanandSettingsManager<CanandcolorSettings> redux::sensors::canandcolor::Canandcolor::stg {*this}

protected

internal settings manager

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

src/main/native/include/redux/sensors/Canandcolor.h

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Canandcolor()

Member Function Documentation

◆ ClearAllDigoutSlots()

◆ ClearStickyFaults()

◆ GetActiveFaults()

◆ GetAddress()

◆ GetBlue()

◆ GetColor()

◆ GetColorFrame()

◆ GetDeviceClassName()

◆ GetDigoutFrame()

◆ GetDigoutSlot()

◆ GetDigoutState()

◆ GetGreen()

◆ GetMinimumFirmwareVersion()

◆ GetProximity()

◆ GetProximityFrame()

◆ GetRed()

◆ GetSettings()

◆ GetSettingsAsync()

◆ GetStatusFrame()

◆ GetStickyFaults()

◆ GetTemperature()

◆ GetWhite()

◆ HandleMessage()

◆ ResetFactoryDefaults()

◆ SetDigoutSlot()

◆ SetLampLED()

◆ SetLampLEDBrightness()

◆ SetPartyMode()

◆ SetSettings()

◆ StartFetchSettings()

Member Data Documentation

◆ color

◆ digout

◆ proximity

◆ status

◆ stg