Create a Real-Time Task

Table of Contents

• • Real-Time Tasks Function Library
    • 🔹 Understand the architecture
    • ⚠️ Important Note
    • ✅ Prerequisites
    • 🚀 Quickstart
    • ⚙️ Set up your project
    • 📂 Layout
      • How it works
    • 📜 Create an RTTask functions library
      • Create a global variable
      • Create a task function
      • Optional: Build to a custom library name and directory
    • 🚀 Launch your tasks
      • Optional: Using a custom function library
  • ❓ FAQ

Learn how to create a Real-Time Task (RTTasks).

PREMIUM FEATURE

Recommended

This guide will help you integrate RTTasks into your application. If you're new to RTTasks or want to better understand how they work, refer to the following resources:

• Read the Real-Time Tasks 📖 concept page for an overview
• Explore the Real-Time Tasks 📜 examples to see how to use the API

Real-Time Tasks Function Library

This project, located in the examples/ folder under your RMP install directory (e.g., C:/RSI/X.X.X/examples/ or /rsi/examples/), is a CMake template for building a task functions library for use with Real-Time Tasks (RTTasks).

RTTasks offer a powerful API for responding to input with strict timing guarantees. This guide describes an example project that will move an axis in response to an analog input.

🔹 Understand the architecture

Before writing code, make sure you understand how the pieces fit together:

