Utilities¶
Local running tool¶
Local experiment running tool
usage: artiq_run [-h] [-v] [-q] [--device-db DEVICE_DB]
[--dataset-db DATASET_DB] [-e EXPERIMENT] [-o HDF5]
FILE [ARGUMENTS [ARGUMENTS ...]]
- Positional arguments:
file file containing the experiment to run arguments run arguments - Options:
-v=0, --verbose=0 increase logging level -q=0, --quiet=0 decrease logging level --device-db=device_db.py device database file (default: ‘%(default)s’) --dataset-db=dataset_db.pyon dataset file (default: ‘%(default)s’) -e, --experiment experiment to run -o, --hdf5 write results to specified HDF5 file (default: print them)
Remote Procedure Call tool¶
ARTIQ RPC tool
usage: artiq_rpctool [-h]
SERVER PORT {list-targets,list-methods,call,interactive}
...
- Positional arguments:
server hostname or IP of the controller to connect to port TCP port to use to connect to the controller - Sub-commands:
- list-targets
list existing targets
usage: artiq_rpctool list-targets [-h]
- list-methods
list target’s methods
usage: artiq_rpctool list-methods [-h] [-t TARGET]
- Options:
-t, --target target name
- call
call a target’s method
usage: artiq_rpctool call [-h] [-t TARGET] METHOD ...
- Positional arguments:
method method name args arguments - Options:
-t, --target target name
- interactive
enter interactive mode (default)
usage: artiq_rpctool interactive [-h] [-t TARGET]
- Options:
-t, --target target name
This tool is the preferred way of handling simple ARTIQ controllers. Instead of writing a client for very simple cases you can just use this tool in order to call remote functions of an ARTIQ controller.
Listing existing targets
The
list-targets
sub-command will print to standard output the target list of the remote server:$ artiq_rpctool hostname port list-targets
Listing callable functions
The
list-methods
sub-command will print to standard output a sorted list of the functions you can call on the remote server’s target.The list will contain function names, signatures (arguments) and docstrings.
If the server has only one target, you can do:
$ artiq_rpctool hostname port list-methods
Otherwise you need to specify the target, using the
-t target
option:$ artiq_rpctool hostname port list-methods -t target_name
Remotely calling a function
The
call
sub-command will call a function on the specified remote server’s target, passing the specified arguments. Like with the previous sub-command, you only need to provide the target name (with-t target
) if the server hosts several targets.The following example will call the
set_attenuation
method of the Lda controller with the argument5
:$ artiq_rpctool ::1 3253 call -t lda set_attenuation 5
In general, to call a function named
f
with N arguments named respectivelyx1, x2, ..., xN
you can do:$ artiq_rpctool hostname port call -t target f x1 x2 ... xN
You can use Python syntax to compute arguments as they will be passed to the
eval()
primitive. The numpy package is available in the namespace asnp
. Beware to use quotes to separate arguments which use spaces:$ artiq_rpctool hostname port call -t target f '3 * 4 + 2' True '[1, 2]' $ artiq_rpctool ::1 3256 call load_sample_values 'np.array([1.0, 2.0], dtype=float)'
If the called function has a return value, it will get printed to the standard output if the value is not None like in the standard python interactive console:
$ artiq_rpctool ::1 3253 call get_attenuation 5.0 dB
Static compiler¶
This tool compiles an experiment into a ELF file. It is primarily used to prepare binaries for the default experiment loaded in non-volatile storage of the core device.
Experiments compiled with this tool are not allowed to use RPCs, and their run
entry point must be a kernel.
ARTIQ static compiler
usage: artiq_compile [-h] [-v] [-q] [--device-db DEVICE_DB]
[--dataset-db DATASET_DB] [-e EXPERIMENT] [-o OUTPUT]
FILE [ARGUMENTS [ARGUMENTS ...]]
- Positional arguments:
file file containing the experiment to compile arguments run arguments - Options:
-v=0, --verbose=0 increase logging level -q=0, --quiet=0 decrease logging level --device-db=device_db.py device database file (default: ‘%(default)s’) --dataset-db=dataset_db.pyon dataset file (default: ‘%(default)s’) -e, --experiment experiment to compile -o, --output output file
Flash storage image generator¶
This tool compiles key/value pairs into a binary image suitable for flashing into the flash storage space of the core device.
ARTIQ flash storage image generator
usage: artiq_mkfs [-h] [-s KEY STRING] [-f KEY FILENAME] output
- Positional arguments:
output output file - Options:
-s=[] add string -f=[] add file contents
Flashing/Loading tool¶
ARTIQ flashing/deployment tool
usage: artiq_flash [-h] [-v] [-q] [-n] [-H HOSTNAME] [-J JUMP] [-t TARGET]
[-V VARIANT] [-I PREINIT_COMMAND] [-f STORAGE] [-d DIR]
[--srcbuild SRCBUILD]
[ACTION [ACTION ...]]
- Positional arguments:
action actions to perform, default: %(default)s - Options:
-v=0, --verbose=0 increase logging level -q=0, --quiet=0 decrease logging level -n=False, --dry-run=False only show the openocd script that would be run -H, --host SSH host where the development board is located -J, --jump SSH host to jump through -t=kasli, --target=kasli target board, default: %(default)s, one of: kasli sayma kc705 -V, --variant board variant -I=[], --preinit-command=[] add a pre-initialization OpenOCD command. Useful for selecting a development board when several are connected. -f, --storage write file to storage area -d, --dir look for files in this directory --srcbuild look for bitstream, bootloader and firmware in this ARTIQ source build tree
Valid actions: * gateware: write gateware bitstream to flash * bootloader: write bootloader to flash * storage: write storage image to flash * firmware: write firmware to flash * load: load gateware bitstream into device (volatile but fast) * start: trigger the target to (re)load its gateware bitstream from flash Prerequisites: * Connect the board through its/a JTAG adapter. * Have OpenOCD installed and in your $PATH. * Have access to the JTAG adapter’s devices. Udev rules from OpenOCD: ‘sudo cp openocd/contrib/99-openocd.rules /etc/udev/rules.d’ and replug the device. Ensure you are member of the plugdev group: ‘sudo adduser $USER plugdev’ and re-login.
Core device management tool¶
The artiq_coremgmt utility gives remote access to the core device logs, the Flash storage, and other management functions.
To use this tool, you need to specify a device_db.py
device database file which contains a comm
device (an example is provided in examples/master/device_db.py
). This tells the tool how to connect to the core device and with which parameters (e.g. IP address, TCP port). When not specified, the artiq_coremgmt utility will assume that there is a file named device_db.py
in the current directory.
To read core device logs:
$ artiq_coremgmt log
To set core device log level and UART log level (possible levels are TRACE
, DEBUG
, INFO
, WARN
and ERROR
):
$ artiq_coremgmt log set_level LEVEL
$ artiq_coremgmt log set_uart_level LEVEL
Note that enabling the TRACE
log level results in small core device slowdown, and printing large amounts of log messages to the UART results in significant core device slowdown.
To read the record whose key is mac
:
$ artiq_coremgmt config read mac
To write the value test_value
in the key my_key
:
$ artiq_coremgmt config write -s my_key test_value
$ artiq_coremgmt config read my_key
b'test_value'
You can also write entire files in a record using the -f
parameter. This is useful for instance to write the startup and idle kernels in the flash storage:
$ artiq_coremgmt config write -f idle_kernel idle.elf
$ artiq_coremgmt config read idle_kernel | head -c9
b'\x7fELF
You can write several records at once:
$ artiq_coremgmt config write -s key1 value1 -f key2 filename -s key3 value3
To remove the previously written key my_key
:
$ artiq_coremgmt config delete my_key
You can remove several keys at once:
$ artiq_coremgmt config delete key1 key2
To erase the entire flash storage area:
$ artiq_coremgmt config erase
You do not need to remove a record in order to change its value, just overwrite it:
$ artiq_coremgmt config write -s my_key some_value
$ artiq_coremgmt config write -s my_key some_other_value
$ artiq_coremgmt config read my_key
b'some_other_value'
ARTIQ core device management tool
usage: artiq_coremgmt [-h] [-v] [-q] [--device-db DEVICE_DB] [-D DEVICE]
{log,config,reboot,hotswap,profile,debug} ...
- Options:
-v=0, --verbose=0 increase logging level -q=0, --quiet=0 decrease logging level --device-db=device_db.py device database file (default: ‘%(default)s’) -D, --device use specified core device address instead of reading device database - Sub-commands:
- log
read logs and change log levels
usage: artiq_coremgmt log [-h] {clear,set_level,set_uart_level} ...
- config
read and change core device configuration
usage: artiq_coremgmt config [-h] {read,write,remove,erase} ...
- reboot
reboot the currently running firmware
usage: artiq_coremgmt reboot [-h]
- hotswap
load the specified firmware in RAM
usage: artiq_coremgmt hotswap [-h] IMAGE
- Positional arguments:
image runtime image to be executed
- profile
account for communications CPU time
usage: artiq_coremgmt profile [-h] {start,stop,save} ...
- debug
specialized debug functions
usage: artiq_coremgmt debug [-h] {allocator} ...
Core device RTIO analyzer tool¶
ARTIQ core device RTIO analysis tool
usage: artiq_coreanalyzer [-h] [-v] [-q] [--device-db DEVICE_DB]
[-r READ_DUMP] [-p] [-w WRITE_VCD] [-d WRITE_DUMP]
- Options:
-v=0, --verbose=0 increase logging level -q=0, --quiet=0 decrease logging level --device-db=device_db.py device database file (default: ‘%(default)s’) -r, --read-dump read raw dump file instead of accessing device -p=False, --print-decoded=False print raw decoded messages -w, --write-vcd format and write contents to VCD file -d, --write-dump write raw dump file
Note
The RTIO analyzer does not support SAWG.
Data to InfluxDB bridge¶
ARTIQ data to InfluxDB bridge
usage: artiq_influxdb [-h] [--server-master SERVER_MASTER]
[--port-master PORT_MASTER]
[--retry-master RETRY_MASTER] [--baseurl-db BASEURL_DB]
[--user-db USER_DB] [--password-db PASSWORD_DB]
[--database DATABASE] [--table TABLE]
[--pattern-file PATTERN_FILE] [--bind BIND]
[--no-localhost-bind] [--port-control PORT_CONTROL] [-v]
[-q]
- Options:
--server-master=::1 hostname or IP of the master to connect to --port-master=3250 TCP port to use to connect to the master --retry-master=5.0 retry timer for reconnecting to master --baseurl-db=http://localhost:8086 base URL to access InfluxDB (default: %(default)s) --user-db= InfluxDB username --password-db= InfluxDB password --database=db database name to use --table=lab table name to use --pattern-file=influxdb_patterns.cfg file to load the patterns from (default: %(default)s). If the file is not found, no patterns are loaded (everything is logged). --bind=[] additional hostname or IP address to bind to; use ‘*’ to bind to all interfaces (default: %(default)s) --no-localhost-bind=False do not implicitly also bind to localhost addresses --port-control=3248 TCP port to listen on for control connections (default: 3248) -v=0, --verbose=0 increase logging level -q=0, --quiet=0 decrease logging level
Pattern matching works as follows. The default action on a key (dataset name) is to log it. Then the patterns are traversed in order and glob-matched with the key. Optional + and - pattern prefixes specify whether to ignore or log keys matching the rest of the pattern. Default (in the absence of prefix) is to ignore. Last matched pattern takes precedence.