DECtalk ESPress Firmware

An ESP32 firmware for ESP32-S3 and ESP32-C6 boards that turns a microcontroller into a standalone DECtalk text-to-speech device. The firmware boots directly into the DECtalk ESPress serial protocol, allowing a host computer to send text and receive status exactly as it would with a vintage DECtalk Express hardware unit. On ESP32-S3 the host link uses USB CDC-ACM; on ESP32-C6 it uses the built-in USB Serial/JTAG interface. The documented photographed hardware build in HARDWARE.md is an ESP32-C6 perfboard build; ESP32-S3 remains a supported firmware target, but it is not the specific physical build documented there.

The speech synthesis itself is provided by the DECtalk component (components/dectalk/) which cross-compiles the upstream dapi library as a reusable ESP-IDF component. See the component README for component-specific documentation (language selection, dictionary storage modes, source resolution, porting notes).

For detailed build instructions, toolchain setup, and architecture notes see BUILD.md.

Acknowledgments

This project wouldn't exist without the efforts of the dectalk/dectalk project and the DECtalk community. Thank you for preserving and advancing DECtalk for everyone.

Table of Contents

• Key Features
• Hardware Requirements
• Wiring
• Physical Device Build
• Quick Start
• Web Flasher
• Web GUI
• Release Build Workflow
• Serial Interfaces
• ESPress Protocol Summary
• Host Tools
• Custom [:fw …] Commands
• Configuration (menuconfig)
  • DECtalk (component settings)
  • DECtalk ESPress Firmware (application settings)
• Troubleshooting
• License
• References

Key Features

• ESPress serial protocol — drop-in replacement for a real DECtalk Express: plain-ASCII text input, ETX flush, ENQ status query, SO/SI pause/resume, DLE command sequences, XON/XOFF flow control
• Native USB host transport — ESP32-S3 uses TinyUSB CDC-ACM and ESP32-C6 uses USB Serial/JTAG, both appearing as standard serial ports to the host (for example COM, /dev/ttyACM*, or /dev/ttyUSB* depending on board and driver); no external UART adapter needed
• I2S audio output — 11.025 kHz, 16-bit mono via I2S to an external DAC (PCM5102, MAX98357A, etc.)
• Configurable via menuconfig — I2S pins, DMA tuning, flow-control thresholds, task pinning, and more; no source edits needed
• Python host tools — a serial API module (dtesp_serial.py) and GUI applications for controlling the device from a PC
• Browser-based Web GUI — control the device directly from Chrome or Edge via the Web Serial API; no install required
• Memory diagnostics — optional runtime task that logs per-task stack high-water marks and heap fragmentation statistics
• Full DECtalk speech synthesis — provided by the DECtalk component, supporting six languages and three dictionary storage modes

Hardware Requirements

Board selection note: The firmware currently supports ESP32-S3 and ESP32-C6. sdkconfig.defaults sets CONFIG_IDF_TARGET="esp32s3" by default; run idf.py set-target esp32c6 when building for ESP32-C6 so ESP-IDF also applies sdkconfig.defaults.esp32c6.

Port usage: On ESP32-S3, the UART-side USB connection is for reflashing and console logs while the native USB CDC port is reserved for normal runtime host↔︎ESPress protocol communication. On ESP32-C6, the built-in USB Serial/JTAG port is now supported for host communication; the firmware disables the RTS-triggered reset so opening the port does not reboot the device.

Memory note: PSRAM is not strictly required to run the firmware because the ESPress application itself fits within the base 512 KB RAM budget. However, dictionary storage mode matters: embedded dictionaries and dedicated dictionary partitions can work without PSRAM, while loading the dictionary from a SPIFFS file uses additional heap, so a modest PSRAM size (roughly 2 MB, depending on filesystem size and usage) is recommended.

Wiring

Current default I2S pin assignments (configurable via idf.py menuconfig → DECtalk ESPress Firmware → Audio output):

PCM5102 notes — short SCK→GND (internal PLL), FLT→GND, DEMP→GND, FMT→GND.

MAX98357A notes — connect a 4–8 Ω speaker directly to the amplifier output terminals.

TLV320DAC3100 (Adafruit breakout) notes — the TLV320DAC3100 adds I2C control pins on top of the basic I2S wiring. The current Kconfig defaults are:

The optional TLV320 MCLK output is disabled by default (-1). If you wire MCLK, set it explicitly in idf.py menuconfig → DECtalk ESPress Firmware → Audio output. Select Adafruit TLV320DAC3100 breakout as the Audio DAC to expose the codec I2C, reset, interrupt, MCLK, and DSP-default settings.

Quick Start

# 1. Source the ESP-IDF environment
. ~/esp/esp-idf/export.sh

# 2. Navigate to the project directory
cd DECtalk_ESPress

# 3. Select the target if needed
# idf.py set-target esp32c6

# 4. Build (dictionary is compiled automatically)
idf.py build

# 5. Flash firmware
idf.py -p /dev/ttyUSB0 flash

# 6. Monitor console logs (UART0 or your board's console port)
idf.py -p /dev/ttyUSB0 monitor

For ESP32-S3, the runtime host port is the board's native USB CDC-ACM device (typically /dev/ttyACM0 on Linux). For ESP32-C6, use the native USB Serial/JTAG port exposed by the board. Open the port at any baud rate and start sending text.

See BUILD.md for full prerequisites and configuration options.

Web Flasher

The published project site includes a browser-based flasher for installing released firmware without setting up ESP-IDF locally.

