How to Build MicroPython

Building MicroPython from source gives you full control over the features, modules, and performance of your firmware. Whether you’re targeting ESP32, ESP8266, RP2040, or STM32, customizing the firmware helps you:

• Reduce firmware size
  
• Improve execution speed
  
• Optimize memory usage
  
• Add your own modules and hardware features
  
• Tailor the firmware for production-grade devices
  

These steps are highly searched by developers and IoT engineers, making customization topics powerful for SEO and organic traffic.

Enable or Disable Modules (Shrink Firmware Size)

MicroPython comes with many built-in modules, but not all of them are necessary for every project. Disabling unneeded features can significantly cut down the firmware size—especially useful on memory-constrained boards like ESP8266 or small STM32 variants.

Where to Edit Module Settings

Navigate to:

/ports/<selected_port>/mpconfigport.h

Example: Turning Off Unused Modules

Disable modules you don’t need:

// Turn off SSL support

#undef MICROPY_PY_SSL

#define MICROPY_PY_SSL 0

// Disable hashlib to save space

#undef MICROPY_PY_HASHLIB

#define MICROPY_PY_HASHLIB 0

Enable Only What You Need

#define MICROPY_PY_UHASHLIB 1

#define MICROPY_PY_UBINASCII 1

Outcome

• Smaller firmware image
  
• Reduced boot time
  
• More free RAM for Python scripts
  

This is one of the fastest ways to optimize MicroPython for real-world IoT applications.

Add Your Own C Module to MicroPython

If you need fast native performance or want to interface with hardware that MicroPython doesn’t support out of the box, you can integrate your own C module. This lets you extend MicroPython exactly the way you want, while keeping Python as the high-level user interface.

Minimal Example of a Custom C Module

Create a folder for your module:

/modules/custom_mod/

Add custom_mod.c:

#include “py/obj.h”

STATIC mp_obj_t custom_hello(void) {

    return mp_obj_new_str(“Hello from Custom Module!”, 27);

}STATIC MP_DEFINE_CONST_FUN_OBJ_0(custom_hello_obj, custom_hello);

STATIC const mp_rom_map_elem_t custom_module_globals_table[] = {

    { MP_ROM_QSTR(MP_QSTR_hello), MP_ROM_PTR(&custom_hello_obj) },

};STATIC MP_DEFINE_CONST_DICT(custom_module_globals, custom_module_globals_table);

const mp_obj_module_t custom_module = {

        .globals = (mp_obj_dict_t *)&custom_module_globals,

};MP_REGISTER_MODULE(MP_QSTR_custom, custom_module);

Now you can use it in MicroPython:

import custom

print(custom.hello())

Connect the Module to the Build System

In your board or port configuration, enable module registration:

mpconfigport.h

#define MICROPY_REGISTER_MODULE 1

Then add your file to the build:

Makefile

SRC_USERMOD += modules/custom_mod/custom_mod.c

or for CMake-based ports (ESP32, RP2040):

add_subdirectory(modules/custom_mod)

Rebuild the firmware to include your new module.

Freeze Python Scripts Into the Firmware

Freezing Python files is a powerful optimization technique. When your .py scripts are frozen:

• They run faster because they’re pre-compiled
  
• They don’t occupy RAM
  
• Firmware behaves more predictably during boot
  

This is perfect for production IoT devices, robotics systems, and low-memory MCUs.

Where to Place Frozen Files

Save your Python scripts in:

/ports/<port>/modules/

Example: app.py

def run():

    print(“Running from frozen firmware!”)

After flashing, run it in REPL:

import app

app.run()

Benefits

• Zero RAM usage for the script
  
• Faster startup
  
• Great for fixed application logic
  

Modify Board Configuration Files

Each board supported by MicroPython has its own configuration folder. Editing these files lets you define custom pins, enable peripherals, or adjust hardware-specific settings. This is crucial when working with custom hardware or modified development boards.

Where Board Configurations Live

/ports/<port>/boards/<board_name>/

Important files include:

Custom Pin Example

In pins.csv:

PA0, UART2_TX

PA1, UART2_RX

PB5, LED

PB6, I2C1_SCL

PB7, I2C1_SDA

You can now use those pins directly in Python:

from machine import Pin

led = Pin(“PB5”, Pin.OUT)

Add Peripherals (I2C, SPI, ADC, PWM, CAN)

Enable peripherals in mpconfigboard.h:

#define MICROPY_HW_ENABLE_I2C1 1

#define MICROPY_HW_ENABLE_SPI1 1

#define MICROPY_HW_ENABLE_CAN  1

#define MICROPY_HW_ENABLE_ADC  1

This lets you tailor MicroPython for custom hardware, industrial controllers, or complex IoT devices.

Understanding the “ports” Directory

The ports/ folder contains all architecture-specific implementations for MicroPython. Each subfolder corresponds to a supported microcontroller platform:

ports/

├── esp32/

├── esp8266/

├── rp2/          # RP2040

├── stm32/

├── zephyr/

├── nrf/

├── renesas-ra/

Each port includes:

• Device drivers
  
• Board definitions
  
• Build scripts (Make/CMake)
  
• Flashing utilities
  
• Low-level hardware interfaces
  

Learning this structure helps you navigate, customize, and extend MicroPython at the source level.