Skip to content

Commit

Permalink
Update COMMON_ISSUES re: write() function (#947)
Browse files Browse the repository at this point in the history
* Update COMMON_ISSUES re: write() functions

- Update comment regarding troubleshooting and CE Pin
- Add info on the different write() functions

#816 #877

* Formatting & IRQ info
  • Loading branch information
TMRh20 committed Feb 24, 2024
1 parent fe25130 commit 881473a
Showing 1 changed file with 21 additions and 1 deletion.
22 changes: 21 additions & 1 deletion COMMON_ISSUES.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ users can uncomment the lines `printf_begin()` & `radio.printDetails()` and
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 in software 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.


Expand Down Expand Up @@ -84,6 +84,26 @@ Because the RF24 library uses `millis()` to implement a timeout and `delay()` fo

More info about why you can't call `millis()` (or `delay()`) from an ISR callback function is available at [the Arduino docs](https://www.google.com/url?sa=t&source=web&rct=j&url=https://www.arduino.cc/reference/en/language/functions/external-interrupts/attachinterrupt/&ved=2ahUKEwjMhtSRl5jzAhVUsp4KHWIPCrIQFnoECAoQAQ&usg=AOvVaw1X9H0058Nz7Hck91VIC3bD).

## Which write*() function do I use?

**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())**

`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:

`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.

Again, some of the other functions can technically be placed inside interrupt routines, but rely on millis() for timeouts etc. and this functionality will not typically work within an interrupt routine. Advanced users can comment out `FAILURE_HANDLING` in `RF24_config.h` to disable some of this functionality on non-linux devices to make functions like `RF24::txStandBy()` interrupt-safe.

## Here are the most common issues and their solutions

### write() always returns true after setAutoAck(false)
Expand Down

0 comments on commit 881473a

Please sign in to comment.