machine — funkcje związane ze sprzętem

Moduł machine zawiera specyficzne funkcje związane ze sprzętem konkretnej płytki. Większość funkcji w tym module pozwala uzyskać bezpośredni i nieograniczony dostęp do bloków sprzętowych systemu (takich jak CPU, liczniki czasu, magistrale itp.) oraz kontrolę nad nimi.

Dostęp do pamięci

Moduł udostępnia trzy indeksowalne obiekty służące do bezpośredniego dostępu do pamięci. Każdy z nich zachowuje się jak rzadka tablica indeksowana adresem bajtu: value = memN[addr] odczytuje, a memN[addr] = value zapisuje. Adres jest zawsze adresem bajtu, niezależnie od szerokości dostępu.

machine.mem8

Indeksowalny 8-bitowy akcesor pamięci. mem8[addr] odczytuje int z zakresu 0-255 z bajtu pod adresem addr; mem8[addr] = value zapisuje dolne 8 bitów wartości value. addr musi być wyrównany do 1 bajtu (dowolny adres).

machine.mem16

Indeksowalny 16-bitowy (półsłowo) akcesor pamięci. mem16[addr] odczytuje int z zakresu 0-65535; mem16[addr] = value zapisuje dolne 16 bitów. addr musi być wyrównany do 2 bajtów.

machine.mem32

Indeksowalny 32-bitowy (słowo) akcesor pamięci. mem32[addr] odczytuje int z zakresu 0-0xFFFFFFFF; mem32[addr] = value zapisuje dolne 32 bity. addr musi być wyrównany do 4 bajtów.

Przykład użycia (rejestry są specyficzne dla mikrokontrolera STM32H7 – na OpenMV Cam H7 / H7 Plus / Pure Thermal pin P0 na złączu jest połączony z PB15):

import machine
from micropython import const

GPIOB = const(0x58020400)
GPIO_BSRR = const(0x18)
GPIO_IDR = const(0x10)

# set P0 (PB15) high via the GPIOB bit-set/reset register
machine.mem32[GPIOB + GPIO_BSRR] = 1 << 15

# read P0 (PB15) directly out of the GPIOB input-data register
value = (machine.mem32[GPIOB + GPIO_IDR] >> 15) & 1

Funkcje związane z resetem

machine.reset() → None

Twardo resetuje urządzenie w sposób podobny do naciśnięcia zewnętrznego przycisku RESET.

machine.soft_reset() → None

Wykonuje miękki reset interpretera, usuwając wszystkie obiekty Pythona i resetując stertę Pythona.

machine.reset_cause() → int

Zwraca przyczynę resetu. Zobacz stałe, aby poznać możliwe wartości zwracane.

machine.bootloader(value: int | None = None, /) → NoReturn

Resetuje kamerę do jej bootloadera DFU / pobierania szeregowego, gotowego do ponownego wgrania nowego oprogramowania układowego. To wywołanie nigdy nie zwraca wartości; płytka uruchamia się ponownie bezpośrednio do bootloadera.

Argument value jest akceptowany dla zgodności między portami, ale jest ignorowany na każdej płytce obsługiwanej przez OpenMV.

Funkcje związane z przerwaniami

Poniższe funkcje pozwalają na kontrolę nad przerwaniami. Niektóre systemy wymagają przerwań do poprawnego działania, więc wyłączanie ich na długie okresy może zagrozić podstawowej funkcjonalności, na przykład watchdog timery mogą wyzwolić się nieoczekiwanie. Przerwania powinny być wyłączane wyłącznie na minimalny czas, a następnie ponownie włączane do poprzedniego stanu. Na przykład:

import machine

# Disable interrupts
state = machine.disable_irq()

# Do a small amount of time-critical work here

# Enable interrupts
machine.enable_irq(state)

machine.disable_irq() → int

Wyłącza żądania przerwań. Zwraca poprzedni stan IRQ, który należy traktować jako wartość nieprzezroczystą. Tę wartość zwracaną należy przekazać do funkcji enable_irq(), aby przywrócić przerwania do ich pierwotnego stanu, sprzed wywołania disable_irq().

machine.enable_irq(state: int) → None

Ponownie włącza żądania przerwań. Parametr state powinien być wartością zwróconą przez najnowsze wywołanie funkcji disable_irq().

Funkcje związane z zasilaniem

machine.freq(hz: int | None = None, /) → int | tuple[int, ...]

Zwraca częstotliwości zegara MCU.

