PYNQ emulator

Content:

1. What is PYNQ emulator
2. How to use
2.1. Download the library and get started
2.2. Commands you may need
3. Known problems
4. Example code

Sisältö:

1. Mikä on PYNQ-emulaattori
2. Käyttöohje
2.1. Kirjaston lataaminen ja aloitus
2.2. Komentoja joita voit tarvita
3. Tunnetut ongelmat
4. Esimerkkikoodi

1. What is PYNQ emulator

About real PYNQ by Xilinx: https://www.pynq.io

The PYNQ emulator is a Python library programmed using tkinter. The emulator was made to simulate the functionalities of the original PYNQ and the Python library used by TUNI, showing a simulation of the led matrix, buttons, switches and light sensor of the Xilinx Zynq device.
The emulator project's Github page is https://github.com/Riku-S/led-matrix

1. Mikä on PYNQ-emulaattori

Oikeasta Xilinxin PYNQ:istä: https://www.pynq.io

PYNQ-emulaattori on Python-kirjasto, joka on ohjelmoitu tkinter-kirjoston avulla. Emulaattori on tehty simuloimaan oikean PYNQ:in toimintoja, ja siihen liittyvää, TUNI:n käyttämää Python-kirjastoa, näyttäen ruudun, jossa on simulaatio Xilinx Zynq laitteen ledimatriisista, napeista, vivuista ja valosensorista.
Projektin Github sivu on https://github.com/Riku-S/led-matrix

2. How to use

2.1. Download the library and get started:

Note: The following instructions assume you use PyCharm, since it's the coding IDE used by most of TUNI students.
To get started, run PyCharm as administrator. This is important if you have installed Python in a folder that requires admin priviliges for modications. Create a new project in PyCharm. Open Terminal tab from the menu in the bottom left of the window. Execute command pip install pynq-emulator in the terminal to download and install the pynq-emulator package.

Downloading packages with PyCharm is not the only way thoough, so if you use another IDE or want to use a better way to dowloading packages, learn about downloading packages with pip: Installing Packages --- Python Packaging User Guide

The emulator requires tkinter to work, and it usually comes with Python, but if you don't have it, follow the instructions: TkDocs - Tk Tutorial - Installing Tk

Import the contents in your code by writing from pynq_emulator.emulation import *, but remember that in the final product with an actual hardware, the import commands you should use are import tut.arduino_led_matrix as led_matrix, from pynq.lib import Button and from pynq.lib import Switch
You can write your own code as you would write it for PYNQ, or modify the example code in the end of this document, to get started. Run your code to see if everything works. Close the simulation from your coding IDE rather than by closing the window.

2.2. Commands and variables you may need:

pip install pynq-emulator Run the command in your coding environment's terminal, (or another command prompt, see Installing Packages --- Python Packaging User Guide) to download and install the emulator package.

from pynq_emulator.emulation import * Use the library in your python file.

led_matrix.clear() Set all the LEDs dark.
led_matrix.init() Always start your simulation with this!
led_matrix.read_sensor() Read the light sensor's value. In the simulation you can adjust it between 0 and 20000.
led_matrix.set_led_color(x: int, y: int, red: int, green: int, blue: int) Set a light level for the red, green and blue LED lights in the coordinates (x, y). The colors may have values between 0 and 255.

Button(id: int) Returns the button with the given index.
Button.read() Returns the state of the button, 0 or 1
Button.wait_for_value(value: int) Don't do anything before the button gets the value 0 or 1

Switch(id: int) Returns the switch with the given index.
Switch.read() Returns the state of the switch, 0 or 1
Switch.wait_for_value(value: int) Don't do anything before the switch gets the value 0 or 1

2. Käyttöohje

2.1. Kirjaston lataaminen ja aloitus:

Huomio: Seuraavassa osiossa oletetaan, että käytät PyCharmia, sillä suurin osa TUNI:n opiskelijoista käyttää sitä tehtävien tekoon.
Päästäksesi alkuun, käynnistä Pycharm järjestelmänvalmojana. Tämä on tärkeää, etenkin jos Python on asennettuna kansioon, jonka muokkaaminen vaatii järjestelmänvalvojan oikeuksia. Aloita uusi projekti PyCharmissa. Avaa Terminal välilehti ikkunan alhaalla vasemmalla olevasta valikosta. Suorita terminaalissa komento pip install pynq-emulator
ladataksesi ja asentaaksesi pynq-emulaator-kirjaston.

Paketteja voi ladata muutenkin, kuin PyCharmin kautta, joten jos käytät toista ohjelmaa, tai haluat käyttää pidemmän päälle parempaa tapaa ladata paketteja, lue pakettien lataamisesta pip:illä: Installing Packages --- Python Packaging User Guide

Emulaattori tarvitsee kirjaston tkinter toimiakseen, ja yleensä se tulee Pythonin mukana, mutta jos se puuttuu, seuraa ohjeita: TkDocs - Tk Tutorial - Installing Tk

Importtaa moduulin sisältö koodissa kirjoittamalla from pynq_emulator.emulation import *, mutta muista, että lopullisessa tuotteesssa oikealla laitteella, import-komentoihin kuuluu import tut.arduino_led_matrix as led_matrix, from pynq.lib import Button ja from pynq.lib import Switch
Voit kirjoittaa koodia niinkuin kirjoittaisit sitä PYNQ:ille, tai muokata esimerkkikoodia dokumentaation lopussa, päästäksesi alkuun. Aja koodisi nähdäksesi, että kaikki toimii. Sulje simulaatio mieluiten PyCharmin punaisesta neliöstä.

2.2. Komentoja joita voit tarvita:

pip install pynq-emulator Ohjhelmointiympäristön terminaalissa, (tai muussa komentotulkissa, katso Installing Packages --- Python Packaging User Guide) suoritettava komento, jolla voi ladata ja asentaa emulaattori-paketin.

from pynq_emulator.emulation import * Ota kirjasto käyttöön python-tiedostossa.

led_matrix.clear() Pimennä kaikki ledit.
led_matrix.init() Aloita simulaatio aina tällä komennolla!
led_matrix.read_sensor() Lue valosensorin arvo. Simulaatiossa voi säädellä sitä 0-20000 välillä.
led_matrix.set_led_color(x: int, y: int, punainen: int, vihreä: int, sininen: int) Aseta punaisen, vihreän ja sinisen valon määrä koordinaatteihin (x, y). Värien arvot tulee asettaa välille 0 ja 255.

Button(id: int) Palauttaa kyseisen numeroisen napin.
Button.read() Palauttaa napin tilan, 0 tai 1
Button.wait_for_value(arvo: int) Älä tee mitään ennen kuin nappi saa arvon 0 tai 1

Switch(id: int) Palauttaa kyseisen numeroisen vivun.
Switch.read() Palauttaa vivun tilan, 0 tai 1
Switch.wait_for_value(arvo: int) Älä tee mitään ennen kuin vipu saa arvon 0 tai 1

3. Known problems:

Repeated .read() and .wait_for_value() functions aren't necessarily the most accurate possible. For example, writing


if my_button.read(1):
	my_button.wait_for_value(0)

may soft lock the hardware PYNQ while it behaves in a more predictable way in the simulation.

Graphics can't always follow rapid changes in the led matrix.

Threading, which you will probably never use with this emulator, destroys the program easily.

Keep in mind that the testing process has been very shorthanded, since the programmer of the emulator doesn't own a PYNQ. The features are mainly made after the descriptions of the PYNQ-exercises. The error messages differ from the real device and may be caused by wrong reasons. For example, an earlier version of the emulator let you try to light up LEDs that wouldn't exist, without giving an error message, and continue the program, which is not the case in the real device.

If you notice something wrong yourself, or want to give feedback of any kind, please feel free to send mail at rikusalminen15@gmail.com. Feedback is very welcome.

Character functions aren't implemented.

3. Tunnetut ongelmat:

Peräkkäiset .read() ja .wait_for_value() funktiot eivät ole välttämättä tarkimpia mahdollisia. Esimerkiksi


if my_button.read(1):
	my_button.wait_for_value(0)

voi saada PYNQ:in jumiin, vaikka simulaatio käyttäytyisi arvattavammin.

Grafiikat eivät aina pysy nopean vaihtelun perässä.

Threading, mitä tuskin tulisit koskaan käyttämään pynq-emulaattorin kanssa, tuhoaa helposti ohjelman.

Pidä mielessä, että ohjelman testaaminen on ollut erittäin vajaata. Ominaisuudet on suurimmalta osin tehty PYNQ-tehtävien tehtävänantojen antamien kuvauksien perusteella. Virheilmoitukset ovat erit, kuin oikealla laitteella, ja saattavat seurata vääristä asioista. Esimerkiksi emulaattorin aiempi versio antoi käyttäjän yrittää sytyttää ledin matriisin ulkopuolelta antamatta virheilmoitusta ja jatkaen ohjelman suoritusta, eroten oikeasta laitteesta.

Jos huomaat jotakin olevan pielessä, tai haluat antaa mitä tahansa palautetta, lähetä viestiä osoitteeseen rikusalminen15@gmail.com. Palaute on erittäin tervetullutta.

Kirjainfunktiot eivät sisälly simulaattoriin.

4. example.py:

# PYNQ led matrix simulator example

# Remember not to import this in your final product
from pynq_emulator.emulation import *

# These would be imported instead. Don't import them in the emulation!
# import tut.arduino_led_matrix as led_matrix
# from pynq.lib import Button
# from pynq.lib import Switch

import time


def set_all_leds(red, green, blue):
    """ Set the color value to all the LEDs

    :param red: Red value between 0 and 255
    :param green: Green value between 0 and 255
    :param blue: Blue value between 0 and 255
    :return: None
    """
    for i in range(8):
        for j in range(8):
            led_matrix.set_led_color(i, j, red, green, blue)


def main():
    # Always remember to initialize the led matrix!
    led_matrix.init()

    button0 = Button(0)
    switch0 = Switch(0)

    # Let's first set all LEDs green

    red = 0
    green = 255
    blue = 0

    set_all_leds(red, green, blue)

    # Advance to the next step when switch 0 is turned on
    switch0.wait_for_value(1)

    # From this point on the LEDs are red
    red = 255
    green = 0

    # Stop the program by turning off the switch
    while switch0.read() == 1:

        # If button 1 is pressed, turn the LEDs magenta colored
        # (full red + full blue)
        if button0.read() == 1:
            blue = 255
        else:
            blue = 0

        set_all_leds(red, green, blue)

        # Add a little delay between checks
        time.sleep(0.1)

    # Ending the simulation doesn't shut down the LEDs in real life
    led_matrix.clear()


main()