Package com.reduxrobotics.sensors.canandcolor

Class CanandcolorSettings

java.lang.Object
com.reduxrobotics.canand.CanandSettings
com.reduxrobotics.sensors.canandcolor.CanandcolorSettings
public class CanandcolorSettings extends CanandSettings
The settings class for the Canandcolor.

This class holds settings values that can be used to reconfigure Canandcolor via Canandcolor.setSettings(CanandcolorSettings). Additionally, objects of this class are returned from Canandcolor.getSettings() and Canandcolor.getSettingsAsync() which can be used to read the device's settings. 

 // Object initialization
 Canandcolor canandcolor = new Canandcolor(0);
 
 // Only settings that are explicitly set here will be edited, so other settings 
 // such as the status frame period will remain untouched.
 // For example, canandcolor.setSettings(new CanandcolorSettings()); will be a no-op.
 
 canandcolor.setSettings(new CanandcolorSettings()
     .setProximityFramePeriod(0) // disables proximity reading updates
     .setColorFramePeriod(0.020) // sets the rate of color measurements to every 20 ms
     .setColorIntegrationPeriod(ColorPeriod.k25ms) // sets the color integration period to 25 milliseconds 
 );
 // canandcolor.setSettings will block by default for up to 350 ms to confirm all values were set.

To check if the settings fetch succeeded, one can use CanandSettings.allSettingsReceived() to check all fields are populated. If that flag is true, all Optional values returned by the getters can be assumed to not be Optional.empty().

