Proposal: Enhanced MicroPython REPL with Spawn Capability and Security Features

[itaysaadia]

Proposal: Enhanced MicroPython REPL with Spawn Capability and Security Features

Dear MicroPython Community,

I’d like to propose a new feature for MicroPython: the ability to spawn a REPL instance programmatically at runtime. This feature would function similarly to IPython.embed(), allowing users to drop into an interactive REPL environment at any point in their code without resetting the device.

This mode is important especially for production devices that are in secure boot without the dev mode. For these cases we’ll want to enable the REPL if and only if the fuse burnt password is correct.

Key Features and Benefits

1. Dynamic Debugging

• Developers can inspect, modify, and interact with the live state of their application at runtime.
• Unlike the current REPL, this spawned REPL can be exited gracefully, allowing the user to return to normal program execution.

2. Security Integration

• To prevent unauthorized access, this feature can be secured with a password. In my implementation, the password is read directly from the device's eFuse memory (ESP32-S3), ensuring hardware-level security.

3. Portability

• The feature is implemented in Python, making it easy to adapt and extend for other MicroPython platforms.

4. Custom REPL Enhancements

• Includes advanced line editing, tab-based autocomplete, history navigation, and paste mode support.

Implementation Details

I have developed a prototype implementation comprising two parts:

1. repl.py: A fully functional REPL implementation that supports custom input handling and advanced editing capabilities. (Pure MicroPython, tested on ESP32-S3 but should work anywhere)
2. read_fuses.py: A utility to read eFuse memory blocks on the ESP32-S3, which can be used for secure password storage. (Specific for ESP32-S3)

Code Snippets

Custom REPL (repl.py)

A robust REPL implementation supporting:

• Tab-completion
• History navigation
• Paste mode (triggered by Ctrl+E)

import sys
import micropython

ESC = '\x1b'
CTRL_C = '\x03'
CTRL_D = '\x04'
CTRL_E = '\x05'     # <-- paste mode hotkey
BACKSPACE = '\x7f'  # Some terminals may send '\x08' instead
ENTER = '\r'        # or '\n'
TAB = '\x09'

def raw_repl():
    """
    A basic custom REPL demonstrating:
      - Character-by-character input
      - Line editing (left/right arrow, backspace)
      - Tab-based autocomplete
      - Up/down arrow history
      - Paste mode (Ctrl+E enters raw mode, read until Ctrl+D)
    """
    history = []

    micropython.kbd_intr(3)  # Enable interrupt for ^C
    while True:
        line = edit_line(prompt="#>> ", history=history)
        if line is None:
            print()
            break
        if line == "":
            continue
        if line.strip() in ("exit", "quit", "bye"):
            print("Goodbye!")
            break
        if line.strip():
            history.append(line)
        try:
            code = compile(line, "<stdin>", "single")
            exec(code, globals(), globals())
        except Exception as ex:
            print(ex)
    micropython.kbd_intr(-1)  # Disable interrupt for ^C

def edit_line(prompt="#>> ", history=None):
    if history is None:
        history = []

    line_chars = []
    cursor_pos = 0
    history_index = len(history)

    _print(prompt)

    while True:
        c = sys.stdin.read(1)
        if not c:
            return None
        if c == CTRL_C:
            _print("^C\n")
            return ""
        if c == CTRL_D:
            return None
        if c == CTRL_E:
            _print("\n=== Paste mode (Ctrl+D to finish) ===\n")
            _paste_mode()
            return ""
        if c in ("\r", "\n"):
            _print("\n")
            return "".join(line_chars)
        if c in (BACKSPACE, '\x08'):
            if cursor_pos > 0:
                del line_chars[cursor_pos - 1]
                cursor_pos -= 1
            _redraw_line(prompt, line_chars, cursor_pos)
            continue
        if c == ESC:
            seq = sys.stdin.read(1)
            if seq == '[':
                arrow_cmd = sys.stdin.read(1)
                if arrow_cmd == 'A':
                    if history and history_index > 0:
                        history_index -= 1
                        line_str = history[history_index]
                        line_chars = list(line_str)
                        cursor_pos = len(line_chars)
                        _redraw_line(prompt, line_chars, cursor_pos)
                elif arrow_cmd == 'B':
                    if history and history_index < len(history):
                        history_index += 1
                        if history_index == len(history):
                            line_chars = []
                            cursor_pos = 0
                        else:
                            line_str = history[history_index]
                            line_chars = list(line_str)
                            cursor_pos = len(line_chars)
                        _redraw_line(prompt, line_chars, cursor_pos)
                elif arrow_cmd == 'C':
                    if cursor_pos < len(line_chars):
                        cursor_pos += 1
                        _redraw_line(prompt, line_chars, cursor_pos)
                elif arrow_cmd == 'D':
                    if cursor_pos > 0:
                        cursor_pos -= 1
                        _redraw_line(prompt, line_chars, cursor_pos)
            continue
        if c == TAB:
            new_line_chars, new_cursor_pos = _attempt_autocomplete(line_chars, cursor_pos)
            line_chars, cursor_pos = new_line_chars, new_cursor_pos
            _redraw_line(prompt, line_chars, cursor_pos)
            continue
        line_chars.insert(cursor_pos, c)
        cursor_pos += 1
        _redraw_line(prompt, line_chars, cursor_pos)