Na portach STM32 (każda OpenMV Cam M4/M7/H7/H7+/PT/N6 oraz warianty marki Arduino) wartością zwracaną jest krotka zegarów wewnętrznych w Hz. Na STM32N6 (OpenMV Cam N6) krotka ma postać (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5); na pozostałych kamerach STM32 jest to (SYSCLK, HCLK, PCLK1, PCLK2).

Na porcie mimxrt (OpenMV Cam RT1062) oraz porcie alif (OpenMV Cam AE3) wartością zwracaną jest pojedyncza liczba całkowita – częstotliwość CPU w Hz.

Wywołanie freq(hz) w celu ustawienia zegara zgłasza NotImplementedError na każdej płytce obsługiwanej przez OpenMV.

machine.idle() → None

Bramkuje zegar CPU, co jest przydatne do zmniejszenia poboru mocy w dowolnym momencie podczas krótkich lub długich okresów. Urządzenia peryferyjne nadal działają, a wykonanie wznawia się natychmiast po wyzwoleniu dowolnego przerwania lub najpóźniej jedną milisekundę po wstrzymaniu CPU.

Zaleca się wywoływanie tej funkcji wewnątrz każdej ciasnej pętli, która stale sprawdza zmianę zewnętrzną (czyli odpytuje). Zmniejszy to pobór mocy bez znaczącego wpływu na wydajność. Aby jeszcze bardziej zmniejszyć pobór mocy, zobacz funkcje lightsleep(), time.sleep() oraz time.sleep_ms().

machine.sleep() → None

Informacja

Ta funkcja jest przestarzała, zamiast niej użyj lightsleep() bez argumentów.

machine.lightsleep(time_ms: int | None = None, /) → None

Zatrzymuje wykonanie i wchodzi w stan niskiego poboru mocy z pełnym zachowaniem RAM i urządzeń peryferyjnych. Zegar MCU jest bramkowany; gdy funkcja zwróci wartość, wykonanie wznawia się od miejsca, w którym wywołano lightsleep(), przy czym każdy podsystem nadal działa.

Jeśli podano time_ms, jest to maksymalny czas uśpienia w milisekundach. Z limitem czasu lub bez niego wykonanie może wznowić się wcześniej, jeśli wyzwoli się dowolne skonfigurowane źródło wybudzenia (przerwanie Pin, alarm RTC, włączone przerwanie urządzenia peryferyjnego, …). Źródła wybudzenia muszą zostać skonfigurowane przed wywołaniem.

Oszczędność energii jest skromniejsza niż przy deepsleep(), ale wybudzenie jest natychmiastowe i żaden stan nie zostaje utracony.

machine.deepsleep(time_ms: int | None = None, /) → NoReturn

Zatrzymuje wykonanie i wchodzi w najgłębszy dostępny stan niskiego poboru mocy. Zawartość RAM, stan urządzeń peryferyjnych oraz połączenia sieciowe mogą zostać utracone. Gdy MCU się wybudzi, uruchamia się od początku głównego skryptu, podobnie jak przy włączeniu zasilania lub twardym resecie; reset_cause() zwróci wówczas DEEPSLEEP_RESET, dzięki czemu skrypt może odróżnić wybudzenie z deepsleep od innych przyczyn resetu.

Jeśli podano time_ms, MCU planuje wybudzenie po tylu milisekundach (lub wcześniej, jeśli wyzwoli się najpierw inne skonfigurowane źródło wybudzenia). Nie przekazuj nic, aby uśpić do momentu wyzwolenia zewnętrznego źródła wybudzenia.

To wywołanie nigdy nie zwraca wartości – obsłuż wznowione wykonanie na początku głównego skryptu, uzależniając je od reset_cause().

Funkcje różne

machine.unique_id() → bytes

Zwraca obiekt bytes zawierający unikalny identyfikator tej płytki. Wartość jest odczytywana ze sprzętu MCU (zazwyczaj jest to zaprogramowany fabrycznie numer seryjny urządzenia), więc jest stabilna pomiędzy restartami i różni się dla każdej płytki.

Długość zależy od rodziny MCU – 12 bajtów na STM32, 8 bajtów na portach mimxrt i alif. Jeśli aplikacja potrzebuje ID o stałej długości, wytnij fragment lub zahaszuj zwróconą wartość.

machine.time_pulse_us(pin: Pin, pulse_level: int, timeout_us: int = 1000000, /) → int

Mierzy szerokość pojedynczego impulsu na pin i zwraca jego czas trwania w mikrosekundach.

