RSDK-3657: TS SDK Gantry API changes (#128)

Author: martha-johnston

buf.lock

@@ -9,8 +9,8 @@ deps:
   - remote: buf.build
     owner: viamrobotics
     repository: api
-    commit: 77bcd1d0f47a437e8c58639004a13451
-    digest: shake256:9d311393e8b744ced31428355d42d3a997a92ee5cc9ecfa10cb30e656ad265986c7d758ecc3ad5ed6de1ebf2d1ae514a1fca9dee128244c4420a56b5c5066a5e
+    commit: 1ea16dd720f04cefa61f380ccc375d6f
+    digest: shake256:c51fd611a013929061384c1630d5e421a1083a62b6d5e4256c0a50b8abd4e8b91a944495918bbaa165d32398bbd6990a0c9b71f5275df9375386f2b050e67a6f
   - remote: buf.build
     owner: viamrobotics
     repository: goutils

codesamples/apis.json

@@ -31,6 +31,11 @@
         "func": "getProperties",
         "args": []
     },
+    "gantry": {
+        "client": "GantryClient",
+        "func": "getLengths",
+        "args": []
+    },
     "sensor": {
         "client": "SensorClient",
         "func": "getReadings",

src/components/gantry.ts

@@ -0,0 +1,2 @@
+export type { Gantry } from './gantry/gantry';
+export { GantryClient } from './gantry/client';

src/components/gantry/client.ts

@@ -0,0 +1,130 @@
+import { Struct } from 'google-protobuf/google/protobuf/struct_pb';
+import type { RobotClient } from '../../robot';
+import pb from '../../gen/component/gantry/v1/gantry_pb';
+import { GantryServiceClient } from '../../gen/component/gantry/v1/gantry_pb_service';
+import type { Options, StructType } from '../../types';
+import { doCommandFromClient, promisify } from '../../utils';
+import type { Gantry } from './gantry';
+
+/**
+ * A gRPC-web client for the Gantry component.
+ *
+ * @group Clients
+ */
+export class GantryClient implements Gantry {
+  private client: GantryServiceClient;
+  private readonly name: string;
+  private readonly options: Options;
+
+  constructor(client: RobotClient, name: string, options: Options = {}) {
+    this.client = client.createServiceClient(GantryServiceClient);
+    this.name = name;
+    this.options = options;
+  }
+
+  private get GantryService() {
+    return this.client;
+  }
+
+  async getPosition(extra = {}) {
+    const gantryService = this.GantryService;
+    const request = new pb.GetPositionRequest();
+    request.setName(this.name);
+    request.setExtra(Struct.fromJavaScript(extra));
+
+    this.options.requestLogger?.(request);
+
+    const response = await promisify<
+      pb.GetPositionRequest,
+      pb.GetPositionResponse
+    >(gantryService.getPosition.bind(gantryService), request);
+
+    return response.getPositionsMmList();
+  }
+
+  async moveToPosition(
+    positionsMm: number[],
+    speedsMmPerSec: number[],
+    extra = {}
+  ) {
+    const gantryService = this.GantryService;
+
+    const request = new pb.MoveToPositionRequest();
+    request.setName(this.name);
+    request.setPositionsMmList(positionsMm);
+    request.setSpeedsMmPerSecList(speedsMmPerSec);
+    request.setExtra(Struct.fromJavaScript(extra));
+
+    this.options.requestLogger?.(request);
+
+    await promisify<pb.MoveToPositionRequest, pb.MoveToPositionResponse>(
+      gantryService.moveToPosition.bind(gantryService),
+      request
+    );
+  }
+
+  async home(extra = {}) {
+    const gantryService = this.GantryService;
+    const request = new pb.HomeRequest();
+    request.setName(this.name);
+    request.setExtra(Struct.fromJavaScript(extra));
+
+    this.options.requestLogger?.(request);
+
+    const response = await promisify<pb.HomeRequest, pb.HomeResponse>(
+      gantryService.home.bind(gantryService),
+      request
+    );
+
+    return response.getHomed();
+  }
+
+  async getLengths(extra = {}) {
+    const gantryService = this.GantryService;
+    const request = new pb.GetLengthsRequest();
+    request.setName(this.name);
+    request.setExtra(Struct.fromJavaScript(extra));
+
+    this.options.requestLogger?.(request);
+
+    const response = await promisify<
+      pb.GetLengthsRequest,
+      pb.GetLengthsResponse
+    >(gantryService.getLengths.bind(gantryService), request);
+
+    return response.getLengthsMmList();
+  }
+
+  async stop(extra = {}) {
+    const gantryService = this.GantryService;
+    const request = new pb.StopRequest();
+    request.setName(this.name);
+    request.setExtra(Struct.fromJavaScript(extra));
+
+    this.options.requestLogger?.(request);
+
+    await promisify<pb.StopRequest, pb.StopResponse>(
+      gantryService.stop.bind(gantryService),
+      request
+    );
+  }
+
+  async isMoving() {
+    const gantryService = this.GantryService;
+    const request = new pb.IsMovingRequest();
+    request.setName(this.name);
+
+    this.options.requestLogger?.(request);
+
+    const response = await promisify<pb.IsMovingRequest, pb.IsMovingResponse>(
+      gantryService.isMoving.bind(gantryService),
+      request
+    );
+    return response.getIsMoving();
+  }
+
+  async doCommand(command: StructType): Promise<StructType> {
+    const gantryService = this.GantryService;
+    return doCommandFromClient(gantryService, this.name, command, this.options);
+  }
+}

src/components/gantry/gantry.ts

@@ -0,0 +1,39 @@
+import type { Resource, StructType } from '../../types';
+
+/** Represents a physical gantry that exists in three-dimensional space. */
+export interface Gantry extends Resource {
+  /**
+   * Move each axis of the gantry to the positionsMm at the speeds in
+   * speedsMmPerSec
+   *
+   * @param positionsMm - The goal positions for each axis of the gantry.
+   * @param speedsMmPerSec - The desired speed for each axis to move to the
+   *   respective position in positionsMm.
+   */
+  moveToPosition: (
+    positionsMm: number[],
+    speedsMmPerSec: number[],
+    extra?: StructType
+  ) => Promise<void>;
+
+  /** @returns The current position of each axis. */
+  getPosition: (extra?: StructType) => Promise<number[]>;
+
+  /**
+   * Runs the homing sequence to find the start and end positions of the gantry
+   * axis.
+   *
+   * @returns A bool representing whether the gantry has run the homing sequence
+   *   successfully.
+   */
+  home: (extra?: StructType) => Promise<boolean>;
+
+  /** @returns The lengths of the axes of the gantry in millimeters. */
+  getLengths: (extra?: StructType) => Promise<number[]>;
+
+  /** Stops the motion of the gantry. */
+  stop: (extra?: StructType) => Promise<void>;
+
+  /** Get if the gantry is currently moving. */
+  isMoving: () => Promise<boolean>;
+}

src/main.ts

@@ -90,6 +90,18 @@ export {
   EncoderClient,
 } from './components/encoder';
 
+/**
+ * Raw Protobuf interfaces for a Gantry component.
+ *
+ * Generated with https://github.com/improbable-eng/grpc-web
+ *
+ * @deprecated Use {@link GantryClient} instead.
+ * @alpha
+ * @group Raw Protobufs
+ */
+export { default as gantryApi } from './gen/component/gantry/v1/gantry_pb';
+export { type Gantry, GantryClient } from './components/gantry';
+
 /**
  * Raw Protobuf interfaces for a Motor component.
  *
@@ -171,35 +183,6 @@ export { default as sensorsApi } from './gen/service/sensors/v1/sensors_pb';
 export { default as streamApi } from './gen/proto/stream/v1/stream_pb';
 export { type Stream, StreamClient } from './extra/stream';
 
-/**
- * Raw Protobuf interfaces for a Gantry component.
- *
- * Generated with https://github.com/improbable-eng/grpc-web
- *
- * @example
- *
- * ```ts
- * import { grpc } from '@improbable-eng/grpc-web';
- *
- * const client = {}; // replace with a connected robot client
- *
- * const request = new gantryApi.GetLengthsRequest();
- * request.setName('mygantry');
- *
- * client.gantryService.getLengths(
- *   request,
- *   new grpc.Metadata(),
- *   (error, response) => {
- *     // do something with error or response
- *   }
- * );
- * ```
- *
- * @alpha
- * @group Raw Protobufs
- */
-export { default as gantryApi } from './gen/component/gantry/v1/gantry_pb';
-
 /**
  * Raw Protobuf interfaces for a Generic component.
  *