Inspect the system
These verbs answer what is in the system and what it can do: devices, locations, workflow and method templates, teachpoints, deck layouts and the labware catalog. Use them after topology mount and before you submit anything. None of them mutate state.
orca describe: the one-screen overview
orca describe system takes no name. It prints the system's name, description and version, plus 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
The same group handles depth on a single named entity:
orca describe workflow smc_assay
orca describe method seal_step
orca describe thread sample_plate
orca describe location ml_star.deck.A1
orca describe device shaker_01
| Form | What it prints |
|---|---|
describe workflow <name> | Entry thread templates. |
describe method <name> | Failure policy. |
describe thread <name> | Labware template, start location, and the end-location candidates. |
describe location <name> | Backing resource and loaded labware ids. |
describe device <name> | Type, initialized and busy flags, effective mode, locations, loaded labware, and whether it is under external control. |
describe method, describe thread and describe location work against both backends. describe system, describe workflow and describe device are local-daemon only, and the whole describe group is hidden from --help when the resolved backend is cloud.
Every describe form resolves the name by exact match and exits 20 if nothing matches. There are no prefixes here; these are names, not ids.
Devices
How a device is declared and where its driver comes from is on Devices. These verbs read what the running system made of it.
orca device list # all devices, status, busy flag, fault
orca device capabilities <id> # driver introspection: interfaces + methods
orca device info <id> # runtime snapshot
orca device info <id> --capabilities # snapshot plus the per-command capability list
orca device registry list # topology + connection cards, all devices
orca device registry show <id> # one device's two-card registry entry
device list prints six columns:
name type busy initialized mode fault
shaker_01 Shaker False True PURE_SIM shake (unknown)
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
The fault column is why the workflow will not drive that device: the command that ended badly, and how. A row showing only busy and initialized reads healthy on a machine nothing may touch, which is why the column is there.
The outcome in parentheses is the part that decides what you do next. failed means the driver ran the command and reported the failure, so the instrument is stopped somewhere between where it started and where it was going. unknown means no answer came back at all, so the instrument may still be moving and nothing has told it to stop. Clearing a fault clears the record, not the trouble; put the instrument right first.
device info <id> prints the same snapshot as a key-value block: type, initialized, busy, mode, locations, loaded labware. Add --capabilities for a second table of commands the daemon will dispatch, with each one's danger level, whether the CLI can reach it, and its parameters.
device capabilities <id> is the other read, and it prints different content: the driver's own introspection. A key-value header (type, interfaces, capabilities, provides_state) followed by one row per advertised method with its kind, return type and parameter names. Use this to decide between orca device invoke and orca device send.
device registry
device registry is a sub-app, not a bare verb. Each entry pairs a topology card (the kind the topology declared) with a connection card (the kind the connected client advertised), and adds live state:
name declared advertised client device link initialized modes fault
robotic_arm Transporter PF400 True True LIVE True device_sim,live
shaker_01 Shaker - True False - False pure_sim
Read client, device and link together:
clientis whether the on-prem client is reachable. A released device still sits under a client that is heartbeating.deviceis whether the link is open on whichever driver is being driven.linknames the mode of the driver that answered. A link open underPURE_SIMon a bench you believe is live belongs to a simulator, not the instrument.linkshowing-means nobody could answer.deviceis then false for want of anywhere to put "unknown", not because a link is known closed.
modes is the per-mode eligibility matrix: which of pure_sim, device_sim and live this device can be submitted under today. See run mode and the sim hierarchy.
Locations
orca location list # every routable location on the system map
orca describe location <name> # one location's detail
There is no bare orca location <name> verb. The location sub-app exposes only list; per-entity detail is orca describe location <name>.
list prints name, resource, loaded_labware and deck_sites. The deck_sites column holds a device's addressable deck-site children, for example mlstar_1/carrier-9-0. A labware thread's start= or end=, or an action's deck_positions, can target one. Deck sites are not routing nodes, so they never get their own row. Their geometry lives in the owning device's deck layout.
Workflows, methods, threads
These are the templates the loaded code declares. How each one is authored is on Workflows, Methods and 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 and method) or orca describe <noun> <name>.
method list prints workflow_name, name and failure_policy. Method names are unique per workflow, not globally, so method get <name> takes --workflow <name> when the same method name exists in more than one workflow.
thread list prints workflow_name, name, labware, start and end. end is a comma-separated list: a thread template can declare several end-location candidates, and the first free one wins at runtime.
Both get verbs return the registry snapshot, not source. To read the authored source of a workflow or method on a hosted deployment, use orca module get workflow <name> (see Code deployment).
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, which adds the owning device_id as a first column; pass it to scope to one.
list prints one row per teachpoint: 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
show adds the orientation, what the position was taught with, every per-labware exception on it, and then the coordinate values themselves.
The registry also has create / update / delete (orca teachpoints create <arm-id> <position-id> ...), taking --coords or --coords-file, --coord-type, --orientation, --access-config, --gateway and --taught-with.
Per-labware exceptions
orca teachpoints labware is the narrowest layer of move parameters: how one labware type is handled at one position.
orca teachpoints labware list <arm-id> <position-id>
orca teachpoints labware set <arm-id> <position-id> <labware-type> [--z-offset 2.0] [--speed 40]
orca teachpoints labware clear <arm-id> <position-id> <labware-type>
list prints one row per excepted labware type with the fields that type overrides. A position with no exceptions says so instead of printing an empty table.
Deck layouts
orca deck-layouts list # all liquid handlers' 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, which adds a device_id column. list prints the layout name and deck type.
show prints the device, deck type and resource count, then a table of resources (name, catalog ref, rail, parent id), then the full DeckLayoutConfig as JSON.
The registry also has create / update / delete, each taking --config-file (a DeckLayoutConfig JSON file). Edits need a rebuild to take effect.
Access configs
orca access-configs list
orca access-configs show <name>
An access config says how a robotic arm, a transporter, approaches and retracts from a location. They are deployment-wide, so several teachpoints reference one config rather than repeating its numbers. Where they sit among the layers a move resolves through is on Move parameters.
list prints name, type, gripper offset, vertical clearance and horizontal clearance. show prints the same fields at three decimal places.
The registry also has create / update / delete, each taking --access-type (vertical or horizontal) plus --gripper-offset, --vertical-clearance and --horizontal-clearance. Deleting a config that a teachpoint still references is refused.
Labware catalog
The catalog enumerates labware definitions: the geometry rows used to author deck layouts and workflows. That is a different thing from labware list, which enumerates the labware instances currently in the system. How a workflow declares the labware it needs is on Labware.
orca labware catalog # all labware definitions
orca labware catalog --category plate # filter by category
orca labware get <labware-type> # one definition's detail
--category filters to one of plate, tip_rack, trough, tube or carrier. Catalog rows are geometry-free: labware type, category, display name, vendor, source. That is deliberate, because one 384-well plate's geometry runs to about 77 KB and a whole catalog of them runs to megabytes.
labware get adds the PLR class name in the table view, and the full geometry blob in the --json view. source is plr_seed for a seeded row or operator_custom for one an operator added.
Operator-custom rows can be added or edited with labware add / labware update / labware delete. add and update take --display-name, --category and --geometry-file, plus optional --vendor and --plr-class-name. source is forced to operator_custom server-side, and seeded rows are protected: editing or deleting one exits 30.
What the catalog is for
A labware_type from this catalog is what you name to introduce labware the deployment package never declared:
orca labware register --labware-type nest_1_reservoir_195ml --location lh/carrier-25-0
That derives an ad-hoc labware template from the catalog row on the spot, so a trough somebody set on a deck can be told to the system without editing workflow code. register is covered on Operator interventions. Browsing the catalog is the first half of that job.
Only four of the five categories can be registered: plate, tip_rack, trough and tube. A carrier is deck furniture the layout declares, so naming one exits 2 and says which categories are placeable.
Most catalog rows cannot be built. A row carries geometry; making an instance also needs a PLR model that cheshire-drivers exposes for that exact labware_type, and 135 of the 216 placeable seeded rows have none. Naming one exits 2 with a refusal saying the type is in the catalog but no model exists for it. Nothing is registered and nothing is placed, so a refused register leaves no trace. A declared template name hits the same check, so this is not a penalty for going through the catalog.
Match the labware_type exactly, case included. The seed carries near-duplicate spellings, so hamilton_1_trough_200ml_Vb and hamilton_1_trough_200mL_Vb are different lookups and only one of them resolves.
orca labware list prints the instances: short id, template, barcode and location. A location reading (expected) means the record expects the labware there but nobody has confirmed it; (removed) means it has been retired. Mid-flight labware reads are covered on Monitor.
JSON for scripts
Every list verb supports --json. Output is a JSON array, one element per entity.
$ orca device list --json | jq '.[] | select(.type_name == "MLSTAR") | .name'
"ml_star"
Pitfalls
device infoshows the runtime's view, not a fresh driver poll. If a device drifted out of sync (manual intervention, a comms blip),inforeports the last-known state. To force a poll, call the driver's own status method withdevice invoke.teachpoints showreturns the last recorded coordinate. If someone updated teachpoints mid-session,showreflects the store as it is now. Useorca audit listto see who changed what.describe workflowlists threads in declaration order, not execution order. Spawn order comes fromwf.start()andwf.thread()calls and from event handlers, not from the template list.- A catalog row is not proof you can place that labware. Most rows have no model behind them, and the refusal only arrives when you try to register one. See What the catalog is for.
See also
- Run a workflow: submit one of the workflows you just listed.
- Monitor: the same nouns read mid-flight, with live state on them.
- Operator interventions: the write side of teachpoints, deck layouts and labware.
- Devices: how a device and its driver are declared.
- Move parameters: the six layers behind teachpoints and access configs.