Running a composter in the study

Commands are for PowerShell: the prompt starts with PS. If it does not (Command Prompt), type powershell and press Enter first. Run them from the RND_AI_DynamicAlgo folder unless a step says otherwise.

1. i

   Get the code from GitHub once per laptop

   Can skipif this laptop already has the RND_AI_DynamicAlgo folder with a hidden .git folder inside.

   The repository is private: sign in with a GitHub account that is a member of virgohomeio. Use one of the two ways.

   With Git in PowerShell. Install Git once, then close PowerShell and open a new one:

   winget install --id Git.Git -e --source winget

   Copy

   Go to the folder that should hold the project (for example C:\Vcycene) and copy it down. A GitHub sign-in window opens the first time.

   git clone https://github.com/virgohomeio/RND_AI_DynamicAlgo.git
   cd RND_AI_DynamicAlgo

   Copy

   With GitHub Desktop (no commands): install it from desktop.github.com, sign in, then File → Clone repository → URL → https://github.com/virgohomeio/RND_AI_DynamicAlgo → Clone.

   Getting updates later: git pull in PowerShell, or Fetch origin → Pull origin in GitHub Desktop. If neither works, download the ZIP from the repository page (Code → Download ZIP), extract it, and copy its RL and docs folders over this laptop's, choosing Replace. Your machine_<NUM>.yaml, the unlock and the keys are not in the download, so they stay.

2. ii

   The settings file: what it must say

   Each machine has its own settings file on each laptop: RL\harness\config\machine_<NUM>.yaml, named after the last three digits of its serial, so machine_312.yaml for LL01-00000000312 (step 4 makes it). It never goes to GitHub, so a pull never brings these settings: check them by hand on every laptop. Open the file in Notepad and make these lines read as below. Lines under transport: and firmware: keep their two spaces in front; every other line has none. If a line is missing, add it at the end of the file.

   serial: <SERIAL>
   transport:
     uart: {port: <PORT>, baud: 115200, timeout_s: 0.5}
   gas_saturation_ohm: 102400000
   ptc_guard_c: {off_at: 58, on_below: 51, alarm_at: 75}
   firmware:
     stop_process_on_start: false
     start_process_on_exit: false
   stage: 1
   policy: {kind: random}
   scores_drive_decisions: false
   firmware_modes_only: true

   Copy

   Replace <SERIAL> with the machine's serial (step 3) and <PORT> with this laptop's port for it (step 2).

   Line	What it is	Changes when
   serial:	the machine this laptop drives (step 3 reads it)	new machine
   port: inside uart:	where the USB cable shows up on this laptop (step 2 finds it)	new laptop, or a new machine or cable
   stop_process_on_start, start_process_on_exit	false: these machines take commands directly and refuse the hand-over	never, for now
   firmware_modes_only	true: decisions use only A1 light and A3 heavy	only when the study says so
   scores_drive_decisions	false: scores are recorded, not used to steer	only when the study says so
   gas_saturation_ohm, ptc_guard_c, stage, policy	the study's current values	only when the study says so

   Every laptop driving the study must have the same values, apart from serial and port, so the study runs the same whichever laptop is plugged in.

