API Reference¶

Hardware¶

class XRPLib.motor.Motor(direction_pin: int, speed_pin: int, flip_dir: bool = False)¶

A wrapper class handling direction and power sets for DC motors on the XRP robots

set_effort(effort: float)¶

Sets the effort value of the motor (corresponds to power)

Parameters:: effort (float) – The effort to set the motor to, between -1 and 1

class XRPLib.encoded_motor.EncodedMotor(motor: Motor, encoder: Encoder)¶

classmethod get_default_encoded_motor(index: int = 1)¶

Get one of the default XRP v2 motor instances. These are singletons, so only one instance of each of these will ever exist. Raises an exception if an invalid index is requested.

Parameters:: index (int) – The index of the motor to get; 1 for left, 2 for right, 3 for motor 3, 4 for motor 4

get_position() → float¶

Returns:: The position of the encoded motor, in revolutions, relative to the last time reset was called.
Return type:: float

get_position_counts() → int¶

Returns:: The position of the encoded motor, in encoder counts, relative to the last time reset was called.
Return type:: int

get_speed() → float¶

Returns:: The speed of the motor, in rpm
Return type:: float

reset_encoder_position()¶: Resets the encoder position back to zero.

set_effort(effort: float)¶

Parameters:: effort (float) – The effort to set this motor to, from -1 to 1

set_speed(speed_rpm: float = None)¶

Sets target speed (in rpm) to be maintained passively Call with no parameters or 0 to turn off speed control

Parameters:: target_speed_rpm (float, or None) – The target speed for the motor in rpm, or None

set_speed_controller(new_controller: Controller)¶

Sets a new controller for speed control

Parameters:: new_controller (Controller) – The new Controller for speed control

class XRPLib.motor_group.MotorGroup(*motors: EncodedMotor)¶

A wrapper class for multiple motors, allowing them to be treated as one motor.

Parameters:: motors (tuple<EncodedMotor>) – The motors to add to this group

add_motor(motor: EncodedMotor)¶

Parameters:: motor (EncodedMotor) – The motor to add to this group

get_position() → float¶

Returns:: The average position of all motors in this group, in revolutions, relative to the last time reset was called.
Return type:: float

get_position_counts() → int¶

Returns:: The average position of all motors in this group, in encoder counts, relative to the last time reset was called.
Return type:: int

get_speed() → float¶

Returns:: The average speed of the motors, in rpm
Return type:: float

remove_motor(motor: EncodedMotor)¶

Parameters:: motor (EncodedMotor) – The motor to remove from this group

reset_encoder_position()¶: Resets the encoder position of all motors in this group back to zero.

set_effort(effort: float)¶

Parameters:: effort (float) – The effort to set all motors in this group to, from -1 to 1

set_speed(target_speed_rpm: float = None)¶

Sets target speed (in rpm) to be maintained passively by all motors in this group Call with no parameters to turn off speed control

Parameters:: target_speed_rpm (float, or None) – The target speed for these motors in rpm, or None

set_speed_controller(new_controller)¶

Parameters:: new_controller (Controller) – The new Controller for speed control

class XRPLib.differential_drive.DifferentialDrive(left_motor: EncodedMotor, right_motor: EncodedMotor, imu: IMU = None, wheel_diam: float = 6.0, wheel_track: float = 15.5)¶

A Differential Drive class designed for the XRP two-wheeled drive robot.

Parameters:

leftMotor (EncodedMotor) – The left motor of the drivetrain
rightMotor (EncodedMotor) – The right motor of the drivetrain
imu (IMU) – The IMU of the robot. If None, the robot will not use the IMU for turning or maintaining heading.
wheelDiam (float) – The diameter of the wheels in inches. Defaults to 6 cm.
wheelTrack (float) – The distance between the wheels in inches. Defaults to 15.5 cm.

arcade(straight: float, turn: float)¶

Sets the raw effort of both motors based on the arcade drive scheme

Parameters:

straight (float) – The base effort (Bounded from -1 to 1) used to drive forwards or backwards.
turn (float) – The modifier effort (Bounded from -1 to 1) used to skew robot left (positive) or right (negative).

