micropython — MicroPythonin sisäisten osien käyttö ja hallinta

Funktiot

micropython.const(expr: int) → int

Käytetään ilmoittamaan, että lauseke on vakio, jotta kääntäjä voi optimoida sen. Tätä funktiota tulee käyttää seuraavasti:

from micropython import const

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

Tällä tavalla ilmoitetut vakiot ovat edelleen käytettävissä globaaleina muuttujina sen moduulin ulkopuolelta, jossa ne on ilmoitettu. Toisaalta, jos vakio alkaa alaviivalla, se on piilotettu, sitä ei ole saatavilla globaalina muuttujana eikä se vie lainkaan muistia suorituksen aikana.

Tämän const -funktion MicroPython-jäsennin tunnistaa suoraan, ja se tarjotaan osana micropython -moduulia pääasiassa siksi, että skriptejä voidaan kirjoittaa toimimaan sekä CPythonissa että MicroPythonissa edellä kuvattua mallia noudattamalla.

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

Jos level annetaan, tämä funktio asettaa optimointitason skriptien myöhempää kääntämistä varten ja palauttaa None. Muussa tapauksessa se palauttaa nykyisen optimointitason.

Optimointitaso ohjaa seuraavia käännösominaisuuksia:

• Vakuutuslauseet (assertions): tasolla 0 vakuutuslauseet ovat käytössä ja käännetään tavukoodiin; tasoilla 1 ja korkeammilla vakuutuslauseita ei käännetä.

• Sisäänrakennettu __debug__ -muuttuja: tasolla 0 tämä muuttuja laajenee arvoksi True; tasoilla 1 ja korkeammilla se laajenee arvoksi False.

• Lähdekoodin rivinumerot: tasoilla 0, 1 ja 2 lähdekoodin rivinumerot tallennetaan tavukoodin mukana, jotta poikkeukset voivat raportoida rivin, jolla ne tapahtuivat; tasoilla 3 ja korkeammilla rivinumeroita ei tallenneta.

Oletusarvoinen optimointitaso on yleensä taso 0.

micropython.alloc_emergency_exception_buf(size: int) → None

Varaa size tavua RAM-muistia hätäpoikkeuspuskuria varten (hyvä koko on noin 100 tavua). Puskuria käytetään poikkeusten luomiseen tilanteissa, joissa normaali RAM-muistin varaus epäonnistuisi (esim. keskeytyskäsittelijän sisällä), ja siten hyödyllisen jäljitystiedon tarjoamiseen näissä tilanteissa.

Hyvä tapa käyttää tätä funktiota on sijoittaa se pääskriptisi alkuun (esim. boot.py tai main.py), jolloin hätäpoikkeuspuskuri on aktiivinen kaikelle sen jälkeen tulevalle koodille.

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

Tulosta tietoja tällä hetkellä käytetystä muistista. Jos verbose -argumentti annetaan, tulostetaan lisätietoja.

Tulostettavat tiedot ovat toteutuskohtaisia, mutta sisältävät tällä hetkellä käytetyn pinon ja keon määrän. Verbose-tilassa se tulostaa koko keon ilmoittaen, mitkä lohkot ovat käytössä ja mitkä vapaita.

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

Tulosta tietoja tällä hetkellä internoiduista merkkijonoista. Jos verbose -argumentti annetaan, tulostetaan lisätietoja.

Tulostettavat tiedot ovat toteutuskohtaisia, mutta sisältävät tällä hetkellä internoitujen merkkijonojen määrän ja niiden käyttämän RAM-muistin määrän. Verbose-tilassa se tulostaa kaikkien RAM-internoitujen merkkijonojen nimet.

micropython.stack_use() → int

Palauta kokonaisluku, joka edustaa tällä hetkellä käytetyn pinon määrää. Tämän absoluuttinen arvo ei ole erityisen hyödyllinen, vaan sitä tulisi käyttää pinon käytön erojen laskemiseen eri kohdissa.

micropython.heap_lock() → None

