Domofon

domofon-esp32 — analog intercom ↔ ESP32-C3 / ESPHome / Home Assistant

An interface that connects a classic 2-wire analog intercom handset line (Polish: domofon) to an ESP32-C3 SuperMini (HW-466B) running ESPHome, so the intercom can be used from Home Assistant.

Status: design only — not yet tested on real hardware. Schematic, single-sided PCB, BOM and firmware are complete; the board has passed KiCad DRC, but nothing has been built or measured yet.

Features

• Ring detection — AC-input optocoupler (LTV-814) on the line, debounced input on GPIO3.
• Off-hook — PhotoMOS relay (AQY214EH, 400 V) connects a load resistor and a 600:600 line transformer, just like lifting the handset. The line is forced back on-hook when a configurable limit elapses (default 60 s), whatever took it off-hook.
• DTMF transmit — sine PWM (ESPHome component in this repo) summed and filtered, coupled through the transformer. Any DTMF sequence; the default sends "1" to open the gate.
• DTMF receive (software) — line audio via the transformer to ADC1 (GPIO1), decoded on the ESP with a Goertzel filter bank (ESPHome component in this repo). Works only while off-hook.
• Galvanic isolation — ESP ground never touches the line; 4 mm isolation gap + milled slot on the PCB.
• Extra handset jack — RJ11 (J1) wired in parallel with the line.

Home Assistant entities

Schematic

Repository layout

├── README.md
├── docs/
│   ├── design-notes.md          # English summary of the circuit
│   └── design-notes-pl.md       # full design notes (Polish): netlist, pin numbers, rationale
├── hardware/
│   ├── schematic/
│   │   ├── schematic.py         # source (schemdraw)
│   │   └── schematic.svg/.png   # generated output
│   ├── pcb/
│   │   ├── domofon.kicad_pro/.kicad_pcb/.kicad_dru   # KiCad 9 project (single-sided, THT)
│   │   ├── drc-report.txt       # KiCad DRC: 0 violations, 0 unconnected
│   │   ├── README-pl.md         # PCB notes (Polish)
│   │   ├── gerbers/             # Gerber X2 + Excellon (mm) — input for CNC
│   │   ├── previews/            # PNG renders
│   │   └── scripts/             # Python/KiCad generators, autorouting, DRC, export
│   ├── bom/
│   │   ├── bom.csv              # full bill of materials
│   │   └── tme-order.csv        # original TME order (history, pre rev. 5)
│   └── enclosure/               # 3D-printed wall box (CadQuery source, STL, 3MF, STEP, previews)
├── firmware/esphome/
│   ├── domofon.yaml
│   ├── secrets.yaml.example
│   ├── intercom-package.example.yaml   # HA builder example (packages)
│   └── components/

PCB

• Single-sided (copper on B.Cu only), all parts THT on top, 55.6 × 46.0 mm, designed for isolation milling with a 30° / 0.2 mm V-bit.
• Rules: clearance ≥ 0.4 mm, tracks 0.6 mm (signal) / 1.0 mm (power and line), no vias, one wire jumper (JP1).
• Low parts sit under the ESP32-C3 module → mount the module on female headers (~8–11 mm).
• gerbers/domofon-F_Cu-jumpers_DO_NOT_MILL.gtl only models the wire jumper for DRC — do not mill it.

Placement	Bottom copper (mirrored, as milled)

How to regenerate

Requirements: Python 3, schemdraw + pillow; KiCad 9 (kicad-cli and the pcbnew Python module); rsvg-convert (librsvg) for previews; optionally Freerouting 2.x + Java for re-routing.

# Schematic -> hardware/schematic/schematic.svg + schematic.png
cd hardware/schematic
python3 -m venv .venv && .venv/bin/pip install schemdraw pillow
.venv/bin/python schematic.py

# PCB checks and outputs (run from anywhere)
hardware/pcb/scripts/drc.sh              # DRC -> hardware/pcb/drc-report.txt
hardware/pcb/scripts/export_gerbers.sh   # -> hardware/pcb/gerbers/
hardware/pcb/scripts/make_previews.sh    # -> hardware/pcb/previews/

# Full re-generation of the board from footprints.py / netlist.py / placement.py (optional)
FREEROUTING_JAR=/path/to/freerouting.jar JAVA=java hardware/pcb/scripts/build_and_route.sh 30
#   -> hardware/pcb/work/routed.kicad_pcb ; review, then copy to hardware/pcb/domofon.kicad_pcb

Autorouting is not deterministic; the committed domofon.kicad_pcb is the reviewed result.

Firmware

