Tutorial 1: Hello Sen¶

In this tutorial you will build the simplest possible Sen application: a single object that updates a property each cycle and exposes a method. By the end, you will have a running kernel, a live object visible in the term, and a clear picture of how Sen's pieces fit together.

What you'll learn:

• The STL → code generation → C++ → YAML → run workflow
• How to define properties and methods in STL
• How to implement a generated base class
• How to stage property updates with setNext and why that matters
• How to use the term to inspect a live object

Prerequisites: Sen installed, basic C++ knowledge, and the activation script sourced in the shell you are about to work in:

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

Having sen on your PATH is not enough. The script also exports SEN_PREFIX, which is what lets find_package(sen REQUIRED) succeed in Step 4. Without it, cmake fails at configure time with "Could not find a package configuration file provided by sen". See Getting Sen.

What we're building¶

A simple counter object that increments a value every drain-update-commit cycle and exposes a hello method. Nothing exciting, but it touches every part of the workflow in the most direct way possible.

Step 1: Create the package skeleton¶

Sen can generate the folder structure for you:

sen package init my_counter --class Counter
cd my_counter

This creates:

my_counter/
    ├── CMakeLists.txt  # (1)!
    ├── config.yaml     # (2)!
    ├── src/
    │   ├── counter.cpp
    │   └── counter.h
    └── stl/
        └── my_counter/
            ├── basic_types.stl
            └── counter.stl  # (3)!

1. Tells CMake how to build the package. Uses add_sen_package(), a function Sen provides.
2. A ready-to-run configuration file that instantiates the object and opens a shell.
3. The interface definition for your Counter class. You will edit this next.

Step 2: Define the interface¶

Open stl/my_counter/counter.stl and replace its contents with this:

package my_counter;
class Counter
{
  // The current value of the counter.
  var value : i32;

  // How much should the counter increase each cycle.
  var step : i32 [static];

  // Returns a greeting message.
  fn hello() -> string [const];

  // Emitted each time the current value is divisible by 10.
  event valueIsDivisibleByTen(newValue: i32);
}

package my_counter declares the namespace, so everything defined here belongs to it.

value is dynamic and read-only: your object updates it each cycle, and other components can read it. step is static, so it is set at construction and never changes, and you will set it in config.yaml. hello() is marked const, so it cannot change the object. valueIsDivisibleByTen is an event, and any component can subscribe to it.

Step 3: Implement the class¶

The header¶

Edit src/counter.h:

// === counter.h =======================================================================================================
//                                               Sen Infrastructure
//                   Released under the Apache License v2.0 (SPDX-License-Identifier Apache-2.0).
//                                    See the LICENSE.txt file for more information.
//                   © Airbus SAS, Airbus Helicopters, and Airbus Defence and Space SAU/GmbH/SAS.
// =====================================================================================================================
#pragma once

#include "stl/my_counter/counter.stl.h"  // (1)!

// sen
#include "sen/kernel/component_api.h"

namespace my_counter
{

class CounterImpl: public CounterBase  // (2)!
{
public:
  SEN_NOCOPY_NOMOVE(CounterImpl)  // (3)!

  using CounterBase::CounterBase;
  ~CounterImpl() override = default;

public:
  void update(sen::kernel::RunApi& runApi) override;  // (4)!

protected:
  std::string helloImpl() const override;  // (5)!
};

}  // namespace my_counter

1. The code generator produces this header from your STL file. It contains CounterBase and all the generated plumbing.
2. You always inherit from the generated base class. It handles serialization, subscriptions, and method dispatch. You just fill in the logic.
3. A helper macro that deletes the copy and move constructors.
4. Called once per cycle during the update stage. This is where you compute your next state.
5. The generated base class declares helloImpl as a pure virtual method. You must implement it.

The implementation¶

Edit src/counter.cpp:

// === counter.cpp =====================================================================================================
//                                               Sen Infrastructure
//                   Released under the Apache License v2.0 (SPDX-License-Identifier Apache-2.0).
//                                    See the LICENSE.txt file for more information.
//                   © Airbus SAS, Airbus Helicopters, and Airbus Defence and Space SAU/GmbH/SAS.
// =====================================================================================================================
#include "counter.h"

// sen
#include "sen/core/meta/class_type.h"
#include "sen/kernel/component_api.h"

// std
#include <string>

namespace my_counter
{

void CounterImpl::update(sen::kernel::RunApi& /*runApi*/)
{
  setNextValue(getValue() + getStep());  // (1)!

  if (getNextValue() % 10 == 0)
  {
    valueIsDivisibleByTen(getNextValue());  // (2)!
  }
}

std::string CounterImpl::helloImpl() const
{
  return "Hello from Sen! My current value is: " + std::to_string(getValue());
}

// (3)!
SEN_EXPORT_CLASS(CounterImpl)

}  // namespace my_counter