Lukitse keko. Lukituksen aikana muistinvarausta ei voi tapahtua, ja MemoryError aiheutuu, jos keon varausta yritetään.

Lukitukset sisäkkäistyvät: heap_lock() -kutsuminen useita kertoja kasvattaa lukitussyvyyttä. Keko pysyy lukittuna, kunnes heap_unlock() on kutsuttu saman verran kertoja.

Jos REPL aktivoituu keon ollessa lukittuna, lukitus avataan pakotetusti.

micropython.heap_unlock() → int

Vähennä keon lukitussyvyyttä yhdellä ja palauta uusi syvyys ei-negatiivisena kokonaislukuna. Paluuarvo 0 tarkoittaa, että keko ei ole enää lukittu ja varaukset ovat jälleen sallittuja.

micropython.heap_locked() → int

Palauta nykyinen keon lukitussyvyys ei-negatiivisena kokonaislukuna; 0 tarkoittaa, ettei keko ole lukittu.

Huomautus: tämä funktio ei ole käytettävissä OpenMV Camissa.

micropython.kbd_intr(chr: int) → None

Aseta merkki, joka aiheuttaa KeyboardInterrupt -poikkeuksen. Oletuksena tämä on asetettu arvoon 3 skriptin suorituksen aikana, mikä vastaa Ctrl-C:tä. Arvon -1 välittäminen tälle funktiolle poistaa Ctrl-C:n kaappauksen käytöstä, ja arvon 3 välittäminen palauttaa sen.

Tällä funktiolla voidaan estää Ctrl-C:n kaappaus saapuvasta merkkivirrasta, jota yleensä käytetään REPLiin, siltä varalta, että virtaa käytetään muihin tarkoituksiin.

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

Aseta funktio func suoritettavaksi ”hyvin pian”. Funktiolle välitetään arvo arg sen ainoana argumenttina. ”Hyvin pian” tarkoittaa, että MicroPython-ajonaikainen järjestelmä tekee parhaansa suorittaakseen funktion mahdollisimman aikaisin, ottaen huomioon, että se pyrkii myös olemaan tehokas, ja että seuraavat ehdot pätevät:

• Ajoitettu funktio ei koskaan keskeytä toista ajoitettua funktiota.

• Ajoitetut funktiot suoritetaan aina ”opcodejen välissä”, mikä tarkoittaa, että kaikki Pythonin perustoiminnot (kuten listaan lisääminen) ovat taatusti atomisia.

• Tietty portti voi määritellä ”kriittisiä alueita”, joiden sisällä ajoitettuja funktioita ei koskaan suoriteta. Funktioita voidaan ajoittaa kriittisen alueen sisällä, mutta niitä ei suoriteta ennen kuin kyseiseltä alueelta poistutaan. Esimerkki kriittisestä alueesta on keskeyttävä keskeytyskäsittelijä (IRQ).

• Natiivien koodifunktioiden sisällä ajoitettuja funktioita ei kutsuta, ellei natiivikoodi kutsu funktiota, joka erityisesti tekee niin.

• Tietyt funktiot, kuten poll.poll, poll.ipoll, time.sleep ja time.sleep_ms (mukaan lukien nollan pituiset unet), kutsuvat ajoitettuja funktioita.

Yksi käyttötarkoitus tälle funktiolle on takaisinkutsun ajoittaminen keskeyttävästä IRQ:sta. Tällainen IRQ asettaa rajoituksia koodille, joka suoritetaan IRQ:ssa (esimerkiksi keko voi olla lukittu), ja funktion ajoittaminen kutsuttavaksi myöhemmin poistaa nämä rajoitukset.

Monisäikeisissä porteissa ajoitetun funktion käyttäytyminen riippuu siitä, onko Global Interpreter Lock (GIL) käytössä kyseisessä portissa:

• Jos GIL on käytössä, funktio voi keskeyttää minkä tahansa säikeen ja suorittua sen kontekstissa.

