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

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.

    6 months later

    I've been following this post, trying to install an Urukul EEM into a test system in our lab. When I run the artiq_flash start command I get an error in the gtkterm readout, which is copied at the bottom of this post. This means I can't ping the Kasli or run any scripts.

    I have tried using the ubirmingham.json, uamsterdam.json and an edited usussex.json file to compile the gateware. This system was previously working with an old artiq-4.0 virtual machine.

    Did you see a similar error at any point in your installation or are there any additional steps that I need to take?

    Booting from flash...
    Starting firmware.
    [ 0.000009s] INFO(runtime): ARTIQ runtime starting...
    [ 0.003931s] INFO(runtime): software ident 6.7369.bff611a8.beta;usussex
    [ 0.010648s] INFO(runtime): gateware iden6.7369.bff611a8.beta;usussex
    [ 0.017376s] INFO(runtime): g level set to INFO by default
    [ 0.023101s] INFO(runtime): UART log level set to INFO by default
    [ 0.029485s] INFO(runtime::rtio_clocking): using internal RTIO clock (by deult)
    panic at src/libcore/result.rs:945:5: cannot initialize Si5324: "Si5324 misses clock input signal"
    backtrace for software vsion 6.7369.bff611a8.beta;usussex:
    0x400509b0
    0x4001fecc
    0x40003460
    0x4004b6d4
    0x400500f0
    halting.

    3 months later

    With a combination of WSL 2, Ubuntu 18.04 LTS and xming I was able to generate the gateware (from Windows) for Artiq 5.7. Generating the gateware takes about 10-15 minutes.

    Most of the steps are as above, here are the most important differences:

    Get WSL 2 (1 doesn't work). I can confirm that this works with Ubuntu 18.04.5 LTS.

    To install Vivado I used xming. After xming installation in Ubunut you have to execute

    export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

    ( https://superuser.com/questions/1476086/error-cant-open-display-0 ). I start xming with xlaunch with "no client" and "no access control".

    After running the toolchain I had to zip the files, otherwise I couldn't get the folder out of WSL. At the moment it is not possible to bridge a USB device to WSL. It might be possible to directly reference the WSL filesystem when flashing from windows, but I haven't tried that yet.

    Useful things:
    You can execute

    explorer.exe .

    inside WSL to open an explorer window. You can use /mnt/c/Users/... to reference files in Windows.

      Philipp To install Vivado I used xming

      You can perhaps run the installer in command line instead, which should not require X.

      With recent Vivado versions, this is what I am doing because their "unsupported Linux distribution" warning window crashes the GUI installer 🙄

          I thought this was how everybody does it. It's ./Xilinx_Unified_2020.1_0602_1208/xsetup -a XilinxEULA,3rdPartyEULA,WebTalkTerms -b Install -e 'Vitis Unified Software Platform' -l /srv/Xilinx/ (Vivado for earlier versions).

          3 months later

          Hi, thanks for the detailed instructions 🙂
          However, could you please correct the typo in the title. It would make it much easier to find this very interesting/important topic using the search.

          5 days later

          I've documented the workaround in the ARTIQ manual.

          Thanks @sb10q !

          And thanks to @jdp for detailing your steps to configure a Kasli Crate.

          a year later
          2 months later

          sb10q Hi, would you please refer me to the right place to find the corresponding procedure used by version 7.

          We have the afws account but what should we do if we'd like to compile the gateware ourselves since we have some customed boards to be connected to the Kasli.

            Interesting to hear about those custom boards. What are they? Do you have schematics/designs somewhere?

              sb10q No existing design for now. But the plan is to send some simple instructions to a customed AWG and make it work in a Urukul-like way.

                sb10q Are we still able to build the gateware by ourselves after ARTIQ version 7?

                  Yes, see the "Developing" section of the v7 manual.