@vention/vention-skills 0.1.0

package/skills/vention-machine-logic/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: vention-machine-logic
+description: Write, edit, validate, and deploy MachineLogic Python applications for Vention machines with the machine-logic-sdk and the Vention CLI. Use when the user wants to program a Vention machine or MachineMotion controller, drive actuators, conveyors, robots, pneumatics, or digital I/O from Python, build a state machine for a cell, debug a failing application from its logs, or pull, push, or link an application with the Vention CLI (vention or vn). Trigger on MachineLogic, machine-logic-sdk, MachineMotion, MachineBuilder applications, or the Vention CLI, including inside a directory that holds .machine-code-app-directory-info.json. Do not use when the user has asked for no program at all and only wants an existing machine, its parts, or its configuration explained back to them in words; a read-only script that prints what the machine reports is still a program.
+license: MIT
+metadata:
+  version: "0.1.0"
+  machine-logic-sdk: ">=3.0,<4"
+  author: Vention
+---
+
+# Vention MachineLogic applications
+
+A MachineLogic application is a Python program that drives a Vention machine through the `machinelogic` package (installed as `machine-logic-sdk`). It runs on the machine's MachineMotion AI controller or on the design's digital twin, and it travels between the user's disk and the design through the Vention CLI (`vention`).
+
+## Before you start
+
+Work only inside a directory the Vention CLI has linked to an application. The marker is `.machine-code-app-directory-info.json` in the directory root.
+
+1. If the marker is missing, ask the user to run `vention pull` (downloads the application and its configuration) or `vention link` (attaches an existing folder) in that directory, or to give you the path of a directory that already has it. Never create the marker or an application layout by hand: `vention push` cannot round-trip a directory the CLI did not link.
+2. If `vention` says it is not logged in, the user runs `vention login`.
+3. The design must be open in MachineBuilder with its MachineLogic tab active while pulling, pushing, or reading logs; that is what keeps the design's twin reachable.
+
+## Read the configuration first
+
+`vention pull` writes `.vention-design-configuration.json` next to the code. Read it before writing any device call. Every actuator, robot, input, output, pneumatic, and AC motor is addressed by the `friendlyName` in that file, character for character. A wrong name fails at run time with a `MachineException`, not at write time.
+
+- Never guess or tidy a name. `"Gripper Vaccum"` in the configuration means `machine.get_output("Gripper Vaccum")` in the code.
+- Inputs and outputs use the pin's friendly name (`"Input A1"`), not the name of the device wired to it.
+- If the file is missing, ask the user to run `vention pull` again rather than inventing names.
+
+## The CLI at use time
+
+Do not rely on a memorised command list. At the start of a session run `vention --version` and `vention --help`, and run `vention <command> --help` before using a command for the first time. Describe only what the installed version prints.
+
+- If `vention` is not on the PATH, tell the user to install it with `npm install -g @vention/vention-cli`, then stop describing commands they do not have.
+- Older versions lack commands newer ones have. If `--help` does not list a command you expected, say so instead of using it, and offer the upgrade: `npm install -g @vention/vention-cli@latest`.
+- `vention` and `vn` are the same binary; show the user the long form.
+
+## The SDK version comes from the application
+
+Every version the target installs is declared by the application: `requirements.txt` for Python, `customui/package.json` for the HMI bundle. The SDK is one of those dependencies, not a property of the machine. When a `requirements.txt` exists, the execution engine builds the application a dedicated environment from exactly that file, so the pin decides the version rather than describing it.
+
+Read `machine-logic-sdk==3.1.0` from `requirements.txt`. That is the answer. A `uv.lock` answers too when the project is uv-managed on the authoring side, but the target never installs from it: the engine compiles `requirements.txt` into a lock of its own inside the venv. A range such as `>=3.0` is a constraint, not a version, so treat it as no pin. Never infer a version from the code you are reading: three majors are documented at once, and a signature taken from the wrong one compiles against nothing.
+
+An application with no pin inherits whatever the target already has, and nothing on disk says what that is. Tell the user the version is undeclared and offer to add the pin. Until it is there, read the target and name the signal alongside the version:
+
+- The startup line `vention logs` prints while the application runs.
+- On a controller only, `softwareVersion` in `.vention-design-configuration.json`, read through the compatibility table on the version's documentation page. A digital twin hardcodes that field, so skip this signal there.
+- `pip show machine-logic-sdk` on the user's laptop. That is the authoring environment, not the target, so label it unverified.
+
+Say `unknown` when none of them answers.
+
+Pin the version the target can install rather than the newest one: a controller has the SDK that came with its MMAI release, an existing application runs against the version it was written for, and pinned dependencies are fetched on the target, so an isolated cell resolves only what it already has. A `requirements.txt` that lists no `machine-logic-sdk` removes the SDK the application would otherwise inherit, so once that file exists the SDK belongs in it.
+
+With the version in hand, fetch the reference published for it:
+
+```bash
+python3 scripts/vention-docs.py --version 3.1.0 --print-page
+python3 scripts/vention-docs.py --from-requirements requirements.txt --print-url
+```
+
+It matches the published page by title, checks that the page body names that version before printing anything from it, and refuses to answer from a different version. On `unavailable: <reason>` (exit 2) the documentation is unreachable or publishes no page for that version: continue from this file alone and tell the user the reference was unavailable.
+
+## Library documentation at the pinned version
+
+Vention's application libraries publish their documentation as their package README. Read the README of the version the application pins rather than recalling an API that moved between releases.
+
+```bash
+python3 scripts/library-readme.py --from-app .
+```
+
+It reads `requirements.txt` for `vention-state-machine`, `vention-storage`, and `vention-communication`, and `customui/package.json` (the HMI source folder; `ui/` next to it holds only the built bundle) for `@vention/machine-ui`, `@vention/machine-apps-components`, and `@vention/machine-logic-ui-sdk`, and prints each README under a `## <name>@<version>` heading. A dependency declared as a range is reported `unavailable` instead of answered from the newest release. `--pypi <name> <version>` and `--npm <name> <version>` read a single package.
+
+## The shape of an application
+
+Write the code to `main.py` before you answer, every time the user asks for a program, a script or a readout — even a one-off, even a read-only one. Code that only appears in the reply cannot be type-checked, pushed, or run.
+
+`main.py` is the entry point named in `project.json`. Resolve devices once from the configuration, keep speeds in named constants at the top, and make the shutdown path unconditional.
+
+```python
+from machinelogic import Machine, MotionProfile, VentionException
+from machinelogic.types import MachineSafetyState
+
+TRAVEL_SPEED_MM_S = 100.0
+TRAVEL_ACCELERATION_MM_S2 = 200.0
+
+machine = Machine()  # one per process; connects to the controller this application runs on
+axis = machine.get_actuator("x")  # friendlyName from .vention-design-configuration.json
+part_present = machine.get_input("Input A1")
+profile = MotionProfile(velocity=TRAVEL_SPEED_MM_S, acceleration=TRAVEL_ACCELERATION_MM_S2)
+
+try:
+    axis.home(timeout=30)  # absolute positions mean nothing before homing
+    for station_mm in (50.0, 150.0, 250.0):
+        # check the emergency stop once per pass in any loop that commands motion
+        if machine.state.safety_state == MachineSafetyState.EMERGENCY_STOP:
+            print("emergency stop active, leaving the cycle")
+            break
+        if not part_present.state.value:
+            axis.move_absolute(station_mm, profile)
+except VentionException as error:  # base class of every SDK exception
+    print(f"machine fault: {error}")
+finally:
+    axis.stop()  # the shutdown path runs whatever happened above
+```
+
+`Machine()` is one per process. Once it fails, a retry in the same process fails too: the user restarts the application (stop, then play) to reconnect.
+
+The SDK documentation for the target's version is fetched at use time (`scripts/vention-docs.py`, above) and the complete examples below show the rest of the shape; when a call is in neither, say the SDK does not expose it rather than inventing one.
+
+An operator screen for the application is the `vention-machine-logic-hmi` skill's job. When the request asks for one, load that skill before writing the RPC surface and build the screen in the same task: the request is not done until both exist, so never stop between them to ask whether to go on.
+
+## Reaching a device
+
+The getter follows the element's type in `.vention-design-configuration.json`, not the word the user reached for.
+
+```python
+machine.get_actuator("x")                       # a linear or rotary axis
+machine.get_robot("UR3e")                       # an arm
+machine.get_pneumatic("Outfeed Stopper - Air")  # a two-position air cylinder
+machine.get_input("Input A1")                   # a digital input pin
+machine.get_output("Gripper Vaccum")            # a digital output pin
+machine.get_ac_motor("Belt Drive")
+machine.get_scene()                             # the robot's taught positions and frames
+machine.get_machine_motion("MachineMotion AI").get_actuator("x")  # scoped to one controller
+```
+
+An air cylinder the configuration lists as a pneumatic is `get_pneumatic`, moved with `push_async()` and `pull_async()`; `IPneumatic` has no `extend()` or `retract()`. Drop to `get_output` on its solenoid pins only when the user asks for the raw signals rather than the cylinder. Go through `get_machine_motion` whenever the design carries more than one controller, or the user names the controller a device hangs off: the machine-wide lookup searches them all and is ambiguous there.
+
+## Moving, and when not to block
+
+A move blocks. Reach for the `_async` half of one only when there is work to do while the machine travels, and finish it on the SDK's completion signal rather than a guessed sleep.
+
+```python
+axis.move_absolute(180.0, profile)         # also move_relative; returns on arrival
+robot.movel(pose, 50.0, 100.0)             # also movej, move_to_target
+print(axis.state.position)                 # live position, readable at any time
+
+axis.move_absolute_async(180.0, profile)   # also move_relative_async
+print(axis.state.move_in_progress)         # True while it travels
+axis.wait_for_move_completion(timeout=20)  # actuators take a timeout
+
+robot.movej_async(joint_angles_deg, 40.0, 80.0)  # also movel_async, move_to_target_async
+print(f"cycle {cycle} took {elapsed:.1f} s")     # the work that was worth not blocking for
+robot.wait_for_motion_completion()               # robots take no arguments
+```
+
+Poll `state.move_in_progress` only when something has to be serviced mid-travel, and still finish on the wait. `move_continuous_async` is the exception to all of it: it has no target to arrive at, so it ends at `stop()`, never at a wait.
+
+## Reacting to an input edge
+
+Polling can straddle a pulse that opens and closes between two reads. `on_state_change` fires on every transition, on a background thread, so the process has to stay alive for the edges to land in:
+
+```python
+from machinelogic.ivention.idigital_input import IDigitalInput
+
+def on_edge(value: bool, digital_input: IDigitalInput) -> None:
+    print(f"{digital_input.configuration.name} went {'high' if value else 'low'}")
+
+part_present.on_state_change(on_edge)
+```
+
+## Doing several things at once
+
+A plain sequence stays a plain synchronous script. When two or more things have to happen at the same time (two conveyors, a counter beside a cycle, a cycle that also listens for MQTT), run each as a task on one asyncio loop. The SDK has no coroutines: an `_async` method only sends the command and returns, and the waits block. Keep every blocking call off the loop, or it stalls every other task for as long as it blocks.
+
+```python
+async def feed_board(conveyor: IActuator, line: LineState, travel_mm: float) -> None:
+    recipe = line.recipe
+    profile = MotionProfile(velocity=recipe.conveyor_speed_mm_s, acceleration=recipe.conveyor_acceleration_mm_s2)
+    conveyor.move_relative_async(travel_mm, profile)                # quick: sends the move
+    await asyncio.to_thread(conveyor.wait_for_move_completion, 20)  # the wait blocks a worker thread, not the loop
+    line.boards_out += 1                                            # quick calls and shared state stay on the loop
+```
+
+A blocking call with no `_async` version, such as `home`, goes through `asyncio.to_thread` too; home once, before the tasks start.
+
+- Start the tasks with `asyncio.gather` or `asyncio.wait`; the target runs Python 3.10, which has no `TaskGroup`.
+- SDK callbacks (`on_state_change`, `machine.on_system_state_change`, MQTT) run on SDK threads. Hand their work to the loop with `loop.call_soon_threadsafe`, never by touching shared state from the callback.
+- Cancelling a task does not stop a move a worker thread is waiting on. The shutdown path stops every device it started, in a `finally`.
+- Keep shared state in one dataclass created in `main` and passed to each task. Only the loop's thread changes it, so it needs no lock.
+
+**Recipes.** No Vention library defines a recipe. Write one frozen dataclass per parameter set in a `dict[str, Recipe]`, pick one at start or on an operator event, and read it through the shared state. When recipes must survive a restart, store them with `vention-storage` and read its README first (`library-readme.py`, above).
+
+**State machines.** When the cell has modes (idle, running, paused, faulted) or reacts to events rather than running one sequence, use `vention-state-machine`: pin it in `requirements.txt`, read its README at that pin, and build on its `ready` and `fault` states. A machine has one active state, so concurrent machines are separate instances on the same loop. `examples/pick-and-place-state-machine` shows the shape; `examples/parallel-conveyor-with-recipe` shows parallel tasks with shared state and a recipe. If the README at that pin has no "State naming rules" section, give every member of a `StateGroup` a single word with no underscore: those versions split a nested state's name on `_`, so a member like `interlock_check` raises `KeyError: 'interlock'` when the machine is built.
+
+## Taught robot positions
+
+`vention pull` also writes `.vention-design-scene-assets.json` when the design has taught positions. It is the list `machine.get_scene()` loads, one record per position or frame: its `type` names the getter that reads it (`RobotWaypoint` is `get_cartesian_target`, `RobotJointPosition` is `get_joint_target`, `RobotCalibrationFrame` is `get_calibration_frame`, `ReferenceFrame` is `get_reference_frame`) and `parameters.name` is the name to pass, character for character. Read it before naming a target. When a step needs a position the file does not hold, ask the user to teach it on the design; never map a missing step onto a target that happens to exist.
+
+Positions taught on the design live in the scene under their friendly names. Drive off those names rather than copying pose numbers out of a pendant into the source. `movel` holds a straight line in Cartesian space; `movej` interpolates the joints and can swing the tool sideways on the way, so a lift off a part or an approach that has to come straight down is `movel`.
+
+```python
+scene = machine.get_scene()
+print(scene.get_cartesian_target("Pick").get_position(relative_to="robot_base"))  # [x, y, z, rx, ry, rz]
+print(scene.get_joint_target("home").get_joint_angles())
+frame = scene.get_calibration_frame("Pick Frame")
+print(frame.get_calibrated_value() or frame.get_default_value())  # None until the frame is calibrated
+robot.move_to_target("Pick", "l", 150.0, 300.0)  # "l" straight line, "j" joint space
+pose, _timestamp = robot.state.cartesian_position_data  # live pose, to compute a target from where it is
+pose[2] += 20.0
+robot.movel(pose, 50.0, 100.0)
+```
+
+## Complete examples
+
+Each example is a standalone `main.py` whose module docstring names the device names it assumes. Copy the structure, then replace the names with the ones in the user's configuration.
+
+- `examples/homing-and-indexing/main.py`: home one actuator, then index through three absolute positions, reading a sensor before each move, with a `finally` that stops the axis.
+- `examples/pick-and-place-state-machine/main.py`: a `vention-state-machine` machine (ready, picking, placing, fault) driving one robot, one gripper output, and one part-present input on an asyncio loop, with the emergency stop routed to `fault` and the robot stopped on every way out.
+- `examples/parallel-conveyor-with-recipe/main.py`: two conveyors and a pop-up transfer as parallel asyncio tasks, sharing counters through one dataclass, with speeds and batch size taken from a recipe.
+- `examples/conveyor-with-sensor/main.py`: run a conveyor actuator continuously until a sensor sees a part, count parts, and stop after a target count.
+
+## Validate before you push
+
+1. Keep a `requirements-dev.txt` and a `pyrightconfig.json` next to `requirements.txt`. The engine installs only `requirements.txt`, so neither reaches the machine.
+
+   ```text
+   -r requirements.txt
+   pyright==1.1.411
+   ```
+
+   ```json
+   { "typeCheckingMode": "basic", "pythonVersion": "3.10", "reportMissingImports": true, "enableTypeIgnoreComments": false, "venvPath": ".", "venv": ".venv" }
+   ```
+
+2. Run `uv venv --python 3.10 && uv pip install -r requirements-dev.txt`, then `.venv/bin/pyright`. The venv runs the target's Python and the SDK the application pins, so a wrong name or signature shows up against what the target runs. The first pyright run may download Node if none is on the PATH, so a slow or offline first run is not a type error. Fix every error and run it again until it is clean.
+3. If `uv` is missing or the install fails, tell the user the code is unvalidated. Never report a check you could not run as passed.
+4. `vention push`, then run the application on the digital twin from MachineBuilder before any hardware run.
+5. Read the output with `vention logs`. MachineLogic failures name the device and the reason; read the log before proposing a change.
+6. Show the user the diff before pushing over an application they did not write in this session.
+
+## Safety
+
+This code drives physical machinery that can injure someone.
+
+- Before a run on real hardware, tell the user plainly what will move and how far.
+- Recommend a low-speed dry run before production speeds.
+- Never remove, bypass, or work around an emergency stop, safety interlock, light curtain, door switch, or speed limit, and never suggest doing so, even temporarily, even for testing. If a safety device is blocking a program, say so and stop.
+- Never write code that starts motion automatically on power-up unless the user has explicitly asked for it and confirmed the cell is guarded.
+
+## Common mistakes
+
+- Device names that do not match `.vention-design-configuration.json`.
+- Answering with code in the reply instead of writing `main.py` to disk.
+- Commanding absolute moves before homing.
+- Calling a move without a `MotionProfile`, or passing jerk to a continuous move (it is ignored with a warning).
+- Using an `_async` move where a blocking one would do, leaving one without its `wait_for_move_completion` / `wait_for_motion_completion`, or sleeping a guessed travel time in place of that wait.
+- Driving a pneumatic through `get_output`, or inventing `extend()` / `retract()` on it.
+- Reaching an actuator machine-wide on a rig with more than one controller instead of through `get_machine_motion`.
+- Hard-coding a pose the scene already holds under a taught name.
+- Creating `Machine()` at import time, or twice in one process.
+- Treating a simulation pass as evidence the program is safe on hardware.
+- `pip install machinelogic`: the package is `machine-logic-sdk`; only the import is `machinelogic`.
+- Calling a blocking SDK method (a wait, `home`, a blocking move) directly inside `async def`, or using `asyncio.TaskGroup` (Python 3.11) on a 3.10 target.
+- Assuming a cancelled task stopped its move.

