WiFi (WINC) flash depends on a Windows-only external tool — blocks cross-platform

[cptkoolbeenz]

Concern (raised by the desktop app team)

The desktop app is expected to go cross-platform (Avalonia) in the future, consuming Core on Linux/macOS as well as Windows. The WiFi-module flash path is not cross-platform in its current form.

FirmwareUpdateService.UpdateWifiModuleAsync runs the WiFi flash by shelling out (via IExternalProcessRunner) to a Windows-only external program:

• winc_flash_tool.cmd (a Windows .cmd script — FirmwareUpdateServiceOptions.WifiFlashToolFileName)
• which invokes winc_programmer_uart.exe — Microchip's WINC Programming Tool 2.0.1 [ceebe5f] (Apr 20 2022) (observed in flash logs).

On Linux/macOS there is no .cmd/.exe to run, so WiFi flashing is unavailable. (PIC32 firmware flashing is already managed/native in Core via HID, so it is not affected — this is specific to the WINC/WiFi path.)

Why it's tractable (it's a serial protocol, not raw USB)

The WINC programmer talks to the module over a UART serial bridge: the PIC32 bridges its USB-CDC serial port through to the WINC, and the tool drives the WINC bootloader/programmer over that serial link (handshake → baud change to 500000 → erase/write/read/verify of the 4 Mb WINC SPI flash → Operation completed successfully). System.IO.Ports.SerialPort is cross-platform, so the transport is not the blocker — only the external tool is.

Options (for the desktop team / future work)

1. Port Microchip's open-source WINC UART programmer to managed C# (preferred). Microchip ships the winc_programmer_uart source in the ATWINC15x0 firmware-update package; reimplementing that protocol in Core would make the WiFi flash fully cross-platform and remove the external-process dependency entirely. Likely no reverse-engineering needed.
2. Capture the wire protocol to confirm/fill gaps — a serial port monitor, or Wireshark USB capture (usbmon / USBPcap) on the USB-CDC endpoint, to record the exact bridge handshake + flash command framing during a known-good flash, as a reference for the native implementation.
3. Keep the external tool as a Windows-only fallback. Core already isolates it behind IExternalProcessRunner + the WiFi options, so a native flasher could be introduced as an alternate implementation (e.g. an IWincFlasher seam) with the external-tool path retained where the binary is available.

Notes

• Core already cleanly isolates the tool dependency (IExternalProcessRunner, WifiFlashToolFileName, WifiFlashToolArgumentsTemplate, the bridge-activation callback, output-based success verification), so swapping in a native implementation is a contained change.
• Related: Own the full WiFi-module flash lifecycle in Core so consumers don't reimplement orchestration #269 (WiFi flash lifecycle in Core), feat(firmware): own the WiFi flash lifecycle and verify success from tool output #270 (implementation).

This is a tracking note, not an immediate blocker — WiFi flashing works today on Windows.

[tylerkron]

Correction: Microchip does not ship winc_programmer_uart source

Flagging this so nobody else spends time looking for it.

Option 1 above says "Microchip ships the winc_programmer_uart source in the ATWINC15x0 firmware-update package; reimplementing that protocol in Core... Likely no reverse-engineering needed." That is not correct. The package ships compiled binaries only:

• Harmony repo, wireless_wifi/utilities/wifi/winc/tools: winc_programmer_uart (Linux ELF), winc_programmer_uart.exe, winc_programmer_i2c(.exe), image_tool(.exe), aardvark.so/.dll
• The local winc1500-Manual-UART-Firmware-Update package: same set

I walked the entire Harmony repo tree via the GitHub API — zero .c files for the programmer anywhere. The only sources in that repo are the host-side WINC driver and the serial_bridge sample app, not the PC-side programmer.

There is a better reference anyway

DAQiFi's own firmware implements the bridge, at firmware/src/services/wifi_services/wifi_serial_bridge.c. That is the code which actually accepts or rejects commands from the PC tool, so it is a more authoritative reference for our device than anything Microchip publishes — and it is fully readable. The protocol in #423 is derived from it: op codes, the 12-byte XOR-checked header, mixed endianness (header fields little-endian, register replies big-endian), and the ACK/NACK handshake.

So option 1 is still the right direction, just via a different source. Option 2 (wire capture) is not needed.

