Implementation Guide

typedef enum { IDLE, RECEIVING } fw_state_t;

typedef struct {
    fw_state_t state;
    uint32_t   next_chunk;     // the chunk_nb we expect next
    uint32_t   crc_acc;        // running CRC32 (init 0xFFFFFFFF)
    slot_t     slot;           // the inactive partition we write
    uint8_t    listen_bc;      // accept broadcast chunks? (set by file_setup)
    // + decryptor state, if images are encrypted
} fw_session_t;

static fw_session_t fw;   // one global session

rdm_register(0xc8d7, RDM_SET, handle_file_setup);
rdm_register(0xc8cf, RDM_SET, handle_file_chunk);
rdm_register(0xc8cd, RDM_GET, handle_file_report);
rdm_register(0xc8ce, RDM_GET, handle_partition_info);   // optional but useful
rdm_register(0xc8c8, RDM_SET, handle_control);
rdm_register(0xc8f9, RDM_GET, handle_firmware_state);   // optional

// SET 0xc8d7  {u32 flags} -> {u32 status}
status_t handle_file_setup(const uint8_t *req, uint8_t *resp) {
    uint32_t flags = rd_u32(req);
    fw.listen_bc = flags & 1u;
    // (do NOT begin a session here; chunk 0 does that - see Step 4)
    wr_u32(resp, 0);          // status = 0
    return ACK;
}

// SET 0xc8cf  {u32 chunk_nb}{<=128 B data} -> {u32 status}
status_t handle_file_chunk(const uint8_t *req, uint16_t len, bool is_broadcast) {
    uint32_t chunk_nb = rd_u32(req);
    const uint8_t *data = req + 4;
    uint16_t dlen = len - 4;

    // Ignore broadcast chunks unless armed (Step 3)
    if (is_broadcast && !fw.listen_bc) return NO_REPLY;

    // --- chunk 0: self-describing header -------------------------------
    if (chunk_nb == 0) {
        fw_header_t h = parse_header(data, dlen);   // flash range, ctrl block, seed
        fw.slot       = other_partition();          // never the running slot!
        fw.next_chunk = 1;                          // data starts at chunk 1
        fw.crc_acc    = 0xFFFFFFFF;
        fw.state      = RECEIVING;
        decryptor_init(&fw, &h);                    // if encrypted
        flash_erase_slot(fw.slot);                  // or erase-on-write per sector
        return reply(is_broadcast, /*status*/0);
    }

    if (fw.state != RECEIVING) return reply(is_broadcast, ERR_NOT_ARMED);

    // --- sequence validation ------------------------------------------
    if (chunk_nb < fw.next_chunk) {                 // duplicate / retransmit
        return reply(is_broadcast, 0);              // idempotent ACK, no rewrite
    }
    if (chunk_nb > fw.next_chunk) {                  // gap → out of order
        return reply(is_broadcast, ERR_OUT_OF_ORDER);
    }

    // --- write + checksum ---------------------------------------------
    uint8_t plain[128];
    decrypt_chunk(&fw, chunk_nb, data, plain);      // no-op if unencrypted
    uint32_t addr = slot_start(fw.slot) + 128 * (chunk_nb - 1);
    flash_write(addr, plain, dlen);                 // BLOCKING on the reference MCU
    fw.crc_acc = crc32_update(fw.crc_acc, plain, dlen);
    fw.next_chunk = chunk_nb + 1;

    return reply(is_broadcast, 0);
}

// GET 0xc8cd  {} -> {u32 status, u32 crc}
status_t handle_file_report(uint8_t *resp) {
    uint32_t crc = crc32_final(fw.crc_acc);   // one's-complement
    wr_u32(resp + 0, fw.image_valid ? 0 : ERR_BAD_REPORT);
    wr_u32(resp + 4, crc);
    fw.listen_bc = 0;                          // disarm broadcast - avoid surprises
    return ACK;
}

// SET 0xc8c8  {u16 index, u32 value} -> {u32 status}
status_t handle_control(const uint8_t *req, uint8_t *resp) {
    uint16_t index = rd_u16(req);
    if (index == 0x0019) {                 // reset_device
        wr_u32(resp, 0);
        schedule_reboot_after_reply();     // defer to post-response callback
        return ACK;
    }
    wr_u32(resp, 0);                        // ignore unknown indices, still ACK
    return ACK;
}

const CHUNK_SIZE = 128
const PACING_MS  = 55          // inter-chunk delay for the blocking device model

function* chunks(image: Uint8Array) {
  // chunk 0 is the self-describing header, then 1..N are data
  yield { nb: 0, data: buildHeader(image) }
  for (let i = 0, nb = 1; i < image.length; i += CHUNK_SIZE, nb++) {
    yield { nb, data: image.subarray(i, i + CHUNK_SIZE) }
  }
}

async function flashOverRdm(node, port, targets: Uid[], image: Uint8Array) {
  const BROADCAST = uid(MANUFACTURER, 0xffffffff)   // mmmm:FFFFFFFF

  // 1 · Arm every target (unicast) so they accept broadcast chunks
  for (const uid of targets) {
    await rdmSet(node, port, uid, 0xc8d7, u32(1))   // flags: listen=1
  }

  // 2 · Stream the image once, to the whole family (vendorcast, no ACK)
  for (const { nb, data } of chunks(image)) {
    rdmSetNoReply(node, port, BROADCAST, 0xc8cf, concat(u32(nb), data))
    await sleep(PACING_MS)                            // pace for the slowest device
  }

  // 3 · Confirm each device individually (unicast GET)
  const failed: Uid[] = []
  for (const uid of targets) {
    const { status, crc } = await rdmGet(node, port, uid, 0xc8cd)
    if (status !== 0 || crc !== crc32(image)) failed.push(uid)
  }

  // 4 · Retry stragglers by unicast, then reboot everyone
  for (const uid of failed) await unicastFlash(node, port, uid, image)
  for (const uid of targets) {
    await rdmSet(node, port, uid, 0xc8c8, control(0x0019))   // reset_device
  }
}