assembly/src/build_test_firmware.md

# Build and test firmware

## Operating hints and warnings

* 😡 **Always** use grounding strap during dis/assembly or other cards' physical operation
* 😡 **Always** power off devices before un/plugging
* 🧐 If needed to power-cycle the crate, wait at least 30 seconds before turning them on
* 🙅 Avoid the boards touching conductive materials - wires, metals. Use at
  least plastic ESD bags if you need the cards to be put at the desk or any other surface.
* 💁 Be gentle to the EEM ports and any other connectors. Support them when plugging, hold when unplugging
* 🙆 If you need to take the cards out, take them out one-by-one from the end, unplug EEM and cables
  if you feel high tension
* 🙆 Use dedicated power supplies for each crate, preferably given or equivalent to given by us
* 🙅 Avoid unnecessary inserts and pullouts, especially of MMCX cables

Failure to comply with this voids the warranty.

## Shipping hints and warnings

* 🙆 Leave the cards in the crate
* 🙆 Ensure screws are tight
* 🙆 Ensure cards are in card guides
* ⚠️ Remove any cables from front panels
* ⚠️ Remove SFP adapters and insert caps/stubs
* 💁 Also advised to put caps on SMA connectors
* ✅ Wrap each crate in the bubble wrap individually until you don't feel the edges of the crate
  (usually 10 layers of standard buble wrap)
* 🈁 Fill in the space around the crate in the box with foamy stuff

## Kasli standalone

### Checklist for Kasli

1. Build firmware (see commands below)
2. Flash firmware and settings
3. Test hardware with the PSU, which is going to be shipped
4. Create a flash-drive with `device_db.py` file for customers (FAT32)

### CLI commands - build and flash for Kasli

```shell
mkdir <variant>
cd <variant>/
nix develop github:m-labs/artiq\?ref=release-8#boards
# master/standalone only
artiq_mkfs -s ip 192.168.1.75/24 kasli.config
artiq_flash storage -f kasli.config
artiq_ddb_template -o device_db.py <variant>.json 
python -m artiq.gateware.targets.kasli <variant>.json 
artiq_flash --srcbuild -d artiq_kasli/<variant>/
artiq_rtiomap dev_map.bin
artiq_coremgmt config write -f device_map dev_map.bin
artiq_coremgmt reboot
```

## Kasli-SoC (zynq)

### Checklist for Kasli-SoC

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 with the PSU, which is going to be shipped
7. Create a flash-drive with `device_db.py` file for customers (FAT32)

### CLI commands - build and flash for Kasli-SoC

```shell
mkdir <variant>
cd <variant>/
nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-8
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-8"; 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 and connected)
artiq_coremgmt config write -f boot result/boot.bin
artiq_coremgmt reboot
artiq_rtiomap dev_map.bin
artiq_coremgmt config write -f device_map dev_map.bin
```

## Testing (common)

```shell
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 connect the card to the other ports until it gets working.~~
  resolved (hopefully)

## Master-satellite setups

1. Change `base` in JSON to the respective `master` or `satellite`, remove `core_addr` in satellites
2. Build and flash firmware for each crate with JSONs (see instructions above)
3. Create combined `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)
   ![Master-satellite connection](img/master_sat_connection.jpg)
5. Ethernet is needed only for master
6. Test hardware as it would be one crate