ESP32 SIP Client mit Headset-Unterstützung

Ein SIP-Telefon basierend auf ESP32 mit Headset-Unterstützung. Entwickelt für Thin-Client-Umgebungen ohne nativen CTI-Support.

Zwei Hardware-Varianten

Aufgrund der Hardware-Unterschiede zwischen ESP32-Chips gibt es zwei Versionen:

Variante	Chip	Headset-Typ	USB OTG	Bluetooth Classic
USB-Version	ESP32-S3	USB Headsets	Ja	Nein
Bluetooth-Version	ESP32 (WROOM)	BT Headsets	Nein	Ja (HFP)

Wichtig:

• ESP32-S3 hat kein Bluetooth Classic (nur BLE) → nur USB-Headsets
• ESP32 WROOM hat kein USB OTG → nur Bluetooth-Headsets

Features

• WiFi-Konfiguration

  • Automatischer Hotspot-Modus wenn keine WLAN-Daten konfiguriert
  • Web-basierte Konfiguration (SSID: ESP32-SIP-Phone, IP: 192.168.4.1)
  • DHCP oder statische IP-Konfiguration
  • Automatischer Fallback zu Hotspot bei Verbindungsproblemen

• USB Headsets (nur ESP32-S3)

  • USB Audio Class Unterstützung
  • USB-C direkter Anschluss oder USB-A mit Adapter
  • Automatische Erkennung

• Bluetooth Headsets (nur ESP32 WROOM)

  • HFP (Hands-Free Profile) Unterstützung
  • Mehrere Geräte pairen (>5 möglich)
  • Auto-Connect für bekannte Geräte
  • Headset-Tasten: Annehmen, Auflegen, Lautstärke

• SIP/VoIP

  • SIP-Registrierung an TK-Anlage
  • Eingehende und ausgehende Anrufe
  • G.711 µ-law und A-law Codec
  • Digest Authentication

• Weboberfläche

  • Status-Übersicht
  • WLAN-Konfiguration mit Scan
  • SIP-Einstellungen
  • Bluetooth-Geräte-Management (nur WROOM)
  • System-Einstellungen (Neustart, Werksreset)

Hardware

USB-Version (ESP32-S3)

Board:

• ESP32-S3-DevKitC-1 (oder ähnlich mit USB OTG)
• Mindestens 4MB Flash
• Optional: PSRAM für bessere Audio-Pufferung

Anschlüsse:

• USB-C (USB OTG): Für USB-Headsets
• WLAN: 2.4GHz WiFi

Bluetooth-Version (ESP32 WROOM)

Board:

• ESP32-DevKitC oder ESP32-WROOM-32
• Mindestens 4MB Flash

Anschlüsse:

• WLAN: 2.4GHz WiFi
• Bluetooth: Integriert (Classic + BLE)

Installation

ESP-IDF 5 installieren

Linux (Ubuntu/Debian)

# Abhängigkeiten installieren
sudo apt-get update
sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv \
    cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

# ESP-IDF klonen
mkdir -p ~/esp
cd ~/esp
git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git

# Tools installieren (für beide Targets)
cd ~/esp/esp-idf
./install.sh esp32,esp32s3

# Umgebung aktivieren (in jeder neuen Shell)
. ~/esp/esp-idf/export.sh

Arch Linux

# Abhängigkeiten
sudo pacman -S --needed gcc git make flex bison gperf python cmake ninja ccache dfu-util libusb

# Rest wie oben
mkdir -p ~/esp && cd ~/esp
git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && ./install.sh esp32,esp32s3
. ~/esp/esp-idf/export.sh

Windows

1. ESP-IDF Tools Installer herunterladen
2. Installer ausführen, ESP-IDF v5.2.x auswählen
3. "ESP-IDF PowerShell" oder "ESP-IDF CMD" aus Startmenü öffnen

macOS

# Xcode Command Line Tools
xcode-select --install

# Homebrew Abhängigkeiten
brew install cmake ninja dfu-util python3

# ESP-IDF klonen und installieren
mkdir -p ~/esp && cd ~/esp
git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && ./install.sh esp32,esp32s3
. ~/esp/esp-idf/export.sh

Umgebung dauerhaft aktivieren (optional)

# In ~/.bashrc oder ~/.zshrc einfügen:
alias get_idf='. ~/esp/esp-idf/export.sh'

Dann mit get_idf aktivieren.

Build für ESP32-S3 (USB-Version)

# ESP-IDF Umgebung aktivieren
. ~/esp/esp-idf/export.sh

# In Projektverzeichnis wechseln
cd /pfad/zu/bluetooth-sip-client

# Target setzen und bauen
idf.py set-target esp32s3
idf.py build flash monitor

Build für ESP32 WROOM (Bluetooth-Version)

# ESP-IDF Umgebung aktivieren
. ~/esp/esp-idf/export.sh

# In Projektverzeichnis wechseln
cd /pfad/zu/bluetooth-sip-client

