mash-sensor-tof-pc/README.md

# MaSH Sensor - ToF PC

**Time-of-Flight** based **people count sensor** to integrate with the **[MaSH Server](https://github.com/mgfcf/mash-server)**, with the goal to work in a smart home environment. Currently setup to directly communicate with a Philips Hue Bridge and control a single group of lights.

This is very much a work in progress, so every issue and/or pull request is welcome.

Feel free to join and talk on my little server: https://discord.gg/ftwwSdY9e5

## Structure

-   `src/` - All the python code.
    -   `src/sensors/` - Abstract interfaces and implementations for both the actual hardware sensor and the virtually created "people count" sensor.
        -   `src/sensors/people_counter.py` - The actual implementation of the people counter. More details further below.
    -   `src/services/` - Other things to communicate with. For now an interface for the Philips Hue Bridge to turn lights on and off.
    -   `src/statistics/` - Everything related to analysing the log file and creating fun evaluations.
    -   `src/timeloop/` - A copy of my fork of the python package with the same name. Had to implement a little feature it was missing and the original project doesn't accept pull requests.
    -   `src/*` - Example implementations and use cases for the people count sensor.
-   `images/` - Images used for documentation.
-   `log.txt` - A log file with a bunch of my data. Here as an example and to experiment with.

### How it works

The amazingly small and useful VL53L1X sensor is actually able to measure a whole array of distances, not just straight down. Utilizing this, it will alternate between two points - one in the direction of the "inside", the other in the opposite direction, the "outside".

If any of those measurements is returning a distance that is closer than a certain threshhold, it will considere this direction "triggered".

If someone moves into the field of view of the sensor, they will either trigger the inside or outside direction first (depending on the side they are coming from). They can then freely move below the sensor, triggering always at least one direction in consecutive measurements. When they leave, either the inside or outside direction will have been triggered last.

"Leaving" means, the sensor will have made two consecutive measurements (inside, then outside, or outside, then inside, since it is constantly switching between those two directions) without being triggered.

If outside was the initial trigger direction, and inside the last, no matter what happened in between, it will be considered as "someone walked into the room" (change of +1). And vice versa (walking out being a change of -1). If the same direction is initial and last trigger, it will be counted as a change of 0, thereby not affecting the count.

## Initial setup and use

### Required hardware

-   Some kind of device that can run python and connect to the required sensor (developed for **Raspberry Pi Zero W**)
-   **VL53L1X** sensor, I got: https://www.berrybase.de/vl53l1x-time-of-flight-tof-bewegungs-sensor-breakout
-   Philips Hue Bridge recommended, or anything else you want to control with this sensor

### Hardware setup

Most importantly, the sensor should be in the door frame, pointing down. The orientation of the sensor is also important, since you want it to increase the count for people walking into your room, and decrease the count for people walking out.

In the photos below you can see my current setup. The piece of cardboard is supposed to block sunlight from interfering with the sensor. Before the cardboard piece was attached, I had more issues with the sensor, especially in the morning, when sun was shining through a nearby window.

The piece of cardboard is on the side of my room, which might help you to orient the sensor properly.

<p align="left">
    <img height="200px" src="/images/door.png" />
    <br/>
    <img height="200px" src="/images/controller.jpeg" />
    <br/>
    <img height="200px" src="/images/sensor.jpeg" />
</p>

Sadly, due to my limited time, there is so far no proper, easy way of changing the direction of the sensor in software. It is on my todo list tho (see below) and please don't hesistate to open issue if you require a certain feature! I am more than happy to help and expand this project.

### Software setup

This will go through the required setup for `simple_hue_counter.py` and `smart_hue_counter.py`.

1. Clone the repository to your controller
2. Make sure to install everything required from the `requirements.txt`
3. Open your desired script (`simple_hue_counter.py` or `smart_hue_counter.py`) and edit the `hue_conf`

    - `bridge_ip`: Insert the local ip-address of your philips hue bridge here
    - `transition_time`: Supposed to be the duration of the light turning on and off, doesn't seem to work as expected tho. Feel free to play around with it.
    - `light_group`: Enter the name of the light group/room you want to switch on and off. Just use the human readable name you gave your group in the philips hue app.
    - `registered_file`: No need to change this.
    - If you are using the `smart_*`-script:

        - `ENABLE_MOTION_TRIGGERED_LIGHT`: Already turns on lights if someone is _in_ the door. If this is off, the light will only switch when you completely walked through the sensors field of view. Having it on thereby makes it switch on faster, which is especially desirable during the night.
        - `ENABLE_SCHEDULE_TRIGGERS`: When turned on, will setup time triggers for the `SCHEDULE` defined below, so that (when someone is in the room) the light will automatically switch to the current scene when the corresponding time is reached.
        - `SCHEDULE`: If left empty, lights will simply be turned on and off, reusing the previous color and brightness when they were turned off. If you want specific scenes to be turned on during different times of the day, you can define a Schedule here.

            ```python
            SCHEDULE: dict[time, str] = {
                time(8, 0): "Good Morning",
                time(18, 0): "Evening",
                time(22, 0): "Nightlight",
            }
            ```

            This schedule will use the scene "Good Morning" from 8am til 6pm, "Evening" from 6pm til 10pm and "Nightlight" from 10pm til 8am.

            The scene name is also just the human readable name from the philips hue app. If you renamed a scene, you might need to use the previous name.

4. Start your desired script for the first time. You need to press the pairing button on the philips hue bridge ideally in the first 30 seconds (the file referenced in `registered_file` should be created if successful)
5. Setup your script to automatically run when your controller powers on (I like to use supervisor to manage my autostart processes)

It should be working now, hopefully!

### Use

The initial count is 0.

If you walk in, it will increase the counter. If the counter is >0, the lights will turn (or stay) on.

If you walk out, it will decrease the counter. The counter does not go below 0. If the counter reaches 0, the lights will turn off, otherwise will stay on.

Everytime someone triggers the sensor, the current state of the lights is checked. If the count should be 0, but the lights were on, it will be adjusted to 1, before applying the corresponding count (-1 for walking out, +1 for walking in).

If the count should be >0, but the lights were off, it will be adjusted to 0, before applying the corresponding count.

This way you can correct the counter by simply turning the lights on and off via the app. I personally recommended to setup voice commands for ease of use with the personal assistant of your choosing.

A log is written with every event. Great for analysing wrong counts and fun statistics!

## Outlook

### ToDo

-   Implement support for multiple sensor (server/clients) to control more than one group/room
-   Energy-saving/Off mode (Only one light slighty turned on to keep track of current state) (How should power plugs be handled?)
-   Daylight Adjustment (E.g. No ceiling lights during daytime)
-   Save scene when turning off, to re-apply same scene when turning on (Because just turning lights on turns ALL lights on of that group)
-   Detect fast flickering of light state, indicating an issue, and disable the system for a few minutes
-   Simple software switch to change direction of sensor
-   Better project structure and objects
-   Proper handling and recognition of doors in the field of view
-   Packaging it up for ease of use in custom projects
-   Create implementation that can be used on energy-efficient microcontrollers like an esp
-   Try out other sensors like the VL53L3CX
-   Write proper hardware-guide

### Goal

Knowing how many people are in a room, is a really fun information. If at least one person is in a room, turn on the lights! If someone is listening to music alone in the room, and a second person enters the room, turn down the music for an easier conversation. If noone is in the room, lock the computer and put it to sleep after a while.

I personally think, this has a lot of potential for future home automation, and actually makes peoples life easier. (Not like voice controlled light switches, just making it more difficult) Simply using distance sensors reduces the privacy implications significantly, compared to using some kind of camera setup for counting people.

To actually be usable for a wider range of people, it needs to get more reliable, close to 100%. It ideally needs to be as reliable as an actual light switch.

This shall remain an open source, privacy in mind, smart home application. Usable home-wide, not just for a single room. Certainly no requirement for an external server.

Making it compatible with systems like homeassistant is definitely a good idea. Though I am actually planning to create my own little python framework for my personal needs, since homeassistant seems weirdly complicated to use to me and is missing some concepts like "room" or "person" that I would like to have.

Take what you need, go wild, and have fun.