A minimal implementation of debugpy for MicroPython, enabling remote debugging

such as VS Code debugging support.

- Debug Adapter Protocol (DAP) support for VS Code integration

- Basic debugging operations:

- Breakpoints

- Step over/into/out

- Stack trace inspection

- Variable inspection (globals, locals generally not supported)

- Expression evaluation

- Pause/continue execution

- MicroPython with `sys.settrace` support (enabled with `MICROPY_PY_SYS_SETTRACE`)

- Socket support for network communication

- JSON support for DAP message parsing

import debugpy

host, port = debugpy.listen() # Default: 127.0.0.1:5678

print(f"Debugger listening on {host}:{port}")

debugpy.debug_this_thread()

def my_function():

x = 10

y = 20

result = x + y # Set breakpoint here in VS Code

return result

result = my_function()

print(f"Result: {result}")

debugpy.breakpoint()

Create a `.vscode/launch.json` file in your project:

{

"version": "0.2.0",

"configurations": [

{

"name": "Attach to MicroPython",

"type": "python",

"request": "attach",

"connect": {

"host": "127.0.0.1",

"port": 5678

},

"pathMappings": [

{

"localRoot": "${workspaceFolder}",

"remoteRoot": "."

}

],

"justMyCode": false

}

]

}

1. Build the MicroPython Unix coverage port:

```bash

cd ports/unix

make CFLAGS_EXTRA="-DMICROPY_PY_SYS_SETTRACE=1"

```

2. Run the test script:

```bash

cd lib/micropython-lib/python-ecosys/debugpy

../../../../ports/unix/build-coverage/micropython test_debugpy.py

```

3. In VS Code, open the debugpy folder and press F5 to attach the debugger

4. Set breakpoints in the test script and observe debugging functionality

Start listening for debugger connections.

**Parameters:**

- `port`: Port number to listen on (default: 5678)

- `host`: Host address to bind to (default: "127.0.0.1")

**Returns:** Tuple of (host, port) actually used

Enable debugging for the current thread by installing the trace function.

Trigger a manual breakpoint that will pause execution if a debugger is attached.

Wait for the debugger client to connect and initialize.

Check if a debugger client is currently connected.

**Returns:** Boolean indicating connection status

Disconnect from the debugger client and clean up resources.

The implementation consists of several key components:

1. **Public API** (`public_api.py`): Main entry points for users

2. **Debug Session** (`server/debug_session.py`): Handles DAP protocol communication

3. **PDB Adapter** (`server/pdb_adapter.py`): Bridges DAP and MicroPython's trace system

4. **Messaging** (`common/messaging.py`): JSON message handling for DAP

5. **Constants** (`common/constants.py`): DAP protocol constants

This is a minimal implementation with the following limitations:

- Single-threaded debugging only

- No conditional breakpoints

- No function breakpoints

- Limited variable inspection (no nested object expansion)

- No step back functionality

- No hot code reloading

- Simplified stepping implementation

Tested with:

- MicroPython Unix port

- VS Code with Python/debugpy extension

- CPython 3.x (for comparison)

This implementation provides a foundation for MicroPython debugging. Contributions are welcome to add:

- Conditional breakpoint support

- Better variable inspection

- Multi-threading support

- Performance optimizations

- Additional DAP features

MIT License - see the MicroPython project license for details.

import socket

import threading

import json

import time

import sys

class DAPMonitor:

def __init__(self, listen_port=5679, target_host='127.0.0.1', target_port=5678):

self.listen_port = listen_port

self.target_host = target_host

self.target_port = target_port

self.client_sock = None

self.server_sock = None

def start(self):

"""Start the DAP monitor proxy."""

print(f"DAP Monitor starting on port {self.listen_port}")

print(f"Will forward to {self.target_host}:{self.target_port}")

print("Start MicroPython debugpy server first, then connect VS Code to port 5679")

# Create listening socket

listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)

listener.bind(('127.0.0.1', self.listen_port))

