Reorganize directory structure to match typical Arduino library

Author: peterpolidoro

.gitignore

@@ -1,61 +1,63 @@
-*.obj
-*.o
-*.d
-*.lib
-*.a
-*.elf
-*.err
-*.hex
-*.exe
-*.EXE
-*.map
-*.dep
-*.pdf
-*.PDF
-*.Hbp
-*.nav
-*.tps
-*.tws
-*.tmp
-*.log
-*.chm
-*.zip
-*.pdb
-*.ncb
-*.suo
-*.chw
-*.sfr
-*.user
-*.avrsuo
-*.Debug
-*.Release
-lint*.txt
-*.Miro
-*.bak
-*.qlc
-JLink*.*
-
-qm/
-eclipse/
-test/
-test_ports/
-dbg/
-rel/
-spy/
-settings/
-.settings/
-targetConfigs/
-
-Debug/
-Release/
-Spy/
-
-lib/
-obj/
-output/
-
-doxygen/html/
-lint/*.txt
-lint/MISRA_Exemplar_Suite_test/*.txt
-
-.DS_Store
+*.obj
+*.o
+*.d
+*.lib
+*.a
+*.elf
+*.err
+*.hex
+*.exe
+*.EXE
+*.map
+*.dep
+*.pdf
+*.PDF
+*.Hbp
+*.nav
+*.tps
+*.tws
+*.tmp
+*.log
+*.chm
+*.zip
+*.pdb
+*.ncb
+*.suo
+*.chw
+*.sfr
+*.user
+*.avrsuo
+*.Debug
+*.Release
+lint*.txt
+*.Miro
+*.bak
+*.qlc
+JLink*.*
+
+eclipse/
+test/
+test_ports/
+dbg/
+rel/
+spy/
+settings/
+.settings/
+targetConfigs/
+
+Debug/
+Release/
+Spy/
+
+lib/
+obj/
+output/
+
+doxygen/html/
+lint/*.txt
+lint/MISRA_Exemplar_Suite_test/*.txt
+
+.DS_Store
+.venv
+venv
+.pio

README.md

@@ -10,114 +10,120 @@ Please refer to the companion webiste to this project at:
 https://www.state-machine.com/arduino
 
 ----
-# Software Installation
+# Provided Library and Examples
 
-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.
+This repository contains one external library for ARM Cortex-M based Arduinos:
 
-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.
+- `qp-arduino` -- QP/C++ framework for Arduinos based on ARM Cortex-M
 
 ----
-# Provided Libraries and Examples
+# Software Installation
 
-The archive `qp-<ver>_arduino-1.8.x.zip` contains two external libraries
-for SAM-based Arduinos:
+The QP adaptation for Arduino may be used either with the [Arduino
+IDE](https://www.arduino.cc/en/software) or with
+[PlatformIO](https://platformio.org/install/cli).
 
-- `qpcpp_arm-cm` -- QP/C++ framework for Arduinos based on ARM Cortex-M
-- `qpn_avr`   -- QP-nano framework for Arduinos based on AVR
+## Download Library
 
-> **NOTE:** `qpn_avr` is now obsolete. It is provided for backwards compatibility only!
+The QP adaptation for Arduino can be downloaded in a single zip archive or
+cloned to a local git repository.
 
-----
-# Provided Tools
+### Zip File
 
-The archive also contains the QM modeling tool for Windows
+https://github.com/QuantumLeaps/qp-arduino/archive/refs/heads/master.zip
 
-- `qm`        -- QM modeling tool for Windows 32/64-bit
+### Git
 
-----
-# Directories and Files
+```bash
+git clone https://github.com/QuantumLeaps/qp-arduino.git
+```
+
+## Arduino IDE
+
+You need to unzip the zip archive, or clone the git repository, 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 zip archive, or clone the git
+repository, to this folder, renaming the folder qp-arduino if necessary.
 
 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
+```
+<Sketchbook>/
+└── libraries
+    └── qp-arduino
+        ├── examples
+        │   ├── blinky-sam
+        │   ├── blinky2-sam
+        │   ├── blinky_bsp-sam
+        │   ├── blinky_bsp-teensy4
+        │   ├── dpp_bsp-sam
+        │   └── dpp_bsp-teensy4
+        └── src
+            └── qp-arduino
+```
+
+## PlatformIO
+
+Unzip the zip archive or clone the git repository into any folder you prefer.
+
+----
+# Additional Tools
 
+The QM modeling tool may be downloaded and installed from:
+
+https://www.state-machine.com/products/qm
 
 ----
 # Working with the Examples
 
+The intended way of working with the examples is to use the
+[QM modeling tool](https://www.state-machine.com/products/qm/) 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
+
 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](https://www.state-machine.com/products/qm/) 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.
 
+The Arduino IDE serial monitor may be used to observe the output of the dpp
+examples.
+
+## PlatformIO
+
+PlatformIO may be used either with its IDE or on the command line.
+
+### Command Line
+
+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:
+
+```bash
+pio run -e teensy41 -t upload
+```
+
+To use the serial monitor to observe the output of the dpp examples run:
+
+```bash
+pio device monitor
+```
 
 ----
 ## Example Documentation

libraries/qpcpp_arm-cm/examples/blinky-sam/blinky-sam.ino renamed to examples/blinky-sam/blinky-sam.ino

@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<session version="5.1.3">
+ <item name="license"></item>
+ <group name="locked"/>
+ <group name="settings">
+  <item name="tabs">1</item>
+  <item name="windows">0</item>
+  <item name="grid">3</item>
+  <item name="backups">0</item>
+ </group>
+ <group name="windows">
+  <item id="AOs::Blinky::SM">0,0,932,625,*</item>
+ </group>
+ <group name="search">
+  <item name="options">2032128</item>
+  <item name="replace">0</item>
+ </group>
+ <group name="vars"/>
+ <group name="tools">
+  <group name="tool">
+   <item name="icon">0</item>
+   <item name="title"></item>
+   <item name="command"></item>
+   <item name="args"></item>
+   <item name="dir"></item>
+   <item name="options">0</item>
+  </group>
+  <group name="tool">
+   <item name="icon">0</item>
+   <item name="title"></item>
+   <item name="command"></item>
+   <item name="args"></item>
+   <item name="dir"></item>
+   <item name="options">0</item>
+  </group>
+  <group name="tool">
+   <item name="icon">0</item>
+   <item name="title"></item>
+   <item name="command"></item>
+   <item name="args"></item>
+   <item name="dir"></item>
+   <item name="options">0</item>
+  </group>
+  <group name="tool">
+   <item name="icon">0</item>
+   <item name="title"></item>
+   <item name="command"></item>
+   <item name="args"></item>
+   <item name="dir"></item>
+   <item name="options">0</item>
+  </group>
+  <group name="tool">
+   <item name="icon">0</item>
+   <item name="title"></item>
+   <item name="command"></item>
+   <item name="args"></item>
+   <item name="dir"></item>
+   <item name="options">0</item>
+  </group>
+ </group>
+</session>