Introduction

Veecle OS is a programming framework that enables developers to write software for low-power embedded devices and high-powered systems alike. Veecle OS uses features from the Rust programming language to help software developers avoid common complexities. For example:

With the actor model Veecle OS provides, developers can create concurrent programs on single-core processors.
Veecle OS provides an operating system abstraction layer (OSAL) so that Veecle OS programs can run on different platforms, such as embedded devices or Unix derivatives.

Because Veecle OS programs are Rust programs, they gain some of the advantages that Rust provides:

By confining unsafe operations to unsafe sections, memory and thread safety problems can only occur in restricted areas of the program, reducing review effort.

By using Veecle OS, a developer can start prototyping a program on their computer without the difficulties of developing on an embedded device. As their program takes shape, the developer can add any necessary adaptations required for their embedded device target. The developer can develop and troubleshoot many issues inside a full development environment, and only address embedded problems in the more limited embedded development environment.

Veecle OS also provides other features:

Veecle OS provides code that enables developers to collect structured telemetry in all environments. With veecle-telemetry, the Veecle OS framework and Veecle OS programs can record structured events with additional information about temporality and causality. Veecle OS provides tools to inspect traces.
Veecle OS provides utilities for writing tests for Veecle OS programs.
Veecle OS provides libraries for data formats and communication protocols such as:
- CAN
- SOME/IP (work in progress)
Veecle OS provides OSALs for platforms such as:
- std for operating systems supported by Rust, such as Linux or macOS.
- FreeRTOS for FreeRTOS.
- Embassy for Embassy.

Refer to getting started for a guide to write a minimal Veecle OS program. Framework provides an overview over the Veecle framework.

Refer to the Rust documentation for the veecle-os crate for further details on Veecle OS.

Getting started

This document describes how to create and run a minimal Veecle OS application.

Setting up a package

Create an empty package with cargo new and change to the package directory:

cargo new foo
cd foo

By structuring Veecle OS programs in a specific way, you can write Veecle OS programs that run on multiple platforms. Because this example runs only on platforms that provide the Rust std library, the example uses a smaller structure that is not suitable for Veecle OS programs that run on multiple platforms. (Refer to other examples to learn the structure for Veecle OS programs that can run on multiple platforms.)

Run the following commands to add the Veecle OS framework crate with the std operating system abstraction layer (OSAL):

cargo add veecle-os --features osal-std

Writing Veecle OS code

Veecle OS programs contain actors. Actors read inputs and write outputs using runtime channels. The runtime stores marked Rust types. Actors run concurrently by using async programming.

This example contains two actors:

sender_actor writes a Value, then loops.
receiver_actor waits to read a Value, prints the Value, then loops.

Defining the storable types

First, define the Value type by copying the following code into src/main.rs:

//! Getting started example.
use core::convert::Infallible;
use core::fmt::Debug;

use veecle_os::runtime::{InitializedReader, Storable, Writer};

#[derive(Debug, Clone, PartialEq, Eq, Default, Storable)]
#[storable(data_type = "u32")]
pub struct Value;

By implementing Storable with the data_type u32, Value becomes an identifier for readers and writers. Any reader or writer that uses Value will read or write the data_type, in this case u32. The data_type must implement the Debug trait so that logs can show its debug representation.

Storable can also be implemented manually. See the veecle_os::runtime::Storable documentation for more information.

Implementing actors

You can implement actors in multiple ways. This example uses the actor macro, that defines an actor from a Rust function.

In this example, the actors use InitializedReaders and Writers to communicate with other actors.

Copy the following actors into src/main.rs:

/// An actor that writes `Value { i++ }` continuously.
#[veecle_os::runtime::actor]
async fn sender_actor(mut writer: Writer<'_, Value>) -> Infallible {
    let mut value = 0;
    loop {
        println!("[sender] Sending {:?}", value);
        writer.write(value).await;
        value += 1;
    }
}

/// An actor that reads `Value` and terminates when the value is 5.
#[veecle_os::runtime::actor]
async fn receiver_actor(mut reader: InitializedReader<'_, Value>) -> Infallible {
    loop {
        println!("[receiver] Waiting for value");
        reader.wait_for_update().await.read(|value| {
            println!("[receiver] Received: {value:?}");
            if *value == 5 {
                println!("[receiver] Exiting because value is 5");
                // Actors should never terminate. This program ends so it always generates the same short output that is
                // easy to verify.
                std::process::exit(0);
            }
        });
    }
}

