Appendix¶

Creating the SD Card¶

Applied Brain Research uses a custom SD card image to run our bitstreams on the PYNQ board. Our SD card image uses the standard PYNQ SD image as a base and adds everything you need to run NengoFPGA. Download the latest NengoBrainBoard SD card image, and follow the instructions below to copy it onto a microSD card.

Note

Make sure you have a way to connect a microSD card to your computer, typically you will use a USB adapter or a built in SD card reader.

Linux¶

You will need administrative (sudo) privilege to write to the SD card.

In a terminal, navigate to the folder where the NengoBrainBoard SD image is saved and extract it by running:
```
unzip yyyymmdd_PYNQ_vX.Y.Z.img.zip
```
where yyyymmdd is a datestamp and X.Y.Z is the version number.
Find out the location of the SD card on the computer:
1. Before connecting the SD card run the lsblk command. The output will be a list of drives and their names (eg. sda or mmcblk0).
2. Connect the SD card and run lsblk again. There should be a new entry which is the name of the SD card. The location of the SD card will be this name in the /dev directory, for example /dev/sde.
If the operating system automatically mounted the SD card you will need to unmount the drive first. If the SD card was mounted you will see a filepath in the rightmost MOUNTPOINT column in the output of the lsblk command above. Run:
```
umount /dev/sde1
```
for each mounted partition where sde1 is the name of the mounted partition seen in the lsblk output. There may be more than one partition to unmount.
Write the SD image to the SD card by running (use the actual date and version for the SD image name):
```
sudo dd if=yyyymmdd_PYNQ_vX.Y.Z.img of=/dev/sde bs=4M oflag=sync status=progress
```
This will take several minutes.

Danger

If the name of your SD card is not /dev/sde be sure to replace /dev/sde with the name you found in Step 2 for the dd command. If the wrong name is specified the dd will overwrite data with potentially catastrophic results!

Windows¶

Extract the SD image from the compressed yyyymmdd_PYNQ_vX.Y.Z.img.zip archive using tools such as 7zip or winzip.
Download Win32 Disk Imager from sourceforge and extract the application from the archive.
Connect the SD card to your computer.
Launch Win32 Disk Imager by double clicking on the executable you extracted above.
For Image File, browse to the SD image you extracted above.
For Device, select drive letter of the SD card.
Be sure you selected the correct Device and click Write.

Danger

If the wrong drive is specified for Device, Win32 Disk Imager will overwrite data with potentially catastrophic results!

Mac¶

You will need administrative (sudo) privilege to write to the SD card.

In a terminal, navigate to the folder where the NengoBrainBoard SD image is saved and extract it by running:
```
unzip yyyymmdd_PYNQ_vX.Y.Z.img.zip
```
where yyyymmdd is a datestamp and X.Y.Z is the version number.
Find out the location of the SD card on the computer:
1. Before connecting the SD card, open a terminal and run the diskutil list command. The output will be a list of drives and their names (eg. /dev/disk0).
2. Connect the SD card and run the diskutil list command again. There should be a new entry, and this is the location of the SD card. (e.g., /dev/disk5)
The Mac operating system will have automatically mounted the SD card, so you will need to unmount the drive first. In the terminal, run:
```
diskutil unmountDisk /dev/disk5
```
where /dev/disk5 is the location of the SD card obtained above.
Write the SD image to the SD card by running (use the actual date and version for the SD image name):
```
sudo dd if=yyyymmdd_PYNQ_vX.Y.Z.img of=/dev/disk5 bs=4M oflag=sync
```
This will take several minutes.

Danger

If the name of your SD card is not /dev/disk5 be sure to replace /dev/disk5 with the name you found in Step 2 for the dd command. If the wrong name is specified the dd will overwrite data with potentially catastrophic results!

Copying Files to/from PYNQ¶

SCP (secure copy) is a convenient and secure way of transferring files to and from the PYNQ board. To use SCP, first ensure that you can connect the board via SSH.

Linux & Mac¶

SCP comes pre-installed on most Linux and Mac operating systems. To use SCP, simply open a terminal and use the scp command as shown below.

To copy files to the board from the computer:

scp <file_on_pc> xilinx@<board-ip-address>:<absolute/destination/path>

For example:

scp script.py [email protected]:/home/xilinx

If you setup the ssh config this can be simplified to:

scp <file_on_pc> NengoBrainBoard:<absolute/destination/path>

To copy files from the board to the computer, simply reverse the last two arguments:
```
scp NengoBrainBoard:<absolute/file/path> <destination/on/pc>
```

