Note

This documentation is for a development version. Click here for the latest stable release (v0.3.2).

Connecting PYNQ

Now that the board is setup we need to connect to it from the computer. This can be done in two ways, either via UART using the USB cable, or via SSH over an Ethernet cable. We prefer SSH for it’s ease of use, however UART is a safe fallback as it does not depend on the board having a valid network configuration.

UART

UART is a way for the board and host computer to communicate via a serial communication protocol over USB. For the PYNQ board, UART is primarily used to gain direct terminal access to the hardware boot menu options, or to the operating system installed on the microSD card.

The settings used for the serial communication on the board are:

  • 115200 BAUD

  • 8 data bits

  • 1 stop bit

  • no parity

  • no flow control (neither hardware nor software)

Upon a successful connection to the board, you will be presented with the OS login terminal screen. By default, the NengoBrainBoard PYNQ SD image is shipped configured to use the xilinx user, with xilinx as the password.

Linux

This guide will use minicom as the terminal emulator. It can be installed easily through your operating system’s package manager (e.g., sudo apt install minicom).

  1. If the board’s Micro-USB UART cable is already connected to your computer, disconnect it.

  2. Reconnect the Micro-USB UART cable and run dmesg | tail in a terminal. One of the messages should resemble “FTDI USB Serial Device converter now attached to ttyUSB0” which indicates the name of the device as ttyUSB0.

  3. Setup minicom:

    1. Run minicom as root, sudo minicom -s.

    2. Use the arrow keys to select Serial port setup and press Enter.

    3. Press A to change the Serial Device to /dev/ttyUSB0, where ttyUSB0 is the name found above. Press Enter. to confirm.

    4. Press E, then press E again to select 115200 and press Q to select 8-N-1. Press Enter to confirm

    5. Ensure Hardware Flow Control and Software Flow Control are both No. Press F or G respectively to toggle the setting. Press Enter to confirm.

    6. (Optional) Press Enter again to return to the main menu. Navigate to Save setup as dfl and press Enter to save these settings as default.

  4. Once you see the minicom welcome screen press Enter and you should see the Ubuntu terminal screen.

  5. You should now be connected to the board. Login to the Ubuntu operating system on the board. The default username is xilinx, and the default password is xilinx.

Note

If you saved these settings as default, you can connect to the board with sudo minicom now without navigating the settings menu. To exit minicom press CTRL+A then X.

Note

It is also possible to use PuTTY to establish the serial communication. Simply install PuTTY (e.g., with sudo apt install putty), and follow the instructions listed in the Windows section below. Be sure to use the device name identified above (e.g., /dev/ttyUSB0) for the port name.

Windows

First we will need a terminal emulator, we suggest using PuTTY. You can download PuTTY here.

  1. Ensure the board’s Micro-USB UART cable is connected to your computer and the board is powered on.

  2. Determine the COM port the board is using:

    1. From the Windows Start menu, open up the Control Panel. In Windows 10, you can search the Start menu for “Control Panel” to find it.

    2. Within the Control Panel, click Hardware and Sound.

    3. Under Devices and Printers group, click Device Manager.

    4. In the Device Manager, expand the Ports group. There, you should see a listing like USB Serial Port (COM<X>). If you do, the serial port to use is COM<X> (e.g., COM3).

  3. Open PuTTY, you should be on the Session tab (the first item in the menu on the left).

  4. Select Serial from Connection group in the menu on the left (it should be the last entry).

  5. Enter the serial port identified above into the Serial line to connect to text box.

  6. Enter the configuration noted above.

  7. Return to the Session tab by clicking the first item in the menu on the left.

  8. Select Serial as the Connection type (The default should be SSH).

  9. (Optional) Enter in a name in the text box under Saved Sessions, then press the Save button to save the connection configuration for use in the future.

  10. Click the Open button to connect to the board.

  11. You should now be connected to the board. Login to the Ubuntu operating system on the board. The default username is xilinx, and the default password is xilinx.

Note

If you have saved the connection configuration in the steps above, you can load this configuration by clicking the name, then pressing the Load button. Next, click the Open button to open the loaded configuration without having to re-enter all of the connection details.

Mac

