Getting Started

Installation

Download the NengoFPGA source code from github using git:

git clone https://github.com/nengo/nengo-fpga.git

or navigate to the repository and download the files manually. Once downloaded, navigate to the nengo-fpga folder in a terminal window and install with:

pip install -e ./nengo-fpga

Requirements

Configuration

NengoFPGA is the frontend that connects to one of many backend FPGA devices. You will need to have a supported FPGA board with access to ABR designs. Each FPGA board will have it’s own setup and configuration procedure outlined in it’s own documentation, however, the NengoFPGA frontend has its own configuration as outlined below.

FPGA Board Setup

Follow docs for your particular FPGA device:

NengoFPGA Frontend Config

The NengoFPGA default config file, fpga_config, is located in the root directory of nengo-fpga and contains example settings for your host machine as well as the FPGA board you are using. You can also create a copy in the directory in which your project files are located. Anything in square brackets (eg. [host]) is defining a new entry name and everything below that name up until the blank line defines parameters of that entry.

Host

First we will look at the host configuration; this is information about your computer and must be called [host]:

[host]
ip = 10.162.177.10

Make sure these lines are uncommented (remove the leading # and space so it appears as above). This is just an example value for ip, you will need to replace this with your computer’s actual IP address, see Finding your IP Address for instructions on finding your IP address.

Note

Your computer IP address will need to be in the same range as the board IP address, follow your board specific instructions to get the board IP and setup your computer IP before proceeding.

FPGA Board

The entries that define the FPGA board parameters have more values than the host entry, the name (eg. [pynq]) can be anything, though we recommend using a descriptive name such as [pynq] or [de1].

# Example DE1 FPGA board configuration
[de1]
ip = 10.162.177.236
ssh_port = 22
ssh_user = root
ssh_pwd =
remote_script = /opt/nengo-de1/nengo_de1/single_pes_net.py
remote_tmp = /opt/nengo-de1/params
udp_port = 0

# Example PYNQ FPGA board configuration
[pynq]
ip = 10.162.177.99
ssh_port = 22
ssh_user = xilinx
ssh_pwd = xilinx
remote_script = /opt/nengo-pynq/nengo_pynq/single_pes_net.py
remote_tmp = /opt/nengo-pynq/params
udp_port = 0

For whichever board you are using, make sure the lines in the appropriate sections are uncommented (remove the leading # and space so it appears as above). These default values should be correct unless you’ve modified the settings or installation of your FPGA board. These parameters are described here but modifications of these values will be described in the board-specific documentation.

  • ip: IP address of the FPGA board.
  • ssh_port: The port used to open SSH communications between the host and FPGA board.
  • ssh_user: SSH username to use to login to the board.
  • ssh_pwd: Password for ssh_user to use to login to the board. Note that the fpga_config file supports the use of SSH keys (see Generating and Using SSH keys) as an alternate form of authentication.
  • remote_script: The location of the communication script on the FPGA board.
  • remote_tmp: Temporary location used to store data as it is transferred between the host and FPGA board.
  • udp_port: The port used for UDP communications between the host and FPGA board.

Note

It should be noted that the FPGA board should be configured such that non-root users do not require a password to perform sudo commands. Refer to the respective FGPA board documentation for instructions on how to do this.

Usage

Note

Ensure you’ve configured your board and NengoFPGA as outlined in Configuration above.

For any questions visit the Nengo Forum.

Examples

NengoFPGA ships with a few example implementations in the nengo-fpga/docs/examples folder. These examples are designed to be used with Nengo GUI, so first we will install that.

  1. Install the GUI with pip install nengo-gui.
  2. In a terminal window, navigate to the nengo-fpga/docs/examples directory.
  3. Try running an example with nengo <file name> -b nengo_fpga. This should open the Nengo GUI interface in a browser and display the code on the right and a graphical representation on the left.
  4. Near the top of the file you should see --- BOARD SELECT ---, select the appropriate board here. (In fact, the de1 and pynq correspond to the headers in the fpga_config file).
  5. Click the play button in the bottom right to start the simulation. It may take several seconds to build the model and begin running.

Basic Use

This is an extension of Nengo core, networks and models are described using traditional Nengo workflow and a single ensemble will be replaced with an FPGA ensemble using the FpgaPesEnsembleNetwork:

import nengo
from nengo_fpga.networks import FpgaPesEnsembleNetwork

with nengo.Network() as model:

   ...

   fpga_ens = FpgaPesEnsembleNetwork('de1', n_neurons=50,
                                     dimensions=2,
                                     learning_rate=0,
                                     label='ensemble')

   ...

This is designed to work with Nengo GUI, however you can see Scripting below if you prefer not to use the GUI. To view and run your networks, simply pass nengo_fpga as the backend to Nengo GUI.

nengo <my_file.py> -b nengo_fpga

Scripting

If you are not using Nengo GUI you can use the nengo_fpga simulator in the scripting environment as well:

import nengo
import nengo_fpga

with nengo.Network() as model:

   ...

with nengo_fpga.simulator(model) as sim:
   sim.run(1)