UTU Logo EU Logo ELY Logo EU Logo

  1. Starting the software
    1. JAR distribution
    2. Jlink distribution
    3. Docker distribution
    4. Custom build
  2. Accessing the web UI
  3. Closing the application
  4. Advanced use
    1. Command line tools
    2. System service
    3. Optimized use

This section shows how to start the measurement software, depending on how the software was installed in the previous step.

The measurement program does not launch the web interface by default, but we feel that this is the most natural way to use the program, so the target state after launch is that the program can be used via the web interface. A command line switch is required to launch the web interface. Another switch is required to configure settings such as the HTTP port for the interface, if the default configuration needs to be changed.

Starting the software

Using the application is straightforward. First make sure you have already set up the application for performing measurements. Depending on how you obtained the software, we have multiple ways of starting the application.

JAR distribution

This version of PowerGoblin requires OpenJDK 25 or later to run. We have instructions for installing Java here.

If you downloaded the jar distribution, run:

$ java --enable-native-access=ALL-UNNAMED -jar powergoblin.jar

The --enable-native-access=ALL-UNNAMED option is a recent addition in Java 25+ and is supposed to control the access to low level devices. Obviously PowerGoblin requires such access, because it is communicating with power meters.

The first command assumes that you have downloaded the jlink distribution (a zip archive) and extracted the application to a local directory powergoblin/:

$ powergoblin/bin/power

The project repository also contains the XDG .desktop file for setting up a quick launch icon for the application on Linux and other compatible systems. Simply extract the zip to /usr/local/powergoblin, copy the jpg file there as well, then copy the .desktop file to ~/.local/share/applications/ and restart your desktop session.

Docker distribution

If you have downloaded or built the Docker distribution, run:

$ docker run --privileged registry.gitlab.utu.fi/tech/soft/visiiri/powergoblin:latest

The --privileged flag is used here to share the devices connected to the host to the containers. Otherwise, the meter device files will not be visible inside the container. However, there are other options for sharing the device files as well, if this sounds too risky.

You may also want to set --network=host in case internet connection is needed inside the container (e.g. updates) and DNS does not work properly.

It's also possible to use the Docker configuration as a starting point for Docker Compose or Podman.

Custom build

If you wanted to build the application yourself, after running mvn clean package, simply type:

$ java -jar goblin-service/target/fatjar/powergoblin-service-*.jar

The jlink version can be started with

$ goblin-service/target/maven-jlink/classifiers/app/bin/power

Accessing the web UI

After launching the application, it should print some debug data such as

PowerGoblin, version dev-snapshot

