diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml index bb16d89bc3..ec43607107 100644 --- a/dartdoc_options.yaml +++ b/dartdoc_options.yaml @@ -1,7 +1,10 @@ dartdoc: categories: + "Viam SDK": + markdown: doc/ViamSDK.md + name: Viam SDK "Protobuf Definitions": markdown: doc/Protobuf.md name: Protobuf Definitions - categoryOrder: ["Protobuf Definitions"] - nodoc: ['**/di/**', '**/domain/**'] + categoryOrder: ["Viam SDK", "Protobuf Definitions"] + nodoc: ["**/di/**", "**/domain/**"] diff --git a/doc/ViamSDK.md b/doc/ViamSDK.md new file mode 100644 index 0000000000..beb132ba56 --- /dev/null +++ b/doc/ViamSDK.md @@ -0,0 +1,3 @@ +# Viam SDK Library + +Smart machines on smart devices. diff --git a/lib/src/app/data.dart b/lib/src/app/data.dart index b9952c86da..b5f3704bf6 100644 --- a/lib/src/app/data.dart +++ b/lib/src/app/data.dart @@ -14,6 +14,7 @@ import '../gen/app/datasync/v1/data_sync.pbgrpc.dart' hide CaptureInterval; import '../gen/google/protobuf/timestamp.pb.dart'; import '../media/image.dart'; +/// {@category Viam SDK} typedef DatabaseConnection = GetDatabaseConnectionResponse; /// gRPC client used for retrieving, uploading, and modifying stored data from app.viam.com. @@ -532,6 +533,7 @@ class DataClient { } } +/// {@category Viam SDK} extension FilterUtils on Filter { /// Return a [Filter] with a [CaptureInterval] created by the provided start and end [DateTime] objects Filter withDateTimeCaptureInterval({DateTime? start, DateTime? end}) { diff --git a/lib/src/app/permissions.dart b/lib/src/app/permissions.dart index 29cab7e375..53e75a1116 100644 --- a/lib/src/app/permissions.dart +++ b/lib/src/app/permissions.dart @@ -1,5 +1,6 @@ import '../gen/app/v1/app.pbgrpc.dart' as proto; +/// {@category Viam SDK} enum AuthorizationId { organizationOwner, organizationOperator, @@ -15,6 +16,7 @@ enum AuthorizationId { } } +/// {@category Viam SDK} enum IdentityType { user, apiKey; @@ -26,8 +28,10 @@ enum IdentityType { } } +/// {@category Viam SDK} enum ResourceType { location, organization, robot } +/// {@category Viam SDK} enum Permission { readOrganization, writeOrganization, @@ -52,6 +56,7 @@ enum Permission { } } +/// {@category Viam SDK} class ViamAuthorization { String authorizationType; diff --git a/lib/src/app/provisioning.dart b/lib/src/app/provisioning.dart index afb178d0eb..444b0c7a0a 100644 --- a/lib/src/app/provisioning.dart +++ b/lib/src/app/provisioning.dart @@ -2,8 +2,10 @@ import 'dart:async'; import '../gen/provisioning/v1/provisioning.pbgrpc.dart'; +/// {@category Viam SDK} enum NetworkType { wifi, wired } +/// {@category Viam SDK} /// gRPC client for connecting to Viam's Provisioning Service /// /// All calls must be authenticated. diff --git a/lib/src/app/robot.dart b/lib/src/app/robot.dart index 4f97026c40..0b71c69b66 100644 --- a/lib/src/app/robot.dart +++ b/lib/src/app/robot.dart @@ -6,6 +6,7 @@ import 'package:viam_sdk/src/gen/google/protobuf/timestamp.pb.dart'; import '../gen/app/v1/robot.pbgrpc.dart'; import '../gen/common/v1/common.pb.dart'; +/// {@category Viam SDK} /// gRPC client for connecting to app's RobotService. /// /// All calls must be authenticated. diff --git a/lib/src/components/arm/arm.dart b/lib/src/components/arm/arm.dart index 7141e147a0..7a1e320413 100644 --- a/lib/src/components/arm/arm.dart +++ b/lib/src/components/arm/arm.dart @@ -2,6 +2,7 @@ import '../../gen/common/v1/common.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} /// Arm represents a physical robot arm that exists in three-dimensional space. /// /// For more information, see [Arm component](https://docs.viam.com/components/arm/). diff --git a/lib/src/components/arm/client.dart b/lib/src/components/arm/client.dart index c97e89880e..55bc023592 100644 --- a/lib/src/components/arm/client.dart +++ b/lib/src/components/arm/client.dart @@ -7,6 +7,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'arm.dart'; +/// {@category Viam SDK} /// gRPC client for an [Arm] component. /// /// Used to communicate with an existing [Arm] implementation over gRPC. diff --git a/lib/src/components/base/base.dart b/lib/src/components/base/base.dart index 56442e8152..7f74dd1318 100644 --- a/lib/src/components/base/base.dart +++ b/lib/src/components/base/base.dart @@ -3,8 +3,10 @@ import '../../gen/component/base/v1/base.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} typedef BaseProperties = GetPropertiesResponse; +/// {@category Viam SDK} /// Base represents a physical base of a robot. /// /// For more information, see [Base component](https://docs.viam.com/components/base/). diff --git a/lib/src/components/base/client.dart b/lib/src/components/base/client.dart index af902aade1..b9a51fda7e 100644 --- a/lib/src/components/base/client.dart +++ b/lib/src/components/base/client.dart @@ -8,6 +8,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'base.dart'; +/// {@category Viam SDK} /// gRPC client for the [Base] component. class BaseClient extends Base implements ResourceRPCClient { @override diff --git a/lib/src/components/board/board.dart b/lib/src/components/board/board.dart index 680c7b04a6..d13760b2e7 100644 --- a/lib/src/components/board/board.dart +++ b/lib/src/components/board/board.dart @@ -5,10 +5,14 @@ import '../../gen/component/board/v1/board.pbgrpc.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} /// Tick of a digital interrupt typedef Tick = StreamTicksResponse; + +/// {@category Viam SDK} typedef AnalogValue = ReadAnalogReaderResponse; +/// {@category Viam SDK} /// Board represents a physical general purpose compute board that contains various /// components such as analog readers, and digital interrupts. /// diff --git a/lib/src/components/board/client.dart b/lib/src/components/board/client.dart index f10c14e3d7..2198c69a9b 100644 --- a/lib/src/components/board/client.dart +++ b/lib/src/components/board/client.dart @@ -12,6 +12,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'board.dart'; +/// {@category Viam SDK} /// gRPC client for the [Board] component. class BoardClient extends Board implements ResourceRPCClient { @override diff --git a/lib/src/components/camera/camera.dart b/lib/src/components/camera/camera.dart index 195520c1b2..e4055244eb 100644 --- a/lib/src/components/camera/camera.dart +++ b/lib/src/components/camera/camera.dart @@ -4,9 +4,11 @@ import '../../media/image.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} /// The camera's supported features and settings typedef CameraProperties = GetPropertiesResponse; +/// {@category Viam SDK} /// Camera represents any physical hardware that can capture frames. /// /// For more information, see [Camera component](https://docs.viam.com/components/camera/). diff --git a/lib/src/components/camera/client.dart b/lib/src/components/camera/client.dart index e4364c0cc9..d9cb0c34f0 100644 --- a/lib/src/components/camera/client.dart +++ b/lib/src/components/camera/client.dart @@ -8,6 +8,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'camera.dart'; +/// {@category Viam SDK} /// gRPC client for the [Camera] component class CameraClient extends Camera implements ResourceRPCClient { @override diff --git a/lib/src/components/gantry/client.dart b/lib/src/components/gantry/client.dart index 056c40f166..dd088fcee9 100644 --- a/lib/src/components/gantry/client.dart +++ b/lib/src/components/gantry/client.dart @@ -7,6 +7,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'gantry.dart'; +/// {@category Viam SDK} /// gRPC client for the [Gantry] component. class GantryClient extends Gantry implements ResourceRPCClient { @override diff --git a/lib/src/components/gantry/gantry.dart b/lib/src/components/gantry/gantry.dart index 05e1d87b16..75b80df8d9 100644 --- a/lib/src/components/gantry/gantry.dart +++ b/lib/src/components/gantry/gantry.dart @@ -2,6 +2,7 @@ import '../../gen/common/v1/common.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} /// Gantry represents a physical Gantry and can be used for controlling gantries of N axes. /// /// For more information, see [Gantry component](https://docs.viam.com/components/gantry/). diff --git a/lib/src/components/generic/client.dart b/lib/src/components/generic/client.dart index 0b324284a0..c6f4fd6de2 100644 --- a/lib/src/components/generic/client.dart +++ b/lib/src/components/generic/client.dart @@ -6,6 +6,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'generic.dart'; +/// {@category Viam SDK} /// gRPC client for the [Generic] component. class GenericClient extends Generic implements ResourceRPCClient { @override diff --git a/lib/src/components/generic/generic.dart b/lib/src/components/generic/generic.dart index 759ed4f169..c6f39f9cc9 100644 --- a/lib/src/components/generic/generic.dart +++ b/lib/src/components/generic/generic.dart @@ -2,6 +2,7 @@ import '../../gen/common/v1/common.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} /// Generic represents a generic component that executes doCommand. /// /// For more information, see [Generic component](https://docs.viam.com/components/generic/). diff --git a/lib/src/components/gripper/client.dart b/lib/src/components/gripper/client.dart index bb81b0bc04..0c33d66e5e 100644 --- a/lib/src/components/gripper/client.dart +++ b/lib/src/components/gripper/client.dart @@ -7,6 +7,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'gripper.dart'; +/// {@category Viam SDK} /// gRPC client for the [Gripper] component. class GripperClient extends Gripper implements ResourceRPCClient { @override diff --git a/lib/src/components/gripper/gripper.dart b/lib/src/components/gripper/gripper.dart index d723d9eded..5eb2573be3 100644 --- a/lib/src/components/gripper/gripper.dart +++ b/lib/src/components/gripper/gripper.dart @@ -2,6 +2,7 @@ import '../../gen/common/v1/common.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} /// Gripper represents a physical Gripper which can open and close. /// /// For more information, see [Gripper component](https://docs.viam.com/components/gripper/). diff --git a/lib/src/components/motor/client.dart b/lib/src/components/motor/client.dart index 37092b059e..9dfba0deb2 100644 --- a/lib/src/components/motor/client.dart +++ b/lib/src/components/motor/client.dart @@ -7,6 +7,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'motor.dart'; +/// {@category Viam SDK} /// gRPC client for the [Motor] component. class MotorClient extends Motor implements ResourceRPCClient { @override diff --git a/lib/src/components/motor/motor.dart b/lib/src/components/motor/motor.dart index fb12edc32c..90799a6cf7 100644 --- a/lib/src/components/motor/motor.dart +++ b/lib/src/components/motor/motor.dart @@ -3,8 +3,10 @@ import '../../gen/component/motor/v1/motor.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} typedef MotorProperties = GetPropertiesResponse; +/// {@category Viam SDK} class PowerState { bool isOn; double powerPct; @@ -16,6 +18,7 @@ class PowerState { } } +/// {@category Viam SDK} /// Motor represents a physical motor. /// /// For more information, see [Motor component](https://docs.viam.com/components/motor/). diff --git a/lib/src/components/movement_sensor/client.dart b/lib/src/components/movement_sensor/client.dart index ef1b6196f4..f76cb004a7 100644 --- a/lib/src/components/movement_sensor/client.dart +++ b/lib/src/components/movement_sensor/client.dart @@ -7,6 +7,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'movement_sensor.dart'; +/// {@category Viam SDK} /// gRPC client for the [MovementSensor] component. class MovementSensorClient extends MovementSensor implements ResourceRPCClient { @override diff --git a/lib/src/components/movement_sensor/movement_sensor.dart b/lib/src/components/movement_sensor/movement_sensor.dart index 767a97009e..0f30074446 100644 --- a/lib/src/components/movement_sensor/movement_sensor.dart +++ b/lib/src/components/movement_sensor/movement_sensor.dart @@ -3,6 +3,7 @@ import '../../gen/component/movementsensor/v1/movementsensor.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} class Position { GeoPoint coordinates; double altitude; @@ -10,9 +11,13 @@ class Position { Position(this.coordinates, this.altitude); } +/// {@category Viam SDK} typedef Properties = GetPropertiesResponse; + +/// {@category Viam SDK} typedef Accuracy = GetAccuracyResponse; +/// {@category Viam SDK} /// MovementSensor reports information about the robot's direction, position and speed. /// /// For more information, see [Movement Sensor component](https://docs.viam.com/components/movement-sensor/). diff --git a/lib/src/components/power_sensor/client.dart b/lib/src/components/power_sensor/client.dart index 7fdb856113..736a5288e0 100644 --- a/lib/src/components/power_sensor/client.dart +++ b/lib/src/components/power_sensor/client.dart @@ -7,6 +7,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'power_sensor.dart'; +/// {@category Viam SDK} /// gRPC client for the [PowerSensor] component. class PowerSensorClient extends PowerSensor implements ResourceRPCClient { @override diff --git a/lib/src/components/power_sensor/power_sensor.dart b/lib/src/components/power_sensor/power_sensor.dart index d8edafa969..8c509aa6ea 100644 --- a/lib/src/components/power_sensor/power_sensor.dart +++ b/lib/src/components/power_sensor/power_sensor.dart @@ -3,9 +3,13 @@ import '../../gen/component/powersensor/v1/powersensor.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} typedef Voltage = GetVoltageResponse; + +/// {@category Viam SDK} typedef Current = GetCurrentResponse; +/// {@category Viam SDK} /// PowerSensor reports information about voltage, current, and power. /// /// For more information, see [Power Sensor component](https://docs.viam.com/components/power-sensor/). diff --git a/lib/src/components/sensor/client.dart b/lib/src/components/sensor/client.dart index cdcaea78a9..27d6867b75 100644 --- a/lib/src/components/sensor/client.dart +++ b/lib/src/components/sensor/client.dart @@ -7,6 +7,7 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'sensor.dart'; +/// {@category Viam SDK} /// gRPC client for the [Sensor] component. class SensorClient extends Sensor implements ResourceRPCClient { @override diff --git a/lib/src/components/sensor/sensor.dart b/lib/src/components/sensor/sensor.dart index fd72561654..27044d0659 100644 --- a/lib/src/components/sensor/sensor.dart +++ b/lib/src/components/sensor/sensor.dart @@ -2,6 +2,8 @@ import '../../gen/common/v1/common.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} + /// Sensor represents a physical sensing device that can provide measurement readings. /// /// For more information, see [Sensor component](https://docs.viam.com/components/sensor/). diff --git a/lib/src/components/servo/client.dart b/lib/src/components/servo/client.dart index 41b127694a..bb99a0213b 100644 --- a/lib/src/components/servo/client.dart +++ b/lib/src/components/servo/client.dart @@ -7,6 +7,8 @@ import '../../resource/base.dart'; import '../../utils.dart'; import 'servo.dart'; +/// {@category Viam SDK} + /// gRPC client for the [Servo] component. class ServoClient extends Servo implements ResourceRPCClient { @override diff --git a/lib/src/components/servo/servo.dart b/lib/src/components/servo/servo.dart index 8b05214ebf..e79f3f8eed 100644 --- a/lib/src/components/servo/servo.dart +++ b/lib/src/components/servo/servo.dart @@ -2,6 +2,7 @@ import '../../gen/common/v1/common.pb.dart'; import '../../resource/base.dart'; import '../../robot/client.dart'; +/// {@category Viam SDK} /// Servo represents a physical servo. /// /// For more information, see [Servo component](https://docs.viam.com/components/servo/). diff --git a/lib/src/media/image.dart b/lib/src/media/image.dart index 8aad08a19f..9f4af0fe6d 100644 --- a/lib/src/media/image.dart +++ b/lib/src/media/image.dart @@ -3,6 +3,7 @@ import 'dart:typed_data'; import 'package:image/image.dart' as img; +/// {@category Viam SDK} /// Mime types supported by Viam class MimeType { final String _type; @@ -89,6 +90,7 @@ class MimeType { } } +/// {@category Viam SDK} /// A custom image type that contains the [MimeTYpe], raw image data, and lazily loads and caches an [img.Image]. class ViamImage { /// The mimetype of the image diff --git a/lib/src/media/stream/client.dart b/lib/src/media/stream/client.dart index 31eafb3b3c..f834a54e9f 100644 --- a/lib/src/media/stream/client.dart +++ b/lib/src/media/stream/client.dart @@ -131,6 +131,7 @@ class StreamManager { } } +/// {@category Viam SDK} /// A client to manage a camera's WebRTC stream. /// /// Use the [getStream] method to obtain a stream of [MediaStream] that can be used to display WebRTC video. diff --git a/lib/src/resource/base.dart b/lib/src/resource/base.dart index 9a2eefb793..f85b13da00 100644 --- a/lib/src/resource/base.dart +++ b/lib/src/resource/base.dart @@ -3,15 +3,19 @@ import 'package:grpc/grpc_connection_interface.dart'; import '../gen/common/v1/common.pb.dart'; +/// {@category Viam SDK} /// The standard namespace for Viam resources (rdk) const String resourceNamespaceRDK = 'rdk'; +/// {@category Viam SDK} /// The standard type for component resources (component) const String resourceTypeComponent = 'component'; +/// {@category Viam SDK} /// The standard type for service resources (service) const String resourceTypeService = 'service'; +/// {@category Viam SDK} /// [Subtype] defines a triplet of strings that correspond to a resource's specific API definition. class Subtype { /// The namespace of the subtype @@ -61,6 +65,7 @@ class Subtype { namespace == other.namespace && resourceType == other.resourceType && resourceSubtype == other.resourceSubtype; } +/// {@category Viam SDK} /// Abstract class that defines the base functionality for all [Resource] types abstract class Resource { abstract final String name; @@ -77,6 +82,7 @@ abstract class Resource { } } +/// {@category Viam SDK} /// Abstract class that defines the base functionality for all RPC clients for resources abstract class ResourceRPCClient { abstract ClientChannelBase channel; diff --git a/lib/src/resource/registry.dart b/lib/src/resource/registry.dart index 3200c3de28..cbd2840fdc 100644 --- a/lib/src/resource/registry.dart +++ b/lib/src/resource/registry.dart @@ -27,6 +27,7 @@ import '../components/servo/servo.dart'; import '../resource/base.dart'; import '../services/vision.dart'; +/// {@category Viam SDK} /// An object representing a resource to be registered. /// /// This object is generic over [Resource], and it includes various required functionality for the resource (e.g. creating an RPC client) @@ -41,6 +42,7 @@ class ResourceRegistration { ResourceRegistration(this.subtype, this.rpcClientCreator); } +/// {@category Viam SDK} /// The global registry of robot resources. /// /// **NB** The [Registry] should almost never be used directly. diff --git a/lib/src/robot/client.dart b/lib/src/robot/client.dart index 287a7e8558..9ced2aee0c 100644 --- a/lib/src/robot/client.dart +++ b/lib/src/robot/client.dart @@ -14,9 +14,11 @@ import '../resource/registry.dart'; import '../rpc/dial.dart'; import '../rpc/web_rtc/web_rtc_client.dart'; +/// {@category Viam SDK} typedef CloudMetadata = GetCloudMetadataResponse; Logger _logger = Logger(); +/// {@category Viam SDK} /// The options that define the behavior of the [RobotClient]. class RobotClientOptions { /// Options for connecting to the robot @@ -50,6 +52,7 @@ class RobotClientOptions { : dialOptions = DialOptions()..credentials = Credentials.locationSecret(locationSecret); } +/// {@category Viam SDK} /// gRPC client for a Robot. This class should be used for all interactions with a robot. /// /// Obtain an instance of this client by using the function: diff --git a/lib/src/rpc/dial.dart b/lib/src/rpc/dial.dart index c6be71178a..959794797d 100644 --- a/lib/src/rpc/dial.dart +++ b/lib/src/rpc/dial.dart @@ -25,6 +25,7 @@ Logger _newDialLogger(LogOutput? output) { var _logger = _newDialLogger(null); +/// {@category Viam SDK} /// Describes the behavior for connecting to a robot class DialOptions { /// Whether the RPC connection is TLS based @@ -67,6 +68,7 @@ class DialOptions { LogOutput? logOutput; } +/// {@category Viam SDK} /// The credentials used for connecting to the robot class Credentials { /// The type of credential, e.g. 'robot-location-secret', 'api-key' @@ -84,6 +86,7 @@ class Credentials { const Credentials.apiKey(this.payload) : type = 'api-key'; } +/// {@category Viam SDK} /// Options specific for connecting over WebRTC class DialWebRtcOptions { /// Whether to disable WebRTC. @@ -120,6 +123,7 @@ class DialWebRtcOptions { String? signalingAccessToken; } +/// {@category Viam SDK} /// Connect to a robot at the provided address with the given options Future dial(String address, DialOptions? options, String Function() sessionCallback) async { final opts = options ?? DialOptions(); @@ -567,6 +571,7 @@ Future _authenticatedChannel(String address, DialOptions o return AuthenticatedChannel(actual.host, actual.port, accessToken, options.insecure, sessionsCallback); } +/// {@category Viam SDK} /// A channel that attaches an access token to gRPC metadata for every call class AuthenticatedChannel extends ViamGrpcOrGrpcWebChannel { final String accessToken; diff --git a/lib/src/services/vision.dart b/lib/src/services/vision.dart index 4c864cd3e5..8b710f4b66 100644 --- a/lib/src/services/vision.dart +++ b/lib/src/services/vision.dart @@ -8,6 +8,7 @@ import '../resource/base.dart'; import '../robot/client.dart'; import '../utils.dart'; +/// {@category Viam SDK} class VisionClient extends Resource implements ResourceRPCClient { static const Subtype subtype = Subtype(resourceNamespaceRDK, resourceTypeService, 'vision'); diff --git a/lib/src/viam_sdk.dart b/lib/src/viam_sdk.dart index 69e59f1f7b..b6f18fb2d7 100644 --- a/lib/src/viam_sdk.dart +++ b/lib/src/viam_sdk.dart @@ -7,6 +7,7 @@ import './gen/app/v1/app.pbgrpc.dart'; import './robot/client.dart'; import './viam_sdk_impl.dart'; +/// {@category Viam SDK} /// An object to interact with the Viam app abstract class Viam { /// Create an authenticated Viam instance with the provided [accessToken]