We have recently configured a custom Kasli crate using bare boards directly from TechnoSystems and I thought it might be useful to document how we got them up and running as whilst there is some great documentation we got caught out by a few subtle steps.

1) Required hardware

Kasli + Sinara HW Boards
Ethernet to SFP adaptor (we used validated adaptors listed here https://github.com/sinara-hw/meta/wiki/SFP)
Digilent JTAG-HS2 Programmer (for Urukul CPLD) - https://store.digilentinc.com/jtag-hs2-programming-cable/
12V, 5A Power for Kasli and USBA to USB Micro for programming Kasli

2) Linux Setup
In order to enable building the boards we setup a Linux VM using Virtualbox (https://www.virtualbox.org) and Ubuntu 18.04 LTS with minimal install option selected. The Xilinx build tools are pretty greedy for hard disk space so you will need around 100 GB hard disk on the VM. Alternatively, just install ubuntu dual boot. If you use virtual box, ensure you download and install the Oracle Vmware extension pack to get the updated USB drivers.

3) Installing Nix and Artiq Developer Environment
Follow the steps in the Artiq manual (https://m-labs.hk/artiq/manual/installing.html#installing-via-nix-linux) to install Nix and setup crypotgraphic keys to install artiq. For the suggested script my-artiq-env.nix we found that we had to comment out (using #) the line
#(ps.matplotlib.override { enableQt = true; })

Once installed, now follow instructions to configure system in developer mode (https://m-labs.hk/artiq/manual/developing.html)

Create a development folder
$ mkdir ~/artiqDev
$ cd ~/artiqDev
Launch nix with git
$ nix-shell -p git

Download the following repositories

    $ git clone https://github.com/m-labs/artiq 
    $ git clone https://git.m-labs.hk/m-labs/nix-scripts 
    $ git clone https://git.m-labs.hk/M-Labs/sinara-systems

Create a script to launch nix in developer mode
$ nano artiqDev-env.sh
Copy the following code
$ nix-shell -I artiqSrc=~/artiqDev/artiq ~/artiqDev/nix-scripts/artiq-fast/shell-dev.nix
Modify permissions to allow running developer environment
$ chmod u+x artiqDev-env.sh
Now the developer environment can be launched in terminal from using
$ . ~artiqDev/artiqDev-env.sh

4) Installing Xilinx Vivado for Kasli

From the Xilinx webpage https://www.xilinx.com/support/download.html download Vivado Design Suite - HLx Editions - 2019.2 and choose file Xilinx Unified Installer 2019.2: Linux Self Extracting Web Installer. An account is required but this is free to sign up.
Once downloaded open a terminal, run the nix developer script and navigate to the downloads folder containing the Web Installer and launch Xilinx installer as root from terminal
$ sudo ./xsetup
A menu will appear - choose to install the Vivado Webpack and set the target directory to /opt/Xilinx - this takes a while.

5) Compiling custom Kasli gateware (standalone system)

To create custom gateware for Kasli, the first step is to create a device configuration file (your_variant.json) that defines the exact card configuration for your customised Kasli crate. Example files can be found in ~/artiqDev/sinara-systems/ which correspond to units created by m-labs.
Once defined, open a terminal in developer mode and run the following code (from the folder containing your *.json) to compile the gateware. Ensure your VM has been allocated as much processor/RAM as possible using the Virtualbox settings, for 8 Gb RAM and 4 cores this took around an hour.
$ python -m artiq.gateware.targets.kasli_generic your_variant.json
Once completed, the compiled code will be in ~/artiqDev/artiq_kasli/your_variant/
To flash the Kasli, connect USB cable to the front panel USB/JTAG and power up. If using a VM, you will need to manually transfer the USB from Windows to Linux using the Virtualbox Toolbar and selecting Devices --> USB --> FTDI Quad RS232-HS. Then from the developer terminal run
$ artiq_flash --srcbuild --dir ~/artiqDev/artiq_kasli/ --variant your_variant
Flashing takes around 10 minutes. To verify successful transfer, open a second terminal window and launch gtkterm as root
$ sudo gtkerm
From Toolbar select Configuration --> Port
- Port = /dev/ttyUSB2 (v1.1 hardware)
- Baud rate = 115200
- Parity = None
- Bits = 8
- Stopbits = 1
- Flow Control = none
Return to nix shell and restart Kasli
$ artiq_flash start
In gtkterm the Kasli boot messages will now appear, including the IP address.
Next, generate the device database device_db.py for artiq_run to work using
$ python -m artiq.frontend.artiq_ddb_template your_variant.json -o device_db.py
Finally, ensure the IP address in device_db.py matches that of the Kasli from above, and move the device_db.py file to your working artiq folder.

6) Compiling and Flashing Urukul

To build gateware for Urukul the Xilinx ISE package must be installed. From https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/archive-ise.html select 14.7, and download all 4 files listed.
Once downloaded, as before launch terminal and run developer script, navigate to downloads folder and run the installer as root
$ sudo ./xsetup
Ensure this installs to /opt/Xinlinx and select the Webpack option
Once installed, navigate to ~/artiqDev and donwload Urukul source
$ git clone https://github.com/quartiq/urukul
This will retrieve code for hardware v1.4 - for earlier hardware releases roll back, e.g. for v1.3.1
$ cd ~urukul
$ git checkout v1.3.1
To build the drivers, first link path to the Xilinx drivers and then run build
$ source /opt/Xilinx/14.7/ISE_DS/settings64.sh
$ make
This creates cpld gateware in folder build/urukul.jed. Note: If you get an error regarding migen try installing via the following:
$ sudo apt install python3-pip
$ pip3 install migen
To flash the Urukul, power the board via EEM to Kasli and connect JTAG-HS2 programmer to board. Instructions for doing this in linux using xc3sprog are here https://github.com/quartiq/urukul but a much easier method is to install the Digilent Adept 2 driver on windows https://store.digilentinc.com/digilent-adept-2-download-only/
Launch Adept 2, select "Initialise Chain" and it should show the CPLD (for v1.3 this is XC2C128). There is then the option to browse for file, select the urukul.jed built for your hardware, and then hit program - takes 10s and its done.