Offline FreeRTOS Build & Flash Dashboard for AmebaPro2 + Fix for “UART Download UCFG Fail”

[inxnik]

Hi everyone,

I ran into some issues flashing images onto the AmebaPRO2-mini. While investigating the root cause, I ended up building a small dashboard to automate the compilation and deployment of FreeRTOS builds to the device.

It provides a clear status for each step, making it much easier to spot errors, identify where the pipeline stops, and avoid getting lost during the process.

GitHub - SmartShelfAI/ameba-flash-ui: Offline, dependency-free local web panel to build, flash and serial-monitor AmebaPro2 / AMB82-mini FreeRTOS firmware (Python stdlib only) · GitHub (MIT)

It’s Python 3 standard library only — no pip install, no internet. Everything stays on localhost.

Quick start

1. Run the server from your AmebaPro2 project root (the folder with build_freertos.sh / images/):

   git clone https://github.com/SmartShelfAI/ameba-flash-ui
   python3 ameba-flash-ui/serve.py
   # or point it at your project explicitly:
   PROJECT_ROOT=/path/to/your/project python3 ameba-flash-ui/serve.py
   
   

   It prints:

   Flash UI: http://127.0.0.1:8765  (project: /path/to/your/project)
   
   

2. Open the URL in a browser — http://127.0.0.1:8765 — not by double-clicking the HTML file (the page needs the server for its API; it will tell you so if opened as a file).

3. Stop it with Ctrl-C in the server terminal (Control, not Cmd). From another terminal: pkill -f serve.py (or lsof -ti :8765 | xargs kill).

What it does (one page, a few buttons):

• Pick a target — full application or any incremental TEST/<id> build (auto-discovered from the cmake files).

• Build — runs your build script and shows a progress bar. It deliberately does not stream the full SDK build log to the browser (tens of thousands of lines crash the tab); only progress + real error lines are shown.

• Check UART — finds the serial port and tells you whether it’s actually free.

• Flash — calls uartfwburn directly. A single clean attempt at a chosen baud (default 115200, see below).

• Serial monitor — streams the board’s UART output to the page and to a file, with optional per-line [HH:MM:SS.mmm] timestamps and rotating per-session logs for long runs.
  
  

The UART problems it helped me solve:

1. ping ok → ucfg fail → download fail, then “I power-cycle everything and it works”.
   The board was clearly in UART DOWNLOAD mode (blue LED on, ping ok), yet the download config handshake failed. What I found: the AmebaPro2 ROM downloader effectively accepts one clean attempt per entry into download mode. A failed attempt leaves it half-negotiated, so the next uartfwburn run still gets ping ok but ucfg fail. A fresh entry (RESET + the UART-DOWNLOAD button together) — or power-cycling the USB-UART adapter — resets it. The panel detects these tokens in the flasher output and tells you exactly which case you’re in.

2. High bauds were the real troublemaker. In my setup I drive the board through an external CH340G wired to its UART pins (signal + GND only — the board runs on its own battery, so no shared USB power). On macOS the CH340G reports non-standard rate at 2M/921600 and fails, and because of (1) that first failed attempt then wedges the ROM so even a later 115200 attempt fails. Forcing a single 115200 attempt made it much more stable — so a single clean attempt is now the default, and the old multi-baud sweep is a clearly-warned option.

3. Garbage in the serial log. Setting the baud with an external stty and then re-opening the device didn’t stick on macOS (the re-open reset termios) → mojibake. Fix: configure termios (raw 8N1 @115200) on the same fd you read from.

Scope / honesty: it’s currently tailored to the AmebaPro2 / AMB82-mini on macOS — it expects the Realtek uartfwburn binary, the SDK build scripts, and a /dev/cu.wchusbserial* port. It can’t press the board’s buttons, so it prompts you to enter download mode and to press RESET afterwards. It’s small and readable on purpose — adapting paths/flash command for another setup is a couple of lines at the top of serve.py.

Feedback and PRs welcome — especially from anyone who’s mapped the AmebaPro2 ROM download protocol and can confirm/correct the “one attempt per entry” behaviour.

P.S. The only piece still missing is a way to enter download mode programmatically. Right now those are physical buttons, so the panel has to ask a human to press RESET + UART DOWNLOAD. If Realtek exposed a software trigger to drop the chip into UART download mode (over USB, or via a command), the whole loop — build → flash → monitor — would be completely hands-off. Fingers crossed.