Základy v CircuitPythonu

Co je CircuitPython #

CircuitPython je verze Pythonu od firmy Adafruit, navržená přímo pro mikrokontroléry. Píšete v ní normální Python, ale váš kód běží přímo v Picopadu. Po nahrání firmwaru se Picopad chová jako USB flash disk s názvem CIRCUITPY – stačí na něj přetáhnout soubor code.py, ten se automaticky spustí a po každém uložení Picopad sám restartuje. Žádný „upload" knoflík, žádné zvláštní nástroje.

Picopad podporuje tři způsoby programování. Tabulka pomůže vybrat:

V tomhle tutoriálu jdeme cestou CircuitPythonu. Hlavní výhoda: vysokoúrovňové knihovny (displayio, adafruit_display_text, simpleio, keypad) a editace souborů přímo přes USB disk – žádné nahrávání tlačítkem v editoru. Ideální pro začátky.

Instalace firmware #

Než začnete programovat, je potřeba do Picopadu nahrát CircuitPython firmware. Je to jednorázová operace – nahrané jednou, drží se v zařízení a přepisuje se jen tehdy, když chcete jiný jazyk.

Postup je v samostatném návodu: Jak nainstalovat CircuitPython →

První program – Hello Picopad #

Když máte CircuitPython nahraný, je čas něco napsat. CircuitPython vám usnadňuje práci tak, že se Picopad chová jako USB flash disk s názvem CIRCUITPY. Stačí editovat soubor code.py – po jeho uložení Picopad sám restartuje a spustí kód.

1) Najděte CIRCUITPY disk

Připojte Picopad přes USB a zapněte ho. Mezi disky v počítači se objeví nová mechanika CIRCUITPY. Otevřete ji – uvidíte několik souborů, hlavně code.py (váš program) a složku lib (pro knihovny).

2) První řádek (přes REPL)

Spolu s USB diskem se otevře i sériový port. Pomocí jakéhokoliv terminálu (např. v Thonny: View → Shell, nebo screen /dev/cu.usbmodem... 115200 na macOS) se připojíte do REPLu – interaktivní konzole CircuitPythonu. Stiskněte Ctrl+C, abyste přerušili běžící code.py, a uvidíte >>>. Napište:

print("Ahoj, Picopade!")

Po Enteru se ihned zobrazí odpověď:

Ahoj, Picopade!

3) Blikání LEDkou (soubor code.py)

V libovolném editoru (Thonny, VS Code, Notepad...) otevřete soubor code.py přímo na CIRCUITPY disku a přepište ho na:

import board
import digitalio
import time

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

while True:
    led.value = False  # rozsvítí (LED je aktivní v low)
    time.sleep(0.5)
    led.value = True   # zhasne
    time.sleep(0.5)

Soubor uložte. Picopad sám restartuje a žlutá uživatelská LED na horní hraně začne blikat – jednou za sekundu.

4) Pin se jmenuje, neukazuje se na něj číslem

Všimněte si, že místo „GPIO 22" píšete board.LED. To je velký rozdíl oproti MicroPythonu nebo C – CircuitPython má pro každou součástku Picopadu pojmenovaný pin. board.SW_A je tlačítko A, board.AUDIO je bzučák, board.DISPLAY už je rovnou inicializovaný displej. V další kapitole najdete kompletní mapu.

5) Co dál

Soubor code.py se spustí pokaždé, když Picopad zapnete. Můžete USB odpojit – LEDka bude blikat dál. Tím končí „Hello world" část. V dalších kapitolách budeme stavět na tomto základu: ovládání displeje, čtení tlačítek, hraní zvuků a další.

Anatomie Picopadu #

Než se vrhneme na jednotlivé HW prvky, podívejme se, co je kde. Diagram níže je vyrenderovaný přímo z výrobního schématu Picopadu, takže pozice tlačítek a LEDek jsou přesně tam, kde je najdete na své konzoli.

Přední strana Picopadu – D-pad, tlačítka A/B/X/Y a stavové LEDky

Mapa pojmenovaných pinů

CircuitPython má pro každý hardware Picopadu pojmenovaný atribut v modulu board. V kódu se na něj odkazujete přímo – nemusíte si pamatovat GPIO čísla.

Externí konektor J2

Na boku Picopadu je 12pinový konektor, kterým se dají připojovat senzory a moduly (např. teplotní čidlo, ultrazvukový dálkoměr, fotorezistor). Vyvedené piny:

• Napájení: 3.3 V, GND, VBAT (přímo z baterie), ADC_VREF, AGND
• Digitální / komunikace: board.D1, board.D2/board.RX/board.SCL, board.D3/board.TX/board.SDA
• Analogové vstupy: board.A0 (= D0), board.A1 (= D4), board.A2 (= D5)

Displej #

Picopad má 2.0" IPS displej s rozlišením 320×240 pixelů. CircuitPython ho má předinicializovaný v board.DISPLAY, takže se s ním pracuje skoro tak snadno jako s plátnem v Pythonu na PC. Pro vykreslování používáme knihovnu displayio (vestavěná) a pro text adafruit_display_text (musíte si stáhnout).

Stažení knihoven – CircuitPython Library Bundle

Mnoho příkladů potřebuje knihovny z Adafruit bundle. Postup:

1. Otevřete circuitpython.org/libraries a stáhněte ZIP odpovídající verzi vašeho CircuitPythonu (např. 9.x bundle).
2. Rozbalte ZIP. Uvnitř je složka lib s desítkami knihoven (přípona .mpy) a examples.
3. Z bundle lib přetáhněte složku adafruit_display_text do CIRCUITPY/lib/ na Picopadu. Hotovo.

První text na displeji

import board
import terminalio
from adafruit_display_text import label

display = board.DISPLAY
text_label = label.Label(terminalio.FONT, text="Ahoj, Picopade!", color=0xFFFFFF, scale=2)
text_label.x = 70
text_label.y = 110

display.root_group = text_label

while True:
    pass

Co se tu děje:

• board.DISPLAY – displej je už spuštěný, jen si ho vezmete.
• terminalio.FONT – vestavěný 6×12 font, není potřeba nic stahovat.
• label.Label – textový sprajt. Barva je RGB v hexa (0xFFFFFF = bílá), scale=2 ho zvětší dvakrát.
• display.root_group – co je nastavené tady, vidíte na obrazovce. Můžete vyměnit kdykoliv za jinou skupinu (Group), tím přepnete „obrazovku".
• while True: pass – aby program neskončil. Když skončí, CircuitPython zobrazí konzoli.

Skupiny, sprajty a obrázky

Reálná aplikace má víc prvků – pozadí, postavičku, text. Spojí se do displayio.Group, která tvoří „scénu". Tady je příklad s barevným pozadím a textem:

import board
import displayio
import terminalio
from adafruit_display_text import label

display = board.DISPLAY

# Skupina = scéna
group = displayio.Group()

# Barevné pozadí: 1px×1px bitmapa roztažená přes celý displej
bg_bitmap = displayio.Bitmap(1, 1, 1)
bg_palette = displayio.Palette(1)
bg_palette[0] = 0x002244  # tmavě modrá
bg_tile = displayio.TileGrid(bg_bitmap, pixel_shader=bg_palette,
                             width=display.width, height=display.height,
                             tile_width=1, tile_height=1)
group.append(bg_tile)

# Text
title = label.Label(terminalio.FONT, text="Picopad rocks", color=0xFFFFFF, scale=3)
title.x = 30
title.y = 100
group.append(title)

display.root_group = group

while True:
    pass

Pro načtení BMP/PNG obrázku slouží adafruit_imageload (z bundle):

import adafruit_imageload
import displayio

bitmap, palette = adafruit_imageload.load("/picture.bmp")
sprite = displayio.TileGrid(bitmap, pixel_shader=palette, x=20, y=20)

Tlačítka #

Picopad má osm tlačítek: D-pad (↑ ↓ ← →) a herní cluster A/B/X/Y. CircuitPython je číst třemi způsoby – od jednoduchého k pokročilému.

1) Nejjednodušší: digitalio

import board
from digitalio import DigitalInOut, Pull
import time

btn_a = DigitalInOut(board.SW_A)
btn_a.pull = Pull.UP

while True:
    if not btn_a.value:   # sepnuto = pin je v 0, .value je False
        print("A!")
    time.sleep(0.05)

Funkční, ale když uživatel drží tlačítko, vypíše „A!" stokrát za sekundu. A mechanická tlačítka „odskakují" (debouncing) – jedno stisknutí registruje jako několik.

2) S debouncerem (knihovna adafruit_debouncer)

Stáhněte z bundle adafruit_debouncer.mpy do /lib. Pak:

