Merge pull request #7 from SjulsonLab/dev2

adding new task framework and web UI

Author: evilrobotxoxo

.gitignore

@@ -214,10 +214,11 @@ irig_decoding/data/
 .idea
 temp/
 tmp_task_runs/
-sample_tasks/
+tmp_operator_runs/
 box_runtime/audio/local_source_wavs/
 box_runtime/audio/local_sounds/
 *.asv
+.DS_Store
 *.m~
 *.mex*
 Thumbs.db

Codex.md

@@ -92,35 +92,35 @@ Hardware/runtime support for RPi4 behavior boxes, including strict head-fixed GP
 - `BehavBox.event_timestamp(event)`
 - `interact_list` entries now reuse the same detection timestamp used for queue event creation.
 
-## Head-Fixed GPIO Mapping
-- `user_configurable`: 4
-- `treadmill_1_input`: 13
-- `treadmill_2_input`: 16
-- `reward_left`: 19
-- `reward_right`: 20
-- `reward_center`: 21
-- `pump4`: 7
-- `airpuff`: 8
-- `vacuum`: 25
-- `cue_led_1`: 22
-- `cue_led_2`: 18
-- `cue_led_3`: 17
-- `cue_led_4`: 14
-- `lick_1`: 26
-- `lick_2`: 27
-- `lick_3`: 15
-- Reserved / unused for BehavBox: 5, 6, 11, 12
-- Legacy sound-board GPIO pins remain present on some hardware drawings, but the
-  supported runtime no longer owns them. Sound playback now uses the direct USB
-  audio subsystem under `box_runtime/audio/`.
-- Supported user-expansion path:
-- `BehavBox.configure_user_output(label=...)` reserves GPIO4 as a user-controlled digital output.
-- `BehavBox.configure_user_input(label=..., pull_up=..., active_state=...)` reserves GPIO4 as a user-controlled digital input.
-- GPIO4 may only be configured once per `BehavBox` instance.
+## Profile-Aware GPIO Mapping
+- Active GPIO mapping is loaded from `unified_GPIO_pin_arrangement_v4.csv`, not a hard-coded dict.
+- Canonical profile key: `box_profile`
+  - fallback: `input_profile` if `box_profile` is absent
+- Dedicated trigger lines:
+  - `trigger_in`: GPIO23
+  - `trigger_out`: GPIO24
+- Generic user-configurable line:
+  - GPIO4, claimed later as input or output if requested
+- Head-fixed inputs:
+  - `ir_lick_left/right/center`: GPIO5/6/12
+  - `lick_left/right/center`: GPIO26/27/15
+  - `treadmill_1/2`: GPIO13/16
+- Freely-moving inputs:
+  - `poke_left/right/center`: GPIO5/6/12
+  - `poke_extra1/2`: GPIO13/16
+- Shared outputs:
+  - `reward_left/right/center`: GPIO19/20/21
+  - `reward_4`: GPIO7
+  - `vacuum`: GPIO25
+  - `cue_led_1..6`: GPIO22/18/17/14/10/11
+  - `trigger_out`: GPIO24
+- Profile-specific GPIO8:
+  - `head_fixed`: `airpuff`
+  - `freely_moving`: `reward_5`
+- User-facing manual-control surfaces show canonical names plus board aliases (for example `reward_left (pump1)`).
 - Reserved-pin guard:
-- `box_runtime/behavior/gpio_backend.py` raises `ReservedPinError` if active runtime code tries to claim GPIO11 through the supported GPIO device classes.
-- GPIO11 is reserved because it is the pin used by the IRIG timecode sender output.
-- This protects IRIG timecode sender use of GPIO11 from future BehavBox edits, but archived `old/` scripts are not covered unless they import through `gpio_backend.py`.
+  - `box_runtime/behavior/gpio_backend.py` raises `ReservedPinError` for GPIO9.
+  - GPIO9 is reserved for the IRIG sender output and should not be claimed by active BehavBox runtime code.
 
 ## Runtime Behavior (Pi vs Non-Pi)
 - Raspberry Pi: real `gpiozero` devices.

README.md

@@ -4,11 +4,11 @@ This repository contains only the hardware and low-level support components
 from the original `RPi4_behavior_boxes` codebase.
 
 Included directories:
