Skip to content

Server Configuration

Jump to bottom
Joseph Nobes edited this page Aug 13, 2025 · 9 revisions

Operating and Configuring a Live odin-control Server on LOKI Systems

Table of Contents:

Background

LOKI-based control systems provide their control interface using an instance of odin-control, a modular framework for control system development. This instance is brought up with an application-specific adapter, which will be developed as part of system integration with hardware. This guide assumes that the adapter has already been developed- odin-control adapter development is out of scope. See LOKI-based Adapter Creation.

By default, this adapter will run automatically on boot, and present a web interface on port 8888. The HTTP REST API can be accessed via the same port.

Warning

A LOKI unit must be connected to an isolated network; it is not a hardened device. You have been warned.

LOKI Device IP

By default, a LOKI unit is configured for a DHCP-obtained address. This means that either it must be plugged into a DHCP-enabled network shared with the machine intended to access the interface, or the controlling machine must provide DHCP in the case of a direct connection.

Alternatively, the unit can be configured with a static IP address. This is implemented by adding aliases to the network configuration stored in non-volatile storage in the eMMC, which will also work alongside DHCP.

Setting up a static IP address

Log into the LOKI unit, and as root (use su -):

# loki_set_static_ip <ip address>

Other Custom Modifications To Wired Network Config (2023 Toolchain)

To provide a more custom solution, add an override file directly in /mnt/emmc/wired-network-overrides-mmc/. Note that the file auto-static-eth0.conf will be overwritten by the above command, but you can add overrides with any filename as long as it ends in .conf.

You could for example use this to disable DHCP and run with only the static address.

Starting and Stopping the odin-control Services

The PetaLinux image produced for LOKI uses System V scripts to control services. Currently, it is only possible to control the service while logged in to the device over SSH or UART.

It is possible to run multiple instances of odin-control. There are helper aliases to stop and restart the servers (as root; use su -):

# odin-control-instance.sh <instance name> stop
# odin-control-instance.sh <instance name> restart

For example, the instance name for the typically built-in update server is loki-update.

Accessing odin-control Logs

By default, the instance will output logs to /var/log/loki/<instance name>.log. This file can be read by the loki user, and is accessible from a logged in terminal only (unless redirected to a network mounted location).

Control Host Configuration

What is a Control Host?

The LOKI system is able to function independently as a controller, with minimal reliance on an external machine to simply access the web interface for whatever detector is being controlled.

Warning

Once again: A LOKI unit must be connected to an isolated network; it is not a hardened device. You have been warned.

For mimimal operation (web interface access), requirements are:

  • A DHCP server on the connected network, or configured static IP
  • A machine on the same network with a web browser installed

For more advanced operation that allows for non-standard configuration, as well as the abilty to write files to network mounts on the host machine as well as edit sequences for odin-sequencer, we can connect a standardised control host.

Note

While the system is under active development, it is typical that any controlling machine should be a standardised control host, as we are almost always going to want to live-edit odin-sequencer sequence files at the very least. This may change in the future when sequences become more standardised, and we can rely on baked-in control.

Requirements of a Standardised Control Host:

  • DHCP server on isolated interface, which allows the LOKI unit to be plugged in directly
  • An exported NFS mount at /opt/export/loki, which will be writable by LOKI devices

Control Host Network Mount Layout

On boot, the LOKI system will look for a control host providing a valid control mount. By default it will expect this to be located at default control host IP and mountpoint 192.168.100.1:/opt/export/loki. By convention, most systems should have it located here (all 'standard' control hosts).

