Deploy OpenEMS Edge

This chapter explains how OpenEMS can be deployed on a Debian Linux Internet-of-Things Gateway. Similar techniques will work for other operating systems as well.

This guide covers a simple, manual approach. For productive systems it is required to automate deployment to IoT devices. Good approaches include a Debian package repository that provides *.deb-files and third-party tools like Eclipse Hawkbit. This is out-of-scope for this small guide.

Prerequisites:

  • A target device running Debian Linux like a Raspberry Pi, Beaglebone Black or an IoT gateway. You need the IP address and SSH access.

  • Create a JAR-file that should be deployes. See Build OpenEMS Edge for details. Alternatively you may download the latest release openems-edge.jar file from GitHub under Assets.

  • Setup an SSH client to connect to the Linux console, e.g. KiTTY

  • Setup an SCP client to copy the JAR file via SSH, e.g. WinSCP

1. Connect via SSH and SCP

  1. Connect via SSH using KiTTY

    1. Open KiTTY and connect to the target device.

      Make sure to select SSH with port 22 and enter the IP address of the target device. Press the Open button.

      KiTTY Configuration
      Figure 1. KiTTY Configuration
    2. Gain root permissions either by logging in as user root or by login in as a default user and executing sudo -s.

      KiTTY Configuration
      Figure 2. KiTTY Configuration
      As an example, for the FENECON Energy Management System (FEMS) it is required to:
      login as: fems
      fems@192.168.178.38’s password: device specific password
      …​
      fems@femsXXX:~$ sudo -s
      [sudo] password for fems: device specific password
      root@femsXXX:/home/fems#
  2. Connect via SCP using WinSCP

    1. If you are lucky and have a fully configured system, right-click on the KiTTY window bar and select Start WinSCP.

      Start WinSCP from KiTTY
      Figure 3. Start WinSCP from KiTTY
    2. Otherwise open WinSCP separately, create a new connection, select SCP as protocol and enter again the IP address and port 22. Click Connect once finished.

      Start WinSCP from KiTTY
      Figure 4. Start WinSCP from KiTTY

1.1. Prepare operating system environment

1.1.1. Create an application directory

Create the directory /usr/lib/openems. This is going to be the place, where we put the JAR file.

Execute mkdir /usr/lib/openems.

1.1.2. Create a config directory

Create the directory /etc/openems.d. This is going to be the place, where all the bundle configurations are held.

Execute mkdir /etc/openems.d.

1.1.3. Create a systemd service definition

The systemd 'Service Manager' manages system processes in a Debian Linux. We will create a systemd service definition file, so that systemd takes care of managing (starting/restarting/…​) the OpenEMS Edge service.

  1. Create and open the service definition file.

    Execute nano /etc/systemd/system/openems.service

  2. Paste the following content:

    [Unit]
    Description=OpenEMS Edge (1)
    After=network.target (2)
    
    [Service]
    User=root (3)
    Group=root
    Type=notify (4)
    WorkingDirectory=/usr/lib/openems
    ExecStart=/usr/bin/java -Dfelix.cm.dir=/etc/openems.d/ -jar /usr/lib/openems/openems.jar (5)
    SuccessExitStatus=143 (6)
    Restart=always (7)
    RestartSec=10 (8)
    WatchdogSec=60 (9)
    
    [Install]
    WantedBy=multi-user.target
    1 The name of the service.
    2 The service is allowed to start after network is available (e.g. to be able to access devices via ethernet connection)
    3 It is run as user 'root' to have access to all devices. It is recommended to change this for productive systems.
    4 OpenEMS notifies systemd once it is started up properly.
    5 The start command executes Java, sets the config directory to /etc/openems.d and runs the jar file at /usr/lib/openems/openems.jar
    6 In contrast to what systemd expects, Java exits with status 143 on success.
    7 Systemd always tries to restart OpenEMS once it was quit.
    8 Systemd waits 10 seconds till the next restart.
    9 Systemd expects OpenEMS to trigger its watchdog once every 60 seconds. OpenEMS is doing that by default if it detects that it is run by systemd.
  3. Press Ctrl + x to exit and y to save the file.

  4. Activate the service definition:

    Execute systemctl daemon-reload

1.1.4. Update OpenEMS Edge JAR file

To update the OpenEMS JAR file at the target device, it is required to copy the JAR file from your build directory (see Build OpenEMS Edge) to /usr/lib/openems/openems.jar on the target device. Afterwards it is required to restart the systemd service

  1. Copy JAR file via SCP.

    In WinSCP open your local build directory on the left side and /usr/lib/openems/ on the right side. Then drag and drop the file from left to right.

    WinSCP copy file
    Figure 5. WinSCP copy file
  2. Restart OpenEMS systemd service.

    Execute systemctl restart openems --no-block; journalctl -lfu openems

    The command restarts the service (systemctl restart openems) while not waiting for the OpenEMS startup notification (--no-block). Then it directly prints the OpenEMS system log (journalctl -lfu openems).

    OpenEMS Edge start-up
    Figure 6. OpenEMS Edge start-up