Web [Simple HTTP] listening at [ http://172.17.0.1:8080 ]
Web [Simple HTTP] listening at [ http://192.168.0.100:8080 ]

Interactive mode. You can close the application by pressing enter / ctrl-c or via mqtt/http

The application will listen to localhost and http://192.168.0.100:8080. Assuming you are not using Docker, you can access the web UI by accessing http://localhost:8080 with a browser.

For Docker users, depending on your Docker settings the container might have a distinct IP address (localhost or 127.0.0.1 will not work). You can access the web UI, but you will need to locate the container's IP first. You can use the following commands to locate the container:

$ docker container ls
CONTAINER ID IMAGE        COMMAND                CREATED       STATUS       PORTS     NAMES
3c002596c0cc 22367e0d24d7 "/power/bin/power -d…" 1 seconds ago Up 1 seconds           vibrant_liskov

$ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' 3c002596c0cc
172.17.0.4

We can deduce that the address of the web UI is now http://172.17.0.4:8080.

In order to send trigger messages from the SUT, the container's IP needs to be accessible from the SUT's network as well. You'll need to configure a bridge or some other network configuration so that the SUT can access the container. Configuring bridges is out of the scope of this tutorial.

Closing the application

The instructions for closing the application depend on the way the application was started. The jar, jlink, and docker versions typically don't restart automatically. The systemd service however might be configured to restart indefinitely.

The easiest way to close the application once is to use the web interface. There is a Shutdown button in the Instance section (see the instructions on sections).

If you started a native instance (non-Docker) of the application, it can be closed by pressing ctrl-c in the terminal for interactive sessions. For non-interactive sessions, use the kill or killall command or a task manager to close the application process:

$ killall java -9
$ killall java -15

Docker users should kill the container with docker container kill.

Advanced use

Command line tools

PowerGoblin supports several special modes for performing various analysis and maintenance tasks.

Instance state dump: E.g. when developing meters, it's useful to quickly get a dump of meter specs and states. This can be performed with the --info switch:

$ java --enable-native-access=ALL-UNNAMED -jar powergoblin.jar --info

Update configuration files: The configuration file can be updated if you wish to update some persistent setting. E.g. to permanently enable the debug mode, use the --save switch:

$ java  -jar powergoblin.jar --debug --save

Browse session logs: The session logs can be browsed with the --analyze switch:

$ java -jar powergoblin.jar --analyze

No log path entered, use log=PATH

Available logs:
 - 2026-05-12_11-46-58: System utility benchmarks
  (Captain Planet): Runs CPU benchmar... | 2026-05-12 | 5912 kB | 17 files

Analyze session logs: The session logs can be browsed with the --analyze switch. Provide the log directory name with log= and select the mode with mode= (modes = short/long/default):

$ java -jar powergoblin.jar --analyze log=2026-05-12_11-46-58 mode=short

{
  "configuration" : {
    "flags" : {
      "logMeterEvents" : true,
...

Reconstruct session logs: The session logs can be reconstructed from the session.json, events.json, and template.md with the --reconstruct switch. Provide the log directory name with log=. All files, including these three, will be rewritten. Possible asset files for the session report will not be processed. The purpose of this feature is to update the reports afterward. Example:

$ java -jar powergoblin.jar --reconstruct log=2026-05-12_11-46-58

Processing 1/System utility benchmarks
Report template unchanged for session [1]
Processing done
Instance 653a6b393f365726918f6ac641b46ae94b136930 stopped
Closed instance.

System service

PowerGoblin can also be started as a background system service. This can be a particularly good solution if, for example, a Raspberry Pi computer is used to manage measurements. When PowerGoblin starts automatically, it can be managed via the web UI without the need to connect a display or input devices to the Raspberry Pi computer. This makes deployment easier in some situations. We provide instructions for setting up Raspberry Pi in the setup section.

Previously, PowerGoblin was very experimental and probably required reboots in case of problems. It did not make sense to run the program as a service. We are now confident that PowerGoblin can run as a background service for multiple measurements. Of course, it should be noted that to ensure maximum reliability, it is advisable to verify the success of the measurement.

PowerGoblin comes with a systemd service file that allows you to start the service in the background when the machine boots up:

[Unit]
Description=PowerGoblin service
After=local-fs.target network.target

[Service]
SuccessExitStatus=143

[Service]
User=powergoblin
Type=simple
AmbientCapabilities=CAP_NET_BIND_SERVICE
WorkingDirectory=/opt/powergoblin
ExecStart=/usr/bin/java --enable-native-access=ALL-UNNAMED -jar /opt/powergoblin/powergoblin.jar port=8080
ExecStop=/bin/kill -15 $MAINPID
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Please note that you need a user called powergoblin for the service, which must be given the correct permissions (see #1 and #2). In addition, OpenJDK 25+ is required.

The following commands set up the user and the service binary on a system which already has OpenJDK configured:

$ sudo useradd -G uucp -m powergoblin
$ sudo mkdir -p /opt/powergoblin
$ wget tech.utugit.fi/soft/visiiri/powergoblin/powergoblin.jar
$ sudo mv powergoblin.jar /opt/powergoblin
$ sudo chown -R powergoblin /opt/powergoblin

You can now enable the service as follows:

$ wget tech.utugit.fi/soft/visiiri/powergoblin/powergoblin.service
$ sudo mv powergoblin.service /etc/systemd/system
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now powergoblin

You can also set up the unprivileged service for the current user, but you can only configure the service to use the port range 1024-65535:

[Unit]
Description=PowerGoblin service

[Service]
SuccessExitStatus=143

[Service]
Type=simple
WorkingDirectory=/home/%u/pg
ExecStart=/usr/bin/java --enable-native-access=ALL-UNNAMED -jar /home/%u/pg/powergoblin.jar
ExecStop=/bin/kill -15 $MAINPID
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

You can now enable the user service as follows:

$ mkdir -p .config/systemd/user pg
$ wget tech.utugit.fi/soft/visiiri/powergoblin/powergoblin.jar -O pg/powergoblin.jar
$ wget tech.utugit.fi/soft/visiiri/powergoblin/powergoblin2.service -O .config/systemd/user/powergoblin.service
$ systemctl --user enable --now powergoblin
$ sudo loginctl enable-linger $USER

You can check the functionality of the service by visiting http://localhost:8080 (or whatever address you set for the service).

In case the service gets stuck, you can run

$ sudo systemctl restart powergoblin

or

$ systemctl --user restart powergoblin

Please note that the service is not safe to run in a public network. We have not implemented any kind of security mechanisms.

Optimized use

You can enable Java's AOT and compact object features to make the tool more efficient:

  • AOT features speed up launch
    • will probably improve even further in the future as the current versions of Java do not cache everything yet
    • Java 26+ will support AOT with other GC types as well
  • Compact object headers will shrink object size to save memory
    • Oracle is apparently planning to make this feature the default in a later version of Java.

First, start the application once using the following options:

$ java -XX:AOTCacheOutput=app.aot --enable-native-access=ALL-UNNAMED -XX:+UseCompactObjectHeaders -jar powergoblin.jar

Later, start the application like this:

$ java -XX:AOTCache=app.aot --enable-native-access=ALL-UNNAMED -XX:+UseCompactObjectHeaders -jar powergoblin.jar