Skip to content

Commit 8c97f71

Browse files
Lyr3xLyr3x
committed
Add docu
1 parent 0950cd9 commit 8c97f71

File tree

2 files changed

+105
-3
lines changed

2 files changed

+105
-3
lines changed

‎README.md

Lines changed: 78 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,94 @@
11
# RooDe
2+
23
People counter working with any smart home system which supports ESPHome and therefore Home Assistamt. All necessary entities are created automatically.
34

45

56
[![Roode community](https://img.shields.io/discord/879407995837087804.svg?label=Discord&logo=Discord&colorB=7289da&style=for-the-badge)](https://discord.gg/RK3KJeSy)
67

78

9+
![Roode](Roode.png)
10+
11+
## Algorithm
12+
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.
13+
The concept of path tracking is the detecion of a human:
14+
* In the first zone only
15+
* In both zones
16+
* In the second zone only
17+
* In no zone
18+
19+
That way we can ensure the direction of movement.
20+
21+
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.
22+
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.
23+
24+
However, the algorithm is very sensitive to the slightest modification of the ROI, regarding both its size and its positioning inside the grid.
25+
26+
ST Microelectronics define the values for the parameters as default like this:
27+
- `ROI_width = 8 //min 4`
28+
- `ROI_height = 16 //min 4`
29+
- `center = {167,231}`
30+
31+
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:
32+
33+
34+
35+
| 128 | 136 | 144 | 152 | 160 | 168 | 176 | 184 | 192 | 200 | 208 | 216 | 224 | 232 | 240 | 248 |
36+
| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
37+
| 129 | 137 | 145 | 153 | 161 | 169 | 177 | 185 | 193 | 201 | 209 | 217 | 225 | 233 | 241 | 249 |
38+
| 130 | 138 | 146 | 154 | 162 | 170 | 178 | 186 | 194 | 202 | 210 | 218 | 226 | 234 | 242 | 250 |
39+
| 131 | 139 | 146 | 155 | 163 | 171 | 179 | 187 | 195 | 203 | 211 | 219 | 227 | 235 | 243 | 251 |
40+
| 132 | 140 | 147 | 156 | 164 | 172 | 180 | 188 | 196 | 204 | 212 | 220 | 228 | 236 | 244 | 252 |
41+
| 133 | 141 | 148 | 157 | 165 | 173 | 181 | 189 | 197 | 205 | 213 | 221 | 229 | 237 | 245 | 253 |
42+
| 134 | 142 | 149 | 158 | 166 | 174 | 182 | 190 | 198 | 206 | 214 | 222 | 230 | 238 | 246 | 254 |
43+
| 135 | 143 | 150 | 159 | 167 | 175 | 183 | 191 | 199 | 207 | 215 | 223 | 231 | 239 | 247 | 255 |
44+
| 127 | 119 | 111 | 103 | 95 | 87 | 79 | 71 | 63 | 55 | 47 | 39 | 31 | 23 | 15 | 7 |
45+
| 126 | 118 | 110 | 102 | 94 | 86 | 78 | 70 | 62 | 54 | 46 | 38 | 30 | 22 | 14 | 6 |
46+
| 125 | 117 | 109 | 101 | 93 | 85 | 77 | 69 | 61 | 53 | 45 | 37 | 29 | 21 | 13 | 5 |
47+
| 124 | 116 | 108 | 100 | 92 | 84 | 76 | 68 | 60 | 52 | 44 | 36 | 28 | 20 | 12 | 4 |
48+
| 123 | 115 | 107 | 99 | 91 | 83 | 75 | 67 | 59 | 51 | 43 | 35 | 27 | 19 | 11 | 3 |
49+
| 122 | 114 | 106 | 98 | 90 | 82 | 74 | 66 | 58 | 50 | 42 | 34 | 26 | 18 | 10 | 2 |
50+
| 121 | 113 | 105 | 97 | 89 | 81 | 73 | 65 | 57 | 49 | 41 | 33 | 25 | 17 | 9 | 1 |
51+
| 120 | 112 | 104 | 96 | 88 | 80 | 72 | 64 | 56 | 48 | 40 | 32 | 24 | 16 | 8 | 0 |
52+
53+
54+
55+
56+
57+
#### Threshold distance
58+
59+
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.
60+
61+
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.
62+
63+
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 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 `threshold_percentage`
64+
65+
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`.
66+
67+
68+
69+
## Useful links
70+
71+
[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
872

973
## Hardware
1074
There will be a specific Hardware setup (recommended brands etc.) soon!
11-
* ESP8266 or ESP32
12-
* 1x VL53L1X
75+
* ESP8266 or ESP32 (Wemos D1 mini case will be available)
76+
* 1x VL53L1X (GY-53 and cheap chinese sensors)
1377
* Optional HC-SR501
1478
* Optional 128x32 OLED
1579
* Power Supply
1680
* Encolsure (see .stl files) - will be updated soon!
81+
Pins:
82+
#define SDA_PIN D2
83+
#define SCL_PIN D1
84+
85+
## Configuration
86+
### ESPHome
87+
Configue 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.
88+
89+
### Entry/Exit inverted:
90+
Set #define INVERT_DIRECTION or comment it out to invert the direction.
91+
1792

1893
## Configuration
1994
Be sure to configure your wifi credentials and adapt the Config.h to set everyhting to your needs.
@@ -65,4 +140,4 @@ Calibration v2 calibrates both zones individually (thanks to @andrea-fox).
65140
* CALIBRATION_VAL to 4000
66141
### Changelog v.0.9.4-release
67142
* Added standard deviation threhsold calculation
68-
* Removed constant THRESHOLD_X
143+
* Removed constant THRESHOLD_X

‎home_assistant.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
To make all functions of Roode work with home assistant you need to set up a few entities and automations.
2+
Roode has endpoints to set the count value, reset the counter to 0 and to recalibrate. Unfourtunately its not possible to expose buttons via ESPHome that do just that.
3+
4+
```
5+
# This automation script runs when a value is received via MQTT on retained topic: setTemperature
6+
# It sets the value slider on the GUI. This slides also had its own automation when the value is changed.
7+
- alias: "Set people slider"
8+
trigger:
9+
platform: mqtt
10+
topic: "people_counter/sensor/people_counter_people/state"
11+
action:
12+
service: input_number.set_value
13+
target:
14+
entity_id: input_number.set_people
15+
data:
16+
value: "{{ trigger.payload }}"
17+
- alias: "People slider moved"
18+
trigger:
19+
platform: state
20+
entity_id: input_number.set_people
21+
action:
22+
service: mqtt.publish
23+
data:
24+
topic: "people_counter/sensor/people/set"
25+
retain: true
26+
payload: "{{ states('input_number.set_people') | int }}"
27+
```

0 commit comments

Comments
 (0)