package/skills/vention-machine-logic/examples/conveyor-with-sensor/main.py

@@ -0,0 +1,58 @@
+"""Run a conveyor until a sensor sees a part, count parts, stop after a target count.
+
+Assumes these friendly names from .vention-design-configuration.json:
+- actuator "x": the conveyor belt axis, configured in mm
+- input "Input A2": a photo-eye at the end of the belt, high while a part blocks it
+
+A part is counted on the sensor's rising edge. The belt stops when the target count
+is reached, when no part shows up for SENSOR_TIMEOUT_S, or on any fault.
+"""
+
+import time
+
+from machinelogic import ActuatorException, Machine, MachineException, MotionProfile
+from machinelogic.types import MachineSafetyState
+
+BELT_SPEED_MM_S = 150.0
+BELT_ACCELERATION_MM_S2 = 300.0
+PARTS_TO_COUNT = 5
+SENSOR_TIMEOUT_S = 60.0
+POLL_INTERVAL_S = 0.05
+
+
+def main() -> None:
+    machine = Machine()
+    belt = machine.get_actuator("x")
+    photo_eye = machine.get_input("Input A2")
+    # Continuous moves use velocity and acceleration only; jerk would be ignored.
+    belt_profile = MotionProfile(velocity=BELT_SPEED_MM_S, acceleration=BELT_ACCELERATION_MM_S2)
+
+    parts_seen = 0
+    try:
+        # A continuous move has no target position, so the belt does not need homing.
+        belt.move_continuous_async(belt_profile)
+        deadline = time.monotonic() + SENSOR_TIMEOUT_S
+        part_in_front = photo_eye.state.value
+
+        while parts_seen < PARTS_TO_COUNT and time.monotonic() < deadline:
+            if machine.state.safety_state == MachineSafetyState.EMERGENCY_STOP:
+                print("emergency stop active, stopping the belt")
+                break
+            sensor_now = photo_eye.state.value
+            if sensor_now and not part_in_front:
+                parts_seen += 1
+                deadline = time.monotonic() + SENSOR_TIMEOUT_S
+                print(f"part {parts_seen} of {PARTS_TO_COUNT}")
+            part_in_front = sensor_now
+            time.sleep(POLL_INTERVAL_S)
+
+        if parts_seen < PARTS_TO_COUNT:
+            print(f"no part for {SENSOR_TIMEOUT_S:.0f} s, stopping with {parts_seen} counted")
+    except (ActuatorException, MachineException) as error:
+        print(f"machine fault: {error}")
+    finally:
+        belt.stop()
+
+
+if __name__ == "__main__":
+    main()

