# qp-arduino

**Repository Path**: mirrors_QuantumLeaps/qp-arduino

## Basic Information

- **Project Name**: qp-arduino
- **Description**: QP/C++ real-time event framework/RTOS for Arduino (ARM Cortex-M)
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-25
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

#+TITLE: qp-arduino README
#+AUTHOR: Peter Polidoro
#+EMAIL: peter@polidoro.io

* Brought to you by

[[./extras/img/logo_ql_400.png]]

[[./extras/img/logo_qp-arduino.png]]

* 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
[[https://www.arduino.cc/en/software][Arduino IDE]] or with
[[https://platformio.org/install/cli][PlatformIO]].

The intended way of working with the examples is to use the
[[https://www.state-machine.com/products/qm/][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:

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

**** Zip File

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

**** Git

#+BEGIN_SRC sh
git clone https://github.com/QuantumLeaps/qp-arduino.git
#+END_SRC

** PlatformIO (recommended) via Pixi

This repository provides a cross-platform, reproducible command-line workflow
via [[https://pixi.sh/][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:

#+BEGIN_SRC sh
pixi install
#+END_SRC

*** Build and upload examples

List connected ports/devices:

#+BEGIN_SRC sh
pixi run ports
#+END_SRC

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

#+BEGIN_SRC sh
pixi run build
pixi run upload                 # defaults to /dev/ttyACM0
pixi run upload /dev/ttyACM1     # override port
#+END_SRC

Build and upload other examples:

#+BEGIN_SRC sh
# 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
#+END_SRC

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:

#+BEGIN_SRC sh
pixi run ql-install
#+END_SRC

Launch QM:

#+BEGIN_SRC sh
pixi run qm
#+END_SRC

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

#+BEGIN_SRC sh
pixi run qtools-install
#+END_SRC

Run QSPY (arguments are passed through to =qspy=):

#+BEGIN_SRC sh
pixi run qspy -c /dev/ttyACM0 -b 115200
#+END_SRC

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

#+BEGIN_SRC sh
pixi run qspy -- -h
#+END_SRC

* QP/Spy Software Tracing Support

The qpcpp_arm-cm library supports the
[[https://www.state-machine.com/software-tracing][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
[[https://www.state-machine.com/qtools/qspy.html][QSPY host utility]].

** QView Demonstration

Once QP/Spy tracing is enabled, the communication with the target system can be
used for [[https://www.state-machine.com/qtools/qview.html][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
[[https://www.state-machine.com/licenses/QP-Arduino_GPL_Exception.txt][QP-Arduino
Exception]] (see also the file
([[./QP-Arduino_GPL_Exception.txt][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 [[https://www.state-machine.com/qm/][QM model-based design tool]] is freeware.
The QM tool is provided under the terms of a simple
[[https://www.state-machine.com/qm/license.html][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