Repository files navigation

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

• 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

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.

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

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

The QP adaptation for Arduino may be used either with theArduino IDE or withPlatformIO.

The intended way of working with the examples is to use theQM 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).

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

In the Arduino IDE libary manager, search for qp-arduino and install the latest version.

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 selectFile|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

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

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

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.

lib_deps =    https://github.com/QuantumLeaps/qp-arduino.git

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

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

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:

pio run -e teensy41 -t upload

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

pio device monitor

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:

cd~&& rm -rf qp&& mkdir qp&&cd qpcurl -OL https://github.com/QuantumLeaps/qm/releases/download/v5.2.3/qm_5.2.3-linux64.zipunzip qm_5.2.3-linux64.zip&& rm qm_5.2.3-linux64.zip&& mv qm qm-5.2.3chmod u+x qm-5.2.3/bin/qm&& chmod u+x qm-5.2.3/bin/qm.shalias qm='~/qp/qm-5.2.3/bin/qm.sh'

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:

cd~/qpcurl -OL https://github.com/QuantumLeaps/qtools/releases/download/v6.9.3/qtools-posix_6.9.3.zipunzip qtools-posix_6.9.3.zip&& rm qtools-posix_6.9.3.zip&& mv qtools qtools-6.9.3cd qtools-6.9.3/qspy/posixsudo apt install build-essentialmakealias qspy='~/qp/qtools-6.9.3/bin/qspy'

The qpcpp_arm-cm library now supports theQP/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 theQS_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 theQSPY host utility.

Once QP/Spy tracing is enabled, this communication with the target system can be used to forQView visualization and monitoring

Thedpp_bsp-teensy4 example demonstrates theQView 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.

The QP/C++ real-time embedded framework (RTEF) for Arduino are licensed under the modified GPLv3 license with theQP-Arduino Exception (see also the file (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.

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

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

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