Merge pull request #27 from copper-project/gbin/doc-drift

doc drift, mainly about ctx

Author: NRdrgz

book/src/ch03-setup.md

@@ -48,8 +48,11 @@ my_project/
 ├── build.rs              # Build script (required by Copper logging)
 ├── Cargo.toml            # Dependencies
 ├── copperconfig.ron      # Task graph definition
+├── justfile              # Helper commands (logreader, replay, DAG rendering)
 └── src/
     ├── main.rs           # Runtime entry point
+    ├── logreader.rs      # Offline log export utility
+    ├── resim.rs          # Replay / remote-debug entry point
     └── tasks.rs          # Your task implementations
 ```
 

book/src/ch04-project-structure.md

@@ -8,10 +8,12 @@ my_project/
 ├── build.rs              # Build script (sets up logging index)
 ├── Cargo.toml            # Dependencies and project metadata
 ├── copperconfig.ron      # Task graph definition
+├── justfile              # Helper commands for logs, replay, and DAG rendering
 └── src/
     ├── main.rs           # Runtime entry point
     ├── tasks.rs          # Your task implementations
-    └── logreader.rs      # (optional) Log export utility
+    ├── logreader.rs      # Log export utility
+    └── resim.rs          # Replay / remote-debug entry point
 ```
 
 ## Which files do I actually work on?
@@ -30,6 +32,8 @@ The rest is scaffolding that you set up once and rarely change:
 | `main.rs` | Boilerplate: create logger, build runtime, call `run()` | Rarely |
 | `build.rs` | Sets an env var for Copper's logging macros | Never |
 | `logreader.rs` | CLI tool to decode and export Copper's binary logs | Rarely |
+| `resim.rs` | Replay target for deterministic re-simulation and remote debug | Rarely |
+| `justfile` | Shortcuts for common commands like `just log` and `just dag` | Occasionally |
 | `Cargo.toml` | Dependencies | When adding new hardware driver crates |
 
 ## The mental model

book/src/ch06-messages.md

@@ -81,7 +81,7 @@ then emit `NoChange` on later cycles until something changes:
 ```rust
 type Output<'m> = output_msg!(CuLatchedStateUpdate<CameraCalibration>);
 
-fn process(&mut self, _clock: &RobotClock, output: &mut Self::Output<'_>) -> CuResult<()> {
+fn process(&mut self, _ctx: &CuContext, output: &mut Self::Output<'_>) -> CuResult<()> {
     if let Some(calibration) = self.pending_calibration.take() {
         output.set_payload(CuLatchedStateUpdate::Set(calibration));
     } else {
@@ -102,7 +102,7 @@ pub struct DepthProjector {
     calibration: CuLatchedState<CameraCalibration>,
 }
 
-fn process(&mut self, _clock: &RobotClock, input: &Self::Input<'_>,
+fn process(&mut self, _ctx: &CuContext, input: &Self::Input<'_>,
            output: &mut Self::Output<'_>) -> CuResult<()> {
     if let Some(update) = input.payload() {
         self.calibration.update(update);

book/src/ch07-task-traits.md

@@ -38,7 +38,7 @@ impl CuSrcTask for MySource {
         Ok(Self {})
     }
 
-    fn process(&mut self, _clock: &RobotClock, output: &mut Self::Output<'_>) -> CuResult<()> {
+    fn process(&mut self, _ctx: &CuContext, output: &mut Self::Output<'_>) -> CuResult<()> {
         output.set_payload(MyPayload { value: 42 });
         Ok(())
     }
@@ -64,7 +64,7 @@ impl CuTask for MyTask {
 
     fn process(
         &mut self,
-        _clock: &RobotClock,
+        _ctx: &CuContext,
         input: &Self::Input<'_>,
         output: &mut Self::Output<'_>,
     ) -> CuResult<()> {
@@ -91,7 +91,7 @@ impl CuSinkTask for MySink {
         Ok(Self {})
     }
 
-    fn process(&mut self, _clock: &RobotClock, input: &Self::Input<'_>) -> CuResult<()> {
+    fn process(&mut self, _ctx: &CuContext, input: &Self::Input<'_>) -> CuResult<()> {
         debug!("Sink Received message: {}", input.payload().unwrap().value);
         Ok(())
     }
@@ -109,7 +109,7 @@ use serde::{Deserialize, Serialize};
 ```
 
 - **`cu29::prelude::*`** -- Brings in everything you need from Copper: task traits,
