Merge pull request #7 from ZZ-Cat:PlatformIO-Transition

Migrate CRSF for Arduino library to PlatformIO

This took a lot longer than what I initially anticipated.

.gitattributes

@@ -1,8 +1,8 @@
 *.c text eol=lf
 *.cpp text eol=lf
 *.h text eol=lf
-*.ino text eol=lf linguist-language=c++
+*.ini text eol=lf
+*.json text eol=lf
 *.md text eol=lf
-*.properties text eol=lf
 *.txt text eol=lf
 *.yml text eol=lf

.gitignore

@@ -1,8 +1,10 @@
 # Artefacts for compiling the code
-/build/
+.pio/
 
 # Artefacts for Visual Studio Code
-/.vscode/
+.vscode/
 
-# Development artefacts
-/.development
+# PlatformIO specific README files
+include/README
+lib/README
+test/README

README.md

@@ -9,30 +9,9 @@
 
 Cassandra "ZZ Cat" Robinson
 
-## Discontinuation of Arduino IDE
+## Warnings
 
-Arduino IDE support in Visual Studio Code is being discontinued.
-The Visual Studo Code extension that adds support for Arduino is discontinuing support for the Arduino IDE.
-This means that I too am discontinuing support for the Arduino IDE in all of my projects - starting with CRSF for Arduino.
-The good news is that my library is in its early stages of development, I have not yet made any official releases of my library, & it isn't being widely used yet. This makes it easier for me to adapt to the new changes.
-
-Does this mean that I may need to rebrand my library? Yes.
-I originally created my library for use within the Arduino IDE (assuming 1.8, here. Not 2.0) without being aware of the fact that the IDE itself had already reached the end of its life, & Arduino themselves had discontinued it.
-If I kept the name "CRSF for Arduino" moving forward, this would imply that you can still use it in the (now discontinued) Arduino IDE. Thus, sending the wrong message about what my library is compatible with.
-
-What of my two existing branches involving telemetry?
-Well... for starters, I rebased Telemetry-Feedback & during that rebase, I somehow managed to completely obliterate my code for telemetry feedback. =</.>=
-I don't know how I did that, but it happened. I was already planning on refactoring it anyway, so now I am having to rewrite it entirely.
-
-So, where to, from here?
-I am no longer using the Arduino IDE.
-In fact, I haven't actually used the Arduino IDE itself in a _very_ long time. All of my development is done in Visual Studio Code, these days. For my Arduino-related projects, I have been using an extension in Visual Studio Code that adds support for the Arduino IDE. The developers of this extension are discontinuing support for the Arduino IDE altogether, & they have no plans to introduce support for version 2.0 of the Arduino IDE.
-
-It _just so happens_ that over the last two days, I have been conducting preliminary tests with PlatformIO & learning how to develop with that. PlatformIO is 100% platform agnostic, has its own built-in debugging system, it even has its own Continuous Integration/Continuous Deployment (I have been chasing after decent CI/CD ever since I started my project), & it has everything that I need & nothing that I don't need.
-At this point, I am like "Where has this been all my life & why am I not already using it?"
-Using PlatformIO is a no-brainer, for me. So, there you go. From 2023-02-17 10:48 Hrs NZDT, I am using PlatformIO as my IDE of choice for developing my embedded systems projects.
-
-## Warning
+### This is not yet ready for prime time release
 
 CRSFforArduino is undergoing active development & is not yet ready for prime time release.
 If you choose to use CRSFforArduino in its current state, do so at your own risk.
