Skip to content

Latest commit

 

History

History
547 lines (423 loc) · 14.7 KB

README.md

File metadata and controls

547 lines (423 loc) · 14.7 KB

ATS Mini Custom Firmware - Bluetooth Edition

🇪🇸 Español | 🇬🇧 English

English

Custom firmware for ATS Mini radio receiver with Bluetooth LE support and custom boot logo.

Version: 1.4 Date: October 20, 2025 Hardware: ESP32-S3-WROOM-1-N16R8 (16MB Flash + 8MB PSRAM)

✨ Features

  • ✅ Bluetooth LE with Nordic UART Service (NUS)
  • ✅ WiFi/BLE automatic mutual exclusion (only one active at a time)
  • ✅ Custom boot logo (2 seconds at startup)
  • ✅ Logo embedded in firmware (no SPIFFS required)
  • ✅ Compatible with USB Serial (dual mode)
  • ✅ Low power consumption with BLE optimization

📦 Precompiled Binaries

Located in binaries/ directory:

Option A - Single File (⭐ RECOMMENDED)

  • ats-mini.ino.merged.bin (16 MB)
    • All-in-one: bootloader + partitions + firmware + boot logo
    • Flash at address 0x0
    • Custom logo included (displays for 2 seconds at boot)

Option B - Separate Files

  • ats-mini.ino.bootloader.bin (20 KB) → Flash at 0x0
  • ats-mini.ino.partitions.bin (3 KB) → Flash at 0x8000
  • ats-mini.ino.bin (1.7 MB) → Flash at 0x10000

🚀 Quick Start - Flash Firmware

Method 1: Web Browser (Easiest - Chrome/Edge only)

  1. Open https://espressif.github.io/esptool-js/
  2. Connect ATS Mini via USB and power it on
  3. Click "Connect" and select the serial port
  4. Add binaries/ats-mini.ino.merged.bin at address 0x0
  5. Click "Program"
  6. Wait for "Leaving... Hard resetting via RTS pin..."
  7. Power cycle the receiver

Method 2: esptool.py (Mac/Linux/Windows)

Install esptool:

pip install esptool

Flash merged firmware (recommended):

# Mac/Linux
esptool.py --chip esp32s3 --port /dev/cu.usbmodem101 \
  --baud 921600 write_flash 0x0 binaries/ats-mini.ino.merged.bin

# Windows
esptool.py --chip esp32s3 --port COM3 \
  --baud 921600 write_flash 0x0 binaries\ats-mini.ino.merged.bin

Flash separate files:

# Mac/Linux
esptool.py --chip esp32s3 --port /dev/cu.usbmodem101 \
  --baud 921600 write_flash \
  0x0 binaries/ats-mini.ino.bootloader.bin \
  0x8000 binaries/ats-mini.ino.partitions.bin \
  0x10000 binaries/ats-mini.ino.bin

# Windows
esptool.py --chip esp32s3 --port COM3 \
  --baud 921600 write_flash \
  0x0 binaries\ats-mini.ino.bootloader.bin \
  0x8000 binaries\ats-mini.ino.partitions.bin \
  0x10000 binaries\ats-mini.ino.bin

For detailed instructions, see binaries/FLASH_INSTRUCTIONS.md

📖 Documentation

🛠️ Development Setup

Prerequisites

  • Arduino IDE 2.x or PlatformIO
  • ESP32 Arduino Core 3.0+
  • USB-C cable for programming
  • ATS Mini hardware

Required Libraries

Install via Arduino Library Manager or PlatformIO:

SI4735 by PU2CLR (pu2clr/SI4735)
TFT_eSPI
NimBLE-Arduino
Preferences (included in ESP32 core)
WiFi (included in ESP32 core)

Arduino IDE Setup

  1. Install ESP32 Board Support

    • Open Arduino IDE
    • File > Preferences
    • Add to "Additional Board Manager URLs": 
      https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
    • Tools > Board > Boards Manager
    • Search "esp32" and install "esp32 by Espressif Systems" (v3.0+)

  2. Board Configuration

    • Board: "ESP32S3 Dev Module"
    • USB CDC On Boot: "Enabled"
    • Flash Size: "16MB (128Mb)"
    • PSRAM: "OPI PSRAM"
    • Partition Scheme: "16M Flash (3MB APP/9.9MB FATFS)"
    • Upload Speed: "921600"

  3. Configure TFT_eSPI

    • Edit libraries/TFT_eSPI/User_Setup.h
    • Or use the tft_setup.h configuration from this project

