Skip to content

Server Configuration

Jump to bottom
Joseph Nobes edited this page Feb 4, 2025 · 5 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.

Setting up a static IP address

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

# loki_set_static_ip <ip address>

Starting and Stopping the odin-control Service

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.

There are helper aliases to stop and restart the server (as root; use su -):

# loki_stop_app
# loki_restart_app

Alternatively, use the init script to start, stop, and restart the odin-control server directly (as root):

# /etc/init.d/loki-config.sh start
# /etc/init.d/loki-config.sh stop
# /etc/init.d/loki-config.sh restart

Accessing odin-control Logs

By default, the instance will output logs to /var/log/loki/detector.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
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-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>

Binding Known Directories

LOKI systems expect to (optionally) mount two 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>.
  • Sequences::
    • Mounted on LOKI to /opt/loki-detector/sequences
    • Used for storing user sequences for odin-sequencer.
    • This directory must be r/w from LOKI as above
    • If not set, the image will use the sequences built into it (for production systems, this might be typical; you can execute sequences, but not edit them).

The control host locations for these are specified in the control host layout file, in EXPORTS_LOC and SEQUENCES_LOC respectively. 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.

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 startup 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 the odin-control config file location, as well as forcing it to use an external python environment (see Process for Creating LOKI Control Host Virtual Environments).

To override the default configuration with your own from the control host, set LOKI_CONFIG_FILENAME in the layout file. By convention this file is called loki-config.conf.

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 loki-config.conf above. If you want to override it, you must add a location to the variable conf_ODIN_DETECTOR_CONFIG_LOC= in loki-config.conf. If you do not include a definition, the config file included in the image will be used.

Warning

Locations specified in the loki-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 the control service while you restart this one.

# loki_stop_app
# /etc/init.d/loki-connect-control-host.sh restart
# loki_restart_app
Clone this wiki locally