Interface

BL4818 Brushless Servo Musical Actuator

This repository contains the electronics, embedded firmware, host software, and browser players for a network of brushless servo percussion actuators. The actuators use modified BL4818 motor-controller hardware, a Nuvoton M2003 microcontroller, hall sensing, and an MT6701 absolute encoder to move a mallet with controlled timing and force.

The system is in active use: roughly 35 actuators have been built, and the firmware plus MIDI player/server are working well. The software is much closer to production-ready than the replication documentation, so this repository should currently be treated as a proven project under documentation rather than a turn-key kit.

Watch

check out video of these actuators playing various instruments on my Instagram!

Each self-contained actuator packages the modified BL4818 motor controller, absolute encoder, power/data interface, and mallet mechanism inside the printed shell. RX and TX connectors allow power and serial data to continue through the actuator chain, while the recessed SWD port provides programming access.

System overview

flowchart LR
    MIDI["MIDI file or browser player"] --> HTTP["Python MIDI server"]
    HTTP --> IFACE["USB serial / interface hardware"]
    IFACE --> A0["Actuator 0"]
    A0 --> A1["Actuator 1"]
    A1 --> AN["More actuators"]
    AN --> IFACE

The Python server owns the serial port and serves the browser UI. It enumerates the actuator ring, maps MIDI pitches to actuator addresses, schedules strikes, compensates for measured mechanical latency, and can build then deploy APROM updates through the permanent LDROM loaders without releasing the serial port. The updater and synchronized chord scheduler are hardware-validated on the 14-actuator handpan ring. Each actuator closes its own current, velocity, and position loops and runs the homing/strike state machine. The current protocol uses a four-bit address and supports up to 16 actuators per ring.

What is in this repository

• src/ and include/: M2003 bare-metal firmware.
• scripts/: ring-bus client, MIDI server, tuning, measurement, and demo tools.
• player/: browser-based MIDI player, looper, and tongue-drum player.
• pcb/: KiCad electronics plus current mechanical/fabrication exports.
• mechanical/: SolidWorks source CAD and STEP exports for the actuator shell, mallet holder, and interface-board reference model.
• docs/: replication notes, hardware references, debug history, and design notes.
• protocol.md: byte-level Ring Bus Protocol v2 specification.
• midi_server_api.md: HTTP API for integrations and custom players.

See Repository map for a guided tour.

Quick software start

The firmware builds on Windows and POSIX hosts, including Raspbian. Its Makefile expects GNU Make and the Arm GNU toolchain in PATH. Initial SWD provisioning still uses the PowerShell/J-Link scripts and is therefore Windows-oriented.

1. Install host dependencies

Install Python 3.10 or newer, then from the repository root run:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -r requirements.txt

2. Build the firmware

Install arm-none-eabi-gcc and GNU Make, then run:

make

The main output is build/m2003-motor.bin. Generate the complete J-Link payload (application, commit manifest, permanent LDROM loader, and read-only CONFIG capture) with:

powershell -File scripts/build-jlink.ps1

Generation does not contact hardware or change CONFIG. The stable Gen1 ring updater, its recovery evidence, and its completed 14-actuator validation are documented in Ring firmware update. The LDROM loader is now maintenance-only; no further Gen1 loader features are planned.

3. Flash an actuator

Connect the programmer over SWD and run:

powershell -File scripts/flash-jlink.ps1

For J-Link V9.58 or newer, use the faster native M2003FC1AE flash loader:

powershell -ExecutionPolicy Bypass -File scripts/flash-jlink.ps1 -NativeFlash

Add -SkipBuild to reuse the generated artifacts, or -GenerateOnly to build them without contacting hardware. Native mode retains the CONFIG preservation, commit-last manifest, and physical verification described below. Omitting -NativeFlash retains the original per-word programming method.

This standard command first records CONFIG0..2, programs and byte-verifies APROM, its manifest, and LDROM, then preserves the existing configuration while selecting LDROM-first boot. It refuses automatic CONFIG changes on a locked or unexpected security configuration. Disconnect motor power while changing wiring or attaching the programmer; a servo actuator can move unexpectedly during bring-up.

4. Start the MIDI player

Connect the interface serial port to a powered actuator ring and run:

py scripts/ring_midi_server.py -p COM7 --library-dir C:\path\to\midi-library

Open http://localhost:8765/. Enumerate the ring, home the actuators, and assign a MIDI pitch to each slot before playing a file. Use the instrument selector to save and switch named pitch maps and player settings. Profiles are stored locally in instruments.json and are intentionally not committed. An existing mapping.json is imported as the Default profile.

For multiple rings, use one USB adapter per ring (at most 16 actuators each):

py scripts/ring_midi_server.py --ring jameson=COM29,10 --ring retuned=COM48,10

The player provides a saved-instrument selector for each ring and shared playback controls. See multiple-ring setup for profile persistence and slot routing. The Firmware panel lets you select rings to update and processes them one after another.

For a first hardware check without the browser:

py scripts/ring_tool.py -p COM7 enumerate
py scripts/ring_tool.py -p COM7 status 0

Run py scripts/ring_tool.py --help for the complete command list.

Documentation

• Replication guide: staged path from hardware to a playing ring.
• Hardware guide: current BL4818 modification and actuator assembly architecture.
• Performance video: ten actuators playing with sound.
• Firmware guide: architecture, build, flash, and module boundaries.
• Ring firmware update: stable LDROM recovery design, flash layout, operation, and validation record.
• Host software guide: server, browser players, and bench tools.
• Replication status: what is reproducible now and what still needs source material.
• Ring Bus Protocol v2: serial packet and command specification.
• MIDI server HTTP API: integration API.
• Design decisions and debug log: engineering history.

Replication status and safety

The repository does not yet contain enough verified information for a new builder to safely reproduce the complete actuator without assistance. In particular, power-system limits, connector pinouts, a released BOM, mechanical assembly dimensions, and a photographed bring-up procedure still need to be documented. Those gaps are tracked explicitly in Replication status; unknown values are not guessed in the guides.

This project drives a fast moving mechanism at several amps. Use a current- limited supply during bring-up, keep hands and instruments clear of the mallet, provide a physical power disconnect, and test one actuator before assembling a ring.

License

No project-wide license has been selected yet. Until one is added, the source is visible for evaluation but normal open-source reuse permissions have not been granted. A license should be chosen before presenting the repository as a fully replicable open-source project; third-party code under CMSIS/, Library/, and RTT/ retains its own notices and terms.