From 69ad074a79d40b148a91add3a7893a0639dc372d Mon Sep 17 00:00:00 2001
From: Cristhian <svarogcl@gmail.com>
Date: Tue, 15 Sep 2026 06:18:38 -0300
Subject: [PATCH] document configuring the node from the dataflow

Every setting is an environment variable, which reads fine for one and badly
for six: the README's table implied the only way to set them was to export them
around `dora run`. A node takes an `env:` map in the dataflow, applied to both
the build and the run, which keeps configuration with the wiring rather than in
whatever shell happened to start it. The README now shows a populated node.

A node's `env:` wins over the environment the dataflow was started in, and a
variable it does not set still passes through. That is why the block in
dataflow.yml is present but commented out: CI passes CAPTURE_FRAMES in through
the shell, and pinning it there would silently override the runner.
---
 README.md    | 35 +++++++++++++++++++++++++++++++++++
 dataflow.yml | 10 ++++++++++
 2 files changed, 45 insertions(+)

diff --git a/README.md b/README.md
index e8c13ac..acda426 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,41 @@ compressed encoding, `width` and `height` are the image's dimensions, not the le
 |---|---|
 | `tick` | Publishes one frame. Wire to `dora/timer/millis/N`; the node stops when it closes. |
 
+## Configuring it
+
+Every setting below is an environment variable, which is convenient for one and
+awkward for several. A dataflow can carry them instead, per node, which keeps the
+configuration with the wiring it belongs to and out of whatever shell happens to start
+it:
+
+```yaml
+nodes:
+  - id: camera
+    git: ssh://git@gitea.liria.cl:5001/liria/dora-webcam.git
+    tag: v0.1.0
+    build: uv pip install .
+    path: dora-webcam
+    env:
+      CAMERA_ID: usb-Acme_Webcam
+      IMAGE_WIDTH: 1280
+      IMAGE_HEIGHT: 720
+      ENCODING: jpeg
+      JPEG_QUALITY: 85
+      FLIP: HORIZONTAL
+    inputs:
+      tick: dora/timer/millis/33
+    outputs:
+      - image
+```
+
+Values may be strings, numbers or booleans, and dora applies them to both the build and
+the run.
+
+**A node's `env:` wins over the environment the dataflow was started in.** A variable
+the node does not set still passes through, so `PREVIEW=true dora run ...` works
+alongside the block above — but a variable pinned there cannot be overridden from the
+shell, which is worth remembering before pinning something a test needs to vary.
+
 ## Environment variables
 
 | Variable | Default | Meaning |
diff --git a/dataflow.yml b/dataflow.yml
index bd947cd..4be4fac 100644
--- a/dataflow.yml
+++ b/dataflow.yml
@@ -7,6 +7,16 @@ nodes:
   - id: camera
     path: dora-webcam
     build: uv pip install .
+    # Settings belong here rather than in the environment of whatever starts the
+    # dataflow. Deliberately empty: a node's `env:` wins over the shell, and CI
+    # passes CAPTURE_FRAMES in through the shell, so pinning one here would
+    # silently override it. See the README for a populated example.
+    #
+    # env:
+    #   CAMERA_ID: usb-Acme_Webcam
+    #   IMAGE_WIDTH: 1280
+    #   IMAGE_HEIGHT: 720
+    #   ENCODING: jpeg
     inputs:
       tick: dora/timer/millis/33
     outputs: