From 1c65bacb261eca88f2ae5f89b7a96b4a37c21b37 Mon Sep 17 00:00:00 2001 From: "Joshua M. Boniface" Date: Wed, 6 Dec 2023 12:38:06 -0500 Subject: [PATCH] Update README information --- README.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 130 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 036605c..a28a821 100644 --- a/README.md +++ b/README.md @@ -11,17 +11,18 @@ as you want them. Assist feedback is provided by a single common-cathode RGB LED. No speakers or annoying TTS feedback here! With the optional 3D Printed case and a clear -diffuser insert, this LED can be turned into a sleek light bar on the bottom +diffuser cover, this LED can be turned into a sleek light bar on the bottom of the unit for quick and easy confirmation of voice actions. To Use: * Fill out a "secrets.yaml" for your environment. - * Install this ESPHome configuration to a compatible ESP32 devkit (V4). + * Install this ESPHome configuration to a compatible ESP32 devkit (below). * Install the ESP32 and sensors into the custom PCB. * [Optional] 3D Print our custom case. * Install the SuperSensor somewhere that makes sense. * Add the SuperSensor to HomeAssistant using the automatic name. + * Tune the SuperSensor values to your needs. Note: Once programmed, the output LED will flash continuously until connected to HomeAssistant, and a bit longer to establish if the wake word @@ -32,11 +33,131 @@ Note: Once programmed, the output LED will flash continuously until connected ## Parts List -* 1x ESP32 devkit -* 1x Common-cathod RGB LED -* 1x Resistor for the common-cathod RGB LED @ 3.3v input (~33-1000Ω, depending on desired brightness and LED) +* 1x ESP32 devkit (V4 38-pin, slim) +* 2x Common-cathod RGB LED +* 2x Resistor for the common-cathod RGB LED @ 3.3v input (~33-1000Ω, depending on desired brightness and LED) * 1x INMP441 MEMS microphone -* 1x BME280 temperature/humidity/pressure sensor (3.3v models) -* 1x VEML7700 light sensor -* 1x HLK-LD1115H-24G mmWave radar sensor -* 1x HC-SR501 (or similar) PIR sensor +* 1x BME680 temperature/humidity/pressure/gase sensor (3.3v models); BME280 or BMP280 can be subsistuted but with reduced fuctionality (comment/uncomment the appropriate blocks as needed) +* 1x TSL2591 light sensor +* 1x HLK-LD2410C mmWave radar sensor +* 1x SR602 PIR sensor +* 1x SuperSensor PCB board +* [Optional] 1x 3D Printed case +* [Optional] 1x 3D Printed diffuser cover + +## Configurable Options + +There are several UI-configurable options with the SuperSensor to help you +get the most out of the sensor for your particular usecase. + +### Light Threshold Control + +The SuperSensor features a "light presence" binary sensor based on the light +level reported by the TSL2591 sensor. This control defines the minimum lux +value from the sensor to be considered "presence". For instance, if you have +a room that is usually dark at 0-5 lux, but illuminated to 100 lux when a +(non-automated) light switch is turned on, you could set a threshold here +of say 30 lux: then, while the light is on, "light presence" is detected, +and when the light is off, "light presence" is cleared. Light presence can +be used standalone or as part of the integrated occupancy sensor (below). + +Valid range is 0 lux (always on) to 500 lux, in 5 lux increments. +Default value is 30 lux. + +### PIR Hold Time + +The SuperSensor uses an SR602 PIR sensor, which has a stock hold time of 2.5 +seconds. While this is configurable via a resistor, this is cumbersome. +Instead, the SuperSensor features a PIR Hold Time control, which allows you +to set how long you want a PIR trigger to be "held" on. Each new trigger of +the PIR resets the timer, so as long as a PIR event fires at least this +often, the "PIR presence" sensor will remain detected. + +Valid range is 0 seconds (match PIR) to 60 seconds, in 5 second increments. +Default value is 15 seconds. + +### Integrated Occupancy Sensor + +The SuperSensor features a fully integrated "occupancy" sensor, which can be +configured to provide exactly the sort of occupancy detection you may want +for your room. + +There are 7 options (plus "None"/disabled), with both "detect" and "clear" +handled separately: + +#### PIR + Radar + Light + +Occupancy is detected when all 3 sensors report detected, and occupancy is +cleared when any of the sensors report clearered. + +For detect, this provides the most "safety" against misfires, but requires +a normally-dark room with a non-automated light source and clear PIR +detection positioning. + +For clear, this option is probably not very useful as it is likely to clear +quite frequently from the PIR, but is provided for completeness. + +#### PIR + Radar + +Occupancy is detected when both sensors report detected, and occupancy is +cleared when either of the sensors report cleared. + +For detect, this provides good "safety" against PIR misfires without +needing a normally-dark room, though detection may be slightly delayed +from either sensor. + +For clear, this option is probably not very useful as it is likely to clear +quite frequently from the PIR, but is provided for completeness. + +#### PIR + Light + +Occupancy is detected when both sensors report detected, and occupancy is +cleared when either of the sensors report cleared. + +For detect, this provides some "safety" against PIR misfires, but requires +a normally-dark room with a non-automated light source and clear PIR +detection positioning. + +For clear, this option is probably not very useful as it is likely to clear +quite frequently from the PIR, but is provided for completeness. + +#### Radar + Light + +Occupancy is detected when both sensors report detected, and occupancy is +cleared when either of the sensors report cleared. + +For detect, this allows for radar detection while suppressing occupancy +without light, for insance in a hallway where one might not want a late +night bathroom visit to turn on the lights, or something to that effect. + +For clear, this option can provide a useful option to clear presence +quickly if the lights go out, while still providing Radar presence. + +#### PIR Only + +Occupancy is based entirely on the PIR sensor for both detect and clear. + +Prone to misfires, but otherwise a good option for quick detection and +clearance in a primarily-moving zone (e.g. hallway). + +#### Radar Only + +Occupancy is based entirely on the Radar sensor for both detect and clear. + +Useful for an area with no consistent motion or light level. + +#### Light Only + +Occupancy is based entirely on the Light sensor for both detect and clear. + +Useful for full dependence on an external light source. + +#### None + +Disable the functionality in either direction. + +For detect, no occupancy will ever fire. + +For clear, no states will clear occupancy; with any detect option, this +means that occupancy will be detected only once and never clear, which +is likely not useful.