Merge branch 'main' into docs-page

Author: imckee-dev

.github/workflows/ci.yml

@@ -6,25 +6,63 @@ on:
   push:
     branches: [ "main" ]
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
-  test:
+  backend-tests:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
       - name: Install UV
         uses: astral-sh/setup-uv@v4
         with:
           version: "latest"
-      
-      - name: Set up Python
-        run: uv python install 3.12
-      
+
       - name: Install dependencies
         working-directory: ./svc
-        run: uv sync
+        run: uv sync --frozen
 
       - name: Run tests
         working-directory: ./svc
-        run: uv run pytest tests/ -v
+        run: uv run pytest tests/ -v
+
+  frontend-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install frontend dependencies
+        working-directory: ./web
+        run: npm ci
+
+      - name: Run frontend tests
+        working-directory: ./web
+        run: npm run test
+
+      - name: Run frontend typecheck
+        working-directory: ./web
+        run: npm run typecheck
+
+      - name: Build frontend
+        working-directory: ./web
+        run: npm run build

.github/workflows/docker-builds.yml

@@ -0,0 +1,30 @@
+name: docker-builds
+
+on:
+  pull_request:
+    branches: [ "main" ]
+  push:
+    branches: [ "main" ]
+
+concurrency:
+  group: docker-builds-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  docker-builds:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate compose file
+        run: docker compose config --quiet
+
+      - name: Build combined app image
+        run: docker build --tag glazing-control-app:${{ github.sha }} .
+
+      - name: Build compose services
+        run: docker compose build

.gitignore

@@ -224,17 +224,29 @@ docs/TintSpecificAPIPages.pdf
 web/node_modules/
 web/dist/
 
+# Service runtime/state data
 svc/data/audit.json
