Merge branch 'main' into addlinks

Author: npentrel

.github/workflows/linkcheck.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Test HTML
         # https://github.com/wjdp/htmltest-action/
         # Don't fail the build on broken links
-        continue-on-error: false
+        continue-on-error: true
         uses: wjdp/htmltest-action@master
         with:
           config: .htmltest.yml

CHANGELOG.md

@@ -1,11 +1,32 @@
 # Changelog
 
-## [v0.0.15](https://github.com/viamrobotics/viam-flutter-sdk/tree/v0.0.15) (2024-05-28)
+## [v0.0.17](https://github.com/viamrobotics/viam-flutter-sdk/tree/v0.0.17) (2024-07-01)
 
-[Full Changelog](https://github.com/viamrobotics/viam-flutter-sdk/compare/v0.0.14...v0.0.15)
+[Full Changelog](https://github.com/viamrobotics/viam-flutter-sdk/compare/v0.0.16...v0.0.17)
 
 **Merged pull requests:**
 
+- Automated Protos Update [\#242](https://github.com/viamrobotics/viam-flutter-sdk/pull/242) ([github-actions[bot]](https://github.com/apps/github-actions))
+- v0.0.16 [\#238](https://github.com/viamrobotics/viam-flutter-sdk/pull/238) ([github-actions[bot]](https://github.com/apps/github-actions))
+- Automated Protos Update [\#237](https://github.com/viamrobotics/viam-flutter-sdk/pull/237) ([github-actions[bot]](https://github.com/apps/github-actions))
+- Automated Protos Update [\#236](https://github.com/viamrobotics/viam-flutter-sdk/pull/236) ([github-actions[bot]](https://github.com/apps/github-actions))
+- Create linkcheck.yml [\#234](https://github.com/viamrobotics/viam-flutter-sdk/pull/234) ([npentrel](https://github.com/npentrel))
+- RSDK-7769, RSDK-7770 Add AppRobotClient and LogOutput dial option [\#233](https://github.com/viamrobotics/viam-flutter-sdk/pull/233) ([benjirewis](https://github.com/benjirewis))
+- DOCS-2036: Add vision service example snippets [\#232](https://github.com/viamrobotics/viam-flutter-sdk/pull/232) ([JessamyT](https://github.com/JessamyT))
+- DOCS-2400: Add snippets for resource base methods [\#231](https://github.com/viamrobotics/viam-flutter-sdk/pull/231) ([JessamyT](https://github.com/JessamyT))
+- DOCS-2035: Add example snippets to movement sensor, power sensor, sensor [\#230](https://github.com/viamrobotics/viam-flutter-sdk/pull/230) ([JessamyT](https://github.com/JessamyT))
+- Automated Protos Update [\#229](https://github.com/viamrobotics/viam-flutter-sdk/pull/229) ([github-actions[bot]](https://github.com/apps/github-actions))
+- Automated Protos Update [\#228](https://github.com/viamrobotics/viam-flutter-sdk/pull/228) ([github-actions[bot]](https://github.com/apps/github-actions))
+- DOCS-2033: Add gripper example snippets [\#227](https://github.com/viamrobotics/viam-flutter-sdk/pull/227) ([JessamyT](https://github.com/JessamyT))
+- DOCS-2032: Add camera and gantry example snippets [\#226](https://github.com/viamrobotics/viam-flutter-sdk/pull/226) ([JessamyT](https://github.com/JessamyT))
+- Fix 3rd Party License Auditor [\#225](https://github.com/viamrobotics/viam-flutter-sdk/pull/225) ([njooma](https://github.com/njooma))
+- `viam_example_app` has syntax's errors [\#224](https://github.com/viamrobotics/viam-flutter-sdk/pull/224) ([g0rdan](https://github.com/g0rdan))
+- Fix pwmFrequency and setPowerMode examples [\#223](https://github.com/viamrobotics/viam-flutter-sdk/pull/223) ([JessamyT](https://github.com/JessamyT))
+- DOCS-2382: Update readme [\#222](https://github.com/viamrobotics/viam-flutter-sdk/pull/222) ([JessamyT](https://github.com/JessamyT))
+- Automated Protos Update [\#221](https://github.com/viamrobotics/viam-flutter-sdk/pull/221) ([github-actions[bot]](https://github.com/apps/github-actions))
+- v0.0.15 [\#219](https://github.com/viamrobotics/viam-flutter-sdk/pull/219) ([github-actions[bot]](https://github.com/apps/github-actions))
+- DOCS-2031: Add arm, base, board example snippets [\#218](https://github.com/viamrobotics/viam-flutter-sdk/pull/218) ([JessamyT](https://github.com/JessamyT))
+- Automated Protos Update [\#217](https://github.com/viamrobotics/viam-flutter-sdk/pull/217) ([github-actions[bot]](https://github.com/apps/github-actions))
 - Automated Protos Update [\#216](https://github.com/viamrobotics/viam-flutter-sdk/pull/216) ([github-actions[bot]](https://github.com/apps/github-actions))
 - Add license auditing [\#214](https://github.com/viamrobotics/viam-flutter-sdk/pull/214) ([njooma](https://github.com/njooma))
 - RSDK-7445: paginate data by filter methods [\#213](https://github.com/viamrobotics/viam-flutter-sdk/pull/213) ([purplenicole730](https://github.com/purplenicole730))
@@ -118,6 +139,14 @@
 - RSDK-4580: Flutter SDK Base Properties [\#100](https://github.com/viamrobotics/viam-flutter-sdk/pull/100) ([martha-johnston](https://github.com/martha-johnston))
 - Automated Protos Update [\#97](https://github.com/viamrobotics/viam-flutter-sdk/pull/97) ([github-actions[bot]](https://github.com/apps/github-actions))
 
+## [v0.0.16](https://github.com/viamrobotics/viam-flutter-sdk/tree/v0.0.16) (2024-06-25)
+
+[Full Changelog](https://github.com/viamrobotics/viam-flutter-sdk/compare/v0.0.15...v0.0.16)
+
+## [v0.0.15](https://github.com/viamrobotics/viam-flutter-sdk/tree/v0.0.15) (2024-05-28)
+
+[Full Changelog](https://github.com/viamrobotics/viam-flutter-sdk/compare/v0.0.14...v0.0.15)
+
 ## [v0.0.14](https://github.com/viamrobotics/viam-flutter-sdk/tree/v0.0.14) (2024-05-14)
 
 [Full Changelog](https://github.com/viamrobotics/viam-flutter-sdk/compare/v0.0.13...v0.0.14)

lib/src/app/robot.dart

@@ -0,0 +1,42 @@
+import 'dart:async';
+
+import 'package:logger/logger.dart';
+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';
+
+/// gRPC client for connecting to app's RobotService.
+///
+/// All calls must be authenticated.
+class AppRobotClient {
+  final RobotServiceClient _client;
+
+  AppRobotClient(this._client);
+
+  /// Log the OutputEvent to app with the given partId.
+  Future<void> log(String partId, host, loggerName, OutputEvent event) async {
+    late String level;
+    switch (event.level) {
+      case Level.debug:
+        level = 'debug';
+      case Level.warning:
+        level = 'warning';
+      case Level.error:
+        level = 'error';
+      default:
+        // Assume info level if none of the above.
+        level = 'info';
+    }
+
+    // Assume log was just output (OutputEvent has no timestamp field).
+    final Timestamp protoTs = Timestamp.fromDateTime(DateTime.now());
+
+    // Join lines with '\n' and suffix with '\n'.
+    final String message = '${event.lines.join('\n')}\n';
+
+    final LogEntry entry = LogEntry(host: host, level: level, time: protoTs, loggerName: loggerName, message: message);
+    final request = LogRequest(id: partId, logs: [entry]);
+    await _client.log(request);
+  }
+}

lib/src/components/gripper/gripper.dart

@@ -8,7 +8,7 @@ import '../../robot/client.dart';
 abstract class Gripper extends Resource {
   static const Subtype subtype = Subtype(resourceNamespaceRDK, resourceTypeComponent, 'gripper');
 
-  /// Open the [Gripper]
+  /// Open the [Gripper].
   ///
   /// ```
   /// await myGripper.open();
@@ -26,7 +26,7 @@ abstract class Gripper extends Resource {
   /// For more information, see [Gripper component](https://docs.viam.com/components/gripper/).
   Future<void> grab({Map<String, dynamic>? extra});
 
-  /// Stop all motion of the [Gripper]. It is assumed the [Gripper] stops immediately
+  /// Stop all motion of the [Gripper]. It is assumed the [Gripper] stops immediately.
   ///
   /// ```
   /// await myGripper.stop();
@@ -35,7 +35,7 @@ abstract class Gripper extends Resource {
   /// For more information, see [Gripper component](https://docs.viam.com/components/gripper/).
   Future<void> stop({Map<String, dynamic>? extra});
 
-  /// If the [Gripper] is currently moving
+  /// Whether the [Gripper] is currently moving.
   ///
   /// ```
   /// var isItMoving = await myGripper.isMoving();

lib/src/components/motor/motor.dart

@@ -26,13 +26,23 @@ abstract class Motor extends Resource {
   /// When [powerPct] is negative, the rotation will be in the backward direction.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// // Set the power to  40% forwards.
+  /// await myMotor.setPower(0.4);
+  /// ```
   Future<void> setPower(double powerPct, {Map<String, dynamic>? extra});
 
   /// Spin the [Motor] the specified number of [revolutions] at specified [rpm].
   /// When [rpm] or [revolutions] is a negative value, the rotation will be in the backward direction.
   /// Note: if both [rpm] and [revolutions] are negative, the motor will spin in the forward direction.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// // Turn the motor 7.2 revolutions forward at 60 RPM.
+  /// await myMotor.goFor(60, 7.2);
+  /// ```
   Future<void> goFor(double rpm, double revolutions, {Map<String, dynamic>? extra});
 
   /// Spin the [Motor] to the specified position (provided in revolutions from home/zero),
@@ -41,51 +51,103 @@ abstract class Motor extends Resource {
   /// the [Motor] towards the specified position.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// // Turn the motor to 8.3 revolutions from home at 75 RPM.
+  /// await myMotor.goTo(75, 8.3);
+  /// ```
   Future<void> goTo(double rpm, double positionRevolutions, {Map<String, dynamic>? extra});
 
   /// Spin the [Motor] indefinitely at the specified speed, in revolutions per minute.
   /// If [rpm] is positive, the motor will spin forwards, and if [rpm] is negative, the motor will spin backwards.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// // Set the motor to turn backwards at 120.5 RPM.
+  /// await myMotor.setRPM(-120.5);
+  /// ```
   Future<void> setRPM(double rpm, {Map<String, dynamic>? extra});
 
   /// Set the current position (modified by [offset]) to be the new zero (home) position.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// // Set the current position as the new home position with no offset.
+  /// await myMotor.resetZeroPosition(0.0);
+  /// ```
   Future<void> resetZeroPosition(double offset, {Map<String, dynamic>? extra});
 
   /// Report the position of the motor based on its encoder.
   /// The value returned is the number of revolutions relative to its zero position.
   /// This method will raise an exception if position reporting is not supported by the motor.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// // Get the current position of an encoded motor.
+  /// var position = await myMotor.position();
+  /// ```
   Future<double> position({Map<String, dynamic>? extra});
 
-  /// Report a dictionary mapping optional properties to
+  /// Report a dictionary mapping each optional property to
   /// whether it is supported by this motor.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// // Return whether the motor supports certain optional features
+  /// var properties = await myMotor.properties();
+  /// ```
   Future<MotorProperties> properties({Map<String, dynamic>? extra});
 
   /// Stop the motor immediately, without any gradual step down.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
   Future<void> stop({Map<String, dynamic>? extra});
+  ///
+  /// ```
+  /// // Stop the motor.
+  /// await myMotor.stop();
+  /// ```
+  Future<void> stop({Map<String, dynamic>? extra});
 
-  /// Returns whether or not the motor is currently running.
+  /// Returns whether or not the motor is currently powered, and the portion
+  /// of max power (between 0 and 1; 0 indicates that power is off). Stepper
+  /// motors report `true` if they are being powered while holding a position,
+  /// as well as when they are turning themselves.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
-
+  ///
+  /// ```
+  /// // Check whether the motor is currently powered and
+  /// // check the percentage of max power to the motor.
+  /// var powerState = await myMotor.powerState();
+  /// var powered = powerState.isOn;
+  /// var pct = powerState.powerPct;
+  /// ```
   Future<PowerState> powerState({Map<String, dynamic>? extra});
 
   /// Get if the [Motor] is currently moving.
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// // Check whether the motor is moving.
+  /// var moving = await myMotor.isMoving();
+  /// ```
   Future<bool> isMoving({Map<String, dynamic>? extra});
 
   /// Get the [ResourceName] for this [Motor] with the given [name]
   ///
   /// For more information, see [Motor component](https://docs.viam.com/components/motor/).
+  ///
+  /// ```
+  /// var name = Motor.getResourceName('myMotor');
+  /// ```
+  ///
+  Future<bool> isMoving({Map<String, dynamic>? extra});
   static ResourceName getResourceName(String name) {
     return Motor.subtype.getResourceName(name);
   }

lib/src/components/power_sensor/power_sensor.dart

@@ -27,9 +27,9 @@ abstract class PowerSensor extends Resource {
   /// AC (true) or DC (false).
   ///
   /// ```
-  /// var voltageObject = await myPowerSensor.readings();
-  /// double voltageInVolts = voltageObject['volts'];
-  /// bool isItAC = voltageObject['isAc'];
+  /// var voltageObject = await myPowerSensor.voltage();
+  /// double voltageInVolts = voltageObject.volts;
+  /// bool isItAC = voltageObject.isAc;
   /// ```
   ///
   /// For more information, see [Power Sensor component](https://docs.viam.com/components/power-sensor/).
@@ -39,9 +39,9 @@ abstract class PowerSensor extends Resource {
   /// is AC (true) or DC (false).
   ///
   /// ```
-  /// var currentObject = await myPowerSensor.readings();
-  /// double amps = voltageObject['amperes'];
-  /// bool isItAC = voltageObject['isAc'];
+  /// var currentObject = await myPowerSensor.current();
+  /// double amps = currentObject.amperes;
+  /// bool isItAC = currentObject.isAc;
   /// ```
   ///
   /// For more information, see [Power Sensor component](https://docs.viam.com/components/power-sensor/).

lib/src/components/servo/servo.dart

@@ -16,11 +16,16 @@ abstract class Servo extends Resource {
   /// Get the current angle (degrees) of the [Servo].
   ///
   /// For more information, see [Servo component](https://docs.viam.com/components/servo/).
+  ///
+  /// ```
+  /// var angle = await myServo.position();
+  /// ```
   Future<int> position({Map<String, dynamic>? extra});
 
   /// Stop the [Servo]. It is assumed that the servo stops immediately.
   ///
   /// For more information, see [Servo component](https://docs.viam.com/components/servo/).
+  ///
   Future<void> stop({Map<String, dynamic>? extra});
 
   /// Get if the [Servo] is currently moving.
@@ -31,13 +36,37 @@ abstract class Servo extends Resource {
   /// Get the [ResourceName] for this [Servo] with the given [name]
   ///
   /// For more information, see [Servo component](https://docs.viam.com/components/servo/).
+  ///
+  /// ```
+  /// await myServo.stop();
+  /// ```
+  Future<void> stop({Map<String, dynamic>? extra});
+
+  /// Whether the [Servo] is currently moving.
+  ///
+  /// For more information, see [Servo component](https://docs.viam.com/components/servo/).
+  ///
+  /// ```
+  /// var isItMoving = await myServo.isMoving();
+  /// ```
+  Future<bool> isMoving();
+
+  /// Get the [ResourceName] for this [Servo] with the given [name].
+  ///
+  /// For more information, see [Servo component](https://docs.viam.com/components/servo/).
+  ///
+  /// ```
+  /// // Example:
+  /// var name = Servo.getResourceName('myServo');
+  /// ```
   static ResourceName getResourceName(String name) {
     return Servo.subtype.getResourceName(name);
   }
 
   /// Get the [Servo] named [name] from the provided robot.
   ///
   /// For more information, see [Servo component](https://docs.viam.com/components/servo/).
+  ///
   static Servo fromRobot(RobotClient robot, String name) {
     return robot.getResource(Servo.getResourceName(name));
   }

lib/src/gen/app/data/v1/data.pb.dart

@@ -1934,9 +1934,12 @@ class BinaryMetadata extends $pb.GeneratedMessage {
   $core.List<$core.String> get datasetIds => $_getList(8);
 }
 
-/// DeleteTabularDataRequest deletes the data from the organization that is older than `delete_older_than_days`.
-/// For example if `delete_older_than_days` is 10, this deletes any data that was captured up to 10 days ago.
-/// If it is 0, all existing data is deleted.
+/// DeleteTabularDataRequest deletes the data from the organization that is older than `delete_older_than_days`
+/// in UTC time. For example, if delete_older_than_days=1 and the request is made at 1AM EST on March 11
+/// (March 11 5AM UTC), this deletes all data captured through March 10 11:59:59PM UTC.
+/// If the request is at 10PM EST on March 11 (March 12 2AM UTC), this deletes all data captured
+/// through March 11 11:59:59PM UTC.
+/// If delete_older_than_days is 0, all existing data is deleted.
 class DeleteTabularDataRequest extends $pb.GeneratedMessage {
   factory DeleteTabularDataRequest({
     $core.String? organizationId,