From 62257edf1bf7e8bb39c9042742bd603ba77e4fe5 Mon Sep 17 00:00:00 2001 From: JessamyT Date: Thu, 24 Aug 2023 21:41:44 -0700 Subject: [PATCH 01/19] DOCS-908 pt1: move robot API and make stub doc --- docs/program/apis/_index.md | 396 +---------------------- docs/program/apis/cloud.md | 8 + docs/program/apis/robot.md | 410 ++++++++++++++++++++++++ docs/services/robot-service.md | 3 +- static/include/services/apis/robot.md | 8 + static/include/services/apis/sensors.md | 4 +- 6 files changed, 431 insertions(+), 398 deletions(-) create mode 100644 docs/program/apis/cloud.md create mode 100644 docs/program/apis/robot.md create mode 100644 static/include/services/apis/robot.md diff --git a/docs/program/apis/_index.md b/docs/program/apis/_index.md index 34e02c5eab..b4db35fa11 100644 --- a/docs/program/apis/_index.md +++ b/docs/program/apis/_index.md @@ -344,398 +344,4 @@ In addition to the [board API](#board), the [board component](/components/board/ ## Robot API -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. - -### 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 >}} +{{< readfile "/static/include/services/apis/robot.md" >}} diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md new file mode 100644 index 0000000000..146dd06d83 --- /dev/null +++ b/docs/program/apis/cloud.md @@ -0,0 +1,8 @@ +--- +title: "Accessing the Cloud with Viam's Client SDKs" +linkTitle: "Cloud Management" +weight: 20 +type: "docs" +description: "How to use the cloud API with Viam's client SDKs." +tags: ["cloud", "sdk", "viam-server", "networking", "apis", "robot api", "cloud management"] +--- \ No newline at end of file diff --git a/docs/program/apis/robot.md b/docs/program/apis/robot.md new file mode 100644 index 0000000000..9fe9709208 --- /dev/null +++ b/docs/program/apis/robot.md @@ -0,0 +1,410 @@ +--- +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 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. + +The robot API supports the following methods: + +{{< 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 >}} \ No newline at end of file diff --git a/docs/services/robot-service.md b/docs/services/robot-service.md index 114d2c6f30..4b1f01eeff 100644 --- a/docs/services/robot-service.md +++ b/docs/services/robot-service.md @@ -3,11 +3,12 @@ title: "Robot Service" linkTitle: "Robot" description: "The Robot Service consists of a set of robot monitoring and management APIs that most robots support." type: "docs" -draft: "true" +draft: "false" 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. diff --git a/static/include/services/apis/robot.md b/static/include/services/apis/robot.md new file mode 100644 index 0000000000..eb7ccdca01 --- /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. From dad756e940761c799c889f861d9b92c4960111ce Mon Sep 17 00:00:00 2001 From: JessamyT Date: Fri, 25 Aug 2023 19:15:09 -0700 Subject: [PATCH 02/19] add some methods --- docs/program/apis/_index.md | 12 +- docs/program/apis/cloud.md | 188 +++++++++++++++++++++++++- static/include/services/apis/cloud.md | 44 ++++++ 3 files changed, 242 insertions(+), 2 deletions(-) create mode 100644 static/include/services/apis/cloud.md diff --git a/docs/program/apis/_index.md b/docs/program/apis/_index.md index b4db35fa11..def1cb778d 100644 --- a/docs/program/apis/_index.md +++ b/docs/program/apis/_index.md @@ -342,6 +342,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 + +### Robot API + +All robots support the following methods through the [robot API](/program/apis/robot/): {{< readfile "/static/include/services/apis/robot.md" >}} + +### Cloud API + +The [cloud API](/program/apis/cloud/) provides the following methods: + +{{< readfile "/static/include/services/apis/cloud.md" >}} diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 146dd06d83..ac20fab2df 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -5,4 +5,190 @@ weight: 20 type: "docs" description: "How to use the cloud API with Viam's client SDKs." tags: ["cloud", "sdk", "viam-server", "networking", "apis", "robot api", "cloud management"] ---- \ No newline at end of file +--- + +The cloud app API allows you to [manage your robot fleet](/manage/fleet/) with code instead of through the [Viam app](https://app.viam.com/). +Functionality includes: + +- create and manage organizations, locations, and individual robots +- manage permissions and authorization +- create and manage fragments + +{{% alert title="Support Notice" color="note" %}} + +As of August 24, 2023, the cloud app API is only available in Python. + +{{% /alert %}} + +## API + +{{% alert title="Tip" color="tip" %}} + +To use the Viam cloud app API, you 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): + +```python {class="line-numbers linkable-line-numbers"} +from viam.app.viam_client import ViamClient +from viam.app.app_client import AppClient + +# Make a ViamClient +viam_client = await ViamClient.create_from_dial_options(auth_entity = auth, credentials = creds) +# Instantiate an AppClient called "cloud" to run cloud app API methods on +cloud = await viam_client.app_client() +``` + +Then, you run the methods on the `AppClient` according to the code examples for each method below. + +{{% /alert %}} + +The cloud API supports the following methods: + +{{< 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 currently authenticated-to organization. + +{{< 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): A tuple containing to 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 = 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: An 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 the authorizations attached to an organization invite that has already been created. + +{{< 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_authorization` [(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_authorization` [(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: An 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"} +update_invite = await cloud.update_organization_invite_authorizations( + email="notarealemail@viam.com", + remove_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" + ] +) +``` + +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 under which to create the new robot. + Defaults to the current authorized location. + +**Raises:** + +- GRPCError: An error is raised if an invalid location ID is passed or 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 >}} \ No newline at end of file diff --git a/static/include/services/apis/cloud.md b/static/include/services/apis/cloud.md new file mode 100644 index 0000000000..3aaba3de1d --- /dev/null +++ b/static/include/services/apis/cloud.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/# ) | From 22bef29205e8d9cb7ae4543de09eacee91fd8887 Mon Sep 17 00:00:00 2001 From: JessamyT Date: Mon, 28 Aug 2023 12:58:21 -0700 Subject: [PATCH 03/19] Add interim link and newline --- docs/program/apis/cloud.md | 2 +- .../include/services/apis/cloud-temporary.md | 44 +++++++++++++++++++ static/include/services/apis/cloud.md | 40 ++--------------- 3 files changed, 48 insertions(+), 38 deletions(-) create mode 100644 static/include/services/apis/cloud-temporary.md diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index ac20fab2df..1e6a3d9b87 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -191,4 +191,4 @@ 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 >}} \ No newline at end of file +{{< /tabs >}} 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 index 3aaba3de1d..89712d1647 100644 --- a/static/include/services/apis/cloud.md +++ b/static/include/services/apis/cloud.md @@ -4,41 +4,7 @@ Method Name | Description [`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/# ) | + +**Many other methods are also part of the cloud API. +See the [Python SDK docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient) for a full list.** From 8d1bb78a05e5f4e3383a08c46f627f357c6a90bc Mon Sep 17 00:00:00 2001 From: JessamyT Date: Mon, 28 Aug 2023 14:46:55 -0700 Subject: [PATCH 04/19] Fix linter issues --- docs/program/apis/robot.md | 2 +- static/include/services/apis/robot.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/program/apis/robot.md b/docs/program/apis/robot.md index 9fe9709208..76249c08e0 100644 --- a/docs/program/apis/robot.md +++ b/docs/program/apis/robot.md @@ -407,4 +407,4 @@ const resource_names = await robot.resourceNames(); For more information, see the [Typescript SDK Docs](https://ts.viam.dev/classes/RobotClient.html). {{% /tab %}} -{{< /tabs >}} \ No newline at end of file +{{< /tabs >}} diff --git a/static/include/services/apis/robot.md b/static/include/services/apis/robot.md index eb7ccdca01..51ff8cf424 100644 --- a/static/include/services/apis/robot.md +++ b/static/include/services/apis/robot.md @@ -2,7 +2,7 @@ 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. +[`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. From e7a456d6f128bf87086584ebcf836c32766da30a Mon Sep 17 00:00:00 2001 From: JessamyT Date: Mon, 28 Aug 2023 15:10:17 -0700 Subject: [PATCH 05/19] improve connect code sample specificity --- docs/program/apis/cloud.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 1e6a3d9b87..bbd2a5c174 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -27,16 +27,28 @@ As of August 24, 2023, the cloud app API is only available in Python. To use the Viam cloud app API, you 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): ```python {class="line-numbers linkable-line-numbers"} +from viam.rpc.dial import DialOptions, Credentials from viam.app.viam_client import ViamClient -from viam.app.app_client import AppClient -# Make a ViamClient -viam_client = await ViamClient.create_from_dial_options(auth_entity = auth, credentials = creds) -# Instantiate an AppClient called "cloud" to run cloud app API methods on -cloud = await viam_client.app_client() +async def connect() -> ViamClient: + dial_options = DialOptions( + auth_entity='mrroboto.this_is_just_an_example.viam.cloud', # The URL of your robot. + credentials=Credentials( + type='robot-location-secret', + payload='YOUR ROBOT LOCATION SECRET' # The location secret of your robot + ) + ) + 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 = await viam_client.app_client() ``` -Then, you run the methods on the `AppClient` according to the code examples for each method below. +Then, run methods on the `AppClient` according to the code examples for each method below. {{% /alert %}} From 6f661122d096bd192fc927203e0219ef5e317f26 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Tue, 29 Aug 2023 20:32:07 -0700 Subject: [PATCH 06/19] Apply suggestions from code review Co-authored-by: Sierra Guequierre --- docs/program/apis/cloud.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index bbd2a5c174..64e985099c 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -1,5 +1,5 @@ --- -title: "Accessing the Cloud with Viam's Client SDKs" +title: "Managing Your Fleet with Viam's Cloud API" linkTitle: "Cloud Management" weight: 20 type: "docs" @@ -16,7 +16,7 @@ Functionality includes: {{% alert title="Support Notice" color="note" %}} -As of August 24, 2023, the cloud app API is only available in Python. +As of August 24, 2023, cloud app API methods are only available in the Python SDK. {{% /alert %}} From 999c1cb5a5b32d5deea59a6fc5bc765c2720a22d Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Wed, 30 Aug 2023 12:32:15 -0700 Subject: [PATCH 07/19] Apply suggestions from code review Co-authored-by: Sierra Guequierre --- docs/program/apis/cloud.md | 4 ++-- docs/services/robot-service.md | 8 +++++--- static/include/services/apis/cloud.md | 3 ++- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 64e985099c..3d23b3fc38 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -16,7 +16,7 @@ Functionality includes: {{% alert title="Support Notice" color="note" %}} -As of August 24, 2023, cloud app API methods are only available in the Python SDK. +Cloud app API methods are only available in the Python SDK. {{% /alert %}} @@ -82,7 +82,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ### ListOrganizationMembers -List the members and invites of the currently authenticated-to organization. +List the members and invites of the organization that you are currently authenticated to. {{< tabs >}} {{% tab name="Python" %}} diff --git a/docs/services/robot-service.md b/docs/services/robot-service.md index 4b1f01eeff..e23f1175a7 100644 --- a/docs/services/robot-service.md +++ b/docs/services/robot-service.md @@ -3,14 +3,16 @@ title: "Robot Service" linkTitle: "Robot" description: "The Robot Service consists of a set of robot monitoring and management APIs that most robots support." type: "docs" -draft: "false" +draft: "true" 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.md b/static/include/services/apis/cloud.md index 89712d1647..cee12b82eb 100644 --- a/static/include/services/apis/cloud.md +++ b/static/include/services/apis/cloud.md @@ -1,3 +1,5 @@ +See the [Python SDK docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient) for a full list.** + Method Name | Description ----------- | ----------- [`ListOrganizations`](/program/apis/cloud/#listorganizations) | List the organizations the user owns. @@ -7,4 +9,3 @@ Method Name | Description [`NewRobot`](/program/apis/cloud/# ) | Create a new robot. **Many other methods are also part of the cloud API. -See the [Python SDK docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient) for a full list.** From 70cde1d77e8b5eea2c01aed572171e9293919bd7 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Wed, 30 Aug 2023 12:44:29 -0700 Subject: [PATCH 08/19] Update docs/program/apis/cloud.md --- docs/program/apis/cloud.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 3d23b3fc38..b743625617 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -7,7 +7,7 @@ description: "How to use the cloud API with Viam's client SDKs." 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 through the [Viam app](https://app.viam.com/). +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/). Functionality includes: - create and manage organizations, locations, and individual robots From b1c0e41a7f3de87fefa779528a3c9cc54d5b7c43 Mon Sep 17 00:00:00 2001 From: JessamyT Date: Wed, 30 Aug 2023 17:14:01 -0700 Subject: [PATCH 09/19] Address feedback --- docs/program/apis/cloud.md | 12 ++++++------ static/include/services/apis/cloud.md | 3 +-- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index b743625617..525a4930bb 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -20,11 +20,11 @@ Cloud app API methods are only available in the Python SDK. {{% /alert %}} -## API - -{{% alert title="Tip" color="tip" %}} +## Establish a connection -To use the Viam cloud app API, you 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): +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. +You can find the location secret and the URL of your robot on the [Viam app](https://app.viam.com/): ```python {class="line-numbers linkable-line-numbers"} from viam.rpc.dial import DialOptions, Credentials @@ -48,9 +48,9 @@ async def main(): cloud = await viam_client.app_client() ``` -Then, run methods on the `AppClient` according to the code examples for each method below. +Once you have instantiated an `AppClient`, you can run methods against the `AppClient` object (named `cloud` in the examples) according to the examples for each method below. -{{% /alert %}} +## API The cloud API supports the following methods: diff --git a/static/include/services/apis/cloud.md b/static/include/services/apis/cloud.md index cee12b82eb..eeacf63bad 100644 --- a/static/include/services/apis/cloud.md +++ b/static/include/services/apis/cloud.md @@ -1,3 +1,4 @@ +**Many other methods are also part of the cloud API. See the [Python SDK docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient) for a full list.** Method Name | Description @@ -7,5 +8,3 @@ Method Name | Description [`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. - -**Many other methods are also part of the cloud API. From ea507434fdefe6f59761f391b48f18a3d09494fd Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Thu, 31 Aug 2023 12:20:02 -0700 Subject: [PATCH 10/19] Update docs/program/apis/cloud.md Co-authored-by: Sierra Guequierre --- docs/program/apis/cloud.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 525a4930bb..c4ef1e5406 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -185,7 +185,7 @@ Create a new robot. **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 under which to create 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:** From 7ef2ba9f08e9f0383dac04aa9c15d92ea6ae89ad Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Thu, 31 Aug 2023 13:49:50 -0700 Subject: [PATCH 11/19] Apply suggestions from code review --- docs/program/apis/cloud.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index c4ef1e5406..737c4fab23 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -24,7 +24,7 @@ Cloud app API methods are only available in the Python SDK. 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. -You can find the location secret and the URL of your robot on the [Viam app](https://app.viam.com/): +You can find the location secret and the URL of your robot on the **Code sample** tab in [Viam app](https://app.viam.com/): ```python {class="line-numbers linkable-line-numbers"} from viam.rpc.dial import DialOptions, Credentials @@ -120,7 +120,7 @@ Namespaces can only contain lowercase alphanumeric and dash characters. **Raises:** -- GRPCError: An error is raised if an invalid namespace (for example, `""`) is provided. +- `GRPCError`: This error is raised if an invalid namespace (for example, `""`) is provided. **Returns:** @@ -190,7 +190,7 @@ Create a new robot. **Raises:** -- GRPCError: An error is raised if an invalid location ID is passed or one isn't passed and no location ID was provided at `AppClient` instantiation. +- `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:** From 60c7c86f7c5949f42ca4c1ee52fb03341119f711 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Fri, 1 Sep 2023 12:33:07 -0700 Subject: [PATCH 12/19] Apply suggestions from code review Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> --- docs/program/apis/_index.md | 2 +- docs/program/apis/cloud.md | 17 +++++++++-------- static/include/services/apis/cloud.md | 3 --- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/program/apis/_index.md b/docs/program/apis/_index.md index def1cb778d..04c7bf75bd 100644 --- a/docs/program/apis/_index.md +++ b/docs/program/apis/_index.md @@ -352,6 +352,6 @@ All robots support the following methods through the [robot API](/program/apis/r ### Cloud API -The [cloud API](/program/apis/cloud/) provides the following methods: +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)): {{< readfile "/static/include/services/apis/cloud.md" >}} diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 737c4fab23..0d18e24b50 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -1,14 +1,14 @@ --- -title: "Managing Your Fleet with Viam's Cloud API" +title: "Manage Your Fleet with Viam's Cloud API" linkTitle: "Cloud Management" weight: 20 type: "docs" -description: "How to use the cloud API with Viam's client SDKs." +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/). -Functionality includes: +With it you can - create and manage organizations, locations, and individual robots - manage permissions and authorization @@ -24,7 +24,7 @@ Cloud app API methods are only available in the Python SDK. 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. -You can find the location secret and the URL of your robot on the **Code sample** tab in [Viam app](https://app.viam.com/): +You can find the location secret and the URL of your robot on the [**Code sample**](https://docs.viam.com/manage/fleet/robots/#code-sample) tab in [Viam app](https://app.viam.com/): ```python {class="line-numbers linkable-line-numbers"} from viam.rpc.dial import DialOptions, Credentials @@ -48,11 +48,11 @@ async def main(): cloud = await viam_client.app_client() ``` -Once you have instantiated an `AppClient`, you can run methods against the `AppClient` object (named `cloud` in the examples) according to the examples for each method below. +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: +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" >}} @@ -137,7 +137,8 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ### UpdateOrganizationInviteAuthorizations -Update the authorizations attached to an organization invite that has already been created. +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" %}} @@ -150,7 +151,7 @@ Update the authorizations attached to an organization invite that has already be **Raises:** -- GRPCError: An 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). +- `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:** diff --git a/static/include/services/apis/cloud.md b/static/include/services/apis/cloud.md index eeacf63bad..11c1df13e4 100644 --- a/static/include/services/apis/cloud.md +++ b/static/include/services/apis/cloud.md @@ -1,6 +1,3 @@ -**Many other methods are also part of the cloud API. -See the [Python SDK docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient) for a full list.** - Method Name | Description ----------- | ----------- [`ListOrganizations`](/program/apis/cloud/#listorganizations) | List the organizations the user owns. From 002d282d063fe209a6ec4b8f95fd2a223391d8e9 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Tue, 5 Sep 2023 11:26:12 -0700 Subject: [PATCH 13/19] Apply suggestions from code review Co-authored-by: Ethan --- docs/program/apis/cloud.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 0d18e24b50..2e3c64539e 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -45,7 +45,7 @@ async def main(): # Make a ViamClient viam_client = await connect() # Instantiate an AppClient called "cloud" to run the cloud app API methods on - cloud = await viam_client.app_client() + cloud = await viam_client.app_client ``` Once you have instantiated an `AppClient`, you can run the following [API methods](#api) against the `AppClient` object (named `cloud` in the examples). @@ -93,12 +93,12 @@ List the members and invites of the organization that you are currently authenti **Returns:** -- [(Tuple[List[viam.proto.app.OrganizationMember]])](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.OrganizationMember): A tuple containing to lists: +- (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 = await cloud.list_organization_members() +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). From f4f87e1b940a0ae7635a4ddf51977816122dbc26 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Wed, 6 Sep 2023 13:20:52 -0700 Subject: [PATCH 14/19] Fix connect code --- docs/program/apis/cloud.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 2e3c64539e..16ad38350f 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -24,7 +24,9 @@ Cloud app API methods are only available in the Python SDK. 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. -You can find the location secret and the URL of your robot on the [**Code sample**](https://docs.viam.com/manage/fleet/robots/#code-sample) tab in [Viam app](https://app.viam.com/): +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"} from viam.rpc.dial import DialOptions, Credentials @@ -32,10 +34,10 @@ 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 your robot. + 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 ROBOT LOCATION SECRET' # The location secret of your robot + payload='YOUR LOCATION SECRET' # The location secret ) ) return await ViamClient.create_from_dial_options(dial_options) @@ -45,7 +47,12 @@ async def main(): # Make a ViamClient viam_client = await connect() # Instantiate an AppClient called "cloud" to run the cloud app API methods on - cloud = await viam_client.app_client + 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). From 351a57921b9a19f9fb45d665a3dfe8ed7c40d433 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Wed, 6 Sep 2023 13:21:21 -0700 Subject: [PATCH 15/19] Fix connect code --- docs/program/apis/cloud.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 16ad38350f..652ea5be4b 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -29,6 +29,8 @@ 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 From 1fd8e08ac3d0a915cc5711d245e0f3edafdbbd36 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Wed, 6 Sep 2023 13:47:52 -0700 Subject: [PATCH 16/19] Fix authorizations typos --- docs/program/apis/cloud.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 652ea5be4b..459edc7203 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -155,8 +155,8 @@ If an invitation has only one authorization and you want to remove it, delete th **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_authorization` [(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_authorization` [(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. +- `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:** @@ -167,16 +167,19 @@ If an invitation has only one authorization and you want to remove it, delete th - [(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_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" - ] + remove_authorizations=[authorization_to_add] ) ``` From 267812ea2e39f3fb6971748c037f0cf8c19e9cad Mon Sep 17 00:00:00 2001 From: JessamyT Date: Wed, 6 Sep 2023 14:28:01 -0700 Subject: [PATCH 17/19] add no_list true to api overview page --- docs/program/apis/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/program/apis/_index.md b/docs/program/apis/_index.md index 04c7bf75bd..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). From 7eb173c3b565eeb5095e0c8ac49d358b9dcb8122 Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Thu, 7 Sep 2023 13:21:29 -0700 Subject: [PATCH 18/19] Apply suggestions from code review Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> --- docs/program/apis/robot.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/program/apis/robot.md b/docs/program/apis/robot.md index 76249c08e0..34f7b14ebf 100644 --- a/docs/program/apis/robot.md +++ b/docs/program/apis/robot.md @@ -7,14 +7,14 @@ 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 designated interface for a robot, the root of all robotic parts. +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. -The robot API supports the following methods: +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 From 414ac5dcdcad22ffd75d5f89ba0be7d86bf9d6ad Mon Sep 17 00:00:00 2001 From: JessamyT Date: Thu, 7 Sep 2023 13:39:32 -0700 Subject: [PATCH 19/19] fix multiple blank lines lint error --- docs/program/apis/robot.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/program/apis/robot.md b/docs/program/apis/robot.md index 34f7b14ebf..a64332015b 100644 --- a/docs/program/apis/robot.md +++ b/docs/program/apis/robot.md @@ -15,7 +15,6 @@ These are some of the supported robot API methods. For a full list [see GitHub]( {{< readfile "/static/include/services/apis/robot.md" >}} - ### DiscoverComponents Get a list of discovered component configurations.