nrfutil-web

Flash nRF52 firmware from the browser using Web Serial — no drivers, no desktop app required.

🔗 Live Demo

Features

• Uses the browser's Web Serial API
• Compatible with the Adafruit nRF52 bootloader DFU protocol
• Accepts ZIP packages generated by adafruit-nrfutil directly
• Supports Application, SoftDevice, Bootloader, and SD+BL updates
• Progress callback support
• TypeScript support with type definitions included
• Single dependency: jszip

Requirements

• A browser that supports Web Serial API (Chrome, Edge, etc.)
• A DFU package in ZIP format generated by adafruit-nrfutil

Installation

pnpm add nrfutil-web
# or
npm install nrfutil-web

Usage

Basic usage

import { performDfu, enterDfuMode } from "nrfutil-web";

// 1. Connect to the application port
const appPort = await navigator.serial.requestPort();

// 2. Trigger DFU mode via 1200bps touch
await enterDfuMode(appPort);

// 3. Wait for the device to re-enumerate, then select the DFU port
const dfuPort = await navigator.serial.requestPort();

// 4. Fetch firmware and flash
const zipData = await fetch("/firmware.zip").then(r => r.arrayBuffer());

await performDfu(dfuPort, zipData, {
  onProgress: ({ percent, message }) => {
    console.log(`${percent}% - ${message}`);
  },
});

API Reference

performDfu(port, zipData, options?)

Performs the DFU firmware update.

| Parameter | Type | Description | |---|---|---| | port | SerialPortLike | WebSerial port | | zipData | ArrayBuffer | DFU package ZIP | | options.onProgress | ProgressCallback | Progress callback | | options.ackTimeout | number | ACK timeout in ms (default: 5000) | | options.maxRetries | number | Max retries per packet (default: 3) | | options.singleBank | boolean | Single bank mode (default: true) |

enterDfuMode(port, waitTime?)

Sends a 1200bps touch to trigger DFU mode on the device.

| Parameter | Type | Description | |---|---|---| | port | SerialPortLike | WebSerial port | | waitTime | number | Wait time after touch in ms (default: 1500) |

ProgressCallback

type ProgressCallback = (progress: {
  sent: number;    // Bytes sent so far
  total: number;   // Total bytes to send
  percent: number; // Progress (0–100)
  message: string; // Current operation description
}) => void;

Advanced usage

Lower-level APIs are also available for advanced use cases.

import { DfuSerialTransport, parseDfuPackage } from "nrfutil-web";

// Parse the ZIP manually
const images = await parseDfuPackage(zipData);

// Operate the transport directly
const transport = new DfuSerialTransport(port, { ackTimeout: 10000 });
await transport.open();
await transport.sendPacket(payload);
await transport.close();

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Start demo page (examples/index.html)
pnpm dev

Architecture

src/
├── index.ts          # Public API
├── dfu.ts            # DFU main controller
├── transport.ts      # Serial transport (HCI / SLIP / ACK)
├── package.ts        # DFU ZIP package parser
├── dfu-protocol.ts   # Protocol constants and packet builders
├── hci.ts            # HCI packet handling
├── slip.ts           # SLIP encode / decode
└── crc16.ts          # CRC-16 calculation

License

BSD-3-Clause