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:/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:/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:/nRF24/RF24/issues/264) [#211](https:/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:/nRF24/RF24/issues/264)
+[#211](https:/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
+