Class GoBildaPinpoint

java.lang.Object
org.wpilib.drivers.odometry.GoBildaPinpoint
All Implemented Interfaces:
AutoCloseable
public class GoBildaPinpoint extends Object implements AutoCloseable
Driver for the goBILDA Pinpoint Odometry Computer.

Aborted I2C transactions and invalid read data are reported through GoBildaPinpoint.DeviceStatus.FAULT_BAD_READ instead of throwing an exception. Unless otherwise noted, methods that access the device throw IllegalStateException after this driver is closed.

  • Field Details

    • DEFAULT_ADDRESS

      public static final int DEFAULT_ADDRESS
      Default 7-bit I2C address of the Pinpoint.
      See Also:

  • Constructor Details

    • GoBildaPinpoint

      public GoBildaPinpoint(I2C.Port port)
      Constructs a Pinpoint on its default I2C address.
      Parameters:
      port - I2C port to which the Pinpoint is connected
      Throws:
      NullPointerException - if port is null

    • GoBildaPinpoint

      public GoBildaPinpoint(I2C.Port port, int deviceAddress)
      Constructs a Pinpoint.
      Parameters:
      port - I2C port to which the Pinpoint is connected
      deviceAddress - 7-bit I2C address
      Throws:
      NullPointerException - if port is null
      IllegalArgumentException - if deviceAddress is outside the 7-bit address range

  • Method Details

    • getPort

      public I2C.Port getPort()
      Returns the I2C port.
      Returns:
      I2C port
      Throws:
      IllegalStateException - if this driver has been closed

    • getDeviceAddress

      public int getDeviceAddress()
      Returns the I2C address.
      Returns:
      7-bit I2C address
      Throws:
      IllegalStateException - if this driver has been closed

    • close

      public void close()
      Closes the I2C connection. Calling this method more than once has no effect.
      Specified by:
      close in interface AutoCloseable

    • update

      public void update()
      Reads all registers in the configured bulk-read scope and updates the cached measurements. Call this once per robot loop.

      An aborted or invalid I2C read does not throw; it sets the device status to GoBildaPinpoint.DeviceStatus.FAULT_BAD_READ and preserves the last valid measurements.

      Throws:
      IllegalStateException - if this driver has been closed
      UnsupportedOperationException - if CRC error detection is active with firmware older than v3

    • updateHeading

      public void updateHeading()
      Reads and caches only the heading register.

      An aborted or invalid I2C read does not throw; it sets the device status to GoBildaPinpoint.DeviceStatus.FAULT_BAD_READ and preserves the last valid heading.

      Throws:
      IllegalStateException - if this driver has been closed

    • setBulkReadScope

      public void setBulkReadScope(GoBildaPinpoint.Register... registers)
      Configures the registers returned by a bulk read on v3 or newer firmware. Duplicate registers are ignored while preserving the order of their first occurrence.
      Parameters:
      registers - readable registers to include
      Throws:
      NullPointerException - if registers or any register in it is null
      UnsupportedOperationException - if the firmware is older than v3
      IllegalArgumentException - if no registers are provided or a register is not readable
      IllegalStateException - if this driver has been closed

    • setErrorDetectionType

      public void setErrorDetectionType(GoBildaPinpoint.ErrorDetectionType errorDetectionType)
      Selects the read error detection method. Selecting CRC reads the firmware version and requires v3 or newer firmware.
      Parameters:
      errorDetectionType - error detection method
      Throws:
      NullPointerException - if errorDetectionType is null
      UnsupportedOperationException - if CRC is selected with firmware older than v3
      IllegalStateException - if this driver has been closed

    • setOffsets

      public void setOffsets(double xOffsetMeters, double yOffsetMeters)
      Sets the odometry pod offsets in meters.

      The X pod offset is positive to the left of the tracking point. The Y pod offset is positive in front of the tracking point.

      Parameters:
      xOffsetMeters - X pod offset in meters
      yOffsetMeters - Y pod offset in meters
      Throws:
      IllegalArgumentException - if either offset is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • setOffsets

      public void setOffsets(Distance xOffset, Distance yOffset)
      Sets the odometry pod offsets.

      The X pod offset is positive to the left of the tracking point. The Y pod offset is positive in front of the tracking point.

      Parameters:
      xOffset - X pod offset
      yOffset - Y pod offset
      Throws:
      NullPointerException - if either offset is null
      IllegalArgumentException - if either converted offset is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • recalibrateImu

      public void recalibrateImu()
      Recalibrates the IMU. The robot must remain stationary for approximately 0.25 seconds.
      Throws:
      IllegalStateException - if this driver has been closed

    • resetPositionAndImu

      public void resetPositionAndImu()
      Resets the pose to the origin and recalibrates the IMU. The robot must remain stationary.
      Throws:
      IllegalStateException - if this driver has been closed

    • setEncoderDirections

      public void setEncoderDirections(GoBildaPinpoint.EncoderDirection xEncoder, GoBildaPinpoint.EncoderDirection yEncoder)
      Sets the directions of both odometry pod encoders.
      Parameters:
      xEncoder - X (forward) pod direction
      yEncoder - Y (left) pod direction
      Throws:
      NullPointerException - if either direction is null
      IllegalStateException - if this driver has been closed

    • setEncoderResolution

      public void setEncoderResolution(GoBildaPinpoint.OdometryPod pod)
      Sets the encoder resolution for a goBILDA odometry pod.
      Parameters:
      pod - odometry pod type
      Throws:
      NullPointerException - if pod is null
      IllegalStateException - if this driver has been closed

    • setEncoderResolution

      public void setEncoderResolution(double ticksPerMeter)
      Sets a custom odometry pod encoder resolution.
      Parameters:
      ticksPerMeter - encoder ticks per meter of pod travel
      Throws:
      IllegalArgumentException - if ticksPerMeter is nonfinite, not positive, or does not produce a positive ticks-per-millimeter value representable by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • setYawScalar

      public void setYawScalar(double yawScalar)
      Sets the scalar applied to the IMU yaw measurement.
      Parameters:
      yawScalar - yaw scalar
      Throws:
      IllegalArgumentException - if yawScalar is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • setPose

      public void setPose(Pose2d pose)
      Overrides the pose tracked by the Pinpoint.
      Parameters:
      pose - pose in meters and radians
      Throws:
      NullPointerException - if pose is null
      IllegalArgumentException - if a pose component is nonfinite or cannot be represented by the device's 32-bit floating-point registers
      IllegalStateException - if this driver has been closed

    • setXPositionMeters

      public void setXPositionMeters(double positionMeters)
      Overrides the tracked X position.
      Parameters:
      positionMeters - X position in meters
      Throws:
      IllegalArgumentException - if positionMeters is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • setXPosition

      public void setXPosition(Distance position)
      Overrides the tracked X position.
      Parameters:
      position - X position
      Throws:
      NullPointerException - if position is null
      IllegalArgumentException - if position is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • setYPositionMeters

      public void setYPositionMeters(double positionMeters)
      Overrides the tracked Y position.
      Parameters:
      positionMeters - Y position in meters
      Throws:
      IllegalArgumentException - if positionMeters is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • setYPosition

      public void setYPosition(Distance position)
      Overrides the tracked Y position.
      Parameters:
      position - Y position
      Throws:
      NullPointerException - if position is null
      IllegalArgumentException - if position is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • setHeadingRadians

      public void setHeadingRadians(double headingRadians)
      Overrides the tracked heading.
      Parameters:
      headingRadians - heading in radians
      Throws:
      IllegalArgumentException - if headingRadians is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • setHeading

      public void setHeading(Angle heading)
      Overrides the tracked heading.
      Parameters:
      heading - heading
      Throws:
      NullPointerException - if heading is null
      IllegalArgumentException - if heading is nonfinite or cannot be represented by the device's 32-bit floating-point register
      IllegalStateException - if this driver has been closed

    • getDeviceId

      public int getDeviceId()
      Returns the device identifier.
      Returns:
      device identifier
      Throws:
      IllegalStateException - if this driver has been closed

    • getDeviceVersion

      public int getDeviceVersion()
      Returns the firmware version.
      Returns:
      firmware version
      Throws:
      IllegalStateException - if this driver has been closed

    • getYawScalar

      public double getYawScalar()
      Returns the configured yaw scalar.
      Returns:
      yaw scalar
      Throws:
      IllegalStateException - if this driver has been closed

    • getEncoderResolutionTicksPerMeter

      public double getEncoderResolutionTicksPerMeter()
      Returns the configured encoder resolution.
      Returns:
      encoder ticks per meter
      Throws:
      IllegalStateException - if this driver has been closed

    • getDeviceStatus

      public GoBildaPinpoint.DeviceStatus getDeviceStatus()
      Returns the highest-priority current device or read status.
      Returns:
      device status
      Throws:
      IllegalStateException - if this driver has been closed

    • getDeviceStatusBits

      public int getDeviceStatusBits()
      Returns the cached device status bits combined with the local bad-read status bit, if set.
      Returns:
      status bits
      Throws:
      IllegalStateException - if this driver has been closed

    • getLastFailedRegister

      public GoBildaPinpoint.Register getLastFailedRegister()
      Returns the register associated with the most recent driver-detected failure.
      Returns:
      failed register, or null if the driver has not detected a failure
      Throws:
      IllegalStateException - if this driver has been closed

    • getLastFailureReason

      public GoBildaPinpoint.FailureReason getLastFailureReason()
      Returns the reason for the most recent driver-detected failure.
      Returns:
      failure reason, or null if the driver has not detected a failure
      Throws:
      IllegalStateException - if this driver has been closed

    • getFailureCount

      public long getFailureCount()
      Returns the total number of failures detected by this driver instance.
      Returns:
      total failure count
      Throws:
      IllegalStateException - if this driver has been closed

    • getFailureCount

      public long getFailureCount(GoBildaPinpoint.Register register)
      Returns the number of failures associated with a register.
      Parameters:
      register - register whose failure count should be returned
      Returns:
      failure count for the register
      Throws:
      NullPointerException - if register is null
      IllegalStateException - if this driver has been closed

    • getLoopTimeMicroseconds

      public int getLoopTimeMicroseconds()
      Returns the most recently reported device loop time.
      Returns:
      loop time in microseconds
      Throws:
      IllegalStateException - if this driver has been closed

    • getFrequencyHz

      public double getFrequencyHz()
      Returns the most recently reported device loop frequency.
      Returns:
      frequency in hertz, or zero when no loop time has been read
      Throws:
      IllegalStateException - if this driver has been closed

    • getFrequency

      public Frequency getFrequency()
      Returns the most recently reported device loop frequency.
      Returns:
      loop frequency, or zero when no loop time has been read
      Throws:
      IllegalStateException - if this driver has been closed

    • getXEncoder

      public int getXEncoder()
      Returns the raw X encoder count.
      Returns:
      X encoder ticks
      Throws:
      IllegalStateException - if this driver has been closed

    • getYEncoder

      public int getYEncoder()
      Returns the raw Y encoder count.
      Returns:
      Y encoder ticks
      Throws:
      IllegalStateException - if this driver has been closed

    • getXPositionMeters

      public double getXPositionMeters()
      Returns the tracked X position.
      Returns:
      X position in meters
      Throws:
      IllegalStateException - if this driver has been closed

    • getXPosition

      public Distance getXPosition()
      Returns the tracked X position.
      Returns:
      X position
      Throws:
      IllegalStateException - if this driver has been closed

    • getYPositionMeters

      public double getYPositionMeters()
      Returns the tracked Y position.
      Returns:
      Y position in meters
      Throws:
      IllegalStateException - if this driver has been closed

    • getYPosition

      public Distance getYPosition()
      Returns the tracked Y position.
      Returns:
      Y position
      Throws:
      IllegalStateException - if this driver has been closed

    • getHeadingRadians

      public double getHeadingRadians()
      Returns the continuous tracked heading.
      Returns:
      heading in radians, not constrained to one rotation
      Throws:
      IllegalStateException - if this driver has been closed

    • getHeading

      public Angle getHeading()
      Returns the continuous tracked heading.
      Returns:
      heading, not constrained to one rotation
      Throws:
      IllegalStateException - if this driver has been closed

    • getXVelocityMetersPerSecond

      public double getXVelocityMetersPerSecond()
      Returns the tracked X velocity.
      Returns:
      X velocity in meters per second
      Throws:
      IllegalStateException - if this driver has been closed

    • getXVelocity

      public LinearVelocity getXVelocity()
      Returns the tracked X velocity.
      Returns:
      X velocity
      Throws:
      IllegalStateException - if this driver has been closed

    • getYVelocityMetersPerSecond

      public double getYVelocityMetersPerSecond()
      Returns the tracked Y velocity.
      Returns:
      Y velocity in meters per second
      Throws:
      IllegalStateException - if this driver has been closed

    • getYVelocity

      public LinearVelocity getYVelocity()
      Returns the tracked Y velocity.
      Returns:
      Y velocity
      Throws:
      IllegalStateException - if this driver has been closed

    • getHeadingVelocityRadiansPerSecond

      public double getHeadingVelocityRadiansPerSecond()
      Returns the heading velocity.
      Returns:
      heading velocity in radians per second
      Throws:
      IllegalStateException - if this driver has been closed

    • getHeadingVelocity

      public AngularVelocity getHeadingVelocity()
      Returns the heading velocity.
      Returns:
      heading velocity
      Throws:
      IllegalStateException - if this driver has been closed

    • getXOffsetMeters

      public double getXOffsetMeters()
      Returns the X pod offset.
      Returns:
      X pod offset in meters
      Throws:
      IllegalStateException - if this driver has been closed

    • getXOffset

      public Distance getXOffset()
      Returns the X pod offset.
      Returns:
      X pod offset
      Throws:
      IllegalStateException - if this driver has been closed

    • getYOffsetMeters

      public double getYOffsetMeters()
      Returns the Y pod offset.
      Returns:
      Y pod offset in meters
      Throws:
      IllegalStateException - if this driver has been closed

    • getYOffset

      public Distance getYOffset()
      Returns the Y pod offset.
      Returns:
      Y pod offset
      Throws:
      IllegalStateException - if this driver has been closed

    • getPose

      public Pose2d getPose()
      Returns the tracked pose. Translation is in meters; heading is normalized by Rotation2d.

      If the configured bulk-read scope does not contain all three pose registers, this reads X, Y, and heading together so the returned components are from the same device snapshot.

      Returns:
      tracked pose
      Throws:
      IllegalStateException - if this driver has been closed

    • getQuaternion

      public Quaternion getQuaternion()
      Returns the device orientation quaternion. Requires v3 or newer firmware. If the configured bulk-read scope does not contain all four quaternion registers, this reads all four components together so they come from the same device snapshot.
      Returns:
      orientation quaternion
      Throws:
      IllegalStateException - if this driver has been closed
      UnsupportedOperationException - if the firmware is older than v3

    • getRotation3d

      public Rotation3d getRotation3d()
      Returns the device orientation as a 3D rotation. Requires v3 or newer firmware.
      Returns:
      3D orientation
      Throws:
      IllegalStateException - if this driver has been closed
      UnsupportedOperationException - if the firmware is older than v3

    • getPitchRadians

      public double getPitchRadians()
      Returns the pitch. Requires v3 or newer firmware.
      Returns:
      pitch in radians
      Throws:
      IllegalStateException - if this driver has been closed
      UnsupportedOperationException - if the firmware is older than v3

    • getPitch

      public Angle getPitch()
      Returns the pitch. Requires v3 or newer firmware.
      Returns:
      pitch
      Throws:
      IllegalStateException - if this driver has been closed
      UnsupportedOperationException - if the firmware is older than v3

    • getRollRadians

      public double getRollRadians()
      Returns the roll. Requires v3 or newer firmware.
      Returns:
      roll in radians
      Throws:
      IllegalStateException - if this driver has been closed
      UnsupportedOperationException - if the firmware is older than v3

    • getRoll

      public Angle getRoll()
      Returns the roll. Requires v3 or newer firmware.
      Returns:
      roll
      Throws:
      IllegalStateException - if this driver has been closed
      UnsupportedOperationException - if the firmware is older than v3