Skip to content

Command Line Tools

Sen comes with a command line application (called sen) to help you perform some actions following the approach taken by git.

The best way to familiarize yourself with all the commands and the available options is to do --help, starting with sen --help.

Welcome to sen

Usage: sen [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help    Print this help message and exit
  --version    Display program version information and exit

Subcommands:
  run          Run a sen kernel
  generate     Generate code (mainly used by build systems)
  archive      Inspect archives
  package      Create or manipulate sen packages
  file-to-array
               Simple utility to convert a file to a C++ array
  shell        Shortcut to run the sen shell stand-alone
  term         Shortcut to run the sen term stand-alone
  explorer     Shortcut to run the sen explorer stand-alone
  replay       Shortcut to run the sen replay stand-alone
  rshell       Shortcut to connect to a remote sen shell

For help on specific commands run 'sen <command> --help'

You can also get help about the specific sub-commands.

For example:

sen command line examples
# open a sen explorer window
sen explorer

# open a sen shell on the current terminal
sen shell

# connect to a remote sen application on localhost:8094
sen rshell localhost:8094

# starts a replay of an archive
sen replay my_archive

# runs a sen kernel from a configuration file
sen run my_config.yaml

Run

sen run
Run a sen kernel

Usage: sen run [OPTIONS] [config]

Positionals:
  config TEXT:PATH(existing)       Configuration file

Options:
  -h,--help                        Print this help message and exit
  --preset TEXT:{shell,explorer,replay}
                                   Preset name
  --start-stop                     Stop execution after all components are running
  --print-config                   Print the configuration that will be used

The configuration file uses YAML, and it has the following structure:

  • A "load" section, where we define the components to be loaded. You need to specify at least the name and the group. You can set all the parameters defined in the ComponentConfig structure. The rest of parameters are forwarded to the component.
  • A "build" section, where we define components to be built by the Sen kernel. You need to specify at least the name and the group. You can set all the parameters defined in the ComponentConfig structure. It also takes the following special entries:
  • "imports": a list of packages to import.
  • "objects": a list where you need to define the objects that will be instantiated. You can define the initial values that the object properties will have. There are three special entries:
    • "name": (required) The name of the instance. Must be unique within the component and bus (if any).
    • "class": (required) The name of the object's class.
    • "bus": (optional) The name of the bus where the object shall be published.
  • An optional "kernel" section, that takes the contents of the KernelParams structure.
example configuration file
load:
  - name: shell
    group: 2
    open: [ school.primary, school.secondary ]

build:
  - name: example
    group: 3
    freqHz: 30
    imports: [ school ]
    objects:
      - name: firstGrade
        class: school.ClassRoom
        studentsBus: school.primary
        bus: school.primary
        defaultSize: 5
        createTeacher: true
      - name: secondGrade
        class: school.ClassRoom
        studentsBus: school.secondary
        bus: school.secondary
        defaultSize: 10
        createTeacher: true

The ComponentConfig structure is defined as follows:

// Basic runtime configuration for a component
struct ComponentConfig
{
  priority   : Priority,     // thread priority
  stackSize  : u32,          // thread stack size in bytes, 0 means default
  group      : u32,          // the group where to run the component
  inQueue    : QueueConfig,  // queuing of inbound information
  outQueue   : QueueConfig   // queuing of outbound information
}

Regarding queues, they can be configured using the QueueConfig structure:

// Component queue eviction policy
enum QueueEvictionPolicy: u32
{
  dropOldest, // when full, drop the least recent element
  dropNewest, // when full, drop the most recent element
}

struct QueueConfig
{
  evictionPolicy : QueueEvictionPolicy, // what to do when the queue is full
  maxSize        : u64                  // 0 means unbounded
}

By default, queues are unbounded.

another example configuration file
load:
  # first, load the shell
  - name: shell
    group: 2

  # then, load our component
  - name: my_component_with_config
    group: 3
    someParam: a value
    someOtherParam: 5 s

Environment variables

The YAML sen parser supports using environment variable values directly by using @env(VARIABLE_NAME) pattern. The pattern can be escaped using the backslash \ character. If an even number backlash characters are found before the @env() pattern, they are rendered as half of them and the variable is also rendered. If the number is odd, they are rendered as half of them minus one and the env command value is not rendered.

The @env(VARIABLE_NAME) function also supports default values for when the variable is not found. It can be specified using @env(VARIABLE_NAME, DEFAULT_VALUE).

If the @env(VARIABLE_NAME) is used and the variable does not exist, a runtime error is thrown.

Consider the variables MY_COMP=FooComponent and MY_BUS=BarBus

another example configuration file
load:
  # first, load the shell
  - name: shell
    group: 2
    open: @env(MY_BUS) # Will throw if MY_BUS does not exist
  # then, load our component
  - name: @env(MY_COMP, defaultComponent) # rendered as - name: FooComponent
    group: 3
    someParam: a value
    someOtherParam: 5 s
    someEscape1: \env(MY_COMP, defaultComponent)        # rendered as env(MY_COMP, defaultComponent)
    someEscape2: \\env(MY_COMP, defaultComponent)       # rendered as \FooComponent
    someEscape3: \\\env(MY_COMP, defaultComponent)      # rendered as \env(MY_COMP, defaultComponent)
    someEscape4: \\\\env(MY_COMP, defaultComponent)     # rendered as \\FooComponent
    someEscape5: \\\\\env(MY_COMP, defaultComponent)    # rendered as \\env(MY_COMP, defaultComponent)
    someEscape6: \\\\\\env(MY_COMP, defaultComponent)   # rendered as \\\FooComponent
    someEscape7: \\\\\\\env(MY_COMP, defaultComponent)  # rendered as \\\env(MY_COMP, defaultComponent)
    someEscape8: \\\\\\\\env(MY_COMP, defaultComponent) # rendered as \\\\FooComponent

Combining yaml files

Since configurations can get very complex and repetitive, Sen provides an "include" mechanism for yaml files.

including yaml files
include:
  - shell.yaml
  - ether.yaml

# the rest of the configuration file, as usual
build:
  - name: myComponent
    group: 3
    freqHz: 10
    imports: [ my_package ]
    objects:
      - name: myObject
        class: my_package.MyClassImpl
        prop1: someValue
        bus: my.tutorial

Where:

shell.yaml
load:
  - name: shell
    group: 2
    open: [ my.tutorial ]
ether.yaml
load:
  - name: ether
    group: 3

Resulting in a yaml that Sen perceives as:

result
load:
  - name: shell
    group: 2
    open: [ my.tutorial ]
  - name: ether
    group: 3

build:
  - name: myComponent
    group: 3
    freqHz: 10
    imports: [ my_package ]
    objects:
      - name: myObject
        class: my_package.MyClassImpl
        prop1: someValue
        bus: my.tutorial

The include block contain a list of files (or a single file like indclude: shell.yaml), relative to the yaml file doing the inclusion. Inclusions are recursive (you can include files that include other files).

When including a file, it gets merged (or combined) with the contents of the current file. With this mechanism you can effectively do "unions" of configuration parameters. If parameters are repeated (the file you are including defines a configuration value that you also define in your file), the one in your file prevails.

For example, let's define another yaml file as follows:

my_component.yaml
build:
  - name: myComponent
    group: 3
    freqHz: 10
    imports: [ my_package ]
    objects:
      - name: myObject
        class: my_package.MyClassImpl
        prop1: someValue
        bus: my.tutorial

And now let's combine all three as such:

combination
include:
  - shell.yaml
  - ether.yaml
  - my_component.yaml

If we want to overwrite the value of prop1 of myObject in myComponent, we can do so like this:

combination
include:
  - shell.yaml
  - ether.yaml
  - my_component.yaml

build:
  - name: myComponent
    objects:
      - name: myObject
        prop1: someOtherValue

Note that you just need to define the things you want to overwrite. The resulting configuration as perceived by Sen would be like this:

result
load:
  - name: shell
    group: 2
    open: [ my.tutorial ]
  - name: ether
    group: 3

build:
  - name: myComponent
    group: 3
    freqHz: 10
    imports: [ my_package ]
    objects:
      - name: myObject
        class: my_package.MyClassImpl
        prop1: someOtherValue
        bus: my.tutorial

Code generator

sen generate
sen code generator

Usage: sen generate [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit
  --expect-failure                 Expect a failure in the generation process (for testing purposes)

Subcommands:
  cpp                              Generate C++ code
  uml                              Generate UML diagrams
  py                               Generate Python dataclasses
  mkdocs                           Generate MkDocs documentation
  json                             Generate JSON schemas

For help on specific commands run 'sen generate <command> --help'

C++

sen generate cpp
Generate C++ code
Usage: sen generate cpp [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit
  -r,--recursive BOOLEAN           Recursively generate imported packages
  --public-symbols                 Make generated classes public

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files
  exports                          Generate the export symbols file for a sen STL package

C++ from STL

sen generate cpp stl
Process STL files
Usage: sen generate cpp stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file

C++ from HLA FOMs

sen generate cpp fom
Process HLA FOM files
Usage: sen generate cpp fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -s,--settings TEXT:FILE          Code generation settings file

C++ exports

sen generate cpp exports
Generate the export symbols file for a sen STL package
Usage: sen generate cpp exports [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -p,--package TEXT                Name of the package to create the exports for
  -f,--file TEXT ...               Name of the STL file containing types
  -d,--depends TEXT ...            Names of the packages we depend on
  -i,--implements TEXT ...         Names of types implemented in this package

UML

Works the same way as C++, but with slightly different options.

sen generate uml
Generate UML diagrams
Usage: sen generate uml [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files

UML from STL

sen generate uml stl
Process STL files
Usage: sen generate uml stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output PlantUML file
  --only-classes Excludes: --only-types --no-enumerators
                                   Only generate class diagrams
  --only-types Excludes: --only-classes
                                   Only generate diagrams for basic types
  --no-enumerators Excludes: --only-classes
                                   Do not generate enumerations

UML from HLA FOMs

sen generate uml fom
Process HLA FOM files
Usage: sen generate uml fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output PlantUML file
  --only-classes Excludes: --only-types --no-enumerators
                                   Only generate class diagrams
  --only-types Excludes: --only-classes
                                   Only generate diagrams for basic types
  --no-enumerators Excludes: --only-classes
                                   Do not generate enumerations

MKDocs markdown

Works the same way as C++, but with slightly different options.

sen generate mkdocs
Generate MkDocs documentation
Usage: sen generate mkdocs [OPTIONS] SUBCOMMAND

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  stl                              Process STL files
  fom                              Process HLA FOM files

MKDocs from STL

sen generate mkdocs stl
Process STL files
Usage: sen generate mkdocs stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -t,--title TEXT                  Document title

MKDocs from HLA FOMs

sen generate mkdocs fom
Process HLA FOM files
Usage: sen generate mkdocs fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -t,--title TEXT                  Document title

JSON schemas

Generates json schemas from a Sen data model.

JSON schemas for Sen components from STL

Process STL files
Usage: sen generate json component stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -n,--name TEXT                   Name of the component

JSON schemas for Sen components from HLA FOMs

Process HLA FOM files
Usage: sen generate json component fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -n,--name TEXT                   Name of the component

JSON schemas for Sen packages from STL

Process STL files
Usage: sen generate json package stl [OPTIONS] stl_files...

Positionals:
  stl_files TEXT:FILE ... REQUIRED STL files

Options:
  -h,--help                        Print this help message and exit
  -i,--import TEXT ...             Paths where other STL files can be found
  -b,--base-path,--base_path TEXT  Base path for including generated files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -c,--class TEXT ...              Classes implemented by the user

JSON schemas for Sen packages from HLA FOMs

Process HLA FOM files
Usage: sen generate json package fom [OPTIONS]

Options:
  -h,--help                        Print this help message and exit
  -m,--mappings TEXT:FILE ...      XML defining custom mappings between sen and HLA
  -d,--directories TEXT:DIR ... REQUIRED
                                   Directories containing FOM XML files
  -s,--settings TEXT:FILE          Code generation settings file
  -o,--output TEXT                 Output file
  -c,--class TEXT ...              Classes implemented by the user

Combine multiple JSON schemas to create a kernel configuration schema

Generate JSON schemas for sen configurations
Usage: sen generate json schema [OPTIONS] schema_files...

Positionals:
  schema_files TEXT:FILE ... REQUIRED
                                   JSON schema files

Options:
  -h,--help                        Print this help message and exit
  -o,--output TEXT                 Output file

Archiving Utility

Helps you interact with archives.

sen archive
Recording inspection utility

Usage: sen archive [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help Print this help message and exit

Subcommands:
  info      Print basic information about an archive
  indexed   Print basic info about the indexed objects

For help on specific commands run 'sen archive <command> --help'

Basic information

sen archive info
Print basic information about an archive
Usage: sen archive info [OPTIONS] archive_path

Positionals:
  archive_path TEXT:DIR REQUIRED
            Archive path

Options:
  -h,--help Print this help message and exit

Indexed objects

sen archive indexed
Print basic info about the indexed objects
Usage: sen archive indexed [OPTIONS] archive_path

Positionals:
  archive_path TEXT:DIR REQUIRED
            Archive path

Options:
  -h,--help Print this help message and exit

Packaging Utility

sen package
Create or manipulate sen packages

Usage: sen package [OPTIONS] [SUBCOMMAND]

Options:
  -h,--help                        Print this help message and exit

Subcommands:
  init                             Start a package working area
  init-component                   Start a component working area

Package skeleton creation

sen package init
Start a package working area
Usage: sen package init [OPTIONS] path

Positionals:
  path TEXT REQUIRED               Path

Options:
  -h,--help                        Print this help message and exit
  --class TEXT REQUIRED            Name of a class

Component skeleton creation

sen package init-component
Start a component working area
Usage: sen package init-component [OPTIONS] path

Positionals:
  path TEXT REQUIRED               Path

Options:
  -h,--help                        Print this help message and exit
  --with-config Excludes: --full   Include STL and template for configuration
  --full Excludes: --with-config   Include configuration and implementation of all methods

File to array utility

sen file-to-array
Simple utility to convert a file to a C++ array
Usage: sen file-to-array [OPTIONS]

Options:
  -h,--help    Print this help message and exit
  -i TEXT:FILE REQUIRED
               File to read
  -o TEXT REQUIRED
               File to write
  -v TEXT REQUIRED
               Name of the variable that will hold the data