Raspberry Pi intercom front door automation for recognising doorbells and creating photos.
Notification via your own privat Telegram chat channel.
Also opening the front door via the private Telegram chat channel.
Furthermore, a separate website & REST API is offered to open the front door.
It is not recommended to make this website accessible on the Internet!
Please use a VPN tunnel to reach the website or REST API.
It supports Blink camera's and my PiCam_API project.
Door opening authorization is handled by timebased one time passwords.
The following wiring of the circuit is based on a BTIcino intercom system, but can also be connected to other systems.

📚 View on Github Pages

📚 API Docu on Github Pages

• Front-door intercom automation
  • Short description
  • Long description
  • Features advantage comparision FDIA, Blink, Ring and PiCamAPI
  • Demo
  • Outlook/Ideas
    • Plan
    • Ideas
  • Get started
    • Requirements
    • Code tree structure
    • Installation
    • Helper tools
      • Encrypt and decrypt a password with base32 for totp
      • get a OTP password or verify a OTP via cli
    • System service setup
    • Configuration - config files
    • config.yaml - config_template.yaml
    • blink_config.json
    • Setup OTP
  • Cameras
    • Blink Cameras
    • Raspberry Pi Camera Project PiCam_API
  • Telegram
    • Telegram setup
    • Telegram receiving message commands and interactions
  • Mobile Setup
    • Mobile Apps
    • Setup recommended OTP in your mobile phone
    • Mobile usage
    • Mobile IOS Door Open App
    • How to use Apple IOS Shortcuts App to automate door opening
  • Web UI & REST-API usage
  • Hardware Ciruit
    • required HW parts
      • Door bell detection board
      • Door opener board with relais:
    • BTICino CT20/51 Intercom plans
    • Dor bell ring plan
    • BTICino CT20/51 wiring pictures
    • Door open summer SaintSmart relay wiring pictures:
  • Help
    • Debugging
    • Hints
    • How to run unit-tests
    • GiHub actions pipelines
  • ChangeLog
  • Previous Python Version releases
  • Author info
  • License
  • Contribution

Starting point was an article Überallkingel at heise.de.
This front door intercom system extends any standard front door intercom system,
which are not connected to the Internet or ready for it. The project offers the following functionality:

• Front door bell detection.
• Notification via private Telegram channel PyTelegramBotAPI library
• Photo creation and telegram sending on doorbell ringing.
• Front door opening via time-based one-time password PyOTP library
• Use of Blink cameras with BlinkPy library
• Use of my Raspberry PI camera Project PiCam_API Project.
• Day / night detection to select the appropriate camera if several are used simultaneously via astral library
• Blink camera multi factory authentication setup via telegram chat message if Blink requires this.
• Blink camera or PiCamera photo creation and sending on Telegram message request.
• Automatic camera selection between Blink or PiCam_APi possible.
• Fallback camera selection if one fails.
• Internal Flask website to open the front door with the browser using a time-based one-time password.
• Internal Flask REST-API to open the front door (via time-based one-time password) for integration into other projects / solutions / automations.

-> short Telegram usage video will follow.
-> short video WebUi usage video will follow.

• fix codecov
• extend docu for RPi.GPIO access with normal user
• create docu for german users with camera snapshot GDPR hint at the front door
• extend docu with pcb wiring layout
• create docu IOS ShortCut App with aotmatic door opening and GeoFencing
• create demo videos
• create docu OTP App
• Same solution is in development as JAVA Spring Boot app too.
• Also a IOS Swift App, which makes telegram app and OTP obsolete for opening the door.
  It's actually a POC will be published soon.
• Next it's planned to extend the Web-UI with more features (like show snapshots and other things)

• add docker container build, image at GHCR and support via docker-compose.yaml
• Blink door bell notification
• Integrate Ring Cameras(video Doorbell too) (depends on lack of hardware - donation welcome - or temporary provision for development)
• Further it's planed to integrate door opening in Amazon Alexa as ProofOfConcept.
• Integration offering in HomeAssistant
• Support Google / Microsoft Authentication App with their format

Hardware:

• Raspberry PI B+ or above
• Blink Camera oder Pi Zero with PiCam_API Project installed
• Front door intercom like BTIcino

Software:

• Python 3.10 or above
• pip
• git
• Rasbian oder Ubuntu on Raspberry Pi

