Networking and configuration

Setting up core device networking

Note

Satellite core devices (in a DRTIO setting, see Using DRTIO and subkernels) do not support independent networking and this section does not apply to them. Follow the instructions on this page for your master core device, and proceed to Configuring DRTIO satellites once DRTIO communications are established.

For Kasli, insert a SFP/RJ45 transceiver (normally included with purchases from M-Labs and QUARTIQ) into the SFP0 port and connect it to an Ethernet port in your network. If the port is 10Mbps or 100Mbps and not 1000Mbps, make sure that the SFP/RJ45 transceiver supports the lower rate. Many SFP/RJ45 transceivers only support the 1000Mbps rate. If you do not have a SFP/RJ45 transceiver that supports 10Mbps and 100Mbps rates, you may instead use a gigabit Ethernet switch in the middle to perform rate conversion.

You can also insert other types of SFP transceivers into Kasli if you wish to use it directly in e.g. an optical fiber Ethernet network. Kasli-SoC already directly features RJ45 10/100/1000 Ethernet.

IP address and ping

If you purchased a Kasli or Kasli-SoC device from M-Labs, it will arrive with an IP address already set, normally the address requested in the web shop at time of purchase. If you did not specify an address at purchase, the default IP M-Labs uses is 192.168.1.75. If you did not obtain your hardware from M-Labs, or if you have just reflashed your core device, see DHCP and default addresses below.

Once you know the IP, check that you can ping your device:

$ ping <IP_address>

A variety of issues with crate setup tend to make themselves apparent at this step, so if ping fails or artiq_coremgmt cannot connect to the device, some troubleshooting may be required. First, check that the Ethernet LED is ON; on Kasli, it is the LED next to the SFP0 connector. Try connecting to the serial port to read the UART log, as in Connecting to the UART log, and check that the core device is booting correctly and the networking options are set as you expect. For more steps, see also FAQ: how do I troubleshoot networking problems?

Core management tool

The tool used to configure the core device is the command-line utility artiq_coremgmt. In order for it to connect to your core device, it is necessary to supply it somehow with the correct IP address for your core device. This can be done directly through use of the -D option, for example in:

$ artiq_coremgmt -D <IP_address> log

Note

This command reads and displays the core log. If you have recently rebooted or reflashed your core device, you should see the startup logs in your terminal.

Normally, however, the core device IP is supplied through the device database for your system, which comes in the form of a Python script called device_db.py (see also The device database). If you purchased a system from M-Labs, the device_db.py for your system will have been provided for you, either on the USB stick, inside ~/artiq on your NUC, or sent by email.

Make sure the field core_addr at the top of the file is set to your core device’s correct IP address, and always execute artiq_coremgmt from the same directory the device database is placed in.

Once you can reach your core device, the IP can be changed at any time by running:

$ artiq_coremgmt [-D old_IP] config write -s ip <new_IP>

and then rebooting the device:

$ artiq_coremgmt [-D old_IP] reboot

Make sure to correspondingly edit your device_db.py after rebooting.

DHCP and default addresses

Kasli and KC705 devices can be configured to use DHCP to obtain an IP address and default gateway. This is done by setting the ip config value to use_dhcp, which is also the default if no IP address has been set. The chosen IP address will be in log output, which can be accessed via the UART log.

Tip

If a static IP address is required and artiq_coremgmt can’t be used, ip (and other configuration keys) can be set by flash with artiq_mkfs and artiq_flash. See Configuration without artiq_coremgmt.

On other core devices the default IP addresses are static, as follows:

For Kasli-SoC: 192.168.1.56.

For ZC706: 192.168.1.52.

For EBAZ4205: 192.168.1.57.

Configuring the core device

Note

The following steps are optional, and you only need to execute them if they are necessary for your specific system. To learn more about how ARTIQ works and how to use it first, you might skip to the first tutorial page, ARTIQ Real-Time I/O concepts. For all configuration options, the core device generally must be restarted for changes to take effect.

Detailed networking options

Besides ip, which expects an IPv4 address, ARTIQ core devices also support setting an IPv6 address via the key ipv6. These addresses are independent and can be used simultaneously. Note that each core device also possesses a link-local address corresponding to its EUI-64, which is unrelated to networking configuration and can also be used separately.

