CobotAR-Protocol

A collection of protobuf messages for the CobotAR-project

Current version: 2.3.6

Documentation

Find it here: documentation/README.md

New version

1. Make changes
2. make publish bump={patch,minor,major}

Python

The generated Python modules are imported below the cobotar_protocol namespace. Install the package with Buf's generated SDK index enabled, since the generated Protovalidate messages are hosted there:

python3 -m pip install \
  --extra-index-url https://buf.build/gen/python \
  cobotar-protocol

Consumers only add the package's parent directory to sys.path; do not add the inner cobotar_protocol/ directory.

NATS subjects

NATS subjects are defined in subjects/catalog.yaml. The catalog records each subject pattern, protobuf payload or request/reply types, lifecycle, conformance state, intended publishers, and consumers. Generated Go, C#, TypeScript, and Python helpers reject invalid concrete subject tokens and provide explicit wildcard builders for subscriptions. Entity route families generate both concrete message-aware routes and generic helpers whose entity argument uses the shared generated EntityName contract.

See the generated subject catalog and naming rules. Run go run ./cmd/subjectgen check to validate the catalog and verify that all generated outputs are current.

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

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:

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.