assembly/src/build_test_firmware.md

# Build and test firmware

## Kasli standalone

### Checklist

1. Build firmware (see commands below)
2. Flash firmware and settings
3. Test hardware
4. Create a flash-drive with `device_db.py` file for customers (FAT32)

### CLI commands - build and flash

```shell
mkdir <variant>
cd <variant>/
nix develop github:m-labs/artiq\?ref=release-7
# master/standalone only
artiq_mkfs -s ip 192.168.1.75 kasli.config
artiq_flash storage -f kasli.config
artiq_ddb_template -o device_db.py <variant>.json 
python -m artiq.gateware.targets.kasli_generic <variant>.json 
artiq_flash --srcbuild -d artiq_kasli/<variant>/
```

## Kasli-SoC (zynq)

### Checklist

1. Build firmware (see commands below) for SD card variant
2. Copy `results/boot.bin` to the SD card
3. Insert SD card to the Kasli-SoC and boot
4. Change IP from the default one: `artiq_coremgmt -D 192.168.1.56 config write -s ip 192.168.1.75`
5. Reboot and check it works on new IP address
6. Test hardware
7. Create a flash-drive with `device_db.py` file for customers (FAT32)

### CLI commands - build and flash

```shell
mkdir <variant>
cd <variant>/
nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-7
artiq_ddb_template -o device_db.py <variant>.json 
nix build -L --impure --expr 'let fl = builtins.getFlake "git+https://git.m-labs.hk/m-labs/artiq-zynq?ref=release-7"; in (fl.makeArtiqZynqPackage {target="kasli_soc"; variant="[master, standalone, satellite]"; json=<full path to the json description>;}).kasli_soc-[master, standalone, satellite]-sd' 
# copy `results/boot.bin` to the SD card
# insert SD card to the Kasli-SoC and boot
artiq_coremgmt -D 192.168.1.56 config write -s ip 192.168.1.75 # or just place extra CONFIG.TXT near the boot.bin on SD card
# update firmware (alternative to copy to SD, if ARTIQ already running)
artiq_coremgmt config write -f boot result/boot.bin
# reboot via power supply
```

## Testing (common)

```
artiq_sinara_tester
```

Follow `artiq_sinara_tester` instructions for testing the hardware. For more detailed information, 
you can use this book's pages, or if there is no instruction for testing your hardware, please add them to this book.

### Known issues

* [artiq-zynq#197](https://git.m-labs.hk/M-Labs/artiq-zynq/issues/197) - some cards (Sampler, Mirny, Zotino and others)  
  do not work properly with some EEM ports. You might need to reconnect the card to the other ports until it gets working.

## Master-satellite setups

1. Change `base` in JSON to the respective `master` or `satellite`, add `"enable_sata_drtio": true` if needed to the master,
   remove `core_addr` in satellites
2. Build and flash firmware for each crate with JSONs (see instructions above)
3. Create composed `device_db.py`: e.g. `artiq_ddb_template -o device_db.py -s 1 <satellite1>.json -s 2 <satellite2>.json <master>.json`
4. Connect satellite crates to the master respective to their numbers via the fiber (see example picture)
   ![](img/master_sat_connection.jpg)
5. Ethernet is needed only for master
6. Test hardware as it would be one crate