Motion activated surveillance videos via telegram
This telegram security bot is designed to run on a Raspberry Pi zero W with a PiCamera and a RCWL-0516 radar motion sensor.
When motion is detected, it notifies authorized users via textmessage and starts the videorecording. When no further movements can be detected, the recording is stopped and sent. To be somewhat sure that no unauthorized users get access to these recordings, the bot allows basic user administration.
- Get security camera footage anywhere via telegram
- Create activation tokens to give other users access
- Manage users
- Pause and resume surveillance
Whether you are using an already set up Pi or a new one, make sure that you activate the camera and if needed ssh in the raspi-config.
git clone https://github.com/ningelsohn/telegram-security-bot.git
If you're new to telegram-bots, you can find an introduction by telegram here.
get your api-token and insert it in the config.py file along with a self-selected first activation token for you, the owner.
Once the bot is live, you will be able to register youself with that owner-token and take control,
so that no unauthorized persons have access to the surveillance videos.
You can now choose how to proceed. The script setup should be the faster and easier option.
If you dont want to use venv or a systemd service you can jump to the manual setup.
sudo telegram-security-bot/install.shWhat does this script do?
- Setting up virtual python environment and installing dependencies
- Installing MP4Box for .h264-to-.mp4 converting
- Adjusting the .service-file according to the app-location
- Installing and activating systemd service (stars the app automatically)
Check service status
systemctl status app.serviceIf no errors occured, you should now be able to interact with the bot.
Navigate into the project directory
cd {...}/telegram-security-botOptional: Install and activate venv
python3 -m pip install virtualenv
python3 -m virtualenv venv
source venv/bin/activateInstall python dependencies
python3 -m pip install -r requirements.txtInstall MP4Box
sudo apt-get install gpac Why?
PiCamera is capturing videos in h264-encoding. While this is no problem for the usage on the pi, MP4 is a more common coding and has caused less compatibility problems. MP4Box is used to convert .h264 videos to .mp4.
Start the appllication:
python3 -m app.pyIf you decide to set up the systemd service on your own, make sure to replace both placeholders.
- Raspberry Pi zero W
- Raspberry Pi (zero) camera
- RCWL-0516 radar-sensor
Make sure that the Pi has permanent access to the internet.
Even though the Pi can run on a battery, a power supply is clearly preferable since the video recordings increase the power consumption significantly.
The camera is simply plugged in with the enclosed ribbon cable. If you're buying a camera for this project, keep in mind that Pi Zero camera cables dont fit the bigger Pi's and vice versa. The radar-sensor in my case has five pins which are soldered onto the Pi as follows:
| RCWL-0516 Pin | Raspberry Pi Zero W |
|---|---|
| 3V3 | |
| GND | PIN 6 (GROUND) |
| OUT | PIN 7 (GPIO 4) |
| VIN | PIN 2 (5V) |
| CDS |
This may vary, so make sure to look into the pinout. If your want to use another GPIO Pin, make sure to adjust the config.py accordingly. If you are interested in more details about the RCWL-0516, you should check this out.
In my case the sensor was misfiring a lot when it was pressed tightly together with the Pi.
Keeping a little distance has solved the problem.
Now that your bot is up and runnning, you should register yourself as the owner as long as the OWNER_ACTIVATION_TOKEN is valid.
The following commands are documented with a specific format. The first section is the name of the command. This will trigger the handler for this specific command. The second section is a parameter for this command. The majority of the commands don't require parameters. The last section specifies the role which is required to call this command. The roles are strictly ordered and each role has the permissions of the respective subordinate roles.
/command <PARAM_NAME> *ROLE
Use the /activate command to register as a new user.
The token determines your authorizations.
/activate <TOKEN> *OPEN_ROLE
Usually a token is only valid for one day, so register promptly after receiving one.
Example: /activate HG3TL4NZE9M7
Use the /leave command to unsubscribe. As the owner, you cant leave.
If you change your mind, you will need a new activation token.
/leave
Usually a token is only valid for one day, so register promptly after receiving one.
Example: /activate HG3TL4NZE9M7
Use the /users command to get a list of all registered users.
/users *MOD_ROLE
Example: /users
Use the /banned command to get a list of all banned users.
/banned *MOD_ROLE
Example: /banned
Use the /token command to generate new tokens.
This is the only way to give other users access to the surveillance.
/token <ROLE_OPTION> *ADMIN_ROLE
This request will yields a two-step query to determine the role and validity period. You can only create tokens for roles that have less authority than your own. Take a look into the role table for a rough feature overview.
Example: /token
Use the /cleartokens command to remove all pending tokens.
/cleartokens *ADMIN_ROLE
Currently this is the only option of invalidating tokens.
Example: /cleartokens
Use the /pause command to pause the motion activated surveillance.
/pause *ADMIN_ROLE
If at the moment of pausing the camera is active, the recording will continue and you will receive it as usual.
Example: /pause
Use the /unpause command to unpause motion activated surveillance..
/unpause *ADMIN_ROLE
If at the moment of unpausing a previously detected motion is still ongoing, this will not trigger a new recording. Only after the motion stopped the surveillance is active again.
Example: /unpause
Use the /ban command to ban an active user.
/ban *ADMIN_ROLE
This will yield a query in which you can select the user to be banned. Only users with less powerful roles are shown.
Example: /ban
Use the /unban command to unban an banned user.
/ban *ADMIN_ROLE
This will yield a query in which you can select the user to be unbanned. Only users with less powerful roles are shown.
Example: /unban
Use the /clear command to clear all registered users and currently pending tokens.
/clear *OWNER_ROLE
Example: /clear
| role level | role name | role | features |
|---|---|---|---|
| 4 | OWNER_ROLE | owner | text & video notifications, create new tokens (-a, -m, -s) , manage users |
| 3 | ADMIN_ROLE | admin | text & video notifications, create new tokens (-m, -s) , manage users |
| 2 | MOD_ROLE | mod | text notifications, manage users |
| 1 | SUB_ROLE | subscriber | text notifications |
| 0 | OPEN_ROLE | activate token |