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 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
 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 = new CanandcolorSettings();
 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.setColorIntegrationPeriod(CanandcolorColorIntegration.kPeriod40Ms); // 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.
 CanandcolorFaults faults = canandcolor.getStickyFaults(); // fetches faults
 System.out.printf("Canandcolor rebooted: %d\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

  • Field Details

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

    • getRed

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

    • getGreen

      public double getGreen()
      Green intensity, normalized [0..1) 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) where 0 is none and 1 is as bright as possible.
      Returns:
      blue intensity [0..1)

    • getWhite

      public double 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)

    • getColor

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

    • getDigoutState

      public CanandcolorDigoutState getDigoutState()
      Returns a CanandcolorDigoutState object representing the current state of the digital outputs.
      Returns:
      color 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:

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

    • 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

      public CanandcolorSettings getSettings(double timeout)
      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:
      CanandcolorSettings representing the device's configuration, or null on timeout.

    • setLampLED

      public void setLampLED(boolean lamp)
      Sets whether or not the onboard lamp LED is to be powered.

      The LED can als 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
      See Also:

    • 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 a teleop or autonomous init function, rather than the main loop.
      Returns:
      CanandcolorSettings representing the device's configuration, or null on timeout.

    • 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(double) instead.

      One can call this after a 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 = 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().getLampEnable());
 }
      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 a loop 
 canandcolor.setSettings(new CanandcolorSettings().setProximityFramePeriod(0.100));
 canandcolor.getSettingsAsync().getProximityFramePeriod(); // will likely return -1, 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
      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:

    • setDigoutSlot

      public boolean setDigoutSlot(CanandcolorDigitalOutput digout, int slotIndex, CanandcolorDigoutSlot 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/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 (set to 0 to not block)
      Returns:
      whether or not the slot update was successful

    • setDigoutSlot

      public boolean setDigoutSlot(CanandcolorDigitalOutput digout, int slotIndex, CanandcolorDigoutSlot slotConfig)
      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/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)
      Returns:
      whether or not the slot update was successful

    • getDigoutSlot

      public CanandcolorDigoutSlot getDigoutSlot(CanandcolorDigitalOutput digout, int slotIndex, double timeout)
      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 (recommend 0.05)
      Returns:
      CanandcolorDigoutSlot object on success, null on failure

    • getDigoutSlot

      public CanandcolorDigoutSlot getDigoutSlot(CanandcolorDigitalOutput digout, int slotIndex)
      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/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)
      Returns:
      CanandcolorDigoutSlot object on success, null on failure

    • clearAllDigoutSlots

      public void clearAllDigoutSlots(CanandcolorDigitalOutput digout)
      Clears all configured "slots" on the specified digital output.
      Parameters:
      digout - the digital output to clear slots on

    • 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 if successful, null on confirmation timeout or if timeout is 0

    • resetFactoryDefaults

      public CanandcolorSettings resetFactoryDefaults()
      Resets the device to factory defaults, waiting up to 500 ms to confirm the settings changes.
      Returns:
      CanandcolorSettings object if successful, null on confirmation timeout or if timeout is 0

    • isPresent

      public boolean isPresent(double timeout)
      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
      Returns:
      true if there has been a message within the last timeout seconds, false if not

    • isPresent

      public boolean isPresent()
      Checks whether or not the device has sent a message within the last 2000 milliseconds.
      Returns:
      true if there has been a message within the last 2000 milliseconds, false if not

    • getProximityFrame

      public Frame<Double> getProximityFrame()
      Returns the proximity reading frame.
      Returns:
      the proximity reading frame, which will hold the current proximity in the same units as getProximity()
      See Also:

    • getColorFrame

      public Frame<CanandcolorColor> 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 Frame<CanandcolorDigoutState> getDigoutFrame()
      Returns the digital output state frame, which includes CAN timestamp data.
      Returns:
      the digital output state frame

    • getStatusFrame

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

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