3. iii

   What to do for a new laptop, and for a new machine

   	Do
   New laptop	i (get the code), step 1 (packages), step 2 (port), step 4 with the lines in ii, step 5 (unlock), step 6 (keys), step 7 (tests), then step 8 (machine check)
   New machine on a laptop already set up	step 2 (its port), step 3 (its serial), copy an existing machine_<NUM>.yaml to the new machine's name (step 4), change its serial and port, then step 8 (machine check)
   Two or more machines on one laptop	Each machine runs in its own windows with its own file: one harness and one safety guard per machine (steps 10 and 11 with that machine's machine_<NUM>.yaml). The commands are the same for every machine; only the file name changes. Each harness's small local page takes the next free port by itself (8443, then 8444, …)
   Same machine, other laptop	stop the harness and the safety guard on the first laptop, move the USB cable, then step 8 on the second. The run picks up where it was

   A machine appears on Compost Control (Insights, Quick score, Full check) by itself once it has sent any data, on any device.

1. 1

   Install the Python packages once per laptop

   Can skipif this laptop already has them installed.

   pip install -r requirements-bench.txt
   pip install -r RL\requirements.txt

   Copy

   Python 3.11 or newer.

2. 2

   Find the machine's port

   Can skipif you already know the port from an earlier run on this laptop.

   Run this once with the machine unplugged and once with it plugged in by USB. The port that appears the second time is the machine, for example COM5.

   python -m serial.tools.list_ports -v

   Copy

   Only one program can use the port at a time, so close any other script first.

3. 3

   Read the sensors for two minutes

   Can skipif this machine was checked before and you already have its serial.

   python read_sensors.py --port <PORT> --seconds 120 --no-upload

   Copy

   • The first line shows the machine's serial number. You need it in step 4.
   • This only reads, and --no-upload keeps the test out of the study data.
   • Temperatures and humidity should look sensible.
4. 4

   Create this laptop's settings file once per laptop

   Can skipif RL\harness\config\machine_<NUM>.yaml already exists on this laptop for this machine.

   Each machine gets its own file on this laptop, named after the last three digits of its serial. It is never shared through GitHub, because it holds this laptop's port. Start from the shared template, or copy another machine's file and change its serial and port:

   Copy-Item RL\harness\config\machine.example.yaml RL\harness\config\machine_<NUM>.yaml

   Copy

   Open RL\harness\config\machine_<NUM>.yaml in Notepad and set the lines shown in ii at the top of this guide: serial from step 3, port from step 2, and the study values exactly as shown.

   • Leave seed and decision_times_local as they are, so a run can move between laptops without breaking its cycle.
   • The harness checks the serial against the machine at start and refuses to run if they differ.
5. 5

   Allow this laptop to control a machine once per laptop

   Can skipif this laptop is already allowed, or if it will only log (read-only runs).

   As it comes from GitHub, the harness only reads a machine and refuses to drive it. Each laptop that will run the study switches this on for itself. Open RL\harness\config\actions.yaml and change the line

   placeholders_confirmed: false

   Copy

   to

   placeholders_confirmed: true

   Copy

   • Never commit or push this change. The copy on GitHub stays locked on purpose; each laptop unlocks its own.
   • If you see "placeholders are not confirmed" when starting a run, this step was skipped.
6. 6

   Create this laptop's own keys once per laptop

   Can skipif RL\harness\secrets\ already has api_token, harness_cert.pem and harness_key.pem.

   The harness serves a small page on the laptop and needs three key files for it. Do not copy them from another laptop: each laptop makes its own. Without them, the harness will not start.

   Run in RND_AI_DynamicAlgo\RL

   cd RL
   python -m harness.api.certs --out harness\secrets

   Copy

   File in RL\harness\secrets	Needed?
   api_token, harness_cert.pem, harness_key.pem	Yes: made by the command above, on this laptop
   supabase_service_key	No. It stays only on the first laptop. Without it, the harness uses the shared key from the repository, which can add and read rows: all a run needs

   The folder is never sent to GitHub: the command puts a "keep out of git" file inside it.

7. 7

   Run the tests

   Run in RND_AI_DynamicAlgo\RL

   python -m pytest harness\tests -q

   Copy

   Every test should pass. If any fails: stop and save the output.

1. 8

   Check the machine

   Fit both chambers, empty, and close both lids. Then run the check. It confirms every sensor answers, every actuator responds under laptop control, and the data can be saved and uploaded.

   Run in RND_AI_DynamicAlgo\RL

   python -m harness.tools.machine_check --config harness\config\machine_<NUM>.yaml

   Copy

   • The blower, intake fan, each pad heater, the PTC and each mixer run for a few seconds each. Stay beside the machine; the mixers turn.
   • Every line says PASS, WARN, FAIL or SKIP. It ends with READY or NOT READY.
   • Fix every FAIL before loading. WARN lines are worth a look but don't block a run.
   • The actuators are skipped while a lid is open.
   • A report is saved next to the machine's study files.

   FAIL line	What to do
   lid: front lid open	Close the lid, then run the check again.
   chamber air (BME) answers with zeros	The chamber's air sensor is missing or not connected.
   firmware hands over: STOP_PROCESS refused	The machine's firmware does not accept laptop control. It needs the PC-control firmware build.
   mixer: no motor current	The mixer did not turn. Check its connector and the chamber seating.
   Supabase not reachable	Check the internet connection. A run still saves locally and uploads later.

2. 9

   Fill both chambers and close both lids again

   Only the front lid has a switch. The mixers never run while it reads open.

3. 10

   Start a read-only run for about 5 minutes

   Run in RND_AI_DynamicAlgo\RL

   python -m harness.run --config harness\config\machine_<NUM>.yaml --read-only --verbose --hours 0.08

   Copy

   • The harness reads and logs, and uploads the readings, but makes no decisions and sends nothing to the machine. The firmware keeps running it.
   • Open Insights and pick your machine, or add ?machine=<SERIAL> to the address. New readings should appear within a few minutes.
   • Decisions only appear at the 4-hourly times. You don't need to wait for one.
   • --verbose prints every reading to the screen; without it the terminal only shows events and looks idle while it logs.
   • --hours 0.08 stops it by itself after about 5 minutes. To stop earlier, press Ctrl+C once and wait.
4. 11

   Start the real run

   Run in RND_AI_DynamicAlgo\RL

   python -m harness.run --config harness\config\machine_<NUM>.yaml --verbose

   Copy

   For a run you will leave, also start the safety guard in a second terminal. It is a separate safety process: if the harness stops answering, it switches everything off and hands the machine back to its firmware. It reports to Supabase, so Insights (Health tab) shows from any device whether it is on, and when it stepped in.

   python -m harness.run --config harness\config\machine_<NUM>.yaml --watchdog

   Copy

   • The harness pauses the firmware's program and runs the blower, heaters and mixers itself.
   • It picks one of A0 to A4 at random for each chamber at each 4-hourly decision.
   • Every row goes to the local CSV files and to Supabase.

1. 12

   Score each chamber at least twice a day

   For example once in the morning and once in the evening. Use whichever way suits the moment. All three save to the same place and count the same.

   Way	Use it for	What it records
   Quick score	The routine daily check	Squeeze, smell, or why it was missed, and a feed with an optional note
   Full check	A detailed check, or anything beyond a feed	Score with a photo, feed, water added, unload, service done, plus the machine's status, recent events and latest scores. The Entries tab fixes or deletes a wrong entry; every add, edit and delete is kept in Supabase (entry_changes)
   Terminal questions (score.py)	When you are at the laptop and don't want to open a browser	Asks you questions in the PowerShell window, chamber L then R: scored or missed, squeeze 1 to 6, smell level 0 to 2, and if it smells, what kind and where. No photo and no feed. If the internet is down it keeps the score and sends it the next time you run it.

   python score.py --observer <YOUR NAME>

   Copy

   Squeeze	What you see	Grade
   1	Crumbles, dry	−1
   2	Holds briefly, then crumbles	−1
   3	Holds its shape, no water	+1
   4	A few drops	+1
   5	Steady drips	+1
   6	Water runs, slurry	−2
   any, sour smell in the material	Gone wrong	−2

2. 13

   Check progress

   On the Progress tab of Insights: decisions and scores so far for each chamber, against the current stage targets.

Differences from the firmware: the PTC switches off at 58 °C (back on below 51, as in BUILD_PLAN) instead of 70, because it overshoots by about 12 °C and should peak near the firmware's 70 °C; heavy's mix phases are 24 s / 12 s where the firmware source uses 12 s / 6 s.

1. a

   Open the front lid

   The mixers stop at once and do not start while the lid is open. The blower and heaters keep their current setting.

2. b

   Check and close

   Do the squeeze test and smell, then close the lid. Mixing resumes on its own. Each opening is logged as a lid event.

3. c

   Enter the score

   On the Quick score or Full check page. The run picks it up from Supabase.

Only one laptop can drive a machine at a time. Stop the old one before starting the new one.

1. 14

   Train

   Run in RND_AI_DynamicAlgo\RL

   python -m Machine_Learning validate --since <STUDY START DATE>
   python -m Machine_Learning train --since <STUDY START DATE> --out runs\r1

   Copy

   Training reads everything straight from Supabase, from every laptop and every web page, so no files need copying. --since leaves out the bench tests from before the study; add --serial to train on one machine. It writes runs\r1\policy_<version>.json only if a learned policy beats the firmware's own modes. If no file appears, keep collecting and train again later.

2. 15

   Switch the machine to the learned policy

   In RL\harness\config\machine_<NUM>.yaml, replace the policy: line with:

   policy: {kind: loaded, path: runs/r1/policy_<version>.json, epsilon: 0.1}

   Copy

   It applies at the next decision. One decision in ten stays random so the data keeps growing.

Run in RND_AI_DynamicAlgo, while the harness is running. Change chamber (L or R) and profile each time.

$t = (Get-Content RL\harness\secrets\api_token -Raw).Trim()
Invoke-RestMethod -Method Post -Uri https://localhost:8443/intervals -SkipCertificateCheck `
  -Headers @{Authorization = "Bearer $t"} -ContentType "application/json" `
  -Body '{"kind":"feed_week","chamber":"L","profile":"heavy","stage":1}'

This command has not been tried on a machine yet. If it answers with an error, keep the message.