#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< CanandcolorSettings >	GetSettings (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< CanandcolorDigoutSlot >	GetDigoutSlot (CanandcolorDigitalOutput digout, uint8_t slotIndex, units::second_t timeout=50_ms)

void	ClearAllDigoutSlots (CanandcolorDigitalOutput digout)

std::optional< CanandcolorSettings >	ResetFactoryDefaults (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::CanandAddress &	GetAddress () override

virtual void	HandleMessage (CanandMessage &msg)=0

virtual CanandAddress &	GetAddress ()=0

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

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

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

redux::frames::Frame< CanandcolorStatus >	status {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)
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.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.

Parameters

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

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

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

Returns a CanandcolorColor object which can also convert to HSV.

Returns: color object

◆ GetColorFrame()

redux::frames::Frame< CanandcolorColor > & 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

◆ GetDigoutFrame()

redux::frames::Frame< CanandcolorDigoutState > & 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< 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 https://docs.reduxrobotics.com/canspec/Canandcolor.html#digout1-config

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

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)

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

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.

Parameters

timeout maximum number of seconds to wait for settings before giving up

Returns: 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};
canandcolor.StartFetchSettings();

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

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.

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

Parameters

timeout window to check for message updates in seconds (default 2000 ms)

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

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: 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 https://docs.reduxrobotics.com/canspec/Canandcolor.html#digout1-config

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

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

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

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.

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

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

protected

internal Frame variable holding current color state

◆ digout

redux::frames::Frame<CanandcolorDigoutState> redux::sensors::canandcolor::Canandcolor::digout {CanandcolorDigoutState{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

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

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

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Canandcolor()

Member Function Documentation

◆ ClearAllDigoutSlots()

◆ ClearStickyFaults()

◆ GetActiveFaults()

◆ GetAddress()

◆ GetBlue()

◆ GetColor()

◆ GetColorFrame()

◆ GetDigoutFrame()

◆ GetDigoutSlot()

◆ GetDigoutState()

◆ GetGreen()

◆ GetProximity()

◆ GetProximityFrame()

◆ GetRed()

◆ GetSettings()

◆ GetSettingsAsync()

◆ GetStatusFrame()

◆ GetStickyFaults()

◆ GetTemperature()

◆ GetWhite()

◆ HandleMessage()

◆ IsPresent()

◆ ResetFactoryDefaults()

◆ SetDigoutSlot()

◆ SetLampLED()

◆ SetPartyMode()

◆ SetSettings()

◆ StartFetchSettings()

Member Data Documentation

◆ color

◆ digout

◆ proximity

◆ status