https://github.com/nodestark/mdb-esp32-master
ESP32-based MDB Vending Machine Controller (VMC) with support for bill validators, coin changers, cashless devices, and EVA-DTS DEX/DDCMP telemetry for vending machine integration and management.
https://github.com/nodestark/mdb-esp32-master
esp32 iot nuttx protocol-mdb vending-machine
Last synced: 1 day ago
JSON representation
ESP32-based MDB Vending Machine Controller (VMC) with support for bill validators, coin changers, cashless devices, and EVA-DTS DEX/DDCMP telemetry for vending machine integration and management.
- Host: GitHub
- URL: https://github.com/nodestark/mdb-esp32-master
- Owner: nodestark
- License: mit
- Created: 2026-05-30T14:44:17.000Z (30 days ago)
- Default Branch: main
- Last Pushed: 2026-06-19T13:05:29.000Z (10 days ago)
- Last Synced: 2026-06-19T15:10:23.752Z (10 days ago)
- Topics: esp32, iot, nuttx, protocol-mdb, vending-machine
- Language: C
- Homepage: https://vmflow.xyz
- Size: 924 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://discord.gg/YgnusQaDHM)
[](LICENSE)
[](https://docs.espressif.com/projects/esp-idf/)
# VMflow — MDB ESP32 Vending Machine Controller
**A micro vending machine controller (VMC) on the ESP32, speaking native MDB to real peripherals.**
---
This project implements the **MDB master / Vending Machine Controller (VMC)** side of the [Multi-Drop Bus](https://en.wikipedia.org/wiki/Multidrop_bus) protocol. The ESP32 acts as the brain of a micro vending machine: it powers the 9-bit MDB bus and polls real peripherals — coin changer, bill validator, and cashless readers — driving the full deposit → credit → vend → audit cycle. It runs on **any ESP32**, and ships with a bare-metal **KiCad** board that provides the sockets and level/current bridges required for MDB.
The board exposes **two independent MDB ports** — a **controller port** and a **target port**. On the **controller port** the board is the master (VMC): it drives the peripherals — coin changer, bill validator, cashless reader. On the **target port** the board is a slave: it emulates a peripheral and talks to the vending machine's VMC/master. This firmware uses the controller port.
# Features
- **MDB master / VMC** firmware implementing the bus poll loop, ACK/NAK/RET handling, and 9-bit address/mode framing
- Talks to the standard MDB peripherals:
- **Coin Changer** (moedeiro, address `0x08`) — setup, tube status, coin-type enable, deposited credit
- **Bill Validator** (noteiro, address `0x30`) — setup, security, bill-type enable, escrow/stacker
- **Cashless reader #1** (`0x10`) and **#2** (`0x60`) — reset/setup/poll/vend/reader session flow
- **Combined cash + cashless** vend logic: accumulates coin and bill credit, deducts on vend, and reports cash sales back to the cashless device for audit
- **EVA-DTS DEX** interface over a dedicated UART for reading machine audit data
- **WS2812 status LED** indicating MDB bus state
- Product-selection button (GPIO0) to trigger a vend on the selected coil
- **Dual MDB ports**: drive peripherals as a VMC on the controller port, or act as a peripheral on the target port
- Bare-metal **KiCad** hardware: MDB sockets + bridges, designed for low-cost production and customization
- Part of the open **VMflow** platform — pairs with the [📊 Web Dashboard](https://vmflow.xyz/dashboard) for telemetry, sales, inventory, and AI-powered diagnostics
# Hardware
The companion board (KiCad project [`kicad/`](kicad)) carries the ESP32-S3 module and the MDB interface bridge (TX/RX opto-isolation and the 9-bit UART path) plus the peripheral socket. Shared on PCBWay:
👉 **[MDB ESP32 Bridge Device — PCBWay](https://www.pcbway.com/project/shareproject/MDB_ESP32_Bridge_Device_ca013cf8.html)**
[](https://www.pcbway.com/project/member/?bmbno=1B3B95CB-4E28-4D)
### MDB ports & pinout (default)
Two MDB ports — name reflects the board's role on each:
| Port | RX | TX | Board role | Connects to |
|-----------------|-----|-----|---------------------|----------------------------------------------|
| **Controller** | IO1 | IO2 | master (VMC) | peripherals: coin changer, bill validator, cashless |
| **Target** | IO4 | IO5 | slave (peripheral) | the vending machine's VMC/master |
This VMC firmware uses the **controller port** (master): peripherals plug in here. The **target port** lets the board act as a peripheral driven by an external VMC.
Other pins:
| Signal | GPIO | Note |
|---------------|------|------------------------------|
| MDB state LED | 21 | WS2812 status LED |
| DEX RX | 18 | EVA-DTS / DDCMP |
| DEX TX | 17 | EVA-DTS / DDCMP |
| Vend button | 0 | product select (active low) |
MDB UART: 9600 baud, 9 data bits (8 data + 1 mode), even parity emulated for the 9th bit, 1 stop bit.
# Getting Started
Build with **ESP-IDF v5.x**:
```bash
# Clone the repository
git clone https://github.com/nodestark/mdb-esp32-vending-machine-control
cd mdb-esp32-vending-machine-control
idf.py build flash monitor
```
Wire the MDB bridge to the peripheral's MDB connector, power the bus, and the VMC starts polling automatically — reset → setup → enable → poll. Press the vend button to attempt a purchase using whichever credit (coin, bill, or cashless) is available.
# How to Contribute
- Contributions are welcome! Open issues, send pull requests, or propose new features
- Before submitting a pull request, make sure the code complies with the style and quality guidelines defined in the project
- Help improve documentation by adding usage examples, wiring notes, and peripheral compatibility reports
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.