Skip to main content

Inspect the system

After topology mount + workflow load succeed, these verbs answer "what's actually in this system, and what can it do?" None of them mutate state.

orca describe — the one-screen overview​

orca describe system takes no name. It renders a key-value block: the system's name, description, and version, plus aggregate counts of devices, locations, workflows, and methods.

$ orca describe system
System
  name:         hamilton_smc
  description:  SMC immunoassay cell
  version:      1.0.0
  devices:      12
  locations:    18
  workflows:    4
  methods:      8

describe is the unifier — the same group also handles depth on a single named entity:

orca describe workflow smc_assay
orca describe method seal_step
orca describe thread sample_journey
orca describe location ml_star.deck.A1
orca describe device shaker_01

Each form prints a structured summary: workflow shows its entry threads; method shows its failure policy; thread shows its labware template and start/end locations; device shows type, initialized/busy flags, mode, locations, loaded labware, and whether it's under external control.

Devices​

orca device list                       # all devices, status, busy flag
orca device capabilities <id>          # interfaces implemented + methods exposed
orca device info <id>                  # full snapshot + currently-loaded labware
orca device info <id> --capabilities   # snapshot plus the per-command capability list
orca device registry list              # device cards + connection info, all devices
orca device registry show <id>         # one device's two-card registry entry

device registry is a sub-app, not a bare verb: use device registry list / device registry show <id>. Each entry pairs a topology card (declared kind) with a connection card (advertised kind) plus live connected / initialized flags and a per-mode eligibility matrix.

device list example:

NAME            TYPE          BUSY     INITIALIZED   MODE
shaker_01       Shaker        False    True          PURE_SIM
sealer_01       Sealer        False    True          PURE_SIM
ml_star         MLSTAR        False    True          PURE_SIM
stacker_01      Storage       False    True          PURE_SIM
robotic_arm     Transporter   False    True          PURE_SIM

device capabilities shows which driver interfaces a device satisfies (e.g. IShaker, IPlateSource) and the methods each one exposes. This is what you grep when deciding whether to call orca device invoke or orca device send.

Locations​

orca location list                # every named position in the topology
orca describe location <name>     # one location's detail

There is no bare orca location <name> verb. For per-entity detail use orca describe location <name>. The location sub-app exposes only list.

Every entry in your topology's locations dict shows up here, plus auto-derived deck slots from liquid-handler DeckLayoutConfig entries.

Workflows, methods, threads​

orca workflow list                # all @orca.workflow templates
orca workflow get <name>          # one workflow's registry summary
orca describe workflow <name>     # one workflow's detail view

orca method list                  # all @orca.method templates
orca method get <name>            # one method's registry summary
orca describe method <name>       # one method's detail view

orca thread list                  # all @orca.thread templates
orca describe thread <name>       # one thread template's detail view

There are no bare orca workflow <name> / orca method <name> / orca thread <name> aliases. Per-entity detail is either <noun> get <name> (registry summary, for workflow/method) or orca describe <noun> <name> (the unified detail view). thread list shows labware template, start location, and end location.

Teachpoints​

orca teachpoints list                          # all transporters' teachpoints
orca teachpoints list <arm-id>                 # one transporter (positional device id)
orca teachpoints show <arm-id> <position-id>   # one coordinate set

The device id on list is a positional argument, not --device. Omit it to list every transporter's teachpoints (with the owning device id as an extra column); pass it to scope to one. show takes the device id and the position id. The registry also has create / update / delete verbs (orca teachpoints create <arm-id> <position-id> ...) taking --coords or --coords-file, --coord-type, --orientation, --access-config, and --gateway.

list shows one row per teachpoint with its position id, coord type, referenced access config, and gateway; the coordinate values themselves appear in show:

DEVICE_ID       POSITION_ID   COORD_TYPE   ACCESS_CONFIG   GATEWAY
robotic_arm     stacker       cartesian    default         -
robotic_arm     shaker        cartesian    default         -
robotic_arm     sealer        cartesian    default         -

Deck layouts​

orca deck-layouts list                # all LH deck layouts
orca deck-layouts list <lh-id>        # one liquid handler (positional device id)
orca deck-layouts show <lh-id> <name> # full resource dump

The device id on list is positional, not --device; omit it to span every liquid handler. show takes the device id and the layout name and prints the deck type plus the resource rows (name, catalog ref, rail, parent). The registry also has create / update / delete, each taking --config-file (a DeckLayoutConfig JSON file); edits are rebuild-required to take effect.

Access configs​

orca access-configs list
orca access-configs show <name>

Deployment-wide access configs — currently used for transporter restricted-arm assignments and a few device-level operator restrictions. The registry also has create / update / delete, each taking --access-type (vertical or horizontal) plus --gripper-offset, --vertical-clearance, and --horizontal-clearance.

Labware catalog​

The catalog enumerates labware DEFINITIONS (geometry rows used to author deck layouts and workflows), distinct from labware list, which enumerates runtime labware INSTANCES.

orca labware catalog                       # all labware definitions
orca labware catalog --category plate      # filter by category
orca labware get <labware-type>            # one definition's full detail

--category filters to one of plate, tip_rack, trough, tube, or carrier. Each catalog row is geometry-free (labware type, category, display name, vendor, source); fetch geometry per row with labware get. Operator-custom rows can be added or edited with labware add / labware update / labware delete (add / update take --display-name, --category, and --geometry-file; source is forced to operator_custom, and seed rows are protected).

JSON for scripts​

Every list verb supports --json. Output is a JSON array, one element per entity. Schemas are stable across CLI / REST / MCP.

$ orca device list --json | jq '.[] | select(.type_name == "MLSTAR") | .name'
"ml_star"

Pitfalls​

  • device info shows the runtime view, not the driver-poll truth. If a device drifted out of sync (manual intervention, comms blip), info reports the runtime's last-known state. To force a fresh poll, use device invoke <id> <get_status_method>.
  • teachpoints show returns the LAST recorded coordinate. If someone updated teachpoints mid-session, show reflects the current store. Use the audit log (forensics) to see who changed what.
  • describe workflow lists threads in declaration order, not execution order. Thread spawn order is determined by wf.start() + wf.thread() calls and by event handlers, not by the template list.