Examples

Koheron SDK V1 documentation. The V1 branch is recommended for new instrument development and remains under active development ahead of the major release. Boards currently ship with V0; build and install a V1 OS image to follow this workflow. V1 images do not support legacy V0 instruments.

The ALPHA250 FFT example includes an FPGA design, C++ drivers, Python clients and a web interface. Use make list to find examples for other boards.

Source layout

examples/alpha250/fft/
  config.mk
  memory.yml
  block_design.tcl
  fft.hpp
  fft.cpp
  web/

Source code:

Build the reference instrument

make -j CFG=examples/alpha250/fft/config.mk

Output: tmp/examples/alpha250/fft/fft.zip, also copied to tmp/alpha250/instruments/fft.zip for image builds. See host setup for build requirements.

Prepare the board with a V1 image

Boards ship with V0. Use a V1 image for development.

make -j CFG=examples/alpha250/fft/config.mk image

Output: tmp/examples/alpha250/fft/alpha250-fft.zip. Install the image on an SD card; it includes the FFT instrument.

Run on a board

make -j CFG=examples/alpha250/fft/config.mk HOST=192.168.1.100 run

run builds, uploads and starts the instrument, then streams logs. Ctrl+C stops the log stream and leaves the instrument running. Instrument changes do not require rebuilding the OS image.

What the example demonstrates

config.mk selects the board, FPGA constraints, cores, C++ drivers and web files:

NAME := fft
VERSION := 0.3.0
BOARD_PATH := $(SDK_PATH)/boards/alpha250

memory.yml defines memory regions, register names and parameters used by generated Tcl, C++ and device-tree files:

parameters:
  fclk0: 143000000
  adc_clk: 250000000
  dac_width: 16
  adc_width: 16
  n_adc: 2
  fft_size: 8192
  n_cycles: 1023
  cic_differential_delay: 1
  cic_decimation_rate: 500
  cic_n_stages: 6

The generated instrument archive contains:

runtime FPGA bitstream binary (.bit.bin)
device-tree overlay (pl.dtbo)
original Vivado bitstream (.bit)
compiled server executable (serverd)
generated driver JSON (drivers.json)
built web assets
version file

Create a new instrument from the example

make copy CFG=examples/alpha250/fft/config.mk DEST=examples/alpha250/my-instrument

copy sets NAME := my-instrument; the archive and stored instrument use this name. It refuses an existing destination or the source instrument's name.

Board settings, VERSION, driver names and shared SDK references are preserved. The API class remains FFT. Change hard-coded client instrument names, such as connect(host, 'fft'), to my-instrument.

make validate CFG=examples/alpha250/my-instrument/config.mk
make -j CFG=examples/alpha250/my-instrument/config.mk

Relationship with 0.x examples

V1 uses CFG=.../config.mk and memory.yml; 0.x uses CONFIG=.../config.yml. See the migration guide for porting.