However, if you need to override the default location, you must modify the /mnt/sd-mmcblk0p1/loki-config/loki-host.conf` file on your specific unit's eMMC card.

Inside this file, set the host IP and mountpoint with variables LOKI_CONTROLHOST_IP and LOKI_CONTROLHOST_MOUNTPOINT.

From here, the system will look for a top-level <APPLICATION NAME>/layout.conf file that tells it where to look further for the other optional components on the mountpoint. The application name here is defined by the application of the current project, as defined in the environment variable loki_application_name supplied in repo.env to the Makefile when building your system's image. This means you can control multiple different kinds of LOKI-based system from the same control host without them interfering with each other.

Note

All locations in the layout.conf are relative to the mountpoint root.

layout.conf variable Usage
CREATE_SYSTEM_ID_DIRECTORY If 1 will create a directory at <MOUNTPOINT ROOT>/<SYSTEM ID> for your system, which can then be referred to in below variables as ${LOKI_SYSTEMID}`. See Unique System Identifiers
SEQUENCES_LOC User sequences location This is now only managed by the location in the odin configuration file for simplicity.
EXPORTS_LOC General purpose output directory location
IMAGE_UPDATE_LOC A read-only directory intended for standardised location to place image files for later install.
LOKI_CONFIG_FILENAME Optional override of LOKI system-wide config file loki-config.conf/loki-system-config-default.conf. Details
INSTANCE_CONFIG_FILENAMES Optional override of instance configuration files <instance name>-config.conf. Details

Unique System Identifiers

