Professional-grade presence detection for your smart home
Open-source smart home presence sensor with complete design files included. Custom ESP32 circular PCB (KiCad), mmWave+PIR+lux sensors, 3D-printable enclosure, and mounting solutions. Deploy via PoE, Ethernet+USB-C, or WiFi+USB-C. ESPHome-ready for Home Assistant integration.
Fork it, build it, customize it. Professional results, maker-friendly.
🔗 Repository: https://github.com/Soriarty/HaloSense
- mmWave Radar - Accurate presence detection (even stationary people)
- PIR Motion Sensor - Fast motion detection for instant room entry trigger
- Ambient Light Sensor - Lux measurement for smart lighting automation
Why Both mmWave + PIR?
- PIR: Instant detection (<0.1s) when entering room - immediate automation trigger
- mmWave: Continuous presence monitoring - detects even stationary people
- Combined: Best of both worlds - instant response + accurate presence tracking
- PoE Mode - Single cable for power + data (IEEE 802.3af)
- Ethernet + USB-C - Standard network connection with USB power
- WiFi + USB-C - Wireless connectivity for flexible placement
- Hardware - Single mainboard design (circular form factor)
- Top-side: ESP32 + sensor module connectors
- Bottom-side: PoE circuit + vertical Ethernet + vertical USB-C
- Firmware - ESPHome configuration for Home Assistant
- Enclosure - 3D-printable housing (STL files)
- Mounting - Various mounting options (wall, ceiling, desk)
Inspired by devices like the Aqara FP2, but addressing key limitations:
- ✅ Wired networking - No WiFi congestion, rock-solid reliability
- ✅ PoE support - Single cable installation
- ✅ Open source - Full control, no cloud dependencies
- ✅ ESPHome integration - Seamless Home Assistant compatibility
- ✅ Flexible deployment - Multiple power/connectivity options
- ✅ DIY-friendly - Build it yourself, customize to your needs
🚧 Current Phase: Phase 1 - Component Selection & Planning (100% complete ✅)
This is a hobby project in active development with a realistic timeline. Check back for updates!
| Phase | Milestone | Focus Area | Status | Target |
|---|---|---|---|---|
| Phase 1 | v0.1 | Component Selection & Planning | ✅ Complete (100%) | 2026 Q1 |
| Phase 2 | v0.2 | Hardware Design (Schematic, PCB, BOM) | 📋 Planned | 2026 Q3 |
| Phase 3 | v0.3 | Firmware Development (ESPHome) | 📋 Planned | 2026 Q4 |
| Phase 4 | v0.4 | Enclosure Design (3D Models, FreeCAD) | 📋 Planned | 2027 Q1 |
| Phase 5 | v0.5 | Prototype & Testing | 📋 Planned | 2027 Q2 |
| Phase 6 | v1.0 | Documentation & Public Release | 📋 Planned | 2027 Q3 |
- ✅ Project setup, Git Flow workflow, Wiki (15+ pages)
- ✅ Sensors selected with full documentation (mmWave, PIR, Light)
- ✅ ESP32 modules documented (WROOM-32E recommended, WROVER-E alternative)
- ✅ Hardware components documented (Ethernet PHY, PoE, Power ICs, USB)
- ✅ GPIO allocation finalized (all conflicts resolved)
- ✅ OLIMEX ESP32-POE reference design analyzed
📊 Track detailed progress:
- GitHub Project Board - Kanban view with all tasks
- Milestones - Phase tracking with due dates
- Open Issues - Current work items
- Closed Issues - Completed work
HaloSense/
├── hardware/ # KiCad PCB design files (planned)
│ ├── schematics/
│ ├── pcb/
│ ├── gerbers/
│ ├── reference/ # Reference designs (submodules)
│ │ └── esp32-poe/ # OLIMEX ESP32-POE reference ✓
│ └── README.md
├── firmware/ # ESPHome configuration (planned)
│ ├── halosense.yaml
│ └── FIRMWARE_GUIDE.md
├── enclosure/ # 3D printable models (planned)
│ ├── stl/
│ ├── step/
│ └── ENCLOSURE_DESIGN.md
├── docs/ # Technical documentation (for developers)
│ ├── wiki/ # Wiki submodule (user documentation) ✓
│ │ ├── Home.md
│ │ ├── Getting-Started.md
│ │ ├── Assembly-Guide.md
│ │ ├── FAQ.md
│ │ └── ... (15 Wiki pages)
│ ├── hardware/ # Hardware component documentation ✓
│ │ ├── components/ # All hardware components (sensors + ICs)
│ │ │ ├── dfrobot-c4001/ # mmWave radar sensor
│ │ │ ├── panasonic-ekmc1604111/ # PIR motion sensor
│ │ │ ├── rohm-bh1750/ # Ambient light sensor
│ │ │ ├── espressif-esp32-wroom-32e/ # ESP32 MCU (recommended)
│ │ │ ├── espressif-esp32-wrover-e/ # ESP32 with PSRAM
│ │ │ ├── microchip-lan8720a/ # Ethernet PHY
│ │ │ ├── ti-tps2378/ # PoE controller
│ │ │ ├── ti-tps62a02a/ # 3.3V buck converter
│ │ │ ├── silergy-tx4138/ # 5V buck converter
│ │ │ ├── tp-tp4054/ # Battery charger
│ │ │ └── wch-ch340x/ # USB-UART bridge
│ │ ├── power-budget.md # Power consumption analysis
│ │ └── ip-rating.md # IP54 enclosure design
│ ├── development/ # Developer workflow docs ✓
│ │ ├── git-flow.md
│ │ ├── conventional-commits.md
│ │ ├── versioning.md
│ │ ├── branch-protection.md
│ │ └── github-wiki.md
│ ├── assembly.md # → Redirects to Wiki
│ ├── bom.md # → Redirects to Wiki
│ └── installation.md # → Redirects to Wiki
├── CONTRIBUTING.md # Contribution guidelines ✓
├── LICENSE.md # Project license ✓
├── CHANGELOG.md # Version history ✓
└── README.md # This file
For building and using HaloSense, visit the Wiki:
- Getting Started Guide - Start here!
- Bill of Materials - What to buy
- Assembly Guide - How to build
- Installation Guide - Setup and config
- FAQ - Common questions
- Troubleshooting - Problem solving
For developers and technical details, see the docs/ directory:
Hardware Components (Sensors + ICs):
- All Components Overview & GPIO Allocation - Complete documentation, power budget
- DFRobot C4001 mmWave Radar - UART protocol, ESPHome integration
- Panasonic EKMC1604111 PIR Sensor - Motion detection specs
- ROHM BH1750FVI Light Sensor - I2C ambient light sensor
- ESP32-WROOM-32E Module - Main MCU
Development Workflow:
- Git Flow Workflow - Branching strategy
- Conventional Commits - Commit standards
- Contributing Guidelines - How to contribute
- Hardware: See Bill of Materials on Wiki
- Software:
- KiCad 9.0+ - PCB design
- FreeCAD 1.0+ - 3D enclosure design
- ESPHome - Firmware
- Home Assistant - Integration (optional)
- PoE (802.3af): 15.4W available, ~5W typical consumption
- USB-C: 5V/2A minimum
- Ethernet + USB-C: Standard networking + external power
- Ethernet: 10/100 Mbps
- WiFi: 802.11 b/g/n (2.4GHz)
- Protocol: MQTT, Home Assistant API
-
mmWave Radar: DFRobot C4001 (SEN0609)
- 24GHz FMCW radar, UART interface (115200 baud)
- GPIO: GPIO16 (RX), GPIO9 (TX) - Software UART
- Presence: 16m, Motion: 25m, 100° × 40° beam
- ESPHome compatible, ASCII command protocol
-
PIR Motion: Panasonic EKMC1604111
- Three-step lens (12m/6m/3m zones), Digital output
- GPIO: GPI35 (input-only, 33kΩ pull-down resistor)
- Coverage: 105° × 40° (asymmetric vertical), 68 beams
- Response: <0.1s instant trigger, 170μA low power
- Mainboard-integrated (through-hole mounting)
-
Light Sensor: ROHM BH1750FVI
- Digital 16-bit I2C ambient light sensor
- GPIO: GPIO32 (SDA), GPIO33 (SCL) - Hardware I2C
- Range: 1-65,535 lx (extendable to 0.11-100,000 lx)
- Resolution: 0.5-4 lx, Address: 0x23 or 0x5C
- Power: 120μA active, 0.01μA standby (0.4mW typical)
- ESPHome native support, JLCPCB available (C78960)
All GPIO conflicts resolved - No interference with Ethernet RMII or boot strapping pins.
-
MCU: ESP32-WROOM-32E
- Dual-core Xtensa LX6 @ 240 MHz, 520KB SRAM, 4/8/16MB Flash
- Wi-Fi 802.11 b/g/n + Bluetooth 4.2 BR/EDR/BLE
- All 38 GPIOs available (including GPIO16/GPIO17)
-
Ethernet PHY: Microchip LAN8720A (10/100 Mbps RMII)
-
PoE Controller: TI TPS2378 (IEEE 802.3af/at, up to 25.5W)
-
Power ICs:
- Silergy TX4138 (48V → 5V buck converter)
- TI TPS62A02A (5V → 3.3V buck converter for LAN PHY)
- TP4054 (Li-Po battery charger, optional backup)
-
USB Bridge: WCH CH340X (USB-to-UART for programming)
See Hardware Components Documentation for complete specifications.
- Form Factor: Circular PCB (based on OLIMEX ESP32-POE reference)
- Diameter: TBD (Phase 2 design)
- Mounting: Wall, ceiling, or desk options
This project is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0).
You are free to:
- ✅ Build - Manufacture units for personal use
- ✅ Modify - Adapt the design to your needs
- ✅ Share - Distribute your modifications (under same license)
- ✅ Non-commercial - Use in your home, share with friends
Commercial use requires a separate licensing agreement.
Commercial use includes:
- Manufacturing for sale or profit
- Integration into commercial products or services
- Providing as part of paid installation/support services
📧 Contact: @Soriarty or open an issue for commercial licensing inquiries.
Contributions are welcome! Whether it's hardware improvements, firmware enhancements, documentation, or bug reports - all help is appreciated.
Please read our Contribution Guidelines for detailed information on:
- How to contribute (hardware, firmware, enclosure, documentation)
- Development setup
- Pull request process
- Style guidelines
- Testing requirements
- Fork the repository
- Create a feature branch from
develop:git checkout develop git pull origin develop git checkout -b feature/amazing-improvement
- Make your changes following the guidelines
- Test thoroughly
- Commit using Conventional Commits format:
git commit -m "feat(sensor): add new sensor support" - Push to your fork and create PR to
develop
Workflow: We use Git Flow branching strategy with Conventional Commits and Semantic Versioning.
First time contributing? Check out our detailed guide or ask in Discussions!
- 📖 Wiki: User Documentation - Getting started, guides, tutorials
- Issues: GitHub Issues - Bug reports and feature requests
- Discussions: GitHub Discussions - General questions and community
- Contributing: Contribution Guidelines - How to contribute
- Technical Documentation:
- Author: @Soriarty
- Home Assistant Community: [Coming soon]
- OLIMEX - ESP32-POE board design foundation (included as git submodule in
hardware/reference/esp32-poe/) - ESPHome - Making ESP32 integration seamless
- Home Assistant - Open-source smart home platform
- Inspired by Aqara FP2 presence sensor design
Soriarty - @Soriarty
HaloSense was created to address the need for reliable, wired presence detection in professional smart home installations while remaining accessible to the DIY community.
This is a DIY electronics project. Build at your own risk. Always follow proper safety procedures when working with electronics and mains power (especially with PoE).
The authors are not responsible for any damage, injury, or issues arising from building or using this design.
This project was born from a simple need: reliable, wired presence detection for smart homes. While there are excellent wireless options available, the lack of PoE-capable, multi-sensor presence detectors led to the creation of HaloSense.
Built during a home renovation with smart home integration in mind, HaloSense aims to provide the flexibility and reliability that professional installations demand, while remaining accessible to the DIY community.
Star ⭐ this repo if you find it useful!
License: CC BY-NC-SA 4.0 | Created by @Soriarty | Made with ❤️ for the smart home community