Package com.reduxrobotics.sensors.canandcolor

Class Canandcolor

java.lang.Object
com.reduxrobotics.canand.CanandDevice
com.reduxrobotics.sensors.canandcolor.Canandcolor
All Implemented Interfaces:
AutoCloseable
public class Canandcolor extends CanandDevice
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 20ms 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..1] inclusive. Values increase as objects move away from 
 // the sensor in an approximately linear relationship.
 canandcolor.getProximity(); 
 
 // these are all also bounded [0..1] inclusive.
 canandcolor.getRed();
 canandcolor.getGreen();
 canandcolor.getBlue();
 canandcolor.getHSVHue();
 canandcolor.getHSVSaturation();
 canandcolor.getHSVValue();
 
 // you can also get a compound ColorData object with getColor
 // this will also have red/green/blue and hue/sat/value getters,
 // and is most relevant if used with frames
 ColorData colorData = canandcolor.getColor();
 
 // read digout channels over CAN
 // see the DigoutChannel class docs for more detailed information on how these work
 // and how to configure them.
 canandcolor.digout1().getValue(); // regular value
 canandcolor.digout1().getStickyValue(); // sticky value
 canandcolor.getDigoutState(); // full digout state as a DigoutState object
 
 // Changing configuration
 CanandcolorSettings settings = new CanandcolorSettings();
 // set the proximity frame period to be sent every 10 ms
 settings.setProximityFramePeriod(0.010);
 // set the color frame period to be sent every 10 ms (instead of the default)
 settings.setColorFramePeriod(0.010);
 // set the color sensor integration to happen over 100 milliseconds
 settings.setColorIntegrationPeriod(ColorPeriod.k100ms); 
 canandcolor.setSettings(settings, 0.020); // apply the new settings to the device, with maximum 
                                           // 20 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
 System.out.printf("Canandcolor rebooted: %b\n", faults.powerCycle());
 
 // Timestamped data
 // gets current proximity + timestamp together
 FrameData<Double> distFrame = canandcolor.getProximityFrame().getFrameData(); 
 distFrame.getValue(); // fetched proximity value
 distFrame.getTimestamp(); // timestamp of the proximity reading

  • Field Details

    • proximity

      protected final DoubleFrame<Double> proximity
      internal Frame variable holding current proximity state

    • color

      protected final ColorFrame color
      internal Frame variable holding current color state

    • digout

      protected final LongFrame<DigoutSlotState> digout
      internal Frame variable holding current digital output state

    • status

      protected final LongFrame<CanandcolorStatus> 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.

      The value decreases as an object gets closer to the sensor.

      Note that proximity is not given a unit as different materials and sensor configurations can greatly vary how the proximity value translates to actual real-world units. 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] inclusive)

    • getRed

      public double getRed()
      Red intensity, normalized [0..1] inclusive where 0 is none and 1 is as bright as possible.
      Returns:
      red intensity [0..1]

    • getGreen

      public double getGreen()
      Blue intensity, normalized [0..1] inclusive where 0 is none and 1 is as bright as possible.
      Returns:
      green intensity [0..1]

    • getBlue

      public double getBlue()
      Blue intensity, normalized [0..1] inclusive where 0 is none and 1 is as bright as possible.
      Returns:
      blue intensity [0..1]

    • getHSVHue

      public double getHSVHue()
      HSV colorspace hue, normalized [0 inclusive ..1.0 exclusive)

      This can be used to more accurately determine the color of a sensed object.

      Returns:
      hue [0..1)

    • getHSVSaturation

      public double getHSVSaturation()
      HSV colorspace saturation, normalized [0..1] inclusive.
      Returns:
      saturation [0..1]

    • getHSVValue

      public double getHSVValue()
      HSV colorspace value, normalized [0..1] inclusive.

      This is the maximum value out of the red/green/blue values.

      Returns:
      value [0..1]

    • getColor

      public ColorData getColor()
      Returns a ColorData object which can also convert to the HSV colorspace.
      Returns:
      color object
      See Also:

    • getDigoutState

      public DigoutSlotState getDigoutState()
      Returns a DigoutSlotState object representing the current state of the digital outputs as reported over CAN.
      Returns:
      digital output state object

    • getStickyFaults

      public CanandcolorFaults 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.
      See Also:

    • getActiveFaults

      public CanandcolorFaults 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
      See Also:

    • 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 CanandcolorFaults.faultsValid() for faults returned by getStickyFaults()

    • getTemperature

      public double getTemperature()
      Get onboard device temperature readings in degrees Celsius. This temperature is not particularly accurate or precise, but is meant as a rough approximation.
      Returns:
      temperature in degrees Celsius

    • setPartyMode

      public void setPartyMode(int level)
      Controls "party mode" -- an device identification tool that blinks the onboard LED various colors if level != 0. This function does not block.
      Parameters:
      level - the party level value to set.

    • getSettings

      public CanandcolorSettings getSettings(double timeout, double missingTimeout, int attempts)
      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 320 ms, and retry missing values 3 times
 CanandcolorSettings stg = color.getSettings(0.350, 0.02, 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.02, 3); // only fetch the missing settings
 stg.allSettingsReceived(); // far more likely to be true

      Note that 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:
      CanandcolorSettings representing the device's configuration

    • getSettings

      public CanandcolorSettings getSettings(double timeout)
      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 20ms timeout, and if they still fail, a partial Settings will still be returned.

      Note that 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:
      CanandcolorSettings representing the device's configuration

    • getSettings

      public CanandcolorSettings 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 this function may return incomplete settings! Use CanandSettings.allSettingsReceived() to verify all settings were received.

      Returns:
      CanandcolorSettings representing the device's configuration

    • setLampLEDBrightness

      public void setLampLEDBrightness(double brightness)
      Sets the brightness of the onboard lamp LED.

      This value does not persist on device reboot! Use CanandcolorSettings.setLampLEDBrightness(double) and setSettings(CanandcolorSettings) 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 from getSettingsAsync()

    • getSettingsAsync

      public CanandcolorSettings 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 getSettings() instead.

      One can call this after a startFetchSettings() call, and use CanandSettings.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 brightness: %f\n",
     canandcolor.getSettingsAsync().getLampLEDBrightness().get());
 }
      If this is called after 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 initialization (just as a definition):
 Canandcolor canandcolor = new Canandcolor(0); 
 
 // somewhere in a loop 
 canandcolor.setSettings(new CanandcolorSettings().setProximityFramePeriod(0.100));
 
 // will likely return Optional.empty(), as the device hasn't confirmed the previous transaction
 canandcolor.getSettingsAsync().getProximityFramePeriod();
 
 // after up to ~300 ms...
 canandcolor.getSettingsAsync().getProximityFramePeriod(); // will likely return 0.1 seconds
      Returns:
      CanandcolorSettings object of known settings
      See Also:

    • setSettings

      public CanandcolorSettings setSettings(CanandcolorSettings settings, double timeout, int attempts)
      Applies the settings from a CanandcolorSettings 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 a CanandcolorSettings object of settings that were not able to be successfully applied.
      Parameters:
      settings - the CanandcolorSettings to update the encoder with
      timeout - 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 CanandcolorSettings object of unsuccessfully set settings.
      See Also:

    • setSettings

      public boolean setSettings(CanandcolorSettings settings, double timeout)
      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. Set to 0 to not check (and not block).
      Returns:
      true if successful, false if a setting operation timed out
      See Also:

    • setSettings

      public boolean setSettings(CanandcolorSettings settings)
      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
      Returns:
      true if successful, false if a setting operation timed out
      See Also:

    • clearStickyDigoutFlags

      public void clearStickyDigoutFlags()
      Clears all sticky digout flags, as readable by DigoutSlotState.getStickyDigoutValue(DigoutChannel.Index) from getDigoutState()

    • resetFactoryDefaults

      public CanandcolorSettings resetFactoryDefaults(double timeout)
      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:
      CanandcolorSettings object of received settings. Use CanandSettings.allSettingsReceived() to verify success.

    • resetFactoryDefaults

      public CanandcolorSettings resetFactoryDefaults()
      Resets the device to factory defaults, waiting up to 350 ms to confirm the settings changes.
      Returns:
      CanandcolorSettings object of received settings. Use CanandSettings.allSettingsReceived() to verify success.

    • digout1

      public DigoutChannel digout1()
      Returns the first digout channel.
      Returns:
      digout channel 1

    • digout2

      public DigoutChannel digout2()
      Returns the second digout channel.
      Returns:
      digout channel 2

    • getProximityFrame

      public DoubleFrame<Double> getProximityFrame()
      Returns the proximity reading frame.
      Returns:
      the proximity reading frame, which will hold the current proximity reading.
      See Also:

    • getColorFrame

      public ColorFrame 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

      public LongFrame<DigoutSlotState> getDigoutFrame()
      Returns the digital output state frame, which includes CAN timestamp data.
      Returns:
      the digital output state frame

    • getStatusFrame

      public LongFrame<CanandcolorStatus> getStatusFrame()
      Returns the current status frame, which includes CAN timestamp data. FrameData objects are immutable.
      Returns:
      the current status frame, as a CanandcolorStatus record.

    • getInternalSettingsManager

      public CanandSettingsManager<CanandcolorSettings> getInternalSettingsManager()
      Returns the CanandSettingsManager associated with this device. The CanandSettingsManager is an internal helper object. Teams are typically not expected to use it except for advanced cases (e.g. custom settings wrappers)
      Returns:
      internal settings manager handle

    • handleMessage

      public void handleMessage(CanandMessage msg)
      Description copied from class: CanandDevice
      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().

      Specified by:
      handleMessage in class CanandDevice
      Parameters:
      msg - a CanandMessage representing the received message.

    • getAddress

      public CanandAddress getAddress()
      Description copied from class: CanandDevice
      Returns 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.

      Specified by:
      getAddress in class CanandDevice
      Returns:
      the CanandAddress for the device.

    • getMinimumFirmwareVersion

      public CanandFirmwareVersion 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 class CanandDevice
      Returns:
      minimum firmware version