classmethod get_default_differential_drive()¶: Get the default XRP v2 differential drive instance. This is a singleton, so only one instance of the drivetrain will ever exist.

get_left_encoder_position() → float¶

Returns:: the current position of the left motor’s encoder in cm.
Return type:: float

get_right_encoder_position() → float¶

Returns:: the current position of the right motor’s encoder in cm.
Return type:: float

reset_encoder_position() → None¶: Resets the position of both motors’ encoders to 0

set_effort(left_effort: float, right_effort: float) → None¶

Set the raw effort of both motors individually

Parameters:

leftEffort (float) – The power (Bounded from -1 to 1) to set the left motor to.
rightEffort (float) – The power (Bounded from -1 to 1) to set the right motor to.

set_speed(left_speed: float, right_speed: float) → None¶

Set the speed of both motors individually

Parameters:

leftSpeed (float) – The speed (In Centimeters per Second) to set the left motor to.
rightSpeed (float) – The speed (In Centimeters per Second) to set the right motor to.

stop() → None¶: Stops both drivetrain motors

straight(distance: float, max_effort: float = 0.5, timeout: float = None, main_controller: Controller = None, secondary_controller: Controller = None) → bool¶

Go forward the specified distance in centimeters, and exit function when distance has been reached. Max_effort is bounded from -1 (reverse at full speed) to 1 (forward at full speed)

Parameters:

distance (float) – The distance for the robot to travel (In Centimeters)
max_effort (float) – The max effort for which the robot to travel (Bounded from -1 to 1). Default is half effort forward
timeout (float) – The amount of time before the robot stops trying to move forward and continues to the next step (In Seconds)
main_controller (Controller) – The main controller, for handling the distance driven forwards
secondary_controller (Controller) – The secondary controller, for correcting heading error that may result during the drive.

Returns:

if the distance was reached before the timeout

Return type:

bool

turn(turn_degrees: float, max_effort: float = 0.5, timeout: float = None, main_controller: Controller = None, secondary_controller: Controller = None, use_imu: bool = True) → bool¶

Turn the robot some relative heading given in turnDegrees, and exit function when the robot has reached that heading. effort is bounded from -1 (turn counterclockwise the relative heading at full speed) to 1 (turn clockwise the relative heading at full speed) Uses the IMU to determine the heading of the robot and P control for the motor controller.

Parameters:

turnDegrees (float) – The number of angle for the robot to turn (In Degrees)
max_effort (float) – The max speed for which the robot to travel (Bounded from -1 to 1)
timeout (float) – The amount of time before the robot stops trying to turn and continues to the next step (In Seconds)
main_controller (Controller) – The main controller, for handling the angle turned
secondary_controller (Controller) – The secondary controller, for maintaining position during the turn by controlling the encoder count difference
use_imu (bool) – A boolean flag that changes if the main controller bases its movement off of the imu (True) or the encoders (False)

Returns:

if the distance was reached before the timeout

Return type:

bool

class XRPLib.servo.Servo(signal_pin: int)¶

A simple class for interacting with a servo through PWM

Parameters:: signal_pin (int) – The pin the servo is connected to

free()¶: Allows the servo to spin freely without holding position

classmethod get_default_servo(index: int)¶

Gets one of the default XRP v2 servo instances. These are singletons, so only one instance of each servo will ever exist. Raises an exception if an invalid index is requested.

Parameters:: index (int) – The index of the servo to get (1 or 2)

set_angle(degrees: float)¶: Sets the angle of the servo :param degrees: The angle to set the servo to [0,200] :ptype degrees: float

Sensors¶

class XRPLib.encoder.Encoder(index, encAPin, encBPin)¶

Uses the on board PIO State Machine to keep track of encoder positions. Only 4 encoders can be instantiated this way.

Parameters:

index (int) – The index of the state machine to be used, indexed 0-3.
encAPin (int) – The pin the left reflectance sensor is connected to
encBPin (int) – The pin the right reflectance sensor is connected to

