Skip to main content

Minimal ecosystem for bare-metal RISC-V development

Project description


Minimal ecosystem for bare-metal RISC-V development


Bronzebeard is first and foremost a single-file nanopass assembler for developing bare metal RISC-V programs. It is designed for applications that stand on their own without relying on operating systems, frameworks, SDKs, or pre-existing software of any kind.


Much of modern software has accrued vast amounts of bulk and complexity throughout the years. Can useful software be developed without relying on any of it? That's the question that this project seeks to answer. I believe that the rise of RISC-V provides a great opportunity to explore different methods of program development. Installing a full operating system doesn't have to be a prerequisite to building something useful.

Check out the DerzForth project for further elaboration of this idea.


Bronzebeard and its tools are implemented purely in Python. It has been written in order to be free from large, complex toolchains. This keeps the project portable, minimal, and easy to understand.


The assembler itself supports the base 32-bit instruction set as well as the M, A, and C extensions (RV32IMAC). At the moment, Bronzebeard has only been used to target the Longan Nano and the Wio Lite. There are plans to test on additional RISC-V boards such as the HiFive1 Rev B in the future.


Most of the surface-level documentation for Bronzebeard lives right here in this README. For more specific details regarding the usage and accepted syntax of the assembler, check out the docs directory. This is where the project's primary documentation will live until the time comes to setup something more official.


If you are unfamiliar with virtual environments, I suggest taking a brief moment to learn about them and set one up. The Python docs provide a great tutorial for getting started with virtual environments and packages.

Bronzebeard can be installed via pip:

pip install bronzebeard


All major operating system platforms are supported: Windows, macOS, and Linux. In order to utilize Bronzebeard, you need to download and install a recent version of Python. For more info, Real Python has a great installation and setup guide that I recommend following.


The USB-based devices that Bronzebeard targets don't work well with Windows by default. They each need to be associated with the generic WinUSB driver in order to be identified and programmed. The easiest way to accomplish this is with a tool called Zadig. With the device attached to your computer (and in DFU mode, if applicable), use Zadig to assign the WinUSB driver to the device. Note that you will have to apply this driver assignment to each physical USB port that you want to use for programming the device.


The only extra requirement on macOS is libusb. It can be easily installed via homebrew.

brew install libusb


Programming devices over DFU requires libusb version 1.0 or greater. The following command will install the library on Debian-based Linux systems such as Debian, Ubuntu, Linux Mint, and Pop!_OS.

sudo apt install libusb-1.0-0-dev

For other Linux ecosystems, consult their respective package repositories.

If you'd like to program and interact with the device as a normal, non-root user, create the following udev rules file:

# /etc/udev/rules.d/99-bronzebeard.rules

# Longan Nano / Wio Lite
ATTRS{idVendor}=="28e9", ATTRS{idProduct}=="0189", MODE="0666"
# Adafruit USB to TTL Serial Cable
ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", MODE="0666"
# SparkFun USB to TTL Serial Cable
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666"

After the rules file is setup, reload udev via sudo udevadm control --reload.


usage: python -m bronzebeard.asm [-h] [--compress] [--verbose] [--version] input_asm output_bin

Assemble RISC-V source code

positional arguments:
  input_asm   input source file
  output_bin  output binary file

optional arguments:
  -h, --help  show this help message and exit
  --compress  identify and compress eligible instructions
  --verbose   verbose assembler output
  --version   print assembler version and exit


With Bronzebeard installed:

python3 -m bronzebeard.asm examples/example.asm example.bin

Program (via DFU)

NOTE: The DFU implemention included with Bronzebeard only supports the Longan Nano and Wio Lite at this time.

With the target device in DFU mode:

python3 -m bronzebeard.dfu <device_id> example.bin

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for bronzebeard, version 0.0.15
Filename, size File type Python version Upload date Hashes
Filename, size bronzebeard-0.0.15-py3-none-any.whl (20.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size bronzebeard-0.0.15.tar.gz (21.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page