Samd51 Support

.github/dependabot.yml

@@ -3,7 +3,7 @@ updates:
   - package-ecosystem: 'github-actions'
     directory: '/'
     schedule:
-      interval: 'daily'
+      interval: 'weekly'
     labels:
       - 'CI/CD'
     commit-message:

.github/workflows/build_examples.yaml

@@ -9,10 +9,31 @@ concurrency:
 
 jobs:
   build_examples:
-    name: Build all examples with PlatformIO and the Arduino CLI
+    name: Build standard examples with PlatformIO and the Arduino CLI
     if: ${{ ! contains(github.event.head_commit.message, 'ci skip') }}
     uses: EnviroDIY/workflows/.github/workflows/build_examples.yaml@main
     with:
-      boards_to_build: 'mayfly,uno,megaatmega2560,leonardo,zeroUSB,arduino_nano_esp32,feather328p,feather32u4,adafruit_feather_m0,adafruit_feather_m4,adafruit_grandcentral_m4,huzzah,featheresp32,nodemcu,nodemcuv2,esp32dev,esp32-c3-devkitm-1,esp32-s3-devkitm-1'
-      examples_to_build: 'examples/a_wild_card,examples/b_address_change,examples/c_check_all_addresses,examples/d_simple_logger,examples/e_continuous_measurement,examples/f_basic_data_request,examples/g_terminal_window,examples/h_SDI-12_slave_implementation,examples/i_SDI-12_interface,examples/j_external_pcint_library,examples/k_concurrent_logger,examples/l_verify_crc/,'
+      boards_to_build: 'mayfly,uno,megaatmega2560,leonardo,zeroUSB,arduino_nano_esp32,feather328p,feather32u4,adafruit_feather_m0,adafruit_feather_m4,huzzah,featheresp32,esp32-c3-devkitm-1,esp32-s3-devkitm-1'
+      examples_to_build: 'examples/a_wild_card,examples/b_address_change,examples/c_check_all_addresses,examples/d_simple_logger,examples/e_continuous_measurement,examples/f_basic_data_request,examples/g_terminal_window,examples/h_SDI-12_slave_implementation,examples/i_SDI-12_interface,examples/k_concurrent_logger,examples/l_verify_crc'
     secrets: inherit
+
+
+  build_ext_ints:
+    name: Build the External Interrupt Example
+    runs-on: ubuntu-latest
+    if: ${{ ! contains(github.event.head_commit.message, 'ci skip') }}
+    env:
+      PLATFORMIO_BUILD_CACHE_DIR: ~/.platformio/caches
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup PlatformIO
+        uses: EnviroDIY/[email protected]
+
+      - name: Build PlatformIO examples
+        env:
+          PLATFORMIO_BUILD_FLAGS: -D SDI12_EXTERNAL_PCINT
+          PLATFORMIO_CI_SRC: examples/j_external_pcint_library
+        run: pio ci --board=mayfly --board=uno --board=megaatmega2560 --board=leonardo --board=zeroUSB --board=feather328p --board=feather32u4 --board=adafruit_feather_m0 --lib="." --project-option="lib_deps=greygnome/EnableInterrupt@^1.1.0"

.gitignore

@@ -166,3 +166,5 @@ SDI12 Repo Token.txt
 boards/
 lib/
 variants/
+docs/DoxygenLayout.xml_archive
+/pio_common_libdeps.ini

ChangeLog.md

@@ -12,13 +12,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Added python version to GitHub actions (for PlatformIO)
+- Switched to reusable workflows for GitHub actions
+- Consolidated timer prescaler math
+- Moved bitTimes and mul8x8to16 functions to the timers files
+- Replace c-style casts with c++ style casts
+- Do not disable interrupts during Tx for processors over 48MHz
+- Cast all timer values and math to the proper type for the processor timer being read
+  - SAMD21 boards now use the full 16-bits of the timer rather than only the first 8-bits.
+  - AVR xU4 boards (ie, 32u4/Leonardo) still use the 10-bit timer as an 8-bit timer.
+- Shortened name of espressif ISR access macro from `ESPFAMILY_USE_INSTRUCTION_RAM` to `ISR_MEM_ACCESS`
+  - This does not change any functionality of the macro, just the name.
+- Moved defines to the top of the SDI12_boards.h file
+- Renamed the "tools" directory to "extras" in compliance with Arduino library standards.
 
 ### Added
 
+- Added support for SAMD51 processors using dedicated timers
+- Added parity checking on character reception
+  - This can be disabled by defining the macro `SDI12_IGNORE_PARITY`
+- Allowing (_**without testing**_) processors over 48MHz to use `micros()` function
+- Added a 'yield' function within stream functions to allow the buffer to fill
+  - The yield time can be modified using the macro `SDI12_YIELD_MS`
+
 ### Removed
 
