edu.wpi.first.wpilibj

## Class Ultrasonic

- java.lang.Object
- - edu.wpi.first.wpilibj.SensorBase
  - - edu.wpi.first.wpilibj.Ultrasonic

- All Implemented Interfaces:
    LiveWindowSendable, PIDSource, Sendable

      public class Ultrasonic
      extends SensorBase
      implements PIDSource, LiveWindowSendable

  Ultrasonic rangefinder class. The Ultrasonic rangefinder measures absolute distance based on the round-trip time of a ping generated by the controller. These sensors use two transducers, a speaker and a microphone both tuned to the ultrasonic range. A common ultrasonic sensor, the Daventech SRF04 requires a short pulse to be generated on a digital channel. This causes the chirp to be emitted. A second line becomes high as the ping is transmitted and goes low when the echo is received. The time that the line is high determines the round trip distance (time of flight).

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Ultrasonic.Unit` The units to return when PIDGet is called.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected PIDSourceType` | `m_pidSource`

    - ### Fields inherited from class edu.wpi.first.wpilibj.SensorBase

      `kAnalogInputChannels, kAnalogOutputChannels, kDigitalChannels, kPCMModules, kPDPChannels, kPDPModules, kPwmChannels, kRelayChannels, kSolenoidChannels, kSystemClockTicksPerMicrosecond`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Ultrasonic(DigitalOutput pingChannel, DigitalInput echoChannel)` Create an instance of an Ultrasonic Sensor from a DigitalInput for the echo channel and a DigitalOutput for the ping channel.
    `Ultrasonic(DigitalOutput pingChannel, DigitalInput echoChannel, Ultrasonic.Unit units)` Create an instance of an Ultrasonic Sensor from a DigitalInput for the echo channel and a DigitalOutput for the ping channel.
    `Ultrasonic(int pingChannel, int echoChannel)` Create an instance of the Ultrasonic Sensor.
    `Ultrasonic(int pingChannel, int echoChannel, Ultrasonic.Unit units)` Create an instance of the Ultrasonic Sensor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `free()` Destructor for the ultrasonic sensor.
    `Ultrasonic.Unit` | `getDistanceUnits()` Get the current DistanceUnit that is used for the PIDSource base object.
    `PIDSourceType` | `getPIDSourceType()` Get which parameter of the device you are using as a process control variable.
    `double` | `getRangeInches()` Get the range in inches from the ultrasonic sensor.
    `double` | `getRangeMM()` Get the range in millimeters from the ultrasonic sensor.
    `java.lang.String` | `getSmartDashboardType()` Live Window code, only does anything if live window is activated.
    `void` | `initTable(NetworkTable subtable)` Initializes a table for this `Sendable` object.
    `boolean` | `isEnabled()` Is the ultrasonic enabled.
    `boolean` | `isRangeValid()` Check if there is a valid range measurement.
    `double` | `pidGet()` Get the range in the current DistanceUnit for the PIDSource base object.
    `void` | `ping()` Single ping to ultrasonic sensor.
    `void` | `setAutomaticMode(boolean enabling)` Turn Automatic mode on/off.
    `void` | `setDistanceUnits(Ultrasonic.Unit units)` Set the current DistanceUnit that should be used for the PIDSource base object.
    `void` | `setEnabled(boolean enable)` Set if the ultrasonic is enabled.
    `void` | `setPIDSourceType(PIDSourceType pidSource)` Set which parameter of the device you are using as a process control variable.
    `void` | `startLiveWindowMode()` Start having this sendable object automatically respond to value changes reflect the value on the table.
    `void` | `stopLiveWindowMode()` Stop having this sendable object automatically respond to value changes.
    `void` | `updateTable()` Update the table for this sendable object with the latest values.

    - ### Methods inherited from class edu.wpi.first.wpilibj.SensorBase

      `checkAnalogInputChannel, checkAnalogOutputChannel, checkDigitalChannel, checkPDPChannel, checkPDPModule, checkPWMChannel, checkRelayChannel, checkSolenoidChannel, checkSolenoidModule, getDefaultSolenoidModule, setDefaultSolenoidModule`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### m_pidSource

          protected PIDSourceType m_pidSource

  - ### Constructor Detail

    - #### Ultrasonic

          public Ultrasonic(int pingChannel,
                            int echoChannel,
                            Ultrasonic.Unit units)

      Create an instance of the Ultrasonic Sensor. This is designed to supchannel the Daventech SRF04 and Vex ultrasonic sensors.
      Parameters:
        `pingChannel` - The digital output channel that sends the pulse to initiate the sensor sending the ping.
        `echoChannel` - The digital input channel that receives the echo. The length of time that the echo is high represents the round trip time of the ping, and the distance.
        `units` - The units returned in either kInches or kMilliMeters

    - #### Ultrasonic

          public Ultrasonic(int pingChannel,
                            int echoChannel)

      Create an instance of the Ultrasonic Sensor. This is designed to supchannel the Daventech SRF04 and Vex ultrasonic sensors. Default unit is inches.
      Parameters:
        `pingChannel` - The digital output channel that sends the pulse to initiate the sensor sending the ping.
        `echoChannel` - The digital input channel that receives the echo. The length of time that the echo is high represents the round trip time of the ping, and the distance.

    - #### Ultrasonic

          public Ultrasonic(DigitalOutput pingChannel,
                            DigitalInput echoChannel,
                            Ultrasonic.Unit units)

      Create an instance of an Ultrasonic Sensor from a DigitalInput for the echo channel and a DigitalOutput for the ping channel.
      Parameters:
        `pingChannel` - The digital output object that starts the sensor doing a ping. Requires a 10uS pulse to start.
        `echoChannel` - The digital input object that times the return pulse to determine the range.
        `units` - The units returned in either kInches or kMilliMeters

    - #### Ultrasonic

          public Ultrasonic(DigitalOutput pingChannel,
                            DigitalInput echoChannel)

      Create an instance of an Ultrasonic Sensor from a DigitalInput for the echo channel and a DigitalOutput for the ping channel. Default unit is inches.
      Parameters:
        `pingChannel` - The digital output object that starts the sensor doing a ping. Requires a 10uS pulse to start.
        `echoChannel` - The digital input object that times the return pulse to determine the range.

  - ### Method Detail

    - #### free

          public void free()

      Destructor for the ultrasonic sensor. Delete the instance of the ultrasonic sensor by freeing the allocated digital channels. If the system was in automatic mode (round robin), then it is stopped, then started again after this sensor is removed (provided this wasn't the last sensor).
      Overrides:
        `free` in class `SensorBase`

    - #### setAutomaticMode

          public void setAutomaticMode(boolean enabling)

      Turn Automatic mode on/off. When in Automatic mode, all sensors will fire in round robin, waiting a set time between each sensor.
      Parameters:
        `enabling` - Set to true if round robin scheduling should start for all the ultrasonic sensors. This scheduling method assures that the sensors are non-interfering because no two sensors fire at the same time. If another scheduling algorithm is preferred, it can be implemented by pinging the sensors manually and waiting for the results to come back.

    - #### ping

          public void ping()

      Single ping to ultrasonic sensor. Send out a single ping to the ultrasonic sensor. This only works if automatic (round robin) mode is disabled. A single ping is sent out, and the counter should count the semi-period when it comes in. The counter is reset to make the current value invalid.

    - #### isRangeValid

          public boolean isRangeValid()

      Check if there is a valid range measurement. The ranges are accumulated in a counter that will increment on each edge of the echo (return) signal. If the count is not at least 2, then the range has not yet been measured, and is invalid.
      Returns:
        true if the range is valid

    - #### getRangeInches

          public double getRangeInches()

      Get the range in inches from the ultrasonic sensor. If there is no valid value yet, i.e. at least one measurement hasn't completed, then return 0.
      Returns:
        double Range in inches of the target returned from the ultrasonic sensor.

    - #### getRangeMM

          public double getRangeMM()

      Get the range in millimeters from the ultrasonic sensor. If there is no valid value yet, i.e. at least one measurement hasn't completed, then return 0.
      Returns:
        double Range in millimeters of the target returned by the ultrasonic sensor.

    - #### setPIDSourceType

          public void setPIDSourceType(PIDSourceType pidSource)

      Description copied from interface: `PIDSource`
      Set which parameter of the device you are using as a process control variable.
      Specified by:
        `setPIDSourceType` in interface `PIDSource`
      Parameters:
        `pidSource` - An enum to select the parameter.

    - #### getPIDSourceType

          public PIDSourceType getPIDSourceType()

      Description copied from interface: `PIDSource`
      Get which parameter of the device you are using as a process control variable.
      Specified by:
        `getPIDSourceType` in interface `PIDSource`
      Returns:
        the currently selected PID source parameter

    - #### pidGet

          public double pidGet()

      Get the range in the current DistanceUnit for the PIDSource base object.
      Specified by:
        `pidGet` in interface `PIDSource`
      Returns:
        The range in DistanceUnit

    - #### setDistanceUnits

          public void setDistanceUnits(Ultrasonic.Unit units)

      Set the current DistanceUnit that should be used for the PIDSource base object.
      Parameters:
        `units` - The DistanceUnit that should be used.

    - #### getDistanceUnits

          public Ultrasonic.Unit getDistanceUnits()

      Get the current DistanceUnit that is used for the PIDSource base object.
      Returns:
        The type of DistanceUnit that is being used.

    - #### isEnabled

          public boolean isEnabled()

      Is the ultrasonic enabled.
      Returns:
        true if the ultrasonic is enabled

    - #### setEnabled

          public void setEnabled(boolean enable)

      Set if the ultrasonic is enabled.
      Parameters:
        `enable` - set to true to enable the ultrasonic

    - #### getSmartDashboardType

          public java.lang.String getSmartDashboardType()

      Live Window code, only does anything if live window is activated.
      Specified by:
        `getSmartDashboardType` in interface `Sendable`
      Returns:
        The type of this `Sendable`.

    - #### initTable

          public void initTable(NetworkTable subtable)

      Description copied from interface: `Sendable`
      Initializes a table for this `Sendable` object.
      Specified by:
        `initTable` in interface `Sendable`
      Parameters:
        `subtable` - The table to put the values in.

    - #### updateTable

          public void updateTable()

      Description copied from interface: `LiveWindowSendable`
      Update the table for this sendable object with the latest values.
      Specified by:
        `updateTable` in interface `LiveWindowSendable`

    - #### startLiveWindowMode

          public void startLiveWindowMode()

      Description copied from interface: `LiveWindowSendable`
      Start having this sendable object automatically respond to value changes reflect the value on the table.
      Specified by:
        `startLiveWindowMode` in interface `LiveWindowSendable`

    - #### stopLiveWindowMode

          public void stopLiveWindowMode()

      Description copied from interface: `LiveWindowSendable`
      Stop having this sendable object automatically respond to value changes.
      Specified by:
        `stopLiveWindowMode` in interface `LiveWindowSendable`