@cobotar/protocol 0.16.11 → 0.17.1

package/README.md

@@ -1,7 +1,7 @@
 # CobotAR-Protocol
 A collection of protobuf messages for the CobotAR-project
 
-Current version: 0.16.11
+Current version: 0.17.1
 
 ## Documentation
 Find it here: [documentation/README.md](documentation/README.md)
@@ -41,3 +41,178 @@ telemetry.robot.state.workcellA.robot-1
 event.robot.started.workcellA.robot-1
 event.plan.cancelled.workcellA.plan-P123
 ```
+
+
+## Conceptual design of Assembly processes
+### A. Product definition (What the thing is)
+* Parts
+* Assemblies / sub-assemblies
+* Product BOM / hierarchy
+* Part occurrences / instances
+* CAD / 3D model references
+* Mating / connection hints if you have them
+
+### B. Process template (How the thing is normally assembled)
+* Process recipe
+* Sequences / sub-sequences
+* Tasks / operations / steps
+* Preconditions / ordering / alternatives / variants
+* Required tool roles, skill requirements, actor constraints
+* Operator text
+
+### C. Execution instance (What is happening right now on the floor)
+* Running process
+* Current state of sequences/tasks
+* Assigned human(s)/robot(s)
+* Start/end timestamps
+* Current station
+* Evidence / completion / faults / overrides
+
+### D. Resource library (What can be used to perform the work)
+* Humans
+* Robots
+* Tools
+* Fixtures
+* Assets
+* Stations / cells
+* Models
+
+### E. Capability layer (Why a given resource can or cannot do a task)
+* Skills
+* Capability profiles
+* Tool roles
+* Constraints
+* Validity / training / retraining / calibration / certification
+
+## Distinguish type from instance
+Example: Part. In assembly we usually need both:
+* Part definition: “M4x12 screw”
+* Part occurrence: “the third M4x12 screw in this assembly”
+
+thus distinguishing between the two is important and must be supported and done consistently.
+
+
+### Minimal TaskDefinition example
+```typescript
+TaskDefinition {
+  id: "task-fasten-cover-screw-1"
+  name: "Fasten cover screw 1"
+  instruction_text: "Fasten screw 1 to 0.8 Nm"
+  task_type: TASK_TYPE_FASTEN
+  target: {
+    target_node_id: "node-screw-1"
+    target_part_definition_id: "part-m4x12"
+    local_target: {
+      anchor_id: "node-screw-1"
+    }
+  }
+  tool_requirements: [{
+    role: TOOL_ROLE_APPLY_TORQUE,
+    required_properties: [TOOL_PROPERTY_TORQUE_CONTROLLED],
+    minimum_capability: {
+      min_torque_nm: 0.72,
+      max_torque_nm: 0.88
+    }
+  }]
+  skill_requirements: [{
+    skill_id: "SK-APPLY-CONTROLLED-TORQUE",
+    minimum_level: SKILL_LEVEL_QUALIFIED
+  }]
+  validation: {
+    require_tool_feedback: true
+    allow_manual_confirmation: true
+    manual_confirmation_min_level: SKILL_LEVEL_QUALIFIED
+  }
+  execution_policy: {
+    assignment_preference: TASK_ASSIGNMENT_PREFERENCE_EITHER
+    actor_constraint: {
+      allowed_actor_kinds: [ACTOR_KIND_HUMAN, ACTOR_KIND_ROBOT]
+      collaboration_mode: COLLABORATION_MODE_SEQUENTIAL_HRC
+    }
+  }
+}
+```
+
+
+## Variant handling
+
+### Types of variants
+#### Bucket A — Structural variants
+Affect product tree. Modeled in product.
+
+Examples:
+* hinge side
+* optional handle
+* different fastener family
+* extra sensor module
+
+#### Bucket B — Workflow variants
+Affect tasks/sequences/skills/tools/validation. Modeled in recipe applicability or recipe branching.
+
+Examples:
+* door must be flipped
+* adhesive cure step required
+* fragile part requires two-person lift
+* robot can only assemble one orientation
+
+#### Bucket C — Parametric variants
+Do not change workflow structure. Passed at run-time.
+
+Examples:
+* color
+* language
+* customer text
+* batch number
+* cosmetic finish code
+
+### Handle variants without recipe explosion
+For a product family, do this:
+
+* **One ProductDefinition**
+  * Contains all structural possibilities.
+* **Few ProcessRecipes**
+
+  Only split recipes where the workflow truly differs. For example:
+  * recipe-door-standard
+  * recipe-door-flipped-fixture
+  * recipe-door-adhesive
+
+  Not:
+  * red-left-short-handle
+  * red-left-long-handle
+  * blue-right-short-handle
+  * …
+
+* **One ProcessRun per actual order/build**
+
+  Contains:
+  * selected product configuration
+  * runtime parameters
+
+#### Example
+
+##### Product dimensions
+* hinge_side = left | right
+* color = red | green | blue
+* handle = short | long
+
+##### Recipe
+* `recipe-door-standard` is applicable when:
+  * handle = short or long
+  * color = any
+  * hinge_side = left
+* `recipe-door-flipped` is applicable when:
+  * hinge_side = right
+
+They need to be split into two recipes because `right-hinge` requires a `flip` operation and different fixture.
+
+##### Process run
+When a real order starts the selection might look like this:
+```typescript
+product_selection:
+  hinge_side = right
+  color = green
+  handle = long
+```
+thus the system chooses the `recipe-door-flipped` recipe and the recipe stays the same regardless of `color`.
+

package/lib/assembly/v1/actor_pb.ts

@@ -0,0 +1,160 @@
+// @generated by protoc-gen-es v2.10.2 with parameter "target=ts,import_extension=ts"
+// @generated from file assembly/v1/actor.proto (package assembly.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
+import type { ActorKind, CustomProperties, ExternalReference } from "./common_pb.ts";
+import { file_assembly_v1_common } from "./common_pb.ts";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import { file_google_protobuf_timestamp } from "@bufbuild/protobuf/wkt";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file assembly/v1/actor.proto.
+ */
+export const file_assembly_v1_actor: GenFile = /*@__PURE__*/
+  fileDesc("Chdhc3NlbWJseS92MS9hY3Rvci5wcm90bxILYXNzZW1ibHkudjEi4gEKEFdvcmtlckRlZmluaXRpb24SCgoCaWQYASABKAkSDAoEbmFtZRgCIAEoCRITCgtkZXNjcmlwdGlvbhgDIAEoCRIMCgRpY29uGAQgASgJEhAKCGRpc2FibGVkGAUgASgIEhMKC2VtcGxveWVlX2lkGAYgASgJEjsKE2V4dGVybmFsX3JlZmVyZW5jZXMYByADKAsyHi5hc3NlbWJseS52MS5FeHRlcm5hbFJlZmVyZW5jZRItCgZjdXN0b20YCCABKAsyHS5hc3NlbWJseS52MS5DdXN0b21Qcm9wZXJ0aWVzIkEKEVdvcmtlckRlZmluaXRpb25zEiwKBWl0ZW1zGAEgAygLMh0uYXNzZW1ibHkudjEuV29ya2VyRGVmaW5pdGlvbiJCCghBY3RvclJlZhIkCgRraW5kGAEgASgOMhYuYXNzZW1ibHkudjEuQWN0b3JLaW5kEhAKCGFjdG9yX2lkGAIgASgJIusBCg9BY3RvckFzc2lnbm1lbnQSCgoCaWQYASABKAkSJAoFYWN0b3IYAiABKAsyFS5hc3NlbWJseS52MS5BY3RvclJlZhIWCg5wcm9jZXNzX3J1bl9pZBgDIAEoCRIXCg9zZXF1ZW5jZV9ydW5faWQYBCABKAkSEwoLdGFza19ydW5faWQYBSABKAkSLwoLYXNzaWduZWRfYXQYBiABKAsyGi5nb29nbGUucHJvdG9idWYuVGltZXN0YW1wEi8KC3JlbGVhc2VkX2F0GAcgASgLMhouZ29vZ2xlLnByb3RvYnVmLlRpbWVzdGFtcEKwAQoPY29tLmFzc2VtYmx5LnYxQgpBY3RvclByb3RvUAFaO2dpdGh1Yi5jb20vY29ib3Rhci9wcm90b2NvbC9tZXNzYWdlcy9hc3NlbWJseS92MTthc3NlbWJseXYxogIDQVhYqgIUTWVzc2FnZXMuQXNzZW1ibHkuVjHKAgtBc3NlbWJseVxWMeICF0Fzc2VtYmx5XFYxXEdQQk1ldGFkYXRh6gIMQXNzZW1ibHk6OlYxYgZwcm90bzM", [file_assembly_v1_common, file_google_protobuf_timestamp]);
+
+/**
+ * @generated from message assembly.v1.WorkerDefinition
+ */
+export type WorkerDefinition = Message<"assembly.v1.WorkerDefinition"> & {
+  /**
+   * @generated from field: string id = 1;
+   */
+  id: string;
+
+  /**
+   * @generated from field: string name = 2;
+   */
+  name: string;
+
+  /**
+   * @generated from field: string description = 3;
+   */
+  description: string;
+
+  /**
+   * @generated from field: string icon = 4;
+   */
+  icon: string;
+
+  /**
+   * If disabled, the worker can't be selected
+   *
+   * @generated from field: bool disabled = 5;
+   */
+  disabled: boolean;
+
+  /**
+   * @generated from field: string employee_id = 6;
+   */
+  employeeId: string;
+
+  /**
+   * @generated from field: repeated assembly.v1.ExternalReference external_references = 7;
+   */
+  externalReferences: ExternalReference[];
+
+  /**
+   * @generated from field: assembly.v1.CustomProperties custom = 8;
+   */
+  custom?: CustomProperties;
+};
+
+/**
+ * Describes the message assembly.v1.WorkerDefinition.
+ * Use `create(WorkerDefinitionSchema)` to create a new message.
+ */
+export const WorkerDefinitionSchema: GenMessage<WorkerDefinition> = /*@__PURE__*/
+  messageDesc(file_assembly_v1_actor, 0);
+
+/**
+ * @generated from message assembly.v1.WorkerDefinitions
+ */
+export type WorkerDefinitions = Message<"assembly.v1.WorkerDefinitions"> & {
+  /**
+   * @generated from field: repeated assembly.v1.WorkerDefinition items = 1;
+   */
+  items: WorkerDefinition[];
+};
+
+/**
+ * Describes the message assembly.v1.WorkerDefinitions.
+ * Use `create(WorkerDefinitionsSchema)` to create a new message.
+ */
+export const WorkerDefinitionsSchema: GenMessage<WorkerDefinitions> = /*@__PURE__*/
+  messageDesc(file_assembly_v1_actor, 1);
+
+/**
+ * @generated from message assembly.v1.ActorRef
+ */
+export type ActorRef = Message<"assembly.v1.ActorRef"> & {
+  /**
+   * @generated from field: assembly.v1.ActorKind kind = 1;
+   */
+  kind: ActorKind;
+
+  /**
+   * worker_definition_id or robot_instance_id
+   *
+   * @generated from field: string actor_id = 2;
+   */
+  actorId: string;
+};
+
+/**
+ * Describes the message assembly.v1.ActorRef.
+ * Use `create(ActorRefSchema)` to create a new message.
+ */
+export const ActorRefSchema: GenMessage<ActorRef> = /*@__PURE__*/
+  messageDesc(file_assembly_v1_actor, 2);
+
+/**
+ * @generated from message assembly.v1.ActorAssignment
+ */
+export type ActorAssignment = Message<"assembly.v1.ActorAssignment"> & {
+  /**
+   * @generated from field: string id = 1;
+   */
+  id: string;
+
+  /**
+   * @generated from field: assembly.v1.ActorRef actor = 2;
+   */
+  actor?: ActorRef;
+
+  /**
+   * @generated from field: string process_run_id = 3;
+   */
+  processRunId: string;
+
+  /**
+   * @generated from field: string sequence_run_id = 4;
+   */
+  sequenceRunId: string;
+
+  /**
+   * @generated from field: string task_run_id = 5;
+   */
+  taskRunId: string;
+
+  /**
+   * @generated from field: google.protobuf.Timestamp assigned_at = 6;
+   */
+  assignedAt?: Timestamp;
+
+  /**
+   * @generated from field: google.protobuf.Timestamp released_at = 7;
+   */
+  releasedAt?: Timestamp;
+};
+
+/**
+ * Describes the message assembly.v1.ActorAssignment.
+ * Use `create(ActorAssignmentSchema)` to create a new message.
+ */
+export const ActorAssignmentSchema: GenMessage<ActorAssignment> = /*@__PURE__*/
+  messageDesc(file_assembly_v1_actor, 3);
+