# 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**: 2025-07-26

## 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.6
- qpcpp version: 6.9.3
- qm version: 5.2.3
- qtools version: 6.9.3
- Release Date: 2025-03-14
- 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 Libary 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

* 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).

** Arudino IDE

Download and setup the Arduino IDE if necessary:

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

This libary may be installed by either using the Arduino IDE libary manager or
by downloading this repository into the Sketchbook location directly.

Assumming 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.

The Arduino IDE serial monitor may be used to observe the output of the dpp
examples.

*** Arduino IDE Libary Manager

In the Arduino IDE libary 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 =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

PlatformIO can be used as an alternative to the Arduino IDE for compiling and
uploading Arduino code to embedded boards using a command line interface.

Download and setup PlatformIO if necessary:

https://platformio.org/install/cli

To use this libary with PlatformIO, simply add the repository URL to your
platformio.ini file.

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

To compile and run an example in this repository, clone the repository to any
directory you prefer:

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

Navigate inside the qp-arduino directory where the platformio.ini file is
contained.

Modify the platformio.ini file to compile the example that you prefer.

Compile and upload the example with a command like this:

#+BEGIN_SRC sh
pio run -e teensy41 -t upload
#+END_SRC

To use the serial monitor to observe the output of the dpp examples run:

#+BEGIN_SRC sh
pio device monitor
#+END_SRC

** QM

QM™ (QP Modeler) is a freeware model-based design (MBD) and automatic code
generation tool for designing software based on modern finite state machines
(UML statecharts) and the QP™ Real-Time Embedded Frameworks. QM™ is available
for Windows, Linux and macOS hosts. The QM™ modeling tool is offered under a
simple click-through EULA license.

QM may be downloaded and installed from:

https://www.state-machine.com/products/qm

Or it may be downloaded and installed on the command line:

#+BEGIN_SRC sh
cd ~ && rm -rf qp && mkdir qp && cd qp
curl -OL https://github.com/QuantumLeaps/qm/releases/download/v5.2.3/qm_5.2.3-linux64.zip
unzip qm_5.2.3-linux64.zip && rm qm_5.2.3-linux64.zip && mv qm qm-5.2.3
chmod u+x qm-5.2.3/bin/qm && chmod u+x qm-5.2.3/bin/qm.sh
alias qm='~/qp/qm-5.2.3/bin/qm.sh'
#+END_SRC

** QTools

QTools™ is a collection of various open source host-based tools for working with
the QP frameworks, such as: QP/Spy™ software tracing and testing system, QUTest™
unit testing harness, QView™ monitoring and visualizing, and QWin™ GUI toolkit
for prototyping embedded systems on Windows. The QTools collection for Windows
provides also the MinGW C/C++ compiler (GNU GCC) and GNU make for Windows, as
well as the related file utilities (rm, touch, etc.)

QTools may be downloaded and installed from:

https://www.state-machine.com/products/qtools

Or they may be downloaded and installed on the command line:

#+BEGIN_SRC sh
cd ~/qp
curl -OL https://github.com/QuantumLeaps/qtools/releases/download/v6.9.3/qtools-posix_6.9.3.zip
unzip qtools-posix_6.9.3.zip && rm qtools-posix_6.9.3.zip && mv qtools qtools-6.9.3
cd qtools-6.9.3/qspy/posix
sudo apt install build-essential
make
alias qspy='~/qp/qtools-6.9.3/bin/qspy'
#+END_SRC

* QP/Spy Software Tracing Support

The qpcpp_arm-cm library now 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).

To activate the software tracing, you would need to un-comment the =QS_ON= macro
at the top of bsp.cpp source file.

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, this communication with the target system can be
used to for [[https://www.state-machine.com/qtools/qview.html][QView
visualization and monitoring]]

The =dpp_bsp-teensy4= example demonstrates the *QView monitoring*. To see this
feature, you need to upload the dpp_bsp-teensy4 code to the Arduino Teensy 4
board and then you need to launch QView.

* Licensing

The QP/C++ real-time embedded framework (RTEF) for Arduino are 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
the archive).

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