[Guide 01] Getting Started with DSL: Writing Machine Sequences Like Sentences
DSL Starter Guide (
ds2 v2;)Learn the 4-level building blocks, the Box · Circle · Arrow visual map, how just 2 primitives (
>and|>) compose all 5 arrows, parallel calls (Call DAG), and one-block homing (origin flow).
1. Four Building Blocks of Any Machine
Level · Keyword · Everyday Meaning · Role
1. Outer Frame · project · Cell or line project · Groups all units and selects the target controller with active <Controller>;.
2. Equipment Unit · system · Cylinder, robot, or controller · Every unit is a uniform system ({{Fractal Reuse::A station controller system built today can be reused tomorrow as a child unit inside a larger plant-line project.}}).
3. Sequence Track · flow / origin flow · Production vs. homing track · Separates normal cycle steps (flow) from safe return-to-home sequences (origin flow).
4. Unit Step · work · One process step · Actions like Lock, Drill, or Unload. Add {{finished::Marks that the actuator starts in its completed/retracted home state at power-on (B0).}} to initial home states.
2. Visual Map: Box · Circle · Arrow
Shape · Name · In Code · Role
[[shape:box\ · ▢ Box]] · Work (work) · work DrillBothSides { ... } · One major process step completed together on a part
[[shape:circle\ · Circle]] · Call (api) · Clamp.Lock · A child unit action triggered inside a Box (Work)
[[shape:arrow\ · →]] · Arrow (Edge) · >, `\ · >, =>, =\ · >, <\ · >` · Links controlling start order, state cleanup, and safety locks
3. How 2 Primitive Arrows (> & |>) Compose All 5
You only need two basic pieces—> (Start) and |> (Reset)—to understand every arrow in DSL:
Kind · Glyph · Symbol · Built From · When to Use It
Primitive 1 · [[op:start]] · A > B · Start · Starts B when A finishes (A stays Done). Used to chain Circles (Call) inside a work.
Primitive 2 · [[op:reset]] · **`A \ · > B`** · Reset · Clears B's Done mark when A starts. Used to loop the last step back to the first step.
Composite 1 · [[op:baton]] · A => B · A > B + **`B \ · > A`** · Baton Pass! Starts B and immediately clears A in {{one scan transaction::StartReset prevents scan-gap races between starting B and resetting A.}}.
Composite 2 · [[op:term]] · **`A =\ · > B`** · A => B + **`A \ · > B`** · Baton Pass + End Auto-Clean! Also clears B when A restarts on the next cycle ({{Prevents 2nd-cycle deadlock::Required on single-action units like `Drill =\ · > Retract; (DS2-E025` static check).}}).
Composite 3 · [[op:mutex]] · **`A <\ · > B`** · **`A \ · > B + B \ · > A`** *(+ Block)* · Opposing-Motion Safety Guard! Enforces exclusive execution, completion reset, and unlatch between opposing steps (`Up <\ · > Down). *(Use zone_mutex` Shared Zone to cap concurrent entry capacity without resetting peers.)*
4. Parallel Calls Inside One Box (Call DAG)
Inside a single work, chain or fork/join child api calls with no fixed call-count cap—parentheses (A, B) run units in parallel and wait until both finish:
ds2 v2;
project DualDrillCell {
active CellController;
system Clamp {
flow Act {
work Lock { duration 200ms; }
work Unlock finished { duration 200ms; }
Lock <|> Unlock;
}
api Lock = Act.Lock;
api Unlock = Act.Unlock;
}
system LeftDrill {
flow Act {
work Drill { duration 400ms; }
work Retract;
Drill =|> Retract;
}
api Drill = Act.Drill;
}
system RightDrill {
flow Act {
work Drill { duration 450ms; }
work Retract;
Drill =|> Retract;
}
api Drill = Act.Drill;
}
system CellController {
flow Main {
work DrillBothSides {
Clamp.Lock > (LeftDrill.Drill, RightDrill.Drill) > Clamp.Unlock;
}
}
api RunOnce = Main.DrillBothSides;
}
}
- Token Boundary Inside Calls ({{
CALL-TOKEN-BOUNDARY-1&DS2-I002::Product-boundCalltargets mint isolated preset tokens without leaking back to callers, while tokenlessCalltargets borrow caller token fields and back-propagateWriteMask=1writes strictly on normal completion; partial-productNOT_APPLICABLEfields use Kleene 3-valued logic (DS2-I002).}}): Parenthesized calls(A, B)synchronize parallel units cleanly; declaring non-virtualsensingdirectly on aWorkwithoutWork-ownedinputemitsDS2-W002and is excluded from runtime watchdog budgets (Cut(G, A)).
5. Safe Return-to-Home in One Block (origin flow)
Adding origin flow inside the active controller automatically creates at-origin detection and collision-free homing (axes already at home are skipped automatically):
ds2 v2;
project PackagingLine {
active LineController;
system StopperUnit {
flow Motion {
work Up { duration 150ms; }
work Down finished { duration 150ms; }
Up <|> Down;
}
api Up = Motion.Up;
api Down = Motion.Down;
}
system LineController {
origin flow Homing {
work LowerStopper { StopperUnit.Down reuse completed; }
}
flow MainFlow {
work HoldBox { StopperUnit.Up; }
work ReleaseBox { StopperUnit.Down; }
HoldBox => ReleaseBox;
}
}
}
- Finite Homing Guarantee: Chain multi-step
origin flowsequences with=>(ZRetract => XHome => ClampRelease;) so homing always terminates cleanly into {{Auto-Ready state::Models withorigin flowcold-boot in10(ORIGIN_REQ)gatingAUTOuntil30(AUTO_READY)and wireoriginapicalls toHMI_TR_TO_HOMING; loops,=|>,|>, andfinishedinsideorigin floware rejected byDS2-E028.}}.