add: expose status byte in public API.

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

Author: 2bndy5

RF24.cpp

@@ -12,6 +12,15 @@
 
 /****************************************************************************/
 
+int StatusFlags::toString(char* buf) const
+{
+    return sprintf(buf, "rx_dr: %s, tx_ds: %s, tx_df: %s, rx_pipe: %d, tx_full: %s",
+                   rx_dr ? "true" : "false", tx_ds ? "true" : "false",
+                   tx_df ? "true" : "false", rx_pipe, tx_full ? "true" : "false");
+}
+
+/****************************************************************************/
+
 void RF24::csn(bool mode)
 {
 #if defined(RF24_TINY)
@@ -1559,6 +1568,53 @@ void RF24::whatHappened(bool& tx_ok, bool& tx_fail, bool& rx_ready)
 
 /****************************************************************************/
 
+StatusFlags RF24::clearStatusFlags()
+{
+    write_register(NRF_STATUS, 0x70);
+    StatusFlags flags;
+    memcpy((void*)(&flags), &status, 1);
+    return flags;
+}
+
+/****************************************************************************/
+
+void RF24::clearStatusFlags(StatusFlags& flags)
+{
+    uint8_t out = 0;
+    memcpy(&out, &flags, 1);
+    write_register(NRF_STATUS, out & 0x70);
+    memcpy((void*)(&flags), &status, 1);
+}
+
+/****************************************************************************/
+
+void RF24::setStatusFlags(StatusFlags flags)
+{
+    uint8_t out = 0;
+    memcpy(&out, &flags, 1);
+    // flip the flags to translate from "human understanding"
+    write_register(NRF_CONFIG, ~out & 0x70);
+}
+
+/****************************************************************************/
+
+void RF24::getStatusFlags(StatusFlags& flags)
+{
+    memcpy((void*)(&flags), &status, 1);
+}
+
+/****************************************************************************/
+
+StatusFlags RF24::update()
+{
+    read_register(RF24_NOP, (uint8_t*)nullptr, 0);
+    StatusFlags flags;
+    memcpy((void*)(&flags), &status, 1);
+    return flags;
+}
+
+/****************************************************************************/
+
 void RF24::openWritingPipe(uint64_t value)
 {
     // Note that AVR 8-bit uC's store this LSB first, and the NRF24L01(+)

RF24.h

@@ -128,6 +128,54 @@ typedef enum
     RF24_FIFO_INVALID,
 } rf24_fifo_state_e;
 
+/**
+ * @}
+ * @defgroup StatusFlags Status flags
+ * @{
+ */
+
+/**
+ * @brief A bit-field struct to represent the radio's STATUS byte.
+ */
+struct StatusFlags
+{
+    // starting with bit 0 at the top...
+    /// Signifies that the TX FIFO is fully occupied.
+    const bool tx_full : 1;
+    /// @brief Represents the pipe number that received the first available payload in the RX FIFO.
+    /// @remark This data shall be considered invalid if the @ref StatusFlags::rx_dr flag is `false`.
+    const uint8_t rx_pipe : 3;
+    /// Represents an event where TX Data Failed to send.
+    bool tx_df : 1;
+    /// Represents an event where TX Data Sent successfully.
+    bool tx_ds : 1;
+    /// Represents an event where RX Data is Ready to `RF24::read()`.
+    bool rx_dr : 1;
+
+    /**
+     * @brief Convert this struct to a human understandable string.
+     *
+     * ```cpp
+     * char buf[69] = {0};
+     * StatusFlags flags;
+     * flags.toString(buf);
+     * ```
+     *
+     * Afterward, printing the string in `buf` should read something similar to:
+     *
+     * > rx_dr: false, tx_ds: false, tx_df: false, rx_pipe: 7, tx_full: false
+     *
+     * @param[out] buf The string buffer into which the StatusFlags description is stored.
+     * This buffer needs to be at least 69 bytes long.
+     * @returns The amount of bytes altered in the given `buf` parameter.
+     */
+    int toString(char* buf) const;
+
+    /// An explicit default initializer for compatibility with C++11 (or newer) standards.
+    /// @see Details about `StatusFlags::toString()` show an example output of default values.
+    StatusFlags() : tx_full(false), rx_pipe(7), tx_df(false), tx_ds(false), rx_dr(false) {};
+};
+
 /**
  * @}
  * @brief Driver class for nRF24L01(+) 2.4GHz Wireless Transceiver
@@ -1162,6 +1210,78 @@ class RF24
      */
     void whatHappened(bool& tx_ok, bool& tx_fail, bool& rx_ready);
 
+    /**
+     * Clear all of the StatusFlags that caused an interrupt event.
+     *
+     * @remark This function is similar to `whatHappened()` because it also returns the
+     * StatusFlags that caused the interrupt event. However, this function returns
+     * a 1-byte bit-field struct (@ref StatusFlags) instead of bit-banging 3 1-byte booleans
+     * passed by reference.
+     *
+     * @note When used in an ISR (Interrupt Service routine), there is a chance that the
+     * @ref StatusFlags::rx_pipe information is inaccurate. See available(uint8_t*) (or the
+     * datasheet) for more detail.
+     *
+     * @ingroup StatusFlags
+     */
+    StatusFlags clearStatusFlags();
+
+    /**
+     * Clear the specified flags.
+     *
+     * If any of the following flags are `true`, then the flag will be reset:
+     *
+     * - @ref StatusFlags::rx_dr
+     * - @ref StatusFlags::tx_ds
+     * - @ref StatusFlags::tx_df
+     *
+     * @ingroup StatusFlags
+     */
+    void clearStatusFlags(StatusFlags& flags);
+
+    /**
+     * Set which flags shall be reflected on the radio's IRQ pin.
+     *
+     * This is similar to maskIRQ(), but with a more intuitive API.
+     *
+     * @param flags The configuration of the StatusFlags to influence the radio's IRQ pin.
+     *
+     * If any of the following `flags` are `true`, then the flag's corresponding event will
+     * trigger the IRQ pin active HIGH:
+     *
+     * - @ref StatusFlags::rx_dr
+     * - @ref StatusFlags::tx_ds
+     * - @ref StatusFlags::tx_df
+     *
+     * @ingroup StatusFlags
+     */
+    void setStatusFlags(StatusFlags flags);
+
+    /**
+     * Get the latest STATUS byte returned from the last SPI transaction.
+     *
+     * @note This does not actually perform any SPI transaction with the radio.
+     * Use `RF24::update()` instead to get a fresh copy of the StatusFlags at
+     * the slight cost of performance.
+     *
+     * @param[out] flags The reference data into which the StatusFlags data is stored.
+     *
+     * In the python wrapper, this function takes no argument and instead
+     * returns an instance of StatusFlags.
+     *
+     * @ingroup StatusFlags
+     */
+    void getStatusFlags(StatusFlags& flags);
+
+    /**
+     * Get an updated STATUS byte from the radio.
+     *
+     * @returns The StatusFlags fetched directly from the radio.
+     *
+     * @ingroup StatusFlags
+     */
+    StatusFlags update();
+
     /**
      * Non-blocking write to the open writing pipe used for buffered writes
      *

cspell.config.yaml

@@ -225,6 +225,7 @@ words:
   - Quigg
   - raspi
   - REALPATH
+  - repr
   - rpmbuild
   - RXADDR
   - rxbuff

pyRF24/pyRF24.cpp

@@ -113,6 +113,31 @@ bp::tuple whatHappened_wrap(RF24& ref)
     return bp::make_tuple(tx_ok, tx_fail, tx_ready);
 }
 
+StatusFlags getStatusFlags_wrap(RF24& ref)
+{
+    StatusFlags flags;
+    ref.getStatusFlags(flags);
+    return flags;
+}
+bool get_rx_dr(const StatusFlags& ref) { return ref.rx_dr; }
+void set_rx_dr(StatusFlags& ref, bool value) { ref.rx_dr = value; }
+bool get_tx_ds(const StatusFlags& ref) { return ref.tx_ds; }
+void set_tx_ds(StatusFlags& ref, bool value) { ref.tx_ds = value; }
+bool get_tx_df(const StatusFlags& ref) { return ref.tx_df; }
+void set_tx_df(StatusFlags& ref, bool value) { ref.tx_df = value; }
+bool tx_full_wrap(const StatusFlags& ref) { return ref.tx_full; }
+uint8_t rx_pipe_wrap(const StatusFlags& ref) { return ref.rx_pipe; }
+std::string reprStatusFlags(StatusFlags& self)
+{
+    char* buf = new char[69];
+    self.toString(buf);
+    std::string result = "<StatusFlags ";
+    result += buf;
+    result += ">";
+    delete[] buf;
+    return result;
+}
+
 bp::tuple available_wrap(RF24& ref)
 {
     bool result;
@@ -287,6 +312,14 @@ BOOST_PYTHON_MODULE(RF24)
         .value("RF24_FIFO_INVALID", RF24_FIFO_INVALID)
         .export_values();
 
+    bp::class_<StatusFlags>("StatusFlags", bp::init<>())
+        .add_property("rx_dr", &get_rx_dr, &set_rx_dr)
+        .add_property("tx_ds", &get_tx_ds, &set_tx_ds)
+        .add_property("tx_df", &get_tx_df, &set_tx_df)
+        .add_property("tx_full", &tx_full_wrap)
+        .add_property("rx_pipe", &rx_pipe_wrap)
+        .def("__repr__", &reprStatusFlags);
+
     // ******************** RF24 class  **************************
     bp::class_<RF24>("RF24", bp::init<uint16_t, uint16_t>((bp::arg("_cepin"), bp::arg("_cspin"))))
 #if defined(RF24_LINUX) && !defined(MRAA)
@@ -348,6 +381,11 @@ BOOST_PYTHON_MODULE(RF24)
         .def("setRadiation", &RF24::setRadiation)
         .def("txStandBy", (bool(::RF24::*)(::uint32_t, bool))(&RF24::txStandBy), txStandBy_wrap1(bp::args("timeout", "startTx")))
         .def("whatHappened", &whatHappened_wrap)
+        .def("setStatusFlags", &RF24::setStatusFlags, (bp::arg("flags")))
+        .def("clearStatusFlags", (StatusFlags(::RF24::*)(void))(&RF24::clearStatusFlags))
+        .def("clearStatusFlags", (void(::RF24::*)(StatusFlags&))(&RF24::clearStatusFlags), (bp::arg("flags")))
+        .def("getStatusFlags", &getStatusFlags_wrap)
+        .def("update", &RF24::update)
         .def("startConstCarrier", &RF24::startConstCarrier, (bp::arg("level"), bp::arg("channel")))
         .def("stopConstCarrier", &RF24::stopConstCarrier)
         .def("write", &write_wrap1, (bp::arg("buf")))