Build from Source

  1. Clone the Repository

    git clone https://github.com/rodillo69/ATS-Mini-Companion.git
cd ATS-Mini-Companion/firmware/ats-mini

  2. Open in Arduino IDE

    # Open ats-mini.ino
open ats-mini/ats-mini.ino  # macOS

  3. Install Dependencies

    • Tools > Manage Libraries
    • Install all required libraries listed above

  4. Compile

    • Sketch > Verify/Compile
    • Check for errors

  5. Upload

    • Connect ATS Mini via USB
    • Tools > Port > Select your port
    • Sketch > Upload

PlatformIO Setup

[env:esp32-s3-devkitc-1]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino

board_build.flash_size = 16MB
board_build.psram_type = opi
board_build.partitions = default_16MB.csv

lib_deps =
    pu2clr/SI4735@^2.1.4
    bodmer/TFT_eSPI@^2.5.0
    h2zero/NimBLE-Arduino@^1.4.0

build_flags =
    -DBOARD_HAS_PSRAM
    -DARDUINO_USB_CDC_ON_BOOT=1

📂 Source Code Structure

firmware/
├── ats-mini/                   # Arduino source code
│   ├── ats-mini.ino           # Main sketch
│   ├── Ble.cpp / Ble.h        # Bluetooth LE module
│   ├── Network.cpp            # WiFi module
│   ├── Common.h               # Common definitions
│   ├── SI4735-fixed.h         # Radio chip interface
│   ├── Storage.cpp            # EEPROM/Preferences
│   ├── Draw.cpp               # Display rendering
│   ├── Menu.cpp               # Menu system
│   ├── Scan.cpp               # Frequency scanning
│   ├── Utils.cpp              # Utilities
│   ├── EIBI.cpp               # Station database
│   ├── splash_data.h          # Boot logo data
│   └── tft_setup.h            # Display configuration
│
├── binaries/                   # Compiled firmware
│   ├── ats-mini.ino.merged.bin
│   ├── ats-mini.ino.bootloader.bin
│   ├── ats-mini.ino.partitions.bin
│   ├── ats-mini.ino.bin
│   ├── CHECKSUMS.txt
│   └── FLASH_INSTRUCTIONS.md
│
├── docs/                       # Documentation
│   ├── BLUETOOTH_IMPLEMENTATION.md
│   └── NOTAS_VERSION.md
│
└── README.md                   # This file

🔧 Key Modules

Bluetooth LE (Ble.cpp / Ble.h)

  • Service: Nordic UART Service (NUS)
  • UUIDs:
    • Service: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E
    • RX (Write): 6E400002-B5A3-F393-E0A9-E50E24DCCA9E
    • TX (Notify): 6E400003-B5A3-F393-E0A9-E50E24DCCA9E
  • Features:
    • Command reception via RX characteristic
    • Status broadcast via TX characteristic (every 500ms)
    • Automatic WiFi/BLE mutual exclusion
    • Connection state management

WiFi Management (Network.cpp)

  • Automatic disconnection when BLE activates
  • WiFi station and AP modes
  • NTP time synchronization

Radio Control (SI4735-fixed.h)

  • SI4735/SI4732 chip interface
  • AM/FM/SSB modes
  • Frequency tuning
  • Signal quality monitoring

Display (Draw.cpp)

  • TFT display rendering
  • Custom boot logo
  • UI updates
  • Theme support

🔨 Customization

Change Boot Logo

  1. Create your image

    • Size: 320x170 pixels
    • Format: RGB565 (16-bit color)

  2. Convert to C array

    # Use image2cpp or similar tool
# Output format: const uint16_t splash_data[] PROGMEM = { ... };

  3. Replace in splash_data.h

    #define SPLASH_WIDTH 320
#define SPLASH_HEIGHT 170
const uint16_t splash_data[] PROGMEM = {
  // Your image data here
};

  4. Recompile and flash

