DOCS-1429: Document Robot API remaining methods (#2293)

viamrobotics · Dec 12, 2023 · 123fda2 · 123fda2
1 parent d7ab01b
commit 123fda2
Show file tree

Hide file tree

Showing 3 changed files with 333 additions and 34 deletions.
diff --git a/.github/workflows/check_python_methods.py b/.github/workflows/check_python_methods.py
@@ -273,7 +273,9 @@ def parse(type, names):
 
             if not found and id != "viam.components.board.client.DigitalInterruptClient.add_callback" \
             and id != "viam.components.board.client.DigitalInterruptClient.add_post_processor" \
-            and id != "viam.components.input.client.ControllerClient.reset_channel":
+            and id != "viam.components.input.client.ControllerClient.reset_channel" \
+            and id != "viam.robot.client.RobotClient.get_component" \
+            and id != "viam.robot.client.RobotClient.get_service":
                 sdk_methods_missing.append(id)
 
 

diff --git a/docs/build/program/apis/robot.md b/docs/build/program/apis/robot.md
@@ -44,10 +44,10 @@ async def connect():
 
 async def main():
     # Make a RobotClient
-    robot_client = await connect()
+    robot = await connect()
     print('Resources:')
     print(robot.resource_names)
-    await robot_client.close()
+    await robot.close()
 
 if __name__ == '__main__':
     asyncio.run(main())
@@ -170,6 +170,321 @@ For the full list of methods, see the [Viam Python SDK documentation](https://py
 
 {{< readfile "/static/include/services/apis/robot.md" >}}
 
+### Options.with_api_key
+
+Create a `RobotClient.Options` using an API key as credentials.
+Pass these options to [`AtAddress`](#ataddress).
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `api_key` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): [An API key](/fleet/cli/#authenticate) with access to the robot.
+- `api_key_id` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Your API key ID.
+  Must be a valid UUID.
+
+**Returns:**
+
+- [(RobotClient.Options)](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.Options): Options for connecting the `RobotClient`.
+
+```python
+# Replace "<API-KEY>" (including brackets) with your robot's api key
+api_key = '<API-KEY>'
+# Replace "<API-KEY-ID>" (including brackets) with your robot's api key
+# id
+api_key_id = '<API-KEY-ID>'
+
+opts = RobotClient.Options.with_api_key(api_key, api_key_id)
+
+robot = await RobotClient.at_address('ADDRESS FROM THE VIAM APP', opts)
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.Options.with_api_key).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### AtAddress
+
+Create a robot client that is connected to the robot at the provided address.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `address` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Address of the robot. For example, IP address or URL.
+- `options` [(Options)](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.Options): Options for connecting and refreshing.
+
+**Returns:**
+
+- `RobotClient`: The robot client.
+
+```python {class="line-numbers linkable-line-numbers"}
+async def connect():
+    opts = RobotClient.Options.with_api_key(
+        # Replace "<API-KEY>" (including brackets) with your robot's api key
+        api_key='<API-KEY>',
+        # Replace "<API-KEY-ID>" (including brackets) with your robot's api key
+        # id
+        api_key_id='<API-KEY-ID>'
+    )
+    return await RobotClient.at_address('ADDRESS FROM THE VIAM APP', opts)
+
+
+async def main():
+    # Make a RobotClient
+    robot = await connect()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.at_address).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### WithChannel
+
+Create a robot that is connected to a robot over the given channel.
+Any robots created using this method will NOT automatically close the channel upon exit.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `channel` [(ViamChannel)](https://python.viam.dev/autoapi/viam/rpc/dial/index.html#viam.rpc.dial.ViamChannel): The channel that is connected to a robot, obtained by [`viam.rpc.dial`](https://python.viam.dev/_modules/viam/rpc/dial.html#dial).
+- `options` [(Options)](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.Options): Options for refreshing. Any connection options will be ignored.
+
+**Returns:**
+
+- `RobotClient`: The robot client.
+
+```python {class="line-numbers linkable-line-numbers"}
+from viam.robot.client import RobotClient
+from viam.rpc.dial import DialOptions, dial
+
+
+async def connect_with_channel() -> RobotClient:
+    async with await dial('ADDRESS', DialOptions()) as channel:
+        return await RobotClient.with_channel(channel, RobotClient.Options())
+
+robot = await connect_with_channel()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.with_channel).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Refresh
+
+Manually refresh the underlying parts of this robot.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- None
+
+**Returns:**
+
+- None
+
+```python {class="line-numbers linkable-line-numbers"}
+await robot.refresh()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.refresh).
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+**Parameters:**
+
+- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
+
+**Returns:**
+
+- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
+
+```go
+err := robot.Refresh(ctx)
+```
+
+For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot/client#RobotClient.Refresh).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Status
+
+Get the status of the robot's components. You can optionally provide a list of each `ResourceName` you want the status of.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `components` [(Optional[List[viam.proto.common.ResourceName]])](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName): Optional list of `ResourceName` for each component you want the status of.
+
+**Returns:**
+
+- List[status]: The status of each of the robot's components you've specified.
+
+```python {class="line-numbers linkable-line-numbers"}
+statuses = await robot.get_status()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_status).
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+**Parameters:**
+
+- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
+- `resourceNames` [([]resource.Name)](https://pkg.go.dev/go.viam.com/[email protected]/resource#Name): Optional list of resource names for each component you want the status of.
+
+**Returns:**
+
+- [([]robot.Status)](https://pkg.go.dev/go.viam.com/rdk/robot#Status): The status of each of the robot's components you've specified.
+- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
+
+```go
+statuses, err := robot.Status(ctx)
+```
+
+For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot/client#RobotClient.Refresh).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetOperations
+
+Get the list of operations currently running on the robot.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- None
+
+**Returns:**
+
+- [(List[viam.proto.robot.Operation])](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.Operation): The list of operations currently running on a given robot.
+
+```python {class="line-numbers linkable-line-numbers"}
+operations = await robot.get_operations()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_operations).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### CancelOperation
+
+Cancel the specified operation on the robot.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `id` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of operation to kill. Find this with [`GetOperations()`](#getoperations).
+
+**Returns:**
+
+- None
+
+```python {class="line-numbers linkable-line-numbers"}
+await robot.cancel_operation("INSERT OPERATION ID")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.cancel_operation).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### BlockForOperation
+
+Blocks on the specified operation on the robot. This function will only return when the specific operation has finished or has been cancelled.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `id` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of operation to block on. Find this with [`GetOperations()`](#getoperations)
+
+**Returns:**
+
+- None
+
+```python {class="line-numbers linkable-line-numbers"}
+await robot.block_for_operation("INSERT OPERATION ID")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.block_for_operation).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### TransformPose
+
+Transform a given source Pose from the original reference frame to a new destination reference frame.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `query` [(viam.proto.common.PoseInFrame)](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.PoseInFrame): The pose that should be transformed.
+- `destination` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The name of the reference frame to transform the given pose to.
+
+**Returns:**
+
+- [(PoseInFrame)](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.PoseInFrame): Transformed pose in frame.
+
+```python {class="line-numbers linkable-line-numbers"}
+pose = await robot.transform_pose(PoseInFrame(), "origin")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.transform_pose).
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+**Parameters:**
+
+- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
+- `query` [(\*referenceframe.PoseInFrame)](https://pkg.go.dev/go.viam.com/rdk/referenceframe#PoseInFrame): The pose that should be transformed.
+- `destination` [(string)](https://pkg.go.dev/builtin#string): The name of the reference page to transform the given pose to.
+- `additionalTransforms` [([]\*referenceframe.LinkInFrame)](https://pkg.go.dev/go.viam.com/[email protected]/referenceframe#LinkInFrame): Any additional transforms.
+
+**Returns:**
+
+- [(\*referenceframe.PoseInFrame)](https://pkg.go.dev/go.viam.com/[email protected]/referenceframe#PoseInFrame): Transformed pose in frame.
+- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
+
+```go
+import (
+  "go.viam.com/rdk/referenceframe"
+  "go.viam.com/rdk/spatialmath"
+)
+
+baseOrigin := referenceframe.NewPoseInFrame("test-base", spatialmath.NewZeroPose())
+movementSensorToBase, err := robot.TransformPose(ctx, baseOrigin, "my-movement-sensor", nil)
+```
+
+For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot/client#RobotClient.TransformPose).
+
+{{% /tab %}}
+{{< /tabs >}}
+
 ### DiscoverComponents
 
 Get a list of discovered component configurations.
@@ -309,7 +624,7 @@ fmt.Println(frameSystem)
 For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/RobotClient.html#frameSystemConfig).
 
 ```typescript {class="line-numbers linkable-line-numbers"}
-// Get the frame system configuration.
+// Get the frame system configuration
 console.log("FrameSytemConfig:", await robot.frameSystemConfig());
 ```
 
@@ -522,6 +837,8 @@ Get a list of all known resource names connected to this robot.
 
 - [(List[viam.proto.common.ResourceName])](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName): List of all known resource names. A property of a [RobotClient](https://python.viam.dev/autoapi/viam/robot/client/index.html)
 
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.resource_names)
+
 ```python
 resource_names = robot.resource_names
 ```
@@ -564,33 +881,4 @@ For more information, see the [Typescript SDK Docs](https://ts.viam.dev/classes/
 {{% /tab %}}
 {{< /tabs >}}
 
-### WithAPIKey
-
-Create a client to interact with your robot using an API key as credentials.
-
-{{< tabs >}}
-{{% tab name="Python" %}}
-
-**Parameters:**
-
-- `api_key` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): [An API key](/fleet/cli/#authenticate) with access to the robot.
-
-- `api_key_id` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Your API key ID.
-  Must be a valid UUID.
-
-**Returns:**
-
-- [(RobotClient.Options)](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient): A gRPC client for interacting with your robot.
-
-- [(List[viam.proto.common.ResourceName])](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName): List of all known resource names. A property of a [RobotClient](https://python.viam.dev/autoapi/viam/robot/client/index.html)
-
-```python
-api_key = "your_api_key"
-api_key_id = "valid_uuid"
-robot_client = RobotClient.with_api_key(api_key, api_key_id)
-```
-
-{{% /tab %}}
-{{< /tabs >}}
-
 For the full list of robot API methods, see the [Viam Python SDK documentation](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient) or the [RDK (the Viam Go SDK) documentation](https://pkg.go.dev/go.viam.com/rdk/robot/client#RobotClient).