CircuitPythonOnSAMD.md

CircuitPython Quick-Start Guide for BlackWing SAMD51

This guide gets CircuitPython running on your custom SAMD51J20A board using PICkit5.

Prerequisites

• CircuitPython firmware for SAMD51 (pre-built)
• PICkit5 programmer
• Microchip Studio
• USB connection to your board (for REPL access)

Step 1: Download CircuitPython Firmware

1. Visit https://circuitpython.org/downloads
2. Search for SAMD51 board that matches your hardware
3. I used this one: https://circuitpython.org/board/sparkfun_samd51_micromod/
4. Download the .bin or .uf2 file
5. Save it to: c:\Projects_2025\BlackWing\Blinky\firmware.uf2

Step 2: Convert firmware to HEX format

1. Convert .uf2 to .bin
2. Use Python script called uf2_to_bin.py
3. Run it to create firmware.bin: PS Prompt> python uf2_to_bin.py
4. Convert .bin to .hex
5. PS Prompt> wsl arm-none-eabi-objcopy -I binary -O ihex firmware.bin firmware.hex

Output: firmware.hex

Step 3: Program via PICkit5

1. Open Microchip Studio
2. File → Open → Select firmware.hex
3. Tools → Device Programming
4. Tool: PICkit 5
5. Device: ATSAMD51J20A
6. ⚠️ CRITICAL: Set these parameters:
   • SWD Speed: 0.100 MHz
   • Program Speed: LOW
7. Click Program
8. Wait for "Programming complete"

Firmware Images

• blink.hex - Bare-metal C LED blink (development reference)
• firmware.hex - CircuitPython interpreter (production firmware)
  • Use this for board bring-up and CubeSat mission logic
  • Program via PICkit5 with 0.100 MHz SWD speed

To switch between them, just reprogram with different .hex file via Microchip Studio.

| No COM port enumeration | Custom board missing USB hardware | Verify USB D+/D- connected to SAMD51 PA24/PA25. Check schematic. | | USB not working | Wrong CircuitPython build for your board | CircuitPython needs custom board definition with USB pins configured | | Got firmware.hex from generic SAMD51 | Generic build doesn't know your custom USB pins | Need to compile CircuitPython with your board definition | Once programmed:

Step 4: Access CircuitPython REPL

1. Connect your board via USB to your PC

2. Open a serial terminal:

   • Option A (VS Code): Install "Serial Monitor" extension
   • Option B (PuTTY): Download from https://www.putty.org/
   • Option C (Thonny): Download from https://thonny.org/

3. Select COM port (check Device Manager)

4. Set baud rate: 115200

5. You should see:

   Adafruit CircuitPython X.X.X on SAMD51
   >>> 
   

Step 5: Test CircuitPython

Type in the REPL:

>>> print("Hello BlackWing!")
Hello BlackWing!
>>> import board
>>> print(dir(board))

Step 6: Create your first script

Create code.py on your board:

# code.py - LED Blink in CircuitPython
import board
import digitalio
import time

led = digitalio.DigitalInOut(board.PA22)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True
    time.sleep(0.5)
    led.value = False
    time.sleep(0.5)

Step 7: Upload script to board

Option A: Thonny IDE (easiest)

1. Download Thonny: https://thonny.org/
2. File → Open → Select code.py
3. Run → Save to device

Option B: mpremote (command-line)

pip install mpremote
mpremote cp code.py :

Option C: Manual drag-drop

1. Connect board via USB
2. If board shows as USB drive, drag code.py onto it
3. Board auto-runs code.py on boot

Customizing for your board

Custom pin names

Create board.py in CircuitPython root:

# board.py - Custom pin definitions
import board as board_module

# Map your custom pins
LED = board_module.PA22
SENSOR_SDA = board_module.PA17
SENSOR_SCL = board_module.PA16

Use in your code:

import board
led = digitalio.DigitalInOut(board.LED)

Available pins on SAMD51J20A

PA0, PA1, PA2, PA3, PA4, PA5, PA6, PA7
PA8, PA9, PA10, PA11, PA12, PA13, PA14, PA15
PA16, PA17, PA18, PA19, PA20, PA21, PA22, PA23
PA24, PA25, PA26, PA27, PA28, PA29, PA30, PA31

Troubleshooting

Issue	Cause	Solution
No REPL prompt	Wrong COM port	Check Device Manager for correct port
"Device not found" when programming	SWD speed too fast	Set to 0.100 MHz in Microchip Studio
Code doesn't run	File not named code.py	Rename to code.py
Import errors (no board module)	Wrong CircuitPython build	Download SAMD51-specific version
LED doesn't toggle	Wrong pin number	Verify PA22 or your custom pin

Next Steps

• Explore CircuitPython libraries: https://circuitpython.org/libraries
• Add sensors (I2C, SPI, analog)
• Integrate with PyCubed framework
• Build your CubeSat mission logic

Useful Links

• CircuitPython Docs: https://docs.circuitpython.org/
• SAMD51 Datasheet: https://ww1.microchip.com/downloads/en/DeviceDoc/60001507F.pdf
• Thonny IDE: https://thonny.org/
• mpremote: https://github.com/micropython/micropython/tree/master/tools/mpremote