refactored patch

- ran clang-format
- conforms to utility/template
- create how-to doc (w/ pics)
- CMake support mimics PicoSDK implementation

CMakeLists.txt

@@ -4,6 +4,10 @@ if (PICO_SDK_PATH)
     # If so, load the relevant CMakeLists-file but don't do anything else
     include(${CMAKE_CURRENT_LIST_DIR}/utility/rp2/CMakeLists.txt)
     return()
+elseif(DEFINED STM32)
+    option(STM32_ARCH "The STM32 architecture family (eg STM32F1 or STM32F4)" "STM32F1")
+    include(${CMAKE_CURRENT_LIST_DIR}/utility/STM32/CMakeLists.txt)
+    return()
 endif()
 
 cmake_minimum_required(VERSION 3.15)

RF24.cpp

@@ -593,7 +593,7 @@ void RF24::_init_obj()
 {
     // Use a pointer on the Arduino platform
 
-#if defined(RF24_SPI_PTR) && !defined(RF24_RP2)
+#if defined(RF24_SPI_PTR) && !defined(RF24_RP2) && !defined(STM32)
     _spi = &SPI;
 #endif // defined (RF24_SPI_PTR)
 
@@ -1518,7 +1518,7 @@ uint8_t RF24::getDynamicPayloadSize(void)
 
 bool RF24::available(void)
 {
-    return available(NULL);
+    return available(nullptr);
 }
 
 /****************************************************************************/
@@ -1786,7 +1786,7 @@ bool RF24::writeAckPayload(uint8_t pipe, const void* buf, uint8_t len)
 
 bool RF24::isAckPayloadAvailable(void)
 {
-    return available(NULL);
+    return available(nullptr);
 }
 
 /****************************************************************************/

RF24_config.h

@@ -56,6 +56,10 @@
     #include "utility/rp2/RF24_arch_config.h"
     #define sprintf_P sprintf
 
+// STM32Cube IDE.
+#elif !defined(ARDUINO) && defined(STM32)
+    #include "utility/STM32/RF24_arch_config.h"
+
 #elif (!defined(ARDUINO)) // Any non-arduino device is handled via configure/Makefile
     // The configure script detects device and copies the correct includes.h file to /utility/includes.h
     // This behavior can be overridden by calling configure with respective parameters

docs/stm32cube.md

@@ -0,0 +1,48 @@
+# Using RF24 in the STM32Cube IDE
+
+The RF24 library can be integrated with any STM32Cube project.
+
+## Required Hardware
+
+The nRF24L01 radio requires 1 SPI bus and 2 GPIO pins for minimal usage. If using the radio's IRQ pin, then that will require an additional GPIO pin.
+
+You can use the IDE set up the necessary GPIO/SPI pins and have the IDE automatically generate the code to initialize the resources.
+
+The RF24 libaray manages the CSN pin without using the STM32HAL features. When setting up the SPI bus, there's no need to use the chips reserved CS pin associated with the selected SPI bus. The RF24 library allows using any GPIO output pin.
+
+## Basic Project Setup
+
+To integrate the RF24 library code into your STM32Cube project, follow these steps:
+
+1. Create a copy of the library in your project's "Drivers" directory.
+2. Exclude all sub-directories except "STM32" in the RF24/utility/ directory.
+3. Open your project's settings and add 2 symbols.
+    1. right-click the project's root folder and select properties.
+        ![select project properties](../images/STM32Cube-project-properties.png)
+    2. In the "C/C++ General" -> "Paths and Symbols" from the side menu.
+        ![select path and symbols](../images/STM32Cube-project-path-symbols.png)
+    3. Select the "Symbols" tab in the main portion of the properties dialogue.
+        ![select symbols](../images/STM32Cube-project-symbols.png)
+    4. Add the following variables (case-sensitive) to both "GNU C" and "GNU C++" categories:
+        - `STM32` (used by RF24_arch_config.h and RF24.cpp)
+        - `STM32yx` where `yx` describes the family of the desired STM32 chip.
+          For example:
+
+            - If using an STM32F103 chip, then set a variable named `STM32F1`
+            - If using an STM32F411 chip, then set a variable named `STM32F4`
+
+        ![add symbols](../images/STM32Cube-language-symbols.png)
+4. Now you can use the RF24 library anywhere in your project like so:
+
+    ```cpp
+    #include "RF24.h"
+
+    RF24 radio = RF24(GPIO_PIN_3, GPIO_PIN_4);
+    if (!radio.begin()) {
+        return 1; // failed to init radio hardware
+    }
+    ```
+
+## Using multiple SPI buses
+
+TODO

utility/STM32/CMakeLists.txt

@@ -0,0 +1,27 @@
+# # Include this file if you want to use the RF24 library
+# # in YOUR (STM32Cube) project.
+# # NOTE: This is preliminary support for CMake (which is not typically used in STM32Cube IDE)
+
+cmake_minimum_required(VERSION 3.12)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+
+add_library(rf24 INTERFACE
+    ../../RF24.cpp
+    ${CMAKE_CURRENT_LIST_DIR}/RF24_arch_config.h
+    ${CMAKE_CURRENT_LIST_DIR}/spi.cpp
+    ${CMAKE_CURRENT_LIST_DIR}/gpio.cpp
+    ${CMAKE_CURRENT_LIST_DIR}/compatibility.cpp
+)
+
+# STM32_ARCH option set in RF24/CMakeLists.txt
+target_compile_definitions(rf24 PUBLIC -DSTM32 -D${STM32_ARCH})
+
+# STM32CubeHalIncludes array/variable set in the project's CMakeLists.txt
+target_include_directories(rf24 PRIVATE . ${STM32CubeHalIncludes} ../Core/Inc)
+
+target_compile_options(rf24 PRIVATE -Ofast)
+
+# STM32CubeHal library discovery in project's CMakeLists.txt
+target_link_libraries(rf24 PRIVATE STM32CubeHal)

utility/STM32/RF24_arch_config.h

@@ -18,11 +18,8 @@
  * @{
  */
 
-#ifndef RF24_UTILITY_TEMPLATE_RF24_ARCH_CONFIG_H_
-#define RF24_UTILITY_TEMPLATE_RF24_ARCH_CONFIG_H_
-
-#include <cstdint>
-#include <memory.h>
+#ifndef RF24_UTILITY_STM32_RF24_ARCH_CONFIG_H_
+#define RF24_UTILITY_STM32_RF24_ARCH_CONFIG_H_
 
 // define here the architecture that you are using
 //#define STM32F1
@@ -32,19 +29,11 @@
 // builds the rf24 library with minimal requirements
 #define MINIMAL
 
-#if defined(STM32F1)
-#include "stm32f1xx_hal.h"
-#include "stm32f1xx_hal_gpio.h"
-#include "stm32f1xx_hal_spi.h"
-#elif defined(STM32F3)
-#include "stm32f3xx_hal.h"
-#include "stm32f3xx_hal_gpio.h"
-#include "stm32f3xx_hal_spi.h"
-#elif defined(STM32F4)
-#include "stm32f4xx_hal.h"
-#include "stm32f4xx_hal_gpio.h"
-#include "stm32f4xx_hal_spi.h"
-#endif
+#include <cstring>
+#include "compatibility.h"
+#include "spi.h"
+#include "gpio.h"
+#include "includes.h"
 
 #undef SERIAL_DEBUG
 #ifdef SERIAL_DEBUG
@@ -53,197 +42,22 @@
     #define IF_SERIAL_DEBUG(x)
 #endif
 
-#if !defined(PROGMEM)
-#define PROGMEM
-#endif
-
-#if !defined(_BV)
-#define _BV(bit) (1<<(bit))
-#endif
-
-#if !defined(PSTR)
-#define PSTR(x) (x)
-#endif
-
 #if !defined(printf_P)
-#define printf_P(x)
-#endif
-
-#if !defined(pgm_read_word)
-#define pgm_read_word(p) (*(p))
-#endif
-
-#if !defined(pgm_read_byte)
-#define pgm_read_byte(p) (*(p))
-#endif
-
-#if !defined(pgm_read_ptr)
-#define pgm_read_ptr(p)  (*(p))
-#endif
-
-typedef enum {
-    RF24_PA0 = 0,
-    RF24_PA1,
-    RF24_PA2,
-    RF24_PA3,
-    RF24_PA4,
-    RF24_PA5,
-    RF24_PA6,
-    RF24_PA7,
-    RF24_PA8,
-    RF24_PA9,
-    RF24_PA10,
-    RF24_PA11,
-    RF24_PA12,
-    RF24_PA13,
-    RF24_PA14,
-    RF24_PA15,
-    RF24_PB0,
-    RF24_PB1,
-    RF24_PB2,
-    RF24_PB3,
-    RF24_PB4,
-    RF24_PB5,
-    RF24_PB6,
-    RF24_PB7,
-    RF24_PB8,
-    RF24_PB9,
-    RF24_PB10,
-    RF24_PB11,
-    RF24_PB12,
-    RF24_PB13,
-    RF24_PB14,
-    RF24_PB15,
-    RF24_PC0,
-    RF24_PC1,
-    RF24_PC2,
-    RF24_PC3,
-    RF24_PC4,
-    RF24_PC5,
-    RF24_PC6,
-    RF24_PC7,
-    RF24_PC8,
-    RF24_PC9,
-    RF24_PC10,
-    RF24_PC11,
-    RF24_PC12,
-    RF24_PC13,
-    RF24_PC14,
-    RF24_PC15,
-    RF24_PD0,
-    RF24_PD1,
-    RF24_PD2,
-    RF24_PD3,
-    RF24_PD4,
-    RF24_PD5,
-    RF24_PD6,
-    RF24_PD7,
-    RF24_PD8,
-    RF24_PD9,
-    RF24_PD10,
-    RF24_PD11,
-    RF24_PD12,
-    RF24_PD13,
-    RF24_PD14,
-    RF24_PD15,
-    RF24_PE0,
-    RF24_PE1,
-    RF24_PE2,
-    RF24_PE3,
-    RF24_PE4,
-    RF24_PE5,
-    RF24_PE6,
-    RF24_PE7,
-    RF24_PE8,
-    RF24_PE9,
-    RF24_PE10,
-    RF24_PE11,
-    RF24_PE12,
-    RF24_PE13,
-    RF24_PE14,
-    RF24_PE15,
-    RF24_PF0,
-    RF24_PF1,
-    RF24_PF2,
-    RF24_PF3,
-    RF24_PF4,
-    RF24_PF5,
-    RF24_PF6,
-    RF24_PF7,
-    RF24_PF8,
-    RF24_PF9,
-    RF24_PF10,
-    RF24_PF11,
-    RF24_PF12,
-    RF24_PF13,
-    RF24_PF14,
-    RF24_PF15,
-    RF24_PG0,
-    RF24_PG1,
-    RF24_PG2,
-    RF24_PG3,
-    RF24_PG4,
-    RF24_PG5,
-    RF24_PG6,
-    RF24_PG7,
-    RF24_PG8,
-    RF24_PG9,
-    RF24_PG10,
-    RF24_PG11,
-    RF24_PG12,
-    RF24_PG13,
-    RF24_PG14,
-    RF24_PG15,
-} rf24_pin;
-
-#if !defined(HIGH)
-#define HIGH true
+    #define printf_P(x)
 #endif
 
-#if !defined(LOW)
-#define LOW false
-#endif
-
-#if !defined(INPUT)
-#define INPUT                    GPIO_MODE_INPUT
-#endif
-
-#if !defined(OUTPUT)
-#define OUTPUT                   GPIO_MODE_OUTPUT_PP
-#endif
-
-#if !defined(digitalWrite)
-void digitalWrite(uint8_t pin, uint8_t value);
-#endif
-
-#if !defined(pinMode)
-void pinMode(uint8_t pin, uint8_t direction);
-#endif
-
-#if !defined(millis)
-#define millis HAL_GetTick
-#endif
-
-#if !defined(delayMicroseconds)
-void delayMicroseconds(uint32_t usecs);
-#endif
-
-#if !defined(delay)
-#define delay(msecs) delayMicroseconds(1000*msecs)
-#endif
-
-class RF24_SPI {
-public:
-    RF24_SPI();
-    void begin();
-    void begin(SPI_HandleTypeDef* hspi);
-    uint8_t transfer(uint8_t data_to_send);
-private:
-    SPI_HandleTypeDef* _hspi;
-};
+#define _BV(bit) (1 << (bit))
+#define PROGMEM
+#define PSTR(x)          (x)
+#define PRIPSTR          "%s"
+#define pgm_read_word(p) (*(const unsigned char*)(p))
+#define pgm_read_byte(p) (*(const unsigned short*)(p))
+#define pgm_read_ptr(p)  (*(const void*)(p))
 
-extern RF24_SPI _SPI;
+#define delayMicroseconds(usecs) __usleep(usecs)
+#define delay(msecs)             HAL_Delay(msecs)
+#define millis                   HAL_GetTick
 
 /**@}*/
 
-#endif // RF24_UTILITY_TEMPLATE_RF24_ARCH_CONFIG_H_
+#endif // RF24_UTILITY_STM32_RF24_ARCH_CONFIG_H_

utility/STM32/compatibility.cpp

@@ -0,0 +1,14 @@
+#include "compatibility.h"
+
+uint32_t rf24_get_time_us()
+{
+    return 1000 * HAL_GetTick() + 1000 - (SysTick->VAL / (SystemCoreClock / 1000000));
+};
+
+void __usleep(int32_t usecs)
+{
+    uint32_t now = rf24_get_time_us();
+    uint32_t blocked_until = now + usecs;
+    while (blocked_until > rf24_get_time_us()) {
+    }
+};