Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mateusz-szczyrzyca/pir-motion-sensor

Rust library to support digital PIR and microwave motion sensors for Raspberry Pi and similar platform
https://github.com/mateusz-szczyrzyca/pir-motion-sensor

alarm-system hc-sr501 iot motion-detection motion-sensor raspberry-pi rust rust-library sensor smart-home

Last synced: 11 days ago
JSON representation

Rust library to support digital PIR and microwave motion sensors for Raspberry Pi and similar platform

Awesome Lists containing this project

README 

        
## pir-motion-sensor



Rust library to interact mainly with PIR motion sensors on Raspberry Pi platform. This lib was tested mainly on HC-SR501 motion sensor on Raspberry Pi 400 and Raspberry Pi 4B and it's widely used at my appartment and at my family's house - for smart alarm purposes (rest code will be published) and some in-house activies like turning on/off various devices based on motion detection.



 



The library leverages the tokio runtime and supports many sensors at the same time (I tested 20 at the same time) with low resource usage which is important, especially for older version of Raspberry Pi or Pi Zero versions.



 



## Why this library?



HC-SR501 PIR is very cheap and widely available an infrared motion sensor and it's very capable to various project based on arduino/raspberry/stm32, etc. 



However, because it's very cheap, it can detects "noise" from time to time, which means detection happens when there are no real motion within it's detection range - this is a false positive detection.



To eliminate this problem I created this simple library which allows to initialize this sensor with various parameters that they changes it's detection characteristic. The library, based on sensor configuration, can "ignore" these false detections and help make this sensors very reliable.



HC-SR501 PIR is not probably the only one infrared sensor which can be supported by the library - if you tested with another motion sensor please let me know. 



Digital microwave sensor like DFRobot SEN0192 is also supported, but keep in mind that SEN0192 sets from `High` to `Low` state once detection happens, so you have to [simply invert this signal by a proper transistor in your circuit to take advantage of this library](https://en.wikipedia.org/wiki/Inverter_(logic_gate)). Currently I have no plan to implement alternative logic for such sensors.



 



## Tested devices



Raspberry Pis:



- Raspberry Pi 4B 4 and 8 GB RAM - Raspbian GNU/Linux 11 (bullseye)

- Raspberry Pi 400 4 GB RAM - Raspbian GNU/Linux 11 (bullseye)

- Raspberry Pi 5 8 GB RAM - Raspbian GNU/Linux 12 (bookworm) 64bit



Tested motion sensors:



- HC-SR501 PIR (infrared)

- HC-SR505 (infrared - basic support as you can't change factory values of this simple sensor)

- DFRobot SEN0192 (microwave)



 



## Prerequsities



Use this reference manual for HC-SR501 PIR: https://lastminuteengineers.com/pir-sensor-arduino-tutorial/



Based on this manual, you should:



- set Sensitivity Adjustment yellow screw to longest range possible

- set Time-Delay Adjustment yellow screw to shortest time possible

- set Trigger Selection Jumper to Multiple Trigger Mode, by default it' probably set to Single Trigger



All of above settings can be programmatically changed by this library, so you won't need to touch jumper and screws again after this operation.



If you are not sure if you did it correctly - attach your sensor to VCC (5V), GND of your raspberry, and simple LED diode with **resistor** (betwen 1-10 kΩ) to OUT signal from the sensor and based on LED check how this sensor work after these adjustments. Be aware, that sensors sets ~5V on it's OUT PIN, when it detects motion, which is it's high state.



 



## Different model of motion sensor



If you have a different model of PIR motion sensor (or microwave sensor) which is purely digital (only sets it's pin signal to high state when it detects motion), then this library should also be suitable for it.



 



## How it works



In this instruction, there is a term `valid detection` - this is a detection which is classified as *valid* by this library - which may be not the same as OUT pin state of the sensor - everything depends on your configuration.



In other words: depends on sensor configuration, there can be many detections made by sensor (here defined as setting it's OUT pin at high state), but it does not mean, there will be single `valid detection` classified.



 



## Configuration



To init your sensor, consider the following parameters:



- GPIO PIN number (obvious staff), not required for tests, see `tests/valid_detections.rs` for more information.



- `sensor refresh rate`

  This isn't a refresh rate for a sensor itself, but the refresh rate for loop reading sensor PIN state. Shorter time allows

  to read data from sensor more often, thus it leads to better "refresh rate" of sensors itself, but may impose sligtly higher system load (it may matters when you have many sensors and RPi 2/3 or Zero).



  Higher values of this parameter may lead to "miss" some fast detections.



- `motion time period`

  It's a time limit which app classifies `valid detection`. If this period is shorter, it means it will be "harder" to detect motion

  within specified time period. 



- `minimal triggering number`

  When a sensor detects motion (or something similar) it sets it's OUT pin to the high state. If you make initial adjustment correctly, this can happen couple times per second and that's fine. This setting is a number of such high state sets which is required within `motion time period` to classify single `valid detection`. This option is especially useful for excluding "noise" detections if >1



To conclude these parameters shortly: based on `sensor refresh rate` time, the library periodically reads state of sensor OUT pin. If there is a detection (here defined as the high state on sensor signal line), the library will try to count up these high states up to `minimal triggering number` within `motion time period` time. If `minimal triggering number` within `motion time period` is reached, then we got `valid detection`.



Setting these parameters allows you to decide how sensitive and accurate is your sensor. Because "noise" detections are usually very short hence using this library you can effectively get rid of them if your settings are not too sensitive (good tested values: `sensor_refresh_rate > 100`, `motion_time_period < 1000`, `minimal_triggering_number > 2`). Feel free to experiment with your own

values.



Keep in mind that these settings can affect each other, for instance: a very short `sensor_refresh_rate` can be reduced by higher values of `motion_time_period` and `minimal_triggering_number`



 

## Using in your project



Please see examples in `examples/` directory



 

## Contributions



Contributions are highly welcomed. 



There are unit tests for this library which can be run by 



`cargo test -- --nocapture`



If you contribute don't forget to add test cases for your changes.



 

## TODO



Soon.