package/skills/vention-machine-logic/examples/homing-and-indexing/main.py

@@ -0,0 +1,51 @@
+"""Home one actuator, then index through three absolute positions.
+
+Assumes these friendly names from .vention-design-configuration.json:
+- actuator "x": a linear axis configured in mm
+- input "Input A1": a station-occupied sensor, high while a part sits at the station
+
+Before each move the sensor is read; an occupied station is skipped. Run on the
+digital twin before any hardware run.
+"""
+
+import time
+
+from machinelogic import ActuatorException, Machine, MachineException, MotionProfile
+from machinelogic.types import MachineSafetyState
+
+HOMING_TIMEOUT_S = 30.0
+STATION_POSITIONS_MM = [50.0, 150.0, 250.0]
+INDEX_SPEED_MM_S = 100.0
+INDEX_ACCELERATION_MM_S2 = 200.0
+DWELL_AT_STATION_S = 0.5
+
+
+def main() -> None:
+    machine = Machine()
+    axis = machine.get_actuator("x")
+    station_occupied = machine.get_input("Input A1")
+    index_profile = MotionProfile(velocity=INDEX_SPEED_MM_S, acceleration=INDEX_ACCELERATION_MM_S2)
+
+    try:
+        # Absolute positions are only meaningful after homing.
+        axis.home(timeout=HOMING_TIMEOUT_S)
+        print("homed")
+
+        for station_position_mm in STATION_POSITIONS_MM:
+            if machine.state.safety_state == MachineSafetyState.EMERGENCY_STOP:
+                print("emergency stop active, leaving the cycle")
+                break
+            if station_occupied.state.value:
+                print(f"station at {station_position_mm:.0f} mm is occupied, skipping")
+                continue
+            axis.move_absolute(station_position_mm, index_profile)
+            print(f"indexed to {station_position_mm:.0f} mm")
+            time.sleep(DWELL_AT_STATION_S)
+    except (ActuatorException, MachineException) as error:
+        print(f"machine fault: {error}")
+    finally:
+        axis.stop()
+
+
+if __name__ == "__main__":
+    main()