1. Open the project site and click Web Flasher in the top navigation.
2. Use Chrome or Edge (version 89 or newer) so the page can access the board over the browser's Web Serial API.
3. Connect the board's UART flashing/debug USB port to your computer, click Connect, and choose the serial device for that port.
4. Select the desired Release and Language, then click Flash Firmware.
5. If you already downloaded a release archive from GitHub, click Flash from File… and select the .tar.gz / .tgz file instead.

After flashing finishes, unplug or close the flashing connection if needed and use the board's runtime host port: native USB CDC on ESP32-S3 or USB Serial/JTAG on ESP32-C6.

Web GUI

The published project site includes a browser-based GUI for controlling the device without installing any software.

1. Open the project site and click Web GUI in the top navigation.
2. Use Chrome or Edge (version 89 or newer) — the page requires the Web Serial API.
3. Connect the board's runtime host port to your computer, click Connect, and select the ESP32 serial port from the browser chooser.
4. Choose a voice, adjust rate and pitch with the sliders, type text in the text box, and click Speak.

The Web GUI mirrors the Qt desktop GUI feature-for-feature: voice / rate / pitch controls, Pause / Resume / Flush / Query Status buttons, an Audio Settings dialog (volume, EQ presets, DRC, speaker gain), a Device Status panel, and a timestamped Communications Log.

Browser support: the Web Serial API is available only in Chromium-based browsers (Chrome, Edge, Opera, …) on desktop. Firefox and Safari are not supported. On Linux, ensure your user has access to the serial device (typically by being in the dialout or uucp group).

See host/README.md for full Web GUI documentation.

Release Build Workflow

GitHub Actions includes a release-build workflow at .github/workflows/release.yml. It builds firmware binaries and the matching dictionary for all six DECtalk languages on both supported targets (ESP32-S3 and ESP32-C6), uploads each language/target combination as a workflow artifact, and attaches the packaged artifacts to published GitHub releases.

Serial Interfaces

The firmware's host transport depends on the target:

On ESP32-S3, this separation means log output never corrupts the ESPress byte stream and protocol debugging is straightforward. On ESP32-C6, the built-in USB Serial/JTAG interface is used for host communications instead.

Transport note: ESP32-S3 keeps using TinyUSB CDC-ACM because its built-in USB Serial/JTAG peripheral reboots the chip when the host toggles DTR. ESP32-C6 now uses USB Serial/JTAG for host communication, with the RTS-triggered reset explicitly disabled in firmware so opening the port does not reboot the chip.

ESPress Protocol Summary

The firmware boots directly into ESPress protocol mode — no handshake or mode-switch command is needed. When the host opens the transport port, the firmware detects the new connection and responds with a protocol-state reset and XON.

See main/dtesp.h for the full protocol constant definitions and encoding/decoding helpers.

Host Tools

The host/ directory contains host software for controlling the device. See host/README.md for full details.

• web/index.html — browser-based Web GUI; no install required; runs in Chrome or Edge 89+ using the Web Serial API. Also hosted on the project site — click Web GUI in the top navigation.
• dtesp_serial.py — DECtalkESPressSerial class implementing the ESPress protocol: connect, speak, flush, pause/resume, status query, device detection.
• dtesp_gui_qt.py — Qt GUI with voice/rate/pitch controls, pause/resume/flush buttons, device status panel, and a communications log.

from dtesp_serial import DECtalkESPressSerial

dt = DECtalkESPressSerial()
dt.connect("/dev/ttyACM0")
dt.speak("Hello from DECtalk on ESP32.", voice="Betty", rate=180)
dt.disconnect()

Custom [:fw …] Commands

Text passed through the ESPress protocol may contain custom [:fw <sub-command> <args…>] directives. These are intercepted before DECtalk sees them and run as firmware-side actions.

Session / GPIO / Tone commands:

Codec / output commands (TLV320DAC3100):

On-chip DSP tone controls — these exploit the TLV320DAC3100's built-in biquad/IIR engine and have no CPU cost:

Why EQ helps DECtalk TTS

DECtalk speech at 11 kHz has most of its energy in 200 Hz–4 kHz. Perceived muddiness usually comes from excess 150–400 Hz output plus weak 2–5 kHz; perceived crispness lives in the 2–4 kHz "presence" band plus 4–5 kHz "sibilance". Good default tunings therefore cut the bass mud and boost presence — which is exactly what the built-in presets do:

• speech — gentle bass cut, 500 Hz cut, 3 kHz boost, 4.5 kHz treble boost, mild DRC. Recommended starting point for TTS.
• crisp — more aggressive 3 kHz + 5 kHz boost for extra intelligibility.
• warm — gentle bass lift, no treble boost.

All tone-control values are clamped to ±12 dB. Each biquad coefficient is stored as Q1.23 two's-complement and applied live via a brief soft-mute so transitions are silent. The complete state (EQ + DRC + speaker gain) is persisted to NVS by [:fw save].

Example:

[:fw eq preset speech] [:fw save] The quick brown fox.

Configuration (menuconfig)

Settings are split across two menus in idf.py menuconfig:

DECtalk (component settings)

These settings are defined by the DECtalk component and control the text-to-speech library itself. See the component README for details.

DECtalk ESPress Firmware (application settings)

These settings are defined by the firmware application and control the ESPress protocol emulation, hardware interfaces, and runtime behaviour.

Troubleshooting

License

This firmware is licensed under the MIT License — see LICENSE.

References

• BUILD.md — detailed firmware build process and architecture
• host/README.md — host tools documentation (Web GUI, Qt GUI, Python API)
• components/dectalk/README.md — DECtalk component: language, dictionary, source resolution
• components/dectalk/BUILD.md — DECtalk component: build process, porting notes
• ESP-IDF Programming Guide
• ESP-IDF I2S Driver
• TinyUSB CDC-ACM
• ESP-IDF USB Serial/JTAG