Update sphinx comments and remove all but 4 warnings

Author: ksiegall

XRPLib/board.py

@@ -14,6 +14,15 @@ def get_default_board(cls):
         return cls._DEFAULT_BOARD_INSTANCE
 
     def __init__(self, vin_pin:int, button_pin:int):
+        """
+        Implements for extra features on the XRP v2 board. Handles the on/off switch, button, and LED.
+
+        :param vin_pin: The pin the on/off switch is connected to
+        :type vin_pin: int
+        :param button_pin: The pin the button is connected to
+        :type button_pin: int
+        """
+
         self.on_switch = ADC(Pin(vin_pin))
 
         self.button = Pin(button_pin, Pin.IN, Pin.PULL_UP)
@@ -28,8 +37,8 @@ def __init__(self, vin_pin:int, button_pin:int):
 
     def are_motors_powered(self) -> bool:
         """
-        : return: Returns true if the batteries are connected and powering the motors, false otherwise
-        : rytpe: bool
+        :return: Returns true if the batteries are connected and powering the motors, false otherwise
+        :rytpe: bool
         """
         return self.on_switch.read_u16() > 20000
 
@@ -39,10 +48,10 @@ def set_button_callback(self, trigger, callback):
         Follow the link for more information on how to write an Interrupt Service Routine (ISR). 
         https://docs.micropython.org/en/latest/reference/isr_rules.html
 
-        : param trigger: The type of trigger to be used for the interrupt
-        : type trigger: Pin.IRQ_RISING | Pin.IRQ_FALLING
-        : param callback: The function to be called when the interrupt is triggered
-        : type callback: function | None
+        :param trigger: The type of trigger to be used for the interrupt
+        :type trigger: Pin.IRQ_RISING | Pin.IRQ_FALLING
+        :param callback: The function to be called when the interrupt is triggered
+        :type callback: function | None
         """
         self.button_callback = callback
         self.button.irq(trigger=trigger, handler=self.button_callback)
@@ -51,8 +60,8 @@ def is_button_pressed(self) -> bool:
         """
         Returns the state of the button
 
-        : return: True if the button is pressed, False otherwise
-        : rtype: bool
+        :return: True if the button is pressed, False otherwise
+        :rtype: bool
         """
         return not self.button.value()
 
@@ -78,8 +87,8 @@ def led_blink(self, frequency: int):
         """
         Blinks the LED at a given frequency
 
-        : param frequency: The frequency to blink the LED at (in Hz)
-        : type frequency: int
+        :param frequency: The frequency to blink the LED at (in Hz)
+        :type frequency: int
         """
         if self.is_led_blinking:
             # disable the old timer so we can reinitialize it

XRPLib/differential_drive.py

@@ -27,6 +27,21 @@ def get_default_differential_drive(cls):
         return cls._DEFAULT_DIFFERENTIAL_DRIVE_INSTANCE
 
     def __init__(self, left_motor: EncodedMotor, right_motor: EncodedMotor, imu: IMU | None = None, wheel_diam:float = 6.0, wheel_track:float = 13.5):
+        """
+        A Differential Drive class designed for the XRP two-wheeled drive robot.
+
+        :param leftMotor: The left motor of the drivetrain
+        :type leftMotor: EncodedMotor
+        :param rightMotor: The right motor of the drivetrain
+        :type rightMotor: EncodedMotor
+        :param imu: The IMU of the robot. If None, the robot will not use the IMU for turning or maintaining heading.
+        :type imu: IMU
+        :param wheelDiam: The diameter of the wheels in inches. Defaults to 6 inches.
+        :type wheelDiam: float
+        :param wheelTrack: The distance between the wheels in inches. Defaults to 13.5 inches.
+        :type wheelTrack: float
+        """
+        
         self.left_motor = left_motor
         self.right_motor = right_motor
         self.imu = imu
@@ -38,10 +53,10 @@ def set_effort(self, left_effort: float, right_effort: float) -> None:
         """
         Set the raw effort of both motors individually
 
-        : param leftEffort: The power (Bounded from -1 to 1) to set the left motor to.
-        : type leftEffort: float
-        : param rightEffort: The power (Bounded from -1 to 1) to set the right motor to.
-        : type rightEffort: float
+        :param leftEffort: The power (Bounded from -1 to 1) to set the left motor to.
+        :type leftEffort: float
+        :param rightEffort: The power (Bounded from -1 to 1) to set the right motor to.
+        :type rightEffort: float
         """
 
         self.left_motor.set_effort(left_effort)
@@ -51,10 +66,10 @@ def set_speed(self, left_speed: float, right_speed: float) -> None:
         """
         Set the speed of both motors individually
 
