Skip to content

README.md

Latest commit

 

History

History
284 lines (217 loc) · 13.5 KB

README.md

File metadata and controls

284 lines (217 loc) · 13.5 KB
Raw

Sen

General-purpose, distributed, object-oriented system for applications that demand high modularity and rich communication.

Documentation License C++

🚀 Overview

Sen is a simple way for applications to talk to one another and create, connect, and integrate complex systems with ease.

Technically speaking, Sen is a general-purpose, distributed, object-oriented system with a focus on applications that demand low-latency, high-performance, rich inter/intra process communication, high modularity, and platform independence while providing low-overhead, full introspection and an extensible tooling support.

Sen comes out of the simulation domain, where systems built by different teams and different companies have to work together, and it is built for any system with that shape.

If you are arriving from ROS, DDS, gRPC or SOME/IP, start with the mental model: it maps what you already know onto Sen's equivalents, and explains the one idea that is genuinely different: Sen is object-oriented at the network level, not message-oriented.

⚡ Quick start

The fastest way to try Sen on Linux: no Conan setup required:

curl -sSf https://raw.githubusercontent.com/airbus/sen/main/resources/installer/install.sh | sh -s -- 0.6.0

The installer downloads a release into ~/.sen/<build-id>/ and writes activate scripts you source from your shell. See the install guide for details.

Source the activate script the installer wrote, which puts sen on your PATH and exports the variables a build needs:

. ~/.sen/current/activate           # bash / zsh
source ~/.sen/current/activate.fish # fish

Setting PATH by hand is not enough. The script also exports SEN_PREFIX, which is what lets find_package(sen REQUIRED) succeed when you build a package of your own. Check it worked with sen --version.

To write your first package:

sen package init my_package --class MyClass               # Generate the skeleton
cd my_package                                             # Go to the new folder
cmake -S . -B build && cmake --build build                # Build it
export LD_LIBRARY_PATH="$(pwd)/build/bin:$LD_LIBRARY_PATH"  # your build first
sen run config.yaml                                       # Run it

config.yaml is the run configuration generated by sen package init. It declares which packages to load, which objects to instantiate, and on which bus they communicate:

load:
  - name: shell                     # load the shell component
    group: 2                        # start it in group 2
    open: [local.example]           # automatically open this bus in the shell

build:
  - name: myComponent               # build this component
    group: 3                        # run it after the shell
    freqHz: 30                      # run it at 30 Hz
    imports:
      - my_package                  # load our package
    objects:
      - class: my_package.MyClassImpl  # instantiate this class
        name: myObject              # set the name of the object
        bus: local.example          # publish this object to the bus
        prop1: some value           # required: prop1 is [static], so it needs a value here

The examples go further, and the docs cover the rest.

Sen is not on Conan Center yet, so you build it into your local Conan cache once, from a checkout of the release tag. Using Sen in your project has the commands.

Main Features

🏗️ Architecture

  • Distributed component-based system for easy microservice-based solutions.
  • Object-oriented and event-driven architecture on top of a light (user-space) micro-kernel.
  • Package-based, plugin-oriented system for higher reuse, modularity and lower coupling.
  • Rich type system with full compile-time and run-time introspection.
  • Generates your types from HLA FOM files, so a SISO standard model such as RPR or NETN can serve as your interface definition. Sen reads FOMs at build time; it does not join HLA federations.
  • Simple language for easy definition of your interfaces: Sen Type Language (STL).

⚙️ Execution model

  • Real-time, faster-than real-time (as fast as possible) and stepped execution.
  • Built-in ownership of objects and their state: each object belongs to the component that created it, and goes away when that component does. This is lifetime ownership, not transfer between components.
  • Inherently asynchronous. Callers cannot be blocked. Callees can postpone their execution.
  • Thread-safe communication with other components: everything Sen calls runs inside the cycle, so your objects exchange data without synchronization primitives of their own. A thread you started yourself is outside the cycle and hands work in rather than writing directly, and protecting what the two share is your job.
  • Dependency management and controlled component execution by groups.
  • Built-in type-safe configuration mechanism based on YAML or Python.

🔗 Communications model

  • Conditional subscription with both producer-side and consumer-side filtering.
  • Data segregation enabled through the usage of dedicated logical buses.
  • Broker-less design. Nothing relays traffic; participants discover each other over multicast, or through a discovery hub where multicast is not available.
  • Quality-of-service attributes: confirmed & ordered, best-effort directed, best-effort broadcast.
  • Generation of documentation and UML diagrams and MkDocs out of the Interface Control Document (ICD) definition.
  • Pluggable data transport: the kernel talks to a transport through an interface, so a deployment can carry Sen traffic over something other than the shipped ether.

