bennu

bennu is a modeling and simulation application for ICS/SCADA devices.

---

Building bennu with Docker

Example of using Docker to perform builds. This is easier to do as it eliminates issues with dependencies and versions on the host OS.

git clone https://github.com/sandialabs/sceptre-bennu.git
cd sceptre-bennu/

# Build the Docker image
# To change the base image, use REGISTRY_IMAGE build arg
# For example, to build with Ubuntu 22.04 (instead of 20.04), add:
#   --build-arg REGISTRY_IMAGE="ubuntu:22.04" \
docker build --pull --tag sceptre-bennu:testing .

# Run the desired executable
# This can also be copied out of the image, including shared libraries, to another system using
docker run -it sceptre-bennu:testing bennu-field-deviced --help

Documentation

• docs/protocol.md: provider/field-device REQ/REP and RADIO/DISH protocol
• docs/logging.md: log levels for C++, pybennu and gobennu
• docs/testing.md: ctest, pytest, go test, Docker harness, CI
• docs/performance.md: 800-tag analysis and throughput numbers

Installation (Ubuntu)

From source

• Install dependencies

  apt-get install --no-install-recommends -y \
      build-essential \
      cmake \
      g++ \
      gcc \
      libasio-dev \
      libboost-date-time-dev \
      libboost-filesystem-dev \
      libboost-program-options-dev \
      libboost-system-dev \
      libboost-thread-dev \
      libfreetype6-dev \
      libssl-dev \
      libzmq5-dev

• Build and install bennu

  mkdir build
  cd build
  cmake ../
  make -j$(nproc)
  sudo make install

  Note if building behind a proxy server, edit src/pybennu/Makefile, uncomment lines 124-126, and add appropriate proxy information.

From releases

• Download and install bennu.deb from the latest release:

  wget https://github.com/sandialabs/sceptre-bennu/releases/latest/download/bennu.deb
  sudo apt install ./bennu.deb

pybennu

Pybennu is a Python library and set of applications for interacting with various simulation providers, hardware-in-the-loop (pybennu-siren) and bennu field devices.
The pybennu source is under src/pybennu.

Installation (Ubuntu)

From source

• Install dependencies

  sudo apt install build-essential cmake git wget python3-dev python3-pip \
      libfreetype6-dev liblapack-dev libboost-dev \
      ninja-build pipx checkinstall

• Build and install libzmq and helics libraries

  cd src/pybennu/
  # build and install libzmq with draft support
  make libzmq-install
  
  # build and install helics (after installing libzmq)
  make helics-install

• Install pybennu

  Note that the pybennu installation forces pyzmq and pyhelics to be built from source. This is done so that they are built against the libzmq library with draft support installed above. This also means that the libzmq and helics libraries always need to be installed before installing pybennu.

  cd src/pybennu
  
  # It is recommended to install in a python virtual environment
  # Depending on your pip version, you may need to upgrade pip first: pip install -U pip
  pip install .

From releases (x86_64 builds only)

• Install dependencies

  sudo apt install git wget python3-dev python3-pip cmake ninja-build libboost-dev

• Download and install libzmq and helics builds

  wget https://github.com/sandialabs/sceptre-bennu/releases/latest/download/helics_3.6.1-1_amd64.deb
  wget https://github.com/sandialabs/sceptre-bennu/releases/latest/download/libzmq_4.3.4-1_amd64.deb
  sudo apt install ./libzmq_4.3.4-1_amd64.deb
  sudo apt install ./helics_3.6.1-1_amd64.deb

• Download and install the pybennu wheel

  Note that even the pybennu wheel installation forces pyzmq and pyhelics to be built from source. This is done so that they are built against the libzmq library with draft support installed above. This also means that the libzmq and helics libraries always need to be installed before installing pybennu.

  wget https://github.com/sandialabs/sceptre-bennu/releases/latest/download/pybennu-6.0.0-py3-none-any.whl
  
  # It is recommended to install in a python virtual environment
  # Depending on your pip version, you may first need to upgrade with: pip install -U pip
  pip install pybennu-6.0.0-py3-none-any.whl

Logging

pybennu logs with loguru to stderr and to a file.

• BENNU_LOG_LEVEL: error, warn, info (default), debug, or 0-3. The C++ tools read the same variable. An invalid value is an error. A -d/-v debug flag or a provider's debug setting forces debug.
• BENNU_LOG_FILE: log file path. Set it empty to disable the file. Unset, services (pybennu-power-solver, pybennu-siren, pybennu-alicanto, pybennu-groundtruth-monitor) write /var/log/bennu/<program>.log, and the CLI and test tools write no file.

Limitations: the file is not rotated, and the log level is global, except for Siren, which keeps its per-device level_name. Applications that import pybennu as a library get no pybennu output until they call pybennu.log.setup_logging() or logger.enable("pybennu").

Other helpful pybennu build tools

• Show makefile options

  make help

  Usage: make <command> [ARGUMENT1=value1] [ARGUMENT2=value2]
  
  Commands:
  
  help           # Show this help
  
  --- Library dependencies (debs) ---
  
  libzmq-deb     # Build the libzmq Debian package with draft support.
  
  libzmq-install # Install the libzmq deb
  
  helics-deb     # Build helics deb package
  
  helics-install # Install helics deb package
  
  --- Python packaging ---
  
  dist           # Build pybennu wheel
  
  sdist          # Build pybennu source distribution
  
  wheelhouse     # Create wheelhouse of pybennu and all dependencies in a .tar.gz
                 # Build and install libzmq and helics debs first so wheels
                 # are built against the proper libraries
  
  --- Cleanup ---
  
  clean          # Clean up build and dist files
  

• build pybennu wheel

  # requires pipx
  make dist

• build wheels for pybennu and all dependencies

  # requires pipx
  make wheelhouse