This project is intended as a flexible and customizable replacement for standard doorbell chimes. It uses common and inexpensive components, is fairly easy to build, and highly customizable through a convenient web interface.
- Chime notifies with sound and light animations so it can't be missed and can be used by people with hearing problems.
- Fully customizable chime sounds and animations.
- Easy to use and customizable web interface.
- Versatile and adaptable hardware requirements.
- Web hooks to trigger alerts when the bell rings.
- HTTP API can be used to connect multiple chimes with webhooks so they all ring together.
- Choice of using onboard storage or external storage for expansion.
- Additional 3D printable case and mounting options.
- Timer options to allow for quiet periods or different chime sounds at different times.
- Fully document API.
Create stripped-down version that uses flash filesystem instead of SD card.- Custom PCB.
These are the suggested requirements for this project, however customization is encouraged.
This list was composed of materials that could all be sourced from a single store, Adafruit, though any compatible substitutions should work. This list does not include common materials like jumper wires, protoboards, or soldering equipment.
- TinyS3 - ESP32-S3
- Class D Amplifier Breakout - MAX98357A
- Speaker - 3" Diameter - 4 Ohm 3 Watt
- Optional: Micro SD SPI or SDIO Card Breakout1
- Optional: Micro SD Card1
- NeoPixel Ring - 16 x 5050
- MPM3610 5V Buck Converter2
- 2.1mm DC Barrel Jack2
- 5V 2A Power Supply2
Warning
Make sure you know what kind of power is available for your chime. The chime itself requires 5VDC, so your setup must be able to provide this.
Most household chimes in the United States use 16VAC with an AC/AC transformer to bring the voltage down from the mains voltage. If this is the case, the safest option is to ignore/remove that transformer and use the 5V 2A supply and barrel jack from the materials above and plug your doorbell into a standard outlet.
If you already have DC voltage available at the wall that's greater than 5V, you can use the MPM3610 from above to bring the voltage down to 5V. More complicated power setups are not covered in this guide and extreme caution is advised when dealing with household and mains electricity.
While you can use any ESP32 device, one with two or more cores and 4 MB or more of PSRAM is required and variants without those specifications will almost certainly not work. The ESP32-S3 is the preferred version, specifically the TinyS3 board. Additionally, at least 4 MB of flash is required and 8 MB recommended if you plan to forgo the SD card and use the onboard flash for storage. You'll need to wire up the various components to the TinyS3 ESP32 in the following manner:
Important
This setup assumes the doorbell button connects to GND as the pin connected to the button uses a pull-up resistor and is considered active when low. If this is not the case, you'll need to modify the code and change the pull-up resistor setting to a pull-down resistor and change the code accordingly. A substitute or a new button can be used if there isn't an existing option, but such scenarios aren't covered in this guide.
| TinyS3 Pin | Device Pin | Device |
|---|---|---|
| 1 | Data Input | LED Ring |
| 5V | 5V DC | |
| GND | Ground | |
| 2 | button | Doorbell Button |
| 8 | clk | Micro SD Card Breakout |
| 34 | cmd | |
| 9 | d0 | |
| 37 | d1 | |
| 35 | d2 | |
| 36 | d3 | |
| 3V3 | 3V | |
| GND | GND | |
| 5 | I2S_BCLK | MAX98357A |
| 4 | I2S_LRC | |
| 21 | I2S_DOUT | |
| 5V | Vin | |
| GND | GND | |
| 5V | 5V out | Power Supply |
| GND | GND |
Tip
If you want to get maximum volume you can connect a 100 kΩ resistor from the amplifier's gain pin to 5V.
Below is an example diagram connecting to a Feather ESP32-S3 device.
Caution
The diagram above does not match the current state of the code and pin assignments for a TinyS3; this is just an example for illustrative purposes. Refer to the table above for the pin connections used in the code.
By default the device is configured to use a portion of the onboard flash storage as a LittleFS storage system. You'll have access to ~1.3-1.5 MB of storage using this system. If more storage is desired, you can hook up the SD card as described above, and you'll need to change one line in the main.cpp file. Specifically, find the line that reads //#define USE_SDCARD and uncomment it so it resembles the following:
/// @brief Uncomment to enable use of SD card instead of LittleFS
#define USE_SDCARDAfter doing that, rebuild and update the firmware on your device as described below.
To program the doorbell chime for the first time follow the below directions. Subsequent updates can be applied using the the web interface documented below.
- First download Visual Studio Code.
- Next, follow the instructions to install PlatformIO.
- Clone or download this repository to a folder.
- Open the project folder with PlatformIO in Visual Studio Code.
- Connect the TinyS3 to the computer via USB.
- Upload the code using the PlatformIO toolbar.
After the first flash you need to setup the web interface. There are two ways to do this:
- Copy the
wwwfolder to the SD card, if using one
Or if you are using the onboard flash storage or can't access the SD card
- Connect to the IP address of the doorbell in your web browser. Here you can upload all the files from the
wwwfolder one at a time to the doorbell and then reboot the device.
If this is the first time powering on the doorbell it could take a while as it may need to format and mount the SD card or LittleFS storage. Once it's finished the initial boot, you'll need to configure it to connect to your WiFi network. When you power on the doorbell for the first time (or if the expected WiFi network is not available for it to connect to) you'll need to wait a minute or so until the LEDs display an short animation of blue LEDs rotating. This is used to indicate that the doorbell is in WiFi setup mode.
Once in WiFi setup mode, the doorbell will create its own WiFi network named "UltimateBell". Connect to that network, there should be no password, ideally with your phone and visit the IP address 192.168.4.1 to reach the doorbell's WiFi setup interface (a phone may do this automatically). Choose "Configure WiFi" and pick the WiFi network you want the doorbell to connect to. Enter the WiFi password as shown below.
If the WiFi credentials are good, the doorbell will reboot and attempt to connect to the network, and you're done! If not, you can repeat this process and try again. To reset the WiFi see the web interface.
The LED ring has several animations and codes that convey the state of the doorbell. A short description of these codes is provided below:
| LED Code | Meaning |
|---|---|
| All LEDs orange, constant on | Doorbell is booting |
| One green LED in a circle | Doorbell is ready |
| Two blue LEDs in a circle | WiFi setup has started |
| Two orange LEDs in a circle | WiFi setup completed successfully |
| Four purple LEDs in a circle | Firmware updated successfully |
| One red LED, constant on | Storage error (SD card or LittleFS) |
| Two red LEDs, constant on | Error loading I2S amplifier settings |
| Three red LEDs, constant on | Error with loading webhooks |
The web interface provides the means to configure and customize your doorbell. You'll need to visit the IP address of your doorbell in a web browser after the initial setup and once it's on your WiFi network. When you do, you'll be presented with a series of links to the various management pages.
This page allows you to manage the contents of the storage. You can upload files to one of three folders:
chimes: contains the audio files for chime sounds.settings: contains the JSON configuration files.www: contains the files for the web interface.
Uploading a file will overwrite an existing file if there is one. You can also download and delete files from the doorbell.
This page allows you to manage the chime sounds that play. Any checked sounds will be available to play when the button is pushed, and one of the available sounds will be chosen randomly. You can also adjust the volume at which the sounds will play or test-play any sound and its animation. After making changes you need to click the Update Sound Settings button before they take effect.
Important
Chime sounds should have the following format: mp3, 96 kbps bitrate, 44.1 khz sample rate. Other formats may work or may cause crashes or unexpected behavior.
This page will allow you to add or remove webhooks. Webhooks are automatically called when the bell chimes and again when the chime finishes ringing. Other event may be added to webhooks in the future. To add a webhook enter the full URL of the webhook.
If you want to include POST or GET parameters, you can create a comma separated list of key:value pairs. There are two special values you can use:
%SOUND_FILE%will be replaced with the path on the SD card of the sound file currently being played.%EVENT%will be replaced with an integer representing the triggering hook event (see the Events enum in the LEDRing.h file)
An example parameter list would be: api-key:12345678,sound:%SOUND_FILE%
This page can be used to update the firmware. You'll need upload the firmware.bin file after running a build from PlatformIO. This firmware can be found in the .pio/build folder for your specific device.
The doorbell comes pre-loaded with animations for each event and for when the chime sounds. However, all of the default event animations can be overridden and additionally custom animations can be added for each chime sound.
To add custom animations, upload a file named animations.json to the settings folder. Ths file should have the following format:
"animations":{
"NAME_OF_EVENT_OR_CHIME_SOUND" : {
"repetitions": 1,
"clearOnDone": true,
"frames": [
{
"duration": 75,
"colors": ["0", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F"]
},
{
"duration": 75,
"colors": ["0x00317F", "0", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F", "0x00317F"]
}
]
},
"NAME_OF_ANOTHER_EVENT_OR_CHIME_SOUND" : {
"repetitions": 4,
"clearOnDone": false,
"frames": [
{
"duration": 100,
"colors": ["0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F"]
},
{
"duration": 100,
"colors": ["0x00317F", "0", "00x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0", "0x00317F", "0"]
}
]
}
}
}The file is broken down into a collection of animations. The name of the animation should be either one of the events in the Events enum in the LEDRing.h file or the name of a chime sound. For example, to override the DOORBELL_READY animation, you would use that name. Or to have a unique animation play when the ding-dong.mp3 chime sounds plays, name the animation ding-dong. Any number of animations can be added/overridden in the file.
Each animation has the following properties:
repetitionsis an integer representing how many times the entire animation will repeat.clearOnDoneis atrueorfalseon whether the last frame of the animation should be left on display (false) or all the LEDs turned off after the animation finishes (true).framesis an array of animation frames described in more detail below.
The frames element is an array that contains any number of animation frames with the following properties:
durationthe amount of time in milliseconds to display the frame.colorsA hex code RGB color value for each of the LEDs on the LED ring.
A 3D printable model of an intercom style mount is provided here. This is designed to work with a 6cm x 8cm protoboard. The model can be edited and customized in OnShape
Tip
The model seems to print best with the front face down on the print bed, supports enabled, and a line height of 0.28mm.
- Adafruit NeoPixel
- ESP32-audioI2S
- ESPAsyncWebServer
- ESPAsyncWiFiManager
- Unexpected Maker ESP32-S3 Arduino Helper Library