If you would like to be able to access the core device from outside of its subnet, the ip_default_route key should be set to the IP address of a default gateway. Additionally, the ip key should be set to a network prefix rather than a simple address, for example:

$ artiq_coremgmt config write -s ip 192.168.1.75/24 -s ip_default_route 192.168.1.0

The equivalent key for ipv6 is ipv6_default_route.

It is also possible to manually set the core device’s MAC address, though on Kasli or Kasli-SoC devices this is unnecessary, as they can obtain it from EEPROM. The corresponding key is mac.

Flash idle and/or startup kernel

The idle kernel is the kernel (that is, a piece of code running on the core device; see ARTIQ Real-Time I/O concepts for further explanation) which the core device runs in between experiments and whenever not connected to the host. It is saved directly to the core device’s flash storage in compiled form. Potential uses include cleanup of the environment between experiments, state maintenance for certain hardware, or anything else that should run continuously whenever the system is not otherwise occupied.

To flash an idle kernel, first write an idle experiment. Note that since the idle kernel runs regardless of whether the core device is connected to the host, remote procedure calls or RPCs (functions called by a kernel to run on the host) are forbidden and the run() method must be a kernel marked with @kernel. Once written, you can compile and flash your idle experiment:

$ artiq_compile idle.py
$ artiq_coremgmt config write -f idle_kernel idle.elf

The startup kernel is a kernel executed once and only once immediately whenever the core device powers on. Uses include initializing DDSes and setting TTL directions. For DRTIO systems, the startup kernel should wait until the desired destinations, including local RTIO, are up, using self.core.get_rtio_destination_status (see get_rtio_destination_status()).

To flash a startup kernel, proceed as with the idle kernel, but using the startup_kernel key in the artiq_coremgmt command.

Note

Subkernels (see Using DRTIO and subkernels) are allowed in idle (and startup) experiments without any additional ceremony. artiq_compile will produce a .tar rather than a .elf; simply substitute idle.tar for idle.elf in the artiq_coremgmt config write command.

Select the RTIO clock source

The core device may use any of an external clock signal, its internal clock with external frequency reference, or its internal clock with internal crystal reference. Clock source and timing are set at power-up. To find out what clock signal you are using, check the startup logs with artiq_coremgmt log.

The default is to use an internal 125MHz clock. To select a source, use a command of the form:

$ artiq_coremgmt config write -s rtio_clock int_125  # internal 125MHz clock (default)
$ artiq_coremgmt config write -s rtio_clock ext0_synth0_10to125  # external 10MHz reference used to synthesize internal 125MHz

See Clocking for availability of specific options.

Set up resolving RTIO channels to their names

This feature allows you to print the channels’ respective names alongside with their numbers in RTIO error messages. To enable it, run the artiq_rtiomap tool and write its result into the device config at the device_map key:

$ artiq_rtiomap dev_map.bin
$ artiq_coremgmt config write -f device_map dev_map.bin

More information on the artiq_rtiomap utility can be found on the Utilities page.

Enable event spreading

This feature changes the logic used for queueing RTIO output events in the core device for a more efficient use of FPGA resources, at the cost of introducing nondeterminism and potential unpredictability in certain timing errors (specifically gateware sequence errors). It can be enabled with the config key sed_spread_enable. See Event spreading.

Load the DRTIO routing table

If you are using DRTIO and the default routing table (for a star topology) is not suitable to your needs, you will first need to prepare and load a different routing table. See Using DRTIO.

Configuring DRTIO satellites

Once DRTIO communications are online, any satellite devices can be accessed as normal using artiq_coremgmt, e.g.:

$ artiq_coremgmt -s <destination_number> log

The destination number corresponds to the number assigned to that satellite both in the device database and, earlier, in the system configuration file. See the notes in Configuring the routing table if you are not sure what destination number to use.

It is also possible to set configuration values, reflash, or reboot the device. Notably, event spreading is a per-device setting considered particularly useful on satellites. Most other configuration settings, e.g. networking, clocking, will not be used in practice in a satellite context – satellites do not support direct network connections and are always bound to the master’s clock.