Merge pull request #48 from Lyr3x/dev

v1.3

.github/workflows/main.yml

@@ -14,7 +14,12 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -U esphome
+      - name: Validate ESP8266 Config
+        run: esphome config peopleCounter.yaml
       - name: Build ESP8266
         run: esphome compile peopleCounter.yaml
+      - name: Validate ESP32 Config
+        run: esphome config peopleCounter32.yaml
       - name: Build ESP32
         run: esphome compile peopleCounter32.yaml
+

.gitignore

@@ -4,13 +4,18 @@
 .vscode/.browse.c_cpp.db*
 .vscode/c_cpp_properties.json
 .vscode/launch.json
-.vscode/
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
 lib/Configuration/Config.h
-roode/
-roode32/
-roode_dev/
+/roode/
+/roode32/
+/roode_dev/
+roode8266
 .esphome/
+.pyc
 .DS_Store
 common/wifi.yaml
 common/secrets.yaml
-secrets.yaml
+secrets.yaml
+__pycache__

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+	"recommendations": [
+		"esphome.esphome-vscode",
+        "ms-vscode.cpptools"
+	]
+}

.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+    "files.associations": {
+        "*.yaml": "esphome",
+        "__split_buffer": "cpp",
+        "__tree": "cpp",
+        "algorithm": "cpp",
+        "deque": "cpp",
+        "functional": "cpp",
+        "iterator": "cpp",
+        "locale": "cpp",
+        "regex": "cpp",
+        "string": "cpp",
+        "unordered_map": "cpp",
+        "unordered_set": "cpp",
+        "vector": "cpp"
+    }
+}

README.md

@@ -2,31 +2,162 @@
 
 People counter working with any smart home system which supports ESPHome and therefore Home Assistant. All necessary entities are created automatically.
 
