micropython-repl

name	micropython-repl
description	MicroPython REPL usage, package management, module inspection, and interactive debugging for Universe 2025 (Tufty) Badge. Use when installing MicroPython packages, testing code interactively, checking installed modules, or using the REPL for development.

MicroPython REPL and Package Management

Master the MicroPython REPL (Read-Eval-Print Loop) for interactive development, package management, and quick testing on the Universe 2025 (Tufty) Badge.

Connecting to REPL

Using screen (macOS/Linux)

# Find the device
ls /dev/tty.usb*

# Connect (115200 baud)
screen /dev/tty.usbmodem* 115200

# Exit screen: Ctrl+A then K, then Y to confirm

Using mpremote

# Install mpremote
pip install mpremote

# Connect to REPL
mpremote connect /dev/tty.usbmodem*

# Or auto-detect
mpremote

Using Thonny IDE

1. Open Thonny
2. Tools → Options → Interpreter
3. Select "MicroPython (RP2040)"
4. Choose correct port
5. Shell window shows REPL

REPL Basics

Special Commands

# Ctrl+C - Interrupt running program
# Ctrl+D - Soft reboot
# Ctrl+E - Enter paste mode (for multi-line code)
# Ctrl+B - Exit paste mode and execute

# Help system
help()              # General help
help(modules)       # List all modules
help(badgeware)     # Help on specific module

# Quick info
import sys
sys.implementation  # MicroPython version
sys.platform        # Platform info

Interactive Testing

# Test code immediately
>>> from badgeware import screen, display, brushes
>>> screen.brush = brushes.color(255, 255, 255)
>>> screen.text("Test", 10, 10, 2)
>>> display.update()

# Test calculations
>>> temp = 23.5
>>> temp_f = temp * 9/5 + 32
>>> print(f"{temp}C = {temp_f}F")

# Test GPIO
>>> from machine import Pin
>>> led = Pin(25, Pin.OUT)
>>> led.toggle()  # Toggle LED immediately

Paste Mode for Multi-line Code

# Enter paste mode: Ctrl+E
# Paste your code:
def calculate_distance(x1, y1, x2, y2):
    import math
    dx = x2 - x1
    dy = y2 - y1
    return math.sqrt(dx*dx + dy*dy)

print(calculate_distance(0, 0, 3, 4))
# Exit paste mode: Ctrl+D

Package Management

Using mip (MicroPython Package Installer)

# Install package from micropython-lib
import mip
mip.install("urequests")        # HTTP client
mip.install("logging")           # Logging module
mip.install("umqtt.simple")      # MQTT client

# Install from GitHub
mip.install("github:org/repo/package.py")

# Install to specific location
mip.install("urequests", target="/lib")

Using upip (older method)

# Connect to WiFi first
import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect('SSID', 'password')

# Wait for connection
while not wlan.isconnected():
    pass

# Install package
import upip
upip.install("micropython-logging")
upip.install("picoweb")

Manual Package Installation

# From your computer, copy files to badge
mpremote cp mymodule.py :/lib/mymodule.py

# Or using ampy
ampy --port /dev/tty.usbmodem* put mymodule.py /lib/mymodule.py

# Then use in REPL
>>> import mymodule

Module Inspection

List Available Modules

# List all built-in and installed modules
help('modules')

# Check if module exists
import sys
'badgeware' in sys.modules  # False until imported

import badgeware
'badgeware' in sys.modules  # True after import

Inspect Module Contents

# See what's in a module
import badgeware
dir(badgeware)  # List all attributes

# Check specific attributes
hasattr(badgeware, 'screen')  # True
hasattr(badgeware, 'brushes')  # True

# Get function signature
help(badgeware.screen)

# Explore submodules
from badgeware import shapes
dir(shapes)  # See all shape functions

# View source (if available)
import inspect
inspect.getsource(mymodule.myfunction)  # May not work on compiled modules

Check Module Location

# Find where module is located
import badgeware
badgeware.__file__  # Shows file path

# List files in system directory
import os
os.listdir('/system')
os.listdir('/system/apps')  # MonaOS apps

Interactive Debugging

Quick Variable Inspection

# Run code and inspect
>>> x = [1, 2, 3, 4, 5]
>>> len(x)
5
>>> type(x)
<class 'list'>
>>> sum(x)
15

# Object inspection
>>> import badgeware
>>> type(badgeware.screen)
<class 'Screen'>
>>> dir(badgeware.screen)  # See all methods
>>> dir(badgeware.brushes)  # See brush functions
>>> dir(badgeware.shapes)  # See shape functions

Print Debugging

# Test function with prints
def process_data(data):
    print(f"Input: {data}")
    result = data * 2
    print(f"Result: {result}")
    return result

>>> process_data(5)
Input: 5
Result: 10
10

Exception Handling

# Test error handling
>>> try:
...     1 / 0
... except ZeroDivisionError as e:
...     print(f"Error: {e}")
Error: division by zero

# Get full traceback
import sys
try:
    buggy_function()
except Exception as e:
    sys.print_exception(e)

Memory Debugging

# Check memory usage
import gc
gc.collect()  # Run garbage collection
gc.mem_free()  # Free memory in bytes
gc.mem_alloc()  # Allocated memory

# Monitor memory during operation
before = gc.mem_free()
# ... do something
after = gc.mem_free()
print(f"Memory used: {before - after} bytes")

Useful REPL Helpers

Create a helpers.py file

# helpers.py - Load in REPL for common tasks
import gc
import sys
import os
from machine import Pin, freq

def info():
    """Display system information"""
    print(f"Platform: {sys.platform}")
    print(f"Version: {sys.version}")
    print(f"CPU Frequency: {freq()} Hz")
    print(f"Free Memory: {gc.mem_free()} bytes")

def ls(path='/'):
    """List files in directory"""
    try:
        files = os.listdir(path)
        for f in files:
            print(f)
    except:
        print(f"Error listing {path}")

def cat(filename):
    """Display file contents"""
    try:
        with open(filename, 'r') as f:
            print(f.read())
    except Exception as e:
        print(f"Error: {e}")

def rm(filename):
    """Remove file"""
    try:
        os.remove(filename)
        print(f"Removed {filename}")
    except Exception as e:
        print(f"Error: {e}")

def blink(pin=25, times=3):
    """Blink LED for testing"""
    import time
    led = Pin(pin, Pin.OUT)
    for i in range(times):
        led.toggle()
        time.sleep(0.5)
    led.value(0)

# Load in REPL with:
# >>> from helpers import *
# >>> info()

Auto-run at REPL start

Create boot.py to run code on startup:

# boot.py - Runs on every boot
import gc
gc.collect()

# Optional: Auto-import common modules
# from badgeware import screen, display, brushes, shapes
# import time

print("Universe 2025 Badge Ready!")
print(f"Free memory: {gc.mem_free()} bytes")

Quick Testing Workflows

Test Hardware Function

# Test I2C scan
from machine import I2C, Pin
i2c = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)
devices = i2c.scan()
print(f"Found devices: {[hex(d) for d in devices]}")

# Test display
from badgeware import screen, display, brushes
screen.brush = brushes.color(0, 0, 0)
screen.clear()
screen.brush = brushes.color(255, 255, 255)
screen.text("REPL Test", 10, 10, 2)
display.update()

Test Network Connection

import network
import time

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
print("Connecting to WiFi...")
wlan.connect('YOUR_SSID', 'YOUR_PASSWORD')

timeout = 10
while not wlan.isconnected() and timeout > 0:
    print(".", end="")
    time.sleep(1)
    timeout -= 1

if wlan.isconnected():
    print("\nConnected!")
    print(f"IP: {wlan.ifconfig()[0]}")
else:
    print("\nConnection failed")

Test API Call

import urequests
import json

response = urequests.get('https://api.github.com/zen')
print(response.text)
response.close()

# JSON API
response = urequests.get('https://api.example.com/data')
data = response.json()
print(data)
response.close()

File System Operations

List and Navigate Files

import os

# Current directory
os.getcwd()

# List files
os.listdir()
os.listdir('/lib')

# File info
os.stat('main.py')  # Returns (mode, ino, dev, nlink, uid, gid, size, atime, mtime, ctime)

# Check if file exists
try:
    os.stat('main.py')
    print("File exists")
except:
    print("File not found")

Read/Write Files

# Write file
with open('test.txt', 'w') as f:
    f.write('Hello from REPL!\n')

# Read file
with open('test.txt', 'r') as f:
    content = f.read()
    print(content)

# Append to file
with open('log.txt', 'a') as f:
    f.write(f'Log entry: {time.time()}\n')

Remove Files

import os

# Remove file
os.remove('test.txt')

# Remove directory (must be empty)
os.rmdir('mydir')

Checking Installed Packages

Verify Package Installation

# Method 1: Try to import
try:
    import urequests
    print("urequests is installed")
    print(f"Location: {urequests.__file__}")
except ImportError:
    print("urequests not installed")

# Method 2: Check file system
import os
lib_files = os.listdir('/lib')
print("Installed in /lib:")
for f in lib_files:
    print(f"  {f}")

# Method 3: Check sys.path
import sys
print("Module search paths:")
for path in sys.path:
    print(f"  {path}")

Package Version Info

# Some packages have __version__
import urequests
if hasattr(urequests, '__version__'):
    print(f"urequests version: {urequests.__version__}")

# Check MicroPython version
import sys
print(sys.version)
print(sys.implementation)

REPL Tips and Tricks

History Navigation

• Up/Down arrows: Navigate command history
• Tab: Auto-completion (limited support)

Copy Output from REPL

# Run command and capture output
>>> result = []
>>> for i in range(10):
...     result.append(i * 2)
>>> print(result)
[0, 2, 4, 6, 8, 10, 12, 14, 16, 18]

# Copy from terminal window

Run Script from REPL

# Import and run
import myapp
myapp.main()

# Or reload after changes
import sys
if 'myapp' in sys.modules:
    del sys.modules['myapp']
import myapp

Timing Code

import time

start = time.ticks_ms()
# ... your code here
for i in range(1000):
    x = i * 2
end = time.ticks_ms()

print(f"Execution time: {time.ticks_diff(end, start)}ms")

Common REPL Issues

REPL not responding: Press Ctrl+C to interrupt, or Ctrl+D to soft reset

Can't import module: Check sys.path, verify file is in /lib or root directory

Out of memory: Run gc.collect(), reduce variable usage, delete large objects

Module changes not reflected: Delete from sys.modules and re-import

Connection lost: Reconnect with screen or mpremote, check USB cable

Using mpremote for Quick Operations

# Execute Python code remotely
mpremote exec "import machine; print(machine.freq())"

# Run local script on device
mpremote run test.py

# Copy file to device
mpremote cp test.py :main.py

# Copy file from device
mpremote cp :main.py local.py

# Mount local directory on device
mpremote mount .

# Filesystem operations
mpremote ls
mpremote mkdir /data
mpremote rm test.txt

# Chain commands
mpremote connect /dev/tty.usbmodem* cp main.py :main.py exec "import main"

REPL Best Practices

1. Save work frequently - REPL state is lost on reboot
2. Use paste mode for multi-line code
3. Run gc.collect() before memory-intensive operations
4. Test incrementally - Build up complex code piece by piece
5. Create helper functions in a dedicated module
6. Use print() liberally for debugging
7. Soft reset (Ctrl+D) to clear state between tests
8. Keep REPL sessions short - Move working code to files

Integration with Development Workflow

1. Prototype in REPL - Test ideas interactively
2. Save to file - Once code works, save to .py file
3. Test from file - Import and run from REPL
4. Iterate - Make changes, reload, test
5. Deploy - Upload final version to badge

The REPL is your best friend for rapid experimentation and debugging on the Badger 2350!