tartelette / documentation demossource ↗

cyw43439: Pico W Wi-Fi and Bluetooth

The Infineon CYW43439 on the Raspberry Pi Pico W, emulated at its pins so unmodified firmware runs, Wi-Fi and Bluetooth both: Embassy's cyw43 + cyw43-pio, and the pico-sdk driver that MicroPython uses. The driver downloads its radio firmware over the emulated gSPI link, scans, joins one of the board file's mock access points, gets a DHCP lease and reaches the network; or it brings up Bluetooth LE and talks to mock devices or a real adapter.

The pico-w board already has one:

tartelette fw.elf --board pico-w

Keys

KeyTypeDefault
onGPIOrequiredWL_ON: power and reset
dioGPIOrequireddata in/out, which doubles as the host interrupt
csGPIOrequiredchip select, active low
clkGPIOrequiredserial clock
macstring28:cd:c1:00:00:01the station's MAC address
apsarray of tablesmock access points, up to eight
mhz1..1000125core clock

Each access point:

KeyTypeDefault
ssidstringrequired1 to 32 bytes
securityopen | wpa2open
passphrasestring8 to 63 characters, for wpa2
rssi-120..0-50signal strength in dBm
channel1..146
[parts.wifi]
kind = "cyw43439"
on = 23
dio = 24
cs = 25
clk = 29
aps = [
  { ssid = "TarteletteNet", security = "wpa2", passphrase = "hunter22", rssi = -45, channel = 6 },
  { ssid = "FreeCafe", rssi = -70, channel = 11 },
]

A scan finds exactly these networks, and a join succeeds when the SSID and passphrase match one of them. The Pico W's LED is on the CYW43439 (its GPIO0), not on an RP2040 pin, and shows up as the widget's lamp.

The network

Behind the radio is a network backend, picked with --net:

  • user (the default, native only): a user-mode NAT in the manner of QEMU's slirp. The firmware's traffic goes out through ordinary sockets on your computer, with no root and no TAP device.

    Address
    10.0.2.15the firmware, leased by the built-in DHCP server
    10.0.2.2the gateway; connecting to it reaches your computer's 127.0.0.1
    10.0.2.3DNS, answered with your computer's resolver (A records only)

    TCP and UDP work; ICMP only to the gateway and DNS addresses. Nothing can connect in unless you forward a port: --forward 8080:80 makes your 127.0.0.1:8080 reach port 80 on the firmware.

  • loopback: a fake network with only the gateway (ARP, DHCP, ping, and a UDP echo service on port 7). Deterministic, for tests.

  • none: nothing behind the radio. Scans find no networks and joins fail. This is what the browser build has, and the panel says so.

The firmware runs on emulated time and the network on real time. A headless run goes as fast as it can by default, which can make the firmware's timeouts expire before a real reply arrives; --speed 1 paces it to the wall clock.

Bluetooth

--bt picks what the Bluetooth side talks to:

  • none (the default): a controller with no radio. The firmware's host stack initialises fine, but scans find nothing and connections never complete.

  • mock: a software controller with a deterministic neighbourhood of mock BLE devices:

    • a central, which connects when the firmware advertises, discovers its services, reads the device name and subscribes to everything that notifies;
    • a BLE MIDI peripheral;
    • a battery peripheral, whose level drops by one percent a second;
    • an MXW01 "cat printer", a 384-dot thermal printer. What the firmware prints can be saved with --dump-paper NAME=FILE.png.
  • hciN (Linux): a real adapter, through an HCI user channel. The firmware's own host stack then drives the radio and real devices. This takes the adapter away from the system while tartelette runs, and needs CAP_NET_ADMIN:

    sudo setcap cap_net_admin+ep $(which tartelette)
    tartelette fw.elf --board pico-w --bt hci0
    

    The adapter keeps real time while the firmware keeps emulated time; a run much slower than real time can miss supervision timeouts and drop connections.

The firmware/examples/pico-w-ble and catprint examples exercise all of this.

What's modelled

The model has layers that follow the chip and the driver:

  • the gSPI wire, bit by bit on the clock edges: the host's bits sampled on rising edges, the chip's changed on falling ones, and the interrupt on DIO;
  • the bus registers, the backplane window and the WLAN function behind it;
  • chip RAM, the chip ID and the core wrappers, so the firmware download "boots";
  • the WHD protocol the driver speaks to the firmware: SDPCM, CDC and BDC framing, iovars, events, scan, join (open, or WPA2 with the passphrase or a precomputed PSK checked against the access point's), and the Ethernet data path;
  • Bluetooth: the patch download, the control registers and the HCI ring buffers in WLAN RAM.

The radio firmware itself isn't run: tartelette answers what it would answer. The blobs (43439A0.bin and friends) are Infineon's and not in this repository. Embassy has them in its cyw43-firmware/ directory.

Panel

The Wi-Fi LED, the network joined and the address leased, the MAC, and errors such as a scan with no network behind the chip.

Events

EventValue
led1 / 0, the on-board LED
scannetworks found
join1 on success, 0 on failure
link1 / 0 as the station associates or leaves
unavailablea scan or join with no network behind the chip
bt_unavailablea Bluetooth scan, connect or advertise with no radio
ble_connected1 / 0, from mock devices
ble_notifya value the mock central received
ble_midi_outMIDI the firmware sent to the mock MIDI peripheral

--wifi-trace NAME prints the last 1024 gSPI transactions at the end of a headless run, which is useful when bringing up a new driver.

Actions

midi with a MIDI message packed into the value, big-endian, sends it from every connected mock MIDI peripheral:

--input wifi:midi=0x903C64@3000000      # note on, middle C, velocity 100

Not modelled

Access point mode, WPA3, power saving, and the chip's GPIOs other than the LED. The Wi-Fi link is not a radio: there is no packet loss, and rssi is only what a scan reports.