Documentation (#98)

Author: njooma

lib/src/app/app.dart

@@ -2,59 +2,71 @@ import 'dart:async';
 
 import '../gen/app/v1/app.pbgrpc.dart';
 
+/// gRPC client for connecting to Viam's App Service
+///
+/// All calls must be authenticated.
 class AppClient {
   final AppServiceClient _client;
 
   AppClient(this._client);
 
+  /// List all the [Organization] the currently authenticated user has access to
   Future<List<Organization>> listOrganizations() async {
     final listOrganizationsRequest = ListOrganizationsRequest();
     final ListOrganizationsResponse response = await _client.listOrganizations(listOrganizationsRequest);
     return response.organizations;
   }
 
+  /// Get a specific [Organization] by ID
   Future<Organization> getOrganization(String organizationId) async {
     final getOrganizationRequest = GetOrganizationRequest()..organizationId = organizationId;
     final GetOrganizationResponse response = await _client.getOrganization(getOrganizationRequest);
     return response.organization;
   }
 
+  /// List the [Location] of a specific [Organization] that the currently authenticated user has access to
   Future<List<Location>> listLocations(Organization organization) async {
     final listLocationsRequest = ListLocationsRequest()..organizationId = organization.id;
     final ListLocationsResponse response = await _client.listLocations(listLocationsRequest);
     return response.locations;
   }
 
+  /// Get a specific [Location] by ID
   Future<Location> getLocation(String locationId) async {
     final getLocationRequest = GetLocationRequest()..locationId = locationId;
     final GetLocationResponse response = await _client.getLocation(getLocationRequest);
     return response.location;
   }
 
+  /// List the [Robot] of a specific [Location] that the currently authenticated user has access to
   Future<List<Robot>> listRobots(Location location) async {
     final listRobotsRequest = ListRobotsRequest()..locationId = location.id;
     final ListRobotsResponse response = await _client.listRobots(listRobotsRequest);
     return response.robots;
   }
 
+  /// Get a specific [Robot] by ID
   Future<Robot> getRobot(String robotId) async {
     final getRobotRequest = GetRobotRequest()..id = robotId;
     final GetRobotResponse response = await _client.getRobot(getRobotRequest);
     return response.robot;
   }
 
+  /// List the [RobotPart] of a specific [Robot] that the currently authenticated user has access to
   Future<List<RobotPart>> listRobotParts(Robot robot) async {
     final getRobotPartsRequest = GetRobotPartsRequest()..robotId = robot.id;
     final response = await _client.getRobotParts(getRobotPartsRequest);
     return response.parts;
   }
 
+  /// Get a specific [RobotPart] by ID
   Future<RobotPart> getRobotPart(String partId) async {
     final getRobotPartRequest = GetRobotPartRequest()..id = partId;
     final response = await _client.getRobotPart(getRobotPartRequest);
     return response.part;
   }
 
+  /// Get a stream of [LogEntry] for a specific [RobotPart]. Logs are sorted by descending time (newest first)
   Stream<List<LogEntry>> tailLogs(RobotPart part, {bool errorsOnly = false}) {
     final request = TailRobotPartLogsRequest()
       ..id = part.id

lib/src/app/data.dart

@@ -6,6 +6,8 @@ import 'package:viam_sdk/src/gen/google/protobuf/timestamp.pb.dart';
 import '../gen/app/data/v1/data.pbgrpc.dart';
 
 /// gRPC client for the [DataClient]. Used for retrieving stored data from app.viam.com.
+///
+/// All calls must be authenticated.
 class DataClient {
   final DataServiceClient _client;
 
@@ -106,11 +108,13 @@ class DataClient {
 }
 
 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}) {
     setDateTimeCaptureInterval(start: start, end: end);
     return this;
   }
 
+  /// Update the current [Filter] with a [CaptureInterval] created by the provided start and end [DateTime] objects
   void setDateTimeCaptureInterval({DateTime? start, DateTime? end}) {
     final interval = CaptureInterval();
     if (start != null) {

lib/src/errors.dart

@@ -1,3 +1,4 @@
+/// Error thrown with connection is lost
 class ConnectionLostError {
   final String? message;
 

lib/src/media/image.dart

@@ -3,6 +3,7 @@ import 'dart:typed_data';
 
 import 'package:image/image.dart' as img;
 
+/// Mime types supported by Viam
 class MimeType {
   final String _type;
   final String _name;
@@ -24,16 +25,27 @@ class MimeType {
 
   const MimeType._(this._type, this._name);
 
+  /// Viam's custom RGBA encoding (image/vnd.viam.rgba)
   static MimeType get viamRgba => const MimeType._('viamRgba', 'image/vnd.viam.rgba');
+
+  /// JPEG encoding (image/jpeg)
   static MimeType get jpeg => const MimeType._('jpeg', 'image/jpeg');
+
+  /// PNG encoding (image/png)
   static MimeType get png => const MimeType._('png', 'image/png');
+
+  /// PointCloud Data encoding (pointcloud/pcd)
   static MimeType get pcd => const MimeType._('pcd', 'pointcloud/pcd');
 
-  /// An unsupported MimeType takes in the String representation of the mimetype that is not supported.
+  /// An unsupported MimeType.
+  /// Takes in the String representation of the mimetype that is not supported.
   const MimeType.unsupported(this._name) : _type = 'unsupported';
 
+  /// Create a [MimeType] from its string representation.
+  /// Returns [MimeType.unsupported] if the provided string is not supported
   static MimeType fromString(String mimeType) => _map[mimeType] ?? MimeType.unsupported(mimeType);
 
+  /// Whether the provided String representation of a [MimeType] is supported
   static bool isSupported(String mimeType) {
     return _map.containsKey(mimeType);
   }
@@ -46,6 +58,7 @@ class MimeType {
   @override
   int get hashCode => Object.hash(_type, _name);
 
+  /// Decode the bytes into an [img.Image] using the appropriate decoder
   img.Image? decode(List<int> bytes) {
     img.Decoder? decoder;
     switch (_type) {
@@ -72,6 +85,7 @@ class MimeType {
   }
 }
 
+/// 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
   final MimeType mimeType;

lib/src/media/stream/client.dart

@@ -56,6 +56,7 @@ class StreamManager {
     };
   }
 
+  /// Add a stream to internal state
   void _addStream(MediaStream stream) {
     _streams[stream.id] = stream;
     if (_clients.containsKey(stream.id)) {
@@ -84,6 +85,7 @@ class StreamManager {
     return client;
   }
 
+  /// Request that a stream get added to the WebRTC channel
   Future<void> _add(String name) async {
     final sanitizedName = _getValidSDPTrackName(name);
     await _client.addStream(AddStreamRequest()..name = sanitizedName);
@@ -113,6 +115,9 @@ class StreamManager {
   }
 }
 
+/// 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.
 class StreamClient {
   final String name;
   final Future<void> Function(String name) _close;
@@ -131,6 +136,7 @@ class StreamClient {
     });
   }
 
+  /// Return a stream of [MediaStream], which can be used to display WebRTC video.
   Stream<MediaStream> getStream() {
     if (_stream != null) {
       Future.delayed(const Duration(milliseconds: 100), () {
@@ -140,6 +146,7 @@ class StreamClient {
     return _streamController.stream;
   }
 
+  /// Close the stream connection and release resources.
   Future<void> closeStream() async {
     await _streamController.close();
     await _internalStreamController.close();

lib/src/resource/base.dart

@@ -3,20 +3,35 @@ import 'package:grpc/grpc_connection_interface.dart';
 
 import '../gen/common/v1/common.pb.dart';
 
+/// The standard namespace for Viam resources (rdk)
 const String resourceNamespaceRDK = 'rdk';
+
+/// The standard type for component resources (component)
 const String resourceTypeComponent = 'component';
+
+/// The standard type for service resources (service)
 const String resourceTypeService = 'service';
 
+/// [Subtype] defines a triplet of strings that correspond to a resource's specific API definition.
 class Subtype {
-  final String namespace, resourceType, resourceSubtype;
+  /// The namespace of the subtype
+  final String namespace;
+
+  /// The resource type (e.g. component, service)
+  final String resourceType;
+
+  /// The resource subtype (e.g. arm, sensor, camera)
+  final String resourceSubtype;
 
   const Subtype(this.namespace, this.resourceType, this.resourceSubtype);
 
+  /// Create a new [Subtype] from a [ResourceName]
   Subtype.fromResourceName(ResourceName name)
       : namespace = name.namespace,
         resourceType = name.type,
         resourceSubtype = name.subtype;
 
+  /// Get a [ResourceName] from this [Subtype] and a provided [name]
   ResourceName getResourceName(String name) {
     return ResourceName()
       ..namespace = namespace
@@ -36,6 +51,7 @@ class Subtype {
       namespace == other.namespace && resourceType == other.resourceType && resourceSubtype == other.resourceSubtype;
 }
 
+/// Abstract class that defines the base functionality for all [Resource] types
 abstract class Resource {
   abstract String name;
 
@@ -44,6 +60,7 @@ abstract class Resource {
   }
 }
 
+/// Abstract class that defines the base functionality for all RPC clients for resources
 abstract class ResourceRPCClient<T extends Client> {
   abstract ClientChannelBase channel;
 

lib/src/resource/manager.dart

@@ -2,26 +2,35 @@ import 'package:viam_sdk/src/gen/common/v1/common.pb.dart';
 
 import 'base.dart';
 
+/// [ResourceManager] manages the state of all currently available resources of a robot
 class ResourceManager {
+  /// The available resources
   Map<ResourceName, Resource> resources = {};
   final Map<String, List<ResourceName>> _shortToLongName = {};
 
+  /// Register a new [Resource] with the manager.
   void register(ResourceName name, Resource resource) {
     if (resources.containsKey(name)) {
       throw Exception('Duplicate registration of resource in manager');
     }
     final shortName = name.name.split(':').last;
-    if (!(_shortToLongName[shortName]?.contains(name) ?? true)) {
-      final names = _shortToLongName[shortName] ?? [];
-      names.add(name);
-      _shortToLongName[shortName] = names;
-    }
+    final names = _shortToLongName[shortName] ?? [];
+    names.add(name);
+    _shortToLongName[shortName] = names;
     resources[name] = resource;
   }
 
+  /// Get a resource with the given [ResourceName]
   T getResource<T>(ResourceName name) {
     final resource = resources[name];
     if (resource == null) throw Exception('Resource not found in manager');
     return resource as T;
   }
+
+  /// Get a resource by its name only
+  T getResourceByName<T>(String name) {
+    final names = _shortToLongName[name] ?? [];
+    if (names.isEmpty) throw Exception('Resource not found in manager');
+    return getResource(names.first);
+  }
 }

lib/src/resource/registry.dart

@@ -20,13 +20,29 @@ import '../components/servo/client.dart';
 import '../components/servo/servo.dart';
 import '../resource/base.dart';
 
+/// 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)
+/// If creating a custom [Resource], you must register the resource using [ResourceRegistration].
 class ResourceRegistration<T extends Resource> {
+  /// The [Subtype] of the resource
   Subtype subtype;
+
+  /// A method to create a [ResourceRPCClient]
   Resource Function(String name, ClientChannelBase channel) rpcClientCreator;
 
   ResourceRegistration(this.subtype, this.rpcClientCreator);
 }
 
+/// The global registry of robot resources.
+///
+/// **NB** The [Registry] should almost never be used directly.
+///
+/// The [Registry] keeps track of the various [Subtype] that are available on robots using this SDK. All Viam-provided resources are
+/// pre-registered (e.g. [Arm], [Motor], [MovementSensor]).
+///
+/// If you create a new resource [Subtype] that is not an extension of any existing resources, you must register the resource using
+/// [registerSubtype]
 class Registry {
   static final Registry instance = Registry._();
   Registry._() {
@@ -42,15 +58,18 @@ class Registry {
     registerSubtype(ResourceRegistration(Servo.subtype, (name, channel) => ServoClient(name, channel)));
   }
 
+  /// The [Subtype] available in the SDK
   final Map<Subtype, ResourceRegistration> subtypes = {};
 
+  /// Register a new resource with the SDK
   void registerSubtype(ResourceRegistration registration) {
     if (subtypes.containsKey(registration.subtype)) {
       throw Exception('Duplicate registration of subtype in registry');
     }
     subtypes[registration.subtype] = registration;
   }
 
+  /// Retrieve a [Subtype]'s registration information
   ResourceRegistration lookupSubtype(Subtype subtype) {
     if (!subtypes.containsKey(subtype)) {
       throw Exception('Subtype not registered in registry');

lib/src/robot/client.dart

@@ -197,7 +197,7 @@ class RobotClient {
       _sessionsClient.stop();
       await _channel.shutdown();
     } catch (e) {
-      _logger.w('Did not cleanly close RobotClient connection', e);
+      _logger.w('Did not cleanly close RobotClient connection', error: e);
     }
   }
 

lib/src/robot/sessions_client.dart

@@ -39,6 +39,7 @@ class SessionsClient implements ResourceRPCClient {
     metadata();
   }
 
+  /// Retrieve metadata associated with the session (e.g. whether sessions are supported, the current ID of the session)
   String metadata() {
     if (!_enabled) return '';
 
@@ -64,26 +65,29 @@ class SessionsClient implements ResourceRPCClient {
         return _currentId;
       });
     } catch (e) {
-      _logger.e('error starting session: $e');
+      _logger.e('Error starting session: $e');
       reset();
     }
 
     return '';
   }
 
+  /// Reset the current session and re-obtain metadata
   void reset() {
-    _logger.d('resetting session');
+    _logger.d('Resetting current session with ID: $_currentId');
     _currentId = '';
     _supported = false;
     metadata();
   }
 
+  /// Stop the session client and heartbeat tasks
   void stop() {
     _logger.d('Stopping SessionClient');
     _currentId = '';
     _supported = false;
   }
 
+  /// Start the session client
   void start() {
     reset();
   }