MCU Manager (Web Bluetooth)

This tool is the Web Bluetooth version of MCU Manager that enables a user to communicate with and manage remote devices running the Mynewt OS. It uses a connection profile to establish a connection with a device and sends command requests to the device.

The main focus is implementing firmware updates via Web Bluetooth, however other commands might be supported as well.

Features

• Firmware Upload: Upload MCUboot-formatted firmware images over Bluetooth LE
• Image Management: Test, confirm, and erase firmware images
• Device Control: Reset device, send echo commands
• Progress Tracking: Real-time upload progress updates
• Auto-Reconnect: Automatic reconnection and upload resumption on connection loss
• Image Validation: Pre-upload validation of MCUboot image format

Quick Start

Online: Try MCU Manager by visiting https://boogie.github.io/mcumgr-web/ with a supported browser.

Local: With the latest Chrome or Edge, simply open index.html directly in your browser.

Note: When using a web server, Web Bluetooth requires HTTPS or localhost for security reasons.

Browser Compatibility

The Web Bluetooth API provides the ability to connect and interact with Bluetooth Low Energy peripherals.

Compatibility Matrix

Platform	Browser	Support	Notes
Windows	Chrome	✅ Full	Recommended
Windows	Edge	✅ Full	Chromium-based
Windows	Opera	❌ No	Web Bluetooth disabled by default
Windows	Firefox	❌ No	Not implemented
macOS	Chrome	✅ Full	Recommended
macOS	Edge	✅ Full	Chromium-based
macOS	Opera	❌ No	Web Bluetooth disabled by default
macOS	Safari	❌ No	Web Bluetooth not supported
macOS	Firefox	❌ No	Not implemented
Linux	Chrome	✅ Full	Recommended
Linux	Edge	✅ Full	Chromium-based
Linux	Opera	❌ No	Web Bluetooth disabled by default
Linux	Firefox	❌ No	Not implemented
Android	Chrome	⚠️ Possible	Untested, likely works
Android	Edge	⚠️ Possible	Untested, likely works
Android	Opera	⚠️ Possible	Untested, likely works
Android	Firefox	❌ No	Not implemented
iOS / iPadOS	Safari	❌ No	WebKit limitation
iOS / iPadOS	Chrome	❌ No	Uses WebKit engine
iOS / iPadOS	Edge	❌ No	Uses WebKit engine
iOS / iPadOS	Bluefy	⚠️ Possible	May require app updates

Legend:

• ✅ Full Support - Tested and working
• ⚠️ Possible - Might work but untested
• ❌ No Support - Web Bluetooth not available

Notes:

• Safari, Chrome, Edge, and Opera on iOS use the Safari WebKit engine, which does not support Web Bluetooth
• Desktop and mobile Firefox have not implemented Web Bluetooth
• Opera has Web Bluetooth disabled by default and cannot be enabled
• For the best experience, use the latest version of Chrome or Edge
• Android Chrome should work but is untested
• On iOS/iPadOS, Bluefy may work but might require updates

Documentation

• API.md - Complete API reference and usage examples
• PROTOCOL.md - SMP protocol specification and MCUboot image format
• CONTRIBUTING.md - Contributing guidelines and development setup

Setting up on your machine

Simple Method (Chrome & Edge):

With the latest versions of Chrome and Edge, you can simply open index.html directly in your browser - no web server needed.

Web Server Method (Optional):

For other browsers or older versions, you can serve the files using a local web server:

Python:

python -m http.server 8000

Node.js:

npx http-server -p 8000

PHP:

php -S localhost:8000

Then visit http://localhost:8000/

Usage Example

// Create MCU Manager instance
const mcumgr = new MCUManager();

// Set up event handlers
mcumgr
  .onConnect(() => console.log('Connected!'))
  .onImageUploadProgress(({ percentage }) =>
    console.log(`Upload: ${percentage}%`)
  );

// Connect to device
await mcumgr.connect();

// Upload firmware
const response = await fetch('firmware.bin');
const imageBuffer = await response.arrayBuffer();
await mcumgr.cmdUpload(imageBuffer);

See API.md for complete documentation.

Development

Running Tests

This project uses Jest for automated testing. Tests are automatically run on every git commit via pre-commit hooks.

Install dependencies:

npm install

Run tests:

npm test

Run tests in watch mode:

npm run test:watch

Generate coverage report:

npm run test:coverage

Test Structure

• __tests__/mcumgr.test.js - Tests for the MCUManager class (connection, messaging, image upload, validation)
• __tests__/cbor.test.js - Tests for CBOR encoding/decoding
• __tests__/setup.js - Test environment setup and mocks

The test suite includes 73 tests covering:

• MCUManager class functionality
  • Constructor and dependency injection
  • Callback registration
  • Device connection and disconnection
  • Message protocol (SMP)
  • Image validation and parsing
  • Firmware upload with chunking
  • Command methods (reset, echo, image state, etc.)
  • Sequence number management
• CBOR encoding/decoding
  • Primitive types (boolean, null, undefined)
  • Numbers (integers, floats, large numbers)
  • Strings (ASCII, UTF-8, long strings)
  • Byte arrays
  • Arrays and nested arrays
  • Objects and nested objects
  • Complex MCU Manager message structures

Pre-commit Hooks

Tests are automatically run before each commit using Husky. If tests fail, the commit will be blocked. This ensures code quality and prevents regressions.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

We're especially looking for help with:

• Testing on different devices and browsers
• Adding support for additional SMP commands
• Improving documentation and examples
• Bug reports and feature requests

License

See LICENSE file for details.

Links

• Live Demo: https://boogie.github.io/mcumgr-web/
• MCUboot: https://www.mcuboot.com/
• Apache Mynewt: https://mynewt.apache.org/
• Web Bluetooth API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API