| name | flash |
| description | Flash an A2FPGA board's FPGA BITSTREAM (the .fs gateware) with openFPGALoader. Use when the user asks to flash, program, upload, load, or deploy a BITSTREAM/gateware to a board (a2mega, a2n20v2, a2n20v2-GS, a2n20v2-Enhanced, a2p25, a2n9, a2n20v1). NOT for the a2n20v2-Enhanced BL616 MCU/microcontroller FIRMWARE — for that use the `flash-mcu` skill (different tool, different chip; using this one would not touch the BL616). |
Flash an A2FPGA board
Programs a board's bitstream with openFPGALoader, using the correct cable/board config
per board. Wraps tools/flash.sh (humans run the same script directly).
Flashing is a real, outward action on hardware — confirm the board and that a device is
connected before running, unless the user already said to go ahead.
Steps
-
Determine the board. If unspecified, ask. See docs/boards.md.
-
Confirm a bitstream exists. The script flashes boards/<board>/impl/pnr/<proj>.fs.
If it's missing, build first with the build skill (tools/build.sh <board>).
-
Preview, then flash. To show the exact command without running it:
DRY_RUN=1 tools/flash.sh <board>
Then flash:
tools/flash.sh <board>
tools/flash.sh <board> --sram
Per-board programming config (handled by the script)
| Board(s) | openFPGALoader |
|---|
| a2n20v1, a2n20v2, a2n20v2-GS, a2n20v2-Enhanced (Tang Nano 20K) | -b tangnano20k |
| a2n9 (Tang Nano 9K) | -b tangnano9k |
| a2mega (Tang Mega 60K), a2p25 (Tang Primer 25K) | -c esp32s3 (on-board ESP32S3; flash adds --bulk-erase -f) |
Notes
- a2mega (DDR3): power-cycle the board between flashes. Reprogramming without a power
cycle can fail DDR3 init and produce a black screen that looks like a logic bug, not a
programming failure. The script prints this reminder. See docs/gotchas.md.
- Loader install (macOS):
brew install openfpgaloader.
- a2mega, indeterminate/corrupt flash state (a write errored or was
interrupted; FPGA no longer configures at power-on; flash ops fail with
"Read ID failed"): do NOT iterate on writes. Bulk-erase first at low speed
—
openFPGALoader -c esp32s3 --freq 500000 --bulk-erase — then replug and
flash normally. The flash phase's default 10 MHz JTAG clock does not work
on this board; 500 kHz does. Full recipe: docs/gotchas.md.