1. getValue() and getStep() read from the current buffer, the frozen snapshot that Sen prepared during the drain stage (the first of the cycle's three stages, explained in What just happened? below). These values will not change during this update cycle. setNextValue() writes to the next buffer. The new value is not visible yet. It becomes visible to all components after Sen commits the outputs. getNextValue() reads that next buffer back, which is how the line below tests the value it has just written instead of last cycle's.
2. Fires the valueIsDivisibleByTen event with the new value. Like property changes, events are buffered and delivered after commit.
3. This macro registers CounterImpl as a class that Sen's kernel can instantiate. Without it there is no build error, but the kernel stops at startup with could not find type 'my_counter.CounterImpl' in any of the imported libraries, naming the symbol it looked for.

Step 4: Configure and run¶

Edit config.yaml so it looks like this:

load:
  - name: term   # (1)!
    group: 2
    open: [local.counters]  # (2)!

build:
  - name: counterComponent
    freqHz: 2      # (3)!
    group: 3
    imports: [my_counter]  # (4)!
    objects:
      - class: my_counter.CounterImpl  # (5)!
        name: myCounter
        step: 5         # (6)!
        bus: local.counters  # (7)!

1. Load the term component so we can interact with the running system.
2. Automatically open this bus in the term so we can see objects without typing open manually.
3. The component (and all its objects) will call update() twice per second.
4. Tell Sen to load your package so it can find CounterImpl.
5. The C++ class you registered with SEN_EXPORT_CLASS, qualified by its package. This is not the STL class name: the term below shows the same object as my_counter.Counter, the class it implements.
6. Initial value for the step static property. Required: static properties must have a value.
7. The bus where your object will be published. Must match what the term opens.

Now build and run:

cmake -S . -B build && cmake --build build
export LD_LIBRARY_PATH="$(pwd)/build/lib:$LD_LIBRARY_PATH"
sen run config.yaml

Step 5: Explore the object¶

The term opens automatically. Its prompt shows your scope, which starts at the root, so it reads sen:/❯. Start with ls, which draws what it can see as a tree:

❯ ls
└─┬ local [session]
  └─┬ counters [bus]
    └── myCounter [my_counter.Counter]

local is the session, counters is the bus we opened, and myCounter is your object with its class beside it.

cd moves into the bus, which shortens what you have to type and narrows what ls shows:

❯ cd local.counters
sen:/local.counters❯ ls
└── myCounter [my_counter.Counter]

inspect prints the interface, which is the fastest way to confirm the generator understood your STL:

❯ inspect myCounter
my_counter.Counter
Properties
├ value : i32  The current value of the counter.
└ step : i32  How much should the counter increase each cycle.
Methods
└ hello() → string  Returns a greeting message.
Events
└ valueIsDivisibleByTen(newValue: i32)  Emitted each time the current value is divisible by 10.

The descriptions come straight from the comments in your STL. value is the one the component updates each cycle and step is the one the configuration set.

Read-only and read-write are about everyone else, not about you: you always set your own properties with setNext<Prop>(). value is a plain var, so nobody outside can write it. step is [static], and that is what makes it settable from the configuration. Declaring a dynamic property [writable] opens it to other objects in the same way.

Now read the properties. A getter prints the name and the value:

❯ myCounter.getValue
  value: 20
❯ myCounter.getValue
  value: 40
❯ myCounter.getStep
  step: 5

Your numbers will differ from these, and that is the point: at 2 Hz with step: 5 the value climbs by ten every second for as long as the kernel runs, so what you see depends on how long it has been up and how fast you type. step does not move, because it is static.

That coupling is deliberate here and fine for a counter. A value that should advance per second, and not per cycle, has to read the time instead, which the execution model shows how to do.

Calling the method returns a string. A call in flight shows a spinner with the time it has been out, and finishes with a tick and the result:

✓ myCounter.hello
  "Hello from Sen! My current value is: 30"

Finally, shutdown stops the kernel:

❯ shutdown
  Shutting down...

What just happened?¶

Here is the execution in plain English:

1. sen run config.yaml starts the kernel. It reads the config, loads the shell component (group 2), then builds the counterComponent (group 3). Groups ensure the term is ready before the component starts.

2. CounterImpl is instantiated with step = 5 and registered on the local.counters bus. The term sees it immediately because it has the bus open.

3. Every 500 ms (2 Hz), the kernel runs the drain-update-commit cycle for counterComponent:

4. Drain: Sen delivers any pending method calls and property changes.
5. Update: Sen calls CounterImpl::update(). You read getValue() (frozen snapshot), compute the next value, and call setNextValue() (writes to back buffer). The event is also staged.

6. Commit: Sen atomically flips the buffers. The new current value is now visible to everyone. The valueIsDivisibleByTen event is delivered to any subscribers.

7. When you called hello in the term, the kernel queued the method call. On the next drain, helloImpl() executed, and returned a string. Your shell received the result via a callback.

Next steps¶

• Tutorial 2: Two objects talking: learn how objects discover each other and make async method calls.
• Understanding Sen: a mental model: a deeper explanation of the drain-update-commit cycle and how Sen differs from other systems.
• Working with objects: the full how-to reference for properties, methods, events and subscriptions.