new examples and more

.github/workflows/build_arduino.yml

@@ -0,0 +1,157 @@
+name: Arduino CLI build
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/build_arduino.yml"
+      - "examples/**"
+      - "!examples/old_backups/recipes/pingpair_maple/**"
+
+  push:
+    paths:
+      - ".github/workflows/build_arduino.yml"
+      - "examples/**"
+      - "!examples/old_backups/recipes/pingpair_maple/**"
+
+jobs:
+  check_formatting:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Check code formatting
+        uses: per1234/artistic-style-action@main
+        with:
+          options-file-path: ./examples/examples_formatter.conf
+          name-patterns: |
+            - '*.ino'
+            - '*.cpp'
+            - '*.hpp'
+            - '*.h'
+          target-paths: |
+            - examples
+  build:
+    needs: check_formatting
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        fqbn:
+          - "arduino:avr:yun"
+          - "arduino:avr:uno"
+          - "arduino:avr:diecimila"
+          - "arduino:avr:nano"
+          - "arduino:avr:mega"
+          - "arduino:avr:megaADK"
+          - "arduino:avr:leonardo"
+          - "arduino:avr:micro"
+          - "arduino:avr:esplora"
+          - "arduino:avr:mini"
+          - "arduino:avr:ethernet"
+          - "arduino:avr:fio"
+          - "arduino:avr:bt"
+          # - "arduino:avr:LilyPad"  # board not found
+          - "arduino:avr:LilyPadUSB"
+          - "arduino:avr:pro"
+          - "arduino:avr:atmegang"
+          - "arduino:avr:robotControl"
+          - "arduino:avr:robotMotor"
+          # - "arduino:avr:gemma"  # does not support SPI
+          - "arduino:avr:circuitplay32u4cat"
+          - "arduino:avr:yunmini"
+          - "arduino:avr:chiwawa"
+          - "arduino:avr:one"
+          - "arduino:avr:unowifi"
+          - "arduino:mbed:nano33ble"
+          # - "arduino:samd:mkr1000"  # InterruptConfigure.ino uses pin 2
+          # - "arduino:samd:mkrzero"  # InterruptConfigure.ino uses pin 2
+          # - "arduino:samd:mkrwifi1010"  # InterruptConfigure.ino uses pin 2
+          - "arduino:samd:nano_33_iot"
+          # - "arduino:samd:mkrfox1200"  # InterruptConfigure.ino uses pin 2
+          # - "arduino:samd:mkrwan1300"  # InterruptConfigure.ino uses pin 2
+          # - "arduino:samd:mkrwan1310"  # InterruptConfigure.ino uses pin 2
+          # - "arduino:samd:mkrgsm1400"  # InterruptConfigure.ino uses pin 2
+          # - "arduino:samd:mkrnb1500"  # InterruptConfigure.ino uses pin 2
+          # - "arduino:samd:mkrvidor4000"  # InterruptConfigure.ino uses pin 2
+          - "arduino:samd:adafruit_circuitplayground_m0"
+          - "arduino:samd:mzero_pro_bl"
+          - "arduino:samd:mzero_bl"
+          - "arduino:samd:tian"
+          - "arduino:megaavr:uno2018"
+          # - "arduino:megaavr:nano4809"  # board not found
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Compile examples
+        uses: arduino/compile-sketches@main
+        with:
+          sketch-paths: |
+            - examples/GettingStarted
+            - examples/AcknowledgementPayloads
+            - examples/ManualAcknowledgements
+            - examples/StreamingData
+            - examples/MulticeiverDemo
+            - examples/InterruptConfigure
+          #   - examples/old_backups/GettingStarted_HandlingFailures
+          #   - examples/old_backups/pingpair_dyn
+          #   - examples/old_backups/pingpair_irq
+          #   - examples/old_backups/pingpair_multi_dyn
+          #   - examples/old_backups/pingpair_sleepy
+          #   - examples/old_backups/scanner
+          #   - examples/old_backups/TransferTimeouts
+          #   - examples/old_backups/recipes/led_remote
+          #   - examples/old_backups/recipes/nordic_fob
+          #   - examples/old_backups/recipes/pingpair_maple
+          fqbn: ${{ matrix.fqbn }}
+  attiny:
+    needs: check_formatting
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        fqbn:
+          - ATTinyCore:avr:attinyx4
+          - ATTinyCore:avr:attinyx4opti
+          - ATTinyCore:avr:attinyx4micr
+          - ATTinyCore:avr:attinyx5
+          - ATTinyCore:avr:attinyx5micr
+          - ATTinyCore:avr:attinyx8
+          - ATTinyCore:avr:attinyx8opti
+          - ATTinyCore:avr:attinyx8micr
+          - ATTinyCore:avr:attinyx7
+          - ATTinyCore:avr:attinyx7opti
+          - ATTinyCore:avr:attinyx7micr
+          - ATTinyCore:avr:attinyx61
+          - ATTinyCore:avr:attinyx61opti
+          - ATTinyCore:avr:attinyx41
+          - ATTinyCore:avr:attinyx41opti
+          - ATTinyCore:avr:attinyx41micr
+          # - ATTinyCore:avr:attiny43  # doesn't seem to support USI implementation of SPI
+          - ATTinyCore:avr:attiny828
+          - ATTinyCore:avr:attiny828opti
+          - ATTinyCore:avr:attiny1634
+          - ATTinyCore:avr:attiny1634opti
+          - ATTinyCore:avr:attinyx313
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Compile examples
+        uses: arduino/compile-sketches@main
+        with:
+          platforms: |
+            - source-url: "http://drazzy.com/package_drazzy.com_index.json"
+              name: "ATTinyCore:avr"
+            - name: "arduino:avr"
+          sketch-paths: |
+            - examples/rf24_ATTiny/rf24ping85
+            - examples/rf24_ATTiny/timingSearch3pin
+          fqbn: ${{ matrix.fqbn }}

.github/workflows/build_linux.yml

@@ -1,64 +1,47 @@
-name: C/C++ CI
+name: Linux build
 
 on: [push]
 
 jobs:
-  build-RPi-BCM2835:
+  build:
     runs-on: ubuntu-latest
 
-    steps:
-      - uses: actions/checkout@v1
-      - name: provide toolchain
-        run: |
-          sudo apt-get update && \
-          sudo apt-get install binutils-arm-linux-gnueabi gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf &&
-          arm-linux-gnueabihf-gcc -v &&
-          arm-linux-gnueabihf-g++ -v
-      - name: configure
-        run: ./configure --soc=BCM2835 --driver=RPi
-      - name: make
-        run: make
-      - name: make
-        run: sudo make install
+    strategy:
+      fail-fast: false
 
-  build-RPi-BCM2836:
-    runs-on: ubuntu-latest
+      matrix:
+        config-options:
+          - "--soc=BCM2835 --driver=RPi"
+          - "--soc=BCM2836 --driver=RPi"
+          - "--soc=BCM2835 --driver=wiringPi --extra-cflags=-I/usr/local/include"
+          - "--driver=SPIDEV"
 
     steps:
       - uses: actions/checkout@v1
       - name: provide toolchain
         run: |
-          sudo apt-get update && \
-          sudo apt-get install binutils-arm-linux-gnueabi gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf &&
-          arm-linux-gnueabihf-gcc -v &&
+          sudo apt-get update
+          sudo apt-get install binutils-arm-linux-gnueabi gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
+          arm-linux-gnueabihf-gcc -v
           arm-linux-gnueabihf-g++ -v
-      - name: configure
-        run: ./configure --soc=BCM2836 --driver=RPi
-      - name: make
-        run: make
-      - name: make
-        run: sudo make install
-
-  build-wiringPi-BCM2835:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v1
-      - name: provide toolchain
-        run: |
-          sudo apt-get update && \
-          sudo apt-get install binutils-arm-linux-gnueabi gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf &&
-          arm-linux-gnueabihf-gcc -v &&
-          arm-linux-gnueabihf-g++ -v
-      - name: provide wiringPi
+          python3 --version
+      - name: provide WiringPi
+        if: ${{ matrix.config-options == '--soc=BCM2835 --driver=wiringPi --extra-cflags=-I/usr/local/include' }}
         run: |
-          git clone https://github.com/CoRfr/WiringPi &&
-          cd WiringPi/wiringPi &&
-          CC="arm-linux-gnueabihf-gcc -marm -mtune=arm1176jzf-s -mfpu=vfp -mfloat-abi=hard" V=1 make -j5 &&
+          git clone https://github.com/CoRfr/WiringPi
+          cd WiringPi/wiringPi
+          CC="arm-linux-gnueabihf-gcc -marm -mtune=arm1176jzf-s -mfpu=vfp -mfloat-abi=hard" V=1 make -j5
           sudo make install
-      - name: configure
-        run: ./configure --soc=BCM2835 --driver=wiringPi --extra-cflags=-I/usr/local/include
-      - name: make
+      - name: library configure
+        run: ./configure ${{ matrix.config-options }}
+      - name: library make
         run: make
-      - name: make
+      - name: library make install
         run: sudo make install
+      - name: make linux examples
+        # compiling examples for wiringPi is broken see nRF24#669 issue
+        if: ${{ matrix.config-options != '--soc=BCM2835 --driver=wiringPi --extra-cflags=-I/usr/local/include' }}
+        run: |
+          cd examples_linux
+          make
+          file ./gettingstarted

.github/workflows/doxygen.yml

@@ -0,0 +1,46 @@
+name: DoxyGen build
+
+on:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+  release:
+    branches:
+      - master
+    types:
+      - published
+      - edited
+
+jobs:
+  build-doxygen:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: get latest release version number
+      id: latest_ver
+      uses: pozetroninc/github-action-get-latest-release@master
+      with:
+        repository: nRF24/RF24
+    - name: checkout
+      uses: actions/checkout@v2
+    - name: overwrite doxygen tags
+      run: |
+        mkdir docs
+        touch doxygenAction
+        echo "PROJECT_NUMBER = ${{ steps.latest_ver.outputs.release }}" >> doxygenAction
+        echo "OUTPUT_DIRECTORY = ./docs" >> doxygenAction
+        echo "@INCLUDE = doxygenAction" >> Doxyfile
+    - name: build doxygen
+      uses: mattnotmitt/doxygen-action@v1
+      with:
+          working-directory: '.'
+          doxyfile-path: './Doxyfile'
+    - name: upload to github pages
+      if: ${{ github.event_name == 'release'}}
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/html

.gitignore

@@ -20,7 +20,16 @@ Session.vim
 Makefile.inc
 utility/includes.h
 examples_linux/*
-!examples_linux/**/
-!examples_linux/*.*
+examples_linux/**/*
+!examples_linux/*.cpp
+!examples_linux/*.py
+!examples_linux/**/*.cpp
+!examples_linux/Makefile
+!examples_linux/**/Makefile
+*__pycache__/
 .directory
 .idea
+doxygenAction
+.vscode/
+*venv
+*.pyc

COMMON_ISSUES.md

@@ -1,8 +1,48 @@
-# Here are the most common issues and their solutions.
+# Common Issues
 
-### I'm not receiving acks!
-If you're not receiving acks correctly/reliably on data rates lower than 2MBPS,
-try adding a big capacitor close to the module/chip. Example issues: [#264](https://github.com/nRF24/RF24/issues/264) [#211](https://github.com/nRF24/RF24/issues/211).
+## Settings that must match
+Before you report undesirable behavior, please make sure that the
+following RF24 configurations match on both receiving and transmitting
+nRF24L01 transceivers:
+1. `RF24::setAddressWidth()`
+2. `RF24::setChannel()`
+3. `RF24::setDataRate()`
+4. `RF24::setAutoAck()`
+5. `RF24::enableDynamicPayloads()` or `RF24::disableDynamicPayloads()`
+6. `RF24::enableAckPayload()` or `RF24::disableAckPayload()` (requires auto-ack and
+   dynamic payloads features)
+7. `RF24::setPayloadSize()` (only if the dynamic payloads feature is disabled -- it is disabled by default)
+8. `RF24::setCRCLength()` or `RF24::disableCRC()` (the auto-ack feature
+   automatically enables CRC because it is required)
 
-For this application, please use Electrolytic or Tantalum capacitors. Ceramic capacitors will probably not be good enough.
+Also, it helps to think of an address as a path (a commonly shared route)
+instead of an identifying device destination. This means that addresses
+have to match for a payload to travel from one transceiver to another.
+However, the pipe numbers assigned with the matching address do not have
+to match. You can think of pipes as parking spots for the packets, while
+all packets' payloads live in a TX or RX FIFO buffer. Remember that the
+TX FIFO buffers and the RX FIFO buffers both have a maximum occupancy of
+3 payloads (regardless of the maximum 32-byte payload size).
 
+## Here are the most common issues and their solutions.
+
+### write() always returns true after setAutoAck(false)
+Don't disabled the auto-ack feature. RF24::write() has no reason to doubt
+that the payload was delivered if the auto-ack feature is disabled. We
+recommend you read the docs about RF24::setAutoAck() before disabling the
+auto-ack feature.
+
+### write() returns false when the payload was received
+If the settings match on both endpoint transceivers, then this can only
+mean that the receiving nRF24L01 failed to send an acknowledgement (ACK)
+packet back to the transmitting nRF24L01. Usually this is due to
+instability (electric noise) in the power lines (VCC and GND) going to
+the receiving nRF24L01.
+
+If you're not receiving ACK packets correctly/reliably on data rates
+lower than 2MBPS, try adding a big capacitor close to the module/chip.
+Example issues: [#264](https://github.com/nRF24/RF24/issues/264)
+[#211](https://github.com/nRF24/RF24/issues/211).
+
+For reliability, please use Electrolytic or Tantalum capacitors. Ceramic
+capacitors may not be good enough (depending on the manufacturing source).

Doxyfile

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = "../../ArduinoBuilds/RF24 Docs"
+OUTPUT_DIRECTORY       = ./docs
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -928,7 +928,8 @@ EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = bcm2835* \
                          readme* \
                          runtest* \
-                         tests*
+                         tests* \
+                         README*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -2582,3 +2583,4 @@ GENERATE_LEGEND        = YES
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 DOT_CLEANUP            = YES
+