Start with the symptom below. Defaults refer to fresh factory settings; a saved recipe may differ. First setup covers the normal path.
Check, in order:
- BBW is on in Home Quick Settings, not just in the saved recipe.
- Home shows fresh usable scale readings.
- Initial BBW protection has ended.
- Fast guard is not deliberately extending.
- Original paddle mode is not waiting for OFF.
- On momentary firmware, the machine state permits an automatic stop pulse.
Use the stop action for your physical switch/mode if the result is unexpected. Auto paddle mode does not interpret OFF as early stop.
Read the shot's stop detail on its Stats history card before changing calibration.
| Result | Likely check |
|---|---|
| Above target, fast shot | Fast guard may extend toward its recovery weight. |
| Below target, slow shot | Slow guard may choose its recovery floor. |
| Around 50 s on factory Double | Max BBW time; distinct from Slow's 44 s decision. |
| After scale loss | A→M deadline is measured from shot start, not disconnect. |
| Ordinary stop followed by extra dripping | Learned offset and drip delay; see BBW. |
Prediction, sample timing and dripping mean the weight at stop need not equal the final stored weight. Guard behavior does not guarantee extraction quality.
Weight stop pauses while reconnection continues. Three coherent readings on the recovered link can restore it. A→M and other applicable limits still act. A steady unchanged weight is not a lost stream.
If the scale was absent at start, No-scale BBW controls whether the attempt is blocked or manual. A scale arriving later does not retroactively make every manual cycle an automatic one.
A cup placed within the retare window can be tared automatically. Later placement is not covered. Require cup to start blocks the start instead.
For a timer-only session, turn BBW off in Home. Tare/timer remain available when supported; weight stop, late retare and Max BBW time do not. Home's session selection does not overwrite the saved preset.
It limits electrical relay closure. On paddle installations that normally stops brewing. A momentary machine needs a stop pulse and valid state conditions; without scale/reed evidence, a tap-started machine may not receive it. Read Momentary limits.
On fresh settings, the AP starts at boot. Its name is
OpenBrewByWeightAP- plus eight characters unique to this controller.
USB AP_STATUS prints the exact name. Forget any saved network named only
OpenBrewByWeightAP. With saved Wi-Fi, fallback begins after roughly 25 s
without association. Automatic AP shuts down after 3 minutes with no associated
clients and does not restart after a later successful home-network connection
drops. Use USB AP_START or reboot.
After a factory reset the password is still ineedacoffee. Phones and
computers often show that message when they cannot finish joining, not only
when the letters are wrong. Join the unique OpenBrewByWeightAP-xxxxxxxx
name from USB AP_STATUS, forget any unsuffixed OpenBrewByWeightAP, and
retry next to the controller. The scale may wait to connect until you finish
this setup network.
Reconnect your phone/computer to the home network, find the controller's DHCP
address in the router or USB NET_STATUS, then open that address and claim
the UI within 3 minutes. The AP address cannot follow a change to a different
network. Unconfirmed changes revert; see Wi-Fi.
Once the controller has joined your home Wi-Fi, open
openbrewbyweight.local in a browser on any phone or computer connected to
the same network — there is no need to look up the IP address. The name comes
from the controller's default device name; if you renamed it in
Admin → Network, open <name>.local instead (spaces become hyphens, so
Cafe Bar is cafe-bar.local). See Wi-Fi.
Usually one of two things is happening. Either the controller never joined
your Wi-Fi (or your phone/computer is on a different network) — check that
both are connected to the same network. Or your network does not allow the
discovery behind .local names (mDNS), which guest and hotel networks
commonly block. In that case, find the controller's IP address in your
router's device list and open that instead. See
Wi-Fi.
Reload claims the Web UI. Admin unlock is a separate password check. Idle timeouts, another browser's claim, and an active shot can each restrict controls for different reasons. See Web access.
Use USB commands or physical recovery. Resetting only the password over USB preserves Wi-Fi; access recovery also forgets the network. Factory reset erases much more. Compare the procedures before choosing one.
Check Home → Cup → Automatic tare and the scale status. With a positive weight already present at startup, remove the cup, let the empty pan settle, and replace it. If the Bookoo zeroed a load already on its pan, wait for the initial zero to settle, remove it, let the negative empty reading settle, then place a different-weight load. If it returns near zero, readings were lost, or the negative reading was present from the first connection, tare the empty pan using the scale's button, reconnect the scale, wait for stable zero and replace the load. Stable-looking weight alone is insufficient after lost readings or a failed tare; an unchanged cup is not automatically retried. See outside-brew tare.
The controller cannot verify a press of the scale's physical tare button from the documented weight notifications. A return to 0 g can also mean a previously removed load was put back. Home may still say Cup present and Tared because those are its last known states. Tare the empty pan using the scale's button, reconnect it, wait for stable zero, then place the cup again. The optional accessory retare handles one stable addition to a controller-tared cup before a shot; it cannot identify physical button presses. See Tare.
Close other scale-connected apps. Check the saved preferred scale and Admin → Power management → BLE scan mode. Factory default is Balanced; Relaxed uses less scanning radio time and Aggressive uses more. Try Relaxed if idle scanning hurts UI response. On a Linea Micra, the machine-aware scale search can ease scanning while the machine is off. Admin → Power management → Wi-Fi sleep can also affect latency. See Scales and Wi-Fi.
They are disabled in default firmware. An explicit development build can enable them, but Admin unlock alone cannot. Remote Stop remains privileged. See build options.
The firmware mode switch is off: the controller is running as a transparent pass-through and every other tab is hidden. Unlock Admin with the device password, open Firmware, and turn Enable Shot Stopper back on.
Yes, but first determine and review the correct configuration for that exact machine and controller assembly. Identify whether its brew control is momentary or maintained/paddle, whether reliable state feedback such as a reed sensor is available, how the isolated normally-open relay must connect, and which factory defaults match the machine's gestures. Then create complete hardware and machine profiles and pass the applicable bench and manual tests. A similar connector, brand, or switch appearance is not proof of electrical or behavioral compatibility.
- Boards / wiring: Hardware. A GPIO map is not a complete machine installation guide.
- Scale models / missing timer or sound: compatibility table. Implemented and physically tested support are different.
- No USB port: default app CDC needs GPIO4 held to GND at reset. ROM download uses BOOT + RST; see USB console.
- LED or beeps: the connection LED is not a brew or safety-ready indicator. Output depends on Alerts, local buzzer and scale capabilities.
- Change GPIOs: create or select a reviewed hardware profile and rebuild; the Web UI does not configure safety-critical pins.
After a watchdog/panic reset, the relay is forced open and the interrupted shot does not resume. Persistent hardware/feedback faults may still block starting. An open K1 cannot stop a welded contact; see isolation.
The Diagnostic page is always available at the address /diagnostic, even
when its tab is hidden from the menu (Admin → Frontend → Show diagnostic
page only shows or hides that tab) and in compatibility mode. Its
measurements keep recording either way. While the page is open, its
States, Machine I/O, and Scale sections — including the scale's
timer — update on their own several times per second, so readings such as the
relay, the switch, the cup, and the weight stay current without reloading;
every other section refreshes every few seconds. The page finishes loading
when those sections have arrived. New log entries appear automatically while
Diagnostic is open, and leaving the page stops its live updates. If the
connection drops, the interface reconnects and reloads current readings.
In NVS, unavailable entry and namespace measurements appear as a dash, so a failed measurement is not mistaken for an empty store.
Diagnostic → Scale → Profiling records what the scale actually sent and what the firmware decided about it. Press Start before reproducing a problem — for example a wrong tare or an unexpected cup event — and Stop when done; Download then saves a plain-text trace and Delete removes it. Recording continues until its capacity fills or you press Stop, keeps running while you leave the page, and works with or without a shot in progress. Every decoded weight is kept exactly as received — including identical, negative, and rejected readings — together with the tare, cup, touch, and first-drop decisions taken around it, so a support conversation can point at one line instead of guessing. Starting a new recording replaces the previous one, which is stated next to the buttons; a finished recording survives a restart once it reports as saved. Losing power during recording or saving can lose that session.
Capture capacity used shows how much recording space has been consumed, including the space kept for the closing event. Elapsed is the time already recorded. Estimated time remaining adapts to how quickly readings and events arrive, so different scales can record for different lengths of time. It takes a few seconds to appear, smooths brief changes in activity, and may increase when fewer events arrive. If no records arrive for several seconds, the estimate returns to Estimating…; recording stays active. The percentage describes the capture, while Saving… and Saved tell you whether it has been stored for a restart. Stopping early keeps the actual percentage used rather than changing it to 100%. The state also explains recording errors, such as insufficient memory or a failed save. If saving fails and Download remains available, download the trace before restarting to preserve the recording held in memory.
On a 16 MB controller, Diagnostic → Misc → Coredump shows how many complete
crash records are saved, up to two. Unlock Admin to download them. The browser
saves a .tar.gz file when gzip is supported, or a .tar file otherwise.
Extract it with tar -xzf <archive.tar.gz> or tar -xf <archive.tar>.
Each crash folder contains the raw core dump, a short address list, and a
manifest with the matching firmware ELF fingerprint. Use the ELF from that
exact build when interpreting addresses. A watchdog dump may contain several
tasks; the short address list describes only the panic callback's view.
The archive can contain passwords or other private data, so share it only with
someone you trust. Downloading does not delete records. Empty asks for
confirmation and permanently removes them; a full factory reset does too.
An incomplete panic or a reboot loop before the record is copied can leave
fewer than two records. The screen reports an error if a temporary dump cannot
be archived. The 8 MB profile does not offer persistent crash downloads.
To report an issue, include firmware version, board and machine type, scale model/firmware, exact gesture/settings, and redacted diagnostic export. Never include passwords or webhook secrets. USB HEALTH and shot history help explain the observed result.
A stale scale event rejected warning means an old weight update or scale
command was ignored. Its detail names the rejected item and reason; gen(e/n)
and disc(e/n) compare the event's link identifiers (e) with the current
link (n).
This can happen briefly after a scale disconnects or reconnects.
Use the settings index for parameter references, OTA troubleshooting for update errors, and webhook troubleshooting for delivery problems.