Skip to content

Commit 0bd92d5

Browse files
2bndy52bndy5
authored
add: expose status byte in public API (#1032)
Offers intuitive alternatives to `maskIRQ()` and `whatHappened()`. The API is more explicit, but there's less bit-banging and memory allocation involved. The StatusFlags API is implemented in the python wrapper also. All new API is grouped in the docs under the topic "Status flags". Also modified streamingData and IRQconfig examples accordingly. Add migration guide about deprecated API
1 parent 6210312 commit 0bd92d5

File tree

13 files changed

+609
-205
lines changed

13 files changed

+609
-205
lines changed

‎RF24.cpp‎

Lines changed: 63 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -482,21 +482,17 @@ uint8_t RF24::flush_tx(void)
482482
return status;
483483
}
484484

485-
/****************************************************************************/
486-
487-
uint8_t RF24::get_status(void)
488-
{
489-
read_register(RF24_NOP, (uint8_t*)nullptr, 0);
490-
return status;
491-
}
492-
493485
/****************************************************************************/
494486
#if !defined(MINIMAL)
495487

496-
void RF24::print_status(uint8_t _status)
488+
void RF24::printStatus(uint8_t flags)
497489
{
498-
printf_P(PSTR("STATUS\t\t= 0x%02x RX_DR=%x TX_DS=%x MAX_RT=%x RX_P_NO=%x TX_FULL=%x\r\n"), _status, (_status & _BV(RX_DR)) ? 1 : 0,
499-
(_status & _BV(TX_DS)) ? 1 : 0, (_status & _BV(MAX_RT)) ? 1 : 0, ((_status >> RX_P_NO) & 0x07), (_status & _BV(TX_FULL)) ? 1 : 0);
490+
printf_P(PSTR("RX_DR=%x TX_DS=%x TX_DF=%x RX_PIPE=%x TX_FULL=%x\r\n"),
491+
(flags & RF24_RX_DR) ? 1 : 0,
492+
(flags & RF24_TX_DS) ? 1 : 0,
493+
(flags & RF24_TX_DF) ? 1 : 0,
494+
(flags >> RX_P_NO) & 0x07,
495+
(flags & _BV(TX_FULL)) ? 1 : 0);
500496
}
501497

502498
/****************************************************************************/
@@ -710,7 +706,9 @@ void RF24::printDetails(void)
710706
printf("================ NRF Configuration ================\n");
711707
#endif // defined(RF24_LINUX)
712708

713-
print_status(get_status());
709+
uint8_t status = update();
710+
printf_P(PSTR("STATUS\t\t= 0x%02x "), status);
711+
printStatus(status);
714712

715713
print_address_register(PSTR("RX_ADDR_P0-1"), RX_ADDR_P0, 2);
716714
print_byte_register(PSTR("RX_ADDR_P2-5"), RX_ADDR_P2, 4);
@@ -1106,7 +1104,7 @@ bool RF24::_init_radio()
11061104

11071105
// Reset current status
11081106
// Notice reset and flush is the last thing we do
1109-
write_register(NRF_STATUS, _BV(RX_DR) | _BV(TX_DS) | _BV(MAX_RT));
1107+
write_register(NRF_STATUS, RF24_IRQ_ALL);
11101108

11111109
// Flush buffers
11121110
flush_rx();
@@ -1151,7 +1149,7 @@ void RF24::startListening(void)
11511149
#endif
11521150
config_reg |= _BV(PRIM_RX);
11531151
write_register(NRF_CONFIG, config_reg);
1154-
write_register(NRF_STATUS, _BV(RX_DR) | _BV(TX_DS) | _BV(MAX_RT));
1152+
write_register(NRF_STATUS, RF24_IRQ_ALL);
11551153
ce(HIGH);
11561154

11571155
// Restore the pipe0 address, if exists
@@ -1247,7 +1245,7 @@ bool RF24::write(const void* buf, uint8_t len, const bool multicast)
12471245
uint32_t timer = millis();
12481246
#endif // defined(FAILURE_HANDLING) || defined(RF24_LINUX)
12491247

1250-
while (!(get_status() & (_BV(TX_DS) | _BV(MAX_RT)))) {
1248+
while (!(update() & (RF24_TX_DS | RF24_TX_DF))) {
12511249
#if defined(FAILURE_HANDLING) || defined(RF24_LINUX)
12521250
if (millis() - timer > 95) {
12531251
errNotify();
@@ -1262,10 +1260,10 @@ bool RF24::write(const void* buf, uint8_t len, const bool multicast)
12621260

12631261
ce(LOW);
12641262

1265-
write_register(NRF_STATUS, _BV(RX_DR) | _BV(TX_DS) | _BV(MAX_RT));
1263+
write_register(NRF_STATUS, RF24_IRQ_ALL);
12661264

12671265
//Max retries exceeded
1268-
if (status & _BV(MAX_RT)) {
1266+
if (status & RF24_TX_DF) {
12691267
flush_tx(); // Only going to be 1 packet in the FIFO at a time using this method, so just flush
12701268
return 0;
12711269
}
@@ -1290,10 +1288,10 @@ bool RF24::writeBlocking(const void* buf, uint8_t len, uint32_t timeout)
12901288

12911289
uint32_t timer = millis(); // Get the time that the payload transmission started
12921290

1293-
while ((get_status() & (_BV(TX_FULL)))) { // Blocking only if FIFO is full. This will loop and block until TX is successful or timeout
1291+
while (update() & _BV(TX_FULL)) { // Blocking only if FIFO is full. This will loop and block until TX is successful or timeout
12941292

1295-
if (status & _BV(MAX_RT)) { // If MAX Retries have been reached
1296-
reUseTX(); // Set re-transmit and clear the MAX_RT interrupt flag
1293+
if (status & RF24_TX_DF) { // If MAX Retries have been reached
1294+
reUseTX(); // Set re-transmit and clear the MAX_RT interrupt flag
12971295
if (millis() - timer > timeout) {
12981296
return 0; // If this payload has exceeded the user-defined timeout, exit and return 0
12991297
}
@@ -1319,7 +1317,7 @@ bool RF24::writeBlocking(const void* buf, uint8_t len, uint32_t timeout)
13191317
void RF24::reUseTX()
13201318
{
13211319
ce(LOW);
1322-
write_register(NRF_STATUS, _BV(MAX_RT)); //Clear max retry flag
1320+
write_register(NRF_STATUS, RF24_TX_DF); //Clear max retry flag
13231321
read_register(REUSE_TX_PL, (uint8_t*)nullptr, 0);
13241322
IF_RF24_DEBUG(printf_P("[Reusing payload in TX FIFO]"););
13251323
ce(HIGH); //Re-Transfer packet
@@ -1339,8 +1337,8 @@ bool RF24::writeFast(const void* buf, uint8_t len, const bool multicast)
13391337
#endif
13401338

13411339
//Blocking only if FIFO is full. This will loop and block until TX is successful or fail
1342-
while ((get_status() & (_BV(TX_FULL)))) {
1343-
if (status & _BV(MAX_RT)) {
1340+
while (update() & _BV(TX_FULL)) {
1341+
if (status & RF24_TX_DF) {
13441342
return 0; //Return 0. The previous payload has not been retransmitted
13451343
// From the user perspective, if you get a 0, call txStandBy()
13461344
}
@@ -1432,8 +1430,8 @@ bool RF24::txStandBy()
14321430
uint32_t timeout = millis();
14331431
#endif
14341432
while (!(read_register(FIFO_STATUS) & _BV(TX_EMPTY))) {
1435-
if (status & _BV(MAX_RT)) {
1436-
write_register(NRF_STATUS, _BV(MAX_RT));
1433+
if (status & RF24_TX_DF) {
1434+
write_register(NRF_STATUS, RF24_TX_DF);
14371435
ce(LOW);
14381436
flush_tx(); //Non blocking, flush the data
14391437
return 0;
@@ -1464,8 +1462,8 @@ bool RF24::txStandBy(uint32_t timeout, bool startTx)
14641462
uint32_t start = millis();
14651463

14661464
while (!(read_register(FIFO_STATUS) & _BV(TX_EMPTY))) {
1467-
if (status & _BV(MAX_RT)) {
1468-
write_register(NRF_STATUS, _BV(MAX_RT));
1465+
if (status & RF24_TX_DF) {
1466+
write_register(NRF_STATUS, RF24_TX_DF);
14691467
ce(LOW); // Set re-transmit
14701468
ce(HIGH);
14711469
if (millis() - start >= timeout) {
@@ -1524,7 +1522,7 @@ bool RF24::available(void)
15241522
bool RF24::available(uint8_t* pipe_num)
15251523
{
15261524
if (available()) { // if RX FIFO is not empty
1527-
*pipe_num = (get_status() >> RX_P_NO) & 0x07;
1525+
*pipe_num = (update() >> RX_P_NO) & 0x07;
15281526
return 1;
15291527
}
15301528
return 0;
@@ -1539,7 +1537,7 @@ void RF24::read(void* buf, uint8_t len)
15391537
read_payload(buf, len);
15401538

15411539
//Clear the only applicable interrupt flags
1542-
write_register(NRF_STATUS, _BV(RX_DR));
1540+
write_register(NRF_STATUS, RF24_RX_DR);
15431541
}
15441542

15451543
/****************************************************************************/
@@ -1548,12 +1546,44 @@ void RF24::whatHappened(bool& tx_ok, bool& tx_fail, bool& rx_ready)
15481546
{
15491547
// Read the status & reset the status in one easy call
15501548
// Or is that such a good idea?
1551-
write_register(NRF_STATUS, _BV(RX_DR) | _BV(TX_DS) | _BV(MAX_RT));
1549+
write_register(NRF_STATUS, RF24_IRQ_ALL);
15521550

15531551
// Report to the user what happened
1554-
tx_ok = status & _BV(TX_DS);
1555-
tx_fail = status & _BV(MAX_RT);
1556-
rx_ready = status & _BV(RX_DR);
1552+
tx_ok = status & RF24_TX_DS;
1553+
tx_fail = status & RF24_TX_DF;
1554+
rx_ready = status & RF24_RX_DR;
1555+
}
1556+
1557+
/****************************************************************************/
1558+
1559+
uint8_t RF24::clearStatusFlags(uint8_t flags)
1560+
{
1561+
write_register(NRF_STATUS, flags & RF24_IRQ_ALL);
1562+
return status;
1563+
}
1564+
1565+
/****************************************************************************/
1566+
1567+
void RF24::setStatusFlags(uint8_t flags)
1568+
{
1569+
// flip the `flags` to translate from "human understanding"
1570+
config_reg = (config_reg & ~RF24_IRQ_ALL) | (~flags & RF24_IRQ_ALL);
1571+
write_register(NRF_CONFIG, config_reg);
1572+
}
1573+
1574+
/****************************************************************************/
1575+
1576+
uint8_t RF24::getStatusFlags()
1577+
{
1578+
return status;
1579+
}
1580+
1581+
/****************************************************************************/
1582+
1583+
uint8_t RF24::update()
1584+
{
1585+
read_register(RF24_NOP, (uint8_t*)nullptr, 0);
1586+
return status;
15571587
}
15581588

15591589
/****************************************************************************/

0 commit comments

Comments
 (0)