Package com.reduxrobotics.sensors.canandmag

Class CanandmagSettings

java.lang.Object
com.reduxrobotics.canand.CanandSettings
com.reduxrobotics.sensors.canandmag.CanandmagSettings
public class CanandmagSettings extends CanandSettings
The settings class for the Canandmag.

This class holds settings values that can be used to reconfigure Canandmag via Canandmag.setSettings(com.reduxrobotics.sensors.canandmag.CanandmagSettings, double, int). Additionally, objects of this class are returned from Canandmag.getSettings(double, double, int) and Canandmag.getSettingsAsync() which can be used to read the devices's settings. 

 // Object initialization
 Canandmag enc = new Canandmag(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, enc.setSettings(new CanandmagSettings()); will be a no-op.
 
 enc.setSettings(new CanandmagSettings()
     .setPositionFramePeriod(0) // disables position readings
     .setVelocityFramePeriod(0.020) // sets the rate of velocity measurements to every 20 ms
     .setInvertDirection(true) // inverts the encoder direction
 );
 // enc.setSettings will block by default for up to 350 ms to confirm all values were set.
Objects returned by the blocking Canandmag.getSettings(double, double, int) method, unlike v2023, may now return null on its getters. This occurs when getSettings would've previously returned null -- however, this allows for partial settings fetches. To check if the settings fetch succeeded, one can use CanandSettings.allSettingsReceived() to check all fields are populated. Example blocking fetch: 
 // Object initialization
 Canandmag canandmag = new Canandmag(0);
 // ...
 
 // the actual fetch itself
 CanandmagSettings stg = canandmag.getSettings(0.5); // wait up to 500 ms
 if (stg.allSettingsReceived()) {
    // print the status frame period (1000 ms/1 second by default)
    System.out.printf("status frame period: %d\n", stg.getStatusFramePeriod()); 
 }

  • Constructor Details

    • CanandmagSettings

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

    • CanandmagSettings

      public CanandmagSettings(CanandmagSettings toCopy)
      Instantiates a new CanandmagSettings 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.

    • setVelocityFilterWidth

      public CanandmagSettings setVelocityFilterWidth(double widthMs)
      Sets the velocity filter width in milliseconds to sample over. Velocity is computed by averaging all the points in the past widthMs milliseconds. By factory default, the velocity filter averages over the past 25 milliseconds.
      Parameters:
      widthMs - the new number of samples to average over. Minimum accepted is 0.25 milliseconds, maximum is 63.75 ms.
      Returns:
      the calling object, so these calls can be chained

    • setPositionFramePeriod

      public CanandmagSettings setPositionFramePeriod(double period)
      Sets the position frame period in seconds. By factory default, position frames are sent every 20 milliseconds (period=0.020) If 0 is passed in, position frames will be disabled and the methods Canandmag.getPosition() and Canandmag.getAbsPosition() will not return new values.
      Parameters:
      period - the new period for position frames in seconds in range [0_ms, 65.535_s]
      Returns:
      the calling object, so these calls can be chained

    • setVelocityFramePeriod

      public CanandmagSettings setVelocityFramePeriod(double period)
      Sets the velocity frame period in seconds. By factory default, velocity frames are sent every 20 milliseconds (period=0.020) If 0 is passed in, velocity frames will be disabled and Canandmag.getVelocity() will not return new values.
      Parameters:
      period - the new period for velocity frames in seconds in range [0_ms, 65.535_s]
      Returns:
      the calling object, so these calls can be chained

    • setStatusFramePeriod

      public CanandmagSettings setStatusFramePeriod(double period)
      Sets the status frame period in seconds. By factory default, the encoder will broadcast 1 status message per second (period=1.0).
      Parameters:
      period - the new period for status frames in seconds in range [1.0_s, 16.383_s].
      Returns:
      the calling object, so these calls can be chained

    • setInvertDirection

      public CanandmagSettings setInvertDirection(boolean invert)
      Inverts the direction read from the sensor. By factory default, the sensor will read counterclockwise from its reading face as positive (invert=false).
      Parameters:
      invert - whether to invert (negate) readings from the encoder
      Returns:
      the calling object

    • setDisableZeroButton

      public CanandmagSettings setDisableZeroButton(boolean disable)
      Sets whether or not the sensor should disallow zeroing and factory resets from the onboard button. By factory default, the sensor will allow the zero button to function when pressed (disable=false)
      Parameters:
      disable - whether to disable the onboard zeroing button's functionality
      Returns:
      the calling object

    • setZeroOffset

      public CanandmagSettings setZeroOffset(double offset)
      Sets the zero offset of the encoder directly, rather than adjusting the zero offset relative to the currently read position.

      The zero offset is subtracted from the raw reading of the encoder's magnetic sensor to get the adjusted absolute position as returned by Canandmag.getAbsPosition(). Users are encouraged to use Canandmag.setAbsPosition(double, double, boolean) instead.

      Parameters:
      offset - the new offset in rotations [0..1)
      Returns:
      the calling object

    • getVelocityFilterWidth

      public Optional<Double> getVelocityFilterWidth()
      Gets the velocity filter width in milliseconds [0.25..63.75], or null if the value has not been set on this object.
      Returns:
      the velocity filter width in milliseconds [0.25..63.75], or null if the value has not been set on this object.

    • getPositionFramePeriod

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

    • getVelocityFramePeriod

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

    • getStatusFramePeriod

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

    • getInvertDirection

      public Optional<Boolean> getInvertDirection()
      Gets whether or not the encoder has an inverted direction (false for no, true for yes, null for unset).
      Returns:
      whether or not the encoder has an inverted direction (false for no, true for yes, null for unset).

    • getDisableZeroButton

      public Optional<Boolean> getDisableZeroButton()
      Gets whether or not the sensor should disallow zeroing and factory resets from the onboard button (0 for allow, 1 for disallow, -1 for unset).
      Returns:
      whether or not the encoder has its onboard zero button's functionality disabled (false for allow, true for disallow, null for unset).

    • getZeroOffset

      public Optional<Double> getZeroOffset()
      Gets the zero offset of the encoder. The zero offset is subtracted from the raw reading of the encoder's magnetic sensor to get the adjusted absolute position as returned by Canandmag.getAbsPosition().
      Returns:
      the zero offset [0..1), or null if the value has not been set on this object.