Example blocking fetch: 
 // Object initialization
 Canandcolor canandcolor = new Canandcolor(0);
 
 // Robot code 
 CanandcolorSettings stg = canandcolor.getSettings(0.5); // wait up to 500 ms
 if (stg.allSettingsReceived()) {
     // print the status frame period (usually 100 ms)
     System.out.printf("status frame period: %d\n", stg.getStatusFramePeriod().get());
 }

  • Constructor Details

    • CanandcolorSettings

      public CanandcolorSettings()
      Instantiates a new CanandcolorSettings object that is "completely blank" -- holding no settings values at all. Settings are only populated into the CanandcolorSettings object explicitly through the various setter methods -- running canandcolor.setSetting(new CanandcolorSettings()) would not update the device at all. To reset a device back to factory defaults, use Canandcolor.resetFactoryDefaults()

    • CanandcolorSettings

      public CanandcolorSettings(CanandcolorSettings toCopy)
      Instantiates a new CanandcolorSettings object that copies its settings from the input instance.
      Parameters:
      toCopy - the input settings object to copy

  • Method Details

    • fetchSettingsAddresses

      protected int[] fetchSettingsAddresses()
      Description copied from class: CanandSettings
      Gets the list of settings addresses this settings class records. This is typically a static list of constants from a Details class.
      Specified by:
      fetchSettingsAddresses in class CanandSettings
      Returns:
      settings addresses.

    • setStatusFramePeriod

      public CanandcolorSettings setStatusFramePeriod(double period)
      Sets the status frame period in seconds. By factory default, the device will broadcast 10 status messages per second (period=0.1).
      Parameters:
      period - the new period for status frames in seconds in range [0.001_s, 16.383_s].
      Returns:
      the calling object, so these calls can be chained

    • setProximityFramePeriod

      public CanandcolorSettings setProximityFramePeriod(double period)
      Sets the proximity frame period in seconds.

      By factory default, proximity frames are broadcast every 20 milliseconds (period=0.02). If 0 is passed in, proximity frames will be disabled and Canandcolor.getProximity() will not return new values.

      Note that if setAlignProximityFramesToIntegrationPeriod(boolean) is enabled, then this becomes the maximum period between two proximity frames, as proximity frames may get scheduled to broadcast early at the rate of the proximity integration period instead to minimize latency; but setting this option to zero still disables all proximity frames.

      Parameters:
      period - the new period for proximity frames in seconds in range [0_s, 65.535_s].
      Returns:
      the calling object, so these calls can be chained

    • setColorFramePeriod

      public CanandcolorSettings setColorFramePeriod(double period)
      Sets the color frame period in seconds.

      By factory default, color frames are broadcast every 25 milliseconds (period=0.025). If 0 is passed in, color frames will be disabled and Canandcolor.getColor() and other color-reading methods will not return new values.

      Note that if setAlignColorFramesToIntegrationPeriod(boolean) is enabled, then this becomes the maximum period between two proximity frames, as proximity frames may get scheduled to broadcast early at the rate of the color integration period instead to minimize latency; but setting this option to zero still disables all color frames.

      Parameters:
      period - the new period for color frames in seconds in range [0_s, 65.535_s].
      Returns:
      the calling object, so these calls can be chained

    • setDigoutFramePeriod

      public CanandcolorSettings setDigoutFramePeriod(double period)
      Sets the digital output (digout) frame period in seconds.

      By factory default, digout frames are broadcast every 100 milliseconds (period=0.10). If 0 is passed in, digout frames will be disabled and Canandcolor.getDigoutState() and DigoutChannel.getValue()/DigoutChannel.getStickyValue() will not return new values.

      Parameters:
      period - the new period for digout frames in seconds in range [0_s, 65.535_s].
      Returns:
      the calling object, so these calls can be chained

    • setLampLEDBrightness

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

      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)
      Returns:
      the calling object, so these calls can be chained

    • setColorIntegrationPeriod

      public CanandcolorSettings setColorIntegrationPeriod(ColorPeriod period)
      Sets the sampling/integration period for the color sensor.

      If setAlignColorFramesToIntegrationPeriod(boolean) is set, this also effectively determines the frame period of the color frame as well.

      Parameters:
      period - the ColorPeriod to apply
      Returns:
      the calling object, so these calls can be chained
      See Also:

    • setProximityIntegrationPeriod

      public CanandcolorSettings setProximityIntegrationPeriod(ProximityPeriod period)
      Sets the integration period/multipulse configuration for the proximity sensor.

      If setAlignProximityFramesToIntegrationPeriod(boolean) is set, this also effectively determines the frame period of the proximity frame as well.

      Parameters:
      period - the ProximityPeriod to apply
      Returns:
      the calling object, so these calls can be chained
      See Also:

    • setDigoutPinConfig

      public CanandcolorSettings setDigoutPinConfig(DigoutChannel.Index digout, DigoutPinConfig config)
      Configures the physical GPIO pin associated with a given digital output 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:

      See DigoutChannel.configureOutputPin(DigoutPinConfig) for how to pass in a DigoutPinConfig.
      Parameters:
      digout - the channel to configure (either DigoutChannel.Index.kDigout1 or DigoutChannel.Index.kDigout2). Note that channel 1 does not support duty cycle output.
      config - a DigoutPinConfig specifying how the digout should output if at all.
      Returns:
      the calling object, so these calls can be chained

    • setDigoutFrameTrigger

      public CanandcolorSettings setDigoutFrameTrigger(DigoutChannel.Index digout, DigoutFrameTrigger trg)
      Sets digout message triggers which control if the Canandcolor should send digout messages on state change.

      These triggers can function even if digout output for the corresponding DigoutChannel.Index via setDigoutPinConfig(DigoutChannel.Index, DigoutPinConfig) is disabled or set to duty cycle output. This allows user code to quickly react to digout logic purely over CAN without needing direct GPIO digital I/O connections.

      Parameters:
      digout - the digout to configure (either DigoutChannel.Index.kDigout1 or DigoutChannel.Index.kDigout2)
      trg - digout message trigger
      Returns:
      the calling object, so these calls can be chained
      See Also:

    • setAlignProximityFramesToIntegrationPeriod

      public CanandcolorSettings setAlignProximityFramesToIntegrationPeriod(boolean align)
      Sets whether or not to align the transmission of proximity frames to the integration period of the proximity sensor.

      This setting makes the Cannadcolor transmit proximity frames whenever it finishes processing new proximity data.

      For example, if the proximity frame period is normally set to 200 ms, and the configured ProximityPeriod is 10 ms, passing true to this method would make the sensor emit a new proximity frame every 10 ms when the proximity sensor updates.

      Parameters:
      align - true if to enable this feature
      Returns:
      the calling object, so these calls can be chained

    • setAlignColorFramesToIntegrationPeriod

      public CanandcolorSettings setAlignColorFramesToIntegrationPeriod(boolean align)
      Sets whether or not to align the transmission of color frames to the integration period of the color sensor.

      This setting makes the Cannadcolor transmit color frames whenever it finishes processing new color data.

      For example, if the color frame period is normally set to 200 ms, and the configured ColorPeriod is 25ms, passing true to this method would make the sensor emit a new color frame every 25ms when the color sensor updates.

      Parameters:
      align - true if to enable this feature
      Returns:
      the calling object, so these calls can be chained

    • getStatusFramePeriod

      public Optional<Double> getStatusFramePeriod()
      Gets the status frame period in seconds [0.001..65.535], or an empty Optional if the value has not been set on this object.
      Returns:
      the status frame period in seconds [0.001..65.535], or an empty Optional if the value has not been set on this object.

    • getProximityFramePeriod

      public Optional<Double> getProximityFramePeriod()
      Gets the proximity frame period in seconds [0..65.535], or an empty Optional if the value has not been set on this object. A value of 0 means proximity messages are disabled.
      Returns:
      the frame period in seconds [0..65.535], or an empty Optional if the value has not been set on this object.

    • getColorFramePeriod

      public Optional<Double> getColorFramePeriod()
      Gets the color frame period in seconds [0..65.535], or an empty Optional if the value has not been set on this object. A value of 0 means color messages are disabled.
      Returns:
      the frame period in seconds [0..65.535], or an empty Optional if the value has not been set on this object.

    • getDigoutFramePeriod

      public Optional<Double> getDigoutFramePeriod()
      Gets the digout status frame period in seconds [0..65.535], or an empty Optional if the value has not been set on this object. A value of 0 means digout status messages are disabled.
      Returns:
      the frame period in seconds [0..65.535], or an empty Optional if the value has not been set on this object.

    • getLampLEDBrightness

      public Optional<Double> getLampLEDBrightness()
      Gets the lamp LED's brightness, scaled from 0.0 (off) to 1.0 (max)
      Returns:
      the brightness factor [0.0..1.0] or an empty Optional if unset

    • getColorIntegrationPeriod

      public Optional<ColorPeriod> getColorIntegrationPeriod()
      Gets the sampling/integration period for the color sensor, if set on this object.
      Returns:
      ColorPeriod enum or Optional.empty() if unset

    • getProximityIntegrationPeriod

      public Optional<ProximityPeriod> getProximityIntegrationPeriod()
      Gets the sampling/integration period for the proximity sensor, if set on this object.
      Returns:
      ProximityPeriod or Optional.empty() if unset

    • getDigoutPinConfig

      public Optional<DigoutPinConfig> getDigoutPinConfig(DigoutChannel.Index digout)
      Gets the output configuration for a physical GPIO pin associated with the given digout channel.
      Parameters:
      digout - the digital output config to fetch
      Returns:
      the DigoutPinConfig or Optional.empty() if unset

    • getDigoutFrameTrigger

      public Optional<DigoutFrameTrigger> getDigoutFrameTrigger(DigoutChannel.Index digout)
      Gets the frame trigger configuration for a digital output.
      Parameters:
      digout - the digital output config to fetch
      Returns:
      the DigoutFrameTrigger or Optional.empty() if unset

    • getAlignProximityFramesToIntegrationPeriod

      public Optional<Boolean> getAlignProximityFramesToIntegrationPeriod()
      Gets the config for proximity frame period alignment with integration period.
      Returns:
      the config state (true if enabled) or Optional.empty() if unset
      See Also:

    • getAlignColorFramesToIntegrationPeriod

      public Optional<Boolean> getAlignColorFramesToIntegrationPeriod()
      Gets the config for color frame period alignment with integration period.
      Returns:
      the config state (true if enabled) or Optional.empty() if unset
      See Also: