GalvOS replaces the original control board of an RGB galvo laser projector (specifically the Mikoy 5W) with an ESP32-S3-based system. The result is a firmware platform that is more capable, fully open, and frankly more fun to work with than whatever the OEM shipped.
The origin story: the stock firmware couldn't dim the laser — it was full-brightness or nothing. What started as a quick bug investigation turned into a complete hardware and firmware replacement. Classic "Well, that escalated quickly..." moment.
Key capabilities:
- 16-bit galvo DAC (vs. OEM 12-bit) via SPI DAC8562
- Browser-based WebUI — no app install, works from any phone or desktop
- DMX-512, Art-Net, sACN/E1.31, and OSC input; Ether Dream and Helios (network) DAC protocols
- ILDA file playback from SD card
- Per-point laser modulation with full RGB PWM control
- BPM-synced show engine: global tempo clock (Tap/DMX/Manual), preset sequencer, and an 8-slot modulation matrix (LFO/Noise/Envelope/Step-Sequencer → any live pattern parameter)
- Hardware safety interlocks (scan-fail detection, watchdog, E-Stop, opto-isolated TTL)
- Point optimizer pipeline with adaptive density, S-curve blanking, and ringing compensation
- Camera-in-the-loop auto-tuning of optimizer parameters via a companion Python tool (see Chapter 6)
- Community Presets — browse, download, and activate GitHub-hosted preset bundles straight from the WebUI
- Temperature monitoring (up to 5× DS18B20 sensors)
Yes, all of this is real, and yes, it's all running on a 6 Freedom Money ($) microcontroller. (That exclude all the other components you need - but hey, sounds much more impressive this way :-) )
| Feature | What it does |
|---|---|
| 16-bit galvo DAC (DAC8562) | 4× the resolution of the OEM's 12-bit — lines that were jagged are now just... lines. |
| 9-stage point optimizer pipeline | Turns "draw a hexagon" into a stream the mirrors can physically survive — corner dwell, blanking, velocity/acceleration clamp, ZV ringing compensation. |
| 6 optimizer profiles (Vector, Smooth, Waves, Wireframe, MultiObject, Particles) | One-size-fits-all optimizer settings don't exist, so pick per preset class instead. Auto-switches with the active preset. |
| Smart Defaults button | Computes sane optimizer parameters from your kpps and frame budget. For when guessing sliders gets old. |
| Adjustable galvo sample rate (12–60 kpps) with Autotune | Binary-searches the highest rate your hardware handles before it starts buffering complaints. |
| CIE 1931 gamma correction | γ≈2.2 so "50% brightness" actually looks like 50% brightness to your eyeballs, not to a linear sensor. |
| Projection zone clipping | Draw a polygon, laser respects it. Points outside get blanked instead of redecorating your neighbor's wall. |
| Feature | What it does |
|---|---|
| Built-in preset library (Geometry, Waves, 3D, Scenes, math curves) | A whole gallery of shapes so you don't have to parametrize a Lissajous curve at 2 AM. |
| Auto-rotation (independent X/Y/Z) + static rotation offset | Spin any pattern on any axis, at its own speed, because static geometry is for cowards. |
| 7 color animation modes (Gradient, Chase, Strobe, Pulse, Twinkle, Flip, Seg) | Layer a light show on top of any preset's own color without touching its code. |
| Points-Only Mode | Turns any pattern into a dot cloud with configurable fade-in/out and fade direction — instant particle show. |
| Kaleidoscope (2–8-fold) & Mirror | Symmetric multiplication of whatever's on screen, because one hexagon is never enough. |
| Global BPM clock (Manual / Tap Tempo / DMX) | The whole show keeps a beat — priority DMX > Tap > Manual, with a big satisfying TAP button. |
| Preset Sequencer | A BPM-synced set list: walk presets step by step, beat-quantized, with optional blank transitions. Never auto-starts on boot — Class 4 lasers don't get autoplay. |
| Modulation engine (8 slots × 16 bindings) | LFOs, noise, multi-point envelopes, and step sequencers routed onto scale, rotation, hue, speed, density... Patterns that breathe on their own. |
| Modular modules: Camera, Duplicator, Spatial Noise, Dotter | Self-registering firmware modules that add 3D camera moves, frame cloning (grid/radial/spiral), organic wobble, and dot scatter — the UI discovers them automatically. |
| Freehand Paint tab | Draw with your finger or mouse, project it as vectors. Shape tools included for people who can't draw circles. |
| Laser Text mode | 3 fonts, 10 animations (scroll, bounce, typewriter, Star Wars crawl, ...), up to 127 characters. |
| Countdown timer with laser payoff | Set a timer, and when it hits zero: show text or fire off an ILDA file. Genuinely useful for events. |
| Community Presets (GitHub-hosted) | Browse a shared preset library straight from GitHub in the WebUI, download to the device, activate with one tap — each bundle carries a full optimizer tuning plus playback params. Now the internet can pick your colors too. |
| Community Preset Builder | Offline browser tool (community-presets/builder.html) for creating those bundles — for people who'd rather drag sliders than write C++. Advanced Mode even has a point/curve editor that exports C++ snippets for new built-in presets. |
| Feature | What it does |
|---|---|
| DMX-512 input (MAX485, 25 channels) | Talks to any real lighting desk like a grown-up fixture. |
| Art-Net input | DMX over Ethernet/Wi-Fi for the desk-less crowd. |
| sACN / E1.31 input (v6.08.0) | The standards-blessed way to do DMX over IP multicast. Same channel map, lowest priority of the three DMX-shaped sources. |
| OSC input (v6.08.0) | /galvos/* on UDP 9000 — preset, color, speed, brightness, and override from TouchOSC & friends. |
| Ether Dream protocol receiver | Laser software that speaks Ether Dream can stream point data straight to the projector. |
| Helios DAC network emulation (v6.08.0) | Helios point-stream framing over TCP 7768 — the USB variant stays a stub, the network one actually works. |
| Live software DMX console (WebUI) | 25 sliders, no physical desk required, with instant test patterns (red circle, rainbow). |
| WebUI override priority | WebUI wins over DMX on demand — for when you need to grab manual control mid-show. |
| Master dimmer (WebUI + DMX CH1 combined) | One dial to rule the overall brightness, regardless of source. |
| Feature | What it does |
|---|---|
| ILDA file playback from SD card | Plays the industry-standard laser show format straight off a memory card — subfolders, live speed/size/color-override controls, browser upload included. |
| Playlist manager | Queue multiple ILDA files with per-entry loop count and pause duration. |
| PSRAM budget guard for ILDA files | Files too big to load safely are grayed out before you play them, instead of rebooting the controller mid-show. |
| SD auto-mount watcher | Insert a card whenever — it gets picked up within 5 seconds. Eject means eject, until you say otherwise. |
| Independent SPI3 bus for SD | SD reads no longer corrupt the DAC output mid-frame — SD card lives on its own SPI3 bus (GPIO5/6/1/42), fully independent of the DAC's SPI2. |
| Feature | What it does |
|---|---|
| Galvo geometry calibration | Offset, gain (linked X/Y), swap, invert — dial in a perfectly centered, correctly proportioned image. |
| Color/gamma calibration patterns | White fill, per-channel fill, three-circle white balance, crosshair, grid, DAC range box, official ILDA test pattern. |
| Visibility threshold calibration | Finds each laser diode's "dead zone" so 0–100% brightness maps to what's actually visible instead of a chunk of invisible PWM range. |
| Auto White Balance | Calculates per-channel gain from configured laser power so R/G/B actually look equally bright. |
| Camera-in-the-loop auto-tuning | A USB camera + Optuna search auto-tunes optimizer profiles against measured beam quality — no more "nudge a slider, squint at the wall" loop. See Chapter 6. |
| Feature | What it does |
|---|---|
| Hardware E-Stop input | A physical kill switch the firmware cannot override. |
| NE555 scan-fail detection | If the galvo stops moving (or firmware hangs), the laser cuts — hardware-level, no software in the loop. |
| NE555 hardware watchdog | Independent of the ESP32's own watchdog; catches the case where the ESP32 itself locks up. |
| Fail-safe opto-isolated RGB TTL | 10kΩ pull-ups keep every laser channel OFF by default on boot, reset, panic, or brownout. |
| OTA update lockout while armed | Can't push new firmware to a live, armed laser. On purpose. |
| Safety Assessment card | Live laser-class and audience-distance estimate from your configured power and beam angles. |
| Thermal protection | Up to 5× DS18B20 sensors, configurable warn/reduce/shutdown thresholds, auto or manual fan control. |
| Feature | What it does |
|---|---|
| Browser-based WebUI, installable as a PWA | No app store, no native install — works full-screen from any phone, tablet, or desktop. |
| Three switchable themes | Cyberpunk/Glitch, Terminal CLI, Minimalist Dark — same controls, three personalities, zero flash-of-wrong-theme on reload. |
| Mobile-first safety controls | ARM/DISARM and Master Dimmer pinned in an always-visible top bar, 44 px touch targets — the kill switch never scrolls away. |
| Per-protocol debug logging | A "snitch switch" per network protocol (DMX, Art-Net, Ether Dream, Helios, OSC, sACN) — raw traffic straight into the Log tab. |
| Live Dashboard | Safety status, telemetry, CPU load, temperature history, DAC output rate, and frame composition — all scrolling in real time. |
| Live log console + memory viewer | Streamed over WebSocket, color-coded by severity, plus a heap/PSRAM breakdown by subsystem for hunting leaks. |
| Wi-Fi AP + STA mode, mDNS | Boots as its own access point out of the box; joins your network and answers at galvOS.local once configured. |
| Static IP / DHCP configuration | For the tinfoil hatters who don't trust DHCP leases. |
| REST API with token auth | Full external control surface — see API Reference. |
| Factory reset | Nukes all NVS config back to defaults when you've fat-fingered one setting too many. |
Feeling yolo? Take this route then:
- Read the Safety section — seriously.
- Check Prerequisites — tools and hardware needed.
- Build & Flash — PlatformIO build, firmware + WebUI upload.
- Connect to WebUI — Wi-Fi, browser, done.
Need a good sleep aid? This is the one for you here:
| Chapter | Description |
|---|---|
| 01 — Introduction | Project background, safety, disclaimer, hardware overview |
| 02 — Prerequisites | Tools, hardware, software, and skills needed |
| 03 — Build & Configuration | PlatformIO setup, all configurable parameters, flash instructions |
| 04 — UI Guide | Complete walkthrough of all WebUI tabs and controls |
| 05 — The Optimizer | Deep-dive into the point optimizer pipeline |
| 06 — Auto-Tuning (CAM-based) | Automated optimizer tuning via scripts/optimizeGalvo/optimizeGalvo.py and a USB camera |
| 07 — Troubleshooting | Common problems and how to solve them |
| 08 — API Reference | REST API endpoints for integration and automation |
| 09 — Contributing | How to contribute, code style, patch workflow |
| 10 — Known Issues & To-dos | Open bugs, missing features, planned work |
| 11 — Glossary & Terminology | All (no but most) abbreviations and technical terms explained |
Don't like one's and zero's that much? Well, this one is for you then:
| Component | Part |
|---|---|
| MCU | ESP32-S3-WROOM-1 N16R8 (16 MB Flash, 8 MB OPI PSRAM) |
| DAC | DAC8562 (16-bit, dual-channel, SPI) |
| Output Stage | OPA4134UA quad op-amp — differential ±5V galvo drive |
| Galvo Set | Jolooyo JY-15K-BL (15 kpps, ±20° optical) |
| Laser Driver | MN-1M5AT (3-channel constant-current buck, active-HIGH) |
| DMX | MAX485 module (receive-only, XLR) |
| Safety | NE555 scan-fail + NE555 hardware watchdog, 6N137 optocouplers |
| Temperature | DS18B20 × up to 5, 1-Wire bus |
| Power | HW-613 buck converter (+5V rail); external ±15V galvo PSU |
| Construction | Perfboard 15 × 9 cm; Gerber File for custom PCB is in progress |
Full netlist: hardware/
GalvOS/
├── src/ # Firmware source (C++, Arduino/PlatformIO)
│ ├── control/ # DMX, Art-Net, safety control
│ ├── ilda/ # ILDA file parser
│ ├── net/ # WebUI server, REST API, Art-Net/sACN/OSC/Ether Dream/Helios receivers
│ ├── output/ # Galvo ISR, DAC output, RGB PWM
│ ├── patterns/ # Pattern engine, presets, optimizer
│ ├── safety/ # E-Stop, watchdog, scan-fail
│ ├── sensors/ # DS18B20, temperature monitoring
│ ├── storage/ # NVS config persistence
│ └── util/ # Shared utilities
├── include/
│ ├── config.h # Runtime config struct, optimizer defaults
│ └── pinmap.h # All GPIO assignments
├── data/
│ └── index.html # WebUI (single-file PWA, served via LittleFS)
├── community-presets/ # GitHub-hosted community preset library
│ ├── index.json # Preset index fetched by the WebUI's GitHub Browser
│ ├── builder.html # Community Preset Builder (offline browser tool, no backend)
│ └── *.json # The preset bundles themselves
├── hardware/ # Netlist, wiring diagrams
├── scripts/
│ ├── upload_all.py # PlatformIO target: flash firmware + LittleFS
│ ├── gzip_assets.py # Pre-build hook: gzip data/ assets
│ ├── test_protocols.py # Manual Ether Dream/Helios stream test client
│ └── optimizeGalvo/ # Camera-in-the-loop auto-tuning tool (see docs/06)
├── docs/ # Full documentation (you are here)
├── assets/ # Screenshots, diagrams
├── platformio.ini # Build configuration
└── partitions.csv # Flash partition table
(I know - BORING! But hey - at least you read this far. So keep going!)
This project involves CLASS IIIB or CLASS IV laser devices.
Lasers at these power levels are capable of causing immediate and permanent eye injury and skin burns, and can ignite materials at close range.
- Never look into the beam or at specular (mirror-like) reflections.
- Always use appropriate laser safety eyewear — OD rating matched to your specific wavelengths and power level.
- Never operate the laser without proper enclosure or beam stops in place.
- By modifying this device, the original CE marking and safety certification are void.
- You are solely responsible for the safe operation of any device built using this project.
- Check your local laws — modifying laser equipment may require licensing in your jurisdiction.
🔴 This project is intended for experienced makers and engineers who understand laser safety. Treat every beam as dangerous until proven otherwise.
- Firmware & Software: GNU General Public License v3.0
- Hardware Designs: CERN Open Hardware License v2 — Strongly Reciprocal (CERN-OHL-S)
Contributions welcome under the same license terms. See Contributing.