-- `essential/` (device interfaces, camera, treadmill, pump, acquisition)
+- `box_runtime/` (active behavior, input, output, audio, mock-hardware, and camera runtime services)
 - `debug/` (hardware test/debug scripts)
 - `environment/` (environment specification files)
-- `video_acquisition/` (active HTTP camera service plus archived legacy camera scripts)
-- `HQ_camera/` (HQ camera support scripts from `matt-behavior`)
+- `docs/` (design notes and Sphinx docs)
+- `sample_tasks/` (reference task runner and example tasks)
 
 Excluded from this split:
 - `task_protocol/` (task-specific experiment logic)
@@ -31,8 +31,12 @@ to support independent versioning of hardware code and task code.
 
 ## Head-Fixed GPIO + Mock UI
 
-- BehavBox now uses a strict head-fixed GPIO arrangement hard-coded in:
-  `essential/behavbox.py` (`HEAD_FIXED_GPIO`).
+- BehavBox now uses a profile-aware GPIO manifest loaded from
+  `unified_GPIO_pin_arrangement_v4.csv`.
+- Canonical runtime code uses semantic names such as `reward_left`,
+  `trigger_in`, and `cue_led_5`.
+- User-facing mock/web surfaces display semantic names plus board aliases such
+  as `reward_left (pump1)` or `trigger_out (DIO2)`.
 - Hardware callbacks now enqueue structured `BehaviorEvent` objects with
   detection-time wall-clock timestamps (`name`, `timestamp`) instead of plain
   event-name strings.

box_runtime/audio/runtime.py

@@ -4,10 +4,11 @@
 
 from dataclasses import dataclass
 import logging
+import os
 from pathlib import Path
 import threading
 import time
-from typing import Protocol
+from typing import Callable, Optional, Protocol
 
 import numpy as np
 
@@ -83,6 +84,51 @@ def close(self) -> None:
         return None
 
 
+class RecordingPlaybackBackend:
+    """Mock playback backend that records submitted stereo buffers.
+
+    Args:
+        sample_rate_hz: Playback sampling rate in hertz.
+        chunk_frames: Number of stereo frames consumed per worker iteration.
+        chunk_sleep_s: Optional per-chunk sleep used to emulate slower devices.
+    """
+
+    def __init__(self, sample_rate_hz: int, chunk_frames: int = 256, chunk_sleep_s: float = 0.0):
+        self.sample_rate_hz = int(sample_rate_hz)
+        self.chunk_frames = int(chunk_frames)
+        self.chunk_sleep_s = float(chunk_sleep_s)
+        self.play_calls: list[np.ndarray] = []
+
+    def write_frames(self, frames: np.ndarray, stop_requested) -> int:
+        """Record the played stereo frames.
+
+        Args:
+            frames: Stereo ``int16`` array of shape ``(num_frames, 2)``.
+            stop_requested: Zero-argument callable returning whether playback
+                should stop early.
+
+        Returns:
+            Number of stereo frames consumed.
+        """
+
+        consumed = 0
+        chunks: list[np.ndarray] = []
+        total_frames = int(frames.shape[0])
+        while consumed < total_frames:
+            if stop_requested():
+                break
+            stop = min(consumed + self.chunk_frames, total_frames)
+            chunks.append(frames[consumed:stop].copy())
+            consumed = stop
+            if self.chunk_sleep_s > 0:
+                time.sleep(self.chunk_sleep_s)
+        self.play_calls.append(np.vstack(chunks) if chunks else np.empty((0, 2), dtype=np.int16))
+        return consumed
+
+    def close(self) -> None:
+        return None
+
+
 class PyAlsaAudioPlaybackBackend:
     """Persistent ALSA playback backend for stereo PCM audio."""
 
@@ -138,6 +184,9 @@ class SoundRuntime:
         ramp_duration_s: Ramp duration in seconds applied to all cue edges.
         reference_rms: Canonical RMS amplitude used for imports and built-in
             white noise generation.
