Loading project Things
README.mdView source
BorneoIoT: Professional Aquarium Lighting Platform
If you would like to support this project, please consider purchasing a ready-to-use, pre-tested, pre-loaded firmware product from PCBWay Store:
Production-grade open-source stack for aquarium LED dimmers. Hardware designs, embedded firmware, and mobile controls. Ready for weekend builds or product integration.
This project delivers a full-stack solution for smart aquarium LED:
- Hardware: Certified open-source PCB designs targeting the ESP32 family, featuring 6-channel PWM dimming and modular architecture.
- Firmware: A robust ESP-IDF based firmware implementing CoAP/CBOR protocols, sunrise/sunset simulation, and cooling control.
- Mobile App: A cross-platform Flutter application for intuitive real-time control, scheduling, and device management.
What Makes Borneo-IoT Stand Out
- Detailed, multi-channel dimming: Supported controllers offer 6 or 12 PWM channels with at least 12-bit (4096-step) resolution. Users can set a custom brightness for each channel at multiple points throughout the day, then let the controller smoothly interpolate between those points.
- Schedules that cross midnight: The schedule editor uses a 48-hour time axis, so a lighting curve can continue past midnight—for example, from 22:00 to 06:00 the following day.
- Location-aware Sun Simulation: Using the device's location and time zone, the firmware calculates solar timing for the current date and generates a 13-point curve based on the sun's changing altitude from sunrise through solar noon to sunset. It recalculates the schedule daily, allowing the curve's timing and shape to change through the year instead of repeating a fixed daily pattern.
- Smoother, more natural transitions: CIE1931 brightness correction and eased fades help make dimming appear more perceptually even, particularly at low brightness and during transitions.
- Control beyond lighting: The firmware also includes temperature-based cooling control, acclimation features, time synchronization, and OTA (over-the-air) updates.
- Local-first, extensible ecosystem: The mobile app supports multi-device management and group control over a local network. Developers can also use the Python SDK and command-line tools for automation, device discovery, and local firmware updates.
- Open from hardware to software: The repository includes hardware designs, firmware, the mobile app, and the Python SDK, giving DIY builders and developers room to assemble, customize, and extend the platform.
Quick Start
New users: Follow the step-by-step guide to flash firmware and connect your first device.
No toolchain required, flash directly from Chrome/Edge Browser:
- Connect ESP32/ESP32-C3/ESP32-C5 via USB
- Visit flasher.borneoiot.com
- Download the app and power on
Features
Hardware
- 6 or 10 PWM channels, 12-bit resolution (4096 steps), up to 19kHz
- Flicker-free, suitable for aquarium photography
- 22×30mm core module, fits slim LED fixtures
- ESP32-C3/C5 native, WiFi + Bluetooth LE
Firmware
- Multi-channel LED control: Per-channel brightness control with scheduled, manual, and solar-simulation modes. Supports configurable 12-bit dimming by default and up to 13-bit resolution on supported builds.
- Custom lighting schedules: Define color and brightness keyframes for each channel. The controller interpolates between keyframes, and schedules can cross midnight using the app's 48-hour timeline.
- Astronomical Sun Simulation: Generates a 13-point daily lighting curve from the device's location, date, and time zone, then recalculates it as the day changes through the year.
- Lunar-cycle lighting: Optional moonlight simulation uses estimated moonrise, moonset, and lunar illumination to create a nightly brightness curve that can cross midnight.
- Passing cloud shadows: Optional randomized cloud events briefly reduce overall light intensity to simulate passing clouds.
- Acclimation mode: Gradually increases light intensity over a configurable period to help livestock adapt to a new lighting setup.
- Perceptually smoother dimming: CIE1931 brightness correction, eased fades, and temporal dithering improve transitions and low-brightness control.
- Time and timezone support: Automatic SNTP time synchronization and timezone-aware schedules.
- Thermal management: Optional NTC temperature monitoring with manual or PID-based fan control, depending on the board configuration.
- Hardware protection: Optional over-temperature and over-power monitoring with automatic shutdown when configured limits are exceeded.
- Power telemetry: Optional voltage and current measurement on supported hardware.
- Multi-controller clustering (Pro only): Synchronizes lighting state across compatible controllers, with configurable channel mapping.
- Device discovery and provisioning: Wi-Fi device discovery over mDNS, with BLE provisioning available on supported builds.
- Remote management and updates: CoAP + CBOR device control, status and sensor queries, and local OTA (over-the-air) firmware updates.
Mobile App
- Cross-platform: iOS, Android, Windows, built with Flutter
- Real-time control: dimming, scheduling, scene presets
- Multi-device: group control, cloud-free local network
- Developer API: Python client for automation
Repository Guide
| Directory | Contents | Entry Point |
|---|---|---|
hw/ | PCB designs (Horizon EDA), Gerbers, 3D models | hw/README.md |
fw/ | ESP-IDF firmware, CoAP protocol | fw/README.md |
client/ | Flutter mobile app | client/README.md |
borneopy/ | Python client library | borneopy/README.md |
Getting Started
- New Users: Check out our Quick Start Guide.
- If you are a new user looking to quickly experience our firmware, you can directly use our web firmware flasher to flash the latest version of the firmware to your ESP32 series development board: https://flasher.borneoiot.com/
- Hardware: Find schematics and BoM files in the
hw/directory. - Firmware: Compilation instructions are available in the
fw/folder.
Project Status
| Component | Status | Details |
|---|---|---|
| Hardware | Stable | Production-ready, OSHWA certified. |
| Firmware | Nearly Perfect | Full-featured and stable on personal tanks for years. |
| Mobile App | Nearly Perfect | Core functionality complete and ready for everyday use. |
Roadmap
Check our milestones for the latest development updates and upcoming features.
Community & Support
- Website: www.borneoiot.com
- Documentation: docs.borneoiot.com
- Discussions: Join the Conversation
- Discord: Connect with Developers
- Email: info@binarystarstech.com
Licenses
- Software/Firmware: Dual-licensed under GPL-3.0+ and Enterprise licenses.
- Hardware: Licensed under CERN-OHL-S-2.0.
Copyright © 2025-TODAY Yunnan BinaryStars Technologies, Co., Ltd. All rights reserved.
The hardware, firmware, and App for this project were all created by: Wei Li（李维）.