Motion activated surveillance videos via telegram

• Introduction
• Features
• Installation
  • Raspberry Pi setup
  • Clone Project
  • Create your Telegram-Bot
  • What are you up to?
  • Script setup
  • Manual setup
• Hardware setup
  • Required parts
  • Wiring
• Usage
  • Commands
    • Example
    • /activate - Activate token
    • /leave - Leave
    • /users - Show registered users
    • /banned - Show banned users
    • /token - Generate token
    • /cleartokens Clear tokens
    • /pause - Pause
    • /unpause - Unpause
    • /ban - Ban user
    • /unban - Unban user
    • /clear - Clear all
  • Roles

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.sh

Check service status

systemctl status app.service

If no errors occured, you should now be able to interact with the bot.

Navigate into the project directory

cd {...}/telegram-security-bot

Optional: Install and activate venv

python3 -m pip install virtualenv
python3 -m virtualenv venv
source venv/bin/activate

Install python dependencies

python3 -m pip install -r requirements.txt

Install MP4Box

sudo apt-get install gpac 

Start the appllication:

python3 -m app.py

If 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:

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