Modify Bluetooth Behavior

Edit Ble.cpp:

// Change device name
#define BLE_DEVICE_NAME "Your-Custom-Name"

// Change broadcast interval
#define BLE_STATUS_INTERVAL 500  // milliseconds

// Modify status data format
String bleGetStatusData() {
  // Customize CSV format
  return customData;
}

🐛 Troubleshooting

Compilation Errors

Error: TFT_eSPI.h: No such file or directory

# Install TFT_eSPI library
arduino-cli lib install "TFT_eSPI"

Error: NimBLEDevice.h: No such file or directory

# Install NimBLE-Arduino library
arduino-cli lib install "NimBLE-Arduino"

Error: SI4735.h: No such file or directory

# Install SI4735 library
arduino-cli lib install "SI4735"

Upload Issues

Problem: Board not detected

  • Check USB cable (must support data transfer)
  • Install CP210x or CH340 drivers if needed
  • Try different USB port

Problem: Upload fails

  • Enter bootloader mode: Hold BOOT + press RESET
  • Release RESET, then release BOOT
  • Try upload again

Problem: "Timed out waiting for packet header"

  • Lower baud rate: Tools > Upload Speed > 115200
  • Check USB cable quality
  • Try shorter USB cable

📊 Technical Specifications

Hardware

  • MCU: ESP32-S3-WROOM-1-N16R8
  • Flash: 16MB
  • PSRAM: 8MB OPI QSPI
  • Radio Chip: SI4735/SI4732
  • Display: 320x170 TFT LCD

Firmware

  • Framework: Arduino ESP32 v3.0+
  • BLE Stack: NimBLE
  • Size: ~1.7MB (86% flash usage)
  • RAM Usage: ~200KB

BLE Protocol

  • Service: Nordic UART Service (NUS)
  • MTU: 512 bytes
  • Data Format: CSV (15 fields)
  • Update Rate: 500ms
  • Range: ~10 meters

📜 Version History

v1.4 (Current - Bluetooth Edition)

  • NEW: Bluetooth LE with Nordic UART Service
  • NEW: WiFi/BLE automatic mutual exclusion
  • NEW: Custom boot logo embedded in firmware
  • IMPROVED: Memory management
  • IMPROVED: Connection stability

📄 License

This project is based on the original ATS Mini firmware and is licensed under MIT License.

🙏 Credits

  • Original ATS Mini: ESP32-SI4732 community
  • SI4735 Library: PU2CLR (Ricardo Lima Caratti)
  • Bluetooth Implementation: EA5IYR - Miguel Cañadas

Español

Firmware personalizado para el receptor de radio ATS Mini con soporte Bluetooth LE y logo de arranque personalizado.

Versión: 1.4 Fecha: 20 Octubre 2025 Hardware: ESP32-S3-WROOM-1-N16R8 (16MB Flash + 8MB PSRAM)

✨ Características

  • ✅ Bluetooth LE con Nordic UART Service (NUS)
  • ✅ Exclusión mutua WiFi/BLE automática (solo uno activo a la vez)
  • ✅ Logo personalizado al arranque (2 segundos al inicio)
  • ✅ Logo embebido en firmware (no requiere SPIFFS)
  • ✅ Compatible con USB Serial (modo dual)
  • ✅ Bajo consumo con optimización BLE

📦 Binarios Precompilados

Ubicados en el directorio binaries/:

Opción A - Archivo Único (⭐ RECOMENDADO)

  • ats-mini.ino.merged.bin (16 MB)
    • Todo en uno: bootloader + particiones + firmware + logo
    • Flashear en dirección 0x0
    • Logo personalizado incluido (se muestra 2 segundos al arrancar)

Opción B - Archivos Separados

  • ats-mini.ino.bootloader.bin (20 KB) → Flashear en 0x0
  • ats-mini.ino.partitions.bin (3 KB) → Flashear en 0x8000
  • ats-mini.ino.bin (1.7 MB) → Flashear en 0x10000

🚀 Inicio Rápido - Flashear Firmware

