blanco-esp32

BLE-to-MQTT gateway for the BLANCO CHOICE.All kitchen faucet, running on an ESP32.

The ESP32 connects to the faucet via Bluetooth Low Energy (BLE), authenticates, and exposes its status and controls over MQTT. This makes the BLE-only faucet integrable into any MQTT-based smart home system (Home Assistant, openHAB, Node-RED, etc.).

Features

• BLE connection to the BLANCO CHOICE.All faucet with PIN-based authentication (SHA-256)
• Periodic status polling (every 15 minutes, configurable)
• MQTT status publishing with device information, filter status, CO2 level, temperatures, and error codes
• Water dispensing via MQTT command (amount and CO2 intensity configurable)
• Automatic reconnection on WiFi/MQTT/BLE connection loss
• Exponential backoff on repeated crashes (RTC memory based)
• MQTT Last Will and Testament for availability detection

Hardware

• ESP32-S3-DevKitC-1 (or any compatible ESP32-S3 board)
• No additional hardware required — the board only uses its built-in WiFi and BLE radios

Note: The code does not use any ESP32-S3-specific features and also runs on a classic ESP32 (e.g. ESP32-DevKitC). Simply change the board in platformio.ini to esp32dev. The Blanco BLE protocol does not require BLE 5.0, so BLE 4.2 on the classic ESP32 is sufficient.

Dependencies

Library	Version	Purpose
NimBLE-Arduino	^1.4	BLE stack (GATT client)
ArduinoJson	^7	JSON serialization for BLE protocol and MQTT
PubSubClient	^2.8	MQTT client

All dependencies are resolved automatically via PlatformIO.

Setup

1. Clone the repository

git clone https://github.com/bruestel/blanco-esp32.git
cd blanco-esp32

2. Create the configuration

cp include/config.example.h include/config.h

Then fill in include/config.h with your own values:

// WiFi
#define WIFI_SSID     "YOUR_WIFI_SSID"
#define WIFI_PASSWORD "YOUR_WIFI_PASSWORD"

// MQTT
#define MQTT_BROKER   "YOUR_MQTT_BROKER_IP"
#define MQTT_PORT     1883
#define MQTT_USER     ""    // leave empty if not required
#define MQTT_PASS     ""

// Blanco Device
#define BLANCO_MAC    "34:5F:45:E8:E7:76"   // BLE MAC address of the faucet
#define BLANCO_PIN    "00000"                // 5-digit PIN of the faucet

// Timing
#define POLL_INTERVAL_S  900   // Status poll interval in seconds (default: 15 min)

Note: config.h is listed in .gitignore and will not be committed to the repository.

3. Build and flash the firmware

Prerequisite: PlatformIO (CLI or VS Code extension)

pio run -t upload

4. Open the serial monitor (optional)

pio device monitor

MQTT Interface

All topics follow the pattern blanco/<mac>/..., where <mac> is the Blanco faucet's BLE MAC address (as configured in BLANCO_MAC) in lowercase without colons.

Publish (Gateway → Broker)

Topic	Retained	Description
blanco/<mac>/available	Yes	"online" or "offline" (LWT)
blanco/<mac>/status	Yes	Full device status as JSON (see below)
blanco/<mac>/command/result	No	"success" or "failed" after dispensing

Subscribe (Broker → Gateway)

Topic	Description
blanco/<mac>/command/dispense	Start water dispensing (JSON)
blanco/<mac>/command/refresh	Trigger an immediate status refresh

Status Payload

{
  "device": {
    "device_name": "...",
    "serial_number": "...",
    "service_code": "...",
    "firmware": {
      "main": "...",
      "comm": "...",
      "elec": "..."
    }
  },
  "status": {
    "filter_rest": 100,
    "co2_rest": 95,
    "temp_boiler_1": 7,
    "temp_boiler_2": 90,
    "temp_compressor": 35,
    "error_bits": 0
  },
  "last_update": "3600s uptime"
}

Dispense Command

{
  "amount": 200,
  "intensity": 1
}

Parameter	Type	Description
amount	int	Water amount in milliliters (default: 200, min: 50)
intensity	int	CO2 carbonation level: 1 = still, 2 = medium, 3 = high (default: 1)

Project Structure

blanco-esp32/
├── platformio.ini           # Build configuration
├── src/
│   └── main.cpp             # Main application (WiFi, MQTT, BLE orchestration)
├── include/
│   ├── config.example.h     # Configuration template
│   ├── config.h             # Your configuration (not in repo)
│   ├── blanco_client.h      # High-level BLE client (pairing, status, dispense)
│   ├── blanco_transport.h   # BLE transport layer (packet fragmentation)
│   └── blanco_auth.h        # SHA-256 token authentication
└── .gitignore

Error Handling

• On BLE connection loss or failure, the ESP32 automatically reboots
• A crash counter in RTC memory provides exponential backoff (3s → 6s → 12s → ... → max 180s) on repeated crashes
• The crash counter is reset after the first successful status read
• WiFi and MQTT connections are automatically re-established

Acknowledgments

This project is based on the excellent work of blanco_unit by @Nailik. The reverse engineering of the BLANCO BLE protocol and the implementation provided there served as the foundation for this project. Many thanks for the great work!

License

This project is licensed under the MIT License. See LICENSE for details.