Add README.org and move images

Author: peterpolidoro

README.org

@@ -0,0 +1,269 @@
+#+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.5
+- qpcpp version: 6.9.3
+- qm version: 5.1.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_QUOTE
+lib_deps =
+    https://github.com/QuantumLeaps/qp-arduino.git
+#+END_QUOTE
+
+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.1.3/qm_5.1.3-linux64.zip
+unzip qm_5.1.3-linux64.zip && rm qm_5.1.3-linux64.zip && mv qm qm-5.1.3
+chmod u+x qm-5.1.3/bin/qm && chmod u+x qm-5.1.3/bin/qm.sh
+alias qm='~/qp/qm-5.1.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
+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
+[QP-Arduino Exception](https://www.state-machine.com/licenses/QP-Arduino_GPL_Exception.txt)
+(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 [QM model-based design tool](https://www.state-machine.com/qm/) is freeware.
+The QM tool is provided under the terms of a simple
+[End-User License Agreement (EULA)](https://www.state-machine.com/qm/license.html).
+
+* Support Questions
+
+Please submit any questions or comments to the free QP support forum at:
+
+https://sourceforge.net/p/qpc/discussion/668726