flash cmd

Makefile

@@ -31,7 +31,14 @@ EXTRA_FLAGS ?=
 # {build.flags.usb} is expanded by arduino-cli (VID/PID/strings); pass it through verbatim.
 USB_EXTRA_FLAGS = -DNRF52840_XXAA {build.flags.usb} -DCFG_TUD_HID=$(CFG_TUD_HID) -DCFG_TUD_TASK_QUEUE_SZ=$(CFG_TUD_TASK_QUEUE_SZ) $(EXTRA_FLAGS)
 
-.PHONY: format format-check check build build-recovery
+# `flash`/`deploy` take the serial port as a REQUIRED POSITIONAL arg: `make flash /dev/cu.usbmodem1101`.
+# (No auto-detect -- uploading to a guessed serial port risks writing to the wrong device. List with
+# `arduino-cli board list`.) FLASH_PORT = whatever goal isn't one of our real targets; the catch-all rule at
+# the bottom swallows it so make doesn't try to build the port path as a target.
+FLASH_PORT := $(filter-out format format-check check build build-recovery flash deploy,$(MAKECMDGOALS))
+UPLOAD = arduino-cli upload -b $(FQBN) -p "$(FLASH_PORT)" OpenPuck
+
+.PHONY: format format-check check build build-recovery flash deploy
 
 ## Compile the firmware with the required USB flags baked in. Override CFG_TUD_HID / CFG_TUD_TASK_QUEUE_SZ /
 ## EXTRA_FLAGS / FQBN as make variables if needed.
@@ -42,6 +49,24 @@ build:
 build-recovery:
 	$(MAKE) build EXTRA_FLAGS="$(EXTRA_FLAGS) -DOPK_FACTORY_RESET=1"
 
+## Upload the most recent build. Usage: make flash <port>   e.g.  make flash /dev/cu.usbmodem1101
+## The board may need DFU/bootloader mode first (double-tap RST): puck (Steam/Lizard) mode drops the CDC port
+## so arduino-cli can't auto-reset it -- see docs/BUILD_AND_DEPLOY.md.
+flash:
+	@[ -n "$(FLASH_PORT)" ] || { echo "usage: make flash <port>   e.g. make flash /dev/cu.usbmodem1101   (list ports: arduino-cli board list)"; exit 1; }
+	$(UPLOAD)
+
+## Build then upload in one step. Usage: make deploy <port>   (same build overrides as `build`).
+deploy:
+	@[ -n "$(FLASH_PORT)" ] || { echo "usage: make deploy <port>   e.g. make deploy /dev/cu.usbmodem1101"; exit 1; }
+	$(MAKE) build
+	$(UPLOAD)
+
+# Swallow the positional <port> arg so make doesn't error trying to build it as a target. Scoped to things
+# that look like a serial port (so a real typo like `make buld` still errors instead of silently no-op'ing).
+/dev/% COM% tty% cu.%:
+	@:
+
 ## Reformat all C/C++ sources in place using the Linux kernel style.
 format:
 	$(CLANG_FORMAT) -i $(FORMAT_FILES)

docs/BUILD_AND_DEPLOY.md

@@ -74,15 +74,22 @@ arduino-cli compile -b adafruit:nrf52:feather52840 --build-property "build.extra
 
 ## 5. Upload the firmware
 
-### macOS / Linux
-
-Find the board port:
+The quickest path is `make`. The serial port is a **required argument** (find it with `arduino-cli board list`):
 
 ```bash
-arduino-cli board list
+make flash /dev/cu.usbmodem1101    # upload the most recent build to that port
+make deploy /dev/cu.usbmodem1101   # build + flash in one step (same build overrides as `make build`)
 ```
 
-Upload:
+Use the port for your OS: macOS `/dev/cu.usbmodem*`, Linux `/dev/ttyACM0`, Windows `COM5`.
+
+> **DFU note:** in puck (Steam/Lizard) mode the firmware drops the CDC serial port to free a USB endpoint, so `arduino-cli` can't auto-reset the board into its bootloader. If the upload can't connect, put the board in DFU mode first by **double-tapping RST**, then `make flash <bootloader-port>` (re-check `arduino-cli board list` — the port can change in DFU mode). The drag-and-drop UF2 path in §5b also works.
+
+### Manual upload (without `make`)
+
+Find the board port with `arduino-cli board list`, then:
+
+### macOS / Linux
 
 ```bash
 arduino-cli upload \