📦 Shipped components

  • Recorder, highly customizable, with LZ4 compression, indexes, snapshots and annotations.
  • Ethernet transport supporting asynchronous I/O over TCP, UDP unicast and multicast.
  • Replayer with support for real-time, stepped execution and random access.
  • Python Interpreter embedded. You can script your components and tests.
  • Shell for CLI interaction, with auto-completion, introspection, and remote connectivity.
  • Grafana visualization via the InfluxDB component.
  • Tracer based on the excellent Tracy frame-based profiler.
  • Log Manager to control and configure the logs of a running system.
  • Explorer GUI to inspect and interact with your system (objects, events, sessions, plots), available as either a native desktop window or a browser-based Web Explorer.
  • REST API Server or JSON-RPC over WebSocket for interfacing external (non-Sen) systems, with an in-tree TypeScript client (@sen/client) and React hooks for browser / Node.js consumers.
  • MCP gateway so a large language model can observe and drive a running system, or read a recording.

💻 Implementation

  • Lightweight, multi-platform implementation. Works on Linux and Windows.
  • Run-time and compile-time introspection provided by the code generator.
  • Optimized memory management by extensive use of memory pools.
  • Natively integrated with CMake. Meta info is baked into the binaries.
  • Self-contained: no 3rd-party dependencies on the public interface.
  • Python bindings for accessing recorded data.
  • Backward compatible ICDs with runtime interoperability. Where two participants disagree about a type, Sen adapts rather than refuses, as far as the types allow (see Compatibility conversions for details).

🔨 How to Build

You need Conan, a C++17 compiler (GCC, Clang, Visual Studio), CMake, Ninja and pkg-config; the last three are used by the third-party recipes when they build from source. Ninja has to be there before Conan starts: where no prebuilt package exists Conan builds Ninja itself, and that build needs a Ninja to run.

On Debian/Ubuntu:

sudo apt install build-essential g++-12 cmake ninja-build pkg-config git \
                 python3-pip pipx python3-venv
pipx install conan
pipx ensurepath       # Puts ~/.local/bin on PATH. Open a new shell before the next line
conan profile detect  # Once per machine: creates conan's default build profile

Then get the source:

git clone https://github.com/airbus/sen.git
cd sen

The .conan/profiles folder holds the profiles this project builds with. Install the whole folder, because several of the profiles include a shared base:

conan config install -tf profiles .conan/profiles/

Then build with sen_gcc, which follows the machine you run it on and so suits Intel, AMD and 64-bit arm alike. It targets Linux and pins gcc-12, which has to exist on your machine.

conan install . --profile:all=sen_gcc --build=missing \
    -c tools.system.package_manager:mode=install \
    -c tools.system.package_manager:sudo=True    # Fetch third-party dependencies (only needed once)
conan build   . --profile:all=sen_gcc            # Build Sen

The package manager conf lets recipes install the system libraries they need (drop the sudo line when you already run as root, for example in a container). The first install compiles every third-party dependency and takes a while; later builds reuse them.

conan install writes CMakeUserPresets.json at the repository root, so VS Code, CLion and Visual Studio list the generated preset once you open the folder.

The first full-mode build fetches its toolchain (including Node.js for the browser UI) and all third-party packages from Conan Center and the npm registry.

Building from source covers the rest: prerequisites on other distributions, driving CMake yourself, Conan editable mode for building a consumer project against your working copy, and the errors a first build usually hits. Building Sen explains the mode option and the developer flags, and Running the tests covers the suite.

Once it builds, the tutorials start with one object that counts and publishes itself, then two objects calling each other. For a tour of a running system, try the Web Explorer showcase.

⚠️ Limitations

Sen is under active development. Expect potential bugs and breaking changes between releases; check the release notes before upgrading. Breaking changes are marked in the commit that makes them and collected into a dedicated section of each release's notes, which are generated from the commit history.

  • Some features may be undocumented or partially implemented.
  • Windows is supported and in use, and its tests run on every pull request, though not yet at parity with Linux: the kernel integration tests and the suites that need a Linux container, signals or /proc are excluded there.
  • Performance is a stated design target, not a published measurement. Low latency and high throughput are what Sen is built for, and the execution model is shaped around them, but we have not yet published figures for latency, message rate, entity count or participant scaling. The benchmarking tooling to produce numbers we would stand behind is in progress. Until it lands, read the performance wording above as intent, and measure on your own workload before designing against it.

Open an issue if you hit a problem, and always consult the docs for the latest guidance.

🙌 Contributing

Contributions are encouraged and valued. Have a look at our guidelines for the full picture.

💖 Credits

Huge thanks to all the people using Sen and providing active feedback!

Sen is built and maintained by the people named in AUTHORS.md, and is possible thanks to the sponsorship and engagement of the Airbus engineering community.