99 lines
6.0 KiB
Markdown
99 lines
6.0 KiB
Markdown
---
|
|
title: "000002 - How can I modify the ARTIQ settings on the controller?"
|
|
layout: article.liquid
|
|
tags: [sinara, utilities, ip, routing, idle_kernel,
|
|
kasli, metlino, sayma, kc705, zc706]
|
|
is_draft: 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:
|
|
|
|
```sh
|
|
$ artiq_route <path-to-output-binary-file> init
|
|
$ artiq_route <path-to-output-binary-file> set ... ...
|
|
```
|
|
|
|
Consult [this manual section](https://m-labs.hk/artiq/manual-beta/drtio.html#the-routing-table) for detailed information about the routing table, as well as [this section](https://m-labs.hk/artiq/manual-beta/utilities.html#drtio-routing-table-manipulation-tool) 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:
|
|
|
|
```sh
|
|
$ 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](https://m-labs.hk/artiq/manual-beta/utilities.html#static-compiler) for the usage of `artiq_compile`.
|
|
|
|
#### Special notes on other settings
|
|
|
|
##### <a id="rtio_clock">`rtio_clock`</a>
|
|
|
|
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](./000001.html) 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:
|
|
|
|
```sh
|
|
$ 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:
|
|
|
|
```sh
|
|
$ 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:
|
|
|
|
```sh
|
|
$ 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`). |