Raccoon: a Seven-Radio BLE Sniffer on One Clock

Raccoon started as bluekitchen/raccoon, an open-source nRF5 sniffer firmware with a USB/UART transport and a Python client that can use three dongles for the three advertising channels. I built a seven-radio instrument on top of it:

• SPI transport and board target. For Adafruit Feather nRF52832s, with a ready-line handshake and a queued, non-blocking transmit path.
• Hardware time alignment. PPI latches the chip-select edge into the packet timer, so every board's clock is tied to the host clock without CPU jitter.
• My own bootloader. 2,780 bytes; it updates a radio in place over the same SPI bus.
• Connection following. In the radio firmware (CSA#1 / CSA#2, PHY updates), with host tools that decrypt the result.
• Periodic advertising: a probe that decodes AuxPtr and SyncInfo, and a follower that puts a radio on the right channel for every event of a PAwR train.

The first version worked for a few dozen packets, then every reply came back as 0xFF. That is the SPIS over-read character, what the peripheral clocks out when the host selects it while it doesn't own a buffer. Re-arming SPIS is asynchronous. nrfx_spis_buffers_set() requests the buffer semaphore and returns at once, and the peripheral only accepts a transaction after it is released again. The ready line went high inside that gap.

The fix follows the hardware's sequence. RDY drops the moment a transfer completes. The next frame is armed, and RDY goes high only on BUFFERS_SET_DONE, when the SPIS can really take a transaction. The radio interrupt never waits for the bus. It drops packets into an 8-slot queue (252 bytes each) and moves on. If the queue is full, a packet is dropped rather than the radio stalled, and since firmware 2.2.0 the next packet carries a flag saying so.

The host side got the matching discipline. It reads only when RDY is high, matches each command reply by its tag and skips unrelated async packets, and drains to idle before a reset.

/* firmware/nrf/transport_spi.c (trimmed) */
static void spis_event_handler(nrfx_spis_evt_t const *e, void *ctx)
{
    if (e->evt_type == NRFX_SPIS_BUFFERS_SET_DONE) {
        /* Buffers loaded, TASKS_RELEASE fired: the SPIS
         * can take a CS transaction only from here on. */
        if (spis_armed_with_data)
            nrf_gpio_pin_set(TRANSPORT_RDY_PIN);
        return;
    }
    if (e->evt_type == NRFX_SPIS_XFER_DONE) {
        /* stop the host before anything else */
        nrf_gpio_pin_clear(TRANSPORT_RDY_PIN);
        ...                     /* take command bytes */
        spis_rearm();           /* next queued packet or idle
                                 * frame; RDY waits for the
                                 * BUFFERS_SET_DONE above */
    }
}

On each board, a GPIOTE channel watches the CS pin, and a PPI channel connects its falling edge straight to a capture task of the packet timer. The capture happens in hardware, independent of interrupt latency or what the firmware is doing. A second GPIOTE channel can watch the same pin as the SPIS driver without interfering with it. I used channels 6/7 and PPI 10/11, well above what nrfx allocates, and configured them with raw register writes so the driver's bookkeeping never sees them.

On the Pi, the host reads perf_counter() immediately before and after the GPIO write that drops CS, then reads the latched value afterwards. The bracket is the host-side uncertainty of the edge.

The design is deliberately small: one firmware slot, updated in place, no second copy to fall back to, no cryptography. That is the right size for bench equipment, and it makes one property essential: an interrupted update must never leave a radio that needs the debugger again. Three rules give that.

• The bootloader never writes its own page. It write-protects that page before starting the firmware.
• The commit is one 32-bit write. An image is bootable only while its magic word is in flash. The update writes everything else, then computes the CRC of the slot as it will read once the word is there, and only then programs it.
• Every boot checks the CRC again. A slot that was never finished stays under the bootloader's control.

The image header sits in the four vector-table entries a Cortex-M never reads, so the firmware needs no special linker section: build at the new base address, run one script over the binary. The bootloader decides whether to stay before it configures any peripheral and only ever leaves through a reset, so the firmware always starts from reset state.

The way back in when a new firmware boots but does not listen: hold that radio's chip select low through a reset. It has to stay low for about 20 ms, ten times longer than the longest SPI transaction at 1 MHz, and a valid command has to follow within three seconds.

/* bootloader/boot_core.c: END command (trimmed) */
/* CRC of the slot as it will read once the
 * magic word is in place. */
wr32(magic_bytes, magic);
crc = crc32_update(0xFFFFFFFFu, img, IMG_OFF_MAGIC);
crc = crc32_update(crc, magic_bytes, 4);
crc = ~crc32_update(crc, img + IMG_OFF_SIZE,
                    upd_size - IMG_OFF_SIZE);
if (crc != upd_crc || crc != rd32(img + upd_size)
        || rd32(img + IMG_OFF_SIZE) != upd_size) {
    return BP_ST_IMAGE_CRC;
}

hal_flash_write(APP_BASE + IMG_OFF_MAGIC, &magic, 1);
if (!app_valid()) {
    return BP_ST_FLASH;
}
updating = false;
app_ok = true;
return BP_ST_OK;

The first run against the real gateway followed the connection across all 37 channels and through the 2M PHY switch, and each of the two following radios recorded 56 and 58 % of the events. The pattern of the misses was the useful part. The two radios did not miss the same events. For long stretches they alternated: one got event n, the other n+1. Two receivers with independent RF problems don't take turns. Something they share was rationing them.

They share the SPI bus. The other five radios sat on busy advertising channels and forwarded every packet from every device in range, 75 to 120 per second each. The host could not drain seven queues fast enough, so the following radios' 8-slot queues overflowed and dropped packets that had been received correctly.

The fix belongs in the radio interrupt, before the packet takes a queue slot: when a target address is set, advertising-channel packets that don't involve it are not forwarded. That went to all seven radios over SPI, and the same test ran again a quarter of an hour after the first.

/* firmware/nrf/main.c: radio interrupt (trimmed) */
static bool adv_pdu_involves_filter_address(
        const uint8_t *pdu) {
    uint8_t type = pdu[0] & 0x0f;
    uint8_t len  = pdu[1];

    if (len >= 6 && memcmp(&pdu[2],
            ctx.connection_filter_address, 6) == 0) {
        return true;                /* AdvA */
    }
    /* SCAN_REQ, CONNECT_IND, ADV_DIRECT_IND carry
     * the advertiser as their second address */
    if ((type == PDU_ADV_TYPE_DIRECT_IND
            || type == PDU_ADV_TYPE_SCAN_REQ
            || type == PDU_ADV_TYPE_CONNECT_IND)
            && len >= 12 && memcmp(&pdu[8],
            ctx.connection_filter_address, 6) == 0) {
        return true;
    }
    return false;
}
...
if (ctx.mode == FOLLOW_CONNECT && ctx.filter_forwarding
        && !adv_pdu_involves_filter_address(curBuf)) {
    queue_packet = 0;   /* buffer is reused */
}

The pairing itself is in the clear, and so are the two PDUs that start encryption: LL_ENC_REQ and LL_ENC_RSP each carry half of the session key diversifier and half of the nonce's IV. With the long-term key, which this gateway can export for its own bonds, the session key is one AES block away. From there every PDU is AES-CCM with a 4-byte MIC, and the MIC is what makes the result trustworthy: a wrong key, a wrong packet counter or a wrong guess at the direction fails the check and never produces plausible garbage.

I let the MIC do more of the work than planned. An event can hold more than two packets, so "first packet is the central's" is sometimes wrong. The decoder tries the other direction and a few counter values ahead, and accepts only what verifies. Both radios' recordings decode to the same 41 PDUs with no failures.

The last decoded line explains the one event the radios did not follow: the gateway changes the connection interval at event 375, and that instruction is encrypted. The radios hop on the old schedule from there and lose the connection shortly before the gateway closes it.

# tools/decrypt_conn.py, run 4, radio D2 (excerpt)
+   0.00 ms ev   0 ch 11 C→P SMP Pairing Request
+ 123.75 ms ev   9 ch 12 C→P LL_PHY_UPDATE_IND
                         2M both ways, instant 19
+ 178.74 ms ev  13 ch 12 C→P SMP Pairing DHKey Check
+ 219.99 ms ev  16 ch 25 C→P LL_ENC_REQ
+ 233.97 ms ev  17 ch  5 P→C LL_ENC_RSP
+ 261.41 ms ev  19 ch 34 P→C LL_START_ENC_REQ
+ 274.97 ms ev  20 ch  3 C→P LL_START_ENC_RSP
+ 302.46 ms ev  22 ch 19 C→P ATT MTU Req
+ 439.96 ms ev  32 ch 16 C→P ATT Write Req 0x0026
+1499.28 ms ev 109 ch  5 P→C ATT Notification 0x0025
+3162.73 ms ev 230 ch 16 C→P LL_PERIODIC_SYNC_WR_IND
   periodic AA 0xDC8A6272, CRC init 0xC1BCC9,
   interval 1408 × 1.25 ms, event counter 16164,
   SID 8, 2M PHY, 1 subevent every 13.75 ms
+5018.52 ms ev 365 ch 34 C→P LL_CONNECTION_UPDATE_IND
   interval 50 ms, instant 375

# the tag's own console, same moment
PER_ADV_SYNC[0]: synced, Interval 0x0580 (1408),
  PHY 2, sync info sid 8
#SYNC_CB:idx=0,sid=8,phy=2,int=1408,num=1,sub_int=11

The channel of each event comes from CSA#2 with the train's access address and the event counter. The transfer gave the counter at one moment, so the counter now is an estimate. The follower parks the seven radios on seven channels, waits until the train lands on two of them, and keeps the counter value that explains both sightings. In the five-minute run the estimate from the transfer was 16634.3 and the counter it settled on was 16634.

From there the host keeps a radio waiting on the right channel for each of the next five events, and re-times its schedule from every packet it sees, so it runs on the gateway's clock and not the Pi's.

Because periodic packets sit on an exact grid, their timestamps also give the transmitter's clock. Against five sniffer radios the gateway's 1.76 s period is short by 37 to 43 ppm, inside the 31–50 ppm class it declares in its SyncInfo.

# host_spi/exp_pawr_follow.py: find the event counter
hits.append((rec['host_time'], rec['channel']))
t1, ch1 = hits[0]
guess = round(estimate(t1))
cands = [c for c in range(guess - 40, guess + 41)
         if channel(c) == ch1
         and all(channel(c + round((t - t1) / period)) == ch
                 for t, ch in hits[1:])]
if len(cands) == 1:
    anchor = (t1, cands[0])

# run 2
  seen on channel 25: 4 candidate counter(s)
  seen on channel 15: 1 candidate counter(s)
[+] event counter 16634
    (estimate from the sync transfer was 16634.3)

A second unit of the same nRF54L15 board ran a beacon with periodic advertising every 20 ms. Four radios each caught around 600 of its packets in eight minutes and fitted the period. Then the same with the crystal's load capacitance changed from 15.5 to 17 pF.

Each radio reads a different absolute value, because each compares the beacon against its own crystal. The difference between the two settings cancels that: 36.15, 36.14, 36.17 and 36.18 ppm on the four radios. The on-chip meter had said 36.2. Its absolute readings sit 4 to 11 ppm above the radios', which is the ordinary tolerance between the board's 32 MHz crystal and theirs.

Advertising capture, 90 s

PAwR investigation, May 2026

An nRF54L15 access point reported success at every step, but its tags lost sync after one periodic event. I added a probe mode: decode ADV_EXT_IND headers (SID, AuxPtr), send a secondary radio to the channel and PHY each CRC-good AuxPtr points at, and decode SyncInfo. A direct mode then listens on the periodic train's own access address.

Before using it on the real device, I validated it against a signal generator I wrote for an nRF54L15. On the access point it produced 4,642 CRC-good target records in one run, and those captures later confirmed the clock error from the air. The full story is in One Packet, Then Silence.