.
├── bot                   # Telegram modul classes for receiveing and sending
├── camera                # Camera module 
├── config                # Config module, enum and data classes
├── docs                  # Further documentation
│   ├── _source           # Documentation source dir for build docu page
│   │   └── _static        # static docu images
│   ├── telegram_bot_setup.md     # Telegram bot setup how to
│   └── pull_request_template.md  # Pull request template
├── door                  # Door module classes for opening or bell detection  
├── test                  # Unit tests
├── tools                 # CLI Helper tools
│   ├── encrypt_decrypt_password_with_base32.py   # Encrypt or decrypt with base32 input password 
│   └── totp_helper_cli.py                        # create or verify a TOTP from config file 
└── web                   # Flask Webpage & REST-API modul class
    ├── static            # Static web page icon files for favicons
    └── templates         # Served and rendered web pages
fdia.py                   # Main program code
fdia.service              # Linux systemd service template file
requirements.txt          # Depend lib to install via pip
config_template.yaml      # Template config file
Makefile                  # make for build html docs - github pages 
README.md                 # This readme
LICENSE                   # This project license
CHANGELOG.md              # Project release changelog file
requirements_licenses.txt # depend library licenses
pull_request_template.md  #  Pull request how to

For fresh install on RaspberryPi with code follow How_to_install_fresh_RPi_with_code.md

1. Clone repo to your RPi. git clone [email protected]:OliverDrechsler/front_door_intercom_automation.git

2. go into project repo cd front_door_intercom_automation

3. now run pip3 to install python requirments pip3 install requirements.txt

4. copy config_template.yaml to config.yaml file cp config_template.yaml config.yaml

5. edit config.yaml file with your favorite editor

   • for creation of telegram bot and privat chat channel follow telegram_bot_setup
   • for creation of base32 encrypted timebased one time password master password follow one_time_password_setup
   • for blink configuration follow blink_camera setup
   • for picam configuration follow config_template.yaml doc remarks or PiCam_API Projects
   • for flask web config follow description in config_template.yaml

6. run app python3 fdia.py and check log output

   for troubleshooting see Help

7. setup app to run as daemon / service in linux follow System service setup

see further docu docs/one_time_password_setup.md

see further docu docs/totp_helper_cli.md

Edit file fdia.service and adjust to your path ( ExecStart=/home/pi/front_door_intercom_automation/fdia.py ).
To run fdia as a service on startup with root permissions
copy fdia.serviceto /etc/systemd/system/to your RPi systemd deamon folder.
Run systemctl daemon-reload and systemctl start fdiato start it as a service.

config_template.yaml is a template config file and must be adjusted to your needs.
Copy config_template.yaml to config.yaml into project root folder.
cp config_template.yaml config.yaml

In this yaml file you'll find after # comments / hints for which the line is what to configure.

If you have configured in the config.yaml your blink camera
( followed by this docu blink_camera setup )
after starting fdia.py application you can send your received blink 2 factor token via telegram channel to the application.
It starts to authenticate via 2FA(FactorAuthentication) / MFA (multi factor authentication) and saves afterwards the blink config to the file blink_config.json. From now on it is getting used and normally no further 2FA / MFA authentication is not anymore required.
Handle this file careful since there is your blink secret stored.

To store a master password for totp time pased one time password it must be encoded with base32 as a hash. You can run the the cli script encrypt_decrypt_password_with_base32.py in tools directory. Than you get a base32 hashed password.
Please store this password in the config.yaml under section otp: password:

For further docu refer to docs/one_time_password_setup.md

This project actually supports two type of cameras.

• Blink cameras with BlinkPy library
  This means all Blink cameras are supported.
• My Raspberry PI camera Project PiCam_API Project.
  It is a self coded software project which just requires a Raspberry Pi and a wired Camera. It is your choice when you want to be more GDPR compliant and don't want to expose your camera to the internet. Also you can use this project from your home wireless network only via web ui and must not use telegram.

For configuration of the blink camera please procceed with further docu/blink_camera_setup.md.

For configuration of the PiCam_API please procceed with the PiCam_API Project docu.

please follow exra documentation here telegram_bot_setup

Received Telegram chat channel message command to action

• /Foto = request to take a foto auto choice for PiCam or Blink config and send it in the telegram chat channel
• /Blink = request to take a Blink foto and send it in the telegram chat channel
• /PiCam = request to take a PiCam_API foto and send it in the telegram chat channel
• /Blink_auth <here your 6 digit security code> = request to do a blink 2FA / MFA authentication and store blink config
• <time based one time password code> = validate totp, take a foto send it and open door.

Install on your Mobile following Apps and set it up.

• Telegram Messagenger for free in AppStore
• OTP Auth App for free in AppStore
• Apple IOS Shortcuts for REST API automation

Provide configure same OTP config in OTP Auth App like in config.yaml defined.

Use OTP App to get a totp code and copy to clipboard.
Paste clipboard code into telegram chat channel where front-door intercom automation bot ist listening. When bot receives valid code - door will be opened.