import board
from digitalio import DigitalInOut, Pull
from adafruit_debouncer import Debouncer
import time

pin = DigitalInOut(board.SW_A)
pin.pull = Pull.UP
btn_a = Debouncer(pin)

while True:
    btn_a.update()
    if btn_a.fell:        # právě teď stisknuto (pin spadl z 1 na 0)
        print("A stisknuto")
    if btn_a.rose:        # právě teď puštěno
        print("A puštěno")
    time.sleep(0.01)

3) Nejlepší: keypad.Keys (vestavěný v CircuitPythonu)

Modul keypad skenuje tlačítka na pozadí a zařazuje stisky do fronty – nikdy je nezmeškáte, ani když máte v hlavní smyčce delší sleep.

import board
import keypad

KEY_A, KEY_B, KEY_X, KEY_Y, KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT = range(8)

keys = keypad.Keys(
    (board.SW_A, board.SW_B, board.SW_X, board.SW_Y,
     board.SW_UP, board.SW_DOWN, board.SW_LEFT, board.SW_RIGHT),
    value_when_pressed=False,  # tlačítka jsou aktivní v LOW
    pull=True,
)

while True:
    event = keys.events.get()
    if event:
        if event.pressed:
            print("Stisknuto tlačítko č.", event.key_number)
        if event.released:
            print("Puštěno tlačítko č.", event.key_number)

Pro běžné herní ovládání používejte keypad – nejméně kódu, nejsolidnější výsledky.

Uživatelská LED #

Žlutá LED nad displejem (popisek USR) je volně k použití pro vaše programy. Připojuje se přes board.LED.

On/off + blikání

import board
import digitalio
import time

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

# Bliknutí 5×
for _ in range(5):
    led.value = False  # rozsvítí (aktivní v LOW)
    time.sleep(0.2)
    led.value = True   # zhasne
    time.sleep(0.2)

Stmívání přes PWM

Pro plynulé stmívání nestačí jen on/off – potřebujete PWM (pulzně šířková modulace). V CircuitPythonu máte modul pwmio:

import board
import pwmio
import time

led = pwmio.PWMOut(board.LED, frequency=1000, duty_cycle=0)

# Plynulé rozjasnění a zatemnění (LED je aktivní v LOW, takže duty_cycle "obrátíme")
while True:
    for d in range(0, 65536, 1024):
        led.duty_cycle = 65535 - d  # 65535 = zhasnuto, 0 = plně rozsvíceno
        time.sleep(0.01)
    for d in range(65535, -1, -1024):
        led.duty_cycle = 65535 - d
        time.sleep(0.01)

duty_cycle jde od 0 do 65535. Protože je LED aktivní v LOW, vyšší PWM hodnota = LED tmavší. Když to zmate, počítejte „svit" jako 65535 - duty_cycle.

microSD karta #

Picopad má slot na microSD pod displejem. Hodí se pro ukládání herních saves, log souborů, obrázků nebo zvuků, které by se nevešly do flash paměti čipu.

CircuitPython má SD kartu integrovanou – po namontování se chová jako normální disk a píšete na ni přes open(...).

import board
import busio
import digitalio
import sdcardio
import storage

# SPI sběrnice pro SD
spi = busio.SPI(clock=board.SD_SCK, MOSI=board.SD_MOSI, MISO=board.SD_MISO)
cs = digitalio.DigitalInOut(board.SD_CS)

# SDCard objekt + namontování pod /sd
sd = sdcardio.SDCard(spi, cs)
vfs = storage.VfsFat(sd)
storage.mount(vfs, "/sd")

# Zápis – jako normální soubor
with open("/sd/log.txt", "a") as f:
    f.write("Ahoj z Picopadu!\n")

# Čtení
with open("/sd/log.txt") as f:
    print(f.read())

Bzučák a zvuk #

V Picopadu je miniaturní reproduktor (popisek SPEAKER), který hraje přes pin board.AUDIO. Pro pípnutí stačí jeden řádek; pro hudbu jdete dál pomocí PWM, případně syntézy.

Jednoduché pípnutí (simpleio)

Stáhněte simpleio.mpy z bundle do /lib:

import board
import simpleio

# Pípnutí na 880 Hz po dobu 0.2 s
simpleio.tone(board.AUDIO, 880, 0.2)

Krátká melodie

import board
import simpleio
import time

