DOCS-1872: Add gripper and input controller methods (#542)

Author: npentrel

src/viam/components/gripper/gripper.py

@@ -28,6 +28,13 @@ async def open(
     ):
         """
         Open the gripper.
+
+        ::
+
+            my_gripper = Gripper.from_robot(robot=robot, name="my_gripper")
+
+            # Open the gripper.
+            await my_gripper.open()
         """
         ...
 
@@ -42,6 +49,13 @@ async def grab(
         """
         Instruct the gripper to grab.
 
+        ::
+
+            my_gripper = Gripper.from_robot(robot=robot, name="my_gripper")
+
+            # Grab with the gripper.
+            grabbed = await my_gripper.grab()
+
         Returns:
             bool: Indicates if the gripper grabbed something.
         """
@@ -57,6 +71,13 @@ async def stop(
     ):
         """
         Stop the gripper. It is assumed the gripper stops immediately.
+
+        ::
+
+            my_gripper = Gripper.from_robot(robot=robot, name="my_gripper")
+
+            # Stop the gripper.
+            await my_gripper.stop()
         """
         ...
 
@@ -65,6 +86,14 @@ async def is_moving(self) -> bool:
         """
         Get if the gripper is currently moving.
 
+        ::
+
+            my_gripper = Gripper.from_robot(robot=robot, name="my_gripper")
+
+            # Check whether the gripper is currently moving.
+            moving = await my_gripper.is_moving()
+            print('Moving:', moving)
+
         Returns:
             bool: Whether the gripper is moving.
         """

src/viam/components/input/input.py

@@ -146,6 +146,18 @@ async def get_controls(self, *, extra: Optional[Dict[str, Any]] = None, timeout:
         """
         Returns a list of Controls provided by the Controller
 
+        ::
+
+            # Get the controller from the machine.
+            my_controller = Controller.from_robot(
+                robot=myRobotWithController, name="my_controller")
+
+            # Get the list of Controls provided by the controller.
+            controls = await my_controller.get_controls()
+
+            # Print the list of Controls provided by the controller.
+            print(f"Controls: {controls}")
+
         Returns:
             List[Control]: List of controls provided by the Controller
         """
@@ -159,6 +171,18 @@ async def get_events(
         Returns the most recent Event for each input
         (which should be the current state)
 
+        ::
+
+            # Get the controller from the machine.
+            my_controller = Controller.from_robot(
+                robot=myRobotWithController, name="my_controller")
+
+            # Get the most recent Event for each Control.
+            recent_events = await my_controller.get_events()
+
+            # Print out the most recent Event for each Control.
+            print(f"Recent Events: {recent_events}")
+
         Returns:
             Dict[Control, Event]: The most recent event for each input
         """
@@ -178,6 +202,46 @@ def register_control_callback(
         Register a function that will fire on given EventTypes for a given
         Control
 
+        ::
+
+            # Define a function to handle pressing the Start Menu Button "BUTTON_START" on
+            # your controller, printing out the start time.
+            def print_start_time(event):
+                print(f"Start Menu Button was pressed at this time: {event.time}")
+
+
+            # Define a function that handles the controller.
+            async def handle_controller(controller):
+                # Get the list of Controls on the controller.
+                controls = await controller.get_controls()
+
+                # If the "BUTTON_START" Control is found, register the function
+                # print_start_time to fire when "BUTTON_START" has the event "ButtonPress"
+                # occur.
+                if Control.BUTTON_START in controls:
+                    controller.register_control_callback(
+                        Control.BUTTON_START, [EventType.BUTTON_PRESS], print_start_time)
+                else:
+                    print("Oops! Couldn't find the start button control! Is your "
+                        "controller connected?")
+                    exit()
+
+                while True:
+                    await asyncio.sleep(1.0)
+
+
+            async def main():
+                # ... < INSERT CONNECTION CODE FROM MACHINE'S CODE SAMPLE TAB >
+
+                # Get your controller from the machine.
+                my_controller = Controller.from_robot(
+                    robot=myRobotWithController, name="my_controller")
+
+                # Run the handleController function.
+                await handleController(my_controller)
+
+                # ... < INSERT ANY OTHER CODE FOR MAIN FUNCTION >
+
         Args:
             control (Control): The control to register the function for
             triggers (List[EventType]): The events that will
@@ -197,6 +261,16 @@ async def trigger_event(
     ) -> None:  # Explicitly return None for typechecking, as this is technically a NoReturn default implementation
         """Directly send an Event (such as a button press) from external code
 
+        ::
+
+            # Define a "Button is Pressed" event for the control BUTTON_START.
+            button_is_pressed_event = Event(
+                time(), EventType.BUTTON_PRESS, Control.BUTTON_START, 1.0)
+
+            # Trigger the event on your controller. Set this trigger to timeout if it has
+            # not completed in 7 seconds.
+            await myController.trigger_event(event=my_event, timeout=7.0)
+
         Args:
             event (Event): The event to trigger
         """