+        state_callback: Optional callback receiving JSON-serializable runtime
+            state updates with keys such as ``active`` and
+            ``current_cue_name``.
     """
 
     def __init__(
@@ -149,6 +198,7 @@ def __init__(
         period_size_frames: int = 256,
         ramp_duration_s: float = 0.002,
         reference_rms: float = DEFAULT_REFERENCE_RMS,
+        state_callback: Optional[Callable[[dict[str, object]], None]] = None,
     ):
         self.paths = paths
         self.paths.ensure_directories()
@@ -163,6 +213,7 @@ def __init__(
         self.device_name = str(device_name)
         self.period_size_frames = int(period_size_frames)
         self.backend = backend or self._build_backend()
+        self.state_callback = state_callback
         self.loaded_sounds: dict[str, LoadedSound] = {}
         self._condition = threading.Condition()
         self._pending_request: tuple[int, PlaybackRequest] | None = None
@@ -172,6 +223,7 @@ def __init__(
         self._shutdown = False
         self._worker = threading.Thread(target=self._worker_main, name="behavbox-sound", daemon=True)
         self._worker.start()
+        self._emit_state(active=False, current_cue_name=None, last_cue_name=None)
 
     def import_wav_file(
         self,
@@ -221,6 +273,33 @@ def clear_sounds(self) -> None:
 
         self.loaded_sounds.clear()
 
+    def register_white_noise(self, name: str, duration_s: float, seed: int = 0) -> LoadedSound:
+        """Register a generated white-noise cue directly in memory.
+
+        Args:
+            name: Cue identifier.
+            duration_s: Cue duration in seconds.
+            seed: Deterministic random seed for waveform generation.
+
+        Returns:
+            LoadedSound prepared for playback.
+        """
+
+        waveform = generate_white_noise(
+            duration_s=float(duration_s),
+            sample_rate_hz=self.sample_rate_hz,
+            rms=self.reference_rms,
+            seed=int(seed),
+        )
+        loaded = build_loaded_sound(
+            name=Path(name).stem,
+            waveform_mono=waveform,
+            sample_rate_hz=self.sample_rate_hz,
+            ramp_duration_s=self.ramp_duration_s,
+        )
+        self.loaded_sounds[loaded.name] = loaded
+        return loaded
+
     def play_sound(
         self,
         name: str,
@@ -254,6 +333,7 @@ def play_sound(
             self._pending_request = (next_token, request)
             self._busy = True
             self._condition.notify_all()
+        self._emit_state(active=True, current_cue_name=cue_key, last_cue_name=cue_key)
 
     def stop_sound(self) -> None:
         """Interrupt the currently playing cue, if any."""
@@ -262,6 +342,7 @@ def stop_sound(self) -> None:
             self._stop_token = max(self._stop_token, self._active_token + 1)
             self._active_token = max(self._active_token, self._stop_token)
             self._condition.notify_all()
+        self._emit_state(active=False, current_cue_name=None)
 
     def start_sound_calibration(self, side: str = "both", gain_db: float = 0.0) -> None:
         """Start long-running white-noise playback for hardware calibration."""
@@ -368,8 +449,15 @@ def close(self) -> None:
             self._condition.notify_all()
         self._worker.join(timeout=2.0)
         self.backend.close()
+        self._emit_state(active=False, current_cue_name=None)
 
     def _build_backend(self) -> PlaybackBackend:
+        if str(os.environ.get("BEHAVBOX_MOCK_AUDIO", "0")).strip().lower() in {"1", "true", "yes", "on"}:
+            LOGGER.info("Using recording audio backend because BEHAVBOX_MOCK_AUDIO is enabled.")
+            return RecordingPlaybackBackend(
+                sample_rate_hz=self.sample_rate_hz,
+                chunk_sleep_s=256.0 / float(self.sample_rate_hz),
+            )
         if alsaaudio is None:  # pragma: no cover - exercised on Raspberry Pi hardware
             LOGGER.warning("pyalsaaudio is unavailable; using null audio backend.")
             return NullPlaybackBackend(sample_rate_hz=self.sample_rate_hz)
@@ -402,6 +490,11 @@ def _worker_main(self) -> None:
                     if self._pending_request is None:
                         self._busy = False
                         self._condition.notify_all()
+                self._emit_state(
+                    active=False,
+                    current_cue_name=None,
+                    last_cue_name=request.name,
+                )
 
     def _interrupt_requested(self, token: int) -> bool:
         with self._condition:
@@ -425,3 +518,14 @@ def _log_clipping_if_needed(self, request: PlaybackRequest) -> None:
             clipped_percent,
             overshoot_db,
         )
+
+    def _emit_state(self, **payload: object) -> None:
+        """Forward one audio runtime-state update to the optional observer.
+
+        Args:
+            payload: JSON-serializable audio runtime-state fields.
+        """
+
+        if self.state_callback is None:
+            return
+        self.state_callback(dict(payload))