# Frekvence not v Hz
notes = [
    ("C5", 523),
    ("E5", 659),
    ("G5", 784),
    ("C6", 1047),
]

for name, freq in notes:
    print(name)
    simpleio.tone(board.AUDIO, freq, 0.3)
    time.sleep(0.05)

Pokročilé: synthio (syntéza)

Pro skutečně herní zvukové efekty se hodí synthio – syntezátor zabudovaný v CircuitPythonu, dokáže hrát víc not najednou, FM modulace, filtry. Inspirace: ukázka monosynth v repu Picopadu.

Měření baterie #

Picopad běží z Li-ion baterie (3.7 V nominálně). Aby vaše hra zobrazila „baterka skoro vybitá", potřebujete přečíst její napětí přes analogio.AnalogIn na pinu board.BAT_SENSE.

import board
import analogio
import time

vbat_pin = analogio.AnalogIn(board.BAT_SENSE)

# Reference je 3.3 V, ADC dává 0..65535. Napětí na pinu:
def battery_voltage():
    raw = vbat_pin.value          # 0..65535
    voltage_at_pin = (raw / 65535) * 3.3
    # Na BAT_SENSE jde napětí baterie přes dělič 1:2, takže ho zdvojnásobíme
    return voltage_at_pin * 2

while True:
    v = battery_voltage()
    print("Baterie: {:.2f} V".format(v))
    time.sleep(2)

Kalibrace na procenta (orientačně):

Externí konektor #

Z boku Picopadu vede 12pinový konektor J2, na kterém najdete digitální piny D0..D5, analogové vstupy A0..A2, I2C, UART a napájení. Můžete přes něj připojit teplotní čidla, OLED displeje, rotační enkodéry, dálkoměry...

Příklad: fotorezistor (jas okolního světla)

Zapojte fotorezistor mezi 3.3 V a pin D0 (= A0), a 10 kΩ rezistor z D0 do GND – klasický napěťový dělič.

import board
import analogio
import time

light = analogio.AnalogIn(board.A0)

while True:
    raw = light.value
    voltage = (raw / 65535) * 3.3
    print("Jas (raw): {}, napětí: {:.2f} V".format(raw, voltage))
    time.sleep(0.5)

Když přiložíte ruku na fotorezistor, číslo klesne; když na něj posvítíte mobilem, vyletí. Takhle si zobrazíte hodnotu třeba na displeji.

Příklad: I2C zařízení (např. teplotní senzor BME280)

Většina I2C senzorů s Adafruit knihovnami funguje out-of-the-box:

import board
import time
from adafruit_bme280 import basic as adafruit_bme280

i2c = board.I2C()                     # SDA = board.SDA, SCL = board.SCL
sensor = adafruit_bme280.Adafruit_BME280_I2C(i2c)

while True:
    print("Teplota: {:.1f} C, vlhkost: {:.0f} %, tlak: {:.0f} hPa"
          .format(sensor.temperature, sensor.relative_humidity, sensor.pressure))
    time.sleep(2)

Knihovna adafruit_bme280 je v bundle. Stejně se připojí SCD4x (CO₂), SSD1306 (OLED), atd.

WiFi #

Picopad Wifi i Picopad Pro mají modul Raspberry Pi Pico W, takže WiFi a Bluetooth máte v ceně. CircuitPython API je naprosto čisté – modul wifi s objektem wifi.radio.

Uložení přihlašovacích údajů (settings.toml)

Aby váš kód neměl heslo přímo v code.py, CircuitPython čte tajné věci z settings.toml v kořeni CIRCUITPY disku:

CIRCUITPY_WIFI_SSID = "muje_wifi"
CIRCUITPY_WIFI_PASSWORD = "tajne_heslo"

Připojení a ping

import os
import wifi
import socketpool
import ipaddress
import time

print("Připojuji se k WiFi...")
wifi.radio.connect(os.getenv("CIRCUITPY_WIFI_SSID"),
                   os.getenv("CIRCUITPY_WIFI_PASSWORD"))
print("Připojeno, IP:", wifi.radio.ipv4_address)

pool = socketpool.SocketPool(wifi.radio)
google = ipaddress.ip_address("8.8.4.4")

while True:
    ms = wifi.radio.ping(google)
    if ms is None:
        print("Žádná odpověď")
    else:
        print("Ping: {:.1f} ms".format(ms * 1000))
    time.sleep(15)

Sken okolních sítí

