rill-patchbay 0.6.0-M2

The world where Automata live - control system for Rill
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# rill-patchbay

Automation and control system — LFOs, envelopes, sequencers, sensors, servos, and event mapping for the Rill signal graph.

## Architecture

Two-thread design. Automata run inside **Servos** on the control thread
(tokio actors) and communicate with the signal graph through lock-free
actor mailboxes (`ActorRef<CommandEnum>`).

```
Control thread (soft-RT):                     Signal thread (hard-RT):
  ┌──────────┐   ┌──────────┐
  │ Automaton│   │  Sensor  │                 ┌──────────────────┐
  │ (LFO,ENV)│   │(MIDI,OSC)│                 │  I/O callback    │
  └────┬─────┘   └────┬─────┘                 │  actor.drain()   │
       │              │                       │  generate()      │
       ▼              ▼                       │  process()       │
  ┌──────────────────────────┐   ClockTick    │  propagate()     │
  │        Servo             │◄───────────────│                  │
  │  automaton.step()       │                └────────▲─────────┘
  │  mapping.apply()        │                         │
  │  strategy: control+     │    SetParameter          │
  │            conflict     │─────────────────────────┘
  └──────────────────────────┘
```

Conflicts between automaton output and HID input (MIDI knob, OSC fader)
are resolved inside the Servo via `ControlStrategy` and `ConflictStrategy`. 
See `strategy.rs`.

## Key components

- **Automata** — `LfoAutomaton`, `EnvelopeAutomaton`, `RandomWalkAutomaton`,
  `SequencerAutomaton`, `FunctionAutomaton`, `CellularAutomaton`
- **Servos** — bridge automatons to graph node parameters via
  `ParameterMapping` (Linear, Exponential, Logarithmic, Inverted, Custom).
  Also apply sensor event mappings (MIDI CC → param, OSC address → param).
  Built-in conflict resolution via `ControlStrategy` (Absolute / Modulation)
  and `ConflictStrategy` (TouchOverride / BasePlusModulation / LastWriteWins).
- **Sensors** — acoustic (pitch, envelope follower), physical (knobs,
  buttons), MIDI, OSC (UDP-based address/argument sensors).
- **Event mapping** — MIDI CC → parameter, OSC address → parameter,
  with transforms.
- **`Servo`** — centralised API for bridging automatons to graph
  parameters, adding mappings, and handling sensor events (fka
  `PatchbayControl`).

## Usage

```rust
use std::sync::Arc;
use rill_core::queues::CommandEnum;
use rill_core_actor::{ActorRef, ActorSystem};
use rill_patchbay::prelude::*;

let system = Arc::new(ActorSystem::new());
let (graph_ref, mut graph_actor) = {
    let mut actor = system.spawn("graph", |_cmd: CommandEnum| {});
    (actor.actor_ref(), actor)
};

let lfo = LfoAutomaton::new("vibrato", 5.0, 0.5, 0.0, LfoWaveform::Sine);
let servo = Servo::new(
    "vibrato", lfo, osc_node_id, "frequency",
    ParameterMapping::Linear, 400.0, 480.0,
    system.clone(), graph_ref.clone(),
);
let _lfo_ref = servo.spawn(&system);

let env = EnvelopeAutomaton::adsr("amp_env", 0.01, 0.1, 0.7, 0.2);
let servo_env = Servo::new(
    "amp_env", env, vca_node_id, "gain",
    ParameterMapping::Linear, 0.0, 1.0,
    system.clone(), graph_ref.clone(),
);
let _env_ref = servo_env.spawn(&system);

graph_actor.drain();
```

## Feature flags

| Feature | Description |
|---------|-------------|
| `serde` | Serialization support (JSON/CBOR) |
| `json` | `serde` + JSON serialization |
| `cbor` | `serde` + CBOR serialization |
| `serialization` | `json` + `cbor` |
| `midi` | MIDI input via `rill-io` backends |
| `osc` | OSC input via `rill-osc` |
| `debug` | Control-path inspection (PatchbayInspector, automaton/sensor snapshots) |

### Debug infrastructure (`debug` feature)

- **`PatchbayInspector`** — collects automaton and sensor snapshots for control-path
  debugging. Automata report enabled/disabled state, current output value, and
  internal state (time, phase). Sensors report connection status and event count.
- **`Servo::inspector()`** — returns an `AutomatonInspector` that snapshots the
  servo's internal state via `Arc<Mutex<ServoState<A>>>`
- **`OscSensor::inspect()` / `MidiHub::inspect()`** — capture sensor status
  (connected, tracker active) for the debugger

## Dependencies

- `rill-core` — node traits, queues, types
- `rill-core-actor` — actor model for lock-free message passing
- `tokio` — green thread infrastructure

## Links

- Repository: <https://github.com/DigitalRats/rill>
- Documentation: <https://docs.rs/rill-patchbay>