Snack Cart POS

Owner & admin manual. A self-contained point-of-sale terminal for a workplace snack cart. People scan their badge, scan their snacks, and pay the cart’s owner by Venmo, Zelle, or Cash App from a QR code on the screen. Everything is stored on the SD card inside; nothing goes to the internet.

Firmware launch build, Oct 2026 · Screen 3.5″ portrait · Input 6 buttons + barcode scanner · Power 5 V USB

1. Overview
2. Controls
3. Buying snacks
4. Running the cart
5. Web portal
6. Care & backups
7. Alerts & boot log
8. Troubleshooting
9. Specifications

Overview

The cart runs on trust. There is no cash drawer and no card reader: each purchase is recorded against the buyer’s badge as an unpaid transaction, and the buyer pays from their own phone. An admin marks transactions paid once the money arrives.

What’s on the cart

• Screen on the top panel, on the left.
• Six buttons on the top panel, to the right of the screen: four yellow direction buttons in a diamond, with green (Enter) and red (Back) below them.
• Barcode scanner on the front face. It reads both employee badges and product barcodes, and beeps on every good read.
• Power switch, and a USB power cable from a wall adapter.
• SD card slot, reachable through a cutout in the side of the case. All data lives on this card.

Who does what

Role	Can do
Anyone	Check prices, browse the catalog.
Enrolled person	Buy snacks, see their own unpaid transactions, play the Extras games.
Admin	Everything above, plus clear balances, manage items and people, change settings, and open the web portal.

Controls

The bottom of every screen spells out what each button does right now, in that button’s colour.

• ▲ ▼ move the highlight in a list.
• ◀ ▶ jump a page at a time in long lists, or do the job named in the footer.
• ENTER opens, selects, or confirms.
• BACK goes up one level, cancels, or says No.

More:

• Holding a button repeats it, which is handy on long lists and the letter wheels.
• Text (names, the WiFi password) is entered on a letter wheel: ▲▼ change the letter, ◀▶ move between positions, ENTER continues.
• Anything that deletes or clears asks you to confirm first.

Buying snacks

The everyday flow. The Start screen reads “Scan Badge To Start.”

Make a purchase

1. Scan your badge. Your transaction opens with your name in the header.
2. Scan each snack. Scanning the same item twice adds a second one. For an item with no barcode, press ▶ Item Lookup and pick it from the list.
3. Fix mistakes by highlighting a line with ▲▼ and pressing ◀ Delete Item (removes one at a time).
4. Press ENTER Pay. The Payment screen shows the total and a QR code. Press ▶ Other Payment to switch method.
5. Pay from your phone (see below), then press ENTER Confirm. The sale is saved and the cart returns to Start.

BACK on the cart or Payment screen cancels the whole transaction (it asks first on the cart screen). Nothing is saved until Confirm.

Paying with the QR code