import wifi

print("SSID                          RSSI  CHN")
for net in wifi.radio.start_scanning_networks():
    print("{:30s} {:5d}  {:3d}".format(net.ssid, net.rssi, net.channel))
wifi.radio.stop_scanning_networks()

HTTP požadavek

Stáhněte z bundle adafruit_requests.mpy do /lib:

import os
import wifi
import socketpool
import ssl
import adafruit_requests

wifi.radio.connect(os.getenv("CIRCUITPY_WIFI_SSID"),
                   os.getenv("CIRCUITPY_WIFI_PASSWORD"))

pool = socketpool.SocketPool(wifi.radio)
session = adafruit_requests.Session(pool, ssl.create_default_context())

resp = session.get("https://api.github.com/repos/Pajenicko/Picopad")
data = resp.json()
print("Hvězdičky:", data["stargazers_count"])

Mini projekt – „Reflex" #

Spojíme to dohromady. Hra otestuje váš reflex: po náhodné prodlevě LED bliknete, vy musíte rychle zmáčknout A. Změřený čas se zobrazí na displeji.

import board
import digitalio
import keypad
import simpleio
import displayio
import terminalio
import random
import time
from adafruit_display_text import label

# LED
led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
led.value = True   # zhasnuto

# Tlačítko A
keys = keypad.Keys((board.SW_A,), value_when_pressed=False, pull=True)

# Displej
display = board.DISPLAY
group = displayio.Group()

title = label.Label(terminalio.FONT, text="REFLEX TEST", color=0xFFFFFF, scale=3)
title.x = 50
title.y = 60
group.append(title)

info = label.Label(terminalio.FONT, text="Stiskni A pro start", color=0xAAAAAA, scale=2)
info.x = 35
info.y = 130
group.append(info)

result = label.Label(terminalio.FONT, text="", color=0x44FF44, scale=3)
result.x = 70
result.y = 200
group.append(result)

display.root_group = group


def wait_for_a():
    keys.events.clear()
    while True:
        ev = keys.events.get()
        if ev and ev.pressed:
            return


while True:
    info.text = "Stiskni A pro start"
    result.text = ""
    wait_for_a()

    info.text = "Cekej..."
    result.text = ""
    time.sleep(random.uniform(1.5, 4.0))

    led.value = False        # bliknout
    info.text = "TED!"
    start = time.monotonic()

    keys.events.clear()
    while True:
        ev = keys.events.get()
        if ev and ev.pressed:
            elapsed_ms = int((time.monotonic() - start) * 1000)
            led.value = True
            simpleio.tone(board.AUDIO, 880, 0.1)
            result.text = "{} ms".format(elapsed_ms)
            info.text = "A = znovu"
            break

Vyzkoušejte. Kolik milisekund vám to dělá? Lidský průměr je kolem 250 ms.

Kam dál #

Tutoriál pokryl základy. Pokud chcete jít hlouběji:

Hotové projekty v repu

• Pajenicko/Picopad – CircuitPython – hello_world, hry (Snake, DinoRun), senzory, síť, makro klávesnice, monosyntezátor, slideshow, budík...
• network/ – webserver (polling/SSE/WebSocket), Golemio MHD, Telegram bot, NTP hodiny, Teletext, ŽivýObraz.eu.
• sensors/ – I2C senzory (SCD4x, BME280), 1-Wire (DS18B20), ultrazvuk (HC-SR04), fotorezistor.

Oficiální dokumentace

• docs.circuitpython.org – kompletní reference modulů (board, displayio, wifi, synthio...).
• Welcome to CircuitPython – pohodlný úvod od Adafruitu.
• circuitpython.org/libraries – balíčky knihoven, vždy stáhněte verzi pasující na váš firmware.
• CircuitPython Essentials – vzorové úlohy pro digitální IO, ADC, PWM, IR, audio, displej...

Komunita Picopadu

Inspirace, co lidé vyrobili – emulátor GameBoy, port DOOMu, MakeCode Arcade patcher, vlastní 3D-tištěné krabičky, vylepšené čepičky tlačítek – najdete na stránce Komunita.

Zpětná vazba

Tenhle tutoriál žije díky vám. Pokud jste narazili na chybu, máte nápad na další kapitolu, nebo jste si postavili něco bezvadného a chcete to ukázat – ozvěte se přes Pajeníčko nebo na GitHub repo. Šťastné programování!