Class Canandcolor
- All Implemented Interfaces:
AutoCloseable
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 = new Canandcolor(0); // device id 0 // Reading the Canandcolor // returns a proximity value [0 inclusive..1 exclusive). Larger values are distances closer to // the sensor. canandcolor.getProximity(); // these are all also bounded [0..1) canandcolor.getRed(); canandcolor.getGreen(); canandcolor.getBlue(); canandcolor.getWhite(); // Changing configuration Canandcolor.Settings settings = new Canandcolor.Settings(); settings.setProximityFramePeriod(0.010); // set the proximity frame period to be sent every 10 ms settings.setColorFramePeriod(0.040); // set the position frame period to be sent every 40 ms settings.setColorConfig(Canandcolor.ColorPeriod.k40ms); // set the color sensor integration to // happen over 80 milliseconds canandcolor.setSettings(settings, 0.050); // 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. Canandcolor.Faults faults = canandcolor.getStickyFaults(); // fetches faults System.out.printf("Canandcolor rebooted: %d\n", faults.powerCycle()); // Timestamped data // gets current proximity + timestamp together FrameData<Double> proxFrame = canandcolor.getProximityFrame().getFrameData(); proxFrame.getValue(); // fetched proximity value proxFrame.getTimestamp(); // timestamp of the proximity reading
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final record
Record class to hold detected color values.static enum
Enum representing the internal configuration of the Canandcolor's color IC.static enum
Data sources that digout slots can use to perform comparisons or output data directly as a duty cycle.static enum
Enum representing the digital output pads on the Canandcolor.static class
A class to hold device faults for theCanandcolor
, as returned bygetStickyFaults()
andgetActiveFaults()
.static class
The settings class for theCanandcolor
.static final record
Container record class representing aCanandcolor
's status. -
Field Summary
Modifier and TypeFieldDescriptionprotected final ByteArrayFrame<Canandcolor.ColorData>
internal Frame variable holding current color stateprotected final ByteArrayFrame<DigoutSlotState>
internal Frame variable holding current digital output stateprotected final DoubleFrame<Double>
internal Frame variable holding current proximity stateprotected final ByteArrayFrame<Canandcolor.Status>
internal Frame variable holding current status value stateFields inherited from class com.reduxrobotics.canand.CanandDevice
lastMessageTs
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Clears all configured "slots" on the specified digital output.void
Clears sticky faults.Returns an object representing currently active faults.Returns theCanandAddress
representing the combination of CAN bus and CAN device ID that this CanandDevice refers to.double
getBlue()
Blue intensity, normalized [0 inclusive..1 exclusive) where 0 is none and 1 is as bright as possible.getColor()
Returns a Canandcolor.ColorData object which can also convert to the HSV colorspaceReturns the color reading frame, which includes CAN timestamp data.Returns the digital output state frame, which includes CAN timestamp data.getDigoutSlot
(Canandcolor.Digout digout, int slotIndex) Fetches a digout slot's configuration with a default 50 ms timeout.getDigoutSlot
(Canandcolor.Digout digout, int slotIndex, double timeout) Fetches a digout slot's configuration.Returns a DigoutSlotState object representing the current state of the digital outputs.double
getGreen()
Green intensity, normalized [0 inclusive..1 exclusive) where 0 is none and 1 is as bright as possible.Returns the minimum firmware version this vendordep requires for this device.double
Gets the currently sensed proximity normalized between [0..1] inclusive.Returns the proximity reading frame.double
getRed()
Red intensity, normalized [0 inclusive..1 exclusive) where 0 is none and 1 is as bright as possible.Fetches the Canandcolor's current configuration in a blocking manner.getSettings
(double timeout) Fetches the device's current configuration in a blocking manner.getSettings
(double timeout, double missingTimeout, int attempts) Fetches the device's current configuration in a blocking manner, with control over failure handling.Non-blockingly returns aCanandcolor.Settings
object of the most recent known settings values received from the device.Returns the current status frame, which includes CAN timestamp data.Returns sticky faults.double
Get onboard device temperature readings in degrees Celsius.double
getWhite()
White intensity, normalized [0 inclusive..1 exclusive) where 0 is none and 1 is as bright as possible.void
A callback called when a Redux CAN message is received and should be parsed.Resets the device to factory defaults, waiting up to 500 ms to confirm the settings changes.resetFactoryDefaults
(double timeout) Resets the Canandcolor to factory defaults.boolean
setDigoutSlot
(Canandcolor.Digout digout, int slotIndex, DigoutSlot slotConfig) Sets an indexed slot on a Canandcolor digital output with a default 50 ms timeout.boolean
setDigoutSlot
(Canandcolor.Digout digout, int slotIndex, DigoutSlot slotConfig, double timeout) Sets an indexed slot on a Canandcolor digital output.void
setLampLED
(boolean enable) Sets whether or not the onboard lamp LED is to be powered.void
setLampLEDBrightness
(double brightness) Sets the brightness of the onboard lamp LED.void
setPartyMode
(int level) Controls "party mode" -- an device identification tool that blinks the onboard LED various colors at a user-specified strobe period.boolean
setSettings
(Canandcolor.Settings settings) Applies the settings from aCanandcolor.Settings
object to the device.boolean
setSettings
(Canandcolor.Settings settings, double timeout) Applies the settings from aCanandcolor.Settings
object to the device.setSettings
(Canandcolor.Settings settings, double timeout, int attempts) Applies the settings from aCanandcolor.Settings
object to the device, with fine grained control over failure-handling.void
Tells the Canandcolor to begin transmitting its settings; once they are all transmitted (after ~200-300ms), the values can be retrieved fromgetSettingsAsync()
Methods inherited from class com.reduxrobotics.canand.CanandDevice
checkReceivedFirmwareVersion, close, getFirmwareVersion, isConnected, isConnected, preHandleMessage, sendCANMessage, toString
-
Field Details
-
proximity
internal Frame variable holding current proximity state -
color
internal Frame variable holding current color state -
digout
internal Frame variable holding current digital output state -
status
internal Frame variable holding current status value state
-
-
Constructor Details
-
Canandcolor
public 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]
-
-
Method Details
-
getProximity
public double getProximity()Gets the currently sensed proximity normalized between [0..1] inclusive. Proximity decreases as objects get further away from the sensor face and increases as they approach the sensor.Proximities that are too close for more detailed readings 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])
-
getRed
public double getRed()Red intensity, normalized [0 inclusive..1 exclusive) where 0 is none and 1 is as bright as possible.- Returns:
- red intensity [0..1)
-
getGreen
public double getGreen()Green intensity, normalized [0 inclusive..1 exclusive) where 0 is none and 1 is as bright as possible.- Returns:
- green intensity [0..1)
-
getBlue
public double getBlue()Blue intensity, normalized [0 inclusive..1 exclusive) where 0 is none and 1 is as bright as possible.- Returns:
- blue intensity [0..1)
-
getWhite
public double getWhite()White intensity, normalized [0 inclusive..1 exclusive) where 0 is none and 1 is as bright as possible. This can be used as a proxy for proximity at ranges too close for the normmal proximity sensor to give useful values.- Returns:
- white intensity [0..1)
-
getColor
Returns a Canandcolor.ColorData object which can also convert to the HSV colorspace- Returns:
- color object
- See Also:
-
getDigoutState
Returns a DigoutSlotState object representing the current state of the digital outputs.- Returns:
- color object
-
getStickyFaults
Returns sticky faults. Sticky faults are the active faults, except once set they do not become unset untilclearStickyFaults()
is called.- Returns:
Canandcolor.Faults
of the sticky faults.- See Also:
-
getActiveFaults
Returns an object representing currently active faults. Active faults are only active for as long as the error state exists.- Returns:
Canandcolor.Faults
of the active faults- See Also:
-
getTemperature
public double getTemperature()Get onboard device temperature readings in degrees Celsius.- Returns:
- temperature in degrees Celsius
-
clearStickyFaults
public void 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
Canandcolor.Faults.faultsValid()
for faults returned bygetStickyFaults()
-
setPartyMode
public void setPartyMode(int 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.
-
getSettings
Fetches the device's current configuration in a blocking manner, with control over failure handling.This method works by requesting the device first send back all settings, and then waiting for up to a specified timeout for all settings to be received by the robot controller. If the timeout is zero, this step is skipped.
If there are settings that were not received by the timeout, then this function will attempt to individually fetched each setting for up to a specified number of attempts. If the fresh argument is true and the timeout argument is 0, then only this latter step runs, which can be used to only fetch settings that are missing from the known settings cache returned by
getSettingsAsync()
.The resulting set of known (received) settings is then returned, complete or not.
This function blocks, so it is best to put this in init routines rather than a main loop.
Canandcolor color = new Canandcolor(0); // Typical usage // fetch all settings with a timeout of 350 ms, and retry missing values 3 times Canandcolor.Settings stg = color.getSettings(0.350, 0.05, 3); // Advanced usage color.startFetchSettings(); // send a "fetch settings command" // wait some amount of time stg = color.getSettingsAsync(); stg.allSettingsReceived(); // may or may not be true stg = color.getSettings(0, 0.05, 3); // only fetch the missing settings stg.allSettingsReceived(); // far more likely to be true
Note that unlike v2023, this function may return incomplete settings! Use
CanandSettings.allSettingsReceived()
to verify all settings were received.- 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:
Canandcolor.Settings
representing the device's configuration
-
getSettings
Fetches the device's current configuration in a blocking manner. This function will block for up to the specified number of 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.If settings time out, it will retry each missing setting once with a 50ms timeout, and if they still fail, a partial Settings will still be returned.
Note that unlike v2023, this function may return incomplete settings! Use
CanandSettings.allSettingsReceived()
to verify all settings were received.- Parameters:
timeout
- maximum number of seconds to wait for settings before giving up- Returns:
Canandcolor.Settings
representing the device's configuration
-
getSettings
Fetches the Canandcolor's current configuration in a blocking manner. This function will block for up to 0.350 seconds waiting for the device to reply, so it is best to put this in an init function rather than the main loop.Note that unlike v2023, this function may return incomplete settings! Use
CanandSettings.allSettingsReceived()
to verify all settings were received.- Returns:
Canandcolor.Settings
representing the device's configuration
-
setLampLED
public void setLampLED(boolean enable) Sets whether or not the onboard lamp LED is to be powered.This value does not persist on device reboot! Use
Canandcolor.Settings.setLampLED(boolean)
andsetSettings(com.reduxrobotics.sensors.canandcolor.Canandcolor.Settings, double, int)
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:
enable
- true to enable or false to disable the lamp LED- See Also:
-
setLampLEDBrightness
public void setLampLEDBrightness(double brightness) Sets the brightness of the onboard lamp LED.This value does not persist on device reboot! Use
Canandcolor.Settings.setLampLEDBrightness(double)
andsetSettings(com.reduxrobotics.sensors.canandcolor.Canandcolor.Settings, double, int)
to set this persistently.The LED can also be physically turned off regardless of setting with the onboard switch.
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)
-
startFetchSettings
public void startFetchSettings()Tells the Canandcolor to begin transmitting its settings; once they are all transmitted (after ~200-300ms), the values can be retrieved fromgetSettingsAsync()
-
getSettingsAsync
Non-blockingly returns aCanandcolor.Settings
object of the most recent known settings values received from the device.Most users will probably want to use
One can call this after agetSettings(double, double, int)
instead.startFetchSettings()
call, and useCanandSettings.allSettingsReceived()
to check if/when all values have been seen. As an example:// somewhere in an init function Canandcolor canandcolor = new Canandcolor(0); canandcolor.startFetchSettings(); // ... // somewhere in a loop function if (canandcolor.getSettingsAsync().allSettingsReceived()) { // do something with the settings object System.out.printf("Canandcolor lamp enable: %d\n", canandcolor.getSettingsAsync().getLampLED()); }
If this is called aftersetSettings(Canandcolor.Settings)
, 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 initialization (just as a definition): Canandcolor canandcolor = new Canandcolor(0); // somewhere in a loop canandcolor.setSettings(new Canandcolor.Settings().setProximityFramePeriod(0.100)); // will likely return -1, as the device hasn't confirmed the previous transaction canandcolor.getSettingsAsync().getProximityFramePeriod(); // after up to ~300 ms... canandcolor.getSettingsAsync().getProximityFramePeriod(); // will likely return 100 ms
- Returns:
- Canandcolor.Settings object of known settings
- See Also:
-
setSettings
public Canandcolor.Settings setSettings(Canandcolor.Settings settings, double timeout, int attempts) Applies the settings from aCanandcolor.Settings
object to the device, with fine grained control over failure-handling. This overload allows specifiyng the number of retries per setting as well as the confirmation timeout. Additionally, it returns aCanandcolor.Settings
object of settings that were not able to be successfully applied.- Parameters:
settings
- theCanandcolor.Settings
to update the encoder withtimeout
- maximum time in seconds to wait for each setting to be confirmed. Set to 0 to not check (and not block).attempts
- the maximum number of attempts to write each individual setting- Returns:
- a Canandcolor.Settings object of unsuccessfully set settings.
- See Also:
-
setSettings
Applies the settings from aCanandcolor.Settings
object to the device. For more information, see theCanandcolor.Settings
class documentation.- Parameters:
settings
- theCanandcolor.Settings
to update the device withtimeout
- maximum time in seconds to wait for each setting to be confirmed. Set to 0 to not check (and not block).- Returns:
- true if successful, false if a setting operation timed out
- See Also:
-
setSettings
Applies the settings from aCanandcolor.Settings
object to the device. For more information, see theCanandcolor.Settings
class documentation.- Parameters:
settings
- theCanandcolor.Settings
to update the device with- Returns:
- true if successful, false if a setting operation timed out
- See Also:
-
setDigoutSlot
public boolean setDigoutSlot(Canandcolor.Digout digout, int slotIndex, DigoutSlot slotConfig, double timeout) 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
These values persist on reboot!
- Parameters:
digout
- The digital output associated with the slot to writeslotIndex
- The index of the slot to write to (0-15)slotConfig
- The actual slot data (seeDigoutSlot
)timeout
- The timeout to wait for a confirmation message (set to 0 to not block)- Returns:
- whether or not the slot update was successful
-
setDigoutSlot
Sets an indexed slot on a Canandcolor digital output with a default 50 ms timeout.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
These values persist on reboot!
- Parameters:
digout
- The digital output associated with the slot to writeslotIndex
- The index of the slot to write to (0-15)slotConfig
- The actual slot data (seeDigoutSlot
)- Returns:
- whether or not the slot update was successful
-
getDigoutSlot
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 fromslotIndex
- The index of the slot to fetch from (0-15)timeout
- The timeout to wait for the slot to be retrieved (recommend 0.05)- Returns:
- DigoutSlot object on success, null on failure
-
getDigoutSlot
Fetches a digout slot's configuration with a default 50 ms timeout. 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 fromslotIndex
- The index of the slot to fetch from (0-15)- Returns:
- DigoutSlot object on success, null on failure
-
clearAllDigoutSlots
Clears all configured "slots" on the specified digital output.- Parameters:
digout
- the digital output to clear slots on
-
resetFactoryDefaults
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:
Canandcolor.Settings
object of received settings. UseCanandSettings.allSettingsReceived()
to verify success.
-
resetFactoryDefaults
Resets the device to factory defaults, waiting up to 500 ms to confirm the settings changes.- Returns:
Canandcolor.Settings
object of received settings. UseCanandSettings.allSettingsReceived()
to verify success.
-
getProximityFrame
Returns the proximity reading frame.- Returns:
- the proximity reading frame, which will hold the current proximity reading.
- See Also:
-
getColorFrame
Returns the color reading frame, which includes CAN timestamp data.- Returns:
- the color reading frame, which will hold timestamped color readings
- See Also:
-
getDigoutFrame
Returns the digital output state frame, which includes CAN timestamp data.- Returns:
- the digital output state frame
-
getStatusFrame
Returns the current status frame, which includes CAN timestamp data.FrameData
objects are immutable.- Returns:
- the current status frame, as a
Canandcolor.Status
record.
-
handleMessage
Description copied from class:CanandDevice
A callback called when a Redux CAN message is received and should be parsed. Subclasses ofCanandDevice
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 byCanandDevice.getAddress()
.- Specified by:
handleMessage
in classCanandDevice
- Parameters:
msg
- aCanandMessage
representing the received message.
-
getAddress
Description copied from class:CanandDevice
Returns theCanandAddress
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.- Specified by:
getAddress
in classCanandDevice
- Returns:
- the
CanandAddress
for the device.
-
getMinimumFirmwareVersion
Description copied from class:CanandDevice
Returns the minimum firmware version this vendordep requires for this device. User-implmenting classes can return null to disable firmware checks.- Overrides:
getMinimumFirmwareVersion
in classCanandDevice
- Returns:
- minimum firmware version
-