receiver_actor uses std::process::exit to exit the program when it receives 5.

Actors should never terminate. In case of unrecoverable errors, actors should return an error. This program ends so it always generates the same short output that is easy to verify.

Implementing the Veecle OS program

Currently, Veecle OS programs have an entry point implemented according to the platform that the Veecle OS program runs on. std Veecle OS programs require Tokio as their async runtime. This is set up by the veecle_os::osal::std::main macro.

Copy the following code into src/main.rs to implement a Veecle OS program entry point:

#[veecle_os::osal::std::main]
async fn main() {
    veecle_os::runtime::execute! {
        store: [Value],
        actors: [ReceiverActor, SenderActor],
    }
    .await;
}

The main function uses veecle_os::runtime::execute! to create and execute a runtime instance that knows about the Value datatype and both actors.

Running the Veecle OS program

(See the end of this document for a complete listing of src/main.rs.)

To execute the Veecle OS program, run the following command:

cargo run

Appendix: the complete Veecle OS program

//! Getting started example.
use core::convert::Infallible;
use core::fmt::Debug;

use veecle_os::runtime::{InitializedReader, Storable, Writer};

#[derive(Debug, Clone, PartialEq, Eq, Default, Storable)]
#[storable(data_type = "u32")]
pub struct Value;

/// An actor that writes `Value { i++ }` continuously.
#[veecle_os::runtime::actor]
async fn sender_actor(mut writer: Writer<'_, Value>) -> Infallible {
    let mut value = 0;
    loop {
        println!("[sender] Sending {:?}", value);
        writer.write(value).await;
        value += 1;
    }
}

/// An actor that reads `Value` and terminates when the value is 5.
#[veecle_os::runtime::actor]
async fn receiver_actor(mut reader: InitializedReader<'_, Value>) -> Infallible {
    loop {
        println!("[receiver] Waiting for value");
        reader.wait_for_update().await.read(|value| {
            println!("[receiver] Received: {value:?}");
            if *value == 5 {
                println!("[receiver] Exiting because value is 5");
                // Actors should never terminate. This program ends so it always generates the same short output that is
                // easy to verify.
                std::process::exit(0);
            }
        });
    }
}

#[veecle_os::osal::std::main]
async fn main() {
    veecle_os::runtime::execute! {
        store: [Value],
        actors: [ReceiverActor, SenderActor],
    }
    .await;
}

Framework

The Veecle framework provides a runtime and supporting tools for developing event-driven applications.

Runtime

The runtime provides the means to build applications using an actor model. This allows the decomposition of functionality into multiple actors communicating via messages. Messages are exchanged between actors via an integrated central communication hub of the application. With the operating system abstraction layer (OSAL) developers can create OS-agnostic code. This allows moving applications and actors between different target operating systems with minimal changes to the application. An instance of the runtime provides the communication hub, and an executor to drive the actors.

Actors

Actors are the basic building blocks of an application. They can be reused across projects and composed to build complex applications. An actor’s interface is made up of message readers and writers and some optional initialization context. The readers and writers are used to communicate between actors. The initialization context allows passing data into an actor that might have to be set up before the executor can take over control (e.g. shared memory, peripherals, etc.).

At their core, actors are asynchronous functions. They wait for events to happen and react accordingly. When an event that an actor is waiting for occurs, the actor gets scheduled by the executor. Events can for example be a timer expiring or a new value being written by another actor.

In Rust, asynchronous functions are inherently lazy and only do work if they are driven by an executor. In practice, this means actors are polled by the executor if an event they are waiting for occurs. The only exception is on startup of the executor, when the executor polls every actor once. This ensures every actor gets a chance to initialize without an event occurring. The order in which the actors are polled in is fixed, but actors without work to do are skipped to reduce resource usage. Actors are expected not to exit, but to either indefinitely process events or to report themselves as not having work to do (in Rust terms: pending). On fatal errors, actors can return an error to indicate their status to the runtime. Within a single instance of the runtime, all actors are driven concurrently by a single executor.

Rust offers the official Rust book and Rust async book for more in-depth information regarding asynchronous programming in Rust.

Communication hub

The runtime provides a central communication hub between actors, a place where actors can store and retrieve messages from. For each message type, the hub internally uses a slot. The slot represents an allotted space for this message type. Readers and writers transparently allow access to the message in the slot. With every message type being associated with a single slot, every message type within the store has to be unique. Multiple readers for the same type of message are automatically using a single shared slot.

