Clarification on QP/C architecture adoption and integration best practices

[jsramesh1990]

1. For developers transitioning from traditional superloop or RTOS task-based embedded architectures, what is the recommended migration strategy for restructuring an existing firmware project into QP/C active objects and hierarchical state machines?

2. In resource-constrained MCUs, what practical guidelines are recommended for balancing the benefits of hierarchical state machines and active objects against RAM/flash overhead and event queue sizing?

3. When integrating QP/C with vendor SDKs or existing peripheral drivers (such as STM32 HAL/CMSIS-based projects), what architectural boundaries are recommended to keep hardware abstraction, event flow, and application logic cleanly separated?

[quantum-leaps]

Thank you for the interest in QP frameworks.

Before diving into architecture and migration strategy, I strongly recommend the following practical learning path. It gives you the necessary intuition for how active objects, event queues, and hierarchical state machines behave in practice:

1. Watch the videos in the “Beyond the RTOS” playlist.
   They explain the paradigm shift from traditional superloops/RTOS tasks based on blocking to event‑driven, non-blocking active objects and hierarchical state machines.

2. Install the QP‑Bundle and build/run the provided examples on the host.
   Running the examples on your PC (no hardware required) is the fastest way to understand the event-driven execution model. Here you could watch the videos from the State Machines playlist.

3. Get one of the inexpensive boards supported by the examples and run them unmodified.
   Build, flash, and debug the examples as-is first. Once everything works, start introducing small changes gradually so you can see how the architecture responds.

4. Copy and adapt the DPP example for your specific board.
   DPP is intentionally structured as a clean, minimal reference for real-time event-driven design. Adapting it to your hardware is the most reliable way to bootstrap a new QP/C project.

With that foundation in place, here are direct answers to your three questions:

---

1. Migration strategy from superloop/RTOS tasks to QP/C active objects and HSMs

The recommended approach is incremental refactoring, not a rewrite.

• Keep using your RTOS, but add to your application the QP framework and the QP-port to the RTOS.
• Identify the first RTOS thread most easy to convert into active object.
• Convert this one thread into an active object replacing all blocking waits and shared-variable signaling with events and time events.
• Once stable, refactor internal logic into hierarchical states to eliminate duplication and clarify modes.
• The "hybrid" system (a combination of threads and active objects) is OK, but remember NOT to mix paradigms within a single Active Object. Specifically, never call blocking RTOS mechanisms from your active object.
• Gradually retire legacy threads one by one, remembering that you can combine functionality from multiple threads into an active object (because it remains responsive to all events).

The DPP example is an excellent template for this process.

---

2. Balancing HSM/AO benefits with RAM/flash constraints

In small MCUs, the key is to use the provided QP mechanisms rather than duplicating them by inventing your own:

• Event-driven paradigm is generally much more efficient for resource constrained systems than sequential paradigm (and that's what these systems are doing)
• Use one of the custom kernels built into QP (QV, QK) to save RAM for the stack (savings of 80% compared to the RTOS threads requiring private stacks)
• Use QP events and event pools as data buffers: produce data directly into events rather than copying the data from local buffers to events.
• Measure the worst-case event pool and event queue usage. QP provides internal "low watermark" variables that store the worst-case usage. You can then inspect them in your debugger (or output them with QS software tracing). This will allow you to save RAM by avoiding oversizing the pools and queues.
• Use hierarchical state machines to avoid duplication of behavior and this save code space (ROM).

Running the provided examples on your board will give you a concrete sense of memory footprint and queue sizing.

---

3. Architectural boundaries when integrating QP/C with vendor SDKs (e.g., STM32 HAL/CMSIS)

QP works well with many SDKs, HALs, and CMSIS.

For example, QP works well with STM32 HAL, as demonstrated in the examples (see qpc/examples/stm32cube) and videos

• Non-preemptive QV Kernel for Active Objects
• Preemptive QK Kernel for Active Objects

QP/C active objects + hierarchical state machines
All application logic, modes, sequencing, and event flow.
AOs call BSP functions for hardware actions and receive events from ISRs.

This structure keeps hardware details out of your state machines and ensures deterministic, event-driven behavior.

[jsramesh1990]

Thank you for the detailed explanation and learning path.

The incremental migration approach and the recommendation to start from the DPP example are especially helpful. I now have a much clearer picture of how to approach QP/C adoption without forcing a full rewrite of an existing firmware architecture.

My immediate plan is to:

• Go through the “Beyond the RTOS” and state machine playlists
• Build and run the host examples from QP-Bundle first
• Run one of the supported board examples unmodified
• Then adapt the DPP example to my STM32/HAL-based setup as the first practical integration step

The guidance on hybrid RTOS + active object migration, avoiding blocking calls inside active objects, and using QV/QK for resource efficiency also clarified several design questions I had.

Thanks again for the comprehensive response. I’ll proceed with the examples first and come back with a more specific implementation question if needed.