QP/C for event-driven embedded systems

The embedded concurrency problem addressed by QP/C

QP/C is designed for embedded applications in which multiple parts of firmware must respond to events asynchronously. Its central model is the Active Object, also called an Actor. Each active object owns an event-handling behavior, while the framework provides a common environment for delivering events and running those behaviors in a deterministic, real-time fashion.

This model is aimed at systems that are more complicated than a single startup function or a collection of independent polling loops. It can represent concurrent objects without requiring every object to be managed as an ordinary thread. The repository describes QP/C both as application infrastructure for building a system from Active Objects and as a runtime environment for executing them.

The framework is particularly relevant to ARM Cortex-M microcontrollers, including the M0, M3, M4 and M7 families named in the repository topics. It is also relevant to developers who model behavior with hierarchical state machines. This makes QP/C a candidate for control systems, device logic and other firmware whose operating mode depends on incoming events, although the README does not name a particular product category beyond real-time embedded systems.

It is not a general-purpose host application framework. The stated target is firmware with deterministic execution requirements, usually near hardware. Projects that only need a library function, a scheduler wrapper around one task or startup-time initialization will probably find the object and state-machine machinery excessive.

How QP/C connects events, Actors and nested states

QP/C combines two behavioral abstractions. The Active Object model separates an object's identity and event queue from the logic that handles those events. Hierarchical state machines then describe how one object's behavior changes as events arrive. The framework supports UML 2.5 statecharts, including state hierarchy and transitions, so an implementation need not reduce behavior to unrelated boolean flags.

An event reaches an active object and causes its state-machine logic to evaluate the current state and the new event. Entry, exit and transition behavior can then depend on where the object currently sits in the state hierarchy. Although the README does not expose the low-level queue algorithm or interrupt dispatch path, it states that applications are executed in a deterministic, real-time fashion and that the framework is asynchronous and event-driven.

Developers can implement state machines manually in C. The repository also supports automatic code generation through QM, its graphical model-based design tool. These are two entry paths into the same QP/C behavior model. Manual C coding gives the developer direct control over the implementation. QM adds graphical modeling and generated output, but also creates another workflow whose generated files and synchronization rules must be understood by the project team.

The repository includes `include/`, `src/`, `ports/`, `examples/`, `tests/` and `templates/`. This layout indicates a reusable C framework with target integrations and runnable examples. It does not mean that every port can be dropped into every MCU project. The selected port still has to match the processor, toolchain and interrupt environment.

Cloning QP/C for a first project

The README describes two acquisition routes. A developer who wants the latest GitHub version can clone the repository with its submodules and shallow history. The command below retrieves the default branch and includes referenced submodules. It does not build the framework for a particular board.

git clone https://github.com/QuantumLeaps/qpc --recurse-submodules --depth 1

The README calls downloading the QP-bundle the easiest and most recommended route. That bundle includes QP/C, the QM modeling tool, the QTools collection and examples, so it covers more of the intended workflow than the Git clone alone.

The repository has a `CMakeLists.txt`, `qpc_sdk_init.cmake` and `cmakeSupport.md`, but the README does not provide a complete board-specific CMake command. It would be misleading to invent compiler flags or target names. After cloning, use the build instructions and configuration in the example selected for the target hardware.

The project also provides the application note titled “Getting Started with QP Real-Time Event Frameworks” and a QP/C Tutorial. Those resources are more useful for a first build than an assumed generic command, because embedded projects depend on startup files, linker settings and hardware support files that are not interchangeable across targets.

Blinky and Dining Philosophers as staged first uses

The first useful exercise is an unmodified example on supported evaluation hardware. The README identifies Blinky as the super-simple starting project and links an STM32 NUCLEO-U545RE implementation. Build it with the toolchain expected by that example, load it onto the board and observe the example before introducing custom application behavior.

This sequence checks the full integration boundary at once: the framework source, selected port, build files and target board must all agree. A failure at this stage may concern the port or toolchain rather than Active Object logic. The README specifically advises starting with a working system and changing one thing at a time.