-        : param leftSpeed: The speed (In Centimeters per Second) to set the left motor to.
-        : type leftSpeed: float
-        : param rightSpeed: The speed (In Centimeters per Second) to set the right motor to.
-        : type rightSpeed: float
+        :param leftSpeed: The speed (In Centimeters per Second) to set the left motor to.
+        :type leftSpeed: float
+        :param rightSpeed: The speed (In Centimeters per Second) to set the right motor to.
+        :type rightSpeed: float
         """
         # Convert from cm/s to RPM
         cmpsToRPM = 60 / (math.pi * self.wheel_diam)
@@ -80,13 +95,15 @@ def reset_encoder_position(self) -> None:
 
     def get_left_encoder_position(self) -> float:
         """
-        Return the current position of the left motor's encoder in revolutions.
+        :return: the current position of the left motor's encoder in revolutions.
+        :rtype: float
         """
         return self.left_motor.get_position()
 
     def get_right_encoder_position(self) -> float:
         """
-        Return the current position of the right motor's encoder in revolutions.
+        :return: the current position of the right motor's encoder in revolutions.
+        :rtype: float
         """
         return self.right_motor.get_position()
 
@@ -96,18 +113,18 @@ def straight(self, distance: float, max_effort: float = 0.5, timeout: float = No
         Go forward the specified distance in centimeters, and exit function when distance has been reached.
         Speed is bounded from -1 (reverse at full speed) to 1 (forward at full speed)
 
-        : param distance: The distance for the robot to travel (In Centimeters)
-        : type distance: float
-        : param speed: The speed for which the robot to travel (Bounded from -1 to 1). Default is half speed forward
-        : type speed: float
-        : param timeout: The amount of time before the robot stops trying to move forward and continues to the next step (In Seconds)
-        : type timeout: float
-        : param main_controller: The main controller, for handling the distance driven forwards
-        : type main_controller: Controller
-        : param secondary_controller: The secondary controller, for correcting heading error that may result during the drive.
-        : type secondary_controller: Controller
-        : return: if the distance was reached before the timeout
-        : rtype: bool
+        :param distance: The distance for the robot to travel (In Centimeters)
+        :type distance: float
+        :param speed: The speed for which the robot to travel (Bounded from -1 to 1). Default is half speed forward
+        :type speed: float
+        :param timeout: The amount of time before the robot stops trying to move forward and continues to the next step (In Seconds)
+        :type timeout: float
+        :param main_controller: The main controller, for handling the distance driven forwards
+        :type main_controller: Controller
+        :param secondary_controller: The secondary controller, for correcting heading error that may result during the drive.
+        :type secondary_controller: Controller
+        :return: if the distance was reached before the timeout
+        :rtype: bool
         """
         # ensure distance is always positive while speed could be either positive or negative
         if distance < 0:
@@ -181,19 +198,19 @@ def turn(self, turn_degrees: float, max_effort: float = 0.5, timeout: float = No
         Speed 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.
 
-        : param turnDegrees: The number of angle for the robot to turn (In Degrees)
-        : type turnDegrees: float
-        : param speed: The speed for which the robot to travel (Bounded from -1 to 1). Default is half speed forward.
-        : type speed: float
-        : param timeout: The amount of time before the robot stops trying to turn and continues to the next step (In Seconds)
-        : type timeout: float
-        : param main_controller: The main controller, for handling the angle turned
-        : type main_controller: Controller
-        : param secondary_controller: The secondary controller, for maintaining position during the turn by controlling the encoder count difference
-        : type secondary_controller: Controller
-        : param use_imu: A boolean flag that changes if the main controller bases it's movement off of 
-        : return: if the distance was reached before the timeout
-        : rtype: bool
+        :param turnDegrees: The number of angle for the robot to turn (In Degrees)
+        :type turnDegrees: float
+        :param speed: The speed for which the robot to travel (Bounded from -1 to 1). Default is half speed forward.
+        :type speed: float
+        :param timeout: The amount of time before the robot stops trying to turn and continues to the next step (In Seconds)
+        :type timeout: float
+        :param main_controller: The main controller, for handling the angle turned
+        :type main_controller: Controller
+        :param secondary_controller: The secondary controller, for maintaining position during the turn by controlling the encoder count difference
+        :type secondary_controller: Controller
+        :param use_imu: A boolean flag that changes if the main controller bases it's movement off of 
+        :return: if the distance was reached before the timeout
+        :rtype: bool
         """
 
         if max_effort < 0:

XRPLib/encoded_motor.py

@@ -12,18 +12,16 @@ class EncodedMotor:
     _DEFAULT_MOTOR_FOUR_INSTANCE = None
 
     @classmethod
-    def get_default_encoded_motor(cls, index:int = 0):
+    def get_default_encoded_motor(cls, 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.
-        Motor indexes:
-            0 - Left Motor
-            1 - Right Motor
-            2 - Motor 3
-            3 - Motor 4
-        Left Motor is the default, so if no index is specified, the left motor will be returned.
+        Left Motor is the default, so if no index (or an invalid index) is specified, the left motor will be returned.
+
+        :param index: The index of the motor to get; 1 for left, 2 for right, 3 for motor 3, 4 for motor 4
+        :type index: int
         """
 
-        if index == 1:
+        if index == 2:
             if cls._DEFAULT_RIGHT_MOTOR_INSTANCE is None:
                 cls._DEFAULT_RIGHT_MOTOR_INSTANCE = cls(
                     Motor(14, 15),
@@ -37,7 +35,7 @@ def get_default_encoded_motor(cls, index:int = 0):
                     Encoder(2, 0, 1)
                 )
             motor = cls._DEFAULT_MOTOR_THREE_INSTANCE
-        elif index == 3:
+        elif index == 4:
             if cls._DEFAULT_MOTOR_FOUR_INSTANCE is None:
                 cls._DEFAULT_MOTOR_FOUR_INSTANCE = cls(
                     Motor(10, 11, flip_dir=True),
@@ -73,15 +71,15 @@ def __init__(self, motor: Motor, encoder: Encoder):
 
     def set_effort(self, effort: float):
         """
-        : param effort: The effort to set this motor to, from -1 to 1
-        : type effort: float
+        :param effort: The effort to set this motor to, from -1 to 1
+        :type effort: float
         """
         self._motor.set_effort(effort)
 
     def get_position(self) -> float:
         """
-        : return: The position of the encoded motor, in revolutions, relative to the last time reset was called.
-        : rtype: float
+        :return: The position of the encoded motor, in revolutions, relative to the last time reset was called.
+        :rtype: float
         """
         if self._motor.flip_dir:
             invert = -1
@@ -91,8 +89,8 @@ def get_position(self) -> float:
 
     def get_position_ticks(self) -> int:
         """
-        : return: The position of the encoded motor, in encoder ticks, relative to the last time reset was called.
-        : rtype: int
+        :return: The position of the encoded motor, in encoder ticks, relative to the last time reset was called.
+        :rtype: int
         """
         if self._motor.flip_dir:
             invert = -1
@@ -108,10 +106,8 @@ def reset_encoder_position(self):
 
     def get_speed(self) -> float:
         """
-        Gets the speed of the motor, in rpm
-
-        : return: The speed of the motor, in rpm
-        : rtype: float
+        :return: The speed of the motor, in rpm
+        :rtype: float
         """
         # Convert from ticks per 20ms to rpm (60 sec/min, 50 Hz)
         return self.speed*(60*50)/self._encoder.ticks_per_rev
@@ -121,8 +117,8 @@ def set_speed(self, speed_rpm: float | None = None):
         Sets target speed (in rpm) to be maintained passively
         Call with no parameters to turn off speed control
 
-        : param target_speed_rpm: The target speed for the motor in rpm, or None
-        : type target_speed_rpm: float, or None
+        :param target_speed_rpm: The target speed for the motor in rpm, or None
+        :type target_speed_rpm: float, or None
         """
         if speed_rpm is None:
             self.target_speed = None
@@ -137,8 +133,8 @@ def set_speed_controller(self, new_controller: Controller):
         """
         Sets a new controller for speed control
 
-        : param new_controller: The new Controller for speed control
-        : type new_controller: Controller
+        :param new_controller: The new Controller for speed control
+        :type new_controller: Controller
         """
         self.speedController = new_controller
 

XRPLib/encoder.py

@@ -5,9 +5,9 @@
 import time
 
 class Encoder:
-    gear_ratio = (30/14) * (28/16) * (36/9) * (26/8) # 48.75
-    ticks_per_motor_shaft_revolution = 12
-    ticks_per_rev = ticks_per_motor_shaft_revolution * gear_ratio # 585
+    _gear_ratio = (30/14) * (28/16) * (36/9) * (26/8) # 48.75
+    _ticks_per_motor_shaft_revolution = 12
+    ticks_per_rev = _ticks_per_motor_shaft_revolution * _gear_ratio # 585
 
     def __init__(self, index, encAPin, encBPin):
         if(abs(encAPin - encBPin) != 1):
@@ -18,19 +18,30 @@ def __init__(self, index, encAPin, encBPin):
         self.sm.active(1)
 
     def reset_encoder_position(self):
+        """
+        Resets the encoder position to 0
+        """
         # It's possible for this to cause issues if in the middle of inrementing
         # or decrementing, but the result should only be off by 1. If that's a
         # problem, an alternative solution is to stop the state machine, then
         # reset both x and the program counter. But that's excessive.
         self.sm.exec("set(x, 0)")
 
     def get_position_ticks(self):
+        """
+        :return: The position of the encoded motor, in ticks, relative to the last time reset was called.
+        :rtype: int
+        """
         ticks = self.sm.get()
         if(ticks > 2**31):
             ticks -= 2**32
         return ticks
 
     def get_position(self):
+        """
+        :return: The position of the encoded motor, in revolutions, relative to the last time reset was called.
+        :rtype: float
+        """
         return self.get_position_ticks() / self.ticks_per_rev
 
     @rp2.asm_pio(in_shiftdir=rp2.PIO.SHIFT_LEFT, out_shiftdir=rp2.PIO.SHIFT_RIGHT)