Fork of Web Bluetooth DFU for Nordic Semiconductors with stability and performance fixes
npm install @thib3113/web-bluetooth-dfuThis repository is a fork of the original web-bluetooth-dfu library, specifically enhanced to provide robust support for nRF52811 and nRF52833 devices. It introduces a modernized build system and critical stability fixes for production environments.
* Modern Build System: Updated to esbuild and TypeScript 5, providing a streamlined development experience and better tree-shaking.
* Reliable Data Transfer:
* Strict CRC Validation: Immediate termination on validation failure to prevent firmware corruption.
* Packet Receipt Notifications (PRN): Full implementation of PRN intervals (Opcode 0x02) for flow control.
* GATT Stability: Integrated a GATT Mutex to serialize write operations, effectively eliminating "GATT operation already in progress" errors.
* Simplified Deployment: Generates a standalone dist/secure-dfu.js bundle including all dependencies (JSZip, CRC32), ready for direct browser usage.
* Advanced Progress Tracking: Events now provide granular feedback, reporting both "Sent" and "Validated" byte counts.
* Smart Speed: Automatic degradation of transfer parameters (MTU, PRN) to adapt to unstable connections.
Tested and verified on nRF52811 and nRF52833 using stock Nordic bootloaders.
This library includes a "Smart Speed" feature designed to maximize performance on modern devices while maintaining reliability on older or unstable connections.
If enableSmartSpeed is set to true, the library monitors for transmission errors (GATT write failures or CRC mismatches). Upon encountering an error:
1. It retries the operation 3 times with the current settings to rule out transient glitches.
2. If errors persist, it degrades the MTU to the next safe tier: [100 -> 64 -> 32 -> 23].
3. If MTU is already at the minimum (23 bytes), it reduces the PRN interval (e.g., from 12 to 6, then 1) to ensure stricter flow control.
This allows the transfer to be fast by default but robust enough to finish even in difficult radio environments.
``typescript
const dfu = new SecureDfu(crc32);
// Enable Smart Speed (Auto Mode)
dfu.enableSmartSpeed = true;
// Optional: Configure manual starting points
dfu.packetSize = 100; // Default is 100
dfu.packetReceiptNotification = 12;
// Or use a custom strategy callback
dfu.enableSmartSpeed = (error, currentPrn, currentMtu) => {
console.warn(DFU Error: ${error}. Degrading...);`
// Return new settings or null to abort
return {
prn: Math.max(1, Math.floor(currentPrn / 2)),
packetSize: 20
};
};
---
Update device firmware via Nordic's DFU protocols using Web Bluetooth.
Since version 12 of Nordic's SDK, the device firmware update protocol has changed to be made secure. The protocol can be seen here:
https://infocenter.nordicsemi.com/topic/com.nordic.infocenter.sdk5.v12.0.0/lib_dfu_transport_ble.html
Earlier protocols were insecure, so it is recommended to use the secure protocol version in this package.
- Supports continuation of failed transfers and skipping of any init packet if already valid
- Supports Buttonless DFU activation
- Uses ES6 syntax assuming that all JS engines supporting Web Bluetooth are also ES6 compatible
- Written with TypeScript to promote type safety
This repo has a live web example of the secure DFU. Open this site in a Web Bluetooth enabled browser:
https://thib3113.github.io/web-bluetooth-dfu/
- Supports drag-and-drop or uploading of firmware packages
- Supports unzipping of the firmware package in-browser
- Supports multiple firmware images in a single package (softdevice, bootloader, application)
* Node.js v18 or newer.
* A browser with Web Bluetooth support (Chrome, Edge, Opera).
`bash`
npm install @thib3113/web-bluetooth-dfu
If you are contributing or want to build the bundles yourself:
`bash`
npm install
npm run builddist/
The output will be in the folder.
You can use the standalone bundle which includes all dependencies:
`html`
`typescript`
import { SecureDfu, SecureDfuPackage } from '@thib3113/web-bluetooth-dfu';
You will need a Nordic nRF51822, nRF52832 or nRF52840 development kit running the latest softdevice. Secure DFU supports softdevices from S130.
Softdevices can be found on Nordic's site:
- S130 (for nRF51)
- S132 (for nRF52)
- S140 (for nRF52)
Upon flashing the device will be in bootloader mode and ready to receive a DFU transfer.
Example packages to update can be found in the firmware folder.
An excellent article exists with a walkthrough of using the device firmware update here:
https://devzone.nordicsemi.com/blogs/1085/getting-started-with-nordics-secure-dfu-bootloader/
tl;dr
__J-LINK Interface Firmware__
- Ensure device is running the J-LINK interface firmware available from Nordic
__Download / Install__
- Download Nordic SDK
- Install J-Link Software Package
- Install nRF5x Command Line Tools (includes nrfjprog)
- Install __nrfutil__: $ pip install nrfutil
__Flashing SoftDevice__
- Erase the chip: $ nrfjprog --family NRF52 --eraseall$ nrfjprog --family NRF52 --program
- Grab the relevant softdevice from website (links above) or the SDK (components/softdevice/\
- Flash the softdevice:
__Using Test DFU Bootloader__
- Grab the relevant bootloader from the SDK (examples/dfu/bootloader_secure_ble/\
- Flash the bootloader: $ nrfjprog --family NRF52 --program
__Signing Keys__
- Create a signing key: $ nrfutil keys generate private.key$ nrfutil keys display --key pk --format code private.key --out_file dfu_public_key.c
- Generate the __.c__ file for the key:
__Developing an Application__
- Ensure you have a machine with relevant build tools such as gcc, linux is easiest$ nrfjprog --family NRF52 --program
- Rebuild the bootloader with your new key (Update the Makefile to use your new key file)
- Flash the bootloader:
- Build your application using your new key file
__Building DFU Package__
Refer to this document:
https://infocenter.nordicsemi.com/topic/com.nordic.infocenter.sdk5.v13.0.0/ble_sdk_app_dfu_bootloader.html
e.g.:
$ nrfutil pkg generate --debug-mode --application