Smart Doorbell for HomeAssistant

Introduction: Smart Doorbell for HomeAssistant

So, I wanted a doorbell with the following features:

  • Video from the door
  • Two way audio
  • Two buttons
  • Integration with wall mounted tablet showing HomeAssistant UI

Some options came along like Doorbird (expensive and they do not have two-way audio calling using HTML5) and Ring doorbell (but I don't like a subscription, cloud based doorbell)

As a developer and tinkerer, I already finished some projects but this was by far one of the most difficult ones to complete. I had a lot of trouble getting the two-way audio working to a point where you can understand each other. This mainly because there is quite a lot of echo, ... . The idea comes from DoorPi, but with the SIP protocol, I had too much echo which made resulted in not understanding one-another.

Since my doorbell is completely protected from the elements, we are able to make the front in lasercut wood.


  • Raspberry Pi 3 B or 3B+ (do not go for a Banana Pi with PoE build in as it does not support the standard Raspberry Pi CSI camera interface) = € 33,67
  • Micro SD card = € 2,69
  • Raspberry Pi fisheye camera = € 14,14
  • PoE adapter = € 4,94
  • RaspiAudio Mic + = € 24,69
  • Access to 3D printer (and laser cutter)
  • Buttons for the Doorbell
  • A lot of time!

This adds up to a total of € 80,13.

Out of scope, the indoor station:

Step 1: Setup Raspberry Pi

I highly recommend you to use ethernet instead of Wifi. My audio quality improved a lot due to it. We will also be using UV4L since it supports webrtc and thus has echo-cancellation built-in. The Doorpi uses linphone, a SIP client and I was unable to get the echo cancellation working.

  • Download Raspbian Stretch Lite and install it on the Micro SD card. Make sure you:
    • enable ssh by creating an empty ssh file in the boot partition
  • Run the following commands:
sudo apt-get update
sudo apt-get upgrade 


Enable the camera via raspi-config and make sure that the GPU has at least 192 MB of ram.


Follow the installation guide of RaspiAudio found at


Follow the installation guide of UV4L found at

Adjust the /etc/uv4l/uv4l-raspicam.conf file and make sure you adjust the following settings:

The most notable settings is probaby --enable-webrtc-video=no: this is because we will always stream the video from uv4l using h264 encoded mjpeg.

Using the following files located in /usr/share/uv4l/demos/doorpi/, you can already test the two-way audio and video.

  • index.html (rename it from index.html5, needed to rename due to instructables upload requirements)
  • main.js
  • signalling.js

Browse to https://[ip-of-raspberrypi]:8888 and test if you can get the 2-way audio working.


The easiest way I found to get the doorbell-buttons working, is to attach them to the raspberry pi and use pi-mqtt-gpio to integrate it with HomeAssistant.

My configuration file is as follows:

mqtt:<br>  host: x.x.x.x
  port: 1883
  user: [username]
  password: [password]
  topic_prefix: "doorbell"

  - name: raspberrypi<br>    module: raspberrypi<br>    cleanup: yes

digital_inputs:<br>  - name: button_1<br>    module: raspberrypi<br>    pin: 17<br>    on_payload: "Off"<br>    off_payload: "On"<br>    pullup: yes<br>    pulldown: no<br>  - name: button_2<br>    module: raspberrypi<br>    pin: 27<br>    on_payload: "Off"<br>    off_payload: "On"<br>    pullup: yes<br>    pulldown: no

Do note that as there more ground pins available as 3.3V pins, I choose to use pullup GPIO pins and thus inverted my MQTT messages.


driver = raspicam
auto-video_nr = yes
frame-buffers = 4
encoding = h264
width = 1024
height = 768
framerate = 10
rotation = 270 #depending on your hardware setup
server-option = --port=9090
server-option = --bind-host-address=
server-option = --use-ssl=yes
server-option = --ssl-private-key-file=/etc/uv4l/selfsign.key
server-option = --ssl-certificate-file=/etc/uv4l/selfsign.crt
server-option = --enable-webrtc-video=no
server-option = --enable-webrtc-audio=yes
server-option = --webrtc-vad=yes
server-option = --webrtc-echo-cancellation=yes
server-option = --webrtc-max-playout-delay=34
server-option = --enable-www-server=yes
server-option = --www-root-path=/usr/share/uv4l/demos/doorpi/
server-option = --www-index-file=index.html
server-option = --www-port=8888
server-option = --www-bind-host-address=
server-option = --www-use-ssl=yes
server-option = --www-ssl-private-key-file=/etc/uv4l/selfsign.key
server-option = --www-ssl-certificate-file=/etc/uv4l/selfsign.crt
server-option = --www-webrtc-signaling-path=/webrtc
view rawgistfile1.txt hosted with ❤ by GitHub

Step 2: Doorbell Box

  • doorbell-back v1.stl: 3D printed box for raspberry pi and PoE adapter
  • doorbell-front v1.svg: Laser cut face plate
  • doorbell-micro v1.stl: 3D printed box containing mirophone wrapped with sound insulation, glued to face plate

Screw the raspberry pi in the attached screw holders and put the PoE adapter on the top right. Put the camera and the microphone in place (make sure to detach the microphone and make sure the hole of the microphone is well aligned with a hole in the face plate).

Step 3: HomeAssistant Integration

The following files allow for HomeAssistant integration:

  • doorpi.yaml: package containing everything related to the doorbell including listening to MQTT messages and automations to play the chime when the doorbell is pushed
  • www/doorpi/doorpi-card.js: lovelace doorpi card which needs the signalling.js and doorpi-camera-view.js

IMPORTANT: Do note that you must be running HomeAssistant with https/ssl as otherwise chrome will not allow you to access the audio devices.

Step 4: Happy Doorbell-calling!

That's it, you should now be able to call someone via the doorbell and HomeAssistant will automatically switch to the doorbell card. There you can decide to accept or ignore the doorbell.

Be the First to Share


    • Microcontroller Contest

      Microcontroller Contest
    • Cheese Challenge

      Cheese Challenge
    • Teach With Tinkercad Contest

      Teach With Tinkercad Contest



    Question 2 years ago on Step 4

    I have run a webrtc on my raspberry pi with the server as describe in the guide.
    The problem is the audio streaming by client to server. In particular the audio from server (server -> client) is ok, but the inverse (client /chrome -> to server) not working.
    Have you any idea?
    Thank you


    Answer 2 years ago

    Are you running on https? Otherwise it won't work? For the rest - no idea. I would test the microphone from the client standalone.


    Reply 2 years ago

    Yes, i m running on https. The microphone is working fine because if i use the webrtc stream on https:ipaddress/stream/webrtc the bidirectional audio are very good. I don t understand because in the other page i don t have the same behaviuor.


    Reply 9 months ago

    dou you have fixed this problem?I'm facing the same problem


    Question 1 year ago

    Hi. This is realy great work. I am at the beginning with Homeassistant. I read about different ways to build a DIY Audio/Video Doorbell to integrate it in Homeassistant and wonder if this projekt can used to get Doorbell calls outside from home. I used for example the Homeassistant Companion App on my phone. There, the doordroid card didn't work at all. Is that normal ? Do you guys use all normal browsers on Android to connect to your Homeassistant ? And, if it should also work with the HA Companion App, is there a way to get notified on a Doorbell Ring and answer the Call in The HA App ? For example like in a communication App (like a SIP Softphone App etc) ? Maybe someone can tell me about it a bit more...

    Cheers Sascha


    Answer 1 year ago

    Hi Sacha, I use the app and the card works on my side, but I'm on local network only at the moment. Had troubles setting up SSL for the app though (self signed certificates), your issue may come from there. And for notifications, pretty easy to setup :


    Reply 1 year ago

    Hi, thank you for answering. Yes in local LAN and with "normal" Browsers the Card works great. if i use the Home Assistant Companion App on Android, i see the Incomming Call as i see it in the Browser. So far so good. But in the Companion App, if i click on Accept, i got asket if i want to allow the use of the Microphone. If i click yes to allow, i got the following error message and stuck: "check media device permissions on media and origin". So the Home Assistant Companion App on Android ist useless for the purpose at the moment. Did anyone use the Companion App with this ? BTW. Same problem when i am using the sip based Doordroid System. It would be cool, if we can use this on Android Companion App.


    1 year ago

    Hi. This is really an amazing project and I have started to give it a go.

    2 questions to start off with:
    - niraviry - you mentioned that you documented this in a bit more detail - are you able to share that?
    - Then, also seeing the missing doorpi files in the uv4l demos. Is this a dependency to get this to work?


    1 year ago

    Thank you very much Ronald for sharing this excellent project. I started it as a complete raspberry/iot noob and still managed to complete the project (in 6 months :0) ).


    Reply 1 year ago

    There is just one thing I still need to do, based on my visitors feedback as everybody believes it is not working as theres no feedback, no sound or light when the button is pressed. Maybe it's also the button I choose...


    2 years ago

    HiI am in the process of building the doorbell project using similar components.
    What I have off hand are:
    - Rpi 2 B with latest Raspbian Buster
    - USB PnP sound card
    - Optionally Piface relay card
    - Running HA (HASS.IO) that runs my whole house.
    I was able to set the USB sound card as my default one.
    The test file works (I hear speakers sound) but I can't tell if the mic is working.
    The are few issues:
    1. The "server-option = --www-root-path=/usr/share/uv4l/demos/doorpi/" points to a non existing dir. The demo is not there thus the rest of the path. Should I add it just for the test files?
    2. The mic1 tries to install the raspiaudio but it looks like I do not need it as the USB is working. I did not figure out yet how to test the mic.
    3. The https://[ip-of-raspberrypi]:8888 is to working (the https://[ip-of-raspberrypi]:8080 works and I see the camera.
    4. The MQTT should follow remote MQTT gpio and it looks like the code does not follow the lates syntax of version 0.107.2.

    Hope you can help to solve these issues assuming this is the best thing to do during the Coronavirus days.


    Reply 2 years ago

    Hi again.
    No answer from anyone. Anyway, the instructions here are very partial and i had to dig a lot to make it work. It is almost done.
    The code that appears here is divided between the config of the pi_mqtt_gpio file in the doorpi unit and the HA.
    In the index file the IP address is a dedicated one which might not fit to your network so it should be updated to the relevant one.
    My last 2 issues are:
    1. MQTT does not recognise properly the 2 IO lines. It connects but it creates just one binary_sensor without getting the name. I use mosquitto MQTT
    2. I am not sure how to use door-card.js as in the new versions the method of using java scripts has changed.

    When this will fully work, I will post a detailed dummies tutorial.


    Reply 2 years ago

    Some of us had the corona virus, so I was out for a couple of weeks - please note that this is a sparetime project for me and that it is difficult to find time after illness, 3 kids and work.

    - Regarding MQTT: I do not understand your question.
    - On the raspberry pi itself, I'm using with the config mentioned above (sorry for the bad layout but instructables is a nightmere for displaying code properly). pi-mqtt-gpio connects to your mosquitto broker and posts messages when the buttons are pressed (in my case button1 is connected to pin17 and button2 is connected to pin27).
    - In HomeAssistant, you will need to create the binary_sensors yourself - these are binary_sensors of type mqtt configured in doorpi.yaml where HomeAssistant listens to the state_topic: "doorbell/input/button_1". The relevant binary_sensor is triggered when pi-mqtt-gpio sends a message via mosquitto on which HomeAssistant is listening.
    - I'm still running HA 0.105.3 - I have not yet updated to 0.107 and do not plan to do so quickly. Have to catch up with other stuff first


    Reply 2 years ago

    Hi Ronald. I have replied yesterday but the answer was gone from some reason. Anyway I made a lot of progress. The problem is documentation, this is why I have made my own documentation with all details including what to do in case of problems and I had more that few.
    I will post it once all will be done.
    The last issue is engaging the doorpi-card to the lovelace and using the camera.
    The documentation in HA is not the best and I am struggling to make it work. The js file comes with no instructions / example how to define the custom card in HA.
    Please send the instructions so I can finalise the project.


    Reply 2 years ago

    I hope you have completed your setup and everything is working as expected
    I'm about to start my own setup and I am wondering if you are ready to share your progress documentation


    Reply 2 years ago


    I am towards the end of it. My implementation included some issues that the original one did not have. I wanted to hook the system into my existing Urmet Synthsi system so that I will not have to change my front gate mailbox. I have to run some reverse engineering in order to use the audio circuitry. I also created a much detailed instructions document. I will post it after reviewing again in a day or so. I am in the middle of integrating everything into the mailbox.
    Unfortunately no one answered the issue of the doorpi.js not running properly under new versions of HA. This still needs tweaking but basically I see image.


    Question 2 years ago

    Nice project, but its not running on my RasPi yet. Where to put all that files, I am missing the paths. Am I right, that there are many servers and clients working at the same time on the RasPi: uv4l streaming (9090), webrtc(8888), homeassitant(8123) and mqtt(1883) ? Why do there are 2 files named "signalling.js"?


    Answer 2 years ago

    Since I have posted my questions I did a lot of progress. The doorpi is working. I have overcome the MQTT. It was a tricky one as HA instructions are not so clear regarding the need for discovery etc.
    Anyway, I put everything is one instructions file and once I will end with it ,I will try and put it in a link so it will be very easy to follow as all instructions are fully placed line by line.
    At this point I am only missing the info regarding building the doorpi custom card as it needs entities or so. There is no documentation about it what so ever.


    Reply 2 years ago

    All you need to do for the doorpi custom card is the following:

    Add it to the resources section:
    - type: module
    url: /local/doorpi/doorpi-card.js?v=0.5.1

    Add the doorpi card (see image).

    Since I want to view my doorbell from outside my homenetwork, I proxy the UV4L with Traefik and give it an address that is available from the internet.


    Reply 2 years ago

    At this point 2 issues are left.
    1. I am trying to cause the pi-mqtt-gpio to load at boot with no luck. The /etc/init.d method or any other way causes it to load during boot.
    2. The doorpi card does not work. Some times I can save it but no camera appears nut most of the time it is poping an error doorpi-card is not found. While editing the card from scratch the error is blinking rapidly in a strange way. One phase is the error with the cancel button on while in the 2nd phase it has no error but also save is grayed out.
    If I do that from scratch it lets me save it but than is blinks.
    I have changed the names of the everywhere and firstfloor to what I needed in the doorpi-card.js as well as the domain name of my camera. The camera works from my phone or PC using https OK.