Feature/top piece

LICENSE

@@ -0,0 +1,83 @@
+Monada Dominion Non-Commercial No-Derivatives Source License (MD-NC-ND) v1.0
+
+IMPORTANT: THIS IS NOT AN OPEN SOURCE LICENSE. IT DOES NOT GRANT PERMISSION FOR COMMERCIAL USE OR FOR DISTRIBUTION OF MODIFIED VERSIONS. BY USING ANY PORTION OF THE LICENSED MATERIAL YOU ACCEPT THESE TERMS.
+
+0. Definitions
+"Licensor" means the copyright holder(s) listed in the copyright notice(s).
+"Licensed Material" means the source code, build scripts, asset files, and accompanying documentation in this repository (the "Project").
+
+"Source Form" means the preferred form for making modifications, including all associated build or configuration files.
+
+"Verbatim Copy" means an exact, unmodified copy of the Licensed Material, preserving all file contents and notices.
+
+"Non-Commercial Use" means any use that (a) is not conducted for or directed toward commercial advantage or monetary compensation; and (b) is not incorporated into, or used to provision, a product or service offered for a fee, subscription, advertising revenue, or other consideration. Academic research, personal study, internal evaluation by a non-profit organization, and classroom teaching are Non-Commercial Uses provided no fee is charged specifically for access to, or use of, the Licensed Material beyond cost-recovery for media or hosting.
+
+"Commercial Use" means any use that is not Non-Commercial Use. Operating the Licensed Material (modified or unmodified) as part of a hosted or managed service for third parties is Commercial Use.
+
+1. Grant of Limited Rights
+Subject to your full compliance with this License, the Licensor grants you a personal, worldwide, revocable, non-exclusive, non-transferable, royalty-free license to:
+ (a) Use and execute the Licensed Material in Source Form or compiled form strictly for Non-Commercial Use; and
+ (b) Create temporary, incidental copies (e.g., in object code, build artifacts, caches) necessary for such Non-Commercial Use; and
+ (c) Distribute Verbatim Copies for Non-Commercial Use, provided Section 4 (Attribution & Notice) is satisfied.
+
+2. No Derivatives / Modification Restriction
+You may not modify, adapt, translate, reverse engineer (except to the extent required by applicable law), or create derivative works of the Licensed Material, except that you may make purely ephemeral modifications strictly necessary to (i) configure build parameters (e.g., editing a .env or config file), or (ii) apply security patches you authored for internal Non-Commercial Use. ANY distribution of a modified or derivative version is expressly prohibited.
+
+3. Prohibited Activities (Without a Separate Commercial / Derivative License)
+Without prior written permission from the Licensor you must NOT:
+ (a) Engage in Commercial Use of the Licensed Material (modified or unmodified);
+ (b) Offer, sell, rent, lease, sublicense, or otherwise commercialize the Licensed Material;
+ (c) Provide the Licensed Material (modified or unmodified) as part of a service, SaaS, hosted, or managed offering;
+ (d) Distribute modified, patched, combined, or derivative versions;
+ (e) Remove, alter, or obscure copyright, license, trademark, or attribution notices;
+ (f) Circumvent or remove any technical protection or usage limitations applied by the Licensor.
+
+4. Attribution & Notice
+All Verbatim Copies you distribute must retain in all files (or in a top-level NOTICE file if present):
+ - Original copyright notice(s);
+ - This License text in full;
+ - A notice substantially in the form: "This distribution contains the Monada Dominion project licensed for NON-COMMERCIAL, NO-DERIVATIVES use under the MD-NC-ND License v1.0. See LICENSE.";
+ - A URL or repository reference to the canonical upstream source (if provided by Licensor).
+
+5. Patent Notice
+NO PATENT LICENSE IS GRANTED OR IMPLIED BY THIS LICENSE. If you initiate or threaten patent litigation (including cross-claim or counterclaim) alleging that the Licensed Material or a contribution thereto infringes any patent, your rights under this License terminate immediately.
+
+6. Feedback
+You may (but are not required to) submit ideas, feedback, or suggestions ("Feedback"). By submitting Feedback you grant Licensor a perpetual, irrevocable, worldwide, transferable, sublicensable, royalty-free license to use, incorporate, and distribute the Feedback without obligation or attribution.
+
+7. Termination
+This License terminates automatically without notice if you breach any term. Upon termination you must cease all use and distribution, destroy local copies (excluding automatically generated backup archives retained unintentionally), and certify compliance upon request. Sections 4–13 survive termination.
+
+Licensor may, at its sole discretion, offer you a different (e.g., commercial or derivative) license under separate written terms.
+
+8. Disclaimer of Warranty
+THE LICENSED MATERIAL IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. YOUR USE IS AT YOUR SOLE RISK.
+
+9. Limitation of Liability
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT WILL LICENSOR OR CONTRIBUTORS BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES; OR FOR ANY LOSS OF PROFITS, REVENUE, DATA, GOODWILL, OR BUSINESS INTERRUPTION; OR FOR SUBSTITUTE GOODS OR SERVICES; ARISING OUT OF OR RELATED TO THIS LICENSE OR USE OF THE LICENSED MATERIAL, HOWEVER CAUSED AND UNDER ANY THEORY OF LIABILITY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TOTAL AGGREGATE LIABILITY SHALL NOT EXCEED ONE HUNDRED (100) USD OR THE AMOUNT (IF ANY) PAID TO LICENSOR FOR THE LICENSED MATERIAL DURING THE SIX (6) MONTHS PRIOR TO THE CLAIM.
+
+10. Compliance with Law
+You are solely responsible for compliance with all applicable laws, regulations, and third-party rights in connection with your use of the Licensed Material.
+
+11. Severability
+If any provision of this License is held unenforceable, that provision will be reformed only to the extent necessary to make it enforceable. The remaining provisions remain in full force and effect.
+
+12. No Waiver
+Failure of Licensor to enforce any right or provision shall not constitute a waiver of future enforcement of that right or provision.
+
+13. Governing Law (Optional)
+If the Licensor designates a jurisdiction in the copyright notice (e.g., "Governing Law: State / Country"), this License will be governed by the laws of that jurisdiction excluding its conflict-of-law principles. Otherwise, governing law is determined by applicable conflict-of-law rules.
+
+14. Entire Agreement
+This License constitutes the entire agreement between you and the Licensor concerning the Licensed Material and supersedes all prior or contemporaneous understandings regarding its subject matter.
+
+15. Versioning
+The Licensor may publish new versions of this License with a unique version number. Unless explicitly stated otherwise, you may continue to use the Licensed Material under the version originally applied.
+
+16. Contact for Commercial / Derivative Licensing
+To request commercial, derivative, or broader usage rights, contact: [make an issue]. Granting such rights is at Licensor's sole discretion.
+
+Copyright (c) 2025 Monada Dominion and/or individual contributors as noted.
+All rights reserved except as expressly granted herein.
+
+END OF LICENSE