After Blinky works, the Dining Philosophers Problem example offers a more advanced reference. It is useful for examining a larger event-driven example, but the README does not document a universal build command for it. Follow the files under the example's own directory and use its target configuration.

When the stock example runs, the next change should remain small. Add one event or one state transition and verify the board again. That practice makes it easier to distinguish an application regression from a board, linker or port configuration problem.

Port selection and undocumented integration boundaries

The repository's `ports/` directory makes target support a first-class adoption concern. It also contains `zephyr/`, examples for different ARM Cortex-M targets, tests and a CMake support file. Those entries indicate multiple integration contexts, but directory names alone do not confirm which boards, tool versions or IDEs are supported in a particular release.

The README does not document the complete compiler command, linker configuration, startup sequence or deployment procedure for each port. It also does not state a complete compatibility matrix for the examples. A team adopting QP/C should therefore inspect the selected example's build files rather than assume that every ARM Cortex-M project can use the same settings.

Interrupt ownership is another boundary worth checking. QP/C is event-driven and targets microcontrollers, but the README does not say how a particular port maps interrupts, timers or task scheduling onto the target. Those details determine whether events enter the framework correctly. The board example is therefore evidence of one supported path, not a universal porting recipe.

The framework may also be the wrong abstraction when application concurrency is trivial, when team expertise is centered on procedural super-loop design, or when a UML-oriented state hierarchy would obscure otherwise direct device logic. Adopting a state-machine framework solely because it is capable does not remove the cost of learning its event and port contracts.

QP/C and SafeQP/C have different assurance boundaries

QP/C and SafeQP/C expose the same API, and the README states that existing QP/C applications can move to SafeQP/C without application modifications. Their assurance and commercial terms are not equivalent. QP/C includes selected assertions, whereas SafeQP/C includes all safety functions and is accompanied by a SafeQP Certification Kit.

That kit provides requirements, architecture and design artifacts intended to support application certification in safety-critical industrial, medical, aerospace and automotive work. These claims apply to SafeQP/C. They do not turn the standard QP/C repository into a certification package, and having hierarchical state machines does not itself satisfy a formal safety-development process.

A commercial project should compare the standard framework against the commercial edition before committing to an upgrade path. An open-source project that does not need the complete safety-function set may focus on QP/C, but it must still assess selected assertions and certification relevance rather than assuming equivalence.

SafeQP/C is also a concrete alternative with the same API and functional model. The choice is not based on a different Actor mechanism. It is based on assurance functions, certification artifacts, licensing and procurement requirements.

Licensing, releases and technical support in QP/C

The repository uses a custom license that GitHub cannot classify. The README refers to open-source and commercial licensing, so teams must read `LICENSE.txt` and the entries under `LICENSES/` before deciding how the source can be distributed or incorporated into a product. This review cannot infer legal terms that are not quoted in the repository documentation.

The repository is not archived. Its last push was on 2026-10-13, and the recent release list includes `v8.1.5`, `v8.1.4` and `v8.1.3`. This indicates recent development activity, but upgrade work still depends on the release notes, port changes and generated-code differences between the versions in use. The README points to the QP/C Revision History for release-specific information.

Technical support does not use GitHub Issues. The README directs bug reports to the SourceForge Bug Tracker database, feature requests to its Feature Requests database, and questions to the QP/QM Free Support Forum. That distinction matters when planning a support workflow. Projects may rely on upstream channels while still needing to maintain their own board support, application tests and release records.

Editorial conclusion

Engineers with concurrent, state-dependent embedded behavior should evaluate QP/C when explicit event dispatch and hierarchical states fit the design. Projects that require complete safety functions, certification artifacts or conventional open-source license terms should inspect LICENSE.txt first. The first technical check is an unmodified example for the target board, followed by verification of its port, build configuration and event flow.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. QuantumLeaps/qpc on GitHub
4. README
5. Releases