One incidental find

The bridge's READ_BLOCK handler never decrements its counter nor advances the address, so any block read of ≥2048 bytes loops forever re-sending the same chunk. Core caps reads at 2047 to avoid it. Being raised separately as a firmware ticket.

Status

#423 lands the protocol library, a read-only WincModuleInspector, the tool locator and 75 tests. It does not close this issue — erase/program is still unimplemented, so cross-platform WiFi flashing remains open. Details and the validation gaps are in that PR.

[tylerkron]

Status after #423 — reading works on Mac/Linux, writing does not

Correcting this issue's premise first, because it sends people down a dead end.

"Microchip ships the winc_programmer_uart source in the ATWINC15x0 firmware-update package; reimplementing that protocol in Core would make the WiFi flash fully cross-platform. Likely no reverse-engineering needed."

Microchip ships binaries only, not source. Verified against both the Harmony GitHub tree and the local package, and cross-checked against this org's own winc1500-Manual-UART-Firmware-Update repo, whose winc/tools carries the same binaries-only set. There is no source to port.

The protocol in #423 was instead derived from DAQiFi's own firmware — firmware/src/services/wifi_services/wifi_serial_bridge.c — which is a better reference anyway, since it is literally the code on the other end of the wire.

A second correction: entering bridge mode is not a one-way door. WifiBridgeActivator.Deactivate restores SCPI cleanly; this was verified on hardware twice. An earlier assumption to the contrary (that only a WiFi re-init or a power cycle could exit) was wrong.

What landed (#423)

Cross-platform, System.IO.Ports-based, no external process:

• WincBridgeProtocol — op codes, 12-byte XOR header, mixed endianness
• WincSerialBridgeClient, SystemWincSerialPort
• WincFlashReader — read-only register sequences
• WincModuleInspector — handshake, baud negotiation, chip/flash identity, flash read-back
• WincFlashToolLocator — answers "can this machine flash?", so a missing tool now gives a clear cross-platform error instead of reading as a bad path

Validated against a live WINC over the USB-CDC bridge:

chipId        = 0x001003A0     (matches the value the firmware source records as bench-observed)
flashJedecId  = 0xC21320C2     (Macronix, capacity 0x13 -> 4 Mbit / 512 KB)
negotiatedBaud= 500000
read 4096 bytes @0x000000, first 4 ASCII = "NMIS"   (WINC image signature)
re-read identical; a different region differs
soft exit -> SCPI restored

The chip-ID match validates the big-endian register decode, which was the asymmetry most likely to be wrong.

The bench run found a bug five rounds of code review could not reach. ReadFlashJedecId returned 0x00000000 from the live module: it wrote DATA_CNT = 0 and DMA_ADDR = 0, so no result bytes were ever clocked back — while every frame stayed well-formed, the device ACKed every one, and TR_DONE still went high. Nothing about the protocol layer was wrong; two register values were. That is structurally invisible to framing tests, because the test fake answers exactly what the device answers. Fixed against spi_flash_rdid and re-verified on hardware.

What's left — the actual blocker in this issue's title is NOT resolved

1. Erase and program are unimplemented and unexercised. No write of any kind has ever been sent to the module. Cross-platform WiFi flashing remains impossible; only inspection and read-back work. This was deliberate — a wrong opcode bricks the module with no macOS recovery path — so the capability is absent rather than shipped unexercised behind an API that looks complete.

2. The external Windows-only tool is still the only way to actually flash. WifiModuleUpdater continues to shell out to winc_flash_tool.cmd; #423 changed none of that, it only made the failure legible off-Windows.

3. A destructive write needs a supervised bench session and an explicit decision. The read path is proven, which materially de-risks it, but validating a write means erasing and reprogramming a real module.

4. Firmware constraint on read-back: block reads of >= 2048 bytes hang the host — see daqifi/daqifi-nyquist-firmware#755. Core caps MaxReadBlockSize at 2047 as a client-side workaround, with tests asserting no oversize request reaches the wire. Note that ticket also carries a companion defect: fixing the loop alone converts the hang into silent data corruption.

5. Ceremonial baud change: the 500000 step is required by the bridge but has no throughput effect over USB CDC, which ignores line rate. Documented on the constant so nobody expects a speedup.

Keeping this open — the title's blocker stands.