Windows¶

SCP is not natively included in the Windows operating system. However, it can be easily obtained by downloading WinSCP from here. WinSCP is a graphical interface to SCP, and you can choose to install it in Commander mode, where you are presented 2 panels (one for the local file system, one for the remote file system), or in Explorer mode, where you get one window per remote file system. The instructions below are for the Commander mode.

When you start WinSCP, you will be presented with a screen to configure the SSH connection details. Enter the SSH connection details for your board, and click Login to connect to the board.

Note

In WinSCP, you can save the board connection details to avoid having to fill them in again for future connections.

You will be presented with two panels upon successful connection to the board. The panel on the left is your local file system, and the panel on the right is the file system of the board.

To copy files to the board from the computer, simply navigate to the file and save locations on the board and computer, respectively; and drag the file from the right panel to the left panel.
To copy files from the computer to the board, simply navigate to the save and file locations on the board and computer, respectively; and drag the file from the left panel to the right panel.

Changing the Board IP Address¶

By default, the NengoBrainBoard SD image assigns the IP address 10.162.177.99 to the PYNQ board. However, depending on your network setup, it may be necessary to modify this setting. The instructions below will tell you how to configure the board to assign it a static IP or to obtain a dynamic IP from a DHCP server (e.g., a network router).

Note

Any modifications to the board’s network configuration must be done through the UART terminal interface, since the SSH connection requires a stable network setup.

Note

The network configuration files are edited using a built in text editor. In the instructions below, the text editor vi is used. To modify the contents of a file, press the i key. This should put vi in -- INSERT -- mode (indicated at the bottom of the terminal) which will allow you to insert and delete content like a typical text editor. Once you are done editing the network configuration files, press ESC to put vi into command mode, then type in :wq and press Enter to save changes to the file and quit vi.

If you have put vi into an unknown mode, and your key presses are not doing what you intend, press esc a few times to exit any current command, then use :q! followed by Enter to force quit without saving changes.

Assigning the Board a Static IP¶

On the board’s UART terminal:

Edit the eth0 file within the /etc/network/interfaces.d/ folder using the command sudo vi /etc/network/interfaces.d/eth0.

You should see an entry like this:

auto eth0:0
   iface eth0:0 inet static
   address 10.162.177.99
   netmask 255.255.255.0

Simply change the address entry to whatever you like.
Connect the board to the Ethernet cable (if not already done).
Restart the interface with sudo ifdown eth0:0 followed by sudo ifup eth0:0.
Confirm this worked by running ifconfig | grep "inet addr".

Note

If you assign the board a static IP, and it is not able to connect to the internet after following the steps here, you may need to also provide the gateway IP and a DNS server list.

The gateway IP is the IP address of the machine the board is connected to the internet through (it could be your computer, or a router), and is typically assigned the first IP address in your subnet (i.e., the last digit of the IP address is 1, e.g., 10.162.177.1).

The DNS server list typically contains the gateway IP, and 8.8.8.8.

The full network configuration then looks something like this:

auto eth0
   iface eth0 inet static
   address 10.162.177.99
   netmask 255.255.255.0
   gateway 10.162.177.1
   dns-nameservers 10.162.177.1 8.8.8.8

Assigning the Board a Dynamic IP¶

On the board’s UART terminal:

Edit the eth0 file within the /etc/network/interfaces.d/ folder using the command sudo vi /etc/network/interfaces.d/eth0.
Change the eth0:0 entry to this:
```
auto eth0:0
   iface eth0:0 inet dhcp
```
Connect the board to the Ethernet cable (if not already done).
Restart the interface with sudo ifdown eth0:0 followed by sudo ifup eth0:0.
Confirm this worked by running ifconfig | grep "inet addr". You should see that the eth0:0 interface has been assigned an IP in the dynamic subnet.

Caution

If you assign the board a dynamic IP, the may change whenever the board is powered off and on. To prevent this, consult your router or operating system manual to assign a static DHCP address to the board.

Giving your Computer a Static IP¶

The instructions below outline how to configure you computer to use the static IP 10.162.177.10, which is known to work with the default IP address that is shipped with the NengoBrainBoard SD image. Replace this IP address with one that reflects your board’s setup.

Warning

If your computer only has one Ethernet interface, giving your computer a static IP will enable it to communicate with the board, but will most likely break your connection to the internet. In such scenarios, it is advised to connect both the board and the computer to a network router, to provide both with an internet connection (see Via a Network Router).