get_position()¶

Returns:: The position of the encoded motor, in revolutions, relative to the last time reset was called.
Return type:: float

get_position_counts()¶

Returns:: The position of the encoded motor, in counts, relative to the last time reset was called.
Return type:: int

reset_encoder_position()¶: Resets the encoder position to 0

resolution = 585.0¶

class XRPLib.imu.IMU(scl_pin: int, sda_pin: int, addr)¶

acc_rate(value=None)¶: Set the accelerometer rate in Hz. The rate can be: ‘0Hz’, ‘12.5Hz’, ‘26Hz’, ‘52Hz’, ‘104Hz’, ‘208Hz’, ‘416Hz’, ‘833Hz’, ‘1660Hz’, ‘3330Hz’, ‘6660Hz’ Pass in no parameters to retrieve the current value

acc_scale(value=None)¶: Set the accelerometer scale in g. The scale can be: ‘2g’, ‘4g’, ‘8g’, or ‘16g’ Pass in no parameters to retrieve the current value

calibrate(calibration_time: float = 1, vertical_axis: int = 2)¶

Collect readings for [calibration_time] seconds and calibrate the IMU based on those readings Do not move the robot during this time Assumes the board to be parallel to the ground. Please use the vertical_axis parameter if that is not correct

Parameters:

calibration_time (float) – The time in seconds to collect readings for
vertical_axis (int) – The axis that is vertical. 0 for X, 1 for Y, 2 for Z

get_acc_gyro_rates()¶: Get the accelerometer and gyroscope values in mg and mdps in the form of a 2D array. The first row is the acceleration values, the second row is the gyro values. The order of the values is x, y, z.

get_acc_rates()¶

Returns:: the list of readings from the Accelerometer, in mg. The order of the values is x, y, z.
Return type:: list<int>

get_acc_x()¶

Returns:: The current reading for the accelerometer’s X-axis, in mg
Return type:: int

get_acc_y()¶

Returns:: The current reading for the accelerometer’s Y-axis, in mg
Return type:: int

get_acc_z()¶

Returns:: The current reading for the accelerometer’s Z-axis, in mg
Return type:: int

classmethod get_default_imu()¶: Get the default XRP v2 IMU instance. This is a singleton, so only one instance of the drivetrain will ever exist.

get_gyro_rates()¶: Retrieves the array of readings from the Gyroscope, in mdps The order of the values is x, y, z.

get_gyro_x_rate()¶: Individual axis read for the Gyroscope’s X-axis, in mdps

get_gyro_y_rate()¶: Individual axis read for the Gyroscope’s Y-axis, in mdps

get_gyro_z_rate()¶: Individual axis read for the Gyroscope’s Z-axis, in mdps

get_heading()¶

Get’s the heading of the IMU, but bounded between [0, 360)

Returns:: The heading of the IMU in degrees, bound between [0, 360)
Return type:: float

get_pitch()¶

Get the pitch of the IMU in degrees. Unbounded in range

Returns:: The pitch of the IMU in degrees
Return type:: float

get_roll()¶

Get the roll of the IMU in degrees. Unbounded in range

Returns:: The roll of the IMU in degrees
Return type:: float

get_yaw()¶

Get the yaw (heading) of the IMU in degrees. Unbounded in range

Returns:: The yaw (heading) of the IMU in degrees
Return type:: float

gyro_rate(value=None)¶: Set the gyroscope rate in Hz. The rate can be: ‘0Hz’, ‘12.5Hz’, ‘26Hz’, ‘52Hz’, ‘104Hz’, ‘208Hz’, ‘416Hz’, ‘833Hz’, ‘1660Hz’, ‘3330Hz’, ‘6660Hz’ Pass in no parameters to retrieve the current value

gyro_scale(value=None)¶: Set the gyroscope scale in dps. The scale can be: ‘125’, ‘250’, ‘500’, ‘1000’, or ‘2000’ Pass in no parameters to retrieve the current value

is_connected()¶

Checks whether the IMU is connected

Returns:: True if WHO_AM_I value is correct, otherwise False
Return type:: bool