def _paste_mode():
    paste_buffer = []

    while True:
        c = sys.stdin.read(1)
        if not c:
            break
        if c == CTRL_D:
            break
        paste_buffer.append(c)
        _print(c)

    code_str = "".join(paste_buffer)
    _print("\n=== Executing pasted code ===\n")

    try:
        code = compile(code_str, "<paste>", "exec")
        exec(code, globals(), globals())
    except Exception as ex:
        print(ex)
    _print("=== End paste mode ===\n")

# Helper functions omitted for brevity

Secure Password Reading from eFuses (read_fuses.py)

This utility demonstrates how to securely read hardware-level eFuse memory to protect sensitive data.

import ustruct as struct
import machine
import micropython

def signedToUnsigned(i): 
    packed = struct.pack('>l', i)  # Packing a long number.
    return struct.unpack('>L', packed)[0]  # Unpacking a packed long number to unsigned long

EFUSE_BASE = const(0x60007000)

def read_efuse_word(offset):
    return signedToUnsigned(machine.mem32[EFUSE_BASE + offset])

def read_efuse_block(offset, num_words):
    return [read_efuse_word(offset + 4*i) for i in range(num_words)]

def dump_all_efuses():
    blocks = [
        ("BLK0_PART0", read_blk0_part0),
        ("BLK0_PART1", read_blk0_part1),
        ("BLK1", read_blk1),
        ("BLK2", read_blk2),
    ]

    for (name, func) in blocks:
        data = func()
        print(f"=== {name} ===")
        for i, word in enumerate(data):
            print(f"  Word {i}: 0x{word:08X} (dec: {word})")

Usage Example

1. Initialize the secure REPL:

   import repl  
   repl.raw_repl()  # Start the interactive REPL session  

2. Secure access by validating the password using eFuses before granting REPL access:

   password = read_fuses.read_blk2()  # Example block containing password  
   # Validate password and grant access  

Next Steps

I believe this feature could significantly enhance MicroPython’s debugging capabilities, particularly for applications running on embedded devices. While my implementation is a prototype, I see it as a solid foundation for further development.

I’m sharing this with the community to gather feedback and assess interest in integrating such functionality into the main MicroPython project.

Feel free to review the code, test it, and suggest improvements.

---

Best regards,
Itay Saadia

[peterhinch]

Have you seen the official aiorepl?

[itaysaadia]

It looks like I've spent WAY much time by not noticing it 🤦 Thank you so much!!

[stinos]

The feature is implemented in Python, making it easy to adapt and extend for other MicroPython platforms.

Maybe I'm missing something here but wouldn't it be possible to use the existing repl code (see pyexec.c) for this instead, by exposing it as a Python function?
It's already implemented, it's probably smaller in code size, it already works for any platform which has a REPL, and it would use the exact same keyboard shortcuts and other behavior without having to reimplement it all in Python.

[itaysaadia]

I didn't wanted to patch micropython itself for it. I thought about it, but eventually I decided to stick to a stable build of micropython.

[Jonty]

@itaysaadia The official aiorepl doesn't support tab completion but yours did - would you consider publishing the full code so we can port that aspect upstream? Or you could do it!

[andrewleech]

Good reminder, I'm working on bringing tab complete to aiorepl by exposing the underlying c impl so aiorepl can call through to it.

Testing of it was blocked waiting for Unix repl improvements to get merged, which was recently completed, so I should get back to the tab complete work!