-  `RobotClock`, `ComponentConfig`, `CuResult`, `Freezable`, `Reflect`, the `input_msg!` /
+  `CuContext`, `ComponentConfig`, `CuResult`, `Freezable`, `Reflect`, the `input_msg!` /
   `output_msg!` macros, and the `debug!` logging macro.
 - **`bincode`** and **`serde`** -- For the serialization derives on `MyPayload` (covered in
   the [Defining Messages](./ch06-messages.md) chapter).
@@ -158,7 +158,7 @@ impl CuSrcTask for MySource {
         Ok(Self {})
     }
 
-    fn process(&mut self, _clock: &RobotClock, output: &mut Self::Output<'_>) -> CuResult<()> {
+    fn process(&mut self, _ctx: &CuContext, output: &mut Self::Output<'_>) -> CuResult<()> {
         output.set_payload(MyPayload { value: 42 });
         Ok(())
     }
@@ -196,7 +196,7 @@ impl CuTask for MyTask {
 
     fn process(
         &mut self,
-        _clock: &RobotClock,
+        _ctx: &CuContext,
         input: &Self::Input<'_>,
         output: &mut Self::Output<'_>,
     ) -> CuResult<()> {
@@ -235,7 +235,7 @@ impl CuSinkTask for MySink {
         Ok(Self {})
     }
 
-    fn process(&mut self, _clock: &RobotClock, input: &Self::Input<'_>) -> CuResult<()> {
+    fn process(&mut self, _ctx: &CuContext, input: &Self::Input<'_>) -> CuResult<()> {
         debug!("Sink Received message: {}", input.payload().unwrap().value);
         Ok(())
     }

book/src/ch08-task-anatomy.md

@@ -35,7 +35,7 @@ type Input<'m> = input_msg!(SensorA, SensorB);
 In `process()`, the `input` parameter becomes a tuple that you can destructure:
 
 ```rust
-fn process(&mut self, _clock: &RobotClock, input: &Self::Input<'_>, ...) -> CuResult<()> {
+fn process(&mut self, _ctx: &CuContext, input: &Self::Input<'_>, ...) -> CuResult<()> {
     let (sensor_a_msg, sensor_b_msg) = *input;
     // Use sensor_a_msg.payload() and sensor_b_msg.payload()
     Ok(())
@@ -86,8 +86,12 @@ You can read the values in `new()`:
 ```rust
 fn new(config: Option<&ComponentConfig>, _resources: Self::Resources<'_>) -> CuResult<Self> {
     let cfg = config.ok_or("MotorDriver requires a config block")?;
-    let pin: u8 = cfg.get("pin").unwrap().clone().into();
-    let max_speed: f64 = cfg.get("max_speed").unwrap().clone().into();
+    let pin: u8 = cfg
+        .get::<u8>("pin")?
+        .ok_or_else(|| CuError::from("MotorDriver missing `pin`"))?;
+    let max_speed: f64 = cfg
+        .get::<f64>("max_speed")?
+        .ok_or_else(|| CuError::from("MotorDriver missing `max_speed`"))?;
     Ok(Self { pin, max_speed })
 }
 ```
@@ -101,14 +105,14 @@ depends on the trait:
 
 | Trait | Signature |
 |---|---|
-| `CuSrcTask` | `process(&mut self, clock, output)` |
-| `CuTask` | `process(&mut self, clock, input, output)` |
-| `CuSinkTask` | `process(&mut self, clock, input)` |
+| `CuSrcTask` | `process(&mut self, ctx, output)` |
+| `CuTask` | `process(&mut self, ctx, input, output)` |
+| `CuSinkTask` | `process(&mut self, ctx, input)` |
 
 In our simple example, the source ignores most parameters and just writes a value:
 
 ```rust
-fn process(&mut self, _clock: &RobotClock, output: &mut Self::Output<'_>) -> CuResult<()> {
+fn process(&mut self, _ctx: &CuContext, output: &mut Self::Output<'_>) -> CuResult<()> {
     output.set_payload(MyPayload { value: 42 });
     Ok(())
 }
@@ -143,32 +147,35 @@ arrive. This is a good fit for calibration bundles, static transforms, lookup ta
 other low-rate metadata that should not be rebuilt every cycle. The full producer and
 consumer pattern is covered in [Defining Messages](./ch06-messages.md#latched-state-updates).
 
-#### The clock: `&RobotClock`
+#### The context: `&CuContext`
 
-Every `process()` receives a `clock` parameter. This is Copper's **only clock** -- a
-monotonic clock that starts at zero when your program launches and ticks forward in
-nanoseconds. There is no UTC or wall-clock in Copper; tasks should never call
-`std::time::SystemTime::now()` or `std::time::Instant::now()`.
+Every lifecycle callback receives a `ctx` parameter of type `&CuContext`. It dereferences
+to Copper's monotonic `RobotClock`, so `ctx.now()` gives you the current Copper time, and
+it also carries runtime metadata such as `ctx.cl_id()`, `ctx.instance_id()`, and the
+currently executing task ID.
 
-`clock.now()` returns a `CuTime` (a `u64` of nanoseconds since startup). In our simple
-project we prefix the parameter with `_` because we don't use it. But on a real robot
-you'd use it like this:
+`ctx.now()` returns a `CuTime` (a `u64` of nanoseconds since startup). There is no UTC or
+wall-clock in Copper; tasks should never call `std::time::SystemTime::now()` or
+`std::time::Instant::now()`.
+
+In our simple project we prefix the parameter with `_` because we don't use it. But on a
+real robot you'd use it like this:
 
 **Timestamp your output** (typical for source tasks):
 
 ```rust
-fn process(&mut self, clock: &RobotClock, output: &mut Self::Output<'_>) -> CuResult<()> {
+fn process(&mut self, ctx: &CuContext, output: &mut Self::Output<'_>) -> CuResult<()> {
     output.set_payload(MyPayload { value: read_sensor() });
-    output.tov = Tov::Time(clock.now());
+    output.tov = Tov::Time(ctx.now());
     Ok(())
 }
 ```
 
 **Compute a time delta** (e.g., for a PID controller):
 
 ```rust
-fn process(&mut self, clock: &RobotClock, input: &Self::Input<'_>, output: &mut Self::Output<'_>) -> CuResult<()> {
-    let now = clock.now();
+fn process(&mut self, ctx: &CuContext, input: &Self::Input<'_>, output: &mut Self::Output<'_>) -> CuResult<()> {
+    let now = ctx.now();
     let dt = now - self.last_time;  // CuDuration in nanoseconds
     self.last_time = now;
 
@@ -182,9 +189,9 @@ fn process(&mut self, clock: &RobotClock, input: &Self::Input<'_>, output: &mut
 **Detect a timeout**:
 
 ```rust
-fn process(&mut self, clock: &RobotClock, input: &Self::Input<'_>) -> CuResult<()> {
+fn process(&mut self, ctx: &CuContext, input: &Self::Input<'_>) -> CuResult<()> {
     if input.payload().is_none() {
-        let elapsed = clock.now() - self.last_seen;
+        let elapsed = ctx.now() - self.last_seen;
         if elapsed > CuDuration::from_millis(100) {
             debug!("Sensor timeout! No data for {}ms", elapsed.as_millis());
         }
@@ -196,8 +203,8 @@ fn process(&mut self, clock: &RobotClock, input: &Self::Input<'_>) -> CuResult<(
 **Why not use the system clock?** Because Copper supports **deterministic replay**. When
 you replay a recorded run, the runtime feeds your tasks the exact same clock values from
 the original recording. If you used `std::time`, the replay would have different
-timestamps and your tasks would behave differently. With `RobotClock`, same clock + same
-inputs = same outputs, every time.
+timestamps and your tasks would behave differently. With `CuContext` (and its underlying
+`RobotClock`), same clock + same inputs = same outputs, every time.
 
 ### The golden rule of `process()`
 

book/src/ch09-task-lifecycle.md

@@ -48,13 +48,13 @@ to run your control loop on slightly stale data than to miss a deadline. Your `p
 should handle this gracefully:
 
 ```rust
-fn preprocess(&mut self, _clock: &RobotClock) -> CuResult<()> {
+fn preprocess(&mut self, _ctx: &CuContext) -> CuResult<()> {
     // Heavy work on the best-effort thread -- might be slow
     self.decoded_image = Some(decode_jpeg(&self.raw_buffer));
     Ok(())
 }
 
-fn process(&mut self, _clock: &RobotClock, input: &Self::Input<'_>,
+fn process(&mut self, _ctx: &CuContext, input: &Self::Input<'_>,
            output: &mut Self::Output<'_>) -> CuResult<()> {
     // Use whatever is ready. If preprocess was late, decoded_image
     // still holds the previous cycle's result (or None on first cycle).
@@ -110,17 +110,17 @@ impl CuTask for MyTask {
     }
 
     // Required: core logic
-    fn process(&mut self, _clock: &RobotClock, input: &Self::Input<'_>,
+    fn process(&mut self, _ctx: &CuContext, input: &Self::Input<'_>,
                output: &mut Self::Output<'_>) -> CuResult<()> {
         // your core logic
         Ok(())
     }
 
     // Optionally implement any of these:
-    // fn start(&mut self, clock: &RobotClock) -> CuResult<()> { ... }
-    // fn stop(&mut self, clock: &RobotClock) -> CuResult<()> { ... }
-    // fn preprocess(&mut self, clock: &RobotClock) -> CuResult<()> { ... }
-    // fn postprocess(&mut self, clock: &RobotClock) -> CuResult<()> { ... }
+    // fn start(&mut self, ctx: &CuContext) -> CuResult<()> { ... }
+    // fn stop(&mut self, ctx: &CuContext) -> CuResult<()> { ... }
+    // fn preprocess(&mut self, ctx: &CuContext) -> CuResult<()> { ... }
+    // fn postprocess(&mut self, ctx: &CuContext) -> CuResult<()> { ... }
 }
 ```
 

book/src/ch10-main-rs.md

@@ -1,8 +1,9 @@
 # The Remaining Files and Running
 
 We've covered `copperconfig.ron` and `tasks.rs` -- the two files you'll edit most. Now
-let's look at the three remaining files: `main.rs`, `build.rs`, and `Cargo.toml`. These
-are mostly boilerplate that you write once and rarely touch.
+let's look at `main.rs`, `build.rs`, and the relevant `Cargo.toml` bits. These are mostly
+boilerplate that you write once and rarely touch. We'll come back to `logreader.rs` in
+Chapter 13 and replay via `resim.rs` later.
 
 ## main.rs -- the entry point
 

book/src/ch11-frequency.md

@@ -13,8 +13,8 @@ Let's modify `MySource` in `tasks.rs` to print the time at each cycle. Replace t
 `process()` method:
 
 ```rust
-fn process(&mut self, clock: &RobotClock, output: &mut Self::Output<'_>) -> CuResult<()> {
-    debug!("Source at {}µs", clock.now().as_micros());
+fn process(&mut self, ctx: &CuContext, output: &mut Self::Output<'_>) -> CuResult<()> {
+    debug!("Source at {}µs", ctx.now().as_micros());
     output.set_payload(MyPayload { value: 42 });
     Ok(())
 }

book/src/ch12-monitoring.md

@@ -9,18 +9,12 @@ standard deviation, min, max, and more.
 
 ## Step 1: Add the dependency
 
-Add `cu-consolemon` to your `Cargo.toml`:
-
-```toml
-[dependencies]
-cu29 = { git = "https://github.com/copper-project/copper-rs" }
-cu-consolemon = { git = "https://github.com/copper-project/copper-rs" }
-bincode = { package = "cu-bincode", version = "2.0", default-features = false,
-            features = ["derive", "alloc"] }
-serde = { version = "1", features = ["derive"] }
-```
+Add `cu-consolemon` to your `Cargo.toml` next to your existing Copper dependencies.
+The only new dependency is `cu-consolemon`.
 
-The only new line is `cu-consolemon`.
+If your project already uses Copper through `git` or local `path` dependencies, keep that
+same source style and add `cu-consolemon` from the same Copper release. If you use
+crates.io, use the same published Copper release as your existing `cu29` dependency.
 
 ## Step 2: Enable it in copperconfig.ron
 
@@ -155,4 +149,3 @@ A scrollable view of all `debug!()` log output from your tasks -- the same messa
 see without the monitor, but captured inside the TUI. You can scroll through the history
 with `hjkl` or arrow keys. The bottom bar also shows keyboard shortcuts: `r` to reset
 latency statistics, `q` to quit.
-

book/src/ch15-workspace.md

@@ -33,6 +33,7 @@ my_workspace/
 │       └── src/
 │           ├── main.rs
 │           ├── logreader.rs
+│           ├── resim.rs
 │           ├── messages.rs
 │           └── tasks/
 │               ├── mod.rs
@@ -79,7 +80,7 @@ When you add a new application or component, you add it to the `members` list.
 ## The apps/ directory
 
 This is where your **application crates** live. Each app is a standalone binary that owns
-its own runtime configuration, log storage, and logreader.
+its own runtime configuration, log storage, logreader, and replay target.
 
 The example app (`cu_example_app`) looks very similar to the `my_project` we built in
 earlier chapters, but with two key differences.