qp-arduino README

Brought to you by

Documentation

This README provides a quick overview of QP for Arduino.

More detailed documentation for qpcpp, QM, and QTools can be found at:

https://QuantumLeaps.github.io/qp-arduino/

Please refer to the companion website to this project at:

https://www.state-machine.com/arduino

Repository Information

• Name: qp-arduino
• Description: QP real-time embedded framework for Arduino (ARM Cortex-M)
• Version: 6.9.9
• qpcpp version: 6.9.3
• QM version: 5.2.3
• QTools version: 6.9.3
• Release Date: 2026-02-18
• Creation Date: 2017-01-30
• License: GPLv3
• URL: https://github.com/QuantumLeaps/qp-arduino
• Author: Quantum Leaps
• Repository Maintainer: Peter Polidoro
• Email: peter@polidoro.io
• Copyright: Quantum Leaps, LLC
• References:
  • https://www.state-machine.com/
  • https://github.com/QuantumLeaps/qp-arduino-example
  • https://sourceforge.net/p/qpc/discussion/668726

Description

The Quantum Leaps’ QP™ real-time embedded frameworks (RTEFs) and the QM™ modeling tool complement the Arduino platform and provide everything you need to program Arduino graphically with event-driven active objects and modern hierarchical state machines.

Provided Library and Examples

This repository contains one external library for ARM Cortex-M based Arduinos:

• qp-arduino – QP/C++ framework for Arduinos based on ARM Cortex-M

This repository also contains several examples under examples/ for:

• Teensy 4.1 (Teensyduino / PlatformIO)
• Arduino Due (ATSAM3X8E)

Installation

The QP adaptation for Arduino may be used either with the Arduino IDE or with PlatformIO.

The intended way of working with the examples is to use the QM modeling tool to modify the models (.qm files) and then to generate code from these models.

In this scenario, the Arduino IDE or PlatformIO are used only to build and upload the code to the Arduino board(s).

Arduino IDE

Download and set up the Arduino IDE if necessary:

https://www.arduino.cc/en/software

This library may be installed by either using the Arduino IDE Library Manager or by downloading this repository into the Sketchbook location directly.

Assuming that you have installed the QP library in your <Sketchbook> directory, the examples provided in each QP library show up in the Arduino IDE under the menu:

File|Examples|Examples from Custom Libraries

NOTE: The preferences in the Arduino IDE should be set up to Use external editor so that the IDE will update the code each time it is re-generated by the QM modeling tool.

NOTE: QS tracing (QS_ON) is enabled by necessity in all Arduino code so the output is binary. Use QSPY (from QTools) to view the trace stream; a standard serial terminal/serial monitor is not suitable.

Arduino IDE Library Manager

In the Arduino IDE Library Manager, search for qp-arduino and install the latest version.

Downloading into Sketchbook Location

This repository can be downloaded into the Sketchbook location either as a single zip archive or cloned to a local git repository.

You need to unzip the zip archive, or clone the git repository, into your Arduino <Sketchbook> directory. To find out where your <Sketchbook> directory is, or to configure a different location for your <Sketchbook> directory, you need to open the Arduino IDE and select the File|Preferences menu. The Sketchbook location will be shown at the top of the Preferences dialog box. Once you identify the <Sketchbook> directory, you simply unzip the whole zip archive, or clone the git repository, to this directory, renaming the directory qp-arduino if necessary.

After the installation, your Arduino <Sketchbook> directory should look as follows:

<Sketchbook>/
└── libraries
    └── qp-arduino
        ├── examples
        │   ├── blinky-sam
        │   ├── blinky2-sam
        │   ├── blinky_bsp-sam
        │   ├── blinky_bsp-teensy4
        │   ├── dpp_bsp-sam
        │   └── dpp_bsp-teensy4
        └── src
            └── qp-arduino

Zip File

https://github.com/QuantumLeaps/qp-arduino/archive/refs/heads/main.zip

Git

git clone https://github.com/QuantumLeaps/qp-arduino.git

PlatformIO (recommended) via Pixi

This repository provides a cross-platform, reproducible command-line workflow via pixi:

• pixi manages the PlatformIO CLI (no manual venv / pip install platformio)
• pixi tasks select which example to build by setting PLATFORMIO_SRC_DIR (so you do not edit platformio.ini)

Install pixi

Follow the official installation instructions:

https://pixi.sh/latest/

Install dependencies

From the repository root:

pixi install

Build and upload examples

List connected ports/devices:

pixi run ports

Build and upload the default example (examples/dpp_bsp-teensy4 on Teensy 4.1):

pixi run build
pixi run upload                 # defaults to /dev/ttyACM0
pixi run upload /dev/ttyACM1     # override port

Build and upload other examples:

# Teensy 4.1
pixi run build-blinky-bsp-teensy4
pixi run upload-blinky-bsp-teensy4 /dev/ttyACM0

# Arduino Due / ATSAM3X8E
pixi run build-blinky-sam
pixi run upload-blinky-sam /dev/ttyACM0

pixi run build-blinky2-sam
pixi run upload-blinky2-sam /dev/ttyACM0

pixi run build-blinky-bsp-sam
pixi run upload-blinky-bsp-sam /dev/ttyACM0

pixi run build-dpp-bsp-sam
pixi run upload-dpp-bsp-sam /dev/ttyACM0

NOTE: On macOS the port is typically like /dev/cu.usbmodemXXXX, and on Windows it is typically like COM3. The upload tasks accept any port string.

QM and QTools (QM 5.2.3 / QTools 6.9.3)

Only very specific versions of QM and QTools are compatible with the qpcpp version used by qp-arduino:

• QM: 5.2.3
• QTools: 6.9.3 (includes QSPY)

This repository provides pixi tasks that download/install these pinned versions locally into:

./.tools/quantum-leaps/

Install both QM and QTools:

pixi run ql-install

Launch QM:

pixi run qm

Install/build QTools (and build qspy on Linux/macOS if needed):

pixi run qtools-install

Run QSPY (arguments are passed through to qspy):

pixi run qspy -c /dev/ttyACM0 -b 115200

If you want QSPY’s own help, use the explicit separator:

pixi run qspy -- -h

QP/Spy Software Tracing Support

The qpcpp_arm-cm library supports the QP/Spy software tracing. This feature is also demonstrated in the qpcpp examples (with the BSP).

In this repository, QS tracing (QS_ON) is enabled in the BSP-based examples. QS_ON must be enabled whenever qpcpp is used with Arduino code due to Arduino macro limitations.

NOTE: Because the QP/Spy output is binary, you cannot watch it with a standard serial terminal. Instead, you need to use the QSPY host utility.

QView Demonstration

Once QP/Spy tracing is enabled, the communication with the target system can be used for QView visualization and monitoring.

The dpp_bsp-teensy4 example demonstrates QView monitoring. To see this feature, upload the dpp_bsp-teensy4 code to the Teensy 4.1 board and then launch QView.

Licensing

The QP/C++ real-time embedded framework (RTEF) for Arduino is licensed under the modified GPLv3 license with the QP-Arduino Exception (see also the file (QP-Arduino_GPL_Exception.txt in the root of this repository).

Specifically, the Arduino GPLv3 Exception removes the requirement to expose your proprietary source code as long as you deploy it on an Arduino-Certified board.

The QM model-based design tool is freeware. The QM tool is provided under the terms of a simple End-User License Agreement (EULA).

Support Questions

Please submit any questions or comments to the free QP support forum at:

https://sourceforge.net/p/qpc/discussion/668726