quantumleaps / qp-arduino

QP real-time embedded frameworks/RTOS for Arduino (AVR and SAM)

Brought to you by:

---

This README provides a quick overview of QP for Arduino. Please refer to the companion webiste to this project at:

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

---

Software Installation

The QP adaptation for Arduino is distributed in a single ZIP archive qp-<ver>_arduino-1.8.x.zip, where <ver> stands for the version of the QP frameworks.

You need to unzip the qp-<ver>_arduino-1.8.x.zip archive into your Arduino <Sketchbook> folder. To find out where your <Sketchbook> folder is, or to configure a different location for your <Sketchbook> folder, 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> folder, you simply unzip the whole qp-<ver>_arduino-1.8.x.zip archive to this folder.

---

Provided Libraries and Examples

The archive qp-<ver>_arduino-1.8.x.zip contains two external libraries for SAM-based Arduinos:

• qpcpp_arm-cm -- QP/C++ framework for Arduinos based on ARM Cortex-M
• qpn_avr -- QP-nano framework for Arduinos based on AVR

NOTE: qpn_avr is now obsolete. It is provided for backwards compatibility only!

---

Provided Tools

The archive also contains the QM modeling tool for Windows

• qm -- QM modeling tool for Windows 32/64-bit

---

Directories and Files

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

<Sketchbook>/             - your Arduino Sketchbook folder
├───libraries/             - libraries folder
│   ├───qpcpp_arm-cm/      - QP/C++ library for ARM Cortex-M based boards
│   │   ├───examples/      - QP/C++ library examples
│   │   │   ├───blinky-sam/             - Blinky example for SAM-Arduinos
│   │   │   │   ├───blinky-sam.ino      - Blinky code (generated by QM)
│   │   │   │   └───blinky-sam.qm       - Blinky model (for QM)
│   │   │   ├───blinky2-sam/            - Blinky2 example for SAM-Arduinos
│   │   │   │   ├───blinky2-sam.ino     - Blinky2 code (generated by QM)
│   │   │   │   └───blinky2-sam.qm      - Blinky2 model (for QM)
│   │   │   ├───blinky_bsp-sam/         - Blinky example with BSP for SAM
│   │   │   │   ├───blinky_bsp-sam.ino  - Blinky-BSP code (generated by QM)
│   │   │   │   ├───blinky_bsp-sam.qm   - Blinky-BSP model (for QM)
│   │   │   │   ├───bsp.hpp             - BSP header (generated by QM)
│   │   │   │   └───bsp.cpp             - BSP source (generated by QM)
│   │   │   ├───blinky_bsp-teensy4/     - Blinky example with BSP for Teensy4
│   │   │   │   ├───blinky_bsp-teensy4.ino - Blinky-BSP code (generated by QM)
│   │   │   │   ├───blinky_bsp-teensy4.qm  - Blinky-BSP model (for QM)
│   │   │   │   ├───bsp.hpp             - BSP header (generated by QM)
│   │   │   │   └───bsp.cpp             - BSP source (generated by QM)
│   │   │   └───dpp_bsp-sam/            - DPP example with BSP for SAM
│   │   │       ├───qview/              - DPP with QView demonstration
│   │   │       ├───dpp_bsp-teensy4.ino - DPP-BSP code (generated by QM)
│   │   │       ├───dpp_bsp-teensy4.qm  - DPP-BSP model (for QM)
│   │   │       ├───bsp.hpp             - BSP header (generated by QM)
│   │   │       └───bsp.cpp             - BSP source (generated by QM)
│   │   └───src/            - QP/C++ library source
│   │
│   └───qpn_avr/            - QP-nano library for AVR-based Arduinos
│       ├───examples/       - QP-nano library examples
│       │   ├───blinky/
│       │   ├───blinky_bsp/
│       │   ├───dpp/
│       │   └───pelican/
│       └───src/
├───qm/                     - QM modeling tool
│   ├───bin/                - QM binaries (executable and DLLs)
│   │   └───qm.exe          - QM executable for Windows
│   └───html/               - QM documentation
│       └───index.html
│
├───QP-Arduino_GPL_Exception.txt - GPL exception for QP on Arduino
└───README.md               - this file

NOTE: The QP-Arduino archive contains QM for Windows only. But QM is also available for Linux and MacOS hosts. If you wish to work on those operating systems, you will need to install QM separately, as described at: https://www.state-machine.com/qm/gs.html

---

Working with the Examples

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

File|Examples|Examples from Custom Libraries

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 is used only to build and upload the code to the Arduino board(s).

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.

---

Example Documentation

Each example model has documentation, which you can view in the QM tool. The model documentation shows in the Property Editor when the model item is active.

---

QP/Spy Software Tracing Support

The qpcpp_arm-cm library now supports the 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 QSPY host utility.

---

QView Demonstration

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

The dpp_bsp-sam example demonstrates the [QView monitoring]. To see this feature, you need to upload the dpp_bsp-sam code to the Arduino UNO board and then you need to launch QView, from the sub-directory qview in the dpp_bsp-sam example.

---

Licensing

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

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

---

Companion Web Page

Please refer to the companion web page to this project at:

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

---

Support Questions

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

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

qp-arduino's Issues

Teensy resets when using QF::poolInit without prior call of QS_INIT

Hello!

We've used qp-arduino for quite a while now on Teensy 4.0 and Teensy 4.1.
As the project becomes more and more involved I wanted to update to the latest version to incorporate QSPY and (proper) UnitTesting.

Adapting the Teensy-example provided with this release was easy enough to get the expected Q-SPY output. But a few issues and questions remain:

• Why are QS::onCleanup(), QS::onGetTime(), QS::onFlush() and QS::onReset() needed, even when Q-Spy is disabled (QS_ON not defined). This seems to be inconsistent with QS::onStartup() and QS::onCommand(), which do not necessarily have to be implemented. This is not a problem, just a question, though.

• When QF::poolInit(...) is called before QS::onStartup() runs, Teensy resets itself. So far I've tracked it down to these BSP-calls in QS::onStartup(void const * arg):

static uint8_t qsTxBuf[1024]; // buffer for QS transmit channel (QS-TX)
static uint8_t qsRxBuf[128];  // buffer for QS receive channel (QS-RX)
initBuf  (qsTxBuf, sizeof(qsTxBuf));
rxInitBuf(qsRxBuf, sizeof(qsRxBuf));

If initBuf and rxInitBuf are not called before initializing the event pool (QF::poolInit(...)) the MCU resets. This means, that without QS_ON no event pool can currently be used, as this surpresses the call to QS::onStartup().

To reproduce, add these lines to the Teensy setup() method after BSP::init();:

DMAMEM static QF_MPOOL_EL(uint64_t) BigPoolSto[50];
QF::poolInit(BigPoolSto, sizeof(BigPoolSto), sizeof(BigPoolSto[0]));

As long as QS_ON is defined, the code should run fine. However, if QS_ON is not defined, the MCU should crash and reset itself.

Here is the code I used to test and reproduce the problem. If you extract it into /libraries/qpcpp_arm-cm/examples/blinky-qspy-teensy4/ it should be directly executable with PlatformIO.
teensy.zip

.

Compatibility with the Arduino library registry ?

The current installation of the library is done by cloning this repository and selecting the version you want to use (arm or avr) and copying it to the Arduino Library path.

Officially Arduino has a registry repository where any library can be added and made accessible via the Arduino library manager.

https://github.com/arduino/library-registry

Why hasn't it been thought to use the official Arduino method?