micropython — toegang tot en beheer van MicroPython-interne onderdelen

Functies

micropython.const(expr: int) → int

Wordt gebruikt om te verklaren dat de expressie een constante is, zodat de compiler deze kan optimaliseren. Het gebruik van deze functie moet als volgt zijn:

from micropython import const

CONST_X = const(123)
CONST_Y = const(2 * CONST_X + 1)

Op deze manier gedeclareerde constanten zijn nog steeds toegankelijk als globale variabelen van buiten de module waarin ze zijn gedeclareerd. Als een constante daarentegen begint met een underscore, dan is ze verborgen, is ze niet beschikbaar als globale variabele en neemt ze tijdens de uitvoering geen geheugen in beslag.

Deze const-functie wordt rechtstreeks herkend door de MicroPython-parser en wordt voornamelijk als onderdeel van de micropython-module aangeboden, zodat scripts geschreven kunnen worden die zowel onder CPython als MicroPython draaien, door bovenstaand patroon te volgen.

micropython.opt_level(level: int | None = None) → int | None

Als level is opgegeven, stelt deze functie het optimalisatieniveau in voor de daaropvolgende compilatie van scripts en retourneert None. Anders retourneert ze het huidige optimalisatieniveau.

Het optimalisatieniveau bepaalt de volgende compilatiefuncties:

  • Assertions: op niveau 0 zijn assertion-statements ingeschakeld en worden ze in de bytecode gecompileerd; op niveau 1 en hoger worden assertions niet gecompileerd.

  • Ingebouwde __debug__-variabele: op niveau 0 wordt deze variabele uitgebreid tot True; op niveau 1 en hoger wordt ze uitgebreid tot False.

  • Regelnummers van broncode: op niveau 0, 1 en 2 worden regelnummers van de broncode samen met de bytecode opgeslagen, zodat uitzonderingen het regelnummer kunnen melden waarop ze zijn opgetreden; op niveau 3 en hoger worden regelnummers niet opgeslagen.

Het standaard optimalisatieniveau is gewoonlijk niveau 0.

micropython.alloc_emergency_exception_buf(size: int) → None

Wijs size bytes RAM toe voor de noodbuffer voor uitzonderingen (een goede grootte is ongeveer 100 bytes). De buffer wordt gebruikt om uitzonderingen aan te maken in gevallen waarin normale RAM-toewijzing zou mislukken (bijv. binnen een interrupt-handler) en geeft daarmee in die situaties bruikbare traceback-informatie.

Een goede manier om deze functie te gebruiken is door haar aan het begin van uw hoofdscript te plaatsen (bijv. boot.py of main.py), waarna de noodbuffer voor uitzonderingen actief is voor alle code die erop volgt.

micropython.mem_info(verbose: Any | None = None) → None

Druk informatie af over het momenteel gebruikte geheugen. Als het argument verbose is opgegeven, wordt er extra informatie afgedrukt.

De afgedrukte informatie is implementatie-afhankelijk, maar omvat momenteel de hoeveelheid gebruikte stack en heap. In verbose-modus drukt ze de volledige heap af met aanduiding van welke blokken gebruikt en welke vrij zijn.

micropython.qstr_info(verbose: Any | None = None) → None

Druk informatie af over de momenteel ge-internde strings. Als het argument verbose is opgegeven, wordt er extra informatie afgedrukt.

De afgedrukte informatie is implementatie-afhankelijk, maar omvat momenteel het aantal ge-internde strings en de hoeveelheid RAM die ze gebruiken. In verbose-modus drukt ze de namen af van alle in RAM ge-internde strings.

micropython.stack_use() → int

Retourneer een geheel getal dat de huidige hoeveelheid gebruikte stack vertegenwoordigt. De absolute waarde hiervan is niet bijzonder nuttig; ze moet eerder worden gebruikt om verschillen in stackgebruik op verschillende punten te berekenen.

micropython.heap_lock() → None

