diff --git a/docs/program/apis/_index.md b/docs/program/apis/_index.md index 34e02c5eab..579027bebd 100644 --- a/docs/program/apis/_index.md +++ b/docs/program/apis/_index.md @@ -8,6 +8,7 @@ icon: "/services/icons/sdk.svg" tags: ["client", "sdk", "viam-server", "networking", "apis", "robot api"] aliases: - "/program/sdks/" +no_list: true --- Every Viam {{< glossary_tooltip term_id="resource" text="resource" >}} exposes an [Application Programming Interface (API)](https://en.wikipedia.org/wiki/API) described through [protocol buffers](https://developers.google.com/protocol-buffers). @@ -342,400 +343,16 @@ In addition to the [board API](#board), the [board component](/components/board/ {{< readfile "/static/include/components/apis/digitalinterrupt.md" >}} -## Robot API +## Robot Management APIs -The Robot API is the designated interface for a robot, the root of all robotic parts. -To interact with the Robot API with Viam's SDKs, instantiate a `RobotClient` ([gRPC](https://grpc.io/) client) and use that class for all interactions. +### Robot API -### DiscoverComponents +All robots support the following methods through the [robot API](/program/apis/robot/): -Get a list of discovered component configurations. +{{< readfile "/static/include/services/apis/robot.md" >}} -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `queries` [(List [viam.proto.robot.DiscoveryQuery])](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.DiscoveryQuery): A list of [tuples of API and model](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.DiscoveryQuery) that you want to retrieve the component configurations corresponding to. - -**Returns:** - -- [(List[viam.proto.robot.Discovery])](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.Discovery): The list of discovered component configurations corresponding to `queries`. - -``` python -# Define a new discovery query. -q = robot.DiscoveryQuery(subtype=acme.API, model="some model") - -# Define a list of discovery queries. -qs = [q] - -# Get component configurations with these queries. -component_configs = await robot.discover_components(qs) -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.discover_components) - -{{% /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. -- `qs` [([]resource.DiscoveryQuery)](https://pkg.go.dev/go.viam.com/rdk/resource#DiscoveryQuery): A list of [tuples of API and model](https://pkg.go.dev/go.viam.com/rdk/resource#DiscoveryQuery) that you want to retrieve the component configurations corresponding to. - -**Returns:** - -- [([]resource.Discovery)](https://pkg.go.dev/go.viam.com/rdk/resource#Discovery): The search query `qs` and the corresponding list of discovered component configurations as an interface called `Results`. -`Results` may be comprised of primitives, a list of primitives, maps with string keys (or at least can be decomposed into one), or lists of the forementioned type of maps. -- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. - -```go -// Define a new discovery query. -q := resource.NewDiscoveryQuery(acme.API, resource.Model{Name: "some model"}) - -// Define a list of discovery queries. -qs := []resource.DiscoverQuery{q} - -// Get component configurations with these queries. -component_configs, err := robot.DiscoverComponents(ctx.Background(), qs) -``` - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -**Parameters:** - -- `queries` [(DiscoveryQuery[])](https://ts.viam.dev/classes/robotApi.DiscoveryQuery.html): An array of [tuples of API and model](https://ts.viam.dev/classes/robotApi.DiscoveryQuery.html#constructor) that you want to retrieve the component configurations corresponding to. - -**Returns:** - -- [(Discovery[])](https://ts.viam.dev/classes/robotApi.Discovery.html): List of discovered component configurations. - -```typescript -// Define a new discovery query. -const q = new proto.DiscoveryQuery(acme.API, resource.Model{Name: "some model"}) - -// Define an array of discovery queries. -let qs: proto.DiscoveryQuery[] = [q] - -// Get the array of discovered component configurations. -const componentConfigs = await robot.discoverComponents(queries); -``` - -For more information, see the [Typescript SDK Docs](https://ts.viam.dev/classes/RobotClient.html). - -{{% /tab %}} -{{< /tabs >}} - -### FrameSystemConfig - -Get the configuration of the frame system of a given robot. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `additional_transforms` [(Optional[List[viam.proto.common.Transform]])](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Transform): A optional list of [additional transforms](/services/frame-system/#additional-transforms). - -**Returns:** - -- `frame_system` [(List[FrameSystemConfig])](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.FrameSystemConfig): The configuration of a given robot’s frame system. - -```python {class="line-numbers linkable-line-numbers"} -# Get a list of each of the reference frames configured on the robot. -frame_system = await robot.get_frame_system_config() -print(f"frame system donfiguration: {frame_system}") -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_frame_system_config). - -{{% /tab %}} -{{% tab name="Go" %}} - -**Parameters:** +### Cloud API -- `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. -- [(framesystem.Config)](https://pkg.go.dev/go.viam.com/rdk/robot/framesystem#Config): The configuration of the given robot’s frame system. - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). - -```go {class="line-numbers linkable-line-numbers"} -// Print the frame system configuration -frameSystem, err := robot.FrameSystemConfig(context.Background(), nil) -fmt.Println(frameSystem) -``` - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -**Parameters:** - -- `transforms` [(Transform[])](https://ts.viam.dev/classes/commonApi.Transform.html): An optional array of [additional transforms](/services/frame-system/#additional-transforms). - -**Returns:** - -- [(FrameSystemConfig[])](https://ts.viam.dev/classes/robotApi.FrameSystemConfig.html): An array of individual parts that make up a robot's frame system. - -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. -console.log('FrameSytemConfig:', await robot.frameSystemConfig()); -``` - -{{% /tab %}} -{{< /tabs >}} - -### Status - -Get the status of the resources on the robot. -You can provide a list of ResourceNames for which you want statuses. -If no names are passed in, the status of every resource configured on the robot is returned. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `resourceNames` [(Optional[List[viam.proto.common.ResourceName]])](https://docs.python.org/library/typing.html#typing.Optional): An optional list of ResourceNames for components you want the status of. -If no names are passed in, all resource statuses are returned. - -**Returns:** - -- [(List[str])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): A list containing the status of each resource. +The [cloud API](/program/apis/cloud/) supports the following methods (among [others](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient)): -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_status). - -```python {class="line-numbers linkable-line-numbers"} -# Get the status of the resources on the robot. -statuses = await robot.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/resource#Name): An optional list of ResourceNames for components you want the status of. -If no names are passed in, all resource statuses are returned. - -**Returns:** - -- [([]Status)](https://pkg.go.dev/go.viam.com/rdk/robot#Status): Status of each resource. -- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). - -```go {class="line-numbers linkable-line-numbers"} -// Get the status of the resources on the robot. -status, err = robot.Status(ctx.Background()) -``` - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -**Parameters:** - -- `resourceNames` [(commonApi.ResourceName[])](https://ts.viam.dev/classes/commonApi.ResourceName.html): An optional array of ResourceNames for components you want the status of. -If no names are passed in, all resource statuses are returned. - -**Returns:** - -- [(robotApi.Status[])](https://ts.viam.dev/classes/robotApi.Status.html): An array containing the status of each resource. - -For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/RobotClient.html#transformPCD). - -```typescript {class="line-numbers linkable-line-numbers"} -// Get the status of the resources on the robot. -const status = await robot.getStatus(); -``` - -{{% /tab %}} -{{< /tabs >}} - -### Close - -Close the underlying connections and stop any periodic tasks across all constituent parts of the robot. -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- None - -**Returns:** - -- None - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.close). - -```python {class="line-numbers linkable-line-numbers"} -# Cleanly close the underlying connections and stop any periodic tasks. -await robot.close() -``` - -{{% /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. - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). - -```go {class="line-numbers linkable-line-numbers"} -// Cleanly close the underlying connections and stop any periodic tasks, -err := robot.Close(ctx.Background()) -``` - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -**Parameters:** - -- None - -**Returns:** - -- None - -For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/RobotClient.html#disconnect). - -```typescript {class="line-numbers linkable-line-numbers"} -// Cleanly close the underlying connections and stop any periodic tasks -await robot.disconnect(); -``` - -{{% /tab %}} -{{< /tabs >}} - -### StopAll - -Cancel all current and outstanding operations for the robot and stop all actuators and movement. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `extra` [(Dict[viam.proto.common.ResourceName, Dict[str, Any]])](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName): Any extra parameters to pass to the resources’ stop methods, keyed on each resource’s [`ResourceName`](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName). - -**Returns:** - -- None - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.stop_all). - -```python {class="line-numbers linkable-line-numbers"} -# Cancel all current and outstanding operations for the robot and stop all actuators and movement. -await robot.stop_all() -``` - -{{% /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. -- `extra` [(map[resource.Name]map[string]interface{})](https://pkg.go.dev/go.viam.com/rdk/resource#Name): Any extra parameters to pass to the resources’ stop methods, keyed on each resource’s [`Name`](https://pkg.go.dev/go.viam.com/rdk/resource#Name). - -**Returns:** - -- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). - -```go {class="line-numbers linkable-line-numbers"} -// Cancel all current and outstanding operations for the robot and stop all actuators and movement. -err := robot.StopAll(ctx.Background()) -``` - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -**Parameters:** - -- None - -**Returns:** - -- None - -For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/RobotClient.html#stopAll). - -```typescript {class="line-numbers linkable-line-numbers"} -// Cancel all current and outstanding operations for the robot and stop all actuators and movement. -await robot.stopAll(); -``` - -{{% /tab %}} -{{< /tabs >}} - -### ResourceNames - -Get a list of all known resource names connected to this robot. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- None - -**Returns:** - -- [(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 -resource_names = robot.resource_names -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -**Parameters:** - -- None - -**Returns:** - -- [([]resource.Name)](https://pkg.go.dev/go.viam.com/rdk/resource#Name): List of all known resource names. - -```go -resource_names := robot.ResourceNames() -``` - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -**Parameters:** - -- None - -**Returns:** - -- [(ResourceName.AsObject[])](https://ts.viam.dev/modules/commonApi.ResourceName-1.html): List of all known resource names. - -```typescript -// Get a list of all resources on the robot. -const resource_names = await robot.resourceNames(); -``` - -For more information, see the [Typescript SDK Docs](https://ts.viam.dev/classes/RobotClient.html). - -{{% /tab %}} -{{< /tabs >}} +{{< readfile "/static/include/services/apis/cloud.md" >}} diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md new file mode 100644 index 0000000000..459edc7203 --- /dev/null +++ b/docs/program/apis/cloud.md @@ -0,0 +1,219 @@ +--- +title: "Manage Your Fleet with Viam's Cloud API" +linkTitle: "Cloud Management" +weight: 20 +type: "docs" +description: "Use the cloud app API with Viam's client SDKs to manage your robot fleet with code." +tags: ["cloud", "sdk", "viam-server", "networking", "apis", "robot api", "cloud management"] +--- + +The cloud app API allows you to [manage your robot fleet](/manage/fleet/) with code instead of with the graphical interface of the [Viam app](https://app.viam.com/). +With it you can + +- create and manage organizations, locations, and individual robots +- manage permissions and authorization +- create and manage fragments + +{{% alert title="Support Notice" color="note" %}} + +Cloud app API methods are only available in the Python SDK. + +{{% /alert %}} + +## Establish a connection + +To use the Viam cloud app API, you first need to instantiate a [`ViamClient`](https://python.viam.dev/autoapi/viam/app/viam_client/index.html#viam.app.viam_client.ViamClient) and then instantiate an [`AppClient`](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient). +See the following example for reference. +To find the location secret, go to [Viam app](https://app.viam.com/), and go to the [**Code sample**](https://docs.viam.com/manage/fleet/robots/#code-sample) tab of any of the robots in the location. +Toggle **Include secret** on and copy the `payload`. +For the URL, use the address of any of the robots in the location (also found on the **Code sample** tab). + +```python {class="line-numbers linkable-line-numbers"} +import asyncio + +from viam.rpc.dial import DialOptions, Credentials +from viam.app.viam_client import ViamClient + +async def connect() -> ViamClient: + dial_options = DialOptions( + auth_entity='mrroboto.this_is_just_an_example.viam.cloud', # The URL of a robot in the location. + credentials=Credentials( + type='robot-location-secret', + payload='YOUR LOCATION SECRET' # The location secret + ) + ) + return await ViamClient.create_from_dial_options(dial_options) + +async def main(): + + # Make a ViamClient + viam_client = await connect() + # Instantiate an AppClient called "cloud" to run the cloud app API methods on + cloud = viam_client.app_client + + viam_client.close() + +if __name__ == '__main__': + asyncio.run(main()) +``` + +Once you have instantiated an `AppClient`, you can run the following [API methods](#api) against the `AppClient` object (named `cloud` in the examples). + +## API + +The cloud API supports the following methods (among [others](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient)): + +{{< readfile "/static/include/services/apis/cloud.md" >}} + +### ListOrganizations + +List the organizations the user is an authorized user of. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- None + +**Returns:** + +- [(List[viam.proto.app.Organization])](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Organization): A list of the organization or organizations of which the user is an authorized owner. + +```python {class="line-numbers linkable-line-numbers"} +org_list = await cloud.list_organizations() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.list_organizations). + +{{% /tab %}} +{{< /tabs >}} + +### ListOrganizationMembers + +List the members and invites of the organization that you are currently authenticated to. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- None + +**Returns:** + +- (Tuple[List[[viam.proto.app.OrganizationMember]](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.OrganizationMember)], List[[viam.proto.app.OrganizationInvite]](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.OrganizationInvite)): A tuple containing two lists: + - The first (`[0]`) is a list of organization members. + - The second (`[1]`) is a list of organization invites. + +```python {class="line-numbers linkable-line-numbers"} +member_list, invite_list = await cloud.list_organization_members() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.list_organization_members). + +{{% /tab %}} +{{< /tabs >}} + +### GetOrganizationNamespaceAvailability + +Check the availability of an organization namespace. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `public_namespace` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The organization namespace to check. +Namespaces can only contain lowercase alphanumeric and dash characters. + +**Raises:** + +- `GRPCError`: This error is raised if an invalid namespace (for example, `""`) is provided. + +**Returns:** + +- [(bool)](https://docs.python.org/3/library/stdtypes.html#bltin-boolean-values): `True` if the provided namespace is available. + +```python {class="line-numbers linkable-line-numbers"} +available = await cloud.get_organization_namespace_availability(public_namespace="my-cool-organization") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_organization_namespace_availability). + +{{% /tab %}} +{{< /tabs >}} + +### UpdateOrganizationInviteAuthorizations + +Update (add or remove) the authorizations attached to an organization invite that has already been created. +If an invitation has only one authorization and you want to remove it, delete the invitation instead of using this method. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `email` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Email of the user the invite was sent to. +- `add_authorizations` [(Optional[List[viam.proto.app.Authorization]])](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Authorization): Optional list of authorizations to add to the invite. +- `remove_authorizations` [(Optional[List[viam.proto.app.Authorization]])](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Authorization): Optional list of authorizations to remove from the invite. + +**Raises:** + +- `GRPCError`: This error is raised if no authorizations are passed or if an invalid combination of authorizations is passed (for example, an authorization to remove when the invite only contains one authorization). + +**Returns:** + +- [(OrganizationInvite)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.OrganizationInvite): The updated invitation. + +```python {class="line-numbers linkable-line-numbers"} +from viam.proto.app import Authorization +authorization_to_add=Authorization( + authorization_type="some type of auth", + authorization_id="identifier", + resource_type="abc", + resource_id="resource-identifier123", + identity_id="id12345", + organization_id="org_id_123" +) + +update_invite = await cloud.update_organization_invite_authorizations( + email="notarealemail@viam.com", + remove_authorizations=[authorization_to_add] +) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.update_organization_invite_authorizations). + +{{% /tab %}} +{{< /tabs >}} + +### NewRobot + +Create a new robot. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `name` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Name of the new robot. +- `location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to create the new robot in. + Defaults to the current authorized location. + +**Raises:** + +- `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation. + +**Returns:** + +- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The new robot's ID. + +```python {class="line-numbers linkable-line-numbers"} +new_robot_id = await cloud.new_robot(name="beepboop") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_organization_namespace_availability). + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/program/apis/robot.md b/docs/program/apis/robot.md new file mode 100644 index 0000000000..a64332015b --- /dev/null +++ b/docs/program/apis/robot.md @@ -0,0 +1,409 @@ +--- +title: "Manage Robots with Viam's Client SDKs" +linkTitle: "Robot Management" +weight: 20 +type: "docs" +description: "How to use the Robot API to monitor and manage your robots." +tags: ["robot state", "sdk", "apis", "robot api"] +--- + +The *robot API* is the application programming interface that manages each of your robots running `viam-server`. +It is the API for high level operations of each robot {{< glossary_tooltip term_id="part" text="part" >}}. +To interact with the robot API with Viam's SDKs, instantiate a `RobotClient` ([gRPC](https://grpc.io/) client) and use that class for all interactions. + +These are some of the supported robot API methods. For a full list [see GitHub](https://python.viam.dev/autoapi/viam/proto/robot/index.html#module-viam.proto.robot). + +{{< readfile "/static/include/services/apis/robot.md" >}} + +### DiscoverComponents + +Get a list of discovered component configurations. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `queries` [(List [viam.proto.robot.DiscoveryQuery])](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.DiscoveryQuery): A list of [tuples of API and model](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.DiscoveryQuery) that you want to retrieve the component configurations corresponding to. + +**Returns:** + +- [(List[viam.proto.robot.Discovery])](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.Discovery): The list of discovered component configurations corresponding to `queries`. + +``` python +# Define a new discovery query. +q = robot.DiscoveryQuery(subtype=acme.API, model="some model") + +# Define a list of discovery queries. +qs = [q] + +# Get component configurations with these queries. +component_configs = await robot.discover_components(qs) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.discover_components) + +{{% /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. +- `qs` [([]resource.DiscoveryQuery)](https://pkg.go.dev/go.viam.com/rdk/resource#DiscoveryQuery): A list of [tuples of API and model](https://pkg.go.dev/go.viam.com/rdk/resource#DiscoveryQuery) that you want to retrieve the component configurations corresponding to. + +**Returns:** + +- [([]resource.Discovery)](https://pkg.go.dev/go.viam.com/rdk/resource#Discovery): The search query `qs` and the corresponding list of discovered component configurations as an interface called `Results`. +`Results` may be comprised of primitives, a list of primitives, maps with string keys (or at least can be decomposed into one), or lists of the forementioned type of maps. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +```go +// Define a new discovery query. +q := resource.NewDiscoveryQuery(acme.API, resource.Model{Name: "some model"}) + +// Define a list of discovery queries. +qs := []resource.DiscoverQuery{q} + +// Get component configurations with these queries. +component_configs, err := robot.DiscoverComponents(ctx.Background(), qs) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `queries` [(DiscoveryQuery[])](https://ts.viam.dev/classes/robotApi.DiscoveryQuery.html): An array of [tuples of API and model](https://ts.viam.dev/classes/robotApi.DiscoveryQuery.html#constructor) that you want to retrieve the component configurations corresponding to. + +**Returns:** + +- [(Discovery[])](https://ts.viam.dev/classes/robotApi.Discovery.html): List of discovered component configurations. + +```typescript +// Define a new discovery query. +const q = new proto.DiscoveryQuery(acme.API, resource.Model{Name: "some model"}) + +// Define an array of discovery queries. +let qs: proto.DiscoveryQuery[] = [q] + +// Get the array of discovered component configurations. +const componentConfigs = await robot.discoverComponents(queries); +``` + +For more information, see the [Typescript SDK Docs](https://ts.viam.dev/classes/RobotClient.html). + +{{% /tab %}} +{{< /tabs >}} + +### FrameSystemConfig + +Get the configuration of the frame system of a given robot. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `additional_transforms` [(Optional[List[viam.proto.common.Transform]])](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Transform): A optional list of [additional transforms](/services/frame-system/#additional-transforms). + +**Returns:** + +- `frame_system` [(List[FrameSystemConfig])](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.FrameSystemConfig): The configuration of a given robot’s frame system. + +```python {class="line-numbers linkable-line-numbers"} +# Get a list of each of the reference frames configured on the robot. +frame_system = await robot.get_frame_system_config() +print(f"frame system donfiguration: {frame_system}") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_frame_system_config). + +{{% /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. +- [(framesystem.Config)](https://pkg.go.dev/go.viam.com/rdk/robot/framesystem#Config): The configuration of the given robot’s frame system. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). + +```go {class="line-numbers linkable-line-numbers"} +// Print the frame system configuration +frameSystem, err := robot.FrameSystemConfig(context.Background(), nil) +fmt.Println(frameSystem) +``` + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `transforms` [(Transform[])](https://ts.viam.dev/classes/commonApi.Transform.html): An optional array of [additional transforms](/services/frame-system/#additional-transforms). + +**Returns:** + +- [(FrameSystemConfig[])](https://ts.viam.dev/classes/robotApi.FrameSystemConfig.html): An array of individual parts that make up a robot's frame system. + +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. +console.log('FrameSytemConfig:', await robot.frameSystemConfig()); +``` + +{{% /tab %}} +{{< /tabs >}} + +### Status + +Get the status of the resources on the robot. +You can provide a list of ResourceNames for which you want statuses. +If no names are passed in, the status of every resource configured on the robot is returned. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `resourceNames` [(Optional[List[viam.proto.common.ResourceName]])](https://docs.python.org/library/typing.html#typing.Optional): An optional list of ResourceNames for components you want the status of. +If no names are passed in, all resource statuses are returned. + +**Returns:** + +- [(List[str])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): A list containing the status of each resource. + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_status). + +```python {class="line-numbers linkable-line-numbers"} +# Get the status of the resources on the robot. +statuses = await robot.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/resource#Name): An optional list of ResourceNames for components you want the status of. +If no names are passed in, all resource statuses are returned. + +**Returns:** + +- [([]Status)](https://pkg.go.dev/go.viam.com/rdk/robot#Status): Status of each resource. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). + +```go {class="line-numbers linkable-line-numbers"} +// Get the status of the resources on the robot. +status, err = robot.Status(ctx.Background()) +``` + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `resourceNames` [(commonApi.ResourceName[])](https://ts.viam.dev/classes/commonApi.ResourceName.html): An optional array of ResourceNames for components you want the status of. +If no names are passed in, all resource statuses are returned. + +**Returns:** + +- [(robotApi.Status[])](https://ts.viam.dev/classes/robotApi.Status.html): An array containing the status of each resource. + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/RobotClient.html#transformPCD). + +```typescript {class="line-numbers linkable-line-numbers"} +// Get the status of the resources on the robot. +const status = await robot.getStatus(); +``` + +{{% /tab %}} +{{< /tabs >}} + +### Close + +Close the underlying connections and stop any periodic tasks across all constituent parts of the robot. +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- None + +**Returns:** + +- None + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.close). + +```python {class="line-numbers linkable-line-numbers"} +# Cleanly close the underlying connections and stop any periodic tasks. +await robot.close() +``` + +{{% /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. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). + +```go {class="line-numbers linkable-line-numbers"} +// Cleanly close the underlying connections and stop any periodic tasks, +err := robot.Close(ctx.Background()) +``` + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- None + +**Returns:** + +- None + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/RobotClient.html#disconnect). + +```typescript {class="line-numbers linkable-line-numbers"} +// Cleanly close the underlying connections and stop any periodic tasks +await robot.disconnect(); +``` + +{{% /tab %}} +{{< /tabs >}} + +### StopAll + +Cancel all current and outstanding operations for the robot and stop all actuators and movement. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `extra` [(Dict[viam.proto.common.ResourceName, Dict[str, Any]])](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName): Any extra parameters to pass to the resources’ stop methods, keyed on each resource’s [`ResourceName`](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName). + +**Returns:** + +- None + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.stop_all). + +```python {class="line-numbers linkable-line-numbers"} +# Cancel all current and outstanding operations for the robot and stop all actuators and movement. +await robot.stop_all() +``` + +{{% /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. +- `extra` [(map[resource.Name]map[string]interface{})](https://pkg.go.dev/go.viam.com/rdk/resource#Name): Any extra parameters to pass to the resources’ stop methods, keyed on each resource’s [`Name`](https://pkg.go.dev/go.viam.com/rdk/resource#Name). + +**Returns:** + +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). + +```go {class="line-numbers linkable-line-numbers"} +// Cancel all current and outstanding operations for the robot and stop all actuators and movement. +err := robot.StopAll(ctx.Background()) +``` + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- None + +**Returns:** + +- None + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/RobotClient.html#stopAll). + +```typescript {class="line-numbers linkable-line-numbers"} +// Cancel all current and outstanding operations for the robot and stop all actuators and movement. +await robot.stopAll(); +``` + +{{% /tab %}} +{{< /tabs >}} + +### ResourceNames + +Get a list of all known resource names connected to this robot. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- None + +**Returns:** + +- [(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 +resource_names = robot.resource_names +``` + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- None + +**Returns:** + +- [([]resource.Name)](https://pkg.go.dev/go.viam.com/rdk/resource#Name): List of all known resource names. + +```go +resource_names := robot.ResourceNames() +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#Robot). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- None + +**Returns:** + +- [(ResourceName.AsObject[])](https://ts.viam.dev/modules/commonApi.ResourceName-1.html): List of all known resource names. + +```typescript +// Get a list of all resources on the robot. +const resource_names = await robot.resourceNames(); +``` + +For more information, see the [Typescript SDK Docs](https://ts.viam.dev/classes/RobotClient.html). + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/services/robot-service.md b/docs/services/robot-service.md index 114d2c6f30..e23f1175a7 100644 --- a/docs/services/robot-service.md +++ b/docs/services/robot-service.md @@ -8,8 +8,11 @@ weight: 10 tags: ["robot state", "services"] # SME: Cheuk --- -Robot Service constitutes a minimal set of APIs that most robots (Viam Server, [Viam Python SDK](https://python.viam.dev/) and various SDKs) should support. -Users will likely use the Robot Service as an entrypoint to interact with Viam robots and provide a way to get updates from the robot as a whole. + +The Robot Service refers to the minimum set of APIs that most robots running `viam-server` support. +This means that any of the various robot clients in Viam, like the Python SDK, Go Client SDK, or modular resources, should also support methods to interface with these same APIs from the client (instead of server) side. +If you are implementing your own client, keep this in mind. +Use the Robot Service as an entrypoint to interact with Viam robots and provide a way to get updates from the robot as a whole. The below is a current list of interfaces provided by the Robot Service. diff --git a/static/include/services/apis/cloud-temporary.md b/static/include/services/apis/cloud-temporary.md new file mode 100644 index 0000000000..3aaba3de1d --- /dev/null +++ b/static/include/services/apis/cloud-temporary.md @@ -0,0 +1,44 @@ +Method Name | Description +----------- | ----------- +[`ListOrganizations`](/program/apis/cloud/#listorganizations) | List the organizations the user owns. +[`GetOrganizationNamespaceAvailability`](/program/apis/cloud/#getorganizationnamespaceavailability) | Check the availability of an organization namespace. +[`ListOrganizationMembers`](/program/apis/cloud/#listorganizationmembers) | List the members and invites of the current organization. +[`UpdateOrganizationInviteAuthorizations`](/program/apis/cloud/#updateorganizationinviteauthorizations) | Update the authorizations attached to an organization invite that has already been created. +[`CreateLocation`](/program/apis/cloud/#createlocation) | +[`GetLocation`](/program/apis/cloud/#getlocation) | +[`UpdateLocation`](/program/apis/cloud/# ) | +[`DeleteLocation`](/program/apis/cloud/# ) | +[`ListLocations`](/program/apis/cloud/# ) | +[`LocationAuth`](/program/apis/cloud/# ) | +[`CreateLocationSecret`](/program/apis/cloud/# ) | +[`DeleteLocationSecret`](/program/apis/cloud/# ) | +[`GetRobot`](/program/apis/cloud/# ) | +[`GetRobotParts`](/program/apis/cloud/# ) | +[`GetRobotPart`](/program/apis/cloud/# ) | +[`GetRobotPartLogs`](/program/apis/cloud/# ) | +[`TailRobotPartLogs`](/program/apis/cloud/# ) | +[`GetRobotPartHistory`](/program/apis/cloud/# ) | +[`UpdateRobotPart`](/program/apis/cloud/# ) | +[`NewRobotPart`](/program/apis/cloud/# ) | +[`DeleteRobotPart`](/program/apis/cloud/# ) | +[`MarkPartAsMain`](/program/apis/cloud/# ) | +[`MarkPartForRestart`](/program/apis/cloud/# ) | +[`CreateRobotPartSecret`](/program/apis/cloud/# ) | +[`DeleteRobotPartSecret`](/program/apis/cloud/# ) | +[`ListRobots`](/program/apis/cloud/# ) | +[`NewRobot`](/program/apis/cloud/# ) | Create a new robot. +[`UpdateRobot`](/program/apis/cloud/# ) | +[`DeleteRobot`](/program/apis/cloud/# ) | +[`ListFragments`](/program/apis/cloud/# ) | +[`GetFragment`](/program/apis/cloud/# ) | +[`CreateFragment`](/program/apis/cloud/# ) | +[`UpdateFragment`](/program/apis/cloud/# ) | +[`DeleteFragment`](/program/apis/cloud/# ) | +[`AddRole`](/program/apis/cloud/# ) | +[`RemoveRole`](/program/apis/cloud/# ) | +[`ListAuthorizations`](/program/apis/cloud/# ) | +[`CreateModule`](/program/apis/cloud/# ) | +[`UpdateModule`](/program/apis/cloud/# ) | +[`UploadModuleFile`](/program/apis/cloud/# ) | +[`GetModule`](/program/apis/cloud/# ) | +[`ListModules`](/program/apis/cloud/# ) | diff --git a/static/include/services/apis/cloud.md b/static/include/services/apis/cloud.md new file mode 100644 index 0000000000..11c1df13e4 --- /dev/null +++ b/static/include/services/apis/cloud.md @@ -0,0 +1,7 @@ +Method Name | Description +----------- | ----------- +[`ListOrganizations`](/program/apis/cloud/#listorganizations) | List the organizations the user owns. +[`GetOrganizationNamespaceAvailability`](/program/apis/cloud/#getorganizationnamespaceavailability) | Check the availability of an organization namespace. +[`ListOrganizationMembers`](/program/apis/cloud/#listorganizationmembers) | List the members and invites of the current organization. +[`UpdateOrganizationInviteAuthorizations`](/program/apis/cloud/#updateorganizationinviteauthorizations) | Update the authorizations attached to an organization invite that has already been created. +[`NewRobot`](/program/apis/cloud/# ) | Create a new robot. diff --git a/static/include/services/apis/robot.md b/static/include/services/apis/robot.md new file mode 100644 index 0000000000..51ff8cf424 --- /dev/null +++ b/static/include/services/apis/robot.md @@ -0,0 +1,8 @@ +Method Name | Description +----------- | ----------- +[`DiscoverComponents`](/program/apis/robot/#discovercomponents) | Get a list of discovered component configurations. +[`FrameSystemConfig`](/program/apis/robot/#framesystemconfig) | Get the configuration of a robot's frame system. +[`Status`](/program/apis/robot/#status) | Get the status of each of the resources on the robot. +[`Close`](/program/apis/robot/#close) | Close the connections and stop periodic tasks across the robot. +[`StopAll`](/program/apis/robot/#stopall) | Cancel all operations for the robot and stop its movement. +[`ResourceNames`](/program/apis/robot/#resourcenames) | Get a list of all the robot's resources. diff --git a/static/include/services/apis/sensors.md b/static/include/services/apis/sensors.md index fbaee0dfcd..060e3de7be 100644 --- a/static/include/services/apis/sensors.md +++ b/static/include/services/apis/sensors.md @@ -1,4 +1,4 @@ Method Name | Description ----------- | ----------- -[`GetSensors`](/services/sensors/#getsensors) | Returns a list of names of the available sensors. -[`GetReadings`](/services/sensors/#getreadings) | Returns a list of readings from a given list of sensors. +[`GetSensors`](/services/sensors/#getsensors) | Return a list of names of the available sensors. +[`GetReadings`](/services/sensors/#getreadings) | Return a list of readings from a given list of sensors.