Package ch.hevs.kart

Interface Kart


public interface Kart

Kart interface.

Once connected, the kart interface allows to manipulate the kart developed during the first year's summer school remotely simply by calling methods on a kart instance. There is no need to care about the Bluetooth communication with the kart at all, everything including retransmissions and error handling is implemented.

  • Method Details

    • setup

      @NonNull KartSetup setup()

      Returns a reference to the kart setup.

      Note that when you change settings on the kart setup object, those are applied automatically and immediately to the kart, so there is no need to call a setter method in order to commit kart setup changes.

      Returns:
      Kart setup object for this kart instance.
    • reset

      void reset()

      Resets the kart.

      Note that the method exits immediately after having communicated the command to the kart - the initialization of the steering wheel system will take a moment.

    • setDriveSpeed

      void setDriveSpeed(int speed)

      Sets the drive speed (throttle) to the given absolute value.

      Valid values are [-15, 15], whereas negative values make the kart driving backward and positive values forward.

      Parameters:
      speed - Absolute drive speed (throttle).
    • getDriveSpeed

      int getDriveSpeed()

      Returns the actual absolute drive speed (throttle) in the range [-15, 15].

      Returns:
      Actual absolute drive speed.
    • setDriveSpeedNormalized

      void setDriveSpeedNormalized(double speed)

      Sets the drive speed (throttle) to the given normalized value.

      Valid values are [-1.0, 1.0], whereas negative values make the kart driving backward and positive values forward.

      Parameters:
      speed - Normalized drive speed (throttle).
    • getDriveSpeedNormalized

      double getDriveSpeedNormalized()

      Returns the actual normalized drive speed (throttle) in the range [-1.0, 1.0].

      Returns:
      Actual normalized drive speed.
    • increaseDriveSpeed

      void increaseDriveSpeed()

      Increases the drive speed (throttle) by the smallest possible amount.

    • decreaseDriveSpeed

      void decreaseDriveSpeed()

      Decreases the drive speed (throttle) by the smallest possible amount.

    • setSteeringTargetPosition

      void setSteeringTargetPosition(int position)

      Sets the steering target position on the kart to the given absolute value.

      Note that this is the set point of the steering control system on the kart. It will take time for the steering system to actually reach this position. The position is limited to the range from 0 to the maximal steering position in the kart setup.

      Parameters:
      position - Absolute target steering position.
    • getSteeringTargetPosition

      int getSteeringTargetPosition()

      Returns the actual absolute steering target position.

      This is not the steering position the kart's steering is actually at, it is the target position the kart's steering system should move towards.

      Returns:
      Absolute target steering position.
    • setSteeringTargetPositionNormalized

      void setSteeringTargetPositionNormalized(double position)

      Sets the steering target position on the kart to the given normalized value.

      Note that this is the set target value of the steering control system on the kart. It will take time for the steering system to actually reach the given position. The position is limited to [-1, 1] whereas -1 and 1 are the end positions on each side.

      Parameters:
      position - Normalized steering target position.
    • getSteeringTargetPositionNormalized

      double getSteeringTargetPositionNormalized()

      Returns the actual normalized steering target position.

      This is not the steering position the kart's steering is actually at, it is the target position the kart's steering system should move towards.

      Returns:
      Normalized steering target position set point [-1.0, 1.0].
    • turnSteeringTargetPositionBy

      void turnSteeringTargetPositionBy(int amount)

      Turns the steering target position by the given absolute number of steps.

      The position is limited to the left and right end positions. Positive and negative numbers can be passed to this method whereas negative numbers signal the opposite direction as positive ones.

      Parameters:
      amount - Absolute number of steps to turn.
    • turnSteeringTargetPositionNormalizedBy

      void turnSteeringTargetPositionNormalizedBy(double amount)

      Turns the steering target position by the given normalized amount.

      The position is limited to the left and right end positions. Positive and negative numbers can be passed to this method whereas negative numbers signal the opposite direction as positive ones.

      Parameters:
      amount - Normalized amount to turn.
    • getSteeringPosition

      int getSteeringPosition()

      Returns the actual absolute steering position (It is the actual position of the steering system, not the target value).

      This is the absolute position (in steps) the steering system actually is at and does not necessarily matches the set point - the system needs time to reach the requested positions.

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.steeringPositionChanged(Kart, int)

      Returns:
      Actual absolute steering position.
    • getSteeringPositionNormalized

      double getSteeringPositionNormalized()

      Returns the actual normalized steering position (not the set point) in the range [-1.0, 1.0].

      This is the absolute position (in steps) the steering system actually is at and does not necessarily matches the set point - the system needs time to reach the requested positions.

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.steeringPositionChangedNormalized(Kart, double)

      Returns:
      Actual normalized steering position from [-1.0, 1.0].
    • isSteeringTargetPositionReached

      boolean isSteeringTargetPositionReached()

      Returns true if the kart has reached the target steering position, false otherwise.

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.steeringTargetPositionReachedChanged(Kart, boolean)

      Returns:
      True if the kart has reached the target steering position, false otherwise.
    • getBatteryVoltage

      double getBatteryVoltage()

      Returns the battery voltage in volts [V].

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.batteryVoltageChanged(Kart, double)

      Returns:
      Battery voltage.
    • getBatteryLevel

      double getBatteryLevel()

      Returns the battery level from 0.0 (empty) to 1.0 (full).

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.batteryLevelChanged(Kart, double)

      Returns:
      Battery level [0.0, 1.0].
    • getCurrent

      default double getCurrent()

      Returns the current in amperes [A].

      Note that not all Kart models do support this, in that case -1 is returned.

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.currentChanged(Kart, double)

      Returns:
      Current.
    • getUltrasonicRangerDistance

      default double getUltrasonicRangerDistance()

      Returns the current distance measured by the ultrasonic ranger.

      Note that not all Kart models do support this, in that case -1 is returned.

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.ultrasonicRangerDistanceChanged(Kart, double)

      Returns:
      Distance in m.
    • getHallSensorCount

      int getHallSensorCount(int index)

      Returns the current hall pulse count if the given hall sensor (1 or 2).

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.hallSensorCountChanged(Kart, int, int)

      Parameters:
      index - Index of the hall sensor [1..2].
      Returns:
      Hall sensor pulse count.
      Throws:
      IndexOutOfBoundsException - If the hall sensor at the given index does not exist.
    • getDigitalInput

      default boolean getDigitalInput(int index)

      Returns the current state of the digital input bit at the given index [0..15].

      Note that not all Kart models do support this, in that case an IndexOutOfBoundsException is thrown.

      Note that this function will just return the latest value received from the kart, it a new value is received, this event is send to all registered listeners via the method KartListener.digitalInputChanged(Kart, int, boolean)

      Parameters:
      index - Index of the digital input [0..15]
      Returns:
      Actual state of the digital input.
    • setLedState

      void setLedState(int index, boolean state)

      Sets the LED or digital output at the give index to the given value (true=on, false=off).

      Parameters:
      index - LED index.
      state - If true the LED is set on, if false the LED is set off.
      Throws:
      IndexOutOfBoundsException - If LED index is out of bounds.
    • getLedState

      boolean getLedState(int index)

      Gets the status if the LED/digital output at the given index.

      Parameters:
      index - LED index.
      Returns:
      True if the LED is on (or blinking), false if the LED is off.
      Throws:
      IndexOutOfBoundsException - If LED index is out of bounds.
    • toggleLed

      void toggleLed(int index)

      Toggles the LED/digital output at the given index. Note that this will not work if the LED is blinking.

      Parameters:
      index - LED index.
      Throws:
      IndexOutOfBoundsException - If LED index is out of bounds.
    • blinkLed

      default void blinkLed(int index, int interval)

      Blinks the LED/digital output at the given index with the given interval in milliseconds.

      Parameters:
      index - LED index.
      interval - Blink interval in milliseconds.
      Throws:
      IndexOutOfBoundsException - If LED index is out of bounds.
    • setControlRegister

      void setControlRegister(int address, int value)

      Sets the control register to the given value.

      When you access the control registers, you really new to know what you are doing! Additionally there are multiple Kart models with different register models, so if you access the registers directly, your Kart control application will not work for all karts anymore. Have a look at KartRegisters for an overview off all available registers.

      Note that control registers can hold only 16 bit values, so not the whole range of Java's integer values is applicable.

      Parameters:
      address - The address of the control register to set.
      value - The value to set for the register.
    • getControlRegisterSigned

      int getControlRegisterSigned(int address)

      Returns the actual value of the control register.

      When you access the control registers, you really new to know what you are doing! Additionally there are multiple Kart models with different register models, so if you access the registers directly, your Kart control application will not work for all karts anymore. Have a look at KartRegisters for an overview off all available registers.

      The value is converted to a signed int - negative values are possible. If you like to read the register value unsigned, use the getControlRegisterUnsigned(int) method.

      Parameters:
      address - The address of the control register to read.
      Returns:
      The actual signed register value.
    • getControlRegisterUnsigned

      int getControlRegisterUnsigned(int address)

      Returns the actual value of the control register.

      When you access the control registers, you really new to know what you are doing! Additionally there are multiple Kart models with different register models, so if you access the registers directly, your Kart control application will not work for all karts anymore. Have a look at KartRegisters for an overview off all available registers.

      The value is converted to an unsigned int - only positive values are possible to avoid problems with big negative numbers. If you like to read the register value signed, use the getControlRegisterSigned(int) method.

      Parameters:
      address - The address of the control register to read.
      Returns:
      The actual UNSIGNED register value.
    • getStatusRegisterSigned

      int getStatusRegisterSigned(int address)
      Returns the actual value of the status register.

      When you access the control registers, you really new to know what you are doing! Additionally there are multiple Kart models with different register models, so if you access the registers directly, your Kart control application will not work for all karts anymore. Have a look at KartRegisters for an overview off all available registers.

      The value is converted to a signed int - negative values are possible. If you like to read the register value unsigned, use the getStatusRegisterUnsigned(int) method.

      Parameters:
      address - The address of the status register to read.
      Returns:
      The actual SIGNED register value.
    • getStatusRegisterUnsigned

      int getStatusRegisterUnsigned(int address)

      Returns the actual value of the status register.

      When you access the control registers, you really new to know what you are doing! Additionally there are multiple Kart models with different register models, so if you access the registers directly, your Kart control application will not work for all karts anymore. Have a look at KartRegisters for an overview off all available registers.

      The value is converted to an unsigned int - only positive values are possible to avoid problems with big negative numbers. If you like to read the register value signed, use the getStatusRegisterSigned(int) method.

      Parameters:
      address - The address of the status register to read.
      Returns:
      The actual UNSIGNED register value.
    • addKartListener

      void addKartListener(@NonNull KartListener listener)

      Adds the passed kart listener to the kart.

      The listener will be notified about the changes of values (registers) on the kart after it has been registered using this method.

      Parameters:
      listener - Reference to the object implementing the kart listener interface.
      Throws:
      NullPointerException - If the passed listened parameter is null.
    • removeKartListener

      void removeKartListener(@NonNull KartListener listener)

      Removes the kart listener.

      Parameters:
      listener - Reference to the object implementing the kart listener interface to remove.
      Throws:
      NullPointerException - If the passed listened parameter is null.
    • getSequencer

      @Nullable KartSequencer getSequencer()
      Returns a KartSequencer object if the Kart supports playing sequences, otherwise it returns null.
      Returns:
      KartSequencer object or null.