Linux (Ubuntu 14, 16 GUI)¶

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.
In the Network Connections dialog box, select the network interface used to connect to the board and click Edit.
Click on the IPv4 Settings tab and set the Method dropdown box to Manual.
Beside the Addresses table, click Add. Then type in 10.162.177.10 for the Address column, and 255.255.255.0 for the Netmask column.
Click Apply to save your changes.

Note

To revert the static IP assignment, set the IPv4 Settings to Automatic (DHCP).

Linux (Generic)¶

On your computer, open a terminal and navigate to the /etc/network directory with:
```
cd /etc/network
```
As is good practice, let’s make a backup of our configuration just in case:
```
cp interfaces interfaces.bak
```
Check the name of your Ethernet adapter by running ifconfig. It will likely be the first entry with a name similar to eth0 or enp8s0. This guide assumes eth0 is being used, so please replace this with the name you found if it differs.
Now edit the interface file with:
```
sudo gedit interfaces
```
1. The file should look something like this:
```
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
```
2. Right now the Ethernet interface eth0 is configured to be dynamic (dhcp). This is what we want to be static. Change your file to look like this (the last four lines are the important bit):
```
auto lo
iface lo inet loopback

auto eth0
# iface eth0 inet dhcp
iface eth0 inet static
   address 10.162.177.10
   netmask 255.255.255.0
```
To see this change take effect, restart the network service by first shutting it down with sudo ifdown eth0 and then starting it back up with sudo ifup eth0.
Check if this was successful with ifconfig eth0 | grep "inet addr". Under the eth0 interface, you should see 10.162.177.10 listed.

Note

To revert these settings, simply copy the backup file from Step 1 back to the original file name. You can do this with:

cp -f interface.bak interfaces

Windows¶

In the Start menu, click Control Panel. If you cannot find it, search for Control Panel in the Start menu.
Under the Network and Internet group, click View network status and tasks.
On the lefthand side menu, click Change adapter settings. This should present you with the list of network interfaces available to the Windows operating system.
Look for the network interface that you use to connect to the board (e.g, Ethernet). Right-click on that interface and select Properties.
In the Properties window, click on the Networking tab, select the Internet Protocol Version 4 (TCP/IPv4) entry. Ensure that the checkbox is ticked, then click Properties.
Select Use the following IP address and enter IP address as 10.162.177.10. The subnet mask should be 255.255.255.0.
Tick the Validate settings upon exit box and click OK, and OK once again for the network interface’s Properties window.

Note

To revert the static IP assignment, select Obtain an IP address automatically in the Internet Protocol Version 4 (TCP/IPv4) properties window.

Mac¶

From the Apple menu, open System Preferences.
Click on Network and select the adapter connected to the board from the list of network interfaces on the left.
Under the Configure IPv4 dropdown select Manually.
Enter 10.162.177.10 as the IP Address.
Enter 255.255.255.0 as the Subnet Mask.
Click Apply to save your changes.

Note

To revert the static IP assignment, select Using DHCP from the Configure IPv4 dropdown.

Adding New NengoFPGA Users on the Board¶

If your system setup requires additional users (apart from the default xilinx user) to be added to the board’s operating system, they need to be added to the nengo_sudo group if they are being used to run NengoFPGA models. The steps to adding a new NengoFPGA user to the PYNQ board operating system are as follows:

SSH into the board using a superuser account (e.g., the xilinx user)
Add the new user:
```
sudo adduser <username>
```
Fill in the prompts for user information when requested.
Add the user to the sudo group:
```
sudo usermod -aG sudo <username>
```
Add the user to the nengo_sudo group:
```
sudo usermod -aG nengo_sudo <username>
```
Log out of the SSH session, and log back into the board using the newly created user account.
Test the user account with the following command. The command should switch the user account to the root user without prompting for a password:
```
sudo su
```

Note

Switch back from the root user by pressing CTRL+D or by using the exit command.

Maximum Model Size¶

The NengoFPGA design is fixed and therefore we must provision resources up front and as a result, we have specific upper bounds. The maximum model size values are summarized in the table below:

Neurons (N)	Dimensions (D)	N x D
16k (rounded to 16380)	1k (rounded to 1020)	32k (rounded to 32760)

Note

All three of these upper bounds must be respected. For example, a model with 10k neurons and 10 dimensions fits the first two bounds (N and D respectively) but is still infeasible to run on the FPGA since the NxD product, 100k, is larger than the provisioned NxD memory structures.