Package com.reduxrobotics.sensors.canandcolor

Class DigoutChannel

java.lang.Object
com.reduxrobotics.sensors.canandcolor.DigoutChannel
public class DigoutChannel extends Object
Represents a digital output channel.

The Canandcolor has two digital output channels: digout1 and digout2. These channels have a boolean value that is computed by evaluating "digout slots" which can be configured via configureSlots(DigoutConfig) or via the Alchemist device tuner. These "digout slots" can be configured to evaluate boolean conditions on sensor values to determine the overall channel's boolean value.

The value of these digout channels can be configued to be broadcasted over CAN or the associated physical 3.3v GPIO pins DIG-1 and DIG-2. The behavior of these GPIO pins can be configured using configureOutputPin(DigoutPinConfig), while the behavior of the digout frame can be configured using CanandcolorSettings.setDigoutFramePeriod(double) to set the baseline frame period and configureFrameTrigger(DigoutFrameTrigger) for behavior on state change.

Basic usage example

 Canandcolor color = new Canandcolor(0);
 // Gets the digout1 channel
 DigoutChannel digout1 = color.digout1();
 
 // Check value over CAN
 digout1.getValue();
 // Check "sticky" value over CAN
 digout1.getStickyValue();
 
 // Check if the an object is close and the color sensor is seeing "blue" for at least 10 milliseconds,
 // (Actual thresholds may need some experimental tuning, but will be in the same units as Canandcolor.getHue())
 digout1.configureSlots(new HSVDigoutConfig()
   .setMaxProximity(0.15)
   .setProximityInRangeFor(0.01)
   .setMinHue(0.5)
   .setMaxHue(0.7)
   .setColorInRangeFor(0.01)
 );
 
 // Set the baseline CAN digout frame period to 50 ms.
 // Note that this is global to both digout1 and digout2.
 color.setSettings(new CanandcolorSettings().setDigoutFramePeriod(0.050));
 
 // Instantly send CAN digout frames when the above condition changes at all.
 digout1.configureFrameTrigger(DigoutFrameTrigger.kRisingAndFalling);
 // Configure the DIG-1 GPIO pin to also output the condition
 digout1.configureOutputPin(DigoutPinConfig.kDigoutLogicActiveHigh);
 // Configure the DIG-2 GPIO pin to output proximity as a duty cycle
 color.digout2().configureOutputPin(DataSource.kProximity);

  • Method Details

    • channelIndex

      public DigoutChannel.Index channelIndex()
      Returns the index of this digout channel.
      Returns:
      channel index (either DigoutChannel.Index.kDigout1 or DigoutChannel.Index.kDigout2)

    • getValue

      public boolean getValue()
      Gets the current value of the digout channel, as reported over CAN.

      By default, the digout frame period is a relatively slow 100ms, so if the most up-to-date information is desired over CAN, changing this frame period via CanandcolorSettings.setDigoutFramePeriod(double) or configuring transmission on state change via configureFrameTrigger(DigoutFrameTrigger) may be desired.

      Returns:
      digout channel value.

    • getStickyValue

      public boolean getStickyValue()
      Gets the current "sticky" value of the digout channel as reported over CAN.

      This is similar to getValue() except the "sticky" value will toggle to true and will indefinitely stay true until Canandcolor.clearStickyDigoutFlags() is called.

      This can be useful for catching when the digout channel goes to true, even if only for a few milliseconds.

      Returns:
      sticky digout channel value.

    • configureSlots

      public boolean configureSlots(DigoutConfig config)
      Configures a digital output channel using the thresholds specified in a DigoutConfig.

      Available DigoutConfigs include:

      Basic usage example: 
       Canandcolor color = new Canandcolor(0);
 // Check if the an object is close and the color sensor is seeing blue for at least 10 milliseconds,
 color.digout1().configureSlots(new HSVDigoutConfig()
   .setMaxProximity(0.15)
   .setProximityInRangeFor(0.01)
   .setMinHue(0.5)
   .setMaxHue(0.7)
   .setColorInRangeFor(0.01)
 );
 // Instantly send CAN digout frames when the above condition changes at all.
 color.digout1().configureFrameTrigger(DigoutFrameTrigger.kRisingAndFalling);
 // Configure the DIG-1 GPIO pin to also output the condition
 color.digout1().configureOutputPin(DigoutPinConfig.kDigoutLogicActiveHigh);
 // Check value over CAN
 color.digout1().getValue();

      The Redux Alchemist tuner is capable of interactively generating code for use with this method. See https://docs.reduxrobotics.com/canandcolor for more information.

      Parameters:
      config - The configuration to apply
      Returns:
      true on success, false on failure. This function is idempotent so calling it again until success will result in correct configuration.

    • configureSlots

      public boolean configureSlots(DigoutConfig config, int triesPerSlot, double timeoutPerTry)
      Configures a digital output channel using the thresholds specified in a DigoutConfig.
      Parameters:
      config - The configuration to apply
      triesPerSlot - number of attempts to try to set each slot with (default 3)
      timeoutPerTry - time in seconds to wait for timeout per try (default 0.20)
      Returns:
      true on success, false on failure. This function is idempotent so calling it again until success will result in correct configuration.
      See Also:

    • configureOutputPin

      public boolean configureOutputPin(DigoutPinConfig config)
      Configures the physical GPIO pin associated with the digout channel.

      Note that these pin outputs are independent of the actual digital output channel's value, which is always continuously calcuated from digout slots.

      These pins can be set into one of two or three modes:

      Some usage examples: 
       Canandcolor color = new Canandcolor(0);
 DigoutChannel digout2 = color.digout2();
 
 // Disable the output pin
 digout2.configureOutputPin(DigoutPinConfig.kDisabled);
 
 // Use the digout slot value as the GPIO value, configure with a 20 ms timeout and up to 3 retries
 digout2.configureOutputPin(DigoutPinConfig.kDigoutLogicActiveHigh, 0.02, 3);
 
 // configure the pin to output proximity as a duty cycle value [0..1]
 digout2.configureOutputPin(DataSource.kProximity);
 
 // this will throw an IllegalArgumentException, as duty cycle is not supported on digout1.
 color.digout1().configureOutputPin(DataSource.kProximity);
      Parameters:
      config - the DigoutPinConfig or DataSource to configure as output
      Returns:
      true on known set success. This method attempts 3 tries at a 20 ms timeout.
      See Also:

    • configureOutputPin

      public boolean configureOutputPin(DigoutPinConfig config, double timeout, int attempts)
      Configures the associated physical GPIO pin associated with the digout channel.

      See configureOutputPin(DigoutPinConfig) for usage information.

      Parameters:
      config - the DigoutPinConfig or DataSource to configure as output
      timeout - maximum timeout for this operation (in seconds). Set to zero to not check.
      attempts - the number of retry attempts to make the configuration succeed.
      Returns:
      true on known set success.
      See Also:

    • configureFrameTrigger

      public boolean configureFrameTrigger(DigoutFrameTrigger trigger)
      Configures the frame trigger settings for this digout channel.

      These determine if extra digout frames should get sent if the current digout channel changes state. These can be used with the Frame interface to run callbacks on state change, or simply ensure that getValue() always has an up-to-date value.

      This will increase CAN usage -- potentially dramatically so if the digout slot conditions have been misconfigured to toggle rapidly. Using time-based conditions such as HSVDigoutConfig.setProximityInRangeFor(double) or DigoutSlotBuilder.trueFor(double) can "debounce" digout conditions preventing this from happening.

      Parameters:
      trigger - the DigoutFrameTrigger to set
      Returns:
      true on set success
      See Also:

    • configureFrameTrigger

      public boolean configureFrameTrigger(DigoutFrameTrigger trigger, double timeout, int attempts)
      Configures the frame trigger settings for this digout channel.

      See configureFrameTrigger(DigoutFrameTrigger) for usage information.

      Parameters:
      trigger - the DigoutFrameTrigger to set
      timeout - maximum timeout for this operation (in seconds)
      attempts - the number of retry attempts to make the configuration succeed.
      Returns:
      true on known set success. This method attempts 3 tries at a 20 ms timeout.
      See Also:

    • clearAllDigoutSlots

      public void clearAllDigoutSlots()
      Clears all configured "slots" on the specified digital output, setting them all to be disabled.

      This clears any configuration previously set by configureSlots(DigoutConfig).