write, writeFast and writeBlocking methods confusions

[flexphperia]

I am trying to understand the write, writeFastand writeBlockingmethods but I need some answers:

1. writeFastand writeBlocking methods have in the code:

while ((get_status () & (_BV (TX_FULL)))) {

So their main operation takes place when the TX FIFO is full (it has 3 payloads in queue). But I can use writeFast function like this and it works:

radio.writeFast(&buf, sizeof (buf));
radio.txStandBy(1000);

I don't call writeFast 3 times and it works.
Although there is an example that calls it 3 times in the documentation for the txStandby function:

radio.writeFast(&buf, 32);
radio.writeFast(&buf, 32);
radio.writeFast(&buf, 32); // Fills the FIFO buffers up
bool ok = radio.txStandBy(1000); // Returns 0 if failed after 1 second of retries. 1 if success.

2. Why do I have to call the txStandBy method after calling writeBlocking - after all writeBlocking method itself has a timeout?

radio.writeBlocking(&buf, sizeof(buf), 1000); // Wait up to 1 second to write 1 payload to the buffers
radio.txStandBy(1000); // Wait up to 1 second for the payload to send. Return 1 if ok, 0 if failed.

Maybe someone could explain more precisely what these 3 methods differ and when to use them: write, writeFast, wirteBlocking?

[TMRh20]

The main difference between the normal write() and the writeFast() and writeBlocking() functions is the latter 2 are used for streaming/demanding applications where large volumes of data are sent at once.

The normal write will block until a payload is sent and an ack is received, (when auto-ack is enabled) then go back to standby mode. The writeFast() and writeBlocking() put data into the radio TX FIFO buffer immediately, unless it is full, then it blocks. writeBlocking() is probably only used in a very limited number of applications where data is re-sent until it gets through, but writeFast() is recommended for use in streaming audio or real-time data at high speeds.

This can be demonstrated by using the startWrite() function to send data at maximum speed. You will see the FIFO buffers get overflowed quite easily and many payloads are lost. This compared to the other mentioned functions, which can block appropriately and prevent FIFO overruns.

The txStandby() function is just used to set the radio out of active-tx mode and back to tx-standby mode. It can also tell you if the sending of all the data was successful.

Hope that makes sense...

[2bndy5]

Since TMRh20 discussed the applicable differences, I'll just focus on the questions posed.

1. Think of the

   while ((get_status () & (_BV (TX_FULL))))
   

   as a condition that would only be satisfied when the TX FIFO is full. If the condition isn't met, then the functions simply load the payload into the TX FIFO.
   • Both writeFast() and writeBlocking() return a boolean describing only if the payload was/wasn't loaded into the TX FIFO. Conversely, write() will return a boolean describing if the singular payload passed to it was sent successfully or not.
   • writeBlocking() will attempt to re-transmit a failed payload but writeFast() will not.
   • both functions use a timeout value to wait while the TX FIFO is full, but only writeBlocking() let's you customize this timeout value (which defaults to the minimum 95 milliseconds).
2. Since writeFast() and writeBlocking() functions' return value only describe if the payload was loaded into the TX FIFO or not, then the txStandby() function can be used to determine if there was a failure to send 1 of the payloads or if all payloads in the TX FIFO were sent successfully. As noted above, the timeout value in writeBlocking() is only applied when the TX FIFO is full. The timeout value for txStandby() is applied when waiting for the TX FIFO to become empty.
   • If no timeout is specified when calling txStandby(), then no re-attempts to send a failed transmission are made.
   • If txStandby() is passed a timeout value, then a failed transmission is retried while waiting for TX FIFO to become empty.
   • Either way, txStandby() will flush the TX FIFO before exiting. Similarly, write() will also flush the TX FIFO when the specified payload fails to transmit.

[2bndy5]

@flexphperia I'll be closing this issue if there is no more activity over the next month. If you would like to add clarity to the docs, we would welcome a PR that might better explain the differences from a user's perspective. It is a common problem when writing docs that they can inadvertently assume too much of the user's understanding.

[flexphperia]

Yes, this information was helpful. My understanding of these methods was not good. Unfortunately, I will not help with PR, but you may want to add a link to this thread in the documentation.