Appendix¶

Creating the SD Card¶

Applied Brain Research uses a custom SD card image to run our bitstreams on the DE1-SoC board. Our SD card image uses the standard DE1-SoC 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_DE1_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_DE1_vX.Y.Z.img of=/dev/sde bs=1M 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_DE1_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_DE1_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_DE1_vX.Y.Z.img of=/dev/disk5 bs=1M 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 DE1-SoC¶

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. You must explicitly supply a cipher or the board will reject the connection!

To copy files to the board from the computer:

scp -c aes256-ctr <file_on_pc> root@<board-ip-address>:<absolute/destination/path>

For example:

scp -c aes256-ctr script.py [email protected]:/home/root

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.236 to the DE1-SoC 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). This system uses connman to manage the Ethernet interface.

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 MAC address of the DE1-SoC board is assigned when the board is booted. If there is no pre-set value, it will be randomly assigned. For this reason, Applied Brain Research sets the MAC address to decafec0ffee by default but this can be changed if necessary and may vary depending on your board configuration. If you see a different interface name use that instead.

Caution

If multiple boards are used on the same network they should have different MAC addresses. See Changing the Board MAC Address for how to do this.

Assigning the Board a Static IP¶

With the Ethernet cable connected, do the following from the board’s UART terminal:

Run connmanctl services. You should see an entry:

*AO Wired                ethernet_<MAC-address>_cable

We use the connman config command to set the IP address:
```
connmanctl config ethernet_<MAC-address>_cable \
   --ipv4 manual <ip_address> <netmask> <gateway>
```
For example:
```
connmanctl config ethernet_decafec0ffee_cable \
   --ipv4 manual 10.162.177.236 255.255.255.0 10.162.177.1
```
Note

The <netmask> will almost always be 255.255.255.0 but the <ip_address> and <gateway> can vary.

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).
Run ifconfig | grep "inet addr" to see if the change was made

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 a DNS server list.

Set the DNS server with:

connmanctl config ethernet_<MAC-address>_cable  \
   --nameservers 8.8.8.8

Assigning the Board a Dynamic IP¶

With the Ethernet cable connected, do the following from the board’s UART terminal:

Run connmanctl services. You should see an entry:

*AO Wired                ethernet_<MAC-address>_cable

We use the connman config command to opt for DHCP to acquire the IP address:

connmanctl config ethernet_<MAC-address>_cable --ipv4 dhcp

For example:

connmanctl config ethernet_decafec0ffee_cable --ipv4 dhcp

Run ifconfig | grep "inet addr" to see if the change was made. You should see that the 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.

Changing the Board MAC Address¶

In order to change the MAC address, you will need to modify the low-level U-BOOT configuration. This may seem daunting, but it is an easy process!

Note

If you change the board MAC address, you will need to set the board static IP again. See Assigning the board a static IP.

Connect to the board via UART.
To access the boot menu you must interrupt the boot sequence:
1. While still connected via UART, reboot the board with shutdown -r now or by using the power button. You will see lots of boot checks being printed to the UART terminal.
2. Eventually you will see Hit any key to stop autoboot with a countdown. Before this countdown reaches 0 and the board boots, press any key to interrupt the boot sequence. This will bring you to the U-BOOT menu. The terminal prompt should read SOCFPGA_CYCLONE5 #.
Set the MAC address with setenv ethaddr 00:11:22:33:44:55.

Note

You can set your MAC address to be anything you like following this format. The MAC address format is always 6 pairs of hex digits (0-9, a-f).
Check the MAC address has been set with print ethaddr.
Once you are happy with the MAC address, save it with saveenv.
Boot the board with boot.
Once booted, login and confirm the change has taken effect. Run ifconfig and observe the HWaddr entry for eth0. This should be the MAC address that was just set.

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	1k	16k

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.