This guide will use screen as the terminal emulator.

  1. If the board’s Micro-USB UART cable is already connected to your computer, disconnect it.

  2. Open a terminal and run ls /dev/cu.usbserial-* to get a list of connected devices.

  3. Connect the board to your computer with the USB cable.

  4. Re-run the ls /dev/cu.usbserial-* and compare it to the list obtained in the previous step. The board’s USB serial connection should be listed (as new entries) and should appear as cu.usbserial-XXXXXXXX where XXXXXXXX are a bunch of hexadecimal numbers.

    Note

    If more than one device appears in the USB serial device list, the device you want is most likely the device with the larger hexadecimal number.

  5. Run screen /dev/cu.usbserial-XXXXXXXX 115200 (where cu.usbserial-XXXXXXXX is the name identified above, and 115200 is the serial baud rate)

  6. screen should start when the command above is executed. If the terminal window is blank (no text is visible), press ENTER a few times to get the login prompt. Note that any connection error messages will appear at the bottom of the terminal window.

  7. You should now be connected to the board. Login to the Ubuntu operating system on the board. The default username is xilinx, and the default password is xilinx.

Note

To exit the screen session, press CTRL+A, type :quit, then press ENTER.

SSH

Ensure that the board is connected to your computer or to the same network as your computer via Ethernet. Keep in mind that the IP addresses of your computer and the board must be in the same subnet. Typically, this means that the first three numbers of the board’s IP address must match that of your computer’s IP. For example, both board and computer have IP addresses starting with 10.162.177.XXX.

The board is shipped with a default static IP address of 10.162.177.99. Once you assign your computer a static IP in this subnet, you should be able to easily connect to the board! To assign your computer a static IP, refer to the Giving your Computer a Static IP section for instructions.

Note

You may need administrative (or sudo) privilege to change Ethernet settings on your computer.

Note

If the IP address of your computer cannot be changed for a specific reason (e.g., you do not have administrative access to your computer, or you prefer not to change the network configuration of your computer), the board’s IP can be changed to match the network settings of your computer. See the Assigning the Board a Static IP section for instructions.

The instructions below outline how to set up the SSH connection using various operating systems. In these instructions, the board IP address is assumed to be unchanged from the default.

Upon a successful connection to the board, you will be presented with the OS login terminal screen. By default, the NengoBrainBoard PYNQ SD image is shipped configured to use the xilinx user, with xilinx as the password.

If this is your first time attempting an SSH connection to the board after modifying the network properties of your computer (or the board), it is advisable to check if the board is reachable from your computer by using the ping command from a terminal. Assuming 10.162.177.99 is the board’s IP address, do ping 10.162.177.99. If a communication between the board and PC can be established, you will see the ping command report a non-zero number of bytes being received from the board’s IP.

Linux & Mac

On the Linux or Mac platforms, an SSH connection with the board can be established using the built-in ssh command.

  1. In a terminal, try connecting to the board with ssh xilinx@10.162.177.99.

  2. It is recommended to setup an ssh configuration to streamline connecting and transferring files going forward.

    1. Navigate to your home directory with cd and create a directory called .ssh with mkdir .ssh.

    2. Move to that new directory with cd .ssh and create a new file called config with touch config.

    3. Edit this file and add the following lines:

      Host NengoBrainBoard
   HostName 10.162.177.99
   User xilinx

    4. You can now connect to your board with ssh NengoBrainBoard.

  3. You should now be connected to the board. Login to the Ubuntu operating system on the board. The default username is xilinx, and the default password is xilinx.

Note

Disconnect your SSH session by press CTRL+D, or by using the exit command.

Windows

To use SSH in Windows, you will need a terminal emulator. We suggest using PuTTY, which you can download PuTTY here.

  1. Open PuTTY, you should be on the Session tab (the first item in the menu on the left).

  2. Select SSH as the Connection type (this should be the default selection).

  3. Enter xilinx@10.162.177.99 as the Host Name.

  4. Leave the Port as the default value of 22.

  5. (Optional) Enter in a name in the text box under Saved Sessions, then press the Save button to save the connection configuration for use in the future.

  6. Click Open.

  7. You should now be connected to the board. Login to the Ubuntu operating system on the board. The default username is xilinx, and the default password is xilinx.

Note

If you have saved the connection configuration in the steps above, you can load this configuration by clicking the name, then pressing the Load button. Next, click the Open button to open the loaded configuration without having to re-enter all of the connection details.

Connecting the Board to the Internet

It is not necessary to connect the board to the internet in order to use it but it can be useful for development when updating and installing packages. Connecting the board to the internet can be done either by using a network router or network switch, or by using your computer’s internet connection.

Via a Network Switch

If your computer is connected to the internet via a network switch, configure both your computer and the board to the subnet used by the switch. Then connect the board to the switch and you should have access to the internet. See Assigning the Board a Static IP for instructions on how to assign the board a static IP within the switch’s subnet.

Network Diagram:

Internet <--> Network Switch <-+-> Computer
                               |
                               +-> Board
                               |    ...
                               +-> Other Boards (Optional)

