XIAO MicroPython Development

Overview

Complete MicroPython development guide for SeeedStudio XIAO series. This skill works with the /xiao skill - use /xiao for pin definitions, /xiao-micropython for MicroPython-specific APIs and libraries.

Prerequisites

1. Pin Definitions: Read /xiao skill first for board-specific pin mappings
2. Thonny IDE: Recommended for MicroPython development
3. Firmware: MicroPython firmware flashed to board
4. Code Verification: Install mpy-cross for fast offline syntax checking (recommended)

Environment Setup

For first-time MicroPython environment setup, see setup/:

• Thonny IDE Installation: setup/thonny-ide.md
• Firmware Flashing: setup/esptool.md
• Code Verification: setup/mpy-cross.md (recommended for syntax validation)

Supported Boards

Board	Firmware Download	Getting Started
ESP32C3	micropython.org	getting-started/esp32c3.md
ESP32C5	ESP32 generic (C3 works)	getting-started/esp32c5.md
ESP32C6	micropython.org	getting-started/esp32c6.md
ESP32S3	micropython.org	getting-started/esp32s3.md
RP2040	micropython.org	getting-started/rp2040.md
RP2350	micropython.org	getting-started/rp2350.md
nRF52840	Community port	getting-started/nrf52840.md
nRF54L15	Seeed port	getting-started/nrf54l15.md

Note: SAMD21, MG24 MicroPython support is limited or requires community forks.

MicroPython Project Structure (CRITICAL)

MicroPython projects typically use these file patterns:

1. main.py - Main application script (auto-runs on boot)
2. boot.py - Initialization script (runs before main.py)
3. config.py - Configuration constants and settings
4. lib/ - Custom library modules

MicroPythonProject/
├── main.py           # Main application (auto-runs)
├── boot.py           # WiFi/initialization
├── config.py         # Pin definitions, settings
└── lib/
    ├── wifi.py       # WiFi connection module
    └── sensor.py     # Sensor driver module

Code Generation Workflow (CRITICAL)

When a user requests MicroPython code generation, you MUST:

Step 1: Create Project Files

• Use the Write tool to create the actual .py file(s)
• Follow the MicroPython project structure shown above
• Example: Create xiao_expansion_base_rtc.py or a full project with main.py, config.py, etc.

Step 2: Verify Syntax (If mpy-cross is Available)

• After creating the file, run mpy-cross to verify syntax
• This catches errors without needing a physical device
• Report syntax validation results to the user

Quick Start

1. Flash Firmware

pip install esptool
esptool.py --chip esp32c3 --port COM3 write_flash -z 4MB 0 firmware.bin

2. Connect with Thonny

1. Open Thonny IDE
2. Tools > Options > Interpreter > MicroPython (ESP32)
3. Select port and connect

3. First Script

from machine import Pin
import time

led = Pin(10, Pin.OUT)  # D10

while True:
    led.value(1)
    time.sleep(1)
    led.value(0)
    time.sleep(1)

Machine Module Quick Reference

Module	Reference	Usage
GPIO (machine.Pin)	api/gpio.md	Digital I/O, interrupts
PWM (machine.PWM)	api/pwm.md	Analog output, servo control
ADC (machine.ADC)	api/adc.md	Analog input reading
I2C (machine.I2C)	api/i2c.md	Sensor communication
SPI (machine.SPI)	api/spi.md	High-speed peripherals
UART (machine.UART)	api/uart.md	Serial communication

GPIO Example

from machine import Pin

led = Pin(10, Pin.OUT)
led.on()           # Turn on
led.off()          # Turn off
led.toggle()       # Toggle

button = Pin(6, Pin.IN, Pin.PULL_UP)
if button.value() == 0:
    print("Pressed")

I2C Example

from machine import I2C, Pin

i2c = I2C(0, scl=Pin(1), sda=Pin(0), freq=100000)
devices = i2c.scan()
print(f"I2C devices: {[hex(d) for d in devices]}")

Network Modules (ESP32)

Module	Reference	Usage
WiFi (network.WLAN)	api/wifi.md	Wireless connectivity
HTTP (urequests)	api/http.md	Web requests
MQTT (umqtt)	api/mqtt.md	IoT messaging
BLE (bluetooth)	api/ble.md	Bluetooth Low Energy
Socket	api/socket.md	TCP/UDP networking

WiFi Quick Start

import network

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect('SSID', 'password')

while not wlan.isconnected():
    time.sleep(1)

print(f'IP: {wlan.ifconfig()[0]}')

HTTP Request

import urequests

response = urequests.get('http://httpbin.org/get')
print(response.text)
response.close()

Common Libraries

