Class CanandcolorSettings

java.lang.Object
com.reduxrobotics.sensors.canandcolor.CanandcolorSettings

public class CanandcolorSettings extends Object
The settings class for the Canandcolor.

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

 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(CanandcolorColorPeriod.k80Milliseconds) // sets the color integration period to 80 milliseconds
 );
 // canandcolor.setSettings will block by default for up to 500 ms to confirm all values were set.
 
 
Note that all get[setting name](); functions may return -1 if they're not populated as CanandcolorSettings objects may not always have a value set for a setting. This is particularly true of instances returned by Canandcolor.getSettingsAsync(), and you will need to use allSettingsReceived() to check if all are present. However, objects returned by the blocking Canandcolor.getSettings(double) method will always have all setting values populated, and getters will never return null. Example blocking fetch:
 Canandcolor canandcolor = new Canandcolor(0);
 CanandcolorSettings stg;
 canandcolor.getSettings(0.5); // wait up to 500 ms
 System.out.printf("status frame period: %d\n", stg.getStatusFramePeriod()); // print the status frame period (usually 1000 ms)
 
  • Constructor Details

    • CanandcolorSettings

      public CanandcolorSettings()
      Instantiates a new CanandcolorSettings object, that is "completely blank" -- that is, it holds 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 an device back to factory defaults, use Canandcolor.resetFactoryDefaults(double)
    • 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

    • setStatusFramePeriod

      public CanandcolorSettings setStatusFramePeriod(double period)
      Sets the status frame period in seconds. By factory default, the device will broadcast 1 status message every second (period=1.0).
      Parameters:
      period - the new period for status frames in seconds in range [0.001_s, 65.535_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 10 milliseconds (period=0.01). If 0 is passed in, proximity frames will be disabled and Canandcolor.getProximity() will not return new values.
      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 40 milliseconds (period=0.04). If 0 is passed in, color frames will be disabled and Canandcolor.getColor() and other color-reading methods will not return new values.
      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() 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
    • setFramePeriodLatencyAdjustment

      public CanandcolorSettings setFramePeriodLatencyAdjustment(boolean adjust)
      Sets whether or not to transmit frame periods early if data has just been received. This applies only in the case where frame periods for color and proximity are equal to or less than the configured sampling periods of their corresponding ICs, which is true by default.

      This increases CAN utilization a little, but minimizes latency.

      By factory default this setting is enabled.
      Parameters:
      adjust - Whether to enable latency adjustment
      Returns:
      the calling object, so these calls can be chained
    • setLampLED

      public CanandcolorSettings 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 this setting is enabled.
      Parameters:
      lamp - whether to enable or disable the lamp LED
      Returns:
      the calling object, so these calls can be chained
    • setProximityConfig

      public CanandcolorSettings setProximityConfig(CanandcolorProximityConfig cfg)
      Sets fine-tuned settings for the proximity sensor through values in a CanandcolorProximityConfig object.
      Parameters:
      cfg - the configruation object to apply setings from
      Returns:
      the calling object, so these calls can be chained
    • setColorConfig

      public CanandcolorSettings setColorConfig(CanandcolorColorPeriod period)
      Sets the sampling/integration period for the color sensor.
      Parameters:
      period - the CanandcolorColorPeriod to apply
      Returns:
      the calling object, so these calls can be chained
    • setDigoutPinEnabled

      public CanandcolorSettings setDigoutPinEnabled(CanandcolorDigitalOutput digout, boolean enableOutput)
      Sets whether to enable output on a digital output pin.
      Parameters:
      digout - the digout to use
      enableOutput - whether the digout pin is enabled (and can thus change values)
      Returns:
      the calling object, so these calls can be chained
    • setDigoutPinNormallyClosed

      public CanandcolorSettings setDigoutPinNormallyClosed(CanandcolorDigitalOutput digout, boolean normallyClosed)
      Sets whether to default to normally open or normally closed on a digital output pin. Normally closed will output high if the digout value is false, whereas normally open will output high if the digout value is true (the default behavior)
      Parameters:
      digout - the digout to use
      normallyClosed - true if normally closed (output high on false) false if normally open (output high on true, the default)
      Returns:
      the calling object, so these calls can be chained
    • getMap

      public Map<Byte,Long> getMap()
      Directly access the underlying Map of settings values. Intended for internal use.
      Returns:
      map
    • allSettingsReceived

      public boolean allSettingsReceived()
      Returns whether or not all settings fields have been written into the object. If this is returned from Canandcolor.getSettings(double) this is guarenteed to be true. However, if returned from Canandcolor.getSettingsAsync(), this may be false until all settings values have been received from the device.
      Returns:
      whether the settings object has been filled
    • getFilteredMap

      public Map<Byte,Long> getFilteredMap()
      Return a direct filtered view of settings values as a new HashMap, limited to only valid settings.
      Returns:
      map
    • getStatusFramePeriod

      public Double getStatusFramePeriod()
      Gets the status frame period in seconds [1..65.535], or null if the value has not been set on this object.
      Returns:
      the status frame period in seconds [1..65.535], or null if the value has not been set on this object.
    • getProximityFramePeriod

      public Double getProximityFramePeriod()
      Gets the proximity frame period in seconds [1..65.535], or null 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 null if the value has not been set on this object.
    • getColorFramePeriod

      public Double getColorFramePeriod()
      Gets the color frame period in seconds [0..65.535], or null 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 null if the value has not been set on this object.
    • getDigoutFramePeriod

      public Double getDigoutFramePeriod()
      Gets the digout status frame period in seconds [0..65.535], or null 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 null if the value has not been set on this object.
    • getFramePeriodLatencyAdjustment

      public Boolean getFramePeriodLatencyAdjustment()
      Gets whether or not to transmit frame periods early if data has just been received. By factory default this setting is enabled.
      Returns:
      true if on, false if off, null if unset
    • getLampLED

      public Boolean getLampLED()
      Gets whether or not the onboard lamp LED setting is to be on.
      Returns:
      true if on, false if off, null if unset
    • getProximityConfig

      public CanandcolorProximityConfig getProximityConfig()
      Gets whether or not the onboard lamp LED setting is to be on.
      Returns:
      true if on, false if off, null if unset
    • getColorConfig

      public CanandcolorColorPeriod getColorConfig()
      Gets the device's sampling/integration period for the color sensor, if set.
      Returns:
      CanandcolorColorPeriod enum or null if unset
    • getDigoutPinEnabled

      public Boolean getDigoutPinEnabled(CanandcolorDigitalOutput digout)
      Gets if output for the specified digout pin is enabled.
      Parameters:
      digout - the digital output to use
      Returns:
      true if enabled, false if not, or null if unset
    • getDigoutPinNormallyClosed

      public Boolean getDigoutPinNormallyClosed(CanandcolorDigitalOutput digout)
      Gets if output for the specified digout pin is set to normally closed (high logic level) operation.
      Parameters:
      digout - the digital output to use
      Returns:
      true if normally closed, false if normally open, or null if unset