Note that for the board to connect to the internet, the subnet’s gateway IP and DNS server IPs need to be added to the static IP configuration See here for an example of how to do this. Check your computer’s internet network interface settings to obtain these values.

Via a Network Router

If your computer is connected to internet via a network router, it is advised to configure your router to automatically assign the board a static IP. Consult your router’s user manual for instructions on how to do that. Once that is done, follow the instructions in Assigning the Board a Dynamic IP to configure the board to use the router’s DHCP service to acquire its IP address. The board will then have access to the internet when plugged into the router.

Network Diagram:

Internet <--> Network Router <-+-> Computer
                               |
                               +-> Board
                               |    ...
                               +-> Other Boards (Optional)

Via a Computer

Connecting the board to the internet via your computer is possible, but only if your computer has more than one network interface. With multiple network interfaces, the typical setup is to use the Ethernet interface to connect to the board, and to use the alternate interface (usually a wireless adapter, but it could also be another Ethernet interface) to connect to the internet. Internet connection sharing works by forwarding network packets from your computer’s primary network interface (i.e., the network interface you use to connect to the internet) to the network interface you use to connect to the board.

Network Diagram:

Internet <--> Computer <--> Board

or

Internet <--> Computer <--> Network Switch <-+-> Board
                                             |    ...
                                             +-> Other Boards (Optional)

Linux (Ubuntu 14, 16 GUI)

Connecting the board to the internet via a Linux (Ubuntu) computer can be achieved using the built-in Internet Connection Sharing utility of the Ubuntu operating system. By default, the Ubuntu operating system will assign any device connected to the internal shared network the 10.42.0.XXX subnet. Note that the IP 10.42.0.1 will be allocated to your computer and should not be used for the board.

On the board:

On your computer:

  1. In the Ubuntu Search your computer menu, search for Network Connections, or, click on the networking icon in the task bar and select Edit Connections.

  2. In the Network Connections dialog box, select the network interface used to connect to the board and click Edit.

  3. Click on the IPv4 Settings tab and set the Method dropdown box option to Shared to other computers.

  4. Click Save, and the internet connection sharing should be enabled.

To test this out:

  1. On the board (via UART):

    1. Try to ping 10.42.0.1 (this is the IP of your Ubuntu computer on the internal shared network). If this doesn’t work, the board cannot communicate with your computer. Check that the network cable is connected properly.

    2. Try to ping 8.8.8.8. If this doesn’t work, the board cannot access the internet. Check that your computer is connected to the internet.

    3. Try to ping www.google.com (or your favorite website). If this doesn’t work, there is an issue with the board’s DNS configuration. Try manually entering 10.42.0.1 as a DNS server in the board’s network configuration (see Assigning the Board a Static IP), or try switching the board to using DHCP.

  2. On your Ubuntu computer, try to ping 10.42.0.2 (if you’ve changed the board’s IP address use that instead). If this doesn’t work and:

    1. You have configured the board to use a static IP, ensure that you use the board’s IP in the ping command. Additionally, check that the network cables are attached properly.

    2. You have configured the board to use a dynamic IP, connect to the board via UART, and do sudo ifconfig to identify what IP address the board has been assigned. Then use that in the ping command.

Linux (Generic)

Connecting the board to the internet via a Linux computer can also be done by done through the command line interface.

On the board:

  • Ensure that the board is assigned a static IP, or leave the default IP assignment shipped with the NengoBrainBoard SD image.

On your computer:

  1. Ensure that IP forwarding is enabled with:

    sysctl -w net.ipv4.ip_forward=1

  2. Setup IP table forwarding with:

    sudo iptables -t nat -A POSTROUTING -o <interface> -j MASQUERADE

    where <interface> is the network interface used to connect to the internet (e.g., wlan0).

  3. These settings will reset after a reboot, to make this change persistent look into iptables-persistent.

Note

Use ifconfig to see all interfaces, the one with an inet addr entry is the one connected to the internet.

To test this out:

  1. On the board (via UART):

    1. Try to ping 10.162.177.1 (use the IP address assigned to your computer). If this doesn’t work, the board cannot communicate with your computer. Check that the network cable is connected properly.

    2. Try to ping 8.8.8.8. If this doesn’t work, the board cannot access the internet. Check that your computer is connected to the internet.

    3. Try to ping www.google.com (or your favorite website). If this doesn’t work, there is an issue with the board’s DNS configuration. Try manually entering 8.8.8.8 as a DNS server in the board’s network configuration (see Assigning the Board a Static IP).

  2. On your Ubuntu computer, try to ping 10.162.177.99 (if you’ve changed the board’s IP address use that instead). If this doesn’t work, check that the network cables are attached properly.