big_lamps_prototype/README.md

@@ -0,0 +1,77 @@
+GLOW 2025 — Big Lamps Prototype (Teensy + Dual DMX Shields)
+
+Overview
+- Teensy 4.1 drives two TinkerKit T040060 DMX shields as RS‑485 transmitters.
+- Two DMX universes: Serial1 (pin 1 TX) for 3 lamps, Serial2 (pin 8 TX) for 2 lamps.
+- All 5 lamps behave the same: channels 1–108 are mirrored from U1 to U2.
+- Primary code: `top/big_lamps_prototype/main_updated.cpp` (paste into a `.ino` for Arduino IDE if needed). The older `main.cpp` can be ignored.
+
+Hardware setup
+- Shields act only as RS‑485 line drivers; DMX is controller‑transmit only.
+- Wiring (Teensy 4.1):
+	- Shield #1 DI ← Teensy pin 1 (Serial1 TX) → Universe 1 (3 fixtures in chain)
+	- Shield #2 DI ← Teensy pin 8 (Serial2 TX) → Universe 2 (2 fixtures in chain)
+	- Optional RX lines are not used.
+	- Common GND between Teensy, shields, and lamp PSU.
+	- DMX/XLR pins: 1=GND, 2=Data− (B), 3=Data+ (A).
+	- Termination: last fixture in each chain ON (120 Ω).
+	- DE/RE on shields: tie for transmit enable per shield docs (controller is TX‑only).
+
+DMX addressing (assumes 108 channels/fixture)
+- Universe 1 chain: A1=1, A2=109, A3=217.
+- Universe 2 chain: A4=1, A5=109.
+- All fixtures use the same 108‑channel personality. Set via menu/DIP.
+
+Code architecture (main_updated.cpp)
+- Libraries: TeensyDMX, Arduino.
+- Two Senders: `dmx1(Serial1)` and `dmx2(Serial2)`.
+- Drive channels 1..108 each frame from a generated pattern (moving gradient).
+- Mirroring: by default the same value `v` is written to U1 and U2 for each channel.
+- Validation mode (optional): define `VALIDATE_DIFFERENT_UNIS` to drive U2 with a different pattern for hardware path checks.
+- Diagnostics: periodic `logFrame(frame, phase, U1_ch1, U2_ch1)` via Serial.
+- Timing: simple `elapsedMillis` tick with `delay(5)` pacing (logic‑level simulation of ~100–200 Hz update cadence).
+
+Build and upload (Arduino IDE)
+1) Open Arduino IDE (with Teensyduino installed).
+2) Create a new sketch and paste `main_updated.cpp` content (Arduino requires `.ino`).
+3) Tools → Board: Teensy 4.1; USB Type: Serial; CPU Speed: 600 MHz.
+4) Upload and open Serial Monitor at 115200 baud.
+
+Expected behavior on hardware
+- Both universes output identical data on channels 1–108 (mirrored), yielding identical looks on the 3‑lamp chain and the 2‑lamp chain.
+- Serial prints every ~50 frames: `frame=... phase=... ch1=U1/U2`.
+- If `VALIDATE_DIFFERENT_UNIS` is defined: U2 intentionally differs (inverse/faster modulation) for visual validation.
+
+No‑hardware host simulator
+- Location: `top/big_lamps_prototype/host_sim`.
+- What it does: stubs Arduino and TeensyDMX APIs and runs `main_updated.cpp` on macOS. This validates logic and logging without real hardware.
+- Build and run (macOS):
+```zsh
+cd ~/Documents/GLOW_2025/top/big_lamps_prototype/host_sim
+clang++ -std=c++17 -Iinclude run.cpp -o sim
+./sim | head -50
+```
+- Expected output: the same startup and periodic frame logs you’d see on Teensy, then “Host sim finished.”
+- Notes: this does not simulate DMX timing or the physical bus; it exercises the code flow only.
+
+Planned command protocol (USB Serial and later a spare UART)
+- During development: send commands over USB Serial; for production also accept via a spare UART (e.g., Serial3).
+- Minimal commands (to be added):
+	- `FILL <v>` — set ch 1–108 to value 0..255
+	- `BLACKOUT` — set all to 0
+	- `GRAD <speed>` — gradient animation with speed 1..10
+	- `SET <ch> <v>` — set channel
+	- `PING` — respond `PONG`
+
+Troubleshooting
+- No light: verify fixture start address=1 and correct personality; confirm termination; check DE/RE enable; swap XLR pins 2/3 if needed.
+- One universe dark: check correct Teensy pin (1 vs 8), shield power/GND, and cable.
+- Serial.printf issues: the code uses a safe `logFrame` helper that falls back to Serial.print when printf isn’t available.
+- Editor include squiggles: harmless for Arduino builds; use Arduino IDE or PlatformIO to compile/upload.
+
+Optional: PlatformIO
+If you prefer PlatformIO, create a `platformio.ini` (Teensy 4.1, Arduino framework, TeensyDMX lib), then `pio run -t upload` and `pio device monitor -b 115200`.
+
+License
+- See repository root for license information (if applicable).
+

