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


    • Mason Jar Speed Challenge

      Mason Jar Speed Challenge
    • Bikes Challenge

      Bikes Challenge
    • Remix Contest

      Remix Contest

    29 Discussions


    Question 8 weeks 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 7 weeks 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 7 weeks 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.


    6 months 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 5 months 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 5 months 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 5 months 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 3 months 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 3 months 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 11 months 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 5 months 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 5 months 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 5 months 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.


    Reply 5 months ago


    I have looked in the mail and it misses the image. Checking again.


    Answer 8 months ago

    Hi, sorry for the late reply - must have missed it.

    On my raspberry pi, I only run doorpi. My HomeAssistant runs on my Synology NAS.
    Regarding the 2 signalling js - one I use for testing purposes, the other one is to add it too HomeAssistant. If you skip the intermediate testing, only the last one is needed.

    Best regards,


    8 months ago

    I think this is an amazing project. I have completed step 1 of the instructables and have video and audio working. I am a little lost at step 3. Do I put the 3 files into the library www/doorpi/, being doorpi-card.js, signalling.js and doorpi-camera-view.js?
    How do I use the doorpi.yaml? Do I copy it to my Configuration.yaml? Do I need to create a LoveLace card, or does the broswer mode do that. Do I need to change any names in the above files?
    Sorry for all the dumb questions, but as you can see I am not very good at this stuff.


    Reply 5 months ago

    Hi Mark,

    sorry for the long time to reply. Some answers to your questions:
    - yes, all 3 files (doorpi-card.js, signalling.js and doorpi-camera-view.js) go in the www/doorpi folder. This is a lovelace view you can embed into your lovelace config. To embed the lovelace card, you add a reference to the doorpi-card.js and then you can use the type: 'custom:doorpi-card' in your lovelace
    - the doorpi.yaml file is a homeassistant package ( file that you need to reference from your configuration. In there, you find all the automations when somebody rings the bell
    - in the doorpi.yaml you see references to my entities, here you will need to make a lot of changes. The important stuff to keep is the first two binary_sensors and the first 2 automations - the automations trigger the binary sensors when an mqtt message arrives from the raspberry pi at the door

    Best regards,


    Reply 5 months ago

    Hi Ronald,
    Thank you so much for all your help. I am pleased to say that I have it all working perfectly. You are a very clever man.
    Thank you very much.
    Kind Regards


    Reply 8 months ago

    Hi Markabee,
    - you put the 3 javascript files in www/doorpi
    - you put the doorpi.yaml in homeassistant package (
    - you then reference the doorpi card in your lovelace configuration, e.g.
    - type: module
    url: /local/doorpi/doorpi-card.js?v=0.5.1
    - you use the following in your lovelace:
    - cards:
    - camera_entity: camera.doorbell_camera
    url: ''
    type: 'custom:doorpi-card'
    icon: 'mdi:door'
    title: DoorPi

    I hope this helps!


    Reply 7 months ago

    Hi Ronald,
    Thank you so much for your help. I seem to be stuck yet again. This time in LoveLace I am recieving the message "you need to define the doorPI settings".
    Any suggestions .
    Kind Regards

    Annotation 2020-02-14 183538.png