jumperless-boardboard-v5/RP23V50firmware/CodeDocs/Building_Native_Module.md

Building the Jumperless Native MicroPython Module

This guide explains how to build the Jumperless firmware with the native MicroPython module integration.

Prerequisites

• PlatformIO installed and configured
• Git (for MicroPython repository cloning)
• Build tools (make, gcc, etc.)

Build Process

1. Build MicroPython with Jumperless Module

First, build MicroPython with the native Jumperless module integrated:

# From the project root directory
./scripts/build_micropython.sh

This script will:

• Clone or update the MicroPython repository
• Build MicroPython embed port with the Jumperless module included
• Generate QSTR definitions for the Jumperless functions
• Verify the module integration

2. Build Jumperless Firmware

After MicroPython is built, compile the main firmware:

# Using PlatformIO
pio run

# Or using PlatformIO with specific environment
pio run -e pico

3. Upload to Device

# Upload firmware
pio run -t upload

# Or with specific environment
pio run -e pico -t upload

Build Verification

The build script will verify:

1. QSTR Generation: Confirms MicroPython QSTR definitions are generated
2. Jumperless QSTRs: Checks that Jumperless-specific function names are included
3. Module Files: Verifies all required source files are present
4. Configuration: Ensures the module is enabled in the configuration

Expected Output

◆ MicroPython embed build successful!
   Generated 1234 QSTR definitions
   Jumperless module QSTRs found: 25
   ◆ Jumperless MicroPython module found
   ◆ Jumperless API wrapper found
   ◆ Jumperless module enabled in configuration
◆ MicroPython is ready for use with Jumperless native module enabled!

Troubleshooting

Common Issues

1. Module Not Found

   ◇ Jumperless MicroPython module missing
   

   • Check that lib/micropython/modjumperless.cpp exists
   • Verify the USER_C_MODULES path is correct

2. API Wrapper Missing

   ◇ Jumperless API wrapper missing
   

   • Check that src/JumperlessMicroPythonAPI.cpp exists
   • Verify include paths in the source file

3. No Jumperless QSTRs

   Warning: No Jumperless module QSTRs detected
   

   • The module may not be properly registered
   • Check MODULE_JUMPERLESS_ENABLED is defined
   • Verify MP_REGISTER_MODULE call in the module source

4. Build Errors

   • Check that all include paths are correct in platformio.ini
   • Verify that required headers are available
   • Ensure MODULE_JUMPERLESS_ENABLED=1 is set in build flags

Debug Steps

1. Check Module Registration:

   grep -r "MP_QSTR_jumperless" lib/micropython/micropython_embed/
   

2. Verify Build Flags:

   grep -A5 "build_flags" platformio.ini
   

3. Check Include Paths:

   find . -name "modjumperless.cpp"
   find . -name "JumperlessMicroPythonAPI.cpp"
   

Runtime Testing

After successful build and upload, test the module:

# In MicroPython REPL
import jumperless

# Test basic functions
jumperless.dac_set(0, 2.5)
voltage = jumperless.adc_get(0)
print(f"ADC reading: {voltage}V")

# Test node connections
jumperless.nodes_connect(1, 5)
jumperless.nodes_disconnect(1, 5)

Or call the built-in test function from C++:

testJumperlessNativeModule();

File Structure

After building, the key files are:

lib/micropython/
├── modjumperless.cpp              # Native module implementation
├── micropython.mk                 # Module build configuration
├── mpconfigport.h                 # Module enabled flag
└── micropython_embed/             # Generated MicroPython files
    ├── genhdr/qstrdefs.generated.h    # QSTR definitions
    └── ...

src/
├── JumperlessMicroPythonAPI.cpp   # C++ wrapper functions
├── Python_Proper.cpp             # MicroPython integration
└── Python_Proper.h               # Header file

platformio.ini                    # Build configuration with module flags

Performance Benefits

The native module provides significant improvements over the string-based approach:

• ~10x faster execution - No string parsing overhead
• Better memory efficiency - No intermediate string buffers
• Type safety - Native Python type handling
• Error handling - Proper Python exceptions
• IDE support - Full Python syntax support

Next Steps

After successful build:

1. Test all hardware functions through the native module
2. Update existing Python code to use direct function calls
3. Remove old string-based command parsing code
4. Add additional hardware functions as needed

For usage examples, see examples/python_proper_native_demo.py.