Home
Softono
qp-arduino

qp-arduino

Open source C++
Website GitHub
44
Stars
28
Forks
0
Issues
11
Watchers
3 months
Last Commit
Firmware & RTOS IoT Platforms

About qp-arduino

QP/C++ real-time event framework/RTOS for Arduino (ARM Cortex-M)

Platforms

Web Self-hosted

Languages

C++

Links

Website Source Code
q
Published by
quantumleaps
Visit View Profile

README.md

View on GitHub

+TITLE: qp-arduino README

+AUTHOR: Peter Polidoro

+EMAIL: [email protected]

  • 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
  • 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 == 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 == directory. To find out where your == directory is, or to configure a different location for your == 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 == 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 == directory should look as follows:

+BEGIN_SRC sh

/ └── 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