Skip to content

Commit

Permalink
new examples and more (#691)
Browse files Browse the repository at this point in the history
* don't hide EN_ACK_PAY reqs; adjust examples & docs

* removed duplicated calls in examples/tests

* too many examples

* update docs about reUseTx()

* deprecate enableDynamicAck()

* clarify reUseTx()

* typo in func ref

* append setAutoAck() about pipe 0

* consistent casing in "auto-ack"

* fix typo

* revert this "see also" changes

* use ack_payloads_enabled to full potential

* undeprecate flush_rx()

* isPVariant return internal var; default dyn_pl on

addresses the following issues:
- #401
- #641
- #660

* oops, readdress #401 #641 #660

* address #640

* deprecate isAckPayloadAvailable() #664

* try to ignore return value; trigger forked actions

attempting to address #636

* this is why I can't have nice things

* retrying to ignore return value; fix init order

* add CI for avr compiling examples

* build doxygen with latest release ver number

* revert doxyfile, fix doxygen.yml, make2 = install

* build examples changes, doxygen.yml bad indent

* remove unnecessary pipe chars in doxygen.yml

* linux CI changed, pde->ino files

* platform specific examples; fix WiringPi build

* fix using void return value

* remove gemma & lilypad; fix certain example vars

* wiringPi may be broken #669

* 8 paragraphs that say keep auto-ack enabled

#667

* reverted examples folders; exclude maple & 3pin

* exclude didn't work

* trigger arduino build on workflow changes

* explicit examples' paths

* no wildcards in explicit paths

* no quotes in yaml sequence

* try using a pipe char

* arduino build "needs" A-style check

* applied arduino IDE's auto formatting

* remove format checker

* fine let the example terminate

* all official arduino cores to build_arduino.yml

* backup examples; new GettingStarted

* no explicit examples; compile all

* new InterruptConfigure example

* // about when IRQ flags get cleared; & a fix typo

* new StreamingData & MulticeiverDemo examples

* reduce streamData compilation size

* tested GetStarted, AckPayloads, Streaming

* IRQ & Multicceiver examples tested

* undo #646; add broken FakeBLE example

* fix arduino build CI

* forgot to use pipe char

* typo

* 2nd job should run on ubuntu-latest

* fqbn arch-type is wrong?!

* uncomment #define IRQ_PIN from testing artifacts

* use SpenceKonde core released zip file

* use SpenceKonde board definitions

* use correct vendor name?!

* use lower case?!

* platform name should match the fqbn

* what am I doing wrong? use SpenceKonde attiny core

* under "platforms" not "with"

* yml formatted "platforms" options

* "with: platforms:"

* source-path uses relative path

* use trailing / in source-path

* clear advice from per1234 about yml syntax

* fixing source-path and version number

* use direct download link to SpenceKonde release

* adjust source-path again

* no source-path

* redo-ing #646

* timingSearch3pin includes stdio

* don't ignore rf24_ATTiny examples

* separate job for separate ATTiny examples

* timingSearch3pin uses redefined spi funcs

* drop testing on attiny43, install core from json

* keywords updated removed duplicate examples

* CallResponse was duplicate; (+) ManualAck example

* doc updates #671 tested new manAck example

* FakeBLE crc calc not checking out

* add per1234's action to check formatting

* did not find expected alphanumeric char?!

* add manualAcknowledgements example to docs

* don't remove comment block prefix

* restored comment prefix in old examples also

* less confusing comments about addresses

* clarify docs on return value for all write-related

* remove broken fakeBLE example

* forgot to remove fakeBLE from arduino workflow

* test deploy to gh-pages

* bad yml format

* something's wrong with the doxygen build CI

* lack of new line in end of  doxyfile

* remove debug prompt; deploy on publish released

* deploy on any release event

* fix main page useful links

* only clear RX_DR flag in read()

* typo

* doc updates; new python examples

* new gettingstarted example for linux

* add micros() to applicable utilities compatiblity

* define micros() in arch_config.h

* printDetails() in linux

* pipe number not printing correctly

* oops it was a non-printable char

* avoid keyboard interrupt

* build wiringPi examples also

* linux build CI for SPIDEV

* ignore return value in utilty/SPIDEV/interrupt.c

* trying rf24_micros()

* ammend example to use rf24_micros()

* let micros() be defined in examples for linux

* need cstdio

* ported arduino examples to linux (& python)

* oops

* should probably declare i huh

* copy n paste much?

* don't use stoi for a char

* typo, expose digitalRead(), ifdef RF24_WIRINGPI

* ifdef WIRINGPI didn't help, fix inline condition

* testing round 1; fix pyRf24/setup.py

* bug fixes in py examples prompt fixes in linux

* fix irqConf for arduino, rename stream_data.py

* copy n paste artifact

* debugging streamingData

* testing round 2

* oops

* timing output changes; printDetails() also

* debugging IRQ configure example

* debugging IRQ_config.py also

* declare timer stuff for micros in manACK example

* typo

* doc read() for python; add flush_rx() to py wrap

* remove cap on how many bytes to read in python!!!

* don't cap bytes read() from RX FIFO in C++

* supposed to be decode() not encode()

* fix typos; better python doc about read()

* py wrapper omits len args for buf-related funcs

* fix streaming_data.py master()

* duplicate prompt in ackPay.py

* prompt format changes

* big commit

- reverted defaults about Dynamic Payloads and Dynamic ACKs per @TMRh20 suggestions about Si24R1 in #658. This reverts #660 & #661
- ammended docs & all examples about above suggestions
- re-wrote InterruptConfigure examples to use attachInterrupt(); py example uses RPi.GPIO equivalant.
- removed MKR-based boards from Arduino build CI as pin 2 on those boards don't support interrupt requests, and InterruptConfigure.ino uses pin 2 for exactly that.
- added building of python wrapper to Linux workflow; it now also runs pylint on python examples
- removed my attempt to port digitalRead() to various Linux drivers as it is no longer needed in the interruptConfigure.cpp example.
- addressed #674 about RX_PW_Px registers manipulation.
- remove and ignore my VSCode folder as it is machine-specific
- removed contradicting "examples_linux" ignores and added "examples_linux/__pycache__"  folder
- RF24::begin() now brute forces a soft reset. It does not reset addresses set to the pipes, but it does close all pipes. This helps address #401
- fixed some typos/copy-n-paste issues in the docs.
- added instructions on how to run the python example scripts

* Linux build CI use pip3 to install RPi.GPIO

* workflow uses python 3.7 x86

* workflow uses python 3.x x86

* python needs x32 called in workflow

* fix address assignment in linux examples

* don't check python examples in workflow

* define INPUT in RPi-BCM driver

* remove GPIO.cleanup() from py examples

* payloadSize is an attribute in python

* fix python examples about getPLsize()

* use RuntimeError in python examples when begin() is false

* testing round 3

* streamData uses write(); python examples need 3.7+

* fix ellapsedTime in streamingData

* status byte saved as private member

addresses #678 #679 #677

removed comments in build_linux.yml about building/testing the python wrapper

added a fail fast prompt to the streaming examples when failures >= 100

* simplify logic about _is_p_variant

* testing round 4 & address #680

* fix irq examples

* fix compilation errors for IRQ examples

* fix irq example for linux

* tweak IRQ py example; writeAckPayload returns bool

* final tweaks to IRQ examples; some doc updates

* leave closeReadingPipe(0) in startListening()

* arduino examples work

address 2 new issues
1. #687 added printPrettyDetails(); updated python wrapper and keywords.txt
2. #686 centralizing all SPI access to write_*() and read_*() functions

Also reverted changes to gitignore about examples_linux folder while adding/ignoring some things about building the python wrapper (venv, *.pyc, __pycache__)

* remove volatile from radio declaration

* datasheets; fix man_ack.py example

updated comment proceeding radio object in python examples

documented enums and linked references to them. Also linked references in COMMON_ISSUES.md & main page's changelog.

* ATTiny examples should work on SpenceKonde core

* exclude ATTinyx313 from timingSearch3pin example

* oops, bad indent

* Astyle indent for #ifdef is 0

* (+) CLI args to examples. pwr down radio on ctrl+c

* fail if no valid arg is specified

* fix parsing args in python examples

* make py examples behave like c++ examples

* found a bug in py examples' -r arg

* testing round 5

* adjust manpage descriptions

* don't use signal.h in cpp examples

* del cli args from all linux examples except 2

* edit doxyfile OUTPUT_DIR

* only run doxygen on master branch

* redirect doc links to nRF24 org

* missed a link

* remove use of timeout bool in manAck.ino

* self-reviewed PR changes

* ATTinyCore adjustments

- use macros from SpenceKonde ATTinyCore
- add macros for CSN settling times for when using the ATTinyCore

* some more self-reviewed PR changes

* exclude root README from doxygen output

* exclude GPIO & SPI classes from doc'd classes

* add Arduino & Linux build badges to readme

* Change link to docs in readme
  • Loading branch information
2bndy5 authored Dec 14, 2020
1 parent c7cfbea commit d69f751
Show file tree
Hide file tree
Showing 104 changed files with 9,119 additions and 7,196 deletions.
157 changes: 157 additions & 0 deletions .github/workflows/build_arduino.yml
Original file line number Diff line number Diff line change
@@ -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 }}
77 changes: 30 additions & 47 deletions .github/workflows/build_linux.yml
Original file line number Diff line number Diff line change
@@ -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
46 changes: 46 additions & 0 deletions .github/workflows/doxygen.yml
Original file line number Diff line number Diff line change
@@ -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
13 changes: 11 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
50 changes: 45 additions & 5 deletions COMMON_ISSUES.md
Original file line number Diff line number Diff line change
@@ -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).
6 changes: 4 additions & 2 deletions Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -2582,3 +2583,4 @@ GENERATE_LEGEND = YES
# This tag requires that the tag HAVE_DOT is set to YES.

DOT_CLEANUP = YES

Loading

0 comments on commit d69f751

Please sign in to comment.