+- Offloaded some internal header file documentation to markdown files
+- Consolidated redundant `READTIME` and `TCNTX` macros, removing `TCNTX`
+- Removed documation m_span commands
+
 ### Fixed
 
+- Added an extra addition/removal of interrupts for espressif boards in the `begin` function to properly initialize the interrupts and avoid a later error with the `gpio_install_isr_service`.
+
 ***
 
 ## v2.1.4 (2021-05-05) [Revert wake delay to 0ms](https://github.com/EnviroDIY/Arduino-SDI-12/releases/tag/v2.1.4)

README.md

@@ -21,7 +21,8 @@ Extensive documentation on the SDI-12 functions and classes is available here:
 
 ### Renaming Notice<!-- {#mainpage_rename} -->
 
-**As of version 2.0.0 this library was renamed from "Arduino-SDI-12" to simply "SDI-12" to comply with requirements for inclusion in the Arduino.cc's IDE and Library Manager.**
+> [!IMPORTANT]
+> **As of version 2.0.0 this library was renamed from "Arduino-SDI-12" to simply "SDI-12" to comply with requirements for inclusion in the Arduino.cc's IDE and Library Manager.**
 
 [//]: # ( @tableofcontents )
 
@@ -35,9 +36,9 @@ Extensive documentation on the SDI-12 functions and classes is available here:
   - [Origins and Inherited Limitations](#origins-and-inherited-limitations)
   - [Compatibility Considerations](#compatibility-considerations)
   - [Variants and Branches](#variants-and-branches)
-      - [EnviroDIY\_SDI12](#envirodiy_sdi12)
-      - [EnviroDIY\_SDI12\_PCINT3](#envirodiy_sdi12_pcint3)
-      - [EnviroDIY\_SDI12\_ExtInts](#envirodiy_sdi12_extints)
+    - [EnviroDIY\_SDI12](#envirodiy_sdi12)
+    - [EnviroDIY\_SDI12\_PCINT3](#envirodiy_sdi12_pcint3)
+    - [EnviroDIY\_SDI12\_ExtInts](#envirodiy_sdi12_extints)
   - [Contribute](#contribute)
   - [License](#license)
   - [Credits](#credits)
@@ -105,7 +106,7 @@ The known compatibile pins for common variants are shown below:
 
 - 0, 11, 12, 13, 14, 15, 50, 51, 52, 53, A8 (62), A9 (63), A10 (64), A11 (65), A12 (66), A13 (67), A14 (68), A15 (69)
 
-**AtMega32u4 / Arduino Leonardo or Adafruit Feather:**
+**AtMega32u4 / Arduino Leonardo or Adafruit Feather 32u4:**
 
 - 8, 9, 10, 11, 14 (MISO), 15 (SCK), 16 (MOSI)
 
@@ -129,20 +130,20 @@ As we've described, the default "master" branch of this library will conflict wi
 To allow simultaneous use of SDI-12 and SoftwareSerial, we have created additional variants of these libraries that we maintain as separate branches of this repository.
 For background information, my be helpful to read our [Overview of Interrupts](https://github.com/EnviroDIY/Arduino-SDI-12/wiki/2b.-Overview-of-Interrupts) wiki page or this [Arduino Pin Change Interrupts article](https://thewanderingengineer.com/2014/08/11/arduino-pin-change-interrupts/).
 
-#### EnviroDIY_SDI12<!-- {#mainpage_master} -->
+### EnviroDIY_SDI12<!-- {#mainpage_master} -->
 
 EnviroDIY_SDI12 is the default master branch of this repository.
 It controls and monopolizes all pin change interrupt vectors, and can therefore have conflicts with any variant of SoftwareSerial and other libraries that use interrupts.
 
-#### EnviroDIY_SDI12_PCINT3<!-- {#mainpage_pcint3} -->
+### EnviroDIY_SDI12_PCINT3<!-- {#mainpage_pcint3} -->
 
 EnviroDIY_SDI12_PCINT3 is in the Mayfly branch of this repository, and was historically was called "SDI12_mod".
 It's been cropped to only control interrupt vector 3, or PCINT3 (D), which on the Mayfly (or Sodaq Mbili) corresponds to Pins D0-D7.
 It is designed to be compatible with [EnviroDIY_SoftwareSerial_PCINT12](https://github.com/EnviroDIY/SoftwareSerial_PCINT12) library (which controls interrupt vectors PCINT1 (B) & PCINT2 (C) / Mayfly pins D08-D15 & D16-D23) and [EnviroDIY PcInt PCINT0](https://github.com/EnviroDIY/PcInt_PCINT0) (which controls interrupt vectors PCINT0 (A) / Mayfly pins D24-D31/A0-A7).
 Note that different AtMega1284p boards have a different mapping from the physical PIN numbers to the listed digital PIN numbers that are printed on the board.
 One of the most helpful lists of pins and interrupts vectors is in the the [Pin/Port Bestiary wiki page for the Enable Interrupt library](https://github.com/GreyGnome/EnableInterrupt/wiki/Usage#PIN__PORT_BESTIARY).
 
-#### EnviroDIY_SDI12_ExtInts<!-- {#mainpage_extints} -->
+### EnviroDIY_SDI12_ExtInts<!-- {#mainpage_extints} -->
 
 EnviroDIY_SDI12_ExtInts is the ExtInt branch of this repository.
 It doesn't control any of the interrupts, but instead relies on an external interrupt management library (like [EnableInterrupt](https://github.com/GreyGnome/EnableInterrupt)) to assign the SDI-12 receive data function to the right pin.

docs/CreatingACharacter.md

@@ -59,22 +59,22 @@ And lets remind ourselves of the static variables we're using to store states:
 The `rxState`, `rxMask`, and `rxValue` all work together to form a character.
 When we're waiting for a start bit `rxValue` is empty, `rxMask` has only the bottom bit set, and `rxState` is set to WAITING-FOR-START-BIT:
 
-```
-    rxValue: |     0   0   0   0   0   0   0   0
--------------|-----------------------------------
-     rxMask: |     0   0   0   0   0   0   0   1
-    rxState: |     1   1   1   1   1   1   1   1
+```unparsed
+| rxValue: | 0   0   0   0   0   0   0   0 |
+| -------- | ----------------------------- |
+| rxMask:  | 0   0   0   0   0   0   0   1 |
+| rxState: | 1   1   1   1   1   1   1   1 |
 ```
 
 ### The Start of a Character<!-- {#rx_mask_start} -->
 
 After we get a start bit, the `startChar()` function creates a blank slate for the new character, so our values are:
 
-```
-    rxValue: |     0   0   0   0   0   0   0   0
--------------|-----------------------------------
-     rxMask: |     0   0   0   0   0   0   0   1
-    rxState: |     0   0   0   0   0   0   0   0
+```unparsed
+| rxValue: | 0   0   0   0   0   0   0   0 |
+| -------- | ----------------------------- |
+| rxMask:  | 0   0   0   0   0   0   0   1 |
+| rxState: | 0   0   0   0   0   0   0   0 |
 ```
 
 ### The Interrupt Fires<!-- {#rx_mask_fire} -->
@@ -93,51 +93,23 @@ For **each bit time that passed**, we apply the `rxMask` to the `rxValue`.
 #### A LOW/1 Bit<!-- {#rx_mask_low} -->
 
 - if the data bit received is LOW (1) we do an `|=` (bitwise OR) between the `rxMask` and the `rxValue`
-[//]: # ( @dot )
-
-digraph xor {
-  graph[rankdir=BT];
-  node[shape=record];
 
-  rxValue[label="{ {<rxValue>rxValue|<rxValue7>0|<rxValue6>0|<rxValue5>0|<rxValue4>0|<rxValue3>0|<rxValue2>0|<rxValue1>0|<rxValue0>1} }"];
-  maskState[label=" {<rxMask>rxMask|<rxState>rxState}|{<rxMask7>0|<rxState7>0}|{<rxMask6>0|<rxState6>0}|{<rxMask5>0|<rxState5>0}|{<rxMask4>0|<rxState4>0}|{<rxMask3>0|<rxState3>0}|{<rxMask2>0|<rxState2>0}|{<rxMask1>0|<rxState1>0}|{<rxMask0>0|<rxState0>0}"];
-
-  maskState:rxMask0 -> rxValue:rxValue0[label="bit-wise or (|=) puts the one \nfrom the rxMask into the rxValue"];
-}
-
-[//]: # ( @enddot )
-
-
-```
-    rxValue: |     0   0   0   0   0   0   0   1
--------------|---------------------------------^- bit-wise or puts the one
-     rxMask: |     0   0   0   0   0   0   0   1      from the rxMask into
-    rxState: |     0   0   0   0   0   0   0   0      the rxValue
+```unparsed
+| rxValue: | 0   0   0   0   0   0   0   1 |
+| -------- | ----------------------------- |^- bit-wise or puts the one
+|  rxMask: | 0   0   0   0   0   0   0   1 |   from the rxMask into
+| rxState: | 0   0   0   0   0   0   0   0 |   the rxValue
 ```
 
 #### A HIGH/0 Bit<!-- {#rx_mask_high} -->
 
 - if the data bit received is HIGH (0) we do nothing
 
-
-[//]: # ( @dot )
-
-digraph xor {
-  graph[rankdir=BT];
-  node[shape=record];
-
-  rxValue[label="{ {<rxValue>rxValue|<rxValue7>0|<rxValue6>0|<rxValue5>0|<rxValue4>0|<rxValue3>0|<rxValue2>0|<rxValue1>0|<rxValue0>1} }"];
-  maskState[label=" {<rxMask>rxMask|<rxState>rxState}|{<rxMask7>0|<rxState7>0}|{<rxMask6>0|<rxState6>0}|{<rxMask5>0|<rxState5>0}|{<rxMask4>0|<rxState4>0}|{<rxMask3>0|<rxState3>0}|{<rxMask2>0|<rxState2>0}|{<rxMask1>0|<rxState1>0}|{<rxMask0>0|<rxState0>0}"];
-
-  maskState:rxMask0 -> rxValue:rxValue0[label="nothing happens",arrowhead="obox"];
-}
-
-[//]: # ( @enddot )
-```
-    rxValue: |     0   0   0   0   0   0   0   0
--------------|---------------------------------x- nothing happens
-     rxMask: |     0   0   0   0   0   0   0   1
-    rxState: |     0   0   0   0   0   0   0   0
+```unparsed
+| rxValue: | 0   0   0   0   0   0   0   0 |
+| -------- | ----------------------------- |x- nothing happens
+|  rxMask: | 0   0   0   0   0   0   0   1 |
+| rxState: | 0   0   0   0   0   0   0   0 |
 ```
 
 #### Shifting Up<!-- {#rx_mask_shift} -->
@@ -148,13 +120,13 @@ The top bit falls off.
   - we always add a 0 on the `rxMask` and the `rxValue`
   - the values of the second bit of the `rxValue` (?) depends on what we did in the step above
 
-```
-    rxValue: |     0        <--- | 0   0   0   0   0   0   ?   0 <--- add a zero
--------------|-------------------|---------------------------|---
-     rxMask: |     0        <--- | 0   0   0   0   0   0   1   0 <--- add a zero
-    rxState: |     0        <--- | 0   0   0   0   0   0   0   1 <--- add a one
--------------|-------------------|---------------------------|---
-             | falls off the top |                           | added to the bottom
+```unparsed
+| rxValue:          | 0        <---       | 0   0   0   0   0   0   ?   0 <--- add a zero |
+| ----------------- | ------------------- | --------------------------------------------- |
+| rxMask:           | 0        <---       | 0   0   0   0   0   0   1   0 <--- add a zero |
+| rxState:          | 0        <---       | 0   0   0   0   0   0   0   1 <--- add a one  |
+| ----------------- | ------------------- | --------------------------------------------- |
+| ----------------- | ^ falls off the top | ------- added to the bottom ^                 |
 ```
 
 ### A Finished Character<!-- {#rx_mask_fin} -->
@@ -164,11 +136,11 @@ The `rxMask`  will have the one in the top bit.
 And the rxState will be filled - which just happens to be the value of `WAITING-FOR-START-BIT` for the next character.
 
 
-```
-    rxValue: |     ?   ?   ?   ?   ?   ?   ?   ?
--------------|-----------------------------------
-     rxMask: |     1   0   0   0   0   0   0   0
-    rxState: |     1   1   1   1   1   1   1   1
+```unparsed
+| rxValue: | ?   ?   ?   ?   ?   ?   ?   ? |
+| -------- | ----------------------------- |
+| rxMask:  | 1   0   0   0   0   0   0   0 |
+| rxState: | 1   1   1   1   1   1   1   1 |
 ```
 
 ## The Full Interrupt Function<!-- {#rx_fxn} -->
@@ -205,7 +177,7 @@ void SDI12::receiveISR() {
     // data, parity, or stop bit.
 
     // Check how many bit times have passed since the last change
-    uint16-t rxBits = bitTimes((uint8-t)(thisBitTCNT - prevBitTCNT));
+    uint16-t rxBits = bitTimes(static_cast<sditimer_t>(thisBitTCNT - prevBitTCNT));
     // Calculate how many *data+parity* bits should be left in the current character
     //      - Each character has a total of 10 bits, 1 start bit, 7 data bits, 1 parity
     // bit, and 1 stop bit