From fd90bc4308ca23af317c5da3d82229d20d7d38f5 Mon Sep 17 00:00:00 2001
From: Brendan <2bndy5@gmail.com>
Date: Tue, 19 Nov 2024 00:45:18 -0800
Subject: [PATCH] use enum to return precise FIFO state

---
 RF24.cpp          |  7 ++++---
 RF24.h            | 30 ++++++++++++++++++++++++++----
 pyRF24/pyRF24.cpp |  9 ++++++++-
 3 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/RF24.cpp b/RF24.cpp
index f0f7a087..2e921188 100644
--- a/RF24.cpp
+++ b/RF24.cpp
@@ -1382,16 +1382,17 @@ bool RF24::rxFifoFull()
 
 /****************************************************************************/
 
-uint8_t RF24::isFifo(bool about_tx)
+rf24_fifo_state_e RF24::isFifo(bool about_tx)
 {
-    return static_cast<uint8_t>((read_register(FIFO_STATUS) >> (4 * about_tx)) & 3);
+    uint8_t state = (read_register(FIFO_STATUS) >> (4 * about_tx)) & 3;
+    return static_cast<rf24_fifo_state_e>(state);
 }
 
 /****************************************************************************/
 
 bool RF24::isFifo(bool about_tx, bool check_empty)
 {
-    return static_cast<bool>(isFifo(about_tx) & _BV(!check_empty));
+    return static_cast<bool>(static_cast<uint8_t>(isFifo(about_tx)) & _BV(!check_empty));
 }
 
 /****************************************************************************/
diff --git a/RF24.h b/RF24.h
index f712750f..0d222f91 100644
--- a/RF24.h
+++ b/RF24.h
@@ -108,6 +108,26 @@ typedef enum
     RF24_CRC_16
 } rf24_crclength_e;
 
+/**
+ * @}
+ * @defgroup fifoState FIFO state
+ * The state of a single FIFO (RX or TX).
+ * Remember, each FIFO has a maximum occupancy of 3 payloads.
+ * @see RF24::isFifo()
+ * @{
+ */
+typedef enum
+{
+    /// @brief The FIFO is not full nor empty, but it is occupied with 1 or 2 payloads.
+    RF24_FIFO_OCCUPIED,
+    /// @brief The FIFO is empty.
+    RF24_FIFO_EMPTY,
+    /// @brief The FIFO is full.
+    RF24_FIFO_FULL,
+    /// @brief Represents corruption of data over SPI (when observed).
+    RF24_FIFO_INVALID,
+} rf24_fifo_state_e;
+
 /**
  * @}
  * @brief Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver
@@ -785,13 +805,15 @@ class RF24
     /**
      * @param about_tx `true` focuses on the TX FIFO, `false` focuses on the RX FIFO
      * @return
-     * - `0` if the specified FIFO is neither full nor empty.
-     * - `1` if the specified FIFO is empty.
-     * - `2` if the specified FIFO is full.
+     * - @ref RF24_FIFO_OCCUPIED (`0`) if the specified FIFO is neither full nor empty.
+     * - @ref RF24_FIFO_EMPTY (`1`) if the specified FIFO is empty.
+     * - @ref RF24_FIFO_FULL (`2`) if the specified FIFO is full.
+     * - @ref RF24_FIFO_INVALID (`3`) if the data fetched over SPI was malformed.
      */
-    uint8_t isFifo(bool about_tx);
+    rf24_fifo_state_e isFifo(bool about_tx);
 
     /**
+     * @deprecated Use RF24::isFifo(bool about_tx) instead.
      * @param about_tx `true` focuses on the TX FIFO, `false` focuses on the RX FIFO
      * @param check_empty
      * - `true` checks if the specified FIFO is empty
diff --git a/pyRF24/pyRF24.cpp b/pyRF24/pyRF24.cpp
index 2c8dd567..56085a9a 100644
--- a/pyRF24/pyRF24.cpp
+++ b/pyRF24/pyRF24.cpp
@@ -280,6 +280,13 @@ BOOST_PYTHON_MODULE(RF24)
         .value("RF24_PA_ERROR", RF24_PA_ERROR)
         .export_values();
 
+    bp::enum_<rf24_fifo_state_e>("rf24_fifo_state_e")
+        .value("RF24_FIFO_OCCUPIED", RF24_FIFO_OCCUPIED)
+        .value("RF24_FIFO_EMPTY", RF24_FIFO_EMPTY)
+        .value("RF24_FIFO_FULL", RF24_FIFO_FULL)
+        .value("RF24_FIFO_INVALID", RF24_FIFO_INVALID)
+        .export_values();
+
     // ******************** RF24 class  **************************
     bp::class_<RF24>("RF24", bp::init<uint16_t, uint16_t>((bp::arg("_cepin"), bp::arg("_cspin"))))
 #if defined(RF24_LINUX) && !defined(MRAA)
@@ -320,7 +327,7 @@ BOOST_PYTHON_MODULE(RF24)
         .def("reUseTX", &RF24::reUseTX)
         .def("read", &read_wrap, (bp::arg("maxlen")))
         .def("rxFifoFull", &RF24::rxFifoFull)
-        .def("isFifo", (uint8_t(::RF24::*)(bool))(&::RF24::isFifo), (bp::arg("about_tx")))
+        .def("isFifo", (rf24_fifo_state_e(::RF24::*)(bool))(&::RF24::isFifo), (bp::arg("about_tx")))
         .def("isFifo", (bool(::RF24::*)(bool, bool))(&::RF24::isFifo), (bp::arg("about_tx"), bp::arg("check_empty")))
         .def("setAddressWidth", &RF24::setAddressWidth)
         .def("setAutoAck", (void(::RF24::*)(bool))(&::RF24::setAutoAck), (bp::arg("enable")))