diff --git a/.github/workflows/sdk_protos_map.csv b/.github/workflows/sdk_protos_map.csv index b15c8dbe61..bb584c85db 100644 --- a/.github/workflows/sdk_protos_map.csv +++ b/.github/workflows/sdk_protos_map.csv @@ -513,15 +513,17 @@ robot,CancelOperation,,cancel_operation,,,cancelOperation robot,BlockForOperation,,block_for_operation,,,blockForOperation robot,FrameSystemConfig,,get_frame_system_config,,,frameSystemConfig robot,TransformPose,,transform_pose,,,transformPose -robot,TransformPCD,,,,,transformPCD +robot,GetPose,,,,,getPose +robot,TransformPCD,,transform_pcd,,,transformPCD robot,StreamStatus,,,,, # DEPRECATED robot,DiscoverComponents,,discover_components,DiscoverComponents,,discoverComponents robot,GetModelsFromModules,,get_models_from_modules,GetModelsFromModules,getModelsFromModules,getModelsFromModules robot,StopAll,,stop_all,StopAll,,stopAll -robot,RestartModule,,restart_module,RestartModule,,restartModule +robot,RestartModule,,restart_module,RestartModule,restartModule,restartModule robot,StartSession,,,,, robot,SendSessionHeartbeat,,,,, robot,Log,,log,,, +robot,UploadDataFromPath,,upload_data_from_path,,, robot,GetCloudMetadata,,get_cloud_metadata,CloudMetadata,getCloudMetadata,getCloudMetadata robot,GetVersion,,get_version,Version,,getVersion ## HACK: Robot (python) provides additional helper function, adding 4 pseudo-entries: diff --git a/.github/workflows/update_sdk_methods.py b/.github/workflows/update_sdk_methods.py index 47778dfcf6..fae933824c 100755 --- a/.github/workflows/update_sdk_methods.py +++ b/.github/workflows/update_sdk_methods.py @@ -354,7 +354,7 @@ "organization settings page": "/manage/reference/organize/", "image tags": "/data-ai/train/create-dataset/#label-your-images", "API key": "/fleet/cli/#authenticate", - "board model": "/dev/reference/apis/components/board/" + "board model": "/reference/apis/components/board/" } ## Map sdk language to specific code fence formatting syntax for that language: @@ -459,7 +459,7 @@ def get_proto_apis(): ## Link matching text, used in write_markdown(): ## NOTE: Currently does not support formatting for link titles -## (EXAMPLE: bolded DATA tab here: https://docs.viam.com/dev/reference/apis/data-client/#binarydatabyfilter) +## (EXAMPLE: bolded DATA tab here: https://docs.viam.com/reference/apis/data-client/#binarydatabyfilter) def link_description(format_type, full_description, link_text, link_url): ## Supports 'md' link styling or 'html' link styling. @@ -930,31 +930,31 @@ def write_markdown(type, names, methods): if type == 'component': ## Replace underscores, and convert generic_component to just generic: resource_adjusted = resource.replace('generic_component', 'generic').replace('_','-') - proto_anchor_link = '/dev/reference/apis/components/' + resource_adjusted + '/#' + proto_link + proto_anchor_link = '/reference/apis/components/' + resource_adjusted + '/#' + proto_link elif type == 'service' and resource in ['base_remote_control', 'motion', 'slam', 'vision']: - proto_anchor_link = '/dev/reference/apis/services/' + resource.replace('base_remote_control', 'base-rc') + '/#' + proto_link + proto_anchor_link = '/reference/apis/services/' + resource.replace('base_remote_control', 'base-rc') + '/#' + proto_link elif type == 'service' and resource == 'data_manager': - proto_anchor_link = '/dev/reference/apis/services/data/#' + proto_link + proto_anchor_link = '/reference/apis/services/data/#' + proto_link elif type == 'service' and resource == 'discovery': - proto_anchor_link = '/dev/reference/apis/services/discovery/#' + proto_link + proto_anchor_link = '/reference/apis/services/discovery/#' + proto_link elif type == 'service' and resource == 'generic_service': - proto_anchor_link = '/dev/reference/apis/services/generic/#' + proto_link + proto_anchor_link = '/reference/apis/services/generic/#' + proto_link elif type == 'service' and resource == 'audio_in': - proto_anchor_link = '/dev/reference/apis/services/audio-in/#' + proto_link + proto_anchor_link = '/reference/apis/services/audio-in/#' + proto_link elif type == 'service' and resource == 'audio_out': - proto_anchor_link = '/dev/reference/apis/services/audio-out/#' + proto_link + proto_anchor_link = '/reference/apis/services/audio-out/#' + proto_link elif type == 'service' and resource == 'mlmodel': - proto_anchor_link = '/dev/reference/apis/services/ml/#' + proto_link + proto_anchor_link = '/reference/apis/services/ml/#' + proto_link elif type == 'service' and resource == 'world_state_store': - proto_anchor_link = '/dev/reference/apis/services/world-state-store/#' + proto_link + proto_anchor_link = '/reference/apis/services/world-state-store/#' + proto_link elif type == 'app' and resource == 'app': - proto_anchor_link = '/dev/reference/apis/fleet/#' + proto_link + proto_anchor_link = '/reference/apis/fleet/#' + proto_link elif type == 'app' and resource in ["billing", "mltraining"]: - proto_anchor_link = '/dev/reference/apis/' + resource.replace('mltraining','ml-training') + '-client/#' + proto_link + proto_anchor_link = '/reference/apis/' + resource.replace('mltraining','ml-training') + '-client/#' + proto_link elif type == 'app' and resource in ["data", "dataset", "data_sync"]: - proto_anchor_link = '/dev/reference/apis/data-client/#' + proto_link + proto_anchor_link = '/reference/apis/data-client/#' + proto_link elif type == 'robot': - proto_anchor_link = '/dev/reference/apis/' + resource + '/#' + proto_link + proto_anchor_link = '/reference/apis/' + resource + '/#' + proto_link ## Fetch just the first sentence from the proto_override_file (first text string terminated by '.\n'), ignoring hugo ## shortcodes like alerts ('{{%.*%}}.*{{% \[a-b].* %}}'), which precede some override files' (proto descriptions') diff --git a/static/include/robot/apis/generated/robot-table.md b/static/include/robot/apis/generated/robot-table.md index 81209a4ffc..64aaab30b3 100644 --- a/static/include/robot/apis/generated/robot-table.md +++ b/static/include/robot/apis/generated/robot-table.md @@ -10,11 +10,13 @@ | [`BlockForOperation`](/reference/apis/robot/#blockforoperation) | Blocks on the specified operation on the machine. | | [`FrameSystemConfig`](/reference/apis/robot/#framesystemconfig) | Get the configuration of the frame system of a given machine. | | [`TransformPose`](/reference/apis/robot/#transformpose) | Transform a given source Pose from the original reference frame to a new destination reference frame. | +| [`GetPose`](/reference/apis/robot/#getpose) | Get the pose of a component in the frame system of the machine, relative to a specified destination frame. | | [`TransformPCD`](/reference/apis/robot/#transformpcd) | Transforms the pointcloud to the desired frame in the robot's frame system. | | [`GetModelsFromModules`](/reference/apis/robot/#getmodelsfrommodules) | Get a list of all models provided by local and registry modules on the machine. | | [`StopAll`](/reference/apis/robot/#stopall) | Cancel all current and outstanding operations for the machine and stop all actuators and movement. | | [`RestartModule`](/reference/apis/robot/#restartmodule) | Reload a module as if its config changed. | | [`Log`](/reference/apis/robot/#log) | Create a LogEntry object from the log to send to the RDK over gRPC. | +| [`UploadDataFromPath`](/reference/apis/robot/#uploaddatafrompath) | Upload data from a file or folder path on the machine to the Viam cloud. | | [`GetCloudMetadata`](/reference/apis/robot/#getcloudmetadata) | Get app-related information about the robot. | | [`GetVersion`](/reference/apis/robot/#getversion) | Return version information about the machine. | | [`Options.with_api_key`](/reference/apis/robot/#optionswith_api_key) | Create a `RobotClient.Options` using an API key as credentials. | diff --git a/static/include/robot/apis/generated/robot.md b/static/include/robot/apis/generated/robot.md index 1c44e69abc..5b9cfc0ce0 100644 --- a/static/include/robot/apis/generated/robot.md +++ b/static/include/robot/apis/generated/robot.md @@ -11,7 +11,7 @@ Get the list of operations currently running on the machine. **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 machine. +- ([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 machine. **Example:** @@ -56,7 +56,7 @@ Get status information about the machine including the status of the machine and **Returns:** -- ([viam.proto.robot.GetMachineStatusResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.GetMachineStatusResponse)): : current status of the machine (initializing or running), current status of the resources (List[ResourceStatus]) and the revision of the config of the machine. +- ([viam.proto.robot.GetMachineStatusResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.GetMachineStatusResponse)): : current status of the machine (initializing or running), current status of the resources (List[ResourceStatus]), the revision of the config of the machine, and the status of modules (List[ModuleStatus]). **Example:** @@ -66,6 +66,7 @@ machine_state = machine_status.state resource_statuses = machine_status.resources cloud_metadata = machine_status.resources[0].cloud_metadata config_status = machine_status.config +module_statuses = machine_status.modules ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_machine_status). @@ -278,7 +279,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ **Example:** ```ts {class="line-numbers linkable-line-numbers"} -await machine.cancelOperation("INSERT OPERATION ID"); +await machine.cancelOperation('INSERT OPERATION ID'); ``` For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/Client.html#canceloperation). @@ -324,7 +325,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ **Example:** ```ts {class="line-numbers linkable-line-numbers"} -await machine.blockForOperation("INSERT OPERATION ID"); +await machine.blockForOperation('INSERT OPERATION ID'); ``` For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/Client.html#blockforoperation). @@ -345,7 +346,7 @@ Get the configuration of the frame system of a given machine. **Returns:** -- ([List[viam.proto.robot.FrameSystemConfig]](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.FrameSystemConfig)): : The configuration of a given machine’s frame system. +- ([List[viam.proto.robot.FrameSystemConfig]](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.FrameSystemConfig)): : The configuration of a given machine’s frame system. **Example:** @@ -394,7 +395,7 @@ Transform a given source Pose from the original reference frame to a new destina **Returns:** -- ([viam.proto.common.PoseInFrame](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.PoseInFrame)): : The pose and the reference frame for the new destination. +- ([viam.proto.common.PoseInFrame](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.PoseInFrame)): : The pose and the reference frame for the new destination. **Example:** @@ -428,8 +429,9 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ - `source` ([commonApi](https://ts.viam.dev/modules/commonApi.html)) (required) - `destination` (string) (required): The name of the reference frame to transform the given. -- `supplementalTransforms` ([commonApi](https://ts.viam.dev/modules/commonApi.html)) (required): Pose information on any additional - reference frames that are needed to perform the transform. +- `supplementalTransforms` ([commonApi](https://ts.viam.dev/modules/commonApi.html)) (required): Pose information on any additional reference frames that are + needed to perform the transform. +- `callOptions` (CallOptions) (optional) **Returns:** @@ -440,6 +442,28 @@ For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/ {{% /tab %}} {{< /tabs >}} +### GetPose + +Get the pose of a component in the frame system of the machine, relative to a specified destination frame. + +{{< tabs >}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `componentName` (string) (required) +- `destinationFrame` (string) (required) +- `supplementalTransforms` ([commonApi](https://ts.viam.dev/modules/commonApi.html)) (required) + +**Returns:** + +- (Promise<[commonApi](https://ts.viam.dev/modules/commonApi.html).[PoseInFrame](https://ts.viam.dev/classes/commonApi.PoseInFrame.html)>) + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/Client.html#getpose). + +{{% /tab %}} +{{< /tabs >}} + ### TransformPCD Transforms the pointcloud to the desired frame in the robot's frame system. @@ -450,19 +474,17 @@ Do not move the robot between the generation of the initial pointcloud and the r **Parameters:** -- `point_cloud_pcd` ([bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)) (required): The point cloud data to transform, in PCD format. -- `source` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The reference frame of the point cloud. -- `destination` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The reference frame to transform the point cloud into. +- `point_cloud_pcd` ([bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)) (required): The point cloud data to transform. +- `source` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the reference frame the point cloud data came from, for example a camera resource. +- `destination` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the reference frame to transform the given data to, for example world. **Returns:** -- ([bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)): The point cloud data relative to the destination reference frame. +- ([bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)): : The point cloud data relative to the destination reference frame. **Example:** ```python {class="line-numbers linkable-line-numbers"} -from viam.components.camera import Camera - my_camera = Camera.from_robot(robot=machine, name="my_camera") data, _ = await my_camera.get_point_cloud() @@ -479,15 +501,14 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ - `pointCloudPCD` (Uint8Array) (required): The point clouds to transform. This should be in the [PCD format encoded into bytes](https://pointclouds.org/documentation/tutorials/pcd_file_format.html). - `source` (string) (required): The reference frame of the point cloud. -- `destination` (string) (required): The reference frame into which the source data should - be transformed, if unset this defaults to the "world" reference frame. Do - not move the robot between the generation of the initial pointcloud and - the receipt of the transformed pointcloud because that will make the - transformations inaccurate. +- `destination` (string) (required): The reference frame into which the source data should be transformed, if + unset this defaults to the "world" reference frame. Do not move the robot between the + generation of the initial pointcloud and the receipt of the transformed pointcloud because + that will make the transformations inaccurate. **Returns:** -- (Promise) +- (Promise>) For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/Client.html#transformpcd). @@ -508,7 +529,7 @@ This includes models that are not currently configured on the machine. **Returns:** -- ([List[viam.proto.robot.ModuleModel]](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.ModuleModel)): : A list of discovered models. +- ([List[viam.proto.robot.ModuleModel]](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.ModuleModel)): : A list of discovered models. **Example:** @@ -695,10 +716,10 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/r **Parameters:** -- `moduleId` (string) (optional): The id matching the module_id field of the registry - module in your part configuration. -- `moduleName` (string) (optional): The name matching the name field of the local/registry - module in your part configuration. +- `moduleId` (string) (optional): The id matching the module\_id field of the registry module in your part + configuration. +- `moduleName` (string) (optional): The name matching the name field of the local/registry module in your part + configuration. **Returns:** @@ -707,11 +728,31 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/r **Example:** ```ts {class="line-numbers linkable-line-numbers"} -await machine.restartModule("namespace:module:model", "my_model_name"); +await machine.restartModule('namespace:module:model', 'my_model_name'); ``` For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/Client.html#restartmodule). +{{% /tab %}} +{{% tab name="Flutter" %}} + +**Parameters:** + +- `moduleId` [String](https://api.flutter.dev/flutter/dart-core/String-class.html)? (optional) +- `moduleName` [String](https://api.flutter.dev/flutter/dart-core/String-class.html)? (optional) + +**Returns:** + +- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html) + +**Example:** + +```dart {class="line-numbers linkable-line-numbers"} +await machine.restartModule(moduleName: 'my-local-module'); +``` + +For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/RobotClient/restartModule.html). + {{% /tab %}} {{< /tabs >}} @@ -739,6 +780,38 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ {{% /tab %}} {{< /tabs >}} +### UploadDataFromPath + +Upload data from a file or folder path on the machine to the Viam cloud. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `path` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): File or folder path on the robot to upload. +- `upload_metadata` ([viam.proto.app.datasync.UploadMetadata](https://python.viam.dev/autoapi/viam/gen/app/datasync/v1/data_sync_pb2/index.html#viam.gen.app.datasync.v1.data_sync_pb2.UploadMetadata)) (optional): Optional metadata to apply to uploaded files. +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([viam.proto.robot.UploadDataFromPathResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.UploadDataFromPathResponse)): : Response containing files\_uploaded, files\_failed, bytes\_uploaded, bytes\_total, and ids. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +response = await machine.upload_data_from_path( + path="/path/to/data", + upload_metadata=UploadMetadata(component_name="camera", tags=["tag1"]) +) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.upload_data_from_path). + +{{% /tab %}} +{{< /tabs >}} + ### GetCloudMetadata Get app-related information about the robot. @@ -752,7 +825,7 @@ Get app-related information about the robot. **Returns:** -- ([viam.proto.robot.GetCloudMetadataResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.GetCloudMetadataResponse)): : App-related metadata. +- ([viam.proto.robot.GetCloudMetadataResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.GetCloudMetadataResponse)): : App-related metadata. **Example:** @@ -844,7 +917,7 @@ Return version information about the machine. **Returns:** -- ([viam.proto.robot.GetVersionResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.GetVersionResponse)): : Machine version related information. +- ([viam.proto.robot.GetVersionResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.GetVersionResponse)): : Machine version related information. **Example:** @@ -902,7 +975,7 @@ Pass these options to [`AtAddress`](#ataddress). **Returns:** -- (Self): : the RobotClient.Options. +- (Self): : the RobotClient.Options. **Raises:** diff --git a/static/include/robot/apis/overrides/methods/python.robot.transform_pcd.destination.md b/static/include/robot/apis/overrides/methods/python.robot.transform_pcd.destination.md new file mode 100644 index 0000000000..a77f99668a --- /dev/null +++ b/static/include/robot/apis/overrides/methods/python.robot.transform_pcd.destination.md @@ -0,0 +1 @@ +The name of the reference frame to transform the given data to, for example world. diff --git a/static/include/robot/apis/overrides/methods/python.robot.transform_pcd.source.md b/static/include/robot/apis/overrides/methods/python.robot.transform_pcd.source.md new file mode 100644 index 0000000000..3055ef6faf --- /dev/null +++ b/static/include/robot/apis/overrides/methods/python.robot.transform_pcd.source.md @@ -0,0 +1 @@ +The name of the reference frame the point cloud data came from, for example a camera resource. diff --git a/static/include/robot/apis/overrides/protos/robot.GetPose.md b/static/include/robot/apis/overrides/protos/robot.GetPose.md new file mode 100644 index 0000000000..65bfe38d8a --- /dev/null +++ b/static/include/robot/apis/overrides/protos/robot.GetPose.md @@ -0,0 +1 @@ +Get the pose of a component in the frame system of the machine, relative to a specified destination frame. diff --git a/static/include/robot/apis/overrides/protos/robot.UploadDataFromPath.md b/static/include/robot/apis/overrides/protos/robot.UploadDataFromPath.md new file mode 100644 index 0000000000..212933efb4 --- /dev/null +++ b/static/include/robot/apis/overrides/protos/robot.UploadDataFromPath.md @@ -0,0 +1 @@ +Upload data from a file or folder path on the machine to the Viam cloud.