reset(wait_for_reset=True, wait_timeout_ms=100)¶

Resets the IMU, and restores all registers to their default values

Parameters:

wait_for_reset (bool) – Whether to wait for reset to complete
wait_timeout_ms (int) – Timeout in milliseconds when waiting for reset

Returns:

False if timeout occurred, otherwise True

Return type:

bool

reset_pitch()¶: Reset the pitch to 0

reset_roll()¶: Reset the roll to 0

reset_yaw()¶: Reset the yaw (heading) to 0

set_pitch(pitch)¶

Set the pitch to a specific angle in degrees

Parameters:: pitch (float) – The pitch to set the IMU to

set_roll(roll)¶

Set the roll to a specific angle in degrees

Parameters:: roll (float) – The roll to set the IMU to

set_yaw(yaw)¶

Set the yaw (heading) to a specific angle in degrees

Parameters:: yaw (float) – The yaw (heading) to set the IMU to

temperature()¶

Read the temperature of the LSM6DSO in degrees Celsius

Returns:: The temperature of the LSM6DSO in degrees Celsius
Return type:: float

class XRPLib.rangefinder.Rangefinder(trigger_pin: int, echo_pin: int, timeout_us: int = 500 * 2 * 30)¶

A basic class for using the HC-SR04 Ultrasonic Rangefinder. The sensor range is between 2cm and 4m. Timeouts will return a MAX_VALUE (65535) instead of raising an exception.

Parameters:

trigger_pin (int) – The number of the pin on the microcontroller that’s connected to the Trig pin on the HC-SR04.
echo_pin (int) – The number of the pin on the microcontroller that’s connected to the Echo pin on the HC-SR04.
timeout_us (int) – Max microseconds seconds to wait for a response from the sensor before assuming it isn’t going to answer. By default set to 30,000 us (0.03 s)

distance() → float¶: Get the distance in centimeters by measuring the echo pulse time

classmethod get_default_rangefinder()¶: Get the default XRP v2 rangefinder instance. This is a singleton, so only one instance of the rangefinder will ever exist.

class XRPLib.reflectance.Reflectance(leftPin: int, rightPin: int)¶

Implements for a reflectance sensor using the built in 12-bit ADC. Reads from analog in and converts to a float from 0 (white) to 1 (black)

Parameters:

leftPin (int) – The pin the left reflectance sensor is connected to
rightPin (int) – The pin the right reflectance sensor is connected to

classmethod get_default_reflectance()¶: Get the default XRP v2 reflectance sensor instance. This is a singleton, so only one instance of the reflectance sensor will ever exist.

get_left() → float¶: Gets the the reflectance of the left reflectance sensor : return: The reflectance ranging from 0 (white) to 1 (black) : rtype: float

get_right() → float¶: Gets the the reflectance of the right reflectance sensor : return: The reflectance ranging from 0 (white) to 1 (black) : rtype: float

Miscellaneous¶

class XRPLib.board.Board(vin_pin: int, button_pin: int)¶

Implements for extra features on the XRP v2 board. Handles the on/off switch, button, and LED.

Parameters:

vin_pin (int) – The pin the on/off switch is connected to
button_pin (int) – The pin the button is connected to

are_motors_powered() → bool¶

Returns:: Returns true if the batteries are connected and powering the motors, false otherwise
Rytpe:: bool

classmethod get_default_board()¶: Get the default board instance. This is a singleton, so only one instance of the board will ever exist.

is_button_pressed() → bool¶

Returns the state of the button

Returns:: True if the button is pressed, False otherwise
Return type:: bool

led_blink(frequency: int = 0)¶

Blinks the LED at a given frequency. If the frequency is 0, the LED will stop blinking.

Parameters:: frequency (int) – The frequency to blink the LED at (in Hz)

led_off()¶: Turns the LED off Stops the blinking timer if it is running

led_on()¶: Turns the LED on Stops the blinking timer if it is running

wait_for_button()¶: Halts the program until the button is pressed

class XRPLib.controller.Controller¶