Vergrendel de heap. Terwijl deze vergrendeld is, kan er geen geheugentoewijzing plaatsvinden en wordt er een MemoryError veroorzaakt als er een heap-toewijzing wordt geprobeerd.

Vergrendelingen nesten: het meerdere keren aanroepen van heap_lock() verhoogt de vergrendelingsdiepte. De heap blijft vergrendeld totdat heap_unlock() hetzelfde aantal keren is aangeroepen.

Als de REPL actief wordt terwijl de heap vergrendeld is, wordt deze geforceerd ontgrendeld.

micropython.heap_unlock() → int

Verlaag de vergrendelingsdiepte van de heap met één en retourneer de nieuwe diepte als een niet-negatief geheel getal. Een retourwaarde van 0 betekent dat de heap niet langer vergrendeld is en dat toewijzingen weer zijn toegestaan.

micropython.heap_locked() → int

Retourneer de huidige vergrendelingsdiepte van de heap als een niet-negatief geheel getal; 0 betekent dat de heap niet vergrendeld is.

Opmerking: deze functie is niet beschikbaar op de OpenMV Cam.

micropython.kbd_intr(chr: int) → None

Stel het teken in dat een KeyboardInterrupt-uitzondering zal veroorzaken. Standaard is dit ingesteld op 3 tijdens scriptuitvoering, wat overeenkomt met Ctrl-C. Het doorgeven van -1 aan deze functie schakelt het opvangen van Ctrl-C uit, en het doorgeven van 3 herstelt het.

Deze functie kan worden gebruikt om het opvangen van Ctrl-C te voorkomen op de binnenkomende stroom van tekens die gewoonlijk voor de REPL wordt gebruikt, voor het geval die stroom voor andere doeleinden wordt gebruikt.

micropython.schedule(func: Callable[[Any], Any], arg: Any) → None

Plan de functie func om “heel binnenkort” te worden uitgevoerd. Aan de functie wordt de waarde arg als enig argument doorgegeven. “Heel binnenkort” betekent dat de MicroPython-runtime zijn best zal doen om de functie zo vroeg mogelijk uit te voeren, gegeven dat hij ook efficiënt probeert te zijn en dat aan de volgende voorwaarden wordt voldaan:

  • Een geplande functie zal nooit voorrang nemen op een andere geplande functie.

  • Geplande functies worden altijd “tussen opcodes” uitgevoerd, wat betekent dat alle fundamentele Python-bewerkingen (zoals het toevoegen aan een lijst) gegarandeerd atomair zijn.

  • Een bepaalde port kan “kritieke regio’s” definiëren waarbinnen geplande functies nooit worden uitgevoerd. Functies kunnen binnen een kritieke regio worden gepland, maar ze worden pas uitgevoerd wanneer die regio wordt verlaten. Een voorbeeld van een kritieke regio is een voorrang nemende interrupt-handler (een IRQ).

  • Binnen native-codefuncties worden geplande functies niet aangeroepen, tenzij de native code een functie aanroept die dit specifiek doet.

  • Bepaalde functies, waaronder poll.poll, poll.ipoll, time.sleep en time.sleep_ms (inclusief slaapperioden van nul duur), zullen geplande functies aanroepen.

Een toepassing van deze functie is het plannen van een callback vanuit een voorrang nemende IRQ. Zo’n IRQ legt beperkingen op aan de code die in de IRQ draait (bijvoorbeeld kan de heap vergrendeld zijn) en het plannen van een functie om later aan te roepen heft die beperkingen op.

Op multithreaded ports hangt het gedrag van de geplande functie af van of de Global Interpreter Lock (GIL) is ingeschakeld voor de specifieke port:

  • Als GIL is ingeschakeld, kan de functie voorrang nemen op elke thread en in diens context draaien.

  • Als GIL is uitgeschakeld, neemt de functie alleen voorrang op de hoofdthread en draait ze in diens context.

