Skip to content

compiling.md

Latest commit

 

History

History
103 lines (68 loc) · 2.28 KB

compiling.md

File metadata and controls

103 lines (68 loc) · 2.28 KB

RP2040 MicroPython Custom Build Reference

This document records the basic steps used to download MicroPython,

make a small board-level change, compile a custom RP2040 firmware,

and flash it.

1. Download MicroPython

git clone https://github.com/micropython/micropython.git
cd micropython
git submodule update --init --recursive

Purpose:

  • Downloads the MicroPython source code
  • Initializes required submodules (including TinyUSB)

2. Build the cross-compiler (required once)

make -C mpy-cross

Purpose:

  • Builds the mpy-cross tool
  • Required before building any MicroPython firmware

3. Board location

RP2040 boards are defined in:

ports/rp2/boards/

Example custom board:

ports/rp2/boards/SENSORS/

Minimum required files:

  • mpconfigboard.h
  • mpconfigboard.mk

4. Edit a basic board identity

File to edit:

ports/rp2/boards/SENSORS/mpconfigboard.h

Example values:

#define MICROPY_HW_BOARD_NAME "SENSORS"
#define MICROPY_HW_USB_MANUFACTURER_STRING "MACH"
#define MICROPY_HW_USB_PRODUCT_STRING "SENSORS RP2040"
#define MICROPY_HW_USB_SERIAL_STRING "SENSORS_001"

Notes:

  • Board name appears in os.uname() inside MicroPython
  • USB product strings may not be displayed by macOS for CDC devices

5. Build the firmware

cd ports/rp2
make BOARD=SENSORS

Result:

  • Output file:

      ports/rp2/build-SENSORS/firmware.uf2

6. Flash the UF2

Steps:

  1. Hold the BOOTSEL button
  2. Plug in the RP2040 over USB
  3. A USB mass-storage device appears
  4. Copy firmware.uf2 to the device
  5. The board reboots automatically

7. Verify the build

Open a serial session:

screen /dev/tty.usbmodemXXXX 115200

Inside MicroPython:

import os
os.uname()

Expected output includes:

machine='SENSORS with RP2040'

8. macOS notes

  • MicroPython uses USB CDC-ACM for serial communication
  • macOS assigns device names like /dev/tty.usbmodemXXXX automatically
  • The USB product name cannot control the /dev name
  • Firmware identity is best verified from inside MicroPython

Summary

  • MicroPython RP2040 builds are board-based
  • Board identity is set in mpconfigboard.h
  • Firmware is built with make BOARD=
  • macOS does not allow custom serial device names for CDC devices
  • Successful changes are confirmed using os.uname() inside the REPL