• Jos GIL on pois käytöstä, funktio keskeyttää vain pääsäikeen ja suorittuu sen kontekstissa.

Huomautus: Jos schedule() kutsutaan keskeyttävästä IRQ:sta, kun muistinvaraus ei ole sallittua ja schedule() -funktiolle välitettävä takaisinkutsu on sidottu metodi, sen välittäminen suoraan epäonnistuu. Tämä johtuu siitä, että viittauksen luominen sidottuun metodiin aiheuttaa muistinvarauksen. Ratkaisuna on luoda viittaus metodiin luokan rakentajassa ja välittää tämä viittaus funktiolle schedule(). Tätä käsitellään yksityiskohtaisesti täällä reference documentation kohdassa ”Creation of Python objects”.

Ajoitettuja funktioita varten on rajallinen jono, ja schedule() aiheuttaa RuntimeError -poikkeuksen, jos jono on täynnä.

Luokat

class micropython.RingIO(size: int)

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

Tarjoaa kiinteäkokoisen rengaspuskurin tavuille virtarajapinnan kanssa. Sitä voidaan pitää io.BytesIO -luokan FIFO-jono-muunnelmana. Kaksi rakentajamuotoa eroavat vain siinä, miten taustapuskuri tarjotaan:

• RingIO(size) varaa taustapuskurin sisäisesti. Klassinen rengaspuskurialgoritmi varaa yhden tavun seurantaa varten, joten varattu puskuri on yhden tavun suurempi kuin size ja ilmentymä voi sisältää kokonaiset size tavua dataa. Esimerkiksi RingIO(16) varaa 17-tavuisen puskurin ja sisältää 16 tavua dataa.

• RingIO(buffer) käyttää tarjottua buffer -puskuria sellaisenaan sen sijaan, että varaisi uuden. Koska yksi tavu varataan seurantaa varten, ilmentymä voi sisältää len(buffer) - 1 tavua dataa. Esimerkiksi RingIO(bytearray(16)) sisältää 15 tavua dataa.

RingIO-ilmentymä on IRQ- ja säieturvallinen, kun sitä käytetään datan välittämiseen yhteen suuntaan (esimerkiksi siihen kirjoitetaan IRQ:sta ja siitä luetaan ei-IRQ-funktiosta tai päinvastoin). Tämä ei päde, jos yhteen ilmentymään kirjoitetaan sekä IRQ- että ei-IRQ-konteksteista, mikä usein aiheuttaisi datan vioittumisen.

any() → int

Palauttaa kokonaisluvun, joka laskee luettavissa olevien merkkien määrän.

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

Lue saatavilla olevat merkit. Tämä on estämätön funktio. Jos nbytes on määritetty, luetaan enintään tuo määrä tavuja, muuten luetaan niin paljon dataa kuin mahdollista.

Paluuarvo: tavuolio, joka sisältää luetut tavut. Se on nollan pituinen tavuolio, jos dataa ei ole saatavilla.

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

Lue rivi, joka päättyy rivinvaihtomerkkiin tai paluumerkkiin, jos sellainen on puskurissa, muuten palauta puskurissa saatavilla olevat tavut. Jos nbytes on määritetty, luetaan enintään tuo määrä tavuja.

Paluuarvo: tavuolio, joka sisältää luetun rivin.

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

Lue saatavilla olevat tavut annettuun buf -puskuriin. Jos nbytes on määritetty, luetaan enintään tuo määrä tavuja. Muuten luetaan enintään len(buf) tavua.

Paluuarvo: kokonaislukumäärä buf -puskuriin luetuista tavuista.

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

Estämätön tavujen kirjoitus buf -puskurista rengaspuskuriin, rajoitettuna rengaspuskurin vapaan tilan mukaan.

Paluuarvo: kokonaislukumäärä kirjoitetuista tavuista.

close() → None

Tyhjä operaatio, joka tarjotaan osana standardia stream -rajapintaa. Sillä ei ole vaikutusta rengaspuskurissa olevaan dataan.