mlabs-kb-cobalt/posts/000002.md

title	layout	tags	is_draft
000002 - How can I modify the ARTIQ settings on the controller?	article.liquid	sinara utilities ip routing idle_kernel kasli metlino sayma kc705 zc706	true

Article #000002

How can I modify the ARTIQ settings on the controller?

There are two ways to modify the settings on your controller:

1. With Ethernet connection: when your controller is connected to the network, use artiq_coremgmt.
2. With USB connection: when your controller is disconnected from the network, plug a USB cable to the front-panel microUSB-JTAG port and use artiq_flash.

The following table shows the identifiers and input types for a non-exhasutive list of commonly-used ARTIQ settings.

Setting	Identifier	Input
IPv4 address	ip	String, in w.x.y.z format
IPv6 address	ip6	String, in w:x:y:z format
Routing table	routing_table	Binary file, generated from artiq_route
Idle kernel	idle_kernel	Binary file (in ELF format), generated from artiq_compile
Clocking mode	rtio_clock	String, one of: i ("internal"), e ("external")

Preparing the routing table

To prepare new setting for the routing table, use the artiq_route utility. The basic commands for doing so are:

$ artiq_route <path-to-output-binary-file> init
$ artiq_route <path-to-output-binary-file> set ... ...

Consult this manual section for detailed information about the routing table, as well as this section for the usage of artiq_route.

Preparing the idle kernel

To prepare new setting for the idle kernel, use the artiq_compile utility. You would need to prepare an ARTIQ experiment Python script containing ARTIQ kernel code, which would then be statically-compiled to an ELF file. You would also need to properly prepare the device database file (e.g. device_db.py). The basic command for doing so is:

$ artiq_compile <path-to-input-experiment-script> -o <path-to-output-elf>

Note that the idle kernel loops until the controller exits the idle state. Consult this manual section for the usage of artiq_compile.

Special notes on other settings

rtio_clock

This is a configuration key providing the mode of clock synthesis on the Si5324 chip (if present). Its value determines how the RTIO clock is generated from external clocking:

• i (default value): The RTIO clock is an "internal" signal converted from the external clock at the Si5324.
• e: The RTIO clock is fed directly from an "external" source at matching RTIO frequency, done by bypassing Si5324.

This setting is effective only if the firmware is configured to operate with external clocking. If the firmware is configured to operate otherwise, since Si5324 must be used to convert the internal oscillator to the RTIO clock, rtio_clock is always effectively i ("internal"). See Note 7 of #000001 for technical details of Si5324 bypass.

Using artiq_coremgmt (with Ethernet connection)

When you use artiq_coremgmt to write the settings to the flash memory on the controller, make sure that the device database file (e.g. device_db.py) and the input files for settings with file-type input are properly prepared (see sub-sections above). Then, follow the basic steps below to construct the command running artiq_coremgmt:

1. Start the command with artiq_coremgmt config write.
2. For each setting with string-type input, add -s <identifier> <input-value> as an argument.
3. For each setting with file-type input, add -f <identifier> <path-to-input-file> as an argument.
4. If your device_db.py file is NOT located at the current working directory, add --device-db <path-to-device-db> as an argument. Afterwards, submit the command.

For example, to configure the IPv4 address and the routing table with a valid device_db.py located in the current directory, run the following command:

$ artiq_coremgmt config write -s ip 192.168.1.75 -f routing_table routing.cfg

The new settings will take effect at the next system boot (e.g. by power-cycling).

Using artiq_flash (with USB connection)

When you use artiq_flash to write to the flash memory on the controller, you should use artiq_mkfs to prepare a single flash image containing all target settings in advance. The basic steps to construct the command running artiq_mkfs are as follows:

1. Start the command with artiq_mkfs.
2. For each setting with string-type input, add -s <identifier> <input-value> as an argument.
3. For each setting with file-type input, add -f <identifier> <path-to-input-file> as an argument.
4. End the command with the path to the output file.

For example, to prepare the flash image (named settings.bin) for setting the IPv4 address and the routing table, run the following command:

$ artiq_mkfs -s ip 192.168.1.75 -f routing_table routing.cfg settings.bin

Once the flash image is prepared, use artiq_flash to write its content to the flash memory at the "storage" location by running:

$ artiq_flash -t <controller-type> storage -f <path-to-flash-image>

For Kasli variants, you can remove the -D <controller-type> argument from the command. Note that this command overwrites all bytes on the flash memory at the "storage" location up to the final byte of the flash image, ignoring the number of bytes currently occupied by each setting.

The new settings will take effect at the next system boot (e.g. by power-cycling, or using artiq_flash start).