listener.listen(1)

print(f"Listening for VS Code connection on port {self.listen_port}...")

try:

# Wait for VS Code to connect

self.client_sock, client_addr = listener.accept()

print(f"VS Code connected from {client_addr}")

# Connect to MicroPython debugpy server

self.server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

self.server_sock.connect((self.target_host, self.target_port))

print(f"Connected to MicroPython debugpy at {self.target_host}:{self.target_port}")

# Start forwarding threads

threading.Thread(target=self.forward_client_to_server, daemon=True).start()

threading.Thread(target=self.forward_server_to_client, daemon=True).start()

print("DAP Monitor active - press Ctrl+C to stop")

while True:

time.sleep(1)

except KeyboardInterrupt:

print("\nStopping DAP Monitor...")

except Exception as e:

print(f"Error: {e}")

finally:

self.cleanup()

def forward_client_to_server(self):

"""Forward messages from VS Code client to MicroPython server."""

try:

while True:

data = self.receive_dap_message(self.client_sock, "VS Code")

if data is None:

break

self.send_raw_data(self.server_sock, data)

except Exception as e:

print(f"Client->Server forwarding error: {e}")

def forward_server_to_client(self):

"""Forward messages from MicroPython server to VS Code client."""

try:

while True:

data = self.receive_dap_message(self.server_sock, "MicroPython")

if data is None:

break

self.send_raw_data(self.client_sock, data)

except Exception as e:

print(f"Server->Client forwarding error: {e}")

def receive_dap_message(self, sock, source):

"""Receive and log a DAP message."""

try:

# Read headers

header = b""

while b"\r\n\r\n" not in header:

byte = sock.recv(1)

if not byte:

return None

header += byte

# Parse content length

header_str = header.decode('utf-8')

content_length = 0

for line in header_str.split('\r\n'):

if line.startswith('Content-Length:'):

content_length = int(line.split(':', 1)[1].strip())

break

if content_length == 0:

return None

# Read content

content = b""

while len(content) < content_length:

chunk = sock.recv(content_length - len(content))

if not chunk:

return None

content += chunk

# Log the message

try:

message = json.loads(content.decode('utf-8'))

msg_type = message.get('type', 'unknown')

command = message.get('command', message.get('event', 'unknown'))

seq = message.get('seq', 0)

print(f"\n[{source}] {msg_type.upper()}: {command} (seq={seq})")

if msg_type == 'request':

args = message.get('arguments', {})

if args:

print(f" Arguments: {json.dumps(args, indent=2)}")

elif msg_type == 'response':

success = message.get('success', False)

req_seq = message.get('request_seq', 0)

print(f" Success: {success}, Request Seq: {req_seq}")

body = message.get('body')

if body:

print(f" Body: {json.dumps(body, indent=2)}")

msg = message.get('message')

if msg:

print(f" Message: {msg}")

elif msg_type == 'event':

body = message.get('body', {})

if body:

print(f" Body: {json.dumps(body, indent=2)}")

except json.JSONDecodeError:

print(f"\n[{source}] Invalid JSON: {content}")

return header + content

except Exception as e:

print(f"Error receiving from {source}: {e}")

return None

def send_raw_data(self, sock, data):

"""Send raw data to socket."""

try:

sock.send(data)

except Exception as e:

print(f"Error sending data: {e}")

def cleanup(self):

"""Clean up sockets."""

if self.client_sock:

self.client_sock.close()

if self.server_sock:

self.server_sock.close()

if __name__ == "__main__":

monitor = DAPMonitor()

monitor.start()

__version__ = "0.1.0"

from .public_api import listen, wait_for_client, breakpoint, debug_this_thread

from .common.constants import DEFAULT_HOST, DEFAULT_PORT

__all__ = [

"listen",

"wait_for_client",

"breakpoint",

"debug_this_thread",

"DEFAULT_HOST",

"DEFAULT_PORT",

]