Windows

Connecting the board to the internet via a Windows computer is achieved using the built-in Internet Connection Sharing utility of the Windows operating system. By default, the Windows operating system will assign any device connected to the internal shared network the following subnets:

  • Windows 7/8/10: 192.168.137.XXX

  • Windows XP: 192.168.0.XXX

Note that the IP XXX.XXX.XXX.1 (e.g., in Windows 10: 192.168.137.1) will be allocated to the Windows computer and should not be used for the board.

On the board:

On your computer:

  1. In the Start menu, click Control Panel. If you cannot find it, search for Control Panel in the Start menu.

  2. Under the Network and Internet group, click View network status and tasks.

  3. On the left-hand side menu, click Change adapter settings. This should present you with the list of network interfaces available to the Windows operating system.

  4. Look for the network interface that you use to connect to the internet (e.g, Wi-Fi). Right-click on that interface and select Properties.

  5. In the Properties window, click on the Sharing tab, and tick the Allow other network users to connect through this computer’s internet connection checkbox. From the Home networking connection dropdown menu, select the network interface used to connect to the board.

  6. Click OK. You should then see the network interface denoted as Shared.

To test this out:

  1. On the board (via UART):

    1. Try to ping 192.168.137.1 (this is the IP of your Windows computer on the internal shared network). If this doesn’t work, the board cannot communicate with your computer. Check that the network cable is connected properly.

      Note

      For Windows XP operating systems, the IP address of your Windows computer on the internal shared network is 192.168.0.1.

    2. Try to ping 8.8.8.8. If this doesn’t work, the board cannot access the internet. Check that your computer is connected to the internet.

    3. Try to ping www.google.com (or your favorite website). If this doesn’t work, there is an issue with the board’s DNS configuration. Try manually entering 192.168.137.1 (or 192.168.0.1 for a Windows XP computer) as a DNS server in the board’s network configuration (see Assigning the Board a Static IP), or try switching the board to using DHCP.

  2. On your Windows computer, try to ping 192.168.137.2 (if you’ve changed the board’s IP address use that instead). If this doesn’t work and:

    1. You have configured the board to use a static IP, ensure that you use the board’s IP in the ping command. Additionally, check that the network cables are attached properly.

    2. You have configured the board to use a dynamic IP, connect to the board via UART, and do sudo ifconfig to identify what IP address the board has been assigned. Then use that in the ping command.

Mac

Connecting the board to the internet via a Mac computer is achieved using the built-in Internet Sharing utility of the Mac operating system. By default, the Mac computer will assign any device connected to the internal shared network to the 192.168.2.XXX subnet. Note that the IP 192.168.2.1 will be allocated to the Mac computer and should not be used for the board.

On the board:

On your computer:

Enable internet sharing on your Mac computer by following the steps below:

  1. Open up the System Preferences

  2. Open up the Sharing options (search for “Sharing” if you are unable to locate it).

  3. In the Sharing options page, click on Internet Sharing from the menu on the left.

  4. Select the appropriate network interfaces for the Share your computer from dropdown menu and the To computers using checkboxes. The network interface that you use to connect to the internet (e.g., Wi-Fi) should be the Share your computer from option, while the network interface used to connect to the board (e.g., Ethernet) should be the To computers using option.

  5. Check the On checkbox beside the Internet Sharing menu item in the list of services to turn on internet connection sharing. You may have to confirm this action by informing your computer to Start the service when prompted to do so.

To test this out:

  1. On the board (via UART):

    1. Try to ping 192.168.2.1 (this is the IP of your Mac computer on the internal shared network). If this doesn’t work, the board cannot communicate with your computer. Check that the network cable is connected properly.

    2. Try to ping 8.8.8.8. If this doesn’t work, the board cannot access the internet. Check that your computer is connected to the internet.

    3. Try to ping www.google.com (or your favorite website). If this doesn’t work, there is an issue with the board’s DNS configuration. Try manually entering 192.168.2.1 as a DNS server in the board’s network configuration (see Assigning the Board a Static IP), or try switching the board to using DHCP.

  2. On your Mac computer, try to ping 192.168.2.2 (if you’ve changed the board’s IP address use that instead). If this doesn’t work and:

    1. You have configured the board to use a static IP, ensure that you use the board’s IP in the ping command. Additionally, check that the network cables are attached properly.

    2. You have configured the board to use a dynamic IP, connect to the board via UART, and do sudo ifconfig to identify what IP address the board has been assigned. Then use that in the ping command.