@@ -42,6 +21,11 @@ Fear not! I am working on this library (aside from flying my helicopters & helpi
 
 If you have spotted any bugs, something isn't working the way it should, or you have any suggestions on what you want to see in CRSFforArduino, don't hesitate to open an Issue. The Discussions tab is also open, so if you want to chat to me about my library, feel free to do so there.
 
+### Arduino IDE is discontinued
+
+Arduino IDE support in Visual Studio Code is discontinued.
+As of 2023-02-17 10:48 Hrs NZDT, I am using PlatformIO as my IDE of choice for development.
+
 ## Description
 
 Traditional PWM RC receivers are becoming a thing of the past & (by extension) are getting harder & harder to come by.
@@ -63,18 +47,31 @@ These installation instructions will be updated as soon as the transition to Pla
 
 ### Prerequisites
 
-You need these before you can use CRSFforArduino.
+You need these before you can use CRSF for Arduino.
 
-- [Adafruit's SAMD Board Support package](https://github.com/adafruit/ArduinoCore-samd)
-- [Adafruit's Zero DMA driver](https://github.com/adafruit/Adafruit_ZeroDMA)
-- [Arduino's SAMD Board Support package](https://github.com/arduino/ArduinoCore-samd)
-- [Arduino IDE](https://www.arduino.cc/en/software) If you are using the VSCode plugin, use the Arduino IDE version 1.8.19. Otherwise, use the very latest version of the Arduino IDE.
+- [Visual Studio Code](https://code.visualstudio.com/) with the following extensions:
+  - [C/C++ Extensions Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack), which includes:
+    - C/C++
+    - C/C++ Themes
+    - CMake
+    - CMake Tools
+  - [PlatformIO IDE](https://platformio.org/)
 
 ### Download CRSFforArduino
 
-1. Click the green code button & hit "Download ZIP".
-2. Extract that to your libraries' directory. EG ```C:\Users\..\Documents\Arduino\libraries```
-3. Start up the Arduino IDE (or VSCode, if you're using that instead).
+#### Quick-&-easy way
+
+- COMING SOON
+
+#### The "Old Skool" way
+
+1. Click on the green "<> Code" button.
+2. Click "Download ZIP" & extract it to wherever is convenient for you.
+3. Go into the CRSFforArduino folder, here is where Arduino diverges from PlatformIO.
+   - **Arduino IDE:**
+     - Go into the lib folder & copy the _CRSFforArduino_ folder to your Arduino IDE's library directory.
+   - **PlatformIO:**
+     - Go into the _top level_ CRSFforArduino folder & copy the _lib_ folder to your PlatformIO project's directory.
 
 ## How to use CRSFforArduino
 
@@ -150,16 +147,19 @@ void loop()
 
 ### Example Sketches
 
-In the ```examples``` folder, there is a sketch called ```channels.ino``` that I used to test this library.
+In the ```examples``` folder, there is a sketch called ```channels.cpp``` that I used to test this library.
 It contains instructions on how to set your hardware up & how to connect your receiver to your development board.
 It also details binding procedures (if needed), & the channel ranges & channel order.
 The example sketch also demonstrates how to read RC channels data from your connected ExpressLRS receiver.
 
+You can build this example to see how CRSF for Arduino works.
+
 ### Flashing
 
-1. Verify your sketch.
-2. Select your com port that your development board is connected to.
-3. Upload your sketch to your development board.
+Flashing is a lot simpler with PlatformIO when compared to the Arduino IDE.
+
+1. Build your sketch ► ```pio run``` in your CLI or ```ctrl+alt+b``` on your keyboard.
+2. Flash your sketch ► ```pio run -t upload``` or ```ctrl+alt+u``` on your keyboard.
 
 ### Viewing RC data
 
@@ -171,22 +171,20 @@ The example sketch also demonstrates how to read RC channels data from your conn
 Here is a list of target development boards CRSFforArduino is compatible with:
 
 - SAMD21 based boards:
-  - Adafruit Crickit M0
   - Adafruit Feather M0 & variants
-  - Adafruit Gemma M0
   - Adafruit ItsyBitsy M0 Express
   - Adafruit QtPy M0
   - Adafruit Trinket M0
   - Arduino MKR series
   - Arduino Zero
 - SAMD51 based boards:
   - Adafruit Feather M4 Express
-  - Adafruit Feather M4 CAN Express
+  - Adafruit Grand Central M4
   - Adafruit ItsyBitsy M4 Express
   - Adafruit Metro M4 Express
   - Adafruit Metro M4 Express AirLift Lite
 - SAME51 based boards:
-  - Adafruit Grand Central M4
+  - Adafruit Feather M4 CAN Express
 
 Compatibility with other microcontroller boards may be added in the future, if there is demand for it. Keep in mind that this will be subject to hardware limitations of the host microcontroller itself.
 

include/README

@@ -0,0 +1,39 @@
+
+This directory is intended for project header files.
+
+A header file is a file containing C declarations and macro definitions
+to be shared between several project source files. You request the use of a
+header file in your project source file (C, C++, etc) located in `src` folder
+by including it, with the C preprocessing directive `#include'.
+
+```src/main.c
+
+#include "header.h"
+
+int main (void)
+{
+ ...
+}
+```
+
+Including a header file produces the same results as copying the header file
+into each source file that needs it. Such copying would be time-consuming
+and error-prone. With a header file, the related declarations appear
+in only one place. If they need to be changed, they can be changed in one
+place, and programs that include the header file will automatically use the
+new version when next recompiled. The header file eliminates the labor of
+finding and changing all the copies as well as the risk that a failure to
+find one copy will result in inconsistencies within a program.
+
+In C, the usual convention is to give header files names that end with `.h'.
+It is most portable to use only letters, digits, dashes, and underscores in
+header file names, and at most one dot.
+
+Read more about using header files in official GCC documentation:
+
+* Include Syntax
+* Include Operation
+* Once-Only Headers
+* Computed Includes
+
+https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html

examples/channels/channels.ino → lib/CRSFforArduino/examples/channels/channels.cpp

@@ -23,31 +23,29 @@
  *
  * @section Dependencies
  *
- * This example sketch depends on the following libraries:
- * - Adafruit_ZeroDMA (This is included with the Adafruit Metro M4 Express board package.)
- * - Arduino.h (This is included with the Arduino IDE.)
- * - CRSFforArduino.h
+ * PlatformIO will automatically install the following dependencies:
+ * - Adafruit ZeroDMA Library
  *
  * @section Quick Start
  *
  * 1. Connect the receiver to the Metro M4 Express using the following pinout:
- *   - TX pin to Metro M4 Express RX (Pin 0).
- *   - RX pin to Metro M4 Express TX (Pin 1).
- *   - GND pin to Metro M4 Express GND.
- *   - 5V pin to Metro M4 Express 5V.
+ *    - TX pin to Metro M4 Express RX (Pin 0).
+ *    - RX pin to Metro M4 Express TX (Pin 1).
+ *    - GND pin to Metro M4 Express GND.
+ *    - 5V pin to Metro M4 Express 5V.
  * 2. Connect the Metro M4 Express to your computer using a USB cable.
- * 3. Select the Metro M4 Express board and the correct port in the Arduino IDE.
- *   - Tools > Board > Adafruit Metro M4 (SAMD51)
- *   - Tools > Port > COM# (where # is the port number)
- * 4. Open the CRSFforArduino library example sketch channels.ino.
- *   - File > Examples > CRSFforArduino > channels
- * 5. Upload the sketch to the Metro M4 Express.
- *   - Sketch > Upload
- * 6. Open the Serial Monitor.
- *   - Tools > Serial Monitor
- * 7. Set the Serial Monitor baud rate to 115200.
- * 8. Set the Serial Monitor line ending to "Both NL & CR".
- * 9. Turn on your transmitter.
+ * 3. Build the firmware:
+ *    - Method 1: pio run
+ *    - Method 2: ctlr+alt+B
+ * 4. Flash your Metro M4 Express.
+ *    - Method 1: pio run -t upload
+ *    - Method 2: ctlr+alt+U
+ * 5. Configure the Serial Monitor:
+ *    - Port: Select the port that your Metro M4 Express is connected to.
+ *    - Baud Rate: 115200
+ *    - Line Ending: Both NL & CR
+ * 6. Turn on your transmitter.
+ * 7. Click "Start Monitoring" on the Serial Monitor.
  *
  * @section Binding (Optional & only needed for the first time)
  *
@@ -61,15 +59,15 @@
  * @par TBS Crossfire:
  * 1. Turn on your transmitter.
  * 2. On your transmitter, open up the TBS Agent Lite app.
- *   - Radio Settings > Tools > TBS Agent Lite
+ *    - Radio Settings > Tools > TBS Agent Lite
  * 3. In TBS Agent Lite, select the Micro TX & enable Binding Mode.
- *   - XF Micro TX > Bind > Execute
+ *    - XF Micro TX > Bind > Execute
  * 4. Power on the Nano Diversity Receiver.
- *   - If you have already powered on the receiver, power it off and then back on again.
- *   - You do not need to hold the bind button on the receiver.
- *   - Binding will begin automatically.
- *   - The Status LED will turn solid green when the receiver is bound.
- *   - The Status LED on the Micro TX will turn solid green when the receiver is bound.
+ *    - If you have already powered on the receiver, power it off and then back on again.
+ *    - You do not need to hold the bind button on the receiver.
+ *    - Binding will begin automatically.
+ *    - The Status LED will turn solid green when the receiver is bound.
+ *    - The Status LED on the Micro TX will turn solid green when the receiver is bound.
  * 5. Close TBS Agent Lite.
  *
  * @section Output
@@ -87,6 +85,7 @@
  *
  */
 
+#include "Arduino.h"
 #include "CRSFforArduino.h"
 
 CRSFforArduino crsf = CRSFforArduino(&Serial1);
@@ -104,7 +103,7 @@ void setup()
     crsf.begin();
 
     // Show the user that the sketch is ready.
-    Serial.println("Channels Example");
+    Serial.println("RC Channels Example");
     delay(1000);
     Serial.println("Ready");
     delay(1000);

lib/CRSFforArduino/library.json

@@ -0,0 +1,45 @@
+{
+    "$schema": "https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/schema/library.json",
+    "name": "CRSFforArduino",
+    "version": "0.1.0",
+    "description": "Arduino library for Crossfire protocol",
+    "keywords": [
+        "adafruit",
+        "arduino",
+        "communication",
+        "crossfire",
+        "crsf",
+        "elrs",
+        "expresslrs",
+        "tbs",
+        "telemetry",
+        "protocol",
+        "remote control",
+        "rc"
+    ],
+    "repository":
+    {
+        "type": "git",
+        "url": "https://github.com/ZZ-Cat/CRSFforArduino"
+    },
+    "authors": [
+        {
+            "name": "Cassandra \"ZZ Cat\" Robinson",
+            "email": "nicad.heli.flier@gmail.com",
+            "maintainer": true
+        }
+    ],
+    "license": "GPL-3.0-or-later",
+    "frameworks": "arduino",
+    "platforms": "atmelsam",
+    "headers": [
+        "Arduino.h",
+        "CRSFforArduino.h"
+    ],
+    "dependencies":
+    {
+        "adafruit/Adafruit Zero DMA Library": "@^1.1.1",
+        "frameworks": "arduino",
+        "platforms": "atmelsam"
+    }
+}

src/CRSFforArduino.cpp → lib/CRSFforArduino/src/CRSFforArduino.cpp

@@ -170,7 +170,7 @@ bool CRSFforArduino::update()
             // Check if the packet is a CRSF frame.
             if (_crsfFrame.frame.deviceAddress == CRSF_ADDRESS_FLIGHT_CONTROLLER)
             {
-                uint8_t payloadSize = _crsfFrame.frame.frameLength - 2;
+                // uint8_t payloadSize = _crsfFrame.frame.frameLength - 2;
 
                 // Check if the packet is a CRSF RC frame.
                 if (_crsfFrame.frame.type == CRSF_FRAMETYPE_RC_CHANNELS_PACKED)
@@ -292,19 +292,15 @@ Sercom *CRSFforArduino::_getSercom()
 
 #if defined(__SAMD21E18A__)
 
-/* Adafruit Gemma M0, QtPy M0 & Trinket M0. */
-#if defined(ADAFRUIT_GEMMA_M0) || defined(ADAFRUIT_QTPY_M0) || defined(ADAFRUIT_TRINKET_M0)
+/* Adafruit QtPy M0 & Trinket M0. */
+#if defined(ADAFRUIT_QTPY_M0) || defined(ADAFRUIT_TRINKET_M0)
     sercom = SERCOM0;
 #endif
 
 #elif defined(__SAMD21G18A__)
 
-/* Adafruit Crickit M0. */
-#if defined(ADAFRUIT_CRICKIT_M0)
-    sercom = SERCOM5;
-
 /* Adafruit Feather M0 , Feather M0 Express, ItsyBitsy M0 & Metro M0 Express. */
-#elif defined(ADAFRUIT_FEATHER_M0) || defined(ADAFRUIT_FEATHER_M0_EXPRESS) || defined(ADAFRUIT_ITSYBITSY_M0) || \
+#if defined(ADAFRUIT_FEATHER_M0) || defined(ADAFRUIT_FEATHER_M0_EXPRESS) || defined(ADAFRUIT_ITSYBITSY_M0) || \
     defined(ADAFRUIT_METRO_M0_EXPRESS)
     sercom = SERCOM0;