Skip to content

libpynq - the C PYNQ library

The PYNQ board is an embedded system with a lot of input/output (I/O), such as LEDs, buttons, (optional) display, audio, ADC, UART, SPI, etc. The libpynq library allows you to use these interfaces in your C program.

The libpynq library must be downloaded (separately from the SD-card image) and then copied to the PYNQ board.

The following PYNQ libraries are available.

Which libpynq version you require depends on the course for which you use the PYNQ board.

Course Year Release & Version Documentation Comment
5EID0 2023/24 5EID0-2023-v0.3.0 here
5EWC0 2023/24 5EWC0-2023-v0.2.6 here Latest (IIC and run-on-boot)
5EWC0 2023/24 5EWC0-2023-v0.2.5 here Superseded (UART & GPIO)
5EWC0 2023/24 5EWC0-2023-v0.2.4 here Superseded (fixed PMOD)
5EWC0 2023/24 5EWC0-2023-v0.2.3 here Superseded (doc update)
5EWC0 2023/24 5EWC0-2023-v0.2.2 here Superseded (display support)
5EWC0 2023/24 5EWC0-2023-v0.2.1 here Superseded
5EWC0 2023/24 5EWC0-2023-v0.2.0 here Superseded
5EWC0 2023/24 5EWC0-2023-v0.1.0 here Superseded

The libpynq versions are hosted on the TU/e Sharepoint for which you may have to log in with your TU/e account. Click "Download" on the Sharepoint page, which will look something like this:
Onedrive

Install libpynq (only once)

We will now add the use of the libpynq library to access the LEDs and buttons of the PYNQ board.

  1. Download the version of the libpynq library on your laptop that is recommended for your course. Depending on your browser or operating system you may have downloaded a zip file (e.g. libpynq-5EWC0-2023-v0.2.5.zip) or it may have been expanded to a directory (e.g. libpynq-5EWC0-2023-v0.2.5). In the latter case, it's easier to rezip it now.
  2. Copy it to /home/student on the PYNQ board by dragging and dropping from your laptop to the Visual Studio Code's Explorer pane that shows the PYNQ files:
    Explorer Pane
  3. Log in (start a terminal) to the PYNQ board with Visual Studio Code, MobaXterm, or ssh.

  4. In the terminal on the PYNQ board, you can list the files in the directory that you are currently in with the ls ("list") command. It should show the zip file you've just copied to the PYNQ board. (You can also see it in Visual Studio Code's Explorer pane.)

    ℹ️ Information See the Linux page for an overview of commands such as ls.

  5. The zip file must be unzipped with unzip -DD -q libpynq-5EWC0-2023-v0.2.5.zip. This should result in a directory called libpynq-5EWC0-2023-v0.2.5. Check that it's in the directory that you are currently in with the ls command.

  6. Enter the directory by typing cd libpynq-5EWC0-2023-v0.2.5 (cd means "change directory") and type ls (list files).

    • Replace libpynq-5EWC0-2023-v0.2.5 with the filename of the version you downloaded! For example if you use v0.2.6 then type cd libpynq-5EWC0-2023-v0.2.6.

    • Pro tip: type cd libp and then press the tab key -- it will auto-complete the file name. This will save you a lot of typing.

  7. Type make install to prepare the library for use. This will result in a lot of output, which you can ignore.

    unzip
    ... lots more output ...
    unzip

    ℹ️ Information

    If the installation never finishes (it keeps producing lots of text on the screen for more than a couple of minutes) then you forgot the -DD flag on unzip. Remove the directory, unzip correctly, and run make install again.

Write & run a C program that uses the PYNQ board's I/O

We illustrate the use of the libpynq library with a C program that uses the PYNQ's LEDs. It uses leds_init_onoff to initialise the LEDs, green_led_onoff to switch one LED on or off, and sleep_msec to donothing for some milliseconds.

Using Visual Studio Menus

  • In the applications directory of the libpynq library, copy the template directory to a new directory myleds. You can do this using Visual Studio Code (copy by right-clicking in the Explorer pane, paste, rename by right-clicking on the copy). Creating the myleds directory Creating the myleds directory

Using the terminal

  • In the applications directory of the libpynq library, copy the template directory to a new directory myleds. You can do this in the terminal of Visual Studio Code (or MobaXterm or ssh) with the following commands: 
    cd libpynq-5EWC0-2023-v0.2.5/applications
cp -r template myleds
cd myleds

cd means change directory, cp means copy, and the -r option means recursive, i.e. copy the directory and everything in it.

To edit the file use the Explorer pane on the left hand side of Visual Studio Code (Explore; libpynq-2023-v0.2.4 ; applications ; myleds) and then open main.c.
Creating the myleds directory

  • Enter myleds and edit main.c to the following (you can copy & paste): 

    #include <libpynq.h>
int main(void) {
  pynq_init();
///// begin of new code that you have type in (or copy):
  leds_init_onoff();           // start using the LEDs
  green_led_onoff(0,LED_ON);  // switch LED 0 on
  sleep_msec(1000);            // wait for one second
  green_led_onoff(0,LED_OFF); // switch LED 0 off
  leds_destroy();              // stop using the LEDs
///// end of new code
  pynq_destroy();
  return EXIT_SUCCESS;
}

  • Compile the program by typing make.

  • Run the program by typing ./main. The first LED (0) should turn on and one second later turn off. (The terminal does not show any output.)
  • There are four green LEDs, numbered from 0 to 3 inclusive. See if you can modify the program turn all of them on in succession.

Compatibility of libpynq and PYNQ hardware (FPGA bitstream)

The PYNQ board is programmable in software with the libpynq library but also has hardware (FPGA) that is programmable with a so-called bitstream. The libpynq library and the bitstream must be compatible, see this page for more information.

Detailed libpynq documentation

Documentation of all libpynq versions is here.