There must always be exactly one writer per message type, producing messages for at least one reader. This prevents accidental misconfiguration where slots are not being written to or read from. At startup, the runtime validates its configuration and exits (in Rust terms panics) if an invalid configuration is detected. All slots before an actor writes to them are initially set to None.

Each instance of the runtime provides a single communication hub to be shared between all actors of the instance.

Operating System Abstraction Layer (OSAL)

The operating system abstraction layer (OSAL) provides OS-agnostic interfaces to interact with OS-provided functionality (e.g. time). By abstracting over the concrete OS interface, actors can make use of OS-provided functionality without requiring OS-specific code. This allows developing actors portable between supported target operating systems.

Check out the OSAL chapter for further details.

Tooling

OSAL

Building Veecle applications that can run on different operating systems requires the framework to define an API actors can rely on. To achieve this, the framework provides an Operating System Abstraction Layer (OSAL), enabling to build OS agnostic Veecle applications and reuse its components across different environments.

Crates

The Veecle OSAL is structured in two layers:

Definitions

The veecle_os::osal::api module defines a collection of traits and data structures that abstract over functionality typically provided by the underlying operating system.

This functionality is meant for building actors and applications regardless of where they will run. This ensures the components remain as decoupled as the framework, being portable across different environments.

Implementations

If veecle_os::osal::api is the specification layer, the other modules within veecle_os::osal are the implementations for the different environments.

The available implementations include:

veecle_os::osal::std for platforms supported by the Rust Standard Library.
veecle_os::osal::freertos for FreeRTOS.
veecle_os::osal::embassy for Embassy.

These are the environments supported by Veecle, but users may build their own implementations as needed.

OSAL implementations are meant for specifying the target platform during the runtime’s construction. This is usually done in the corresponding main.rs file. The components of Veecle applications should never rely on concrete implementations, but on the Definitions instead.

See the time documentation for a practical example.

Crates and tools

Installing the `veecle-telemetry-ui` graphical telemetry viewer

Run the following command to install the veecle-telemetry-ui graphical telemetry viewer.

cargo install veecle-telemetry-ui

Installing the `veecle-telemetry-ui` Visual Studio Code extension

Download the VSIX package file from https://veecle-telemetry-vscode-extension.pages.dev/veecle-telemetry-ui.vsix.

In Visual Studio Code, invoke the “Extensions: Install from VSIX” command and select the downloaded VSIX package.

Testing

Use the veecle_os_test crate to test actors.

Telemetry

Veecle OS has features to learn about the execution of Veecle OS applications.

The veecle-telemetry crate provides functions to add events and spans to Rust programs.

The Veecle OS crates themselves are instrumented, and you can instrument your code with the veecle_os::telemetry macros. Veecle OS applications can use a collector to define where these events and spans are sent.

For example, with a Veecle OS application that emits serialized traces, you can use probe-rs to run the application on an embedded device and pipe the serialized data for further processing.

Configuring applications to emit serialized traces

For std applications, annotate your main function as follows:

#[veecle_os::osal::std::main(telemetry = true)]

The main macro configures veecle_os::telemetry to send traces as logs to the log target implementation from the std OSAL. This log target prints logs to the standard output. The result is that the Veecle OS application prints serialized traces to standard output.

Viewing serialized traces

See installing the veecle-telemetry-ui graphical telemetry viewer.

If cargo run ... starts a program that emits serialized traces, then you can pipe the traces into veecle-telemetry-ui to read and display telemetry in real time:

cargo run ... | veecle-telemetry-ui

Alternatively, if x.trace.jsonl contains serialized traces, then you can use the veecle-telemetry-uito visualize the telemetry:

veecle-telemetry-ui x.trace.jsonl

Legal and Licensing

Open Source Compliance

Veecle OS is built using various open-source libraries and dependencies. If you distribute applications built with Veecle OS, you may need to include license attribution for the third-party libraries Veecle OS uses.

The specific requirements depend on your distribution method and the licenses involved. Generally, including the attribution information with your distributed software satisfies these obligations.

Refer to the Third-Party Notices section for the complete list of dependencies and their licenses. Note that this list includes licenses for all components of Veecle OS; in a typical deployment only a small subset of these dependencies would actually be used.

Third-Party Notices

This document lists the licenses of the third-party dependencies used in Veecle OS under various open-source licenses.

This document was automatically generated. No functionality in—or information provided by—this document constitutes legal advice.

Keyboard shortcuts

User Manual