Concepts and Terminology
To successfully install and configure this firmware, it is important to understand the underlying system design and the specific terminology used throughout this documentation.
đ Connectivity & Privacy:
This system is designed to be fully functional on a local Wi-Fi network. While it supports integrations like Home Assistant or other systems via MQTT/API, these are strictly optional. An active internet connection is not required for core operations.
The Primary Controller
The system requires at least one ESP32-based controller. This primary controller will connect and control the LEDs, provides the main web interface and handles optional interfaces such as MQTT or the HTTP-based API. The primary controller supports up to two wired sensors, either PIR or ToF. The above diagram shows two wired PIR sensors. See the Build Guide for additional wiring diagrams, including how to wire ToF sensors to the primary controller. When using wired sensors, this is the only controller needed but if two wired sensors are used, they must both be of the same type (PIR or ToF). This is unlike wireless sensors which can consist of different types.
For the purposes of this document, this will always be referred to as the âprimaryâ or âmainâ controller⊠even if it is the only controller in use.
Optional Wireless Sensor Controller
The primary controller can also be configured to receive state updates from one or more wireless sensors and forego the use of any locally-wired sensors. This allows sensors to be placed pretty much anywhere without concerns for wiring runs or length.
Naturally, since wireless sensors operate without the main firmware, they will each need their own controller. Firmware is provided for ESP32-based PIR or ToF sensors, and again, the build guide has complete wiring diagrams and parts for creating a PIR or ToF wireless sensor.
Additional options are also available when using wireless sensors. The next section of this guides covers sensor types and selection criteria in more detail.
Other Important Terminology
There are a few other important terms to understand⊠at least as far as this guide is concerned.
Firmware
This is the compilied code that gets installed on the ESP32 or other controller. For this project, the firmware is delivered as a .bin file included in a releaseâs assets. Note that you cannot directly install the source code (.ino) directly on an ESP board. It must be compilied into a binary .bin file using the Arduino IDE, PlatformIO or other compiler. This project includes separate firmware for the primary controller and for any independent wireless controllers. Note if you are building your system using wired sensors, only the primary controller firmware is needed.
Web Application:
Both version of the firmware (primary and sensor) contain embedded web servers and web applications. These are primarily used to configure the controller, but in the case of the primary controller, it is also used to specify LED colors and effects used for each sensor along with other options. But the web application is included as part of the firmware.
When this documentation refers to the âweb appâ, it does not mean a separate application that has to be installed on a computer, phone or tablet. You can always access the firmwareâs âweb appâ by just going to the IP address of the controller in a web browser of any device on the same WiFi network.