6.0 KiB
title | layout | tags | is_draft | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
000002 - How can I modify the ARTIQ settings on the controller? | article.liquid |
|
true |
Article #000002
How can I modify the ARTIQ settings on the controller?
There are two ways to modify the settings on your controller:
- With Ethernet connection: when your controller is connected to the network, use
artiq_coremgmt
. - 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
:
- Start the command with
artiq_coremgmt config write
. - For each setting with string-type input, add
-s <identifier> <input-value>
as an argument. - For each setting with file-type input, add
-f <identifier> <path-to-input-file>
as an argument. - 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:
- Start the command with
artiq_mkfs
. - For each setting with string-type input, add
-s <identifier> <input-value>
as an argument. - For each setting with file-type input, add
-f <identifier> <path-to-input-file>
as an argument. - 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
).