pin musi być skonfigurowany jako wejście cyfrowe.

pulse_level to polaryzacja impulsu, którego czas ma być mierzony: 1 dla impulsu wysokiego, 0 dla impulsu niskiego.

Funkcja działa w dwóch fazach. Najpierw, jeśli pin nie jest jeszcze na poziomie pulse_level, czeka, aż pin przejdzie na poziom pulse_level (początek impulsu). Następnie mierzy czas, przez który pin pozostaje na poziomie pulse_level przed powrotem (koniec impulsu). Zmierzony czas zwracany jest w mikrosekundach.

timeout_us ogranicza każdą fazę niezależnie (więc w najgorszym przypadku wywołanie trwa do 2 * timeout_us). W przypadku przekroczenia limitu czasu funkcja zwraca wartość ujemną wskazującą, której fazy dotyczył limit:

• -2 – przekroczono limit czasu podczas oczekiwania na zbocze narastające (pin nigdy nie osiągnął pulse_level).

• -1 – przekroczono limit czasu podczas oczekiwania na zbocze opadające (impuls był dłuższy niż timeout_us).

machine.bitstream(pin: Pin, encoding: int, timing: tuple, data: bytes, /) → None

Transmituje data metodą bit-bangingu na określonym pin. Argument encoding określa sposób kodowania bitów, a timing to specyfikacja czasowa zależna od kodowania.

Obsługiwane kodowania to:

• 0 dla modulacji czasu trwania impulsu typu „high low”. Spowoduje to transmisję bitów 0 i 1 jako impulsów o określonym czasie, zaczynając od najbardziej znaczącego bitu. timing musi być czteroelementową krotką nanosekund w formacie (high_time_0, low_time_0, high_time_1, low_time_1). Na przykład (400, 850, 800, 450) to specyfikacja czasowa dla diod RGB WS2812 przy 800 kHz.

Dokładność czasowa zależy od sprzętu; szybsze MCU produkują bardziej precyzyjne impulsy (zazwyczaj kilkadziesiąt nanosekund).

Informacja

Do sterowania paskami WS2812 / NeoPixel zobacz moduł neopixel, który oferuje API wyższego poziomu.

Stałe

Poniższe stałe są zwracane przez reset_cause() i identyfikują, dlaczego MCU ostatnio się zresetował. Dostępne na portach STM32 i mimxrt; port alif (OpenMV Cam AE3) nie udostępnia obecnie stałych przyczyny resetu, a jego reset_cause() zawsze zwraca 0.

machine.PWRON_RESET: int

Reset spowodowany doprowadzeniem zasilania do układu. Porty STM32 i mimxrt.

machine.WDT_RESET: int

Reset spowodowany wygaśnięciem watchdog timera. Porty STM32 i mimxrt.

machine.SOFT_RESET: int

Reset spowodowany przez soft_reset() (interpreter Pythona uruchomił się ponownie bez sprzętowego resetu). Porty STM32 i mimxrt.

machine.HARD_RESET: int

Reset spowodowany ustawieniem pinu NRST (zewnętrzny przycisk resetu). Tylko porty STM32.

machine.DEEPSLEEP_RESET: int

Reset spowodowany wybudzeniem z trybu deep-sleep. Tylko porty STM32.

Klasy

• klasa Pin – sterowanie pinami I/O
• klasa Signal – sterowanie i odczyt zewnętrznych urządzeń I/O
• klasa LED – przenośne sterowanie wbudowaną diodą LED
• klasa ADC – konwersja analogowo-cyfrowa
• klasa PWM – modulacja szerokości impulsu
• klasa UART – magistrala szeregowej komunikacji dwukierunkowej
• klasa SPI – protokół magistrali Serial Peripheral Interface (strona kontrolera)
• klasa SoftSPI – magistrala SPI emulowana programowo
• klasa I2C – dwuprzewodowy protokół szeregowy
• klasa SoftI2C – programowo emulowana magistrala I2C
• klasa I2CTarget – urządzenie docelowe I2C
• klasa I2S – protokół magistrali Inter-IC Sound
• klasa CAN – protokół Controller Area Network
• klasa RTC – zegar czasu rzeczywistego
• klasa Timer – wirtualny licznik czasu okresowy / jednorazowy
• klasa WDT – watchdog timer
• klasa SDCard – sterownik karty SD / MMC
• class Counter – licznik impulsów
• class Encoder – dekoder kwadraturowy