Getting Started

Welcome to Xronos! This guide will walk you through everything you need to get up and running, from installation to your first working program.

System Requirements

Before you begin, make sure your environment meets the following requirements:

• A manylinux_2_35 compliant Linux distribution. We recommend Ubuntu 22.04 or newer.

• Python version 3.10, 3.11, 3.12, or 3.13

Installation

We recommend working in a virtual environment to keep your project dependencies isolated. Use the following commands to create and activate a new environment called .venv.

$ python -m venv .venv
$ source .venv/bin/activate

Then install the xronos package:

$ pip install xronos

Hello World

Let’s write your first Xronos program. Create a file called hello.py and paste the following content into it.

plainwith type hints

import xronos


class Hello(xronos.Reactor):
    @xronos.reaction
    def hello(self, interface):
        interface.add_trigger(self.startup)
        return lambda: print("Hello, World!")


def main():
    env = xronos.Environment()
    env.create_reactor("hello", Hello)
    env.execute()


if __name__ == "__main__":
    main()

Run the program:

$ python hello.py
Hello, World!

Now let’s walk through what this program does. The building blocks of the Xronos SDK are called reactors. You can define a new reactor by subclassing the xronos.Reactor base class. The example above defines a new reactor class called Hello.

The behavior of a reactor is defined by its reactions. A new reaction can be defined using the @xronos.reaction decorator on a reactor method. The decorated method accepts a single argument of type xronos.ReactionInterface and returns a callable object (e.g. a function) that implements an event handler. Our example reactor defines a single reaction called hello:

plainwith type hints

@xronos.reaction
def hello(self, interface):
    interface.add_trigger(self.startup)
    return lambda: print("Hello, World!")

Xronos programs are event-driven. Reaction handlers run automatically in response to one or more triggering events. The interface object is how you declare which events trigger a reaction. In our example, hello is triggered by the builtin startup event. As we will discuss later, the interface can also be used to define effects, which allow reactions to trigger new events. The reaction handler returned by hello is a simple lambda function that prints “Hello, World!”.

Finally, the main() function assembles and executes the program.

def main() -> None:
    env = xronos.Environment()
    env.create_reactor("hello", Hello)
    env.execute()

We start by creating a xronos.Environment object, which we call env. The environment manages the execution of any reactors created using the create_reactor() factory method. In our example, we create a reactor called “hello” that is an instance of the Hello class. Once your reactors are set up, execute() starts the execution of all previously created reactors.

Every Xronos program can be rendered into a diagram that visualizes its reactors and their relationships. Here is the diagram for our hello world example.

See Diagram View for instructions on how to generate a diagram view.

Suggested development setup

Once you have the basics working, the following tools can make your development experience more productive.

Editor integration

We recommend Visual Studio Code for editing Xronos projects. It works well with diagram generation and supports on-target development or development on a remote machine over SSH.

See Installation for instructions on how to install the Xronos VS Code extension and for the VS Code extension’s system requirements.

Telemetry dashboard

See Dashboard for setup instructions and system requirements for viewing telemetry data from Xronos applications.

Enabling type checking

To get the most out of the Xronos SDK, we recommend enabling type checking using Pyright or Mypy. Both are well supported, and there are a few ways to configure them.

Microsoft’s Pylance VS Code extension provides Pyright-based type checking, which can be enabled by placing a pyrightconfig.json file such as the following in the root of your project:

{
    "typeCheckingMode": "strict"
}

Alternatively, you can use the following configuration in your pyproject.toml:

[tool.pyright]
typeCheckingMode = "strict"