-
 [![Roode community](https://img.shields.io/discord/879407995837087804.svg?label=Discord&logo=Discord&colorB=7289da&style=for-the-badge)](https://discord.gg/RK3KJeSy)
 
+## Wiring
+The sensors from Pololu, Adafruit and the GY-53 can also be connected to the 5v pin (VIN) as they have an voltage regulator.
+
+If you use a GY-53 you need to connect GND the PS (Ps=0) pin. 
+
+Ps=1 (default): Serial port UART mode, Pin3 is TX, Pin4 is RX, TTL level, PWM output works.
+Ps=0 (when connected to GND): In the IIC mode, the user can operate the chip by himself. The module owns the MCU and does not operate the chip. The PWM output does not work.
+
+### ESP32
+
+```
+                    ESP32   VL53L1X board
+-------------------------   -------------
+                      3V3 - VIN
+                      GND - GND
+     SDA (pin 42, GPIO21) - SDA
+     SCL (pin 39, GPIO22) - SCL
+```
+
+### ESP8266
+```
+                  ESP8266   VL53L1X board
+-------------------------   -------------
+                      3V3 - VIN
+                      GND - GND
+              D2 (GPIO 4) - SDA
+              D1 (GPIO 5) - SCL
+```
+## Configuration
 
-![Roode](Roode.png)
+Roode is provided as an external_component which means it is easy to setup in any ESPHome sensor configuration file.
+
+Example configuration
+
+```
+roode:
+  id: roode_platform
+  address: 0x29
+  update_interval: 100ms
+  calibration: true
+  roi_height: 16
+  roi_width: 6
+  threshold_percentage: 80
+  roi_calibration: false
+  invert_direction: true
+  restore_values: true
+```
+
+### Configuration variables
+
+- **address (Optional, integer)**: The I²C address of the sensor. Defaults to `0x29`.
+- **update_interval (Optional, Time)**: The interval to check the sensor. Defaults to `100ms`.
+- **roi_height (Optional, int)**: The height of the ROI zones. Min: `4` Max: `16`. Defaults to `16`.
+- **roi_width (Optional, int)**: The height of the ROI zones. Min: `4` Max: `16`. Defaults to `6`.
+- **max_threshold_percentage (Optional, int)**: The maxium threshold in % which needs to be reached to detect a person. Min: `50` Max: `100`. Defaults to `85`.
+- **min_threshold_percentage (Optional, int)**: The minimum threshold in % which needs to be reached to detect a person. Min: `0` Max: `100`. Defaults to `0`.
+- **calibration (Optional, bool)**: Enables automatic zone calibration (experimental). Defaults to `true`.
+- **roi_calibration (Optional, bool)**: Enables automatic ROI calibration (experimental). Defaults to `false`.
+- **invert_direction (Optional, bool)**: Inverts the counting direction. Defaults to `false`.
+- **restore_values (Optional, bool)**: Enables the restoration of the last count, after a reboot occurs. Defaults to `false`.
+- **advised_sensor_orientation(Optional, bool)**: Inverts the detection orientation of the sensor. Defaults to `true`.
+
+### Sensor
+
+Example Sensor setup to use all available features:
+
+```
+binary_sensor:
+  - platform: status
+    name: $friendly_name Status
+  - platform: roode
+    presence_sensor:
+      name: $friendly_name presence
+
+sensor:
+  - platform: roode
+    id: hallway
+    people_counter_sensor:
+      id: peopleCounter
+      name: $friendly_name people counter
+    distance_sensor:
+      name: $friendly_name distance
+      filters:
+        - delta: 100.0
+    threshold_zone0:
+      name: $friendly_name Zone 0
+    threshold_zone1:
+      name: $friendly_name Zone 1
+    roi_height:
+      name: $friendly_name ROI height
+    roi_width:
+      name: $friendly_name ROI width
+
+  - platform: wifi_signal
+    name: $friendly_name RSSI
+    update_interval: 60s
+
+  - platform: uptime
+    name: Uptime Sensor
+    id: uptime_sensor
+    update_interval: 120s
+    internal: true
+    on_raw_value:
+      then:
+        - text_sensor.template.publish:
+            id: uptime_human
+            state: !lambda |-
+              int seconds = round(id(uptime_sensor).raw_state);
+              int days = seconds / (24 * 3600);
+              seconds = seconds % (24 * 3600);
+              int hours = seconds / 3600;
+              seconds = seconds % 3600;
+              int minutes = seconds /  60;
+              seconds = seconds % 60;
+              return (
+                (days ? String(days) + "d " : "") +
+                (hours ? String(hours) + "h " : "") +
+                (minutes ? String(minutes) + "m " : "") +
+                (String(seconds) + "s")
+              ).c_str();
+
+text_sensor:
+  - platform: roode
+    version:
+      name: $friendly_name version
+  - platform: roode
+    entry_exit_event:
+      name: $friendly_name last direction
+
+  - platform: template
+    name: $friendly_name Uptime Human Readable
+    id: uptime_human
+    icon: mdi:clock-start
+```
 
 ## Algorithm
-The implemented Algorithm is an improved version of my own implementation which checks the direction of a movement through two defined zones. ST implemented a nice and efficient way to track the path from one to the other direction. I migrated the algorithm with some changes into the Roode project. 
-The concept of path tracking is the detection of a human:
-* In the first zone only
-* In both zones 
-* In the second zone only
-* In no zone
+
+The implemented Algorithm is an improved version of my own implementation which checks the direction of a movement through two defined zones. ST implemented a nice and efficient way to track the path from one to the other direction. I migrated the algorigthm with some changes into the Roode project.
+The concept of path tracking is the detecion of a human:
+
+- In the first zone only
+- In both zones
+- In the second zone only
+- In no zone
+
 
 That way we can ensure the direction of movement.
 
 The sensor creates a 16x16 grid and the final distance is computed by taking the average of the distance of the values of the grid.
-We are defining two different Region of Interest (ROI) inside this grid. Then the sensor will measure the two distances in the two zones and will detect any presence and tracks the path to receive the direction. 
+We are defining two different Region of Interest (ROI) inside this grid. Then the sensor will measure the two distances in the two zones and will detect any presence and tracks the path to receive the direction.
 
 However, the algorithm is very sensitive to the slightest modification of the ROI, regarding both its size and its positioning inside the grid.
 
 ST Microelectronics define the values for the parameters as default like this:
-- `ROI_width = 8 //min 4`
-- `ROI_height = 16 //min 4`
-- `center = {167,231}`
 
 The center of the ROI you set is based on the table below and the optical center has to be set as the pad above and to the right of your exact center:
 
@@ -37,6 +168,7 @@ ST user manual UM2555 explains ROI selection in detail, so we recommend
 reading that document carefully. Here is a table of SPAD locations from
 UM2555 (199 is the default/center):
 
+```
 128,136,144,152,160,168,176,184,  192,200,208,216,224,232,240,248
 129,137,145,153,161,169,177,185,  193,201,209,217,225,233,241,249
 130,138,146,154,162,170,178,186,  194,202,210,218,226,234,242,250
@@ -54,11 +186,13 @@ UM2555 (199 is the default/center):
 122,114,106, 98, 90, 82, 74, 66,   58, 50, 42, 34, 26, 18, 10,  2
 121,113,105, 97, 89, 81, 73, 65,   57, 49, 41, 33, 25, 17,  9,  1
 120,112,104, 96, 88, 80, 72, 64,   56, 48, 40, 32, 24, 16,  8,  0 <- Pin 1
+```
 
 This table is oriented as if looking into the front of the sensor (or top of
 the chip). SPAD 0 is closest to pin 1 of the VL53L1X, which is the corner
 closest to the VDD pin on the Pololu VL53L1X carrier board:
 
+```
   +--------------+
   |             O| GPIO1
   |              |
@@ -74,99 +208,48 @@ closest to the VDD pin on the Pololu VL53L1X carrier board:
   |              |
   |             O| VDD
   +--------------+
+```
 
 However, note that the lens inside the VL53L1X inverts the image it sees
 (like the way a camera works). So for example, to shift the sensor's FOV to
 sense objects toward the upper left, you should pick a center SPAD in the
 lower right.
 
-
-
-
 #### Threshold distance
 
 Another crucial choice is the one corresponding to the threshold. Indeed a movement is detected whenever the distance read by the sensor is below this value. The code contains a vector as threshold, as one (as myself) might need a different threshold for each zone.
 
-The SparkFun library also supports more formats for the threshold: for example one can set that a movement is detected whenever the distance is between two values. However, more information for the interested reader can be found on the corresponding page.
-
-With the updated code (however only for esp32 at the moment) the threshold is automatically calculated by the sensor. To do so it is necessary to position the sensor and, after turning it on, wait for 10 seconds without passing under it. After this time, the average of the measures for each zone will be computed and the threshold for each ROI will correspond to 80% of the average value. Also the value of 80% can be modified in the code, by editing the variable `threshold_percentage`
+The threshold is automatically calculated by the sensor. To do so it is necessary to position the sensor and, after turning it on, wait for 10 seconds without passing under it. After this time, the average of the measures for each zone will be computed and the thereshold for each ROI will correspond to 80% of the average value. Also the value of 80% can be modified in the code, by editing the variable `max_threshold_percentage` and `min_threshold_percentage`.
 
-The calibration of the threshold can also be triggered by a MQTT message. An example for doing so is in the file `integration_with_home_assistant.md`.
 
+If you install the sensor e.g 20cm over a door you dont want to count the door open and closing. In this case you should set the `min_threshold_percentage` to about `10`.
 
+Example:
 
-## Useful links
+```
+Mounting height:    2200mm
+Door height:        2000mm
+Person height:      1800mm
+max_threshold_percentage: 85% = 1760
+min_threshold_percentage: 10% = 200
 
-[SparkFun library guide](https://learn.sparkfun.com/tutorials/qwiic-distance-sensor-vl53l1x-hookup-guide/all) with more information about the functions used in the code
+All distances smaller then 200mm and greater then 17600mm will be ignored.
+```
 
 ## Hardware
+
 There will be a specific Hardware setup (recommended brands etc.) soon!
-* ESP8266 or ESP32 (Wemos D1 mini case will be available)
-* 1x VL53L1X (GY-53 and cheap chinese sensors)
-* Optional HC-SR501
-* Optional 128x32 OLED
-* Power Supply
-* Enclosure (see .stl files) - will be updated soon!
-Pins:
-SDA_PIN D2 or 21 (ESP32)
-SCL_PIN D1 or 22 (ESP32)
 
+- ESP8266 or ESP32 (Wemos D1 mini case will be available)
+- 1x VL53L1X (Pololu, GY-53 and cheap chinese sensors)
+- Power Supply
+- Encolsure (see .stl files) - will be updated soon!
+  Pins:
+  SDA_PIN 4 or 21 (ESP32)
+  SCL_PIN 5 or 22 (ESP32)
+
 ## Configuration
-### ESPHome
-Configure at least the secrets.yaml with your wifi SSID and password to connect. Check the peopleCounter.yaml to adapt the exposed sensors to your needs.
-
-### Entry/Exit inverted:
-Set INVERT_DIRECTION to true or false to invert the direction.
 
+### ESPHome
 
-## Configuration
-Be sure to configure your wifi credentials and adapt the global variables to set everything to your needs.
-The most important config part is the calibration mode. You have two different calibration modes available:
-Calibration v1 calibrates the distance for one zone and calculates the standard deviation and uses that value for both zones. 
-Calibration v2 calibrates both zones individually (thanks to @andrea-fox). 
-
-## Changelog
-### Changelog v1.0
-#### Additions and Breaking Changes
-* ESPHome (thanks to @diplix)
-* Removes legacy support which includes
-   * Arduino platform
-   * MySensors platform
-   * **Non** VL53L1X-Sensors
-* VL531L1X TOF Sensor with configurable ROI zones for one-sensor-solution
-* Counting people entering and leaving a room with path tracking for improved accuracy
-* Sensor threshold calibration for each zone
-* Receiving commands from the the controller e.g softreset
-* OLED support (coming in 1.1)
-* Sleep mode with Motion Sensor support (coming in 1.1)
-* Firmware upgrades over WebUI (esphome)
-
-
-### Changelog v0.9.6
-#### Additions
-* added full VL53L0X support
-* Added OLED brightness config option
-* Updated to [email protected]
-#### Bugfixes and other changes
-* Measuring speed improvements 
-* Fixed receiving and sending message issues
-* General bug fixes and improvements
-* Changed default PA_LEVEL to HIGH
-
-### Changelog v0.9.5
-* Added VL53L0X support
-    * Using the Pololu VL53XXX Library
-* Huge Code refactor
-
-### Changelog v0.9.4-alpha2:
-* added incomplete push button support
-    * There is a need of 2 spare interrupt PINS
-    * May be working with PinChangeInterrupt library
-* minor bugfixes
-* rename send() function and changed signature
-### Changelog v0.9.4-beta:
-* changed IR-calibration hardcoded value to THRESHOLD_X 
-* CALIBRATION_VAL to 4000
-### Changelog v.0.9.4-release
-* Added standard deviation threshold calculation
-* Removed constant THRESHOLD_X
+Configue at least the secrets.yaml with your wifi SSID and password to connect. Check the peopleCounter.yaml or peopleCounter32.yaml to adapt the exposed sensors to your needs.