+svc/data/audit.db
+svc/data/*.db-journal
+svc/data/*.db-wal
+svc/data/*.db-shm
 svc/data/panels.json
 svc/data/panels_state.json
 svc/data/panels_config.json
-#svc/svc/data/window_mapping.json
-# Note: panels_config.json is tracked (structural data)
-# panels_state.json is ignored (runtime state)
+svc/data/routines/
 
 svc/data/audit.db
 # audit.db is a SQLite database for the audit log, changes on run time, so ignore it for now
 
-#just for sim output and routines to not be published
+#just for routines to not be published
 svc/data/routines/
+
+# JETI simulator output (configured as either file or directory)
 svc/data/jeti_sim_output
+svc/data/jeti_sim_output/
+
+# Vendor manuals, extracted text, and ad hoc sensor docs used for local AI context
+/docs/SensorDocs/
+
+# Local temporary research repo / scratch workspace
+/.tmp_luox/

DEV-SETUP.md

@@ -174,7 +174,7 @@ You should see the control interface
 # Use the app
 
 1. The header shows service status  
-2. Pick a group set a level press `Set group`  
+2. Pick a group set a level press `Tint Group`  
 3. Move a slider on any panel and press `Apply`  
 4. Press `Refresh` in the header to reload state
 

OVERVIEW.md

@@ -218,7 +218,7 @@ React + Vite front-end with an HMI-style control screen.
   - Stays a fixed max size in the middle of the screen  
   - Tabs styled to match the Manage side panel tabs:  
     - **Audit log** – table of command history  
-    - **Sensor log** – placeholder for future sensor telemetry  
+    - **Sensor log** – live sensor telemetry with filtering and CSV export
   - Props:  
     - `isOpen` / `onClose`  
     - `auditLogs`, `loading`, `error`  

README.md

@@ -1,58 +1,73 @@
-# Electrochromic Glazing Control System for Trailer Lab
+<div align="center">
+  <h1>Glazing Control App</h1>
+  <p><strong>A local-first control and scheduling system for the OSU Daylighting Innovation and Analysis Lab (DIAL) trailer.</strong></p>
+</div>
 
-A local first control and scheduling system for 18 facade electrochromic panels and 2 skylights in the OSU Radiant Lab trailer. Goals include safe manual control, study friendly scheduling, live status, and reliable operation on a constrained trailer network.
+![Dashboard Mockup](docs/images/dashboard.png)
+*A sleek interface for visualizing and controlling electrochromic panels and skylights.*
 
-## Working Agreements
+## Overview
 
-- Feature branches use `feature/<short-name>`
-- PR required with at least one reviewer
-- CI must be green before merge
-- Respond to PR reviews within 24 hours
+The **Glazing Control App** is the custom software backbone for the **[Daylighting Innovation and Analysis Lab (DIAL)](https://www.clotildepierson.com/facilities/dial)** at Oregon State University. DIAL is an off-the-grid mobile university research facility designed to study the impact of daylighting on human health and productivity.
 
-## Project Board
+This app provides researchers and facility managers with a local-first system to intuitively manage, schedule, and monitor the facility's Halio electrochromic glazing.
 
-We use a board with columns Backlog → Ready → In Progress → Review → Done.
+**The Problem:** Architectural researchers in DIAL need a reliable, study-friendly way to control two symmetrical test rooms (each with 9 windows and 1 skylight) without relying on external internet connections, especially when the mobile lab is deployed in remote or off-grid locations.
 
-## Communication
+**The Solution:** By combining live status monitoring with an automated scheduling engine, the local software system provides precise environmental control.
 
-Primary: Discord private server channel Team 76  
-Secondary: email to partner or instructor
+## Key Features
 
-## Getting Started
-An overview of the file structure:
-- `docs/` for design notes and meeting minutes
-- `sim/` for an API simulator used off site
-- `web/` for the researcher UI (Contains a README specific  to the web interface)
-- `svc/` for the control service and queue (Contains a README specific to the backend service)
+- **Local-First Reliability:** Operates entirely on the local trailer network, provides responsiveness without depending on external internet access.
+- **Smart Scheduling Engine:** Create study-friendly, automated routines that adjust pane tinting based on time of day, minimizing manual intervention during research experiments.
+- **Live System Status:** Get real-time monitoring and visualization of all 18 Halio facade panels and 2 skylights from a single, unified dashboard.
+- **Sensor Integration Ready:** Built to analyze and manage DIAL's advanced setup of indoor and rooftop environmental sensors (including JETI spectroradiometers and EKO pyranometers).
+- **Safe Manual Override:** The safety-first manual override protocols allow the researchers to take direct control of individual panels.
 
-## Watch for errors
-Run the watcher from `root`, `svc`, or `web`:
+![Sensor Integration](docs/images/sensors.png)
+*DIAL's advanced sensor suite provides real-time environmental data to the control system.*
 
-```bash
-npm run watch
-```
+## How to Try It
 
-Defaults by folder:
-- root: backend + frontend (`both`)
-- svc: backend only
-- web: frontend only
+To run the local control service and researcher UI on your machine:
 
-Override the target in any folder:
+**Prerequisites:**
+- [Node.js](https://nodejs.org/) (v18+)
+- [Docker](https://www.docker.com/) (for full stack environment, optional)
 
-```bash
-npm run watch -- backend
-npm run watch -- frontend
-npm run watch -- both
-```
+**Getting Started:**
 
-## Acknowledgment
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/OSU-Radiant-Lab/GlazingControlApp.git
+   cd GlazingControlApp
+   ```
 
-- Aidan Lusk  <luskai@oregonstate.edu>  
-- Carlos Vasquez  <vasqueca@oregonstate.edu>  
-- Ian McKee  <mckeei@oregonstate.edu>  
-- Tyler Vincent  <vincenty@oregonstate.edu>
-- Alexander Ulbrich  <alexander.ulbrich@oregonstate.edu>
+2. **Start the development servers:**
+   Run the watcher from the root directory to spin up both the frontend UI and the backend control service:
+   ```bash
+   npm run watch -- both
+   ```
+   *(To run separately, use `npm run watch -- frontend` or `npm run watch -- backend` on each).*
 
-## License
+3. **Access the Application:**
+   Open your browser and navigate to `http://localhost:3000` (or the port specified in your console output) to view the researcher UI.
 
-GPL 3.0 License. See LICENSE.
+*Note: For real sensor deployment and site-specific facility notes, please refer to our [Setup Documentation](docs/real_sensor_setup.md).*
+
+## The Team
+
+This project was built by Team 76 for the OSU Radiant Lab. 
+
+- **Aidan Lusk** - [luskai@oregonstate.edu](mailto:luskai@oregonstate.edu)
+- **Carlos Vasquez** - [vasqueca@oregonstate.edu](mailto:vasqueca@oregonstate.edu)
+- **Ian McKee** - [mckeei@oregonstate.edu](mailto:mckeei@oregonstate.edu)
+- **Tyler Vincent** - [vincenty@oregonstate.edu](mailto:vincenty@oregonstate.edu)
+
+**Feedback & Contributions:**
+Please open an issue on GitHub or reach out to the team directly via email. For internal team communication, refer to Discord channel Team 76.
+
+---
+<div align="center">
+  <p>Licensed under the <a href="LICENSE">GPL 3.0 License</a>.</p>
+</div>

docker-compose.yml

@@ -0,0 +1,33 @@
+version: '3.8'
+
+services:
+  svc:
+    build:
+      context: ./svc
+      dockerfile: Dockerfile
+    container_name: glazing-svc
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./svc/data:/app/data
+    environment:
+      - SVC_HOST=0.0.0.0
+      - SVC_PORT=8000
+      - UVICORN_RELOAD=false
+    restart: unless-stopped
+
+  web:
+    build:
+      context: ./web
+      dockerfile: Dockerfile
+      args:
+        # Ok since we are only running locally, we can just use localhost
+        - VITE_API_BASE=http://localhost:8000
+    container_name: glazing-web
+    ports:
+      - "80:80"
+    depends_on:
+      - svc
+    restart: unless-stopped
+
+

docs/images/dashboard.png

@@ -0,0 +1,83 @@
+# On-Site Sensor Checklist
+
+Use this at the trailer/lab PC after the hardware is physically installed.
+
+## Connection Order
+
+1. Connect each `T-10A` head chain to its T-10A body.
+2. If a T-10A body has multiple heads, connect external power to that setup.
+3. Connect each `T-10A` body to the PC by USB.
+4. Connect each JETI device to the PC by USB.
+5. If the JETI path will use file mode, confirm the PC software is configured to write a live `.cap` file or folder.
+6. If the JETI path will use direct serial mode, confirm the JETI USB driver is installed and a COM port appears in Windows.
+7. Connect the EKO `MS-90` and optional `MS-80S` to the `C-BOX`.
+8. Connect `C-BOX` output power and RS-485 wiring.
+9. Connect the USB-to-RS485 adapter from the `C-BOX` output side to the PC.
+
+## Windows Checks
+
+1. Open Device Manager.
+2. Record the COM port for each `T-10A` body.
+3. Record the COM port for each JETI device that will use direct serial mode.
+4. Record the COM port for the USB-RS485 adapter used by the `C-BOX`.
+5. If a JETI device is missing, install the JETI USB driver and reconnect it.
+
+## Update `svc/data/sensors_config.json`
+
+1. Set `t10a[].port` to the actual T-10A COM port.
+2. Set `t10a[].heads[].head_no` to the actual physical T-10A adaptor/head ID.
+3. Set `jeti_spectraval[].transport` to either `file` or `serial_scpi`.
+4. If JETI uses file mode, set `jeti_spectraval[].output_path` to the actual live `.cap` file or folder.
+5. If JETI uses serial mode, set `jeti_spectraval[].port` to the JETI COM port.
+6. If JETI uses serial mode, set `jeti_spectraval[].baudrate`:
+   - `921600` for `spectraval 1511`
+   - `115200` for `specbos 1211-2`
+7. Set `eko_ms90_plus[].port` to the COM port of the USB-RS485 adapter.
+
+## Start The Backend
+
+```powershell
+cd svc
+$env:SVC_MODE = "real"
+uv run python main.py
+```
+
+Use `SENSORS_CONFIG_FILE` only if you are not using the default `svc/data/sensors_config.json`.
+
+## Acceptance Checks
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:8000/sensors
+Invoke-RestMethod http://127.0.0.1:8000/metrics/latest
+```
+
+Verify:
+
+- T-10A sensors report `lux`
+- JETI sensors report `lux` plus color/spectral metrics
+- EKO reports `ghi_w_m2`, `dni_w_m2`, `dhi_w_m2`, and sun position data
+
+Then open the HMI and confirm:
+
+- live sensor cards are populated
+- live graphs update
+- `Logs -> Sensor log` is filling with new rows
+- sensor CSV export works
+
+For the full step-by-step connection instructions for each sensor and each supported method, use [`docs/real_sensor_setup.md`](./real_sensor_setup.md).
+
+## If Something Fails
+
+- No T-10A data:
+  - re-check USB COM port
+  - verify head IDs
+  - verify straight CAT5 and external power for multi-point mode
+- No JETI data:
+  - re-check driver install
+  - confirm the PC measurement software is writing to the configured `output_path`, or
+  - confirm COM port and baudrate for serial mode
+- No EKO data:
+  - swap RS-485 `A/B`
+  - verify `12 VDC` power and fuse
+  - verify `slave_address`
+  - try a different `float_byte_order` if values are present but incorrect