An abstract class to be entended to demonstrate different types of control. A PID subclass has also been provided

clear_history()¶: Clears all past data, such as integral sums or any other previous data

is_done() → bool¶

Returns:: If the controller has reached or settled at its desired value
Return type:: bool

update(input) → float¶

Handle a new update of this control loop given an effected input.

Parameters:: error (float) – The input to this controller for a given update. Usually an error or some other correctable value
Returns:: The system output from the controller, to be used as an effort value or for any other purpose
Return type:: float

class XRPLib.pid.PID(kp=1.0, ki=0.0, kd=0.0, min_output=0.0, max_output=1.0, max_derivative=None, max_integral=None, tolerance=0.1, tolerance_count=1)¶

Bases: Controller

Parameters:

kp – proportional gain
ki – integral gain
kd – derivative gain
min_output – minimum output
max_output – maximum output
max_derivative – maximum derivative (change per second)
max_integral – maximum integral windup allowed (will cap integral at this value)
tolerance – tolerance for exit condition
tolerance_count – number of times the error needs to be within tolerance for is_done to return True

clear_history()¶: Clears all past data, such as integral sums or any other previous data

is_done() → bool¶

Returns:: if error is within tolerance for numTimesInTolerance consecutive times, or timed out
Return type:: bool

update(error: float) → float¶

Handle a new update of this PID loop given an error.

Parameters:: error (float) – The error of the system being controlled by this PID controller
Returns:: The system output from the controller, to be used as an effort value or for any other purpose
Return type:: float

class XRPLib.timeout.Timeout(timeout)¶

Starts a timer that will expire after the given timeout.

Parameters:: timeout (float) – The timeout, in seconds

is_done()¶

Returns:: True if the timeout has expired, False otherwise

class XRPLib.webserver.Webserver¶

Host a webserver for the XRP v2 Robot; Register your own callbacks and log your own data to the webserver using the methods below.

add_button(button_name: str, function)¶

Register a custom button to be displayed on the webserver

Parameters:

button_name (str) – The label for the button as it will be displayed, must be unique
function (function) – The function to be called when the button is pressed

connect_to_network(ssid: str = None, password: str = None, timeout=10)¶

Connect to a wifi network with the given ssid and password. If the connection fails, the board will disconnect from the network and return.

Parameters:

ssid (str, optional) – The ssid of the network, defaults to value from secrets.json
password (str, optional) – The password of the network, defaults to value from secrets.json
timeout (int, optional) – The amount of time to wait for the connection to succeed, defaults to 10

classmethod get_default_webserver()¶: Get the default webserver instance. This is a singleton, so only one instance of the webserver will ever exist.

log_data(label: str, data)¶

Register a custom label to be displayed on the webserver

Parameters:

label (str) – The label as it will be displayed, must be unique
data (Any (converted to string)) – The data to be displayed

registerBackwardButton(function)¶

Assign a function to the backward button

Parameters:: function (function) – The function to be called when the button is pressed

registerForwardButton(function)¶

Assign a function to the forward button

Parameters:: function (function) – The function to be called when the button is pressed

registerLeftButton(function)¶

Assign a function to the left button

Parameters:: function (function) – The function to be called when the button is pressed

registerRightButton(function)¶

Assign a function to the right button

Parameters:: function (function) – The function to be called when the button is pressed

registerStopButton(function)¶

Assign a function to the stop

Parameters:: function (function) – The function to be called when the button is pressed

start_network(ssid: str = None, robot_id: int = None, password: str = None)¶

Open an access point from the XRP board to be used as a captive host. The default network information can be set in secrets.json

Parameters:

ssid (str, optional) – The ssid of the access point, defaults to value from secrets.json
robot_id (int, optional) – Replaces “{robot_id}” in ssid, defaults to value from secrets.json
password (str, optional) – The password of the access point, defaults to value from secrets.json

start_server()¶

Begin the webserver in either access point or bridge mode. The IP is printed to the console.

Preconditions: Either start_network or connect_to_network must be called before this method.

stop_server()¶: Shuts off the webserver and network and stops handling requests