# sdkconfig.defaults für ESP32 kopieren
cp sdkconfig.defaults.esp32 sdkconfig.defaults

# Target setzen und bauen
idf.py set-target esp32
idf.py build flash monitor

Tastenkürzel im Monitor:

• Ctrl+] - Monitor beenden
• Ctrl+T dann Ctrl+R - Reset

Clean Rebuild

Bei Problemen oder nach Änderungen an Dependencies:

rm -rf build managed_components dependencies.lock sdkconfig
# Dann nochmal set-target und build

Ersteinrichtung

1. ESP32 mit Strom versorgen

   • LED sollte nach Boot leuchten

2. Mit Hotspot verbinden

   • SSID: ESP32-SIP-Phone
   • Passwort: sip-phone-setup

3. Weboberfläche öffnen

   • Browser: http://192.168.4.1

4. WLAN konfigurieren

   • Tab "WLAN" → Netzwerk auswählen → Verbinden

5. SIP konfigurieren

   • Tab "SIP" → Server, Benutzername, Passwort eingeben

6. Headset verbinden

   • USB-Version: USB-Headset einstecken
   • Bluetooth-Version: Headset in Pairing-Modus → Tab "Bluetooth" → Gerät pairen

API Endpoints

Endpoint	Methode	Beschreibung
/api/status	GET	Gesamtstatus
/api/wifi/config	GET/POST	WLAN-Konfiguration
/api/wifi/scan	GET	WLAN scannen
/api/sip/config	GET/POST	SIP-Konfiguration
/api/bluetooth/devices	GET	Gepaarte BT-Geräte
/api/bluetooth/scan	POST	BT-Scan starten
/api/bluetooth/pair	POST	Gerät pairen
/api/call/answer	POST	Anruf annehmen
/api/call/hangup	POST	Anruf beenden
/api/system/reboot	POST	Neustart
/api/system/factory-reset	POST	Werksreset

Projektstruktur

bluetooth-sip-client/
├── CMakeLists.txt
├── sdkconfig.defaults           # ESP32-S3 (USB)
├── sdkconfig.defaults.esp32     # ESP32 WROOM (Bluetooth)
├── partitions.csv
└── main/
    ├── main.c                   # Hauptprogramm
    ├── config/
    │   ├── config_manager.h     # Konfiguration Header
    │   └── config_manager.c     # NVS-basierte Config
    ├── wifi/
    │   ├── wifi_manager.h       # WiFi Header
    │   └── wifi_manager.c       # WiFi AP/STA Manager
    ├── web/
    │   ├── web_server.h         # Webserver Header
    │   ├── web_server.c         # HTTP Server
    │   ├── web_api.h            # API Header
    │   ├── web_api.c            # REST API
    │   └── static/              # Web UI
    │       ├── index.html
    │       ├── style.css
    │       └── app.js
    ├── bluetooth/               # Nur aktiv auf ESP32 WROOM
    │   ├── bt_manager.h         # BT Manager Header
    │   ├── bt_manager.c         # BT Geräteverwaltung
    │   ├── bt_hfp.h             # HFP Header
    │   └── bt_hfp.c             # HFP Audio Gateway
    ├── usb_audio/               # Nur aktiv auf ESP32-S3
    │   ├── usb_audio_host.h     # USB Audio Header
    │   └── usb_audio_host.c     # USB Audio Class Host
    ├── audio/
    │   ├── audio_router.h       # Audio Router Header
    │   └── audio_router.c       # Audio Routing
    └── sip/
        ├── sip_client.h         # SIP Client Header
        ├── sip_client.c         # SIP UA Implementation
        ├── sip_parser.h         # SIP Parser Header
        └── sip_parser.c         # SIP Message Parser

Einschränkungen

• ESP32-S3: Kein Bluetooth Classic - nur USB-Headsets möglich
• ESP32 WROOM: Kein USB OTG - nur Bluetooth-Headsets möglich
• Bluetooth: Maximal 3-4 gleichzeitig aktive Verbindungen
• USB Audio: Grundlegende UAC1 Unterstützung
• Codecs: Aktuell nur G.711 (PCMU/PCMA)
• SRTP: Nicht unterstützt (nur unverschlüsseltes RTP)

Troubleshooting

Kein WLAN nach Konfiguration

• Gerät neu starten
• Hotspot sollte nach 30 Sekunden automatisch starten

Bluetooth Headset verbindet nicht (nur WROOM)

• Headset zurücksetzen und erneut pairen
• Andere Bluetooth-Verbindungen am Headset trennen

USB Headset wird nicht erkannt (nur S3)

• USB-Kabel prüfen (muss Datenkabel sein, nicht nur Ladekabel)
• Anderes USB-Headset testen

Kein Audio bei Anruf

• Audio-Routing prüfen im Status-Tab
• Headset-Verbindung prüfen

Lizenz

MIT License