cd firmware/esphome
cp secrets.yaml.example secrets.yaml   # fill in Wi-Fi credentials
esphome run domofon.yaml

The DTMF components are fetched from this repository (ref: ${git_ref}, default main) by external_components in domofon.yaml, so no extra files need to be copied.

Home Assistant (ESPHome builder, recommended)

Create a new device in the HA ESPHome builder and paste firmware/esphome/intercom-package.example.yaml. It pulls domofon.yaml as a package from main with refresh: 0s (re-fetched on every build). Add the secrets from secrets.yaml.example to the builder's Secrets. The example configures the device name, API encryption, OTA, Wi-Fi, fallback AP, and captive portal; these device-level settings are kept out of the reusable firmware package. To pin a version, set git_ref in substitutions to a commit SHA or tag; it selects both domofon.yaml and the DTMF components (default main). The HA URL defaults to http://homeassistant.local:8123; override ha_url in substitutions if needed.

Voice prompts (WAV)

Prompts are generated automatically during compilation by the dtmf_tone component: "wprowadź kod", "drzwi otwarte" and "kod nieprawidłowy" are rendered by Home Assistant's Piper TTS (tts_get_url API), and ringback is a synthesized 425 Hz tone (1 s on / 4 s off). Add to the builder's Secrets:

ha_token: "<long-lived access token>"   # HA profile -> Security -> Long-lived access tokens

Results are cached in the build directory, so rebuilds work even if HA is unreachable (the first build needs HA reachable). No WAV files are needed. Voice or language can be changed per clip with tts: {text, engine, language, voice}.

Each prompt is a switch ("Domofon głos: …"). Turning it on plays the clip and the switch turns itself off when playback finishes, so an automation can turn it on and wait for off instead of watching the diagnostic "Domofon audio aktywne" sensor. The same applies to "Domofon otwórz furtkę" (the DTMF sequence). These switches do not take the line off-hook and do not change the DTMF decoder, except the gate switch, which pauses the decoder for the duration of its own tones. "Domofon sygnał oczekiwania" is the exception: it plays ringback in a loop and stays on until something turns it off (a manual turn-off, another clip starting, or hangup — including the off-hook time limit). In YAML: dtmf_tone.play_wav: {id: dtmf_gen, name: enter_code, loop: false}; stop with dtmf_tone.stop.

Enclosure

3D-printed flat wall box: 93 × 68 × 26 mm, a base glued to the wall plus a lid held by 4 countersunk M3×10 screws in brass M3 Ø4×4 heat-set inserts. The PCB is flipped (components toward the wall) and shifted +25 mm to the right, leaving a 25.3 mm left chamber.

• Seen from the room: the RJ11 plug sits inside the left chamber (plugged into J1), its flat cable exits through a 5 × 2.5 mm floor slot at the bottom of the left wall (sealed and pinched by a reinforced 5 mm thick plunger on the lid), the USB-C plug goes in from the top, and the wall cable comes in through a Ø12 mm hole in the back plate at (16.0; 15.5) mm.
• Source and print files are in hardware/enclosure/. The Polish print and assembly guide is in its README.

CNC

Machine: PrintNC + Flexi-HAL (grblHAL), sender ioSender. Ready G-code lives in cnc/gcode/. Operator guide (PL): cnc/OPERATOR_GUIDE.md. Overview / regenerate: cnc/README.md. Do not mill domofon-F_Cu-jumpers_DO_NOT_MILL.gtl — solder jumper JP1 as a wire on the component side.

Safety

• Measure the line first: idle voltage, ring voltage (DC and AC), off-hook voltage and loop current. Pick R5 to match the original handset's current (typically 20–60 mA).
• Line side is rated for ETSI ES 201 970 / TBR21 ringing (up to 100 Vrms on DC; measured idle 42 V DC): K1 AQY214EH 400 V, TVS D2 P6KE220CA (VRWM 185 V), C5 1 µF/100 V, ring-detect DC-blocking C8 0.47 µF/250 V (replaces the former 4k7 R2, same holes). On-hook the device draws no DC (otherwise the exchange sees the line off-hook). Details: design notes.
• Never connect the ESP ground to the intercom line. Power the ESP from an isolated 5 V USB supply.
• Test on a bench supply through a resistor before connecting to the building installation.
• The intercom is part of the building installation — get the administrator's consent.
• Do not connect J1 to a public telephone line.

Datasheets

Vendor datasheets are not included in the repo; see e.g. Adam Tech MTJ-642BX2, Bourns LM-NP-1001-B1L, Liteon LTV-814, Panasonic AQY214EH, Diotec P6KE220CA, WIMA MKS2 1 µF/100 V.