Método 1: Navegador Web (Más fácil - Solo Chrome/Edge)

  1. Abrir https://espressif.github.io/esptool-js/
  2. Conectar ATS Mini por USB y encender
  3. Clic en "Connect" y seleccionar puerto serial
  4. Añadir binaries/ats-mini.ino.merged.bin en dirección 0x0
  5. Clic en "Program"
  6. Esperar "Leaving... Hard resetting via RTS pin..."
  7. Reiniciar el receptor

Método 2: esptool.py (Mac/Linux/Windows)

Instalar esptool:

pip install esptool

Flashear firmware merged (recomendado):

# Mac/Linux
esptool.py --chip esp32s3 --port /dev/cu.usbmodem101 \
  --baud 921600 write_flash 0x0 binaries/ats-mini.ino.merged.bin

# Windows
esptool.py --chip esp32s3 --port COM3 \
  --baud 921600 write_flash 0x0 binaries\ats-mini.ino.merged.bin

Flashear archivos separados:

# Mac/Linux
esptool.py --chip esp32s3 --port /dev/cu.usbmodem101 \
  --baud 921600 write_flash \
  0x0 binaries/ats-mini.ino.bootloader.bin \
  0x8000 binaries/ats-mini.ino.partitions.bin \
  0x10000 binaries/ats-mini.ino.bin

# Windows
esptool.py --chip esp32s3 --port COM3 \
  --baud 921600 write_flash \
  0x0 binaries\ats-mini.ino.bootloader.bin \
  0x8000 binaries\ats-mini.ino.partitions.bin \
  0x10000 binaries\ats-mini.ino.bin

Para instrucciones detalladas, ver binaries/FLASH_INSTRUCTIONS.md

📖 Documentación

🛠️ Configuración de Desarrollo

Requisitos Previos

  • Arduino IDE 2.x o PlatformIO
  • ESP32 Arduino Core 3.0+
  • Cable USB-C para programación
  • Hardware ATS Mini

Librerías Requeridas

Instalar vía Arduino Library Manager o PlatformIO:

SI4735 by PU2CLR (pu2clr/SI4735)
TFT_eSPI
NimBLE-Arduino
Preferences (incluida en ESP32 core)
WiFi (incluida en ESP32 core)

Configuración Arduino IDE

  1. Instalar Soporte para ESP32

    • Abrir Arduino IDE
    • Archivo > Preferencias
    • Añadir a "Gestor de URLs Adicionales de Tarjetas": 
      https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
    • Herramientas > Placa > Gestor de Tarjetas
    • Buscar "esp32" e instalar "esp32 by Espressif Systems" (v3.0+)

  2. Configuración de la Placa

    • Placa: "ESP32S3 Dev Module"
    • USB CDC On Boot: "Enabled"
    • Flash Size: "16MB (128Mb)"
    • PSRAM: "OPI PSRAM"
    • Partition Scheme: "16M Flash (3MB APP/9.9MB FATFS)"
    • Upload Speed: "921600"

  3. Configurar TFT_eSPI

    • Editar libraries/TFT_eSPI/User_Setup.h
    • O usar la configuración tft_setup.h de este proyecto

Compilar desde Código Fuente

  1. Clonar el Repositorio

    git clone https://github.com/rodillo69/ATS-Mini-Companion.git
cd ATS-Mini-Companion/firmware/ats-mini

  2. Abrir en Arduino IDE

    # Abrir ats-mini.ino
open ats-mini/ats-mini.ino  # macOS

  3. Instalar Dependencias

    • Herramientas > Administrar Bibliotecas
    • Instalar todas las librerías requeridas listadas arriba

  4. Compilar

    • Programa > Verificar/Compilar
    • Verificar errores

  5. Subir

    • Conectar ATS Mini por USB
    • Herramientas > Puerto > Seleccionar tu puerto
    • Programa > Subir

Para más detalles sobre desarrollo y personalización, ver la sección en inglés arriba.

📄 Licencia

Este proyecto está basado en el firmware original ATS Mini y está licenciado bajo MIT License.

🙏 Créditos

  • ATS Mini Original: Comunidad ESP32-SI4732
  • Librería SI4735: PU2CLR (Ricardo Lima Caratti)
  • Implementación Bluetooth: EA5IYR - Miguel Cañadas