• RTTaskManager (Firmware) – Distributed with RMP, the manager runs inside the real-time operating system, loads the RTTaskFunctions library, and schedules the functions according to their configured periods and priorities.
• RTTask (Execution Unit) — Represents an individual real-time function instance managed by the RTTaskManager. Each task runs at a defined priority and period.
• RTTaskFunctions library (Real-Time Logic) – This C++ project produces a shared library of deterministic task functions and the accompanying GlobalData definition. It cannot run on its own. The RTTaskManager loads and executes the functions from this library at runtime.
• GlobalData (Shared Memory Bridge) — A structured data block defined in the RTTaskFunctions project that both environments can safely access. RTTasks read or write GlobalData members inside the real-time loop, while the user application reads or updates those values from the host side using the RealTimeTasks API.
• User application – Runs in the non-real-time environment using RapidCode (C++, C#, or Python) or RapidCodeRemote (any gRPC-capable language). It communicates with the RTTaskManager to submit, monitor, and control tasks. It can also read and write to GlobalData through methods in the RealTimeTasks API. All high-level logic remains here, outside the real-time environment.

Keeping these boundaries clear prevents common mistakes and confusion. The RTTaskFunctions project used in this guide defines the RTTaskFunctions library and the GlobalData. It will not be runnable on its own. You will need to start the RTTaskManager separately and submit the tasks to it. You can start the RTTaskManager through the RealTimeTasks API, the rsiconfig utility, or the command line. For more information on using the RealTimeTasks API refer to the Real-Time Tasks concept page in the documentation.

⚠️ Important Note

These samples focus on demonstrating API usage. They may not include the complete safety logic required for your machine. When working with real hardware always wire an external emergency stop, verify limits, and start with conservative motion constants.

✅ Prerequisites

Before generating or building Real-Time Tasks, make sure your development environment meets these requirements:

• Windows hosts:
  • Visual Studio 2022 with the “Desktop development with C++” workload and CMake integration component (“C++ CMake tools for Windows”).
  • Install either the INtime Runtime (CDEV) or the INtime SDK if you plan to deploy or run RTTasks on an INtime node. Without either you can still build and test RTTasks on Windows, but it will not have real-time performance.
• Linux hosts:
  • A recent GCC or Clang toolchain.
  • The distribution’s standard build tools (for example, install build-essential on Debian/Ubuntu).
• CMake 3.15 or newer

For environment setup and Visual Studio generator scripts, see the documentation for the C++ sample applications. For conceptual background and runtime behavior, refer to the Real-Time Tasks concept page in our docs.

🚀 Quickstart

To get up and running quickly, follow these steps:

• Copy the RTTaskFunctions (found in the examples folder) into your project
• Add any required global variables to src/rttaskglobals.h
• Define your task functions in src/rttaskfunctions.cpp, using Increment as a template
• Build the shared library using CMake
• In your application, create an RTTaskManager and use TaskSubmit to launch your tasks from the shared library

For a more detailed walkthrough, continue below.

⚙️ Set up your project

The examples folder in your RMP installation includes a CMake project called RTTaskFunctions. This serves as a starting point for building a shared library containing RTTask functions. Copy this folder into your project directory and rename it appropriately.

Note: If you plan to use Visual Studio to manage your project, then run the generator script for your Visual Studio version (located in examples/VisualStudioGeneratorScripts/) before copying the project folder. This will generate a Visual Studio solution inside examples/RTTaskFunctions/VisualStudio.

Here is an overview of the key files:

📂 Layout

RTTaskFunctions/
├── CMakeLists.txt           # CMake setup for building the shared library
└── src/
    ├── rttaskglobals.h      # Defines Global variables
    └── rttaskfunctions.cpp  # Task function implementations

How it works

The template project takes all the source files (.h, .cpp) in the src/ directory and compiles them into a shared library for the target platform (Windows/INtime or Linux). It automatically includes the RMP headers, links the RMP libraries, and applies necessary configuration for use with RTTasks. The output is a .dll/rsl/.so file that will be loaded by the RTTaskManager. There is no standalone executable produced by this project, so you must launch a manager instance separately.

By default, the resulting library is named RTTaskFunctions and is output to the default RMP install directory (e.g., /rsi or C:/RSI/X.X.X). If these paths or names are modified, you must specify them explicitly when submitting a task from your application. Otherwise, they will be discovered automatically.

If you want to change any of the default behavior or are interested in learning more about how it works, then look at the CMakeLists.txt located in the root of the project folder.

📜 Create an RTTask functions library

In this guide, you’ll build a simple application that moves an axis based on the value of an analog input. It will use one global variable and two RTTasks. The first task, CalculateTarget, reads the analog input and calculates a target position, storing it in the global variable targetPosition. The second task, FollowTarget, moves the axis to the specified target.

Create a global variable

Open src/rttaskglobals.h. This file is where the global variables are defined and registered before being exposed to the host through the RealTimeTasks API.

To add a new global of type double called targetPosition:

• Add RSI_GLOBAL(double, targetPosition) to the GlobalData struct
• Add REGISTER_GLOBAL(targetPosition) to the GlobalMetaDataMap

The result should be:

struct GlobalData
{
  GlobalData() { std::memset(this, 0, sizeof(*this)); }
  GlobalData(GlobalData&& other) { std::memcpy(this, &other, sizeof(*this)); }
 
  // A shared integer counter
  RSI_GLOBAL(int64_t, counter);
 
  // Shared values for FollowSensor
  RSI_GLOBAL(int32_t, startingSample);
  RSI_GLOBAL(double, sensorValue);
 
  //... other globals
 
  RSI_GLOBAL(double, targetPosition);
  RSI_GLOBAL(double, potentialTarget);
};
 
inline constexpr GlobalMetadataMap<RSI::RapidCode::RealTimeTasks::GlobalMaxSize> GlobalMetadata(
{
  REGISTER_GLOBAL(counter),
  REGISTER_GLOBAL(startingSample),
  REGISTER_GLOBAL(sensorValue),
  //... other globals
  REGISTER_GLOBAL(targetPosition),
  REGISTER_GLOBAL(potentialTarget),
});

Create a task function

Open src/rttaskfunctions.cpp. This is the file where the task functions are defined. A task function must follow this template:

RSI_TASK(FunctionName)
{
  ...
}

The example below splits execution into two tasks: CalculateTarget and FollowTarget. This is to demonstrate using shared memory for inter-task communication. Real-world integrations would use multiple RTTasks when they need different priorities, periods, or life cycles.

We will add a new task function called CalculateTarget that will read the analog input, scale it to a value between 0 and 1, and store it in the global created in the previous step.

// This task reads the analog input value from the network node, scales it to 
// a value between 0 and 1, and stores it in the targetPosition variable
RSI_TASK(CalculateTarget)
{
  constexpr int NODE_INDEX = 0;         // The network node with the analog input
  constexpr int ANALOG_INDEX = 0;       // The index of the analog input to use
  constexpr int ANALOG_MAX = 65536;     // Max value of the analog input
 
  // Note: This example assumes your analog input ranges from [0, ANALOG_MAX]
  //       Complicated inputs may need more manipulation to bring it between 0 and 1
  
  // Read the raw analog input value
  int32_t analogInVal = RTNetworkNodeGet(NODE_INDEX)->AnalogInGet(ANALOG_INDEX);
 
  // Scale the value to be between 0 and 1
  double newTarget = double(analogInVal) / ANALOG_MAX;
 
  // Store that in the shared global newTarget
  data->potentialTarget = scaledVal;
}

Then we will add another task function called FollowTarget that will move the axis towards the target position.

For tasks involving RapidCode objects, rttaskglobals.h includes the functions RTMotionControllerGet(), RTAxisGet(), RTMultiAxisGet(), and RTNetworkNodeGet() for your convenience. For more information, see the Concepts > General > Real-Time Tasks page in our docs.

// This task moves the axis to the target position if it is not within the tolerance
// of the target position already.
RSI_TASK(FollowTarget)
{
  constexpr int AXIS_INDEX = 0;      // The index of the axis to move
  constexpr double TOLERANCE = 0.02; // The tolerance for the position difference
 
  // Check if the axis is within the tolerance of target position
  if (std::abs(data->potentialTarget - data->targetPosition) > TOLERANCE)
  {
    // Move the axis to the target position
    double newTarget = data->potentialTarget;
    data->targetPosition = newTarget;
    RTAxisGet(AXIS_INDEX)->MoveSCurve(data->targetPosition);
  }
}

Once the task functions have been added, build the project to produce a new library.

The runtime of all your RTTasks put together is subject to timing requirements based on your sample rate—be wary of very long-running tasks. See the Concepts > General > Real-Time Tasks page in our docs for more details on timing requirements.

Optional: Build to a custom library name and directory

Using the default library name (RTTaskFunctions) and directory (RMP's installation folder) will work fine for many applications. However, in the case that you would like more control (e.g., to avoid library collisions when working on multiple RTTask projects) you may override both.

As an example, we will create a library with the name CustomRTTaskFunctions and the directory ./RTTaskFunctions/lib (relative to your project folder).

First, change the CMakeLists.txt in the RTTaskFunctions folder. Replace every instance of RTTaskFunctions with your custom library name. Then, set OUTPUT_DIR using your custom directory.

# ./RTTaskFunctions/CMakeLists.txt
 
project(CustomRTTaskFunctions)
 
# ...
 
set(OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/lib)
 
# ...
 
add_library(CustomRTTaskFunctions SHARED ${SOURCE_FILES} ${HEADER_FILES})
target_include_directories(CustomRTTaskFunctions PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
target_link_libraries(CustomRTTaskFunctions PRIVATE RSI::RapidCode)
 
set_target_properties(CustomRTTaskFunctions PROPERTIES
  # ...
)
 
if (INTIME_BUILD_ENABLED)
  configure_intime_target(CustomRTTaskFunctions)
endif()

Then, make sure that the CMakeLists.txt in the root of your project folder includes the RTTaskFunctions subdirectory.

add_subdirectory(RTTaskFunctions)

This will build our function library CustomRTTaskFunctions to the folder ./RTTaskFunctions/lib. To properly use this library, see the optional steps below.

🚀 Launch your tasks

In your user application, written in C++, C#, or Python with RapidCode, or in any gRPC-capable language using RapidCodeRemote, create an RTTaskManager instance after configuring your RapidCode objects. Submit your tasks to the manager, which will load the shared library built in the previous steps. You can also start the manager from utilities like rsiconfig if you prefer to manage tasks outside of application code.

Note: Make sure to include the RTTask header, rttask.h.

#include "rttask.h"
 
using namespace RSI::RapidCode::RealTimeTasks;
 
RTTaskManagerCreationParameters parameters;
 
// The path to the RMP install folder
std::snprintf(parameters.RTTaskDirectory,
              RTTaskManagerCreationParameters::DirectoryLengthMaximum,
              RMP_INSTALL_PATH);
 
// On Windows/INtime, use PlatformType::INtime for real-time or PlatformType::Windows for debugging
// On Linux, Platform does not need to be set
parameters.Platform = PlatformType::INtime
 
// For INtime managers, set the node you want the manager to run on
std::snprintf(parameters.NodeName,
              RTTaskManagerCreationParameters::NameLengthMaximum,
              "NodeA");
 
// For Linux, set the CPU core you want the manager to run on
parameters.CpuCore = 3;
 
// Create the RTTaskManager
RTTaskManager manager = RTTaskManager::Create(parameters);

Next, run the Initialize task one time, to get access to RapidCode objects and initialize your global variables.

// If you are not using the default library name and directory, you must specify those here
RTTaskCreationParameters initParams("Initialize");
initParams.Repeats = RTTaskCreationParameters::RepeatNone;  // Don't repeat this task
RTTask initTask = manager.TaskSubmit(initParams);
constexpr int timeoutMs = 5000;
initTask.ExecutionCountAbsoluteWait(1, timeoutMs); // Wait for the task to execute once.

Then submit the tasks created in the previous section.

RTTaskCreationParameters calcParams("CalculateTarget");
calcParams.Repeats = RTTaskCreationParameters::RepeatForever;  // Repeat this task infinitely
calcParams.Period = 10;  // Run the task every 10 samples
RTTask calcTask = manager.TaskSubmit(calcParams);
 
calcTask.ExecutionCountAbsoluteWait(1);
 
RTTaskCreationParameters followParams("FollowTarget");
followParams.Repeats = RTTaskCreationParameters::RepeatForever;
followParams.Period = 10;
RTTask followTask = manager.TaskSubmit(followParams);

Note: the fields RepeatForever and RepeatNone are static constant expressions provided for convenience and readability. They can not be written to on instances of RTTaskCreationParameters. See the our API reference for more static fields.

While your tasks are running, you can use RTTask::StatusGet and RTTaskManager::GlobalValueGet to monitor your tasks.

FirmwareValue value = manager.GlobalValueGet("targetPosition");
std::cout << "Target position: " << value.Double << std::endl;

At the end of your program, stop the tasks and manager.

followTask.Stop();
calcTask.Stop();
manager.Shutdown();

Before launching your RTTasks executable, it is important to run and configure RMP. This can be done via your RapidCode application, rsiconfig, or some other tool. Use the steps below as a checklist to ensure your RTTasks application is ready to run:

• Required:
  • RMP running
  • RapidCode object counts set
• Suggested:
  • Network started/phantom axes created
  • User units set
  • Limits & actions configured
  • Amplifier enabled
  • Other RapidCode configuration

Optional: Using a custom function library

If you built your library to a custom name and directory (as shown in the optional section above), you must provide this information to RTTasks API objects.

You should pass in the library name and directory when getting/setting globals, constructing RTTaskCreationParameters objects, and any other cases indicated by the API reference.

You should not pass in the library directory when configuring RTTaskManagerCreationParameters. The RTTaskDirectory field is the directory that contains the rttaskmanager.exe executable. Typically, this is the RMP installation folder, so this field can be left unmodified.

Once you have implemented the sample code above, make the modifications given here:

// The directory path may be absolute or relative to the executable you are running
// A skeleton of an absolute path is given here that must be modified accordingly
const char* libraryDirectory = "/home/<USER>/.../RTTasksProject/RTTasksFunctions/lib";
const char* libraryName = "CustomRTTaskFunctions";
 
// ...
 
RTTaskManagerCreationParameters parameters;
// This should still be the RMP install folder
std::snprintf(parameters.RTTaskDirectory,
              RTTaskManagerCreationParameters::DirectoryLengthMaximum,
              RMP_INSTALL_PATH);
 
// ...
 
// Construction of RTTaskCreationParameters must include name and directory
RTTaskCreationParameters initParams("Initialize", libraryName, libraryDirectory);
RTTaskCreationParameters calcParams("CalculateTarget", libraryName, libraryDirectory);
RTTaskCreationParameters followParams("FollowTarget", libraryName, libraryDirectory);
 
// ...
 
// Global getters/setters must include name and directory
FirmwareValue value = manager.GlobalValueGet("targetPosition", libraryName, libraryDirectory);

❓ FAQ

When should I use RTTasks instead of RapidCode?

RTTasks guarantees deterministic, real-time performance where regular RapidCode applications cannot. This is useful for cases where you need to meet strict timing requirements, such as responding to input within a certain number of milliseconds, or periodic tasks that cannot miss a cycle.

What are the limitations of an RTTask?

While there are no strict limitations on the kind of C++ code that you can write, your RTTasks will be subject to timing restraints based on your sample rate. Ensure that you have enough headroom in each sample for both the RMP firmware and your RTTask operations to execute.

What happens to the RTTaskManager after my application ends?

The RTTask manager will persist independently of your RapidCode application unless a call to Shutdown is made.

Should I have RMP running before starting my RTTaskManager?

In general, yes. The RTTaskManager uses RMP interrupts for its timing by default. This can be disabled with the NoRmp flag (see RTTaskManagerCreationParameters for more details), but you must have RMP running to command motion with any RapidCode objects.

Can I use controller->AxisGet() in my RTTask function?

While it is possible, it is strongly suggested you use RTAxisGet(), defined in rttaskglobals.h, instead. This method and other RTObjectGet() methods have built-in error checking for RTTasks users.

See Using RapidCode objects for more information.

How do I make an RTTask repeat forever?

While configuring your RTTaskCreationParameters, set the RTTaskCreationParameters::Repeats field to the special static constant value, as shown below:

params.Repeats = RTTaskCreationParameters::RepeatForever;

Then, when you submit this task, the RTTaskManager will repeat it until stopped.

How can I create an RTTasks library with a custom name and directory?

Use the instructions under the "Optional" sections of the guide Create a Real-Time Task.

Why would I run RTTasks on Windows?

Windows users will typically run their RTTasks on INtime. However, users may run their RTTasks on Windows to debug them without needing the INtime SDK.

Important caveat: RTTasks running on Windows will not have real-time performance. This means that it should not be used outside of development, and that bugs related to real-time performance may not be present.

How do I debug RTTasks on Windows?

Windows users who want to debug their RTTasks on Windows should set the RTTaskManagerCreationParameters::Platform to Windows. Additionally, comment out any lines which set RTTaskManagerCreationParameters::NodeName until returning to running on INtime.

Note

This is intended for debugging only. For real-time performance, Windows users must run RTTasks on INtime.

When should I split one RTTask into two?

Whenever you want a separation of concerns (e.g., one task should continue even if the other fails), it is recommended to use multiple tasks. Additionally, any case where tasks require differences in their RTTaskCreationParameters (e.g., priority, period, repeats) naturally requires multiple tasks.