Each LOKI board has a unique identifier from production, regardless of the SoM placed in it. The intention is to identify a specific board, or when built into a system to identify a specific system (or detector head etc). For this reason, the system identifier can be modified. Before being built into systems, the identifier is routinely updated to the format 'loki_____' during commissioning (e.g. `loki_rev2_008').

The current system identifier can be printed out when logged in to a terminal session:

petalinux-custom:~$ loki_system_id 
loki_rev2_008

Alternatively, if you know the IP address and application adapter name, it is returned as part of the REST API. From another machine:

$ http GET http://<LOKI IP>:8888/api/0.1/<Application Adapter name>/carrier_info/system_id

{
    "system_id": "loki_rev2_008\n"
}

To update the system identifier, as root (use su -):

# loki_set_system_id <NEW ID>

Sequences

  • Formerly these were all mounted to LOKI at /opt/loki-detector/sequences in the same way as the 'exports' below.
  • Since the 2023 tool integration, (and because there are now multiple odin instances) sequence locations are managed only by the odin config file.
  • The location in this file can be specified as /controlhost/<your application name>/<chosen location> in the network mount, or otherwise will just be the built-in sequences in the image for this odin-control instance.
  • This directory must be r/w from LOKI as above

Binding Known Directories

LOKI systems expect to (optionally) mount these directories from the control host.

  • Exports:
    • Mounted on LOKI to /opt/loki-detector/exports
    • Used for the output of general use files from users (typically experiment metadata from sequences).
    • This directory must be writeable by LOKI, therefore on the control host modify the permissions to allow it. The most permissive way to do this would be to run chmod a+rw <YOUR CONTROL HOST EXPORTS DIRECTORY>.

The control host location for this is specified in the control host layout file, in EXPORTS_LOC. This location may include the system identifier in case you want different sequences for each device, or a different metadata output directory (see below).

The LOKI system will check if it can see the target at boot. If it does not exist, or the permissions are not correct, it will give up and use the internal version instead.

The LOKI system will check if it can see the target at boot. If it does not exist, or the permissions are not correct, it will give up and use the internal version instead.

Using the System Identifier in Paths

In directories such as the exports and sequences directory above, you can use the location ${LOKI_SYTEMID} to automatically refer to a directory created for the specific system you are using. This will be created if it does not exist (if the CREATE_SYSTEM_ID_DIRECTORY is set to 1) in the control host mount root.

Warning

I would however encourage that you don't do this by default unless you specifically require output to be different for different units; it may cause confusion if swapping out LOKI units causes behaviour to change.

Overriding the LOKI system config file

LOKI systems use a general (legacy) configuration file that is baked into the image. This is not used for much any more, but is still the method for overriding defaults for some system-wide settings, such as whether or not SSH keys persist and whether a generic start-up script is used.

To override the default configuration with your own from the control host, set LOKI_CONFIG_FILENAME in the layout.conf file to the location of your new file. By convention this file is called loki-config.conf. This file overrides settings that can be found in the default file loki-system-config-default.conf.

Available settings:

  • conf_PERSISTENT_SSH_AUTH: set 1 to allow SSH keys stored in /home/loki/.ssh to persist reboots.
  • conf_INITIAL_SETUP_SCRIPT_ENABLE and conf_INITIAL_SETUP_SCRIPT_PATH: set the former to 1, and give a file path to the latter to run an arbitrary script at startup. Ideally not used unless you really need to, as it makes systems unpredictable due to behaviours not captured in the main image.

Overriding odin-control Instance Startup Configs

It is possible to run multiple instances of odin-control on the LOKI system. Most commonly this is used to allow an update server to run alongside the application detector control instance. Each of these instances has an instance configuration file (not to be confused with the odin-control server config file), which dictates settings like the user the server is run under, log locations, and whether a host-mounted alternative python environment is used (see Process for Creating LOKI Control Host Virtual Environments).

By default, each instance will use its own configuration file, as included in the image build and stored in /etc/conf.d/loki-config/ (see example #TODO). To replace the file, you must create a file with the same name in the root of your mount- for example, loki-update-config.conf. Then, update the variable INSTANCE_CONFIG_FILENAMES in your layout.conf to include a list of overriding configs in this format:

INSTANCE_CONFIG_FILENAMES=("garud-detector-config.conf" "file two" "file three...")

Each instance will use defaults for the various settings found in instance-config-default.conf. If an overriding config has been provided in the image build or the network mount via the above method, each individual setting will override the default.

Available settings:

  • conf_ODIN_DETECTOR_PYVENV_ENABLE and conf_ODIN_DETECTOR_PYVENV_PATH: Used to execute odin-control inside a Python virtual environment instead of the default one, potentially on the network mount.
  • conf_ODIN_DETECTOR_ADDITIONAL_ARGUMENTS
  • conf_ODIN_DETECTOR_LOGLEVEL
  • conf_ODIN_DETECTOR_LOGDESTINATION
  • conf_ODIN_DETECTOR_STDERRDESTINATION
  • conf_ODIN_DETECTOR_LOG_FILE_SIZE
  • conf_ODIN_DETECTOR_LOG_FILE_NUM_BACKUPS
  • conf_LOKI_USERNAME: The user under which the server will be executed.
  • conf_AUTO_START: If true (default), the instance will run at boot. Otherwise it must be started manually.
  • conf_ODIN_DETECTOR_CONFIG_LOC: Specifies an alternative odin-control config file (see below)
  • conf_ODIN_DETECTOR_ROOT_LOC: Specifies an alternative directory to execute odin-control from.

Overriding the odin-control config file

The odin-control configuration file config.cfg will be familiar to those who have worked with other odin-control systems. The specifics of the contents will depend on the system.

The location of the file used is defined in the <instance name>-config.conf above. If you want to override it, you must add a location to the variable conf_ODIN_DETECTOR_CONFIG_LOC= in <instance name>-config.conf. If you do not include a definition, the config file included in the image will be used.

Warning

Locations specified in the *-config.conf file will not be relative to the control host mountpoint, so you must include the path as mounted by LOKI. This means that a location inside your mountpoint will be /controlhost/<APPLICATION NAME>/<LOCATION IN MOUNT>.

Remounting the Host Mountpoint

System V scripts are relatively primitive, and do not have dependencies. Therefore , you should stop all control services while you restart this one.

# /etc/init.d/odin-control-instances-manager.sh stop
# /etc/init.d/loki-connect-control-host.sh restart
# /etc/init.d/odin-control-instances-manager.sh start

Clone this wiki locally