The beerbox project
  • JavaScript 49.4%
  • C++ 34%
  • CSS 7.4%
  • C 5.2%
  • HTML 2.3%
  • Other 1.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Lukas Bachschwell cf92e75be3
Off to teh C6 Redesign
Signed-off-by: Lukas Bachschwell <lukas@lbsfilm.at>
2026-11-11 13:56:28 +01:00
3d Off to teh C6 Redesign 2026-11-11 13:56:28 +01:00
docs Off to teh C6 Redesign 2026-11-11 13:56:28 +01:00
hwtest Off to teh C6 Redesign 2026-11-11 13:56:28 +01:00
lib/LiquidCrystal_I2C Display test and correct needed LCD IIC Library 2026-10-01 09:24:50 +02:00
src Off to teh C6 Redesign 2026-11-11 13:56:28 +01:00
test/test_codec Off to teh C6 Redesign 2026-11-11 13:56:28 +01:00
web Off to teh C6 Redesign 2026-11-11 13:56:28 +01:00
.gitignore Initial 3D version 2026-10-10 19:58:13 +02:00
platformio.ini Off to teh C6 Redesign 2026-11-11 13:56:28 +01:00
README.md Off to teh C6 Redesign 2026-11-11 13:56:28 +01:00

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:

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:

  1. The LCD shows Drink: over Bier (a fresh board's default list).
  2. The button cycles through the drinks and wraps around.
  3. create Test over USB asks for a finger (or straight for a card without the sensor), then a card, and ends with a done event carrying the new record.
  4. Presenting that card shows the name and a 3-2-1 countdown, then Saved!, and a booking event arrives.
  5. Pressing the button during the countdown shows Abort! and leaves the count and the credits unchanged.
  6. The same with the fingerprint.
  7. drink add 120 Radler, then drink delete of it: the button stops offering it, and person <id> no longer lists it.
  8. Power-cycle the box: drinks, people and counts are still there.