Method	Scan with	Amount
Venmo	Your phone’s Camera app, not Venmo’s own scanner	Filled in, with the transaction number in the note (#12 Snacks!!)
Cash App	Your phone’s Camera app	Filled in
Zelle	Your bank app’s Zelle scanner, not the Camera app	Type it yourself (Zelle can’t prefill)

Only the methods the owner has set up appear on the Payment screen.

New here?

When Auto Enroll is on, scanning an unknown badge asks “Badge not found. Enroll new user?” Press ENTER Yes, spell your first and last name on the letter wheel, then scan your badge once more to confirm. Your first transaction opens right away. If Auto Enroll is off, an admin adds you (Admin Menu → Users → Add User).

From the Start screen

Press	Opens
▶	Browse/Price: the full price list; scan any item to see its price. Nothing is charged.
◀	Extras: scan your badge, then choose Check Balance (your own unpaid transactions, with the QR code again in case a payment didn’t go through), Laggy Fish, or Slide Free. The games keep a best score per person.
ENTER	Admin Login: then scan an admin badge.
BACK	Screensaver, right away.

Screensaver. After a few idle minutes the screen dims and a fish wanders around. Press any button to wake it. The scanner is switched off while it’s showing, so wake the cart before scanning.

Auto logout. A transaction or admin screen left alone returns to Start on its own after 5 minutes (adjustable). An unfinished transaction is discarded, not saved.

Running the cart

Press ENTER on Start, then scan an admin badge. An inactive or non-admin badge is turned away.

Screen map

Start
├─ scan a badge ............ Transaction → Payment
├─ ◀ Extras ................ Check Balance · Laggy Fish · Slide Free
├─ ▶ Browse/Price
├─ BACK .................... Screensaver
└─ ENTER Admin Login → Admin Menu
   ├─ Balances
   ├─ Inventory ........... Restock · Add/Attach Item · Inventory
   ├─ Users ............... Add User · Edit Users · Auto Enroll on/off
   ├─ Web Portal
   ├─ Settings
   │  ├─ Payment Info ..... Venmo · Zelle · Cash App
   │  ├─ Screensaver ...... Timeout · Dim
   │  ├─ Set Clock
   │  ├─ Display .......... Brightness
   │  └─ Security ......... WiFi Password · Auto Logout
   └─ Advanced Tools ...... SD Info · DB · Scanner · DS3231 Test · Boot Log

BACK on the Admin Menu logs out.

Balances: marking payments received

One row per unpaid transaction, with its number, person, and amount. When the money arrives, highlight the row and press ENTER Clear, then ENTER Yes. Cleared transactions leave the list but stay in the lifetime reports. Venmo payments carry the transaction number in their note; match Zelle and Cash App payments by amount and time.

Inventory

• Restock: scan an item, adjust its count, confirm.
• Add/Attach Item: scan a barcode the cart doesn’t know. Either attach it to an existing item (useful for a variety pack sold as one item) or create a new item with a name and price. An item can have up to 8 barcodes.
• Inventory: the full list. Open an item to change its price or stock, link or unlink barcodes, hide it (off Browse, and its barcode scans as unknown, but its sales history is kept), or delete it. Items that have ever sold can only be hidden, not deleted.

Stock goes down automatically with every sale, and can go below zero if the count was off. For entering many items at once, the web portal is quicker than the buttons.

Users

• Add User: scan the new person’s badge, spell their name, and choose whether they’re an admin.
• Edit Users: rename someone, make them an admin, or set them inactive. An inactive person’s badge is turned away at the cart, but their history is kept.
• Auto Enroll: when on, unknown badges can sign themselves up (see Buying snacks).

You can’t change your own account while you’re logged in, on the cart or on the web. This guarantees there’s always at least one working admin. Ask another admin to make changes to your account.

Settings

Setting	Range	Default
Payment Info: set up an account by scanning your own Venmo, Cash App, or Zelle “my QR code” (or type it). One account per method.	—	—
Screensaver timeout	1–10 min	3 min
Screensaver dim level	10–100%	30%
Display brightness	10–100%	100%
Auto logout	1–10 min	5 min
WiFi password (web portal)	8+ characters	built-in
Set Clock: year, month, day, hour, minute	—	—

The clock keeps time through power cuts on its own coin battery. It has no internet time source, so correct it here if it drifts or after a daylight-saving change.

Advanced Tools

Tool	What it’s for
SD Info	Card size, space used, and a write test.
DB	Read-only views of the users, items, transactions, payment and settings tables; Backup Now; Restore Backup.
Scanner	Lock or unlock the scanner’s setup-code feature, view its settings, restore its defaults.
DS3231 Test	The clock chip’s status and time, and a full clock check.
Boot Log	One page per power-on, newest first. See Alerts & boot log.

Web portal

A phone-friendly admin site served by the cart itself, over its own WiFi network.

1. Log in as an admin and open Web Portal. The cart’s WiFi switches on and the screen shows the network name (SnackCart), its password, and a QR code for the page.
2. Join that network on your phone, then scan the QR code (or browse to the address shown).
3. Work in the browser. Keep the Web Portal screen open on the cart the whole time; the WiFi turns off the moment you leave that screen.

Page	What’s there
Home	Outstanding balance, unpaid transactions, people and item counts.
Balance	Unpaid transactions grouped by person, each with a Clear button.
Items	Every item with price and stock, quick ±1/±10 stock buttons, Edit (name, price, hidden, delete), and Add Item.
Report	Lifetime and monthly sales, per person and per item. Downloads as a spreadsheet (.xlsx) or plain text, for unpaid only, the last 30 days, or lifetime.
Users	Admin and Active switches per person, and Edit (name, badge number, registration date, delete).
Admin	Cart settings, clock, WiFi password, payment accounts (view only), Back up now, Download database, Download boot log.

The portal has no login of its own. Access is protected by needing an admin badge at the cart and the WiFi password, and by the WiFi only running while that screen is open. Anyone on the network while it’s open can see and change everything, so close the Web Portal screen when you’re done.

Care & backups

How your data is protected

• Every power-on checks the whole database before using it.
• The cart keeps five rolling backup copies on the SD card, refreshed at every power-on, after every sale, and when the web portal closes. Each copy is read back and compared before it replaces an older one, and a damaged database is never copied over a good backup.
• If the database is missing or damaged at power-on, the cart restores the newest good copy by itself and shows an alert.

Removing the SD card

1. Turn the cart off with the power switch. Never pull the card while it’s on.
2. Press the card in through the side cutout to release it.
3. On a computer, the card shows the database (pos.db), its backups, the boot log, and the Slide Free puzzle files. Don’t rename or delete pos.db-journal; the database uses it to recover from power cuts.

Recovering on a new card

1. Format a card as FAT32. Testing a new card first with a free tool such as H2testw catches bad or fake-capacity cards.
2. Copy your most recent downloaded database onto it and rename it pos.db. Copy the slidefree folder too if you have it.
3. Insert it and power on. Everything returns as of that download.

A completely blank card starts a setup wizard instead, which walks you through scanning in the first admin. Items and people then have to be added again.

Cleaning & placement

• Wipe the screen and scanner window with a soft, dry or barely damp cloth. Don’t spray liquid onto the cart.
• Keep the vent holes clear, and keep the cart out of direct sun.
• The base is weighted so the cart doesn’t tip forward; set it on a flat surface.

Alerts & boot log

Every time it powers on, the cart checks itself and writes one line to boot_log.csv on the SD card. Problems also appear as a yellow bar at the top of the Admin Menu; customers never see it. The bar shows the most important problem, with “(+N more)” if there are others.

To read the log, open Advanced Tools → Boot Log (◀ older, ▶ newer, ▲▼ scroll; failures show in red, things to act on in orange), or use Download boot log on the web portal.

Alert	What to do
NO SD CARD DETECTED	Power off, reseat the card through the side cutout, power on.
DATABASE UNAVAILABLE	The database couldn’t be opened or restored. Try another card with a downloaded copy (see Care & backups).
DB RESTORED FROM BACKUP THIS BOOT	The cart repaired itself. Anything since the last backup (usually only the very last sale) may be missing; check Balances.
UNEXPECTED RESTART: BROWNOUT	The power dipped. Try a stronger USB adapter (2 A or more) or a different cable.
UNEXPECTED RESTART: CRASH / WATCHDOG	The software stopped. Note what was happening and check the boot log; if it repeats, it needs a firmware fix.
SD CARD NOT WRITABLE	Check the card’s lock switch; replace the card if it persists.
LOW SD CARD SPACE	Under 5% free. Use a larger card.
CLOCK IS WRONG - SET CLOCK CLOCK IS BEHIND LAST SALE	Settings → Set Clock.
CLOCK BATTERY LOST POWER	Set the clock. If it keeps happening, replace the clock’s CR2032 coin cell.
CLOCK CHIP NOT FOUND	Hardware fault in the clock wiring. The cart still runs, but times will be wrong after every power cut.
SCANNER NOT RESPONDING	Power off and on. If it persists, the scanner cable needs checking.
SCANNER SETTINGS UNREADABLE SCANNER SETTINGS DIDN’T STICK	Power off and on. If it repeats, Advanced Tools → Scanner → Restore Defaults.
SCANNER SETUP-CODE LOCK IS OFF	Advanced Tools → Scanner → Disable QR Config Scan. This stops special setup barcodes from changing the scanner’s settings.
BUTTON STUCK DOWN AT BOOT	A button was held or jammed at power-on. The cart ignores it until it’s released; if it’s physically stuck, it needs repair.
DATA CHECK FOUND PROBLEMS - SEE BOOT LOG	Some records don’t add up (for example, a sale whose total doesn’t match its items). Nothing is changed automatically; the boot log says what was found.
SLIDE FREE BOARD FILES MISSING	Copy the slidefree folder back onto the card.

A rising SD write time in the boot log over several months is an early sign of a wearing card; compare power-on boots with each other (a cold power-on is normally around 250 ms).

Troubleshooting

Problem	Try
Scanning does nothing	Wake the screen first (any button); the scanner is off on the screensaver and on most menus. On the cart screen, an unknown item shows “Item not found.”
“Badge not recognized”	The badge isn’t enrolled. Turn on Auto Enroll, or have an admin use Add User.
Badge turned away with “please see the cart owner”	The person is set inactive. An admin can reactivate them in Edit Users.
Venmo QR won’t open	Use the phone’s Camera app, not the scanner inside Venmo.
Zelle QR won’t open	Use the Zelle scanner inside your bank’s app, not the Camera app.
“Couldn’t save. Press Confirm to try again.”	The SD card hiccuped. Press Confirm again; the cart is kept until it saves.
Can’t find the SnackCart WiFi	The WiFi only runs while the Web Portal screen is open on the cart.
Times on transactions are wrong	Settings → Set Clock. Check the clock alerts above.
Screen shows an SD card error at power-on	Follow the message on screen; press ENTER to retry after reseating the card.
Can’t change my own account	By design. Another admin has to do it.

Specifications

Hardware

Part	Details
Controller	ESP32-S3 (N16R8): dual-core 240 MHz, 16 MB flash, 8 MB PSRAM, WiFi
Display	3.5″ TFT, ILI9488 driver, 320 × 480 portrait, PWM backlight
Scanner	GM65 1D/2D barcode module, UART 9600 baud, built-in buzzer (2 kHz)
Buttons	6 tactile switches (Up, Down, Left, Right, Enter, Back)
Storage	microSD, FAT32 (launch card: 16 GB)
Clock	DS3231 real-time clock, CR2032 coin-cell backup
Power input	5 V DC over USB (power only, no data)
Protection	Littelfuse RXEF250 resettable fuse (2.5 A hold, ~5 A trip); 470–1000 µF bulk capacitor + 0.1 µF ceramic on the 5 V input
Enclosure	3D-printed PETG, primed and texture-painted; steel-shot and epoxy ballast in the base; vent holes; side cutout for the SD card
Wireless	WiFi access point only (2.4 GHz, WPA2), on only while the Web Portal screen is open. No internet connection.

Estimated power draw

Estimated from component datasheets and typical values; not yet measured on the finished cart.

State	What’s running	Current at 5 V	Power
Screensaver	Backlight dimmed (30%), scanner off, WiFi off	100–150 mA	0.5–0.75 W
Waiting on Start	Full brightness, scanner watching for a badge	180–260 mA	0.9–1.3 W
Scanning	Scanner illuminating and decoding (brief)	280–400 mA	1.4–2.0 W
Web portal open	WiFi access point running, full brightness	230–330 mA avg	1.2–1.7 W
Worst-case peak	WiFi transmit, a scan, and an SD write at the same instant	1.3–1.5 A	6.5–7.5 W

• Recommended supply: a 5 V USB wall adapter rated 2 A or more. Peaks last milliseconds, but a weak adapter or thin cable can let the voltage dip and restart the cart (logged as a brownout).
• Daily use: at roughly 1 W average, about 24 Wh a day, or about 0.7 kWh a month: on the order of ten cents of electricity.
• Clock battery: the DS3231 draws only microamps from its CR2032 when the cart is unplugged; expect years of life.

Capacities

Limit	Value
Items shown in on-cart lists	255
Barcodes per item	8
Different items in one transaction	32
People shown in on-cart lists	128
Unpaid transactions shown on the cart’s Balances screen (the web shows all)	64
Backup copies kept on the card	5
Boot log size before it rolls over (keeps one older file)	≈1,700 boots
Power-on to ready	≈5 s

Software

• Arduino framework on PlatformIO, LVGL 8.4 graphics, SQLite database on the SD card.
• Every library is pinned to the exact version that shipped, so rebuilding the firmware later produces the same cart. Source is public on GitHub: github.com/Logicish/pos-snack-cart.
• Times are stored as local time with no time zone or daylight-saving adjustment.

Pin assignments (for repairs)

Signal	GPIO
Display CS / Reset / D/C	8 / 9 / 10
SPI MOSI / SCK / MISO (display + SD, shared bus)	11 / 12 / 13
SD card CS	14
Display backlight (PWM)	18
Scanner: ESP receive ← GM65 TX / ESP transmit → GM65 RX	16 / 15
Clock I²C SDA / SCL (4.7 kΩ pull-ups)	5 / 4
Buttons Up / Down / Left / Right	41 / 42 / 2 / 1
Buttons Enter / Back	40 / 39

Snack Cart · built by LogicishDesigns · manual for the October 2026 launch firmware.