micropython — åtkomst till och kontroll av MicroPython-interna delar

Funktioner

micropython.const(expr: int) → int

Används för att deklarera att uttrycket är en konstant så att kompilatorn kan optimera det. Användningen av denna funktion bör se ut enligt följande:

from micropython import const

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

Konstanter som deklareras på detta sätt är fortfarande åtkomliga som globala variabler utanför den modul de deklareras i. Å andra sidan, om en konstant börjar med ett understreck så är den dold, den är inte tillgänglig som en global variabel, och tar inte upp något minne under körning.

Denna const-funktion känns igen direkt av MicroPython-parsern och tillhandahålls som en del av modulen micropython huvudsakligen så att skript kan skrivas som körs under både CPython och MicroPython, genom att följa mönstret ovan.

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

Om level anges så ställer denna funktion in optimeringsnivån för efterföljande kompilering av skript, och returnerar None. Annars returnerar den den aktuella optimeringsnivån.

Optimeringsnivån styr följande kompileringsfunktioner:

  • Assertions: på nivå 0 är assertion-satser aktiverade och kompileras in i bytekoden; på nivå 1 och högre kompileras inte assertions.

  • Inbyggd variabel __debug__: på nivå 0 expanderar denna variabel till True; på nivå 1 och högre expanderar den till False.

  • Källkodens radnummer: på nivå 0, 1 och 2 lagras källkodens radnummer tillsammans med bytekoden så att undantag kan rapportera det radnummer där de inträffade; på nivå 3 och högre lagras inte radnummer.

Standardoptimeringsnivån är vanligtvis nivå 0.

micropython.alloc_emergency_exception_buf(size: int) → None

Allokera size byte RAM för nödfallsbufferten för undantag (en bra storlek är runt 100 byte). Bufferten används för att skapa undantag i fall där normal RAM-allokering skulle misslyckas (t.ex. inom en avbrottshanterare) och därmed ge användbar bakåtspårningsinformation i dessa situationer.

Ett bra sätt att använda denna funktion är att placera den i början av ditt huvudskript (t.ex. boot.py eller main.py), och då kommer nödfallsbufferten för undantag att vara aktiv för all kod som följer efter den.

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

Skriv ut information om för närvarande använt minne. Om argumentet verbose anges skrivs extra information ut.

Informationen som skrivs ut är implementeringsberoende, men inkluderar för närvarande mängden stack och heap som används. I utförligt läge skrivs hela heapen ut med angivelse av vilka block som används och vilka som är lediga.

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

Skriv ut information om för närvarande internerade strängar. Om argumentet verbose anges skrivs extra information ut.

Informationen som skrivs ut är implementeringsberoende, men inkluderar för närvarande antalet internerade strängar och mängden RAM de använder. I utförligt läge skrivs namnen på alla RAM-internerade strängar ut.

micropython.stack_use() → int

Returnera ett heltal som representerar den aktuella mängden stack som används. Det absoluta värdet av detta är inte särskilt användbart, snarare bör det användas för att beräkna skillnader i stackanvändning vid olika punkter.

micropython.heap_lock() → None

Lås heapen. Medan den är låst kan ingen minnesallokering ske och ett MemoryError utlöses om någon heap-allokering försöks.

Lås kapslas: att anropa heap_lock() flera gånger ökar låsdjupet. Heapen förblir låst tills heap_unlock() har anropats samma antal gånger.

Om REPL blir aktiv med heapen låst kommer den att tvångslåsas upp.

micropython.heap_unlock() → int

Minska heapens låsdjup med ett och returnera det nya djupet som ett icke-negativt heltal. Ett returvärde på 0 betyder att heapen inte längre är låst och att allokeringar återigen är tillåtna.

micropython.heap_locked() → int

Returnera heapens aktuella låsdjup som ett icke-negativt heltal; 0 betyder att heapen inte är låst.

Obs: denna funktion är inte tillgänglig på OpenMV Cam.

micropython.kbd_intr(chr: int) → None

Ställ in det tecken som ska utlösa ett KeyboardInterrupt-undantag. Som standard är detta inställt på 3 under skriptkörning, vilket motsvarar Ctrl-C. Att skicka -1 till denna funktion inaktiverar fångst av Ctrl-C, och att skicka 3 återställer det.

Denna funktion kan användas för att förhindra fångst av Ctrl-C i den inkommande strömmen av tecken som vanligtvis används för REPL, ifall den strömmen används för andra ändamål.

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