big_lamps_prototype/docs/DMX_States_and_Order.md

@@ -0,0 +1,82 @@
+# DMX Multi‑Universe: States and Execution Order
+
+Applies to: /top/big_lamps_prototype/main.cpp
+
+Overview
+- Libraries: TeensyDMX (Sender on Serial1/2/3), Arduino core.
+- Universes: U1, U2, U3 (U3 initialized but not used in loop).
+- Behavior: Brightness sweeps 0→255→0; U1 RGB follow brightness; U2 uses inverse red, zero green, blue follows brightness.
+
+Key Variables
+- brightness (uint8_t): 0..255, the current fade level.
+- direction (int): +1 when increasing, −1 when decreasing.
+- baseAddr (int): 1, base DMX address for the first fixture in U1.
+
+High-Level States
+1) Setup
+   - Serial.begin(115200)
+   - dmxX.begin() for U1, U2, U3
+   - For channels 1..512 on each universe: set value = 0
+   - Log: "DMX Multi-Universe Started"
+2) Running
+   - Every loop tick (~10 ms):
+     - Write U1 channels:
+       - Ch 1 (R) = brightness
+       - Ch 2 (G) = brightness
+       - Ch 3 (B) = brightness
+     - Write U2 channels:
+       - Ch 1 (R) = 255 - brightness
+       - Ch 2 (G) = 0
+       - Ch 3 (B) = brightness
+     - Update brightness: brightness += direction
+     - Edge handling:
+       - If brightness == 255 → direction = −1
+       - If brightness == 0 → direction = +1
+     - delay(10)
+
+Execution Order Per Loop Iteration
+1) Compute baseAddr = 1 (constant in this sketch).
+2) Set DMX for U1 (Ch 1..3) and U2 (Ch 1..3) based on current brightness.
+3) Increment brightness by direction.
+4) If at bounds (0 or 255), flip direction.
+5) Wait 10 ms.
+
+Timing Notes
+- Update rate: ~100 Hz.
+- One full triangle wave cycle: 256 steps up + 256 down = 512 steps ≈ 5.12 s.
+
+DMX Universe/Channel Mapping Used
+- Universe 1
+  - Ch 1: R = brightness
+  - Ch 2: G = brightness
+  - Ch 3: B = brightness
+- Universe 2
+  - Ch 1: R = 255 - brightness
+  - Ch 2: G = 0
+  - Ch 3: B = brightness
+- Universe 3
+  - Initialized, not updated in loop.
+
+Notes
+- DMX channels are 1-based (1..512).
+- FIXTURE_CHANNELS and NUM_FIXTURES_U1/U2 are defined for context but not used in loop.
+- Direction flip happens exactly at 0 and 255, avoiding under/overflow artifacts.
+
+State Diagram
+
+~~~mermaid
+stateDiagram-v2
+  [*] --> Setup
+  Setup: Serial + DMX init\nZero all channels
+  Setup --> Running
+
+  state Running {
+    [*] --> Increasing
+    Increasing: direction = +1
+    Increasing --> Decreasing: brightness == 255
+    Decreasing: direction = -1
+    Decreasing --> Increasing: brightness == 0
+  }
+
+  Running --> Running: Each ~10 ms tick\n- Set U1/U2 channels\n- brightness += direction
+~~~