Trouble shooting

It's easy to miss a step in the instructions, misconfigure hardware, or run into a software problem.

Have a look at the instructions again, perhaps you missed a step?
See if your question is answered in the list of common problems below.
Check with fellow students, the teaching assistants or lecturers of the course during the labs/practica.

Under normal circumstances the PYNQ should start up like this

Connect the PYNQ to your laptop.
Switch on the PYNQ. Check that the red power LED is on.
Wait until the green DONE LED turns on.

ℹ️ Information

This may take as long as 5 minutes when the SD card is first used (because it is uncompressing the file system).
If a display is used, then it should show the version of the SD card.
At this point the PYNQ is ready (has "booted") and you can log in to it from your laptop. You can now log in to the PYNQ board using Visual Studio Code, MobaXterm, or ssh.

The relevant LEDs, buttons, and jumpers are shown in the figure: Pynq-Z2

Common problems

Problem	Possible cause	Check #
General - what NOT to do		0
PYNQ / red power LED doesn't switch on	USB cable not plugged in	1
Green "done" LED doesn't switch on	USB not inserted well	2
	low laptop battery	7
Display doesn't show startup message	corrupt SD card	2
	low laptop battery	7
VScode / MobaXterm / ssh can't find PYNQ board	no USB connection	3
	no Ethernet connection	4
	unsupported adapter cable	5
VScode hangs finds PYNQ but doesn't stop initializing	reboot	8
VScode / MobaXterm / ssh finds PYNQ but can't login	wrong ssh information	6
	corrupt SD card	2
Weird Linux error messages	corrupt SD card	2
	low laptop battery	7
VScode debugging doesn't work (with libpynq)	missing Vscode extensions	9

Use the table of contents on the right to quickly jump to the right section.

0. What not to do!

Only use the micro-USB to supply power to the PYNQ board. Do not use the barrel plug unless specifically instructed to do so in your course. Never use the micro-USB and the barrel plug at the same time as this will damage your PYNQ board.
After switching off the PYNQ board, wait at least 10 second before switching it back on. Otherwise you run the risk of corrupting the SD card or damaging the PYNQ hardware
Do not pull out the SD card. To remove the SD card, push it in: it will then click and come out.

⚠️ Warning We've seen multiple PYNQ board with broken SD card slots due to mishandling. We cannot replace those boards.
Be gentle with the micro-USB cable connector, as it is fragile. Pull out the cable with care (aligned with the board, not perpendicular to it).
Never move the jumpers when the PYNQ is switched on, as this can damager the PYNQ hardware.
Never push the SD card in or out when the PYNQ is switched on, as this will corrupt the data (the "image") on it.
Preferably use the PYNQ board with your laptop on a power charger (i.e. not on battery power). When your laptop's battery is low the PYNQ board does not receive enough power, corrupting the SD-card image.

1. Check the power supply (USB cable & power jumper)

Power on the PYNQ board. Does the red power LED turn on? Preferably use the PYNQ board with your laptop on a power charger (i.e. not on battery power).
Power off the PYNQ board. Make sure the power-source-selection jumper is in the correct "USB" position as indicated in the image above. If not then the PYNQ doesn't receive power.

2. Check the SD card & boot-mode jumper

Make sure the boot-mode jumper is in the correct "SD" position as indicated in the image above.
Check that the micro-USB cable is plugged in well (see the connect) page. Switch on the PYNQ and wait for 5 minutes.
To check if the SD card is inserted correctly switch off the PYNQ before touching the SD card. Now check and switch the PYNQ back on.
Try a different SD card. Old SD cards often don't work well any more and can lead to not being to log in to the PYNQ board.

Does the PYNQ work with an SD card that has proven to be functional on other boards? If not, your SD-card image is corrupt or your SD card may be broken altogether. - If you buy your own SD card, ensure it has at least 32 MB. Make sure to buy a fast high-reliability card. Cheap SD cards are much slower (to flash and run Linux) and quickly become corrupt and fail. - Re-flash the SD card with a newly downloaded SD-card image. Don't forget to wait for the software to validate that the image was correctly flashed on the SD card. 1. Try a different PYNQ board with your SD card. Does the SD card work with a PYNQ board that has proven to be functional with another SD card? If yes, the your PYNQ board may be broken. This is very rare (a few out of the thousand boards that we've used), but can happen.

3. Check the USB connection between laptop and PYNQ board

If you've connected the PYNQ board to your laptop, but you can't log in to the PYNQ baord because Visual Studio Code, MobaXterm, or ssh doesn't see the PYNQ board. The first thing to check is if the USB connection works.