Schemalägg funktionen func för att köras ”mycket snart”. Funktionen får värdet arg som sitt enda argument. ”Mycket snart” betyder att MicroPython-körtiden gör sitt bästa för att köra funktionen vid tidigast möjliga tidpunkt, givet att den också försöker vara effektiv, och att följande villkor gäller:

  • En schemalagd funktion kommer aldrig att avbryta en annan schemalagd funktion.

  • Schemalagda funktioner körs alltid ”mellan opcoder”, vilket betyder att alla grundläggande Python-operationer (såsom att lägga till i en lista) garanteras vara atomära.

  • En given port kan definiera ”kritiska regioner” inom vilka schemalagda funktioner aldrig körs. Funktioner kan schemaläggas inom en kritisk region men de körs inte förrän den regionen lämnas. Ett exempel på en kritisk region är en avbrytande avbrottshanterare (en IRQ).

  • Inuti nativa kodfunktioner anropas inte schemalagda funktioner såvida inte den nativa koden anropar en funktion som specifikt gör det.

  • Vissa funktioner inklusive poll.poll, poll.ipoll, time.sleep och time.sleep_ms (inklusive sömnperioder med noll varaktighet) anropar schemalagda funktioner.

En användning för denna funktion är att schemalägga ett återanrop från en avbrytande IRQ. En sådan IRQ ställer begränsningar på koden som körs i IRQ:en (till exempel kan heapen vara låst) och att schemalägga en funktion för att anropa senare lyfter dessa begränsningar.

På flertrådade portar beror den schemalagda funktionens beteende på huruvida Global Interpreter Lock (GIL) är aktiverat för den specifika porten:

  • Om GIL är aktiverat kan funktionen avbryta vilken tråd som helst och köras i dess kontext.

  • Om GIL är inaktiverat kommer funktionen endast att avbryta huvudtråden och köras i dess kontext.

Obs: Om schedule() anropas från en avbrytande IRQ, när minnesallokering inte är tillåten och återanropet som ska skickas till schedule() är en bunden metod, kommer det att misslyckas att skicka detta direkt. Detta beror på att skapandet av en referens till en bunden metod orsakar minnesallokering. En lösning är att skapa en referens till metoden i klassens konstruktor och att skicka den referensen till schedule(). Detta diskuteras i detalj här reference documentation under ”Creation of Python objects”.

Det finns en ändlig kö för att hålla de schemalagda funktionerna och schedule() kommer att utlösa ett RuntimeError om kön är full.

Klasser

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

Tillhandahåller en ringbuffert med fast storlek för bytes med ett strömgränssnitt. Kan betraktas som en FIFO-kövariant av io.BytesIO. De två konstruktorformerna skiljer sig endast i hur den underliggande bufferten tillhandahålls:

  • RingIO(size) allokerar den underliggande bufferten internt. Den klassiska ringbuffertalgoritmen reserverar en byte för spårning, så den allokerade bufferten är en byte större än size och instansen kan hålla hela size byte med data. Till exempel allokerar RingIO(16) en buffert på 17 byte och håller 16 byte data.

  • RingIO(buffer) använder den tillhandahållna buffer på plats istället för att allokera en. Eftersom en byte reserveras för spårning kan instansen hålla len(buffer) - 1 byte data. Till exempel håller RingIO(bytearray(16)) 15 byte data.

En RingIO-instans är IRQ-/trådsäker när den används för att skicka data i en enda riktning (till exempel skriven till från en IRQ och läst från en icke-IRQ-funktion, eller vice versa). Detta gäller inte om en enda instans skrivs till från både IRQ- och icke-IRQ-kontexter, vilket ofta skulle orsaka datakorruption.

any() → int

Returnerar ett heltal som räknar antalet tecken som kan läsas.

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

Läs tillgängliga tecken. Detta är en icke-blockerande funktion. Om nbytes anges läs då högst så många byte, annars läs så mycket data som möjligt.

Returvärde: ett bytes-objekt som innehåller de lästa byten. Kommer att vara ett bytes-objekt med nolllängd om ingen data är tillgänglig.

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

Läs en rad, som slutar med ett radslutstecken eller retur om en sådan finns i bufferten, annars returnera tillgängliga byte i bufferten. Om nbytes anges läs då högst så många byte.

Returvärde: ett bytes-objekt som innehåller den lästa raden.

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

Läs tillgängliga byte in i den tillhandahållna buf. Om nbytes anges läs då högst så många byte. Annars, läs högst len(buf) byte.

Returvärde: Heltalsräkning av antalet byte lästa in i buf.

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

Icke-blockerande skrivning av byte från buf in i ringbufferten, begränsad av det tillgängliga utrymmet i ringbufferten.

Returvärde: Heltalsräkning av skrivna byte.

close() → None

No-op som tillhandahålls som en del av standardgränssnittet stream. Har ingen effekt på data i ringbufferten.