package/skills/vention-machine-logic/examples/parallel-conveyor-with-recipe/main.py

@@ -0,0 +1,118 @@
+"""Two conveyors and a pop-up transfer running at the same time, driven by a recipe.
+
+Assumes these friendly names from .vention-design-configuration.json:
+- actuators "Infeed" and "Outfeed": timing-belt conveyors
+- pneumatic "InfeedPopUP-Air": lifts a board off the infeed onto the cross conveyor
+- input "End Infeed": beam break at the end of the infeed, high while a board is there
+- input "End Outfeed": beam break at the end of the outfeed, high while a board is there
+
+Each sequence is a task on one asyncio loop. SDK callbacks arrive on SDK threads and are handed to
+the loop with call_soon_threadsafe; the shared LineState is only changed on the loop's thread, so it
+needs no lock. The batch ends when the recipe's board count leaves the outfeed or the emergency stop
+trips, and the finally stops both conveyors and drops the pop-up whatever happened.
+Run it as `python main.py fragile` to pick a recipe; the default is "standard".
+"""
+
+import asyncio
+import sys
+from dataclasses import dataclass
+
+from machinelogic import Machine, MotionProfile, VentionException
+from machinelogic.ivention.iactuator import IActuator
+from machinelogic.ivention.idigital_input import IDigitalInput
+from machinelogic.ivention.imachine import MachineOperationalState, MachineSafetyState
+from machinelogic.ivention.ipneumatic import IPneumatic
+
+
+@dataclass(frozen=True)
+class Recipe:
+    conveyor_speed_mm_s: float
+    conveyor_acceleration_mm_s2: float
+    boards_per_batch: int
+
+
+RECIPES = {
+    "standard": Recipe(conveyor_speed_mm_s=200.0, conveyor_acceleration_mm_s2=400.0, boards_per_batch=20),
+    "fragile": Recipe(conveyor_speed_mm_s=80.0, conveyor_acceleration_mm_s2=150.0, boards_per_batch=10),
+}
+POPUP_HOLD_S = 1.0  # the cylinder reports no completion, so the transfer holds for a fixed time
+
+
+@dataclass
+class LineState:
+    recipe: Recipe
+    boards_transferred: int = 0
+    boards_out: int = 0
+
+
+async def transfer_boards(popup: IPneumatic, arrivals: "asyncio.Queue[None]", line: LineState) -> None:
+    while True:
+        await arrivals.get()
+        popup.push_async()
+        await asyncio.sleep(POPUP_HOLD_S)
+        popup.pull_async()
+        line.boards_transferred += 1
+
+
+async def count_boards(departures: "asyncio.Queue[None]", line: LineState, done: asyncio.Event) -> None:
+    while line.boards_out < line.recipe.boards_per_batch:
+        await departures.get()
+        line.boards_out += 1
+    done.set()
+
+
+async def run_line(recipe_name: str) -> None:
+    recipe = RECIPES[recipe_name]
+    machine = Machine()
+    conveyors: list[IActuator] = [machine.get_actuator("Infeed"), machine.get_actuator("Outfeed")]
+    popup = machine.get_pneumatic("InfeedPopUP-Air")
+    end_infeed = machine.get_input("End Infeed")
+    end_outfeed = machine.get_input("End Outfeed")
+
+    loop = asyncio.get_running_loop()
+    line = LineState(recipe=recipe)
+    done = asyncio.Event()
+    arrivals: "asyncio.Queue[None]" = asyncio.Queue()
+    departures: "asyncio.Queue[None]" = asyncio.Queue()
+
+    def on_rising_edge(queue: "asyncio.Queue[None]"):
+        def callback(value: bool, _input: IDigitalInput) -> None:
+            if value:
+                loop.call_soon_threadsafe(queue.put_nowait, None)
+
+        return callback
+
+    def on_safety(_operational: MachineOperationalState, safety: MachineSafetyState) -> None:
+        if safety == MachineSafetyState.EMERGENCY_STOP:
+            print("emergency stop, ending the batch")
+            loop.call_soon_threadsafe(done.set)
+
+    profile = MotionProfile(velocity=recipe.conveyor_speed_mm_s, acceleration=recipe.conveyor_acceleration_mm_s2)
+    workers = [
+        asyncio.create_task(transfer_boards(popup, arrivals, line)),
+        asyncio.create_task(count_boards(departures, line, done)),
+    ]
+    finished = asyncio.create_task(done.wait())
+    try:
+        end_infeed.on_state_change(on_rising_edge(arrivals))
+        end_outfeed.on_state_change(on_rising_edge(departures))
+        machine.on_system_state_change(on_safety)
+        for conveyor in conveyors:
+            conveyor.move_continuous_async(profile)
+        completed, _pending = await asyncio.wait([*workers, finished], return_when=asyncio.FIRST_COMPLETED)
+        for task in completed:
+            task.result()  # re-raises a worker's exception here rather than losing it
+    except VentionException as error:
+        print(f"machine fault: {error}")
+    finally:
+        for task in [*workers, finished]:
+            task.cancel()
+        await asyncio.gather(*workers, return_exceptions=True)
+        for conveyor in conveyors:
+            conveyor.stop()
+        popup.pull_async()
+        print(f"{line.boards_out} of {recipe.boards_per_batch} boards out, {line.boards_transferred} transferred ({recipe_name})")
+
+
+if __name__ == "__main__":
+    asyncio.run(run_line(sys.argv[1] if len(sys.argv) > 1 else "standard"))