Opmerking: als schedule() wordt aangeroepen vanuit een voorrang nemende IRQ, wanneer geheugentoewijzing niet is toegestaan en de aan schedule() door te geven callback een gebonden methode is, zal het rechtstreeks doorgeven hiervan mislukken. Dit komt doordat het aanmaken van een referentie naar een gebonden methode geheugentoewijzing veroorzaakt. Een oplossing is om een referentie naar de methode aan te maken in de klasse-constructor en die referentie aan schedule() door te geven. Dit wordt hier in detail besproken: reference documentation onder “Creation of Python objects”.

Er is een eindige wachtrij om de geplande functies vast te houden en schedule() zal een RuntimeError veroorzaken als de wachtrij vol is.

Klassen

class micropython.RingIO(size: int)
class micropython.RingIO(buffer: bytes | bytearray | memoryview)

Biedt een ringbuffer met vaste grootte voor bytes met een stream-interface. Kan worden beschouwd als een FIFO-wachtrijvariant van io.BytesIO. De twee constructorvormen verschillen alleen in hoe de onderliggende buffer wordt aangeleverd:

  • RingIO(size) wijst de onderliggende buffer intern toe. Het klassieke ringbuffer-algoritme reserveert één byte voor het bijhouden, dus de toegewezen buffer is één byte groter dan size en de instantie kan de volledige size bytes aan gegevens bevatten. RingIO(16) wijst bijvoorbeeld een buffer van 17 bytes toe en bevat 16 bytes aan gegevens.

  • RingIO(buffer) gebruikt de aangeleverde buffer ter plaatse in plaats van er een toe te wijzen. Omdat één byte wordt gereserveerd voor het bijhouden, kan de instantie len(buffer) - 1 bytes aan gegevens bevatten. RingIO(bytearray(16)) bevat bijvoorbeeld 15 bytes aan gegevens.

Een RingIO-instantie is IRQ-/threadveilig wanneer ze wordt gebruikt om gegevens in één richting door te geven (bijvoorbeeld er naartoe geschreven vanuit een IRQ en eruit gelezen vanuit een niet-IRQ-functie, of omgekeerd). Dit geldt niet als een enkele instantie wordt beschreven vanuit zowel IRQ- als niet-IRQ-contexten, wat vaak gegevenscorruptie zou veroorzaken.

any() → int

Retourneert een geheel getal dat het aantal tekens telt dat kan worden gelezen.

read(nbytes: int | None = None) → bytes

Lees beschikbare tekens. Dit is een niet-blokkerende functie. Als nbytes is opgegeven, lees dan hoogstens dat aantal bytes, anders lees zoveel gegevens als mogelijk.

Retourwaarde: een bytes-object dat de gelezen bytes bevat. Zal een bytes-object met lengte nul zijn als er geen gegevens beschikbaar zijn.

readline(nbytes: int | None = None) → bytes

Lees een regel, eindigend op een newline-teken of return als er een in de buffer aanwezig is, anders retourneer de beschikbare bytes in de buffer. Als nbytes is opgegeven, lees dan hoogstens dat aantal bytes.

Retourwaarde: een bytes-object dat de gelezen regel bevat.

readinto(buf: bytearray | memoryview, nbytes: int | None = None) → int

Lees beschikbare bytes in de aangeleverde buf. Als nbytes is opgegeven, lees dan hoogstens dat aantal bytes. Anders lees hoogstens len(buf) bytes.

Retourwaarde: geheeltallig aantal van het aantal bytes dat in buf is gelezen.

write(buf: bytes | bytearray | memoryview) → int

Niet-blokkerend schrijven van bytes vanuit buf naar de ringbuffer, beperkt door de beschikbare ruimte in de ringbuffer.

Retourwaarde: geheeltallig aantal geschreven bytes.

close() → None

No-op die wordt aangeboden als onderdeel van de standaard stream-interface. Heeft geen effect op gegevens in de ringbuffer.