Gebruikershulpmiddelen

Site-hulpmiddelen


program:python:libraries

Python Bibliotheken

Voor de python omgeving zijn verschillende bibliotheken (libraries) gemaakt, specifiek ontwikkelt voor bepaalde taken zoals tijd, hardware, teksten, enz. uit te kunnen voeren. Hieronder heb ik een poging gedaan, om de verschillende, in projecten gebruikte, funkties te beschrijven. Wel moet je daarbij in de gaten houden, dat de beschreven funkties niet compleet hoeven te zijn! Ook heb ik een poging gedaan, om een Nederlandse tekst te maken vanuit de Engelse tekst. Kijk alsjeblieft naar deze (engelstalige) tekst, indien mijn uitleg niet helemaal duidelijk is. Elke beschreven funktie (method) bevat dan ook een link naar de engelstalige site.

Engelstalige documentatie:MicroPython-docs.pdf


Python String Methods

Python heeft een aantalstring methods ingebouwd. Alle string methods geven een nieuwe waarde terug en wijzigen niets aan de orginele tekst.

  • format: string.format(…)
  • find: string.find(value, start, end)
    Deze funktie zoekt de via “value” mee gegevenen tekst en geeft de positie van het eerste karakter terug (startend vanaf '0'). Wanneer de gezochte tekst niet gevonden wordt, geeft de method '-1' terug.
    ⇒ Voorbeeld: led_on=request.find(“/?led=aan”)
    Parameters:
    • value(verplicht): De tekst die we willen zoeken.
    • start(optioneel): De zoek 'start' positie in de orginele string, default is 0 (begin van de tekst).
    • end(optioneel): De zoek 'eind' positie in de orginele tekst, default is het einde van de tekst.

Machine

De machine bibliotheek bevat een aantal hardware gerelateerde funkties. Deze funkties zijn geschreven, specifiek voor het gebruikte (ESP32) board.
Vanuit dezemachine bibliotheek heb ik het volgende gebruikt:

  • machine.Pin: class machine.Pin(id, mode=-1, pull=-1, *, value=None, drive=0, alt=-1)
    Dit is de Constructor binnen de machine.Pin class, welke ervoor zorgt dat de GPIO pin met een specifiek id wordt geassociëerd.
    ⇒ Voorbeeld: led=Pin(2,Pin.OUT,value=1)
    De belangrijke argumenten voor deze constructor zijn:
    • id: Het gpio pinnummer (integer getal), de gpio naam (karakter string), of een combinatie van een poort en pinnummer (tupple: (port,pin)). Wij gebruiken normaal in het programma het pinnummer.
    • mode: De mode waarin de pin geïnitialiseerd wordt
      • Pin.IN: De GPIO poort wordt geïnitializeerd als een input poort.
      • Pin.OUT: De GPIO poort wordt geïnitialiseerd als een output poort.
      • Pin.ANALOG: De GPIO poort wordt gedefinieerd als een analoge (ADC) input poort
      • Meerdere initializatie modes zijn mogelijk, zie de (engelse) beschijving voor uitleg hierover.
    • pull (optioneel): Hiermee kun je aangeven of er een interne pull-up of pull-down weerstand an de input poort hangt. Alleen dus van toepassing bij mode=Pin.IN!
      • None: Geen pull-up of pull-down weerstand met de input poort geassociëerd (Default setting).
      • Pin.PULL_UP: Een pull-up weerstand hangt aan de input poort, de poort is per default “hoog” en moet naar laag getrokken worden.
      • Pin.PULL_DOWN: Een pull-down weerstand hangt aan de input poort, de poort is per default “laag” en moet naar hoog getrokken worden.
    • value=None (optioneel): Hiermee kun je de initiële waarde van de output poort ingeven, alleen dus van toepassing bij mode=Pin.OUT!
    • Andere parameters zijn mogelijk, zie de (engelse) beschrijving voor uitleg.
  • Pin: Pin(x)
    Deze method is niet beschreven (althans, ik kon 'm niet vinden) in de officiële library documentatie, maar werkt dus wel. Voor zover ik kan zien die ie niets meer of minder dan de opgegeven parameter naar de betreffende pin sturen.
    ⇒ Voorbeeld: led(not led.value())
  • Pin.off: Pin.off()
    Zet de waarde van de betreffende GPIO output pin laag ('0').
    ⇒ Voorbeeld: led.off()
  • Pin.on: Pin.on()
    Zet de waarde van de betreffende GPIO output pin hoog ('1').
    ⇒ Voorbeeld: led.on()
  • Pin.value: Pin.value([x])
    Wanneer er een parameter wordt opgegeven in deze method, zal de betreffende pin de opgegeven waarde krijgen. Wanneer er geen parameter wordt opgegeven, krijg je de huidige status van de betreffende pin terug. Voor een pin met mode Pin.IN, omdat deze gespecificeerd is als ingang, zal uiteraard altijd een de betreffende status waarde terug gegeven worden.
    ⇒ Voorbeeld: led(not led.value())

Neopixel

DeNeopixel module verzorgt de aansturing van een of meerdere WS2812/NeoPixel LED(s). De WS2812 is een driver IC, wat één RGB led kan besturen. In principe is een RGB led opgebouwd uit 3 aparte leds (Rood, groen en blauw) die elk met 8 bits (is 256 'grijs' niveaus) bestuurd worden.
Na een reset, zal het IC de éérste 24 bits van de binnenkomende bits afhalen en gebruiken voor de RGB led (3 kanalen van 8 bits) en de rest van de ontvangen bits doorsturen naar de volgende WS2812. Door dus deze IC's in serie te plaatsen, kun je min of meer een oneindig aantal RGB leds aansturen.

  • neopixel.NeoPixel: class neopixel.NeoPixel(pin, n, *, bpp=3, timing=1)
    Met deze class maak je een object, waarmee je de reeks seriëel gekoppelde RGB leds definiëerd. Elk seperaat element van deze class bevat een 3-bits rgb-waarde, waarmee je de kleur en helderheid van de specifieke RGB led bepaald. Het aantal seperate elementen in de class, is gelijk aan het aantal te besturen RGB leds.
    → Voorbeeld: np = neopixel.NeoPixel(27,8)
    De argumenten, die je voor deze constructor meegeeft zij:
    • pin: Het gebruikte GPIO pinnummer, waaraan de (éérste) WS2812 data lijn hangt.
    • n: Het aantal gebruikte RGB leds (seperate elementen)
    • *:
    • bpp (optioneel): Deze parameter kan 2 waarden hebben, '3' voor de RGB led, '4' voor de RGBW led1). Per default is de waarde 3.
    • timing(optioneel): Ook hier kun je twee waarden voor de LED timing opgeven, '0' voor 400kHz, '1' voor 800kHz. Per default staat deze waarde op 1, aangezien de meeste led(strips) een 800kHz timing hebben.
  • write: NeoPixel.write()
    Deze funktie schrijft alle huidige pixelwaardes naar de ledstrip.
    → Voorbeeld: np.write().
    Met dit commando worden alle elementen naar de ledstrip gestuurd.

Network

Deze bibliotheek verzorgt de netwerk drivers en routing configuratie.
Vanuit dezenetwork bibliotheek heb ik het volgende gebruikt:

  • network.WLAN: class network.WLAN(interface_id)
    Dit is een constructor binnen de network.WLAN class. Deze constructor creëert een netwerk interface object, nodig om je netwerk binnen de code te definiëren.
    ⇒ Voorbeeld: wlan=network.WLAN(network.STA_IF)
    Er zijn hierbij twee ondersteunde interface ID types:
    • network.STA_IF: Hiermee connect je aan een specifiek netwerk. Dit heb je nodig om op jouw eigen netwerk te kunnen verbinden.
    • network.AP_IF: Zet een zogenaamd “access point” op, waar andere apparaten naar kunnen connecten.
  • active WLAN.active([is_active])
    Een method, die afhankelijk van een boolean parameter, de netwerk interface aktiveert (is_active = True) of de netwerk interface deaktiveert (is_active = False) 2).
    ⇒ Voorbeeld: wlan.active(True)
  • connect: WLAN.connect(ssid=None, key=None, *, bssid=None)
    Deze method connect aan het netwerk met gegeven ssid en key. De andere parameters zijn voor ons niet van belang en kun je achterwege laten.
    ⇒ Voorbeeld: wlan.connect(WIFI_SSID,WIFI_PASSWORD)
    • ssid: Netwerk naam.
    • key: Netwerk wachtwoord.
  • isconnected: WLAN.isconnected()
    Voor deze method wordt er geen parameter meegegeven en ze geeft de waarde True terug, als er met het opgegeven netwerk (STA mode) verbinding gemaakt is.
    ⇒ Voorbeeld: while not wlan.isconnected():
  • ifconfig: WLAN.ifconfig([(ip, subnet, gateway, dns)])
    Hier hoef je geen parameters mee te geven. Zonder parameters zal de method de huidige configuratie in tuple vorm (ip,subnet,gateway,dns) terug geven. Wanneer je de tuple als parameter meegeeft, wordt het netwerk volgens deze gegevens ingesteld.
    ⇒ Voorbeeld: print(“Netwerk configuratie:”,wlan.ifconfig())

Time

Detime bibliotheek voorziet in een aantal funkties om de huidige datum en tijd te achterhalen, het meten van tijdintervallen en voor vertragingen te genereren.

  • time.sleep: time.sleep(seconds)
    Deze funktie genereert een uitvoerings pauze van het aantal opgegeven seconden 3). In veel gevallen kan hier een gebroken getal (float) opgegeven worden. Echter, voor sommige boards kun je alleen gele getallen (integer) opgeven, zodat je daar met de funktie “sleep_ms” aan de slag moet.
    ⇒ Voorbeeld: sleep(0.2)

Select

Deselect bibliotheek implementeert een deel van de gelijknamigeCPython bibliotheek. Ze verzorgt de afhandeling van gebeurtenissen (event) vanuit een of meerdere streams.

  • select.poll: select.poll()
    Deze funktie creëert een nieuwe instantie van de poll class4). Na het aanmaken van een poll object, zal dit object nog geïnitialiseerd moeten worden met de select.poll() functie.
    → Voorbeeld: poller = select.poll()
  • poller = select.poll()
  • poller.register(s_sock, select.POLLIN)
  • res = poller.poll(1)

Socket

Desocket bibliotheek verzorgt de toegang met een BSD socket 5) interface.

  • socket.socket: class socket.socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP, /)
    Deze constructor definieert een socket opject, gebruikmakende van de gegeven adres familie, socket type en protocol nummer. Merk op dat het protocol nummer meestal niet verplicht (en zelfs niet gewenst) is! Het sock type zal het benodigde protocol automatisch selecteren.
    ⇒ Voorbeeld: server_socket=socket.socket(socket.AF_INET,socket.SOCK_STREAM)
  • accept: socket.accept()
    De method accepteert een connection, de socket wordt aan een IP adres verbonden en zoekt voor een connectie. Er wordt een tuple terug gegeven (con, addr), waarbij con het socket object geeft en addr het verbonden ip-adres waarmee verbonden is.
    ⇒ Voorbeeld: connection,address=server_socket.accept()
  • bind: socket.bind(address)
    De method verbindt de gedefinieerde socket met een IP adres. Uiteraard mag deze verbinding nog niet bestaan. Wanneer je als opgegeven adres een lege string (“”) opgeeft, zal de socket door machines met elk IPv4 adres benaderd kunnen worden.
    ⇒ Voorbeeld: server_socket.bind(('',80))
    Meer informatie:https://docs.python.org/3/howto/sockets.html
  • close: socket.close()
    De method sluit de socket en geeft alle daarvoor gebruikte processen vrij. Te andere kant krijgt een EOF 6) indikatie (indien het gebruikte protocol dit ondersteund). Geadviseerd wordt om een socket te sluiten, zodra je klaar bent met deze socket.
    ⇒ Voorbeeld: connection.close()
  • listen: socket.listen([backlog])
    Deze method definiëert het aantal nog niet geaccepteerde verbindingen, die verbonden mogen worden. De optionele parameter moet minimaal 0 zijn, een negatief getal zal als nul gezien worden. Wanneer de parameter niet opgegeven wordt, bepaalt python zelf hoeveel verbindingen realistisch toegestaan zijn
    ⇒ Voorbeeld: server_socket.listen(5)
  • recv: socket.recv(bufsize)
    Deze method simpelweg ontvangt data van de socket, waarbij de parameter het maximaal aantal karakters aangeeft, wat in een keer ontvangen kan worden.
    –> Voorbeeld: request=str(connection.recv(1024))
  • send: socket.send(bytes)
    De method stuurt data naar de socket, welke verbonden moet zijn met een remote socket ('n ander device). De method geeft het aantal verzonden byte terug.
    ⇒ Voorbeeld: connection.send(“HTTP/1.1 200 OK\n”)
  • sendall: socket.sendall(bytes)
    Deze method stuurt alle data in een keer via blokken naar de socket. Uiteraard dient deze socket weer verbonden te zijn met een remote socket. Het is niet gedefiniëerd wat sendall met non-blocking sockets 7), waardoor er geadviseerd wordt om de send method te gebruiken binnen micopython!
    ⇒ Voorbeeld: connection.sendall(response)

Uasyncio

Evenals voor select, ondersteunt de uasyncio bibliotheek 8) een deel van de gelijknamigeCPython bibliotheek. De bibliotheek plant (schedules) taken en voert deze uit (run).

  • neopixel_task = loop.create_task(start_neopixel_loop(np))
  • await uasyncio.sleep_ms(100)
  • loop.run_until_complete(run(server_socket, loop, np, np_state))
  • loop = uasyncio.get_event_loop()
1)
Een RGBW led heeft een extra warm-witte led, waardoor je een subtielere kleur reeks kunt krijgen. In dat geval heb je dus 32 bits per led/element nodig
2)
De meeste netwerk methods vereisen een aktief netwerk interface
3)
Let op: bij de sleep() funktie wacht het programma de opgegeven tijd en doet dan ook verder niets !
4)
Een poll class object kan alleen via de select.poll() funktie gecreëerd worden!
5)
Een socket kun je in het Nederlands het beste vertalen als TCP/IP verbinding, maar ik zal in de uitleg het woord socket blijven gebruiken
6)
EOF: End Of File
7)
Non-blocking sockets zij sockets waarvoor niet gewacht wordt totdat er data verstuurd of ontvangen is.
8)
uasyncio staat voor “Asynchronous I/O scheduler”
program/python/libraries.txt · Laatst gewijzigd: 2024/04/08 15:05 door sbczobbeheerder