Installation

Server

This guide is for installing the server on the Raspberry Pi mounted within the eVOLVER hardware platform connected via serial to the physical hardware (see Quick Start for running the server locally with dummy hardware).

Requirements

The application depends on python 3.11 or later, so ensure the Raspberry Pi os is up to date and has at least this version of python installed. We recommend using the debian based systems, such as bookworm (see https://www.raspberrypi.com/software/operating-systems/).

If you are using the standard eVOLVER hardware, the Raspberry Pi should also be setup to use the UART serial port available at ttyAMA0, which requires custom bootflags in order to disable bluetooth and enable the serial port. This can be done by adding the following to the /boot/firmware/config.txt file:

[all]
enable_uart=1
dtoverlay=pi3-disable-bt

Install and setup service

Install the package:

pip install git+https://github.com/ssec-jhu/evolver-ng

Setup the service to run on boot. Create a file at /etc/systemd/system/evolver.service with the following contents

[Service] Environment=EVOLVER_HOST=0.0.0.0 EVOLVER_CONFIG_FILE=/etc/evolver.yml ExecStart=python -m evolver.app.main Restart=on-failure Type=exec

[Install] WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable evolver
sudo systemctl start evolver

The service should now be running and API listening at port 8080 for remote connections. You can confirm this by navigating to the openapi documentation interface at http://<raspberry-pi-ip>:8080/docs.

Configuration

The eVOLVER server needs to be configured with the hardware drivers that are available on the system. This can be done either by creating or obtaining the appropriate configuration file prior to server start. Alternatively the API/UI can be used to update the configuration for a server that is already online.

Note

There will be example configurations included in the evolver-ng package for many standard setups. The below advice may only be required in case of custom hardware.

Specifically, the hardware section should contain a map of the hardware on box, where each element is a ConfigDescriptor that describes the hardware, which contains a reference to the python class that implements the hardware driver and the configuration for that driver. For example:

hardware:
  OD90:
    classinfo: "evolver.hardware.standard.od_sensor.ODSensor"
    config:
      addr: "od90"
      integrations: 500

Note that since this references a python class, it is important that the package in which that class is defined is installed in the python environment that runs the server. For standard hardware, this is included in the evolver-ng package as seen above. For custom hardware, maintainers should give instructions for installing the package, and example configurations to simplify setup for end-users. See Developing eVOLVER components for more information on creating extensions.

Web UI

We can similarly install the web UI on the Raspberry Pi, or any other computer with network access to one or more eVOLVER servers.

The simplest way to install the web UI is to use mise to install npm, then build the and run the service via npm (see also https://github.com/ssec-jhu/evolver-ui).

install mise (see also https://mise.jdx.dev/getting-started.html):
```
curl https://mise.run | sh
```
install npm via mise:
```
mise use node@lts
```

clone the web UI repository:

git clone https://github.com/ssec-jhu/evolver-ui

build it:

cd evolver-ui
npm install
npm run build

run it:
```
npm run start
```

Install and setup service

We can also setup the web UI to run as a service on the Raspberry Pi. Here is an example systemd service file (for example at /etc/systemd/system/evolver-ui.service):

[Service]
Requires=evolver.service
ExecStart=/home/pi/evolver-ui/start-ui.sh
WorkingDirectory=/home/pi/evolver-ui
Restart=on-failure
Type=exec

[Install]
WantedBy=multi-user.target

The above uses a helper script to start the UI that has been placed at the root of the repository:

#!/bin/sh
export PATH=/home/pi/.local/share/mise/installs/node/22.15.0/bin:${PATH}
cd /home/pi/evolver-ui
npm start

After which you can enable and start the service:

sudo systemctl enable evolver-ui
sudo systemctl start evolver-ui

By default the UI will run on port 3000, so navigate your browser there and add devices as necessary.