- JavaScript 49.4%
- C++ 34%
- CSS 7.4%
- C 5.2%
- HTML 2.3%
- Other 1.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| 3d | ||
| docs | ||
| hwtest | ||
| lib/LiquidCrystal_I2C | ||
| src | ||
| test/test_codec | ||
| web | ||
| .gitignore | ||
| platformio.ini | ||
| README.md | ||
The Beerbox Project
The Beerbox Project features a digital counter for drunken beer, or other drinks.
To identify a user the Beerbox can either use an RFID tag or a fingerprint. Once a user is identified it books the credits of the selected drink to them. The selected drink can be changed via the push of a button.
The box runs on an ESP32-C6 SuperMini. Drinks and people are stored as JSON in the chip's own flash, and a browser app manages everything over Bluetooth or USB.
Building
The project builds with PlatformIO. The C6 needs the community pioarduino platform (the stock one has no Arduino support for it); PlatformIO installs it on the first build.
pio run -e esp32c6 -t upload # build and flash the box
pio device monitor # console (the C6's native USB)
pio test -e native # host-side unit tests
pio check -e esp32c6 # static analysis
pio run -e esp32c6_rfidtest -t upload # hardware test: RFID reader only
pio run -e esp32c6_displaytest -t upload # hardware test: LCD only
The C6 has no USB-UART chip, so it shows up as a USB CDC device
(/dev/cu.usbmodem* on a Mac). It re-enumerates when it resets, so a monitor may
have to reconnect after an upload.
Flashing firmware keeps the stored drinks and people. pio run -t erase wipes
them, and the next boot starts with the default drink list.
Debug logging is off by default. Set -DBEERBOX_DEBUG=1 in platformio.ini to
put the firmware's own plain-text logging on the console channel alongside the
protocol. A client has to ignore any line that is not JSON (the web app does).
Hardware
| Function | Pins | Notes |
|---|---|---|
| LCD (I²C) | SDA 20, SCL 19 | 8×2, Pollin PCF8574A backpack at 0x38, powered from 5 V. No external pull-ups: the C6's internal ones and a 50 kHz bus. |
| RFID reader | Serial0, RX 17 (silkscreen "RX") |
RDM6300, 125 kHz, 9600 baud. Powered from 5 V; its 5 V TX goes through a divider (below). Its RX is not used. |
| Fingerprint sensor | Serial1, RX 0, TX 1 |
Adafruit #751 (ZFM-20), 57600 baud, 3.3 V logic, wired directly. Optional: without it the box works with cards. |
| Button | GPIO 3, to ground | Internal pull-up |
| Status LED | GPIO 14 | Lit on activity, released after 5 s |
| Buzzer | GPIO 2 | Reserved, currently unused |
| Remote link | built-in BLE (NimBLE) | Advertised as Beerbox |
| Console | native USB (CDC) | Commands and debug log |
The pins avoid the C6's strapping pins (GPIO 4, 5, 8, 9, 15), JTAG (4 to 7) and USB
(12, 13). GPIO 8 drives the board's own RGB LED and GPIO 9 is its BOOT button. All
pins come from src/board_config.h.
RFID divider. The C6's pins are 3.3 V only. The reader's TX goes:
RDM6300 TX (P1 pin 1) ──[ 10k ]──┬── GPIO 17
└──[ 20k ]── GND
Both the divider and the internal I²C pull-ups were tested on the real parts.
Power. An Adafruit PowerBoost 500 Charger with a LiPo cell, switched by an
on/off switch, supplies 5 V to the C6's 5V pin, the RDM6300 and the LCD. Do not
plug USB into the C6 while the PowerBoost is feeding its 5V pin unless you have
checked the board has a diode between USB and 5V. The case is in 3d/.
Datasheets:
- RFID reader: RDM6300,
pinout in
docs/rdm6300_pinout.png - Fingerprint sensor: ZFM-20 user manual and the Adafruit guide
Talking to the box
USB and BLE accept the same line-based command set and answer in JSON. See
docs/protocol.md for the whole of it.
Quick check over USB:
version what is running
drinks list the drinks
drink add 120 Radler add a drink, price in cents
persons list the people
person 1 one full record
credits 1 500 set credits, in cents
help everything else
Every failure answers with a reason, and the box volunteers events of its own:
booking when somebody buys a drink, enroll as an enrolment progresses, ready
when it starts up.
The web frontend
web/ is a browser control panel for all of it (drinks, people, credits,
enrolment, the identify-next-scan trigger) over Web Serial (USB) or Web Bluetooth.
No build step; it installs as an offline PWA.
cd web && python3 -m http.server 8000 # then open http://localhost:8000
Add ?mock=1 to try it against a simulated box with no hardware attached. See
web/README.md for browser support.
Source layout
| File | Responsibility |
|---|---|
src/main.cpp |
setup() / loop() |
src/board_config.h |
Pin map and timings |
src/ports.{h,cpp} |
USB console, BLE link and the sensor UARTs |
src/model.h |
Drink, Person and the limits |
src/codec.{h,cpp} |
Validation and JSON conversion of stored records. No hardware, unit-tested |
src/store.{h,cpp} |
The drink and person tables and their files in flash |
src/cmdparser.{h,cpp} |
Line framing and tokenising. No hardware, unit-tested |
src/protocol.{h,cpp} |
JSON replies and events |
src/commands.{h,cpp} |
Command dispatch |
src/inputs.{h,cpp} |
Button, fingerprint and RFID polling; booking countdown |
src/enroll.{h,cpp} |
Fingerprint and RFID enrolment, as a non-blocking state machine |
src/ui.{h,cpp} |
LCD screens and the status LED |
hwtest/ |
Standalone hardware tests for the RFID reader and the LCD |
Testing on hardware
There is no automated hardware test. After flashing, walk through:
- The LCD shows
Drink:overBier(a fresh board's default list). - The button cycles through the drinks and wraps around.
create Testover USB asks for a finger (or straight for a card without the sensor), then a card, and ends with adoneevent carrying the new record.- Presenting that card shows the name and a 3-2-1 countdown, then
Saved!, and abookingevent arrives. - Pressing the button during the countdown shows
Abort!and leaves the count and the credits unchanged. - The same with the fingerprint.
drink add 120 Radler, thendrink deleteof it: the button stops offering it, andperson <id>no longer lists it.- Power-cycle the box: drinks, people and counts are still there.