diff --git a/.github/workflows/check_python_methods.py b/.github/workflows/check_python_methods.py index 73f1c8d2d9..1185517e7c 100644 --- 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 index fc8cc3855d..29d3c027d5 100644 --- 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 "" (including brackets) with your robot's api key +api_key = '' +# Replace "" (including brackets) with your robot's 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 "" (including brackets) with your robot's api key + api_key='', + # Replace "" (including brackets) with your robot's 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/rdk@v0.15.1/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/rdk@v0.15.1/referenceframe#LinkInFrame): Any additional transforms. + +**Returns:** + +- [(\*referenceframe.PoseInFrame)](https://pkg.go.dev/go.viam.com/rdk@v0.15.1/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). diff --git a/static/include/services/apis/robot.md b/static/include/services/apis/robot.md index 8ec2274c34..03b1443917 100644 --- a/static/include/services/apis/robot.md +++ b/static/include/services/apis/robot.md @@ -1,9 +1,18 @@ + | Method Name | Description | | --------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| [`Options.with_api_key`](/build/program/apis/robot/#optionswith_api_key) | Create Robot client connection options with an API key as credentials. | +| [`AtAddress`](/build/program/apis/robot/#ataddress) | Create a robot client that is connected to the robot at the provided address. | +| [`WithChannel`](/build/program/apis/robot/#withchannel) | Create a robot that is connected to a robot over the given channel. | +| [`Refresh`](/build/program/apis/robot/#refresh) | Manually refesh the underlying parts of the robot. | +| [`Status`](/build/program/apis/robot/#status) | Get the status of the robot's components. | +| [`GetOperations`](/build/program/apis/robot/#getoperations) | Get the list of operations currently running on the robot. | +| [`CancelOperation`](/build/program/apis/robot/#canceloperation) | Cancel the specified operation on the robot. | +| [`BlockForOperation`](/build/program/apis/robot/#blockforoperation) | Blocks on the specified operation on the robot. | +| [`TransformPose`](/build/program/apis/robot/#transformpose) | Transform a given source Pose from the original reference frame to a new destination reference frame. | | [`DiscoverComponents`](/build/program/apis/robot/#discovercomponents) | Get a list of discovered component configurations. | | [`FrameSystemConfig`](/build/program/apis/robot/#framesystemconfig) | Get the configuration of a robot's frame system. | | [`Status`](/build/program/apis/robot/#status) | Get the status of each of the resources on the robot. | | [`Close`](/build/program/apis/robot/#close) | Close the connections and stop periodic tasks across the robot. | | [`StopAll`](/build/program/apis/robot/#stopall) | Cancel all operations for the robot and stop its movement. | | [`ResourceNames`](/build/program/apis/robot/#resourcenames) | Get a list of all the robot's resources. | -| [`WithAPIKey`](/build/program/apis/robot/#withapikey) | Create a client to interact with your robot using an API key as credentials. |