package/skills/vention-machine-logic/examples/parallel-conveyor-with-recipe/requirements.txt

@@ -0,0 +1 @@
+machine-logic-sdk==3.1.0

package/skills/vention-machine-logic/examples/pick-and-place-state-machine/main.py

@@ -0,0 +1,159 @@
+"""Pick-and-place cycle on vention-state-machine, driven from one asyncio loop.
+
+Assumes these friendly names from .vention-design-configuration.json:
+- robot "UR3e"
+- output "Gripper Vaccum": vacuum gripper, True switches suction on
+- input "Input A1": part-present sensor at the pick position, high while a part is there
+
+The machine starts in `ready`; a part arriving, or one already waiting when a cycle ends, triggers
+`start` into picking. Robot moves start with movej_async and finish on the SDK's completion wait in a
+worker thread, so the loop keeps serving the part sensor and the safety callback. An emergency stop or
+any exception in a step routes to `fault`, which cancels the running step; the `finally` stops the arm
+and releases the gripper on every way out, and an error that is not a VentionException is re-raised after it.
+The joint targets are placeholders in degrees; teach real ones on the digital twin first.
+"""
+
+import asyncio
+from typing import Awaitable, Callable, Optional
+
+from machinelogic import Machine, VentionException
+from machinelogic.ivention.idigital_input import IDigitalInput
+from machinelogic.ivention.idigital_output import IDigitalOutput
+from machinelogic.ivention.imachine import MachineOperationalState, MachineSafetyState
+from machinelogic.ivention.irobot import IRobot
+from state_machine.core import BaseStates, BaseTriggers, StateMachine
+from state_machine.decorators import on_enter_state
+from state_machine.defs import State, StateGroup, Trigger
+
+JOINT_SPEED_DEG_S = 30.0
+JOINT_ACCELERATION_DEG_S2 = 60.0
+HOME_JOINTS_DEG = [0.0, -90.0, 90.0, -90.0, -90.0, 0.0]
+PICK_JOINTS_DEG = [20.0, -80.0, 100.0, -110.0, -90.0, 0.0]
+PLACE_JOINTS_DEG = [-40.0, -80.0, 100.0, -110.0, -90.0, 0.0]
+GRIP_SETTLE_S = 0.3
+CYCLES_TO_RUN = 3
+
+
+class Cycle(StateGroup):
+    picking: State = State()
+    placing: State = State()
+
+
+class States:
+    cycle = Cycle()
+
+
+class Triggers:
+    start = Trigger(BaseTriggers.START.value)
+    picked = Trigger("picked")
+    placed = Trigger("placed")
+
+
+TRANSITIONS = [
+    Triggers.start.transition(BaseStates.READY.value, States.cycle.picking),
+    Triggers.picked.transition(States.cycle.picking, States.cycle.placing),
+    Triggers.placed.transition(States.cycle.placing, BaseStates.READY.value),
+]
+
+
+class PickAndPlace(StateMachine):
+    def __init__(self, robot: IRobot, vacuum: IDigitalOutput, part_present: IDigitalInput, finished: asyncio.Event) -> None:
+        super().__init__(states=States, transitions=TRANSITIONS, enable_last_state_recovery=False)
+        self.robot = robot
+        self.vacuum = vacuum
+        self.part_present = part_present
+        self.finished = finished
+        self.cycles_done = 0
+        self.step: Optional["asyncio.Task[None]"] = None
+        self.error: Optional[Exception] = None
+
+    def start_if_ready(self) -> None:
+        if self.state == BaseStates.READY.value:
+            self.trigger(Triggers.start.name)
+
+    async def move_joints(self, target_deg: list[float]) -> None:
+        self.robot.movej_async(target_deg, JOINT_SPEED_DEG_S, JOINT_ACCELERATION_DEG_S2)
+        await asyncio.to_thread(self.robot.wait_for_motion_completion)
+
+    async def run_step(self, step: Callable[[], Awaitable[None]], trigger_when_done: str) -> None:
+        try:
+            await step()
+            self.trigger(trigger_when_done)
+        except VentionException as error:
+            print(f"fault in {self.state}: {error}")
+            self.trigger(BaseTriggers.TO_FAULT.value)
+        except Exception as error:  # anything else would end this task silently and leave the cell waiting
+            self.error = error
+            print(f"unexpected error in {self.state}: {error!r}")
+            self.trigger(BaseTriggers.TO_FAULT.value)
+
+    async def pick(self) -> None:
+        await self.move_joints(PICK_JOINTS_DEG)
+        self.vacuum.write(True)
+        await asyncio.sleep(GRIP_SETTLE_S)
+
+    async def place(self) -> None:
+        await self.move_joints(PLACE_JOINTS_DEG)
+        self.vacuum.write(False)
+        await asyncio.sleep(GRIP_SETTLE_S)
+        await self.move_joints(HOME_JOINTS_DEG)
+        self.cycles_done += 1
+
+    # Enter hooks are called synchronously, so each one starts its step as a task and returns.
+    @on_enter_state(States.cycle.picking)
+    def enter_picking(self, _: object) -> None:
+        self.step = self.spawn(self.run_step(self.pick, Triggers.picked.name))
+
+    @on_enter_state(States.cycle.placing)
+    def enter_placing(self, _: object) -> None:
+        self.step = self.spawn(self.run_step(self.place, Triggers.placed.name))
+
+    @on_enter_state(BaseStates.READY.value)
+    def enter_ready(self, _: object) -> None:
+        if self.cycles_done >= CYCLES_TO_RUN:
+            self.finished.set()
+        elif self.part_present.state.value:
+            # the part arrived mid-cycle, so no edge will start it; call_soon keeps the transition out of this hook
+            asyncio.get_running_loop().call_soon(self.start_if_ready)
+
+    @on_enter_state(BaseStates.FAULT.value)
+    def enter_fault(self, _: object) -> None:
+        if self.step is not None:
+            self.step.cancel()
+        self.finished.set()
+
+
+async def run_cell() -> None:
+    machine = Machine()
+    robot = machine.get_robot("UR3e")
+    vacuum = machine.get_output("Gripper Vaccum")
+    part_present = machine.get_input("Input A1")
+    loop = asyncio.get_running_loop()
+    finished = asyncio.Event()
+    cell = PickAndPlace(robot, vacuum, part_present, finished)
+
+    def on_part(value: bool, _input: IDigitalInput) -> None:
+        if value:
+            loop.call_soon_threadsafe(cell.start_if_ready)
+
+    def on_safety(_operational: MachineOperationalState, safety: MachineSafetyState) -> None:
+        if safety == MachineSafetyState.EMERGENCY_STOP:
+            loop.call_soon_threadsafe(cell.trigger, BaseTriggers.TO_FAULT.value)
+
+    try:
+        await asyncio.to_thread(robot.movej, HOME_JOINTS_DEG, JOINT_SPEED_DEG_S, JOINT_ACCELERATION_DEG_S2)
+        part_present.on_state_change(on_part)
+        machine.on_system_state_change(on_safety)
+        if part_present.state.value:
+            cell.start_if_ready()
+        await finished.wait()
+    finally:
+        robot.move_stop()
+        vacuum.write(False)
+        print(f"finished in state {cell.state} after {cell.cycles_done} cycle(s)")
+    if cell.error is not None:
+        raise cell.error
+
+
+if __name__ == "__main__":
+    asyncio.run(run_cell())

package/skills/vention-machine-logic/examples/pick-and-place-state-machine/requirements.txt

@@ -0,0 +1,2 @@
+machine-logic-sdk==3.1.0
+vention-state-machine==0.4.55