Apple IOS Shotcuts App can be used to to send direct otp code passwords to REST-API. As long as you are in the local network as the fron door intercom automation is you can send it direct. If you're away for your home wireless network you can use a VPN tunnel to connect to your ISP router
and than send the otp door open code to the REST-API.
Do not expose the Flask Web-UI or REST-API to the internet!
VPN Tunnel activation can also be automated like the REST-API call in IOS Shotcut App.

A mobile IOS door opening app is in development.
As long as it's not published i recommened to use the above Apps.

t.b.d

A Flask Web-UI will be provided on given config port in config.yaml under section web:

web:
  flask_web_port: 5001                            # flask webserver port
  flask_secret_key: "my_super_flask_secret_key"   # provide here your own flask secret key
  browser_session_cookie_lifetime: 30             # browser cookie key
  flask_users:             # list of flask app login user for webpage and/or rest api call
    - WebUser1: "password"
    - WebUser2: "password"

Here you can specify multiple users which are allowed to access the Web page and REST-API.

For TLS cert encryption it's recommend to use a NGINX reverse proxy with TLS cert configuration.
Please consult google for further details about it.

A REST-API POST call can to URL http:https://<fqdn, hostname or ip>:<port>/open.
For Authentication a base64 encoded header with username and password must be added.
Request body must be

{
  "totp": "<here time based one time password code>"
}

curl command example

curl -X POST http:https://127.0.0.1:<FLASK_WEB_PORT>/open \
     -H "Content-Type: application/json" \
     -H "Authorization: Basic <BASE64_ENCODED_CREDENTIALS>" \
     -d '{"totp": "<YOUR_TOTP_CODE>"}'

The <BASE64_ENCODED_CREDENTIALS> is username:password encoded base64 string.

• Strip grid circuit board of Epoxy – 100 x 100 mit 2,54mm
• Optocoupler (PC817)
• Resistor: to get correct voltage of 1,2V for Optocoupler, a resistor of 330 Ohm (8 Volt), 560 Ohm (12 Volt) or 1,2 Kilo ohm (24 Volt)
• Raspberry Pi Hutschienen-Netzteil (Mean Well MDR-20-15) für den Einbau in den Sicherungskasten

SmartSaint Relay board is used to open door. RPi GPIO ports ar connected to SmartSaint. Other side of SmartSaint relay ports connected to (BTIcino) Intercom system.

• saintsmart 2-Channel 5V Relay Module
  
  shop where to buy saintsmart relay

• Jumper and wiring layout

wiring layout see at stackexchange

Edit fdia.py file and at top of the file (line 22 - after imports)
there you'll find the section

"""Define logging LEVEL"""
default_log_level = logging.INFO

Here you can modify logging.INFO level to logging.DEBUG and store the file. Now when you run the fdia.pyapp again you get full detail debug log of:

• fdia app and it 6 threads
  • fdia thread = main thread
  • thread_receive_telegram_msg
  • thread_send_telegram_msg
  • thread_cameras
  • web_thread
  • thread_door_bell
  • thread_open_door and
  • blink lib in debug mode
  • telegram lib in debug mode

The communication between thread is handled via queues.
Therefore exists this config/data_class.py which is the the data transfer class between the threads
to submit the task.

In case you do not find ther error in the log, raise a GitHub issue with your error.

Following important libraries are used and can also be consulted in case where issues are in

• Blink -> BlinkPy library
• Telegram -> PyTelegramBotAPI library
• Web-UI and Rest-API (Flask) -> Flask
• Timebase one time password -> PyOTP library
• Ciruit wiring -> Überallkingel at heise.de

Internal code API docu can be found at github pages linked on top above or in code itself.

pytest --cov=./ --cov-report=html

Check folder .github

• dependabot.yml dependcy check pipeline for security issues
• workflows/ci.yml contious integration pipeline builds code and tests code
• workflows/codeql-analysis.yml CodeQL analysis pipeline
• workflows/docs_update.yml build GitHub page pipeline

see CHANGELOG file CHANGELOG

I'm Oliver Drechsler and a Java and Python developer.

• 📫 Connect with me:: ...

This Software is licenced under MIT see license file of this project.

Why is there no GPLv2 dependency as I understand it? pyTelegramBotAPI published under GPLv2, but it is used as a shared library which is linked dynamic. Further only source code is distributed and python code is compiled during runtime (JIT) on user system, therefore it is no distribution. For more details see Fundamental aspects of copyleft in GPL and read section 7. Libraries

Dependcies to other projects and libraries listed here requirements_licenses.txt.
It is create with licensecheck

pip3 install licensecheck
licensecheck -u requirements > requirements_license.txt

Pull request docu can be found here in docs/pull_request_template.md