DOCS-1870: Add methods for arm, board, and base (#541)

Author: npentrel

src/viam/components/arm/arm.py

@@ -37,6 +37,13 @@ async def get_end_position(
         """
         Get the current position of the end of the arm expressed as a Pose.
 
+        ::
+
+            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+
+            # Get the end position of the arm as a Pose.
+            pos = await my_arm.get_end_position()
+
         Returns:
             Pose: The location and orientation of the arm described as a Pose.
         """
@@ -54,6 +61,16 @@ async def move_to_position(
         """
         Move the end of the arm to the Pose specified in ``pose``.
 
+        ::
+
+            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+
+            # Create a Pose for the arm.
+            examplePose = Pose(x=5, y=5, z=5, o_x=5, o_y=5, o_z=5, theta=20)
+
+            # Move your arm to the Pose.
+            await my_arm.move_to_position(pose=examplePose)
+
         Args:
             pose (Pose): The destination Pose for the arm.
         """
@@ -71,6 +88,21 @@ async def move_to_joint_positions(
         """
         Move each joint on the arm to the corresponding angle specified in ``positions``.
 
+        ::
+
+            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+
+            # Declare a list of values with your desired rotational value for each joint on
+            # the arm.
+            degrees = [0.0, 45.0, 0.0, 0.0, 0.0]
+
+            # Declare a new JointPositions with these values.
+            jointPos = arm.move_to_joint_positions(
+                JointPositions(values=[0.0, 45.0, 0.0, 0.0, 0.0]))
+
+            # Move each joint of the arm to the position these values specify.
+            await my_arm.move_to_joint_positions(positions=jointPos)
+
         Args:
             positions (JointPositions): The destination ``JointPositions`` for the arm.
         """
@@ -87,6 +119,13 @@ async def get_joint_positions(
         """
         Get the JointPositions representing the current position of the arm.
 
+        ::
+
+            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+
+            # Get the current position of each joint on the arm as JointPositions.
+            pos = await my_arm.get_joint_positions()
+
         Returns:
             JointPositions: The current JointPositions for the arm.
         """
@@ -102,6 +141,13 @@ async def stop(
     ):
         """
         Stop all motion of the arm. It is assumed that the arm stops immediately.
+
+        ::
+
+            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+
+            # Stop all motion of the arm. It is assumed that the arm stops immediately.
+            await my_arm.stop()
         """
         ...
 
@@ -110,6 +156,16 @@ async def is_moving(self) -> bool:
         """
         Get if the arm is currently moving.
 
+        ::
+
+            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+
+            # Stop all motion of the arm. It is assumed that the arm stops immediately.
+            await my_arm.stop()
+
+            # Print if the arm is currently moving.
+            print(my_arm.is_moving())
+
         Returns:
             bool: Whether the arm is moving.
         """
@@ -122,6 +178,19 @@ async def get_kinematics(
         """
         Get the kinematics information associated with the arm.
 
+        ::
+
+            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+
+            # Get the kinematics information associated with the arm.
+            kinematics = await my_arm.get_kinematics()
+
+            # Get the format of the kinematics file.
+            k_file = kinematics[0]
+
+            # Get the byte contents of the file.
+            k_bytes = kinematics[1]
+
         Returns:
             Tuple[KinematicsFileFormat.ValueType, bytes]:
                 - KinematicsFileFormat.ValueType:

src/viam/components/base/base.py

@@ -47,6 +47,16 @@ async def move_straight(
         When ``distance`` or ``velocity`` is 0, the base will stop.
         This method blocks until completed or cancelled.
 
+        ::
+
+            my_base = Base.from_robot(robot=robot, name="my_base")
+
+            # Move the base 40 mm at a velocity of 90 mm/s, forward.
+            await my_base.move_straight(distance=40, velocity=90)
+
+            # Move the base 40 mm at a velocity of -90 mm/s, backward.
+            await my_base.move_straight(distance=40, velocity=-90)
+
         Args:
             distance (int): The distance (in millimeters) to move.
                 Negative implies backwards.
@@ -71,6 +81,13 @@ async def spin(
         When ``velocity`` is 0, the base will stop.
         This method blocks until completed or cancelled.
 
+        ::
+
+            my_base = Base.from_robot(robot=robot, name="my_base")
+
+            # Spin the base 10 degrees at an angular velocity of 15 deg/sec.
+            await my_base.spin(angle=10, velocity=15)
+
         Args:
             angle (float): The angle (in degrees) to spin.
             velocity (float): The angular velocity (in degrees per second)
@@ -96,6 +113,34 @@ async def set_power(
         When ``linear`` and ``angular`` are both nonzero, the base will move in an arc,
         with a tighter radius if angular power is greater than linear power.
 
+        ::
+
+            my_base = Base.from_robot(robot=robot, name="my_base")
+
+            # Make your wheeled base move forward. Set linear power to 75%.
+            print("move forward")
+            await my_base.set_power(
+                linear=Vector3(x=0, y=-.75, z=0),
+                angular=Vector3(x=0, y=0, z=0))
+
+            # Make your wheeled base move backward. Set linear power to -100%.
+            print("move backward")
+            await my_base.set_power(
+                linear=Vector3(x=0, y=-1.0, z=0),
+                angular=Vector3(x=0, y=0, z=0))
+
+            # Make your wheeled base spin left. Set angular power to 100%.
+            print("spin left")
+            await my_base.set_power(
+                linear=Vector3(x=0, y=0, z=0),
+                angular=Vector3(x=0, y=0, z=1))
+
+            # Make your wheeled base spin right. Set angular power to -75%.
+            print("spin right")
+            await my_base.set_power(
+                linear=Vector3(x=0, y=0, z=0),
+                angular=Vector3(x=0, y=0, z=-.75))
+
         Args:
             linear (Vector3): The linear component. Only the Y component is used
                 for wheeled base. Positive implies forwards.
@@ -117,6 +162,14 @@ async def set_velocity(
         """
         Set the linear and angular velocities of the base.
 
+        ::
+
+            my_base = Base.from_robot(robot=robot, name="my_base")
+
+            # Set the linear velocity to 50 mm/sec and the angular velocity to
+            # 15 degree/sec.
+            await my_base.set_velocity(
+                linear=Vector3(x=0, y=50, z=0), angular=Vector3(x=0, y=0, z=15))
 
         Args:
             linear (Vector3): Velocity in mm/sec
@@ -133,6 +186,16 @@ async def stop(
     ):
         """
         Stop the base.
+
+        ::
+
+            my_base = Base.from_robot(robot=robot, name="my_base")
+
+            # Move the base forward 10 mm at a velocity of 50 mm/s.
+            await my_base.move_straight(distance=10, velocity=50)
+
+            # Stop the base.
+            await my_base.stop()
         """
         ...
 
@@ -141,6 +204,14 @@ async def is_moving(self) -> bool:
         """
         Get if the base is currently moving.
 
+        ::
+
+            my_base = Base.from_robot(robot=robot, name="my_base")
+
+            # Check whether the base is currently moving.
+            moving = await my_base.is_moving()
+            print('Moving: ', moving)
+
         Returns:
             bool: Whether the base is moving.
         """
@@ -151,6 +222,22 @@ async def get_properties(self, *, timeout: Optional[float] = None, **kwargs) ->
         """
         Get the base width and turning radius
 
+        ::
+
+            my_base = Base.from_robot(robot=robot, name="my_base")
+
+            # Get the width and turning radius of the base
+            properties = await my_base.get_properties()
+
+            # Get the width
+            print(f"Width of base: {properties.width_meters}")
+
+            # Get the turning radius
+            print(f"Turning radius of base: {properties.turning_radius_meters}")
+
+            # Get the wheel circumference
+            print(f"Wheel circumference of base: {properties.wheel_circumference_meters}")
+
         Returns:
             Properties: The properties of the base
         """