Library	Reference	Usage
SSD1306	libraries/ssd1306.md	OLED displays
BME280	libraries/bme280.md	Weather sensors
NeoPixel	libraries/neopixel.md	RGB LEDs
DHT	libraries/dht.md	Temp/Humidity sensors
SD (sdcard)	libraries/sdcard.md	SD card storage

SSD1306 OLED

from machine import Pin, I2C
import ssd1306

i2c = I2C(0, sda=Pin(0), scl=Pin(1))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)
oled.fill(0)
oled.text("Hello XIAO!", 0, 0)
oled.show()

Code Verification

Quick syntax validation (no device needed):

# Install mpy-cross
pip install mpy-cross

# Verify syntax
mpy-cross script.py
# ✅ No error = valid, ❌ SyntaxError = fix code

Device testing (optional):

# Install mpremote
pip install mpremote

# Test on device
mpremote run script.py

For detailed verification workflow, see setup/mpy-cross.md and setup/mpremote.md.

Board-Specific APIs

ESP32 Series (C3/C5/C6/S3)

• Deep Sleep: api/esp32-sleep.md
• BLE: api/esp32-ble.md
• Camera (S3 Sense): api/esp32s3-camera.md

nRF52 Series (nRF52840)

• Sleep: api/nrf-sleep.md
• BLE: api/nrf-ble.md

RP Series (RP2040/RP2350)

• Sleep: api/rp-sleep.md
• PIO: api/rp2040-pio.md

Expansion Boards

XIAO expansion boards add peripherals. For hardware specs, see /xiao/references/expansion_boards/.

Expansion Board	Key Features	Reference
Expansion Base	OLED, RTC, SD card, buzzer	expansion-boards/expansion-base.md
Round Display	1.28" touchscreen	expansion-boards/round-display.md
Grove Shield	8 Grove connectors	expansion-boards/grove-shield.md
CAN Bus	MCP2515 controller	expansion-boards/can-bus.md
GPS/GNSS	L76K GNSS module	expansion-boards/gps-gnss.md

Expansion Board Examples

Expansion Base (OLED + RTC)

from machine import Pin, I2C
import ssd1306
import time

# OLED (I2C address 0x3C)
i2c = I2C(0, sda=Pin(0), scl=Pin(1))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)

oled.fill(0)
oled.text("XIAO Base", 0, 0)
oled.show()

# RTC (DS3231, I2C address 0x68)
def set_rtc(datetime_tuple):
    i2c.writeto(0x68, bytes([0x00] + list(datetime_tuple)))

def get_rtc():
    i2c.writeto(0x68, b'\x00')
    data = i2c.readfrom(0x68, 7)
    return (data[0], data[1], data[2])

# SD Card (SPI)
import sdcard, machine
sd = sdcard.SDCard(machine.SPI(0), machine.Pin(4))
vfs = os.VfsFat(sd)
os.mount(vfs, '/sd')

with open('/sd/data.txt', 'w') as f:
    f.write('Hello from XIAO!')

Code Patterns

Main Loop with Exception Handler

import time

def main():
    while True:
        try:
            # Your code here
            time.sleep(1)
        except Exception as e:
            print(f"Error: {e}")
            time.sleep(5)

if __name__ == "__main__":
    main()

Non-blocking Delay

import time

last_check = 0
interval = 5000  # 5 seconds

while True:
    current = time.ticks_ms()
    if time.ticks_diff(current, last_check) >= interval:
        last_check = current
        # Do periodic task

    # Other code here

Troubleshooting

Issue	Solution
OSError: [Errno 5]	Check I2C/SPI pins with /xiao skill
ImportError	Verify module exists in firmware
WiFi won't connect	Ensure 2.4GHz network (ESP32 only)
Board won't upload	ESP32: Hold BOOT; RP2040: Hold BOOTSEL

Resources

setup/

• setup/thonny-ide.md - Thonny IDE installation
• setup/esptool.md - Firmware flashing
• setup/mpy-cross.md - Offline syntax verification
• setup/mpremote.md - Device testing and deployment

getting-started/

Board-specific setup instructions.

api/

MicroPython module documentation (GPIO, I2C, WiFi, BLE, sleep, etc.)

libraries/

Common libraries (SSD1306, BME280, NeoPixel, etc.)

examples/

Complete project examples:

• examples/weather-station.md - BME280 weather station with MQTT
• examples/ble-peripheral.md - BLE environmental sensor
• examples/mqtt-sensor.md - MQTT temperature/humidity sensor

Related Skills

• /xiao - Core board reference with pin definitions
• /xiao-arduino - Arduino development
• /xiao-esphome - ESPHome configuration