diff --git a/.gitattributes b/.gitattributes index b88e369a..fd430872 100644 --- a/.gitattributes +++ b/.gitattributes @@ -10,3 +10,22 @@ *.cpp text eol=lf *.c text eol=lf configure text eol=lf +.yaml text eol=lf +*.yml text eol=lf +*.md text eol=lf +*.txt text eol=lf +*.json text eol=lf +*.properties text eol=lf +LICENSE text eol=lf +nurfile text eol=lf +.gitignore text eol=lf +.gitattributes text eol=lf +.clang-format text eol=lf +.clang-tidy text eol=lf +Makefile text eol=lf +*.svg text eol=lf +*.ino text eol=lf +*.dot text eol=lf +*.cmake text eol=lf +*.css text eol=lf +Doxyfile text eol=lf diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 05a48fc6..078f0cef 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -10,4 +10,10 @@ updates: # default location of `.github/workflows` directory: "/" schedule: - interval: "weekly" + interval: "monthly" + cooldown: + default-days: 5 + groups: + actions: + patterns: + - "*" diff --git a/.github/doxygen.py b/.github/doxygen.py index 7cdf569f..9a89d1b7 100644 --- a/.github/doxygen.py +++ b/.github/doxygen.py @@ -4,6 +4,7 @@ Running this locally will alter the Doxyfile. Such changes SHOULD NOT be pushed to the remote. """ + from pathlib import Path import json @@ -17,9 +18,12 @@ def overwrite_doxygen_value(): properties = json.loads(PROPERTIES.read_text(encoding="utf-8")) assert "version" in properties config = CONFIG.read_text(encoding="utf-8") - TMP.write_text("PROJECT_NUMBER = {}\n".format(properties["version"]), encoding="utf-8") + TMP.write_text( + "PROJECT_NUMBER = {}\n".format(properties["version"]), encoding="utf-8" + ) config += f"\n@INCLUDE = {str(TMP)}\n" CONFIG.write_text(config, encoding="utf-8") + if __name__ == "__main__": overwrite_doxygen_value() diff --git a/.github/workflows/build_arduino.yml b/.github/workflows/build_arduino.yml index f4dd5032..b578af60 100644 --- a/.github/workflows/build_arduino.yml +++ b/.github/workflows/build_arduino.yml @@ -1,163 +1,172 @@ -name: Arduino CLI build - -on: - pull_request: - branches: [master] - paths: - - ".github/workflows/build_arduino.yml" - - "examples/**" - - "!examples/old_backups/**" - - "RF24.*" - push: - branches: [master] - paths: - - ".github/workflows/build_arduino.yml" - - "examples/**" - - "!examples/old_backups/**" - -jobs: - build: - uses: nRF24/.github/.github/workflows/build_arduino.yaml@main - with: - sketch-paths: | - - examples/GettingStarted - - examples/AcknowledgementPayloads - - examples/ManualAcknowledgements - - examples/StreamingData - - examples/MulticeiverDemo - - examples/InterruptConfigure - - examples/scanner - - examples/encodeRadioDetails - # The following examples still exist for posterity. They don't trigger this workflow - # - 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/TransferTimeouts - # - examples/old_backups/recipes/led_remote - # - examples/old_backups/recipes/nordic_fob - # - examples/old_backups/recipes/pingpair_maple - fqbn: ${{ matrix.fqbn }} - enable-deltas-report: ${{ matrix.enable-deltas-report }} - # install earlphilhower's arduino-pico platform index - platforms: | - - name: rp2040:rp2040 - source-url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json - - name: arduino:avr - - name: arduino:megaavr - - name: arduino:sam - - name: arduino:samd - - name: arduino:mbed - strategy: - fail-fast: false - matrix: - fqbn: - - "arduino:avr:yun" - - "arduino:avr:uno" - - "arduino:avr:diecimila" - - "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:mbed:nanorp2040connect" - - "rp2040:rp2040:rpipico" - - "rp2040:rp2040:rpipicow" - - "rp2040:rp2040:adafruit_feather" - - "arduino:samd:mkr1000" # 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 - - "arduino:sam:arduino_due_x_dbg" - # By default, don't generate size deltas data. - enable-deltas-report: - - false - # Generate size deltas data for this board - include: - - fqbn: arduino:avr:nano - enable-deltas-report: true - - fqbn: arduino:samd:mkrzero # InterruptConfigure.ino uses pin 2 - enable-deltas-report: true - - #### NOTE installing ATTinyCore has become too problematic for various reasons - #### I'll have to revisit this later when the Arduino CLI tool gets their act together - # attiny: - # uses: nRF24/.github/.github/workflows/build_arduino.yaml@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 }} - # enable-deltas-report: ${{ matrix.enable-deltas-report }} - # 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 - # # By default, don't generate size deltas data. - # enable-deltas-report: - # - false - # # Generate size deltas data for this board - # include: - # - fqbn: ATTinyCore:avr:attinyx5 - # enable-deltas-report: true - - # When using a matrix to compile for multiple boards, it's necessary to use a separate job for the deltas report - report: - needs: [build] # , attiny] - if: github.event_name == 'pull_request' - uses: nRF24/.github/.github/workflows/arduino_size_deltas.yaml@main +name: Arduino + +on: + pull_request: + branches: [master] + paths: + - ".github/workflows/build_arduino.yml" + - "examples/**" + - "!examples/old_backups/**" + - "RF24.*" + push: + branches: [master] + paths: + - ".github/workflows/build_arduino.yml" + - "examples/**" + - "!examples/old_backups/**" + +permissions: {} + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/master' }} + +jobs: + build: + uses: nRF24/.github/.github/workflows/build_arduino.yaml@main + with: + sketch-paths: | + - examples/GettingStarted + - examples/AcknowledgementPayloads + - examples/ManualAcknowledgements + - examples/StreamingData + - examples/MulticeiverDemo + - examples/InterruptConfigure + - examples/scanner + - examples/encodeRadioDetails + # The following examples still exist for posterity. They don't trigger this workflow + # - 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/TransferTimeouts + # - examples/old_backups/recipes/led_remote + # - examples/old_backups/recipes/nordic_fob + # - examples/old_backups/recipes/pingpair_maple + fqbn: ${{ matrix.fqbn }} + enable-deltas-report: ${{ matrix.enable-deltas-report }} + # install earlphilhower's arduino-pico platform index + platforms: | + - name: rp2040:rp2040 + source-url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json + - name: arduino:avr + - name: arduino:megaavr + - name: arduino:sam + - name: arduino:samd + - name: arduino:mbed + strategy: + fail-fast: false + matrix: + fqbn: + - "arduino:avr:yun" + - "arduino:avr:uno" + - "arduino:avr:diecimila" + - "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:mbed:nanorp2040connect" + - "rp2040:rp2040:rpipico" + - "rp2040:rp2040:rpipicow" + - "rp2040:rp2040:adafruit_feather" + - "arduino:samd:mkr1000" # 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 + - "arduino:sam:arduino_due_x_dbg" + # By default, don't generate size deltas data. + enable-deltas-report: + - false + # Generate size deltas data for this board + include: + - fqbn: arduino:avr:nano + enable-deltas-report: true + - fqbn: arduino:samd:mkrzero # InterruptConfigure.ino uses pin 2 + enable-deltas-report: true + + #### NOTE installing ATTinyCore has become too problematic for various reasons + #### I'll have to revisit this later when the Arduino CLI tool gets their act together + # attiny: + # uses: nRF24/.github/.github/workflows/build_arduino.yaml@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 }} + # enable-deltas-report: ${{ matrix.enable-deltas-report }} + # 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 + # # By default, don't generate size deltas data. + # enable-deltas-report: + # - false + # # Generate size deltas data for this board + # include: + # - fqbn: ATTinyCore:avr:attinyx5 + # enable-deltas-report: true + + # When using a matrix to compile for multiple boards, it's necessary to use a separate job for the deltas report + report: + needs: [build] # , attiny] + if: github.event_name == 'pull_request' + permissions: + # for posting/updating comments on PR threads + pull-requests: write + uses: nRF24/.github/.github/workflows/arduino_size_deltas.yaml@main diff --git a/.github/workflows/build_linux.yml b/.github/workflows/build_linux.yml index efb09999..271cdb3b 100644 --- a/.github/workflows/build_linux.yml +++ b/.github/workflows/build_linux.yml @@ -1,4 +1,4 @@ -name: Linux build +name: Linux on: pull_request: @@ -25,6 +25,7 @@ on: - ".github/workflows/build_linux.yml" push: branches: [master] + tags: ["*"] paths: - "*.h" - "*.cpp" @@ -45,22 +46,25 @@ on: - "pyRF24/setup.py" - "pyRF24/pyRF24.cpp" - ".github/workflows/build_linux.yml" - release: - types: [created] env: # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.) BUILD_TYPE: Release +permissions: {} + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/master' }} + jobs: ####################### using Makefile ############################# build: + name: using legacy makefiles runs-on: ubuntu-latest - strategy: fail-fast: false - matrix: config-options: - "--soc=BCM2835 --driver=RPi" @@ -72,6 +76,10 @@ jobs: # - "--soc=BCM2835 --driver=wiringPi" env: + # this env var is supported as of CMake v3.29+ + CMAKE_INSTALL_PREFIX: /usr/arm-linux-gnueabihf + # this env var is supported as of CMake v3.21+ + CMAKE_TOOLCHAIN_FILE: ${{ github.workspace }}/cmake/toolchains/armhf.cmake CFLAGS: "-I /usr/local/include" steps: @@ -80,7 +88,7 @@ jobs: persist-credentials: false - name: provide toolchain - run: | + 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 @@ -100,7 +108,7 @@ jobs: - name: provide pigpio if: ${{ matrix.config-options == '--driver=pigpio' }} - run: | + run: |- git clone https://github.com/joan2937/pigpio.git cd pigpio git fetch --tags @@ -108,8 +116,7 @@ jobs: git checkout $latestTag mkdir build cd build - cmake .. -D CMAKE_INSTALL_PREFIX=/usr/arm-linux-gnueabihf \ - -D CMAKE_TOOLCHAIN_FILE=${{ github.workspace }}/cmake/toolchains/armhf.cmake + cmake .. make sudo make install @@ -118,22 +125,22 @@ jobs: env: CC: /usr/bin/arm-linux-gnueabihf-gcc CXX: /usr/bin/arm-linux-gnueabihf-g++ - run: | + run: |- git clone https://github.com/intel-iot-devkit/mraa.git cd mraa mkdir build cd build cmake .. \ -D BUILDSWIGNODE=OFF \ - -D BUILDARCH=arm \ - -D CMAKE_INSTALL_PREFIX=/usr/arm-linux-gnueabihf \ - -D CMAKE_TOOLCHAIN_FILE=${{ github.workspace }}/cmake/toolchains/armhf.cmake + -D BUILDARCH=arm sudo make install sudo bash -c 'echo "/usr/local/lib/arm-linux-gnueabihf" >> /etc/ld.so.conf' sudo ldconfig - name: library configure - run: ./configure ${{ matrix.config-options }} + env: + CONFIG_OPTIONS: ${{ matrix.config-options }} + run: ./configure ${CONFIG_OPTIONS} - name: library make run: make @@ -142,14 +149,15 @@ jobs: run: sudo make install - name: make linux examples - run: | + run: |- cd examples_linux make file ./gettingstarted ####################### using CMake ################################ - using_cmake: + build-cmake: + name: using CMake uses: nRF24/.github/.github/workflows/build_linux_cmake.yaml@main with: rf24-ref: ${{ github.sha }} @@ -157,7 +165,6 @@ jobs: compiler: ${{ matrix.toolchain.compiler }} usr-dir: ${{ matrix.toolchain.usr_dir }} examples-path: examples_linux - deploy-release: ${{ github.event_name == 'release' && (matrix.toolchain.compiler == 'armhf' || matrix.toolchain.compiler == 'arm64') && (matrix.driver =='RPi' || matrix.driver =='SPIDEV') }} py-wrapper-path: pyRF24 strategy: fail-fast: false @@ -195,3 +202,13 @@ jobs: toolchain: compiler: "default" # github runner is hosted on a "amd64" usr_dir: "local" + + deploy: + name: deploy release assets + needs: [build-cmake] + permissions: + # needed for uploading release assets + contents: write + if: startsWith(github.ref, 'refs/tags/') + uses: nRF24/.github/.github/workflows/deploy_cpack_artifacts.yaml@main + secrets: inherit diff --git a/.github/workflows/build_platformIO.yml b/.github/workflows/build_platformIO.yml index 39a45955..e56a549e 100644 --- a/.github/workflows/build_platformIO.yml +++ b/.github/workflows/build_platformIO.yml @@ -1,4 +1,4 @@ -name: PlatformIO build +name: PlatformIO on: pull_request: @@ -17,15 +17,18 @@ on: - "examples/**" - "!examples/old_backups/**" - "!examples/rf24_ATTiny/**" - release: - types: [created] + tags: ["*"] + +permissions: {} + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/master' }} jobs: validate_lib_json: - uses: nRF24/.github/.github/workflows/validate_deploy_platformio.yaml@main - secrets: inherit - with: - deploy-release: ${{ github.event_name == 'release' }} + name: validate library.json + uses: nRF24/.github/.github/workflows/vaildate_platformio.yaml@main build: needs: [validate_lib_json] @@ -55,3 +58,13 @@ jobs: - "blackpill_f103c8" - "nodemcuv2" - "adafruit_qtpy_esp32s2" + + deploy: + name: deploy release asset + if: startsWith(github.ref, 'refs/tags/') + needs: [validate_lib_json, build] + permissions: + # needed for uploading release assets + contents: write + uses: nRF24/.github/.github/workflows/deploy_platformio_artifact.yaml@main + secrets: inherit diff --git a/.github/workflows/build_rp2xxx.yml b/.github/workflows/build_rp2xxx.yml index d7b75eeb..ef63099d 100644 --- a/.github/workflows/build_rp2xxx.yml +++ b/.github/workflows/build_rp2xxx.yml @@ -1,4 +1,4 @@ -name: Pico SDK build +name: Pico SDK on: push: @@ -24,6 +24,12 @@ on: - "utility/rp2/*" - "examples_pico/*" +permissions: {} + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/master' }} + jobs: build: uses: nRF24/.github/.github/workflows/build_pico_sdk.yaml@main diff --git a/.github/workflows/clang_format.yml b/.github/workflows/clang_format.yml index 79d1ea39..d58dceec 100644 --- a/.github/workflows/clang_format.yml +++ b/.github/workflows/clang_format.yml @@ -1,14 +1,25 @@ -name: check code formatting +name: Code format on: - push: - branches: [master] - pull_request: - branches: [master] + push: + branches: [master] + pull_request: + branches: [master] + +permissions: {} + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/master' }} jobs: - check_formatting: - uses: nRF24/.github/.github/workflows/cpp_lint.yaml@main - with: - ignore: examples/old_backups|utility/RPi/bcm2835.h|utility/RPi/bcm2835.c - extensions: ino,c,cpp,h + check: + permissions: + # needed to post review suggestions on a PR + pull-requests: write + # needed to detect changed files + contents: read + uses: nRF24/.github/.github/workflows/cpp_lint.yaml@main + with: + ignore: examples/old_backups|utility/RPi/bcm2835.h|utility/RPi/bcm2835.c + extensions: ino,c,cpp,h diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index fb0b0cad..a4f9b84e 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -1,56 +1,71 @@ -name: build Docs - -on: - pull_request: - branches: [master] - paths: - - "*.h" - - "docs/**" - - "!docs/README.md" - - "*.md" - - "utility/template/*.h" - - "examples**.cpp" - - "examples**.ino" - - "images/**" - - "datasheets/**" - - ".github/workflows/doxygen.yml" - - "Doxyfile" - - "library.properties" # get lib version from here - push: - branches: [master] - paths: - - "*.h" - - "docs/**" - - "!docs/README.md" - - "*.md" - - "utility/template/*.h" - - "examples**.cpp" - - "examples**.ino" - - "images/**" - - "datasheets/**" - - ".github/workflows/doxygen.yml" - - "Doxyfile" - - "library.properties" # get lib version from here - release: - types: [published, edited] - workflow_dispatch: - -jobs: - check-spelling: - runs-on: ubuntu-latest - steps: - - uses: actions/setup-node@v6 - with: - node-version: 24.x - - uses: actions/checkout@v6 - with: - persist-credentials: false - - name: Install cSpell - run: npm install -g cspell - - run: npx cspell --gitignore --config cspell.config.yaml . - build-docs: - uses: nRF24/.github/.github/workflows/build_docs.yaml@main - with: - deploy-gh-pages: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') }} - doxygen-version: '1.13.2' - secrets: inherit +name: Docs + +on: + pull_request: + branches: [master] + paths: + - "*.h" + - "docs/**" + - "!docs/README.md" + - "*.md" + - "utility/template/*.h" + - "examples**.cpp" + - "examples**.ino" + - "images/**" + - "datasheets/**" + - ".github/workflows/doxygen.yml" + - "Doxyfile" + - "library.properties" # get lib version from here + push: + branches: [master] + paths: + - "*.h" + - "docs/**" + - "!docs/README.md" + - "*.md" + - "utility/template/*.h" + - "examples**.cpp" + - "examples**.ino" + - "images/**" + - "datasheets/**" + - ".github/workflows/doxygen.yml" + - "Doxyfile" + - "library.properties" # get lib version from here + tags: ["*"] + workflow_dispatch: + +permissions: {} + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/master' }} + +jobs: + check-spelling: + runs-on: ubuntu-latest + steps: + - uses: actions/setup-node@v6 + with: + node-version: 24.x + - uses: actions/checkout@v6 + with: + persist-credentials: false + - name: Install cSpell + run: npm install -g cspell + - run: npx cspell --gitignore --config cspell.config.yaml . + + build: + uses: nRF24/.github/.github/workflows/build_docs.yaml@main + with: + doxygen-version: '1.15.0' + + deploy: + needs: [build] + if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/') + permissions: + # to authenticate the gh-pages environment + id-token: write + # to upload to GitHub Pages + pages: write + uses: nRF24/.github/.github/workflows/deploy_docs.yaml@main + secrets: inherit diff --git a/.readthedocs.yaml b/.readthedocs.yaml index db230524..6935517f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,20 +6,19 @@ version: 2 build: - os: "ubuntu-22.04" - apt_packages: - - libclang1-12 - - libclang-cpp12 + os: "ubuntu-24.04" + # apt_packages: + # - libclang1-12 + # - libclang-cpp12 tools: python: "3" commands: # Install doxygen from source distributions (conda forge does not keep up-to-date doxygen releases) - > - DOXYGEN_VERSION="1.13.2" && + DOXYGEN_VERSION="1.15.0" && + RELEASE_TITLE=$(echo ${DOXYGEN_VERSION} | tr '.' '_') && mkdir .doxygen && cd .doxygen && - echo $(pwd) && - echo "https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz" && - curl -L https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz > doxygen.tar.gz && + curl -L "https://github.com/doxygen/doxygen/releases/download/Release_${RELEASE_TITLE}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz" --output doxygen.tar.gz && gunzip doxygen.tar.gz && tar xf doxygen.tar && mv doxygen-$DOXYGEN_VERSION/bin/doxygen ./ diff --git a/COMMON_ISSUES.md b/COMMON_ISSUES.md index 753f052e..3a7c089e 100644 --- a/COMMON_ISSUES.md +++ b/COMMON_ISSUES.md @@ -14,32 +14,31 @@ successfully with each other. Verify pin connections and wiring. 2. If `radio.begin()` returns true, but the devices are not communicating, users can uncomment the lines `printf_begin()` & `radio.printDetails()` and view the settings. They should appear as the following: - - ``` - SPI Speedz = 10 Mhz - STATUS = 0x0e RX_DR=0 TX_DS=0 MAX_RT=0 RX_P_NO=7 TX_FULL=0 - RX_ADDR_P0-1 = 0x65646f4e31 0x65646f4e32 - RX_ADDR_P2-5 = 0x33 0xce 0x3e 0xe3 - TX_ADDR = 0x65646f4e31 - RX_PW_P0-6 = 0x04 0x04 0x04 0x04 0x04 0x04 - EN_AA = 0x3f - EN_RXADDR = 0x02 - RF_CH = 0x4c - RF_SETUP = 0x03 - CONFIG = 0x0f - DYNPD/FEATURE = 0x00 0x00 - Data Rate = 1 MBPS - Model = nRF24L01+ - CRC Length = 16 bits - PA Power = PA_LOW - ARC = 0 + + ```text + SPI Speedz = 10 Mhz + STATUS = 0x0e RX_DR=0 TX_DS=0 MAX_RT=0 RX_P_NO=7 TX_FULL=0 + RX_ADDR_P0-1 = 0x65646f4e31 0x65646f4e32 + RX_ADDR_P2-5 = 0x33 0xce 0x3e 0xe3 + TX_ADDR = 0x65646f4e31 + RX_PW_P0-6 = 0x04 0x04 0x04 0x04 0x04 0x04 + EN_AA = 0x3f + EN_RXADDR = 0x02 + RF_CH = 0x4c + RF_SETUP = 0x03 + CONFIG = 0x0f + DYNPD/FEATURE = 0x00 0x00 + Data Rate = 1 MBPS + Model = nRF24L01+ + CRC Length = 16 bits + PA Power = PA_LOW + ARC = 0 ``` If the settings do not appear as above, troubleshoot wiring, pin connections, etc. - -3. If both of the above check out, the problem is likely the CE pin is wired wrong, or + +3. If both of the above check out, the problem is likely the CE pin is wired wrong, or even hardware issues (bad radios etc.) See the following. - ## Settings that must match @@ -86,19 +85,19 @@ More info about why you can't call `millis()` (or `delay()`) from an ISR callbac ## Which write*() function do I use? -**Standard:** +### Standard `RF24::write()`: The standard write function, this is the most commonly used way to send data over radio link. This function will block until data is sent successfully. This means that if Auto-Ack is enabled, the radio will write the packet and wait for a response from the receiving radio. If Auto-Ack is disabled, the function will return sooner, as it will not wait for a response from the receiving radio. `RF24::startWrite()`: Can be used similar to the standard `RF24::write()` function, but it will not block. Useful for writing data outside of an interrupt routine, triggering that interrupt. Contains a `delayMicroseconds()` call for faster MCUs/devices to ensure the CE pin is toggled for a full 10us. -**Advanced: (requires calling txStandBy())** +### Advanced: (requires calling `RF24::txStandBy()`) `RF24::writeFast()`: Used for high-speed streaming of data. This function can be used to transmit data by simply placing data in the 3-layer FIFO buffers if room is available, or blocking until available. The function will return after a packet is placed in the buffer, or when a packet fails to transmit, in which case the buffers are cleared. `RF24::writeBlocking()`: Not commonly used, this function will first check the 3-layer FIFO for available space, then block until a timeout period is met if packets are failing, or return once there is room in the FIFO buffer and a packet is placed there. -Interrupt Safe Functions: +### Interrupt Safe Functions `RF24::startFastWrite()`: Can be used to write data and return immediately, without going into standBy mode. Can be used to transmit data at high speeds using interrupts, but will easily overflow the FIFO buffer if attempting to send data faster than the radio will process it. @@ -164,9 +163,10 @@ You may find variants of the nRF24L01 transceiver that are marketed as “nRF24L 2. Needs shielding from electromagnetic interference. Shielding usually works best when it has a path to ground (GND pin), but this connection to the GND pin is not required. It is important that the shielding does not touch any current carrying parts. - Professionals tend to use a faraday cage/mesh to implement electromagnetic shielding, but it can be pricey for this scenario. - - A quick do-it-yourself solution (as proof-of-concept) would be to wrap the PA/LNA module with electrical tape and then wrap foil around the electrical tape (for shielding) while being very careful to not let the foil touch any current carrying parts (like the GPIO pins, the antenna mount, and the soldier joints for the antenna mount). Observe - [![ghetto_shielding_1.png](https://github.com/nRF24/RF24/blob/master/images/ghetto_sheilding_1.png)](https://github.com/nRF24/RF24/blob/master/images/ghetto_sheilding_1.png) - [![ghetto_shielding_2.png](https://github.com/nRF24/RF24/blob/master/images/ghetto_sheilding_2.png)](https://github.com/nRF24/RF24/blob/master/images/ghetto_sheilding_2.png) + - A quick do-it-yourself solution (as proof-of-concept) would be to wrap the PA/LNA module with electrical tape and then wrap foil around the electrical tape (for shielding) while being very careful to not let the foil touch any current carrying parts (like the GPIO pins, the antenna mount, and the soldier joints for the antenna mount). + + Observe: + ![ghetto_shielding_1.png](images/ghetto_sheilding_1.png){width=30%} ![ghetto_shielding_2.png](images/ghetto_sheilding_2.png){width=30%} ### My PA/LNA module doesn't perform as well as I'd hoped or the NRF radio works better on touching it diff --git a/docs/main_page.md b/docs/main_page.md index f1f44b83..65395490 100644 --- a/docs/main_page.md +++ b/docs/main_page.md @@ -69,7 +69,7 @@ changes. Observe -![@image HTML pinout.jpg](https://github.com/nRF24/RF24/raw/master/images/pinout.jpg) +![pinout.jpg](images/pinout.jpg) The table below shows how to connect the the pins of the NRF24L01(+) to different boards. CE and CSN are configurable.