On Windows

Connect and switch on the PYNQ board. Wait until it has booted (the green DONE LED is on).
Open the Device Manager application. It is quickest to go to the windows menu and search for "Device Manager" as shown below.
Select "Network Adapters", which should show a device such as "ASIX AX88772C..." or something related to the Ethernet to USB converter you're using:

If it doesn't then your Ethernet to USB adapter is not supported and you need to use a different one. See the (Un)supported adapter cables page.
Select "USB", which should show a new USB device after connecting the PYNQ:

If it doesn't then your USB adapter is not supported and you need to use a different one. If it does, you can check if it's been installed properly by selecting the "General" tab. If under "Events" the device has been configured correctly and the parent device's adress ends in "tul", your board is connected properly. See the "(Un)supported USB cables" Section below. See the (Un)supported adapter cables page.

On macOS

Connect and switch on the PYNQ board. Wait until it has booted (the green DONE LED is on).
Open the System Information application. It is quickest to use Spotlight and search for "System Information". Otherwise open the System Settings application and select "General" then "About" then "System Report".
Select "Ethernet", which should show a device such as "Realtek":

If it doesn't then your Ethernet to USB adapter is not supported by macOS and you need to use a different one. See the (Un)supported adapter cables page.
Select "USB", which should show "TUL":

If it doesn't then your USB adapter is not supported by macOS and you need to use a different one. See the "(Un)supported USB cables" Section below. See the (Un)supported adapter cables page.
TODO add the command line commands to check
```
ipconfig getiflist
ipconfig getsummary en8
```
and how to interpret.

On Linux

Debug similar to the macOS instructions.

4. Check the Ethernet connection between laptop and PYNQ board

If the USB connection between the laptop and PYNQ board works, then the next thing to check is if the Ethernet connection works.

First, check that your Ethernet cable works (see 2 above).

When trying to log in, do the LEDs on the Ethernet connector on the PYNQ flash, or is the right LED always red? If they don't flash then the Ethernet connection may not be set up correctly.

This image shows that the Ethernet connection is not working (only the right LED is on and it's red): No Ethernet connection

Use ping to see if the Ethernet port is alive

Open a terminal (Terminal application on macOS or Powershell in Visual Studio Code) and run the ping command on your computer to see if the PYNQ's Ethernet port is alive: Output of the ping command

Debugging the Ethernet connection using the serial port

If your Ethernet connection does not work, then try to log in using the serial port.
If that works, then execute the following sudo mii-tool eth0 command on the PYNQ board. It should return "link ok":

If it returns eth0 no link then the Ethernet connection does not work. See the (Un)supported adapter cables Section below.

5. (Un)supported adapter cables

See the (Un)supported adapter cables page.

6. Wrong ssh hostname or user name

6A. Visual Studio Code

Check if the pynq profile you have configured via Remote-SSH: Open SSH Configuration File... uses the correct hostname and user name. If this is not the case, the board will prompt you for a password but will give an error message that the password is incorrect.
Try restarting the Visual Studio Code server. You can do this by opening the command palette in Visual Studio Code. On windows this can either be done by either pressing F1 or by typing Ctrl + Shift + P. On macOS use Command + Shift + p. Search for the option Remote SSH: Kill Local Connection Server for Host.

6B. MobaXterm and ssh

Check that the host name and user name are correct (see Starting MobaXterm for the first time or logging in using secure shell).

7. Low laptop battery

If when you try to execute a command on the Linux command line in the terminal, you get error messages such as I/O error or standard Linux commands such as ls cannot be found this is often due to the battery of your laptop running low. A lop battery results in the PYNQ board not receiving enough power, giving SD card errors. Power your laptop from a charger and reboot your PYNQ board. Hopefully, the SD-card image has not been corrupted.

8. Visual Studio Code hangs on initialization

If Visual Studio Code is hanging (e.g. on initializing the PYNQ board) then you may want to reboot the PYNQ board. To safely do this open a (Power)shell, login, and restart the PYNQ board with sudo reboot.

9. No Vscode extensions

If Visual Studio Code debugging doesn't work with programs that use libpynq then you may have forgotten step 3 "Install Visual Studio Code extensions on the PYNQ board" on the debugging C with libpynq page, especially the copying of the Visual Studio Code configuration files at the end. Without the libpynq-specific Visual Studio Code extensions, the debugging (and running) don't work. You can check this by opening Visual Studio Code and select "Terminal > Run Task"; you should see "libpynq Build".