Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

11.3 KB
Raw Blame
// The two things about a firmware push that fail silently and at the far end.
//
//  · WHICH image gets offered. Offering the wrong one is not a crash: the dial takes it, reboots, and runs
//    software nobody chose — the sibling product lost a fresh build to an older bundle twice before anyone
//    noticed, because `idf.py flash` said Done and the panel looked fine.
//  · HOW FAST it goes out. The ESP32-S3 USB peripheral has no back-pressure, so sending past the credit
//    window does not slow this side down — the dial's ring overflows and the bytes are gone with no error.
import { describe, expect, it, vi } from 'vitest'

import { CIRCLE_OTA_KEY, FW_MAX_RESENDS, FW_SLICE_BYTES, FW_WINDOW_BYTES, FirmwareTransfer, PRO_OTA_KEY, otaKeyFor, otaKeyForBoard, shouldOffer } from './fwPush.js'

describe('shouldOffer', () => {
  it('offers a strictly newer release', () => {
    expect(shouldOffer('0.0.35', '0.0.36')).toBe(true)
    expect(shouldOffer('0.0.35', '0.1.0')).toBe(true)
    expect(shouldOffer('v0.0.35', '0.1.0')).toBe(true)
  })

  it('does nothing for the same version', () => {
    expect(shouldOffer('0.0.35', '0.0.35')).toBe(false)
  })

  it('never rolls a dial backwards', () => {
    // A rollback is a decision made by publishing, not by whichever daemon happens to be plugged in.
    expect(shouldOffer('0.1.0', '0.0.36')).toBe(false)
  })

  it('never touches a dev build', () => {
    // ESP-IDF stamps `git describe` when the project sets no PROJECT_VER. Offering the published image to
    // one of these is exactly how a just-flashed build gets silently replaced seconds later.
    expect(shouldOffer('v0.3.38-36-gbc64073-dirty', '9.9.9')).toBe(false)
    expect(shouldOffer('0.0.35-dirty', '0.0.36')).toBe(false)
    expect(shouldOffer('', '0.0.36')).toBe(false)
  })
})

describe('FirmwareTransfer', () => {
  /** A transfer whose slices are collected instead of written to a port. */
  function make(size: number) {
    const sent: number[] = []
    const image = Buffer.alloc(size, 7)
    const t = new FirmwareTransfer(image, '1.2.3', async (slice) => { sent.push(slice.length) }, () => {})
    return { t, sent, image }
  }

  it('stops at the credit window and goes no further until acked', async () => {
    const { t, sent } = make(1_000_000)
    await t.pump()
    const inFlight = sent.reduce((a, b) => a + b, 0)
    expect(inFlight).toBeLessThanOrEqual(FW_WINDOW_BYTES + FW_SLICE_BYTES)

    // Nothing more moves without an ack — that is the whole mechanism. Calling pump() again must not
    // sneak another slice out.
    const before = sent.length
    await t.pump()
    expect(sent.length).toBe(before)
  })

  it('each ack releases exactly as much as it retired', async () => {
    const { t, sent } = make(1_000_000)
    await t.pump()
    const first = sent.length
    await t.onProgress(FW_SLICE_BYTES) // the dial wrote one slice
    expect(sent.length).toBe(first + 1)
  })

  it('delivers the whole image, in order, in slices no larger than the agreed one', async () => {
    const size = FW_SLICE_BYTES * 5 + 123
    const { t, sent } = make(size)
    await t.pump()
    let acked = 0
    while (acked < size) {
      acked = Math.min(acked + FW_SLICE_BYTES, size)
      await t.onProgress(acked)
    }
    expect(sent.reduce((a, b) => a + b, 0)).toBe(size)
    expect(Math.max(...sent)).toBeLessThanOrEqual(FW_SLICE_BYTES)
    expect(sent.at(-1)).toBe(123) // the tail is short, not padded
  })

  it('sends every slice exactly once when acks land mid-write', async () => {
    // THE FIELD FAILURE, REPRODUCED. On 2026-08-24 a 3,091,648-byte push reached the dial with slice 130
    // written twice — once where it belonged and once over slice 131, which never arrived at all. Both
    // writes were a full 8192 bytes, so the dial's counter read 3091648/3091648 and the daemon logged a
    // complete transfer; only esp_ota_end caught it, as a checksum error that pointed nowhere near here.
    //
    // The cause was ordinary: pump() advanced `offset` AFTER awaiting the write, and `fw.progress` — which
    // the read loop dispatches while that write is parked — called pump() again, which read the same
    // unadvanced offset and sent the same slice.
    //
    // Every other test in this file passes a sendSlice that returns immediately, which is why none of them
    // saw it: with no await gap there is no window for the ack to arrive in. This one parks, acks from
    // inside the write, and asserts on the reassembled BYTES rather than their count — the count was the
    // one thing that stayed correct.
    const slices = 40
    const size = FW_SLICE_BYTES * slices
    const image = Buffer.alloc(size)
    for (let i = 0; i < size; i++) image[i] = Math.floor(i / FW_SLICE_BYTES) & 0xff // each slice, its own byte

    const sent: Buffer[] = []
    let acked = 0
    let transfer: FirmwareTransfer
    transfer = new FirmwareTransfer(
      image,
      '1.2.3',
      async (slice) => {
        sent.push(Buffer.from(slice)) // a copy: the argument is a view into the image
        await Promise.resolve() // a real write parks here, several times, on a tty
        if (acked < size) {
          acked += FW_SLICE_BYTES
          void transfer.onProgress(acked) // the read loop does not wait for the writer, and neither does this
        }
      },
      () => {},
    )

    await transfer.pump()

    expect(sent.length).toBe(slices)
    expect(Buffer.concat(sent).equals(image)).toBe(true)
  })

  it('says how far it got when it is cut off', async () => {
    const log = vi.fn()
    const image = Buffer.alloc(100_000)
    const t = new FirmwareTransfer(image, '1.2.3', async () => {}, log)
    await t.pump()
    await t.onProgress(40_000)
    t.finish('interrupted by the port closing')
    expect(log).toHaveBeenCalledWith(expect.stringContaining('40000/100000'))
    // Finishing twice must not double-log: the port closing and the session ending both call it.
    t.finish('again')
    expect(log).toHaveBeenCalledTimes(1)
  })
})

describe('FirmwareTransfer with offsets (Pro) and resend', () => {
  const mk = (size: number, offsets: boolean, park?: (t: FirmwareTransfer) => Promise<void>) => {
    const image = Buffer.alloc(size)
    for (let i = 0; i < size; i++) image[i] = (i * 31 + (i >> 8)) & 0xff
    const frames: Buffer[] = []
    const t: FirmwareTransfer = new FirmwareTransfer(image, '1.2.3', async (s) => {
      frames.push(Buffer.from(s))
      await park?.(t)
    }, () => {}, { offsets })
    return { t, frames, image }
  }
  const off = (f: Buffer) => f.readUInt32LE(0)

  it('prefixes every slice with its LE offset, data at most 8188', async () => {
    const { t, frames, image } = mk(30_000, true)
    await t.pump()
    for (const f of frames) expect(f.length - 4).toBeLessThanOrEqual(8188)
    expect(frames.map(off)).toEqual(frames.map((_, i) => i * 8188))
    expect(frames.every((f) => f.subarray(4).equals(image.subarray(off(f), off(f) + f.length - 4)))).toBe(true)
  })

  it('round slices stay plain 8192 bytes with no prefix', async () => {
    const { t, frames, image } = mk(30_000, false)
    await t.pump()
    expect(frames[0]!.length).toBe(8192)
    expect(frames[0]!.equals(image.subarray(0, 8192))).toBe(true)
  })

  it('resend rewinds and re-sends the image from `written`', async () => {
    const { t, frames } = mk(100_000, true)
    await t.pump()
    const n = frames.length
    await t.onResend(8188)
    expect(off(frames[n]!)).toBe(8188)
    // the rest is delivered contiguously from the rewind point
    await t.onProgress(8188 + 16_000)
    const offs = frames.slice(n).map(off)
    expect(offs.every((o, i) => i === 0 || o > offs[i - 1]!)).toBe(true)
  })

  it('a resend during a parked write starts no second loop and duplicates nothing', async () => {
    let fired = false
    const { t, frames } = mk(8188 * 6, true, async (self) => {
      await Promise.resolve()
      if (!fired && frames.length === 2) {
        fired = true
        void self.onResend(0)
      }
    })
    await t.pump()
    // sent 0, 8188, then (rewound) 0, 8188 ... the window is not exceeded and no offset repeats back-to-back
    const offs = frames.map(off)
    expect(offs.slice(0, 3)).toEqual([0, 8188, 0])
    for (let i = 1; i < offs.length; i++) expect(offs[i]).not.toBe(offs[i - 1])
  })

  it('ignores stale resends', async () => {
    const { t, frames } = mk(100_000, true)
    await t.pump()
    await t.onProgress(16_376)
    const n = frames.length
    await t.onResend(8188) // behind acked
    await t.onResend(10_000_000) // beyond what was sent
    expect(frames.length).toBe(n)
  })

  it('gives up after too many resends', async () => {
    const { t } = mk(100_000, true)
    await t.pump()
    for (let i = 0; i <= FW_MAX_RESENDS && !t.isDone; i++) await t.onResend(0)
    expect(t.isDone).toBe(true)
  })
})

// ONE IMAGE PER BOARD, AND NEVER A GUESS.
//
// Until Harness Pro existed there was one kind of device on the cable, so the offer took the manifest's
// default entry. Two boards later that default is a brick: the Pro is an ESP32-P4 and the dial an
// ESP32-S3, neither can run the other's image, and the cable that would let anyone put it right is the
// firmware that just stopped booting. So the board decides the entry, and an unrecognised one is offered
// nothing at all.
describe('which firmware a board may be offered', () => {
  it('sends each board to its own manifest entry', () => {
    expect(otaKeyForBoard('cst9217+axp2101')).toBe(CIRCLE_OTA_KEY)
    expect(otaKeyForBoard('cst816s')).toBe(CIRCLE_OTA_KEY)
    expect(otaKeyForBoard('harness-pro')).toBe(PRO_OTA_KEY)
    expect(CIRCLE_OTA_KEY).not.toBe(PRO_OTA_KEY)
  })

  it('offers nothing to a board it does not recognise', () => {
    // A future board, or a device whose hello says something we have never seen. Refusing is the whole
    // point: the alternative is picking one of the two images we do have, and both are wrong.
    expect(otaKeyForBoard('harness-ultra')).toBeNull()
    expect(otaKeyForBoard('')).not.toBeNull()   // empty is "did not say", handled below — not unknown
  })

  it('pro with ota v1 is offered the harness-pro entry', () => {
    expect(otaKeyFor('harness-pro', 'pro', 'v1')).toBe(PRO_OTA_KEY)
  })

  it('pro without ota is not offered', () => {
    expect(otaKeyFor('harness-pro', 'pro', undefined)).toBeNull()
    expect(otaKeyFor('harness-pro', 'pro', 'v2')).toBeNull()
  })

  it('hw harness-pro without board is not offered', () => {
    expect(otaKeyFor('harness-pro', undefined, undefined)).toBeNull()
  })

  it('round choice unchanged', () => {
    expect(otaKeyFor('cst816s', undefined, undefined)).toBe(CIRCLE_OTA_KEY)
    expect(otaKeyFor(undefined, undefined, undefined)).toBe(CIRCLE_OTA_KEY)
    expect(otaKeyFor('harness-ultra', undefined, undefined)).toBeNull()
  })

  it('pro -pod version not offered', () => {
    expect(shouldOffer('0.0.99-pod', '0.1.0')).toBe(false)
  })

  it('pro equal or older version not offered', () => {
    expect(shouldOffer('0.1.0', '0.1.0')).toBe(false)
    expect(shouldOffer('0.2.0', '0.1.9')).toBe(false)
  })

  it('treats a device that does not say as the dial', () => {
    // The one place a guess is right. `hw` has been in the hello since before the Pro was designed, so a
    // build that omits it predates the Pro and can only be a dial. Refusing those would stop updates
    // reaching exactly the devices most in need of one.
    expect(otaKeyForBoard(undefined)).toBe(CIRCLE_OTA_KEY)
    expect(otaKeyForBoard(null)).toBe(CIRCLE_OTA_KEY)
  })
})