Documentação do código

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Para a versão em PT-BR 🇧🇷 desse documento, [veja aqui](CONTRIBUTING.pt-br
 
 First of all, thanks for your interest! We really appreciate the participation of the community! ✨
 
-Here we describe a set of guidelines when contributing to the VSS simulation. These are not strict rules, so use your best judgment, and in case you have questions, contact us on [email protected].
+Here we describe a set of guidelines when contributing to STM32RF24. These are not strict rules, so use your best judgment, and in case you have questions, contact us on [email protected].
 
 Please note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
 
@@ -56,7 +56,7 @@ A few recomendations:
 
 ## Styleguide 💄
 
-### Formatação do código
+### Code formatting
 
 The code is formatted following specific rules, for more information on how to ensure that your code is formatted correctly, see the [🎨 Formatting](./README.md#-formatting) section on the README.
 
@@ -69,7 +69,7 @@ There are some guidelines for organizing C code that should be followed.
 
 ― Harold Abelson, Structure and Interpretation of Computer Programs
 
-#### Scopes
+#### Variables and functions scopes
 
 Always reduce the scopes of the to the minimum possible, avoiding global, external and static variables, giving preference to local variables. The same is ture for functions, do not create public functions if they are only to be used within a file, leave them private.
 
@@ -94,17 +94,13 @@ For more naming tips, see the article ["How To Create Meaningful Names In Code"]
 
 #### Variable types
 
-Make coherent choices for your variable types and your functions return types, besides its parameters, for examples, do not use `float` if your variable is a unit counter.
-
-Make a consistent choice for the types of variables and types of return of functions, in addition to their parameters, for example, do not use `float` if your variable will be a unit counter.
-
-Além disso, para variáveis inteiras faça distinção entre `signed` e `unsigned` e especifique seu tamanho em bits, isso garante mais controle sobre os valores que cada variável pode ter, como também otimiza a ocupação da memória. Para isso utilize a biblioteca `stdint.h`, podendo assim, por exemplo, se utilizar os tipos `uint8_t` para inteiros de 8 bits sem sinal e `int16_t` para inteiros de 16 bits com sinal.
+Make coherent choices for your variable types and your functions return and parameters types. For examples, do not use `float` if your variable is a unit counter.
 
 Besides that, for integer variables, distinguish between `signed` and `unsigned` and specify their size in bits, this ensures more control over the values that each variable can have, as well as optimizes the memory occupation. To do this, use the `stdint.h` library, than, for example, you can use the types `uint8_t` for unsigned 8-bit integers and `int16_t` for signed 16-bit integers.
 
 #### Magic numbers/Constants
 
-Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)) in your code, in addition to obscuring the understanding of it, they also make maintenance difficult. To solve this, use constants defined with `#define` at the beginning of your code.
+Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)) in your code. In addition to decreasing readability, they also make maintenance difficult. To solve this, use constants defined with `#define` at the beginning of your code.
 
 ### Git commit messages
 

CONTRIBUTING.pt-br.md

@@ -67,7 +67,7 @@ Existem algumas diretrizes de organização de código em C que devem seguidas.
 
 ― Harold Abelson, Structure and Interpretation of Computer Programs
 
-#### Escopos
+#### Escopos de variáveis e funções
 
 Reduza sempre os escopos das variáveis ao menor possível, evitando variáveis globais, externas e estáticas, dando preferência para variáveis locais. O mesmo é válido para funções, não crie funções públicas se elas so forem ser usadas dentro de um arquivo, deixe elas privadas.
 
@@ -98,7 +98,7 @@ Além disso, para variáveis inteiras faça distinção entre `signed` e `unsign
 
 #### Números mágicos/Constantes
 
-Evite [números mágicos](https://pt.wikipedia.org/wiki/N%C3%BAmero_m%C3%A1gico_(programa%C3%A7%C3%A3o_de_sistemas)) no meio do código, além de eles obscurecerem o entendimento do mesmo, também dificultam a manutenção. Para contornar isso, utilize constantes definidas com `#define` no ínicio do seu código.
+Evite [números mágicos](https://pt.wikipedia.org/wiki/N%C3%BAmero_m%C3%A1gico_(programa%C3%A7%C3%A3o_de_sistemas)) no meio do código. Além de eles dificultarem a leitura do mesmo, também dificultam a manutenção. Para contornar isso, utilize constantes definidas com `#define` no ínicio do seu código.
 
 ### Menssagens de commit
 

README.md

@@ -34,7 +34,7 @@ Para a versão em PT-BR 🇧🇷 desse documento, [veja aqui](./README.pt-br.md)
 
 ## 🎉 Intro
 
-This repository contains a library to handle Nordic Semiconductor's radio frequency module nRF24L01, whose datasheet can be viewed [here](docs/Nordic_Semiconductor-NRF24L01-datasheet.pdf), when using the microcontrollers of the [STM32] family [STM32](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html).
+This repository contains a library to handle Nordic Semiconductor's radio frequency module nRF24L01, whose datasheet can be viewed [here](docs/Nordic_Semiconductor-NRF24L01-datasheet.pdf), when using the microcontrollers of the [STM32](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html) family.
 
 This library was made to be used as a submodule in the [STM32ProjectTemplate](https://github.com/ThundeRatz/STM32ProjectTemplate).
 
@@ -60,7 +60,7 @@ sudo apt install uncrustify
 On Windows, download the .zip from [SourceForge](https://sourceforge.net/projects/uncrustify/files/). Add the location of the executable in the `PATH` environment variable.
 
 
-## 📦 Adding a submodule
+## 📦 Git Submodules
 
 As stated, this library functions as a submodule. In this way, it is easier to choose the version of the library that will be used in the project, also allowing its development in parallel.
 
@@ -147,7 +147,7 @@ To configure your hardware, you must first analyze the pinout of the nRF24L01 mo
 
 ![nRF24L01 Module's Pinout](./assets/img/nrf24l01_pinout.png)
 
-The module uses SPI (Serial Protocol Interface) to communicate with the microcontroller (to learn more about SPI, I recommend this article [here](https://learn.sparkfun.com/tutorials/serial-peripheral-interface-spi/all) from Sparkfun), so four pins are required for this communication, SCK, MISO, MOSI and CSN. The CSN is a GPIO pin, while the others are dedicated pins.
+The module uses SPI (Serial Protocol Interface) to communicate with the microcontroller (to learn more about SPI, we recommend this article [here](https://learn.sparkfun.com/tutorials/serial-peripheral-interface-spi/all) from Sparkfun), so four pins are required for this communication, SCK, MISO, MOSI and CSN. The CSN is a GPIO pin, while the others are dedicated pins.
 
 In addition, a GPIO pin connected to the CE (Chip Enable) is needed, which is used to control the module, enabling the transition between the states of the module's finite state machine.
 
@@ -391,7 +391,7 @@ if ((device_status = rf24_available(p_dev, NULL)) == RF24_SUCCESS) {
 
 ### 🐛 Debugging
 
-To debug your code it is possible to use the functions of the file `rf24_debug.c/.h`, but for this it is also necessary to define a `printf` function. For ease of use, I recommend adding the [SEGGER_RTT](https://github.com/ThundeRatz/SEGGER_RTT) to the project. After adding it, having called the debugging functions in your code, to see what is being "printed" by the functions, run in the terminal, being at the root of your project:
+To debug your code it is possible to use the functions of the file `rf24_debug.c/.h`, but for this it is also necessary to define a `printf` function. For ease of use, we recommend adding the [SEGGER_RTT](https://github.com/ThundeRatz/SEGGER_RTT) to the project. After adding it, having called the debugging functions in your code, to see what is being "printed" by the functions, run in the terminal, being at the root of your project:
 
 ```C
 make rtt

inc/rf24.h

@@ -41,7 +41,7 @@ typedef enum rf24_status {
     RF24_BUFFER_TOO_SMALL = 5,
     RF24_INTERRUPT_NOT_CLEARED = 6,
     RF24_INVALID_PARAMETERS = 7,
-    RF24_UNKNOWN_ERRO = 8,
+    RF24_UNKNOWN_ERROR = 8,
 } rf24_status_t;
 
 /**
@@ -151,6 +151,8 @@ rf24_status_t rf24_set_channel(rf24_dev_t* p_dev, uint8_t ch);
  * @param p_dev Pointer to rf24 device.
  *
  * @return Channel value.
+ * @retval 0xFF Returns 0xFF when got an error, because
+ *         channel value can't be bigger than 125.
  */
 uint8_t rf24_get_channel(rf24_dev_t* p_dev);
 

src/rf24.c

@@ -55,11 +55,28 @@
  */
 #define MAX_NUM_OF_PIPES 6
 
+/**
+ * @brief Error value for status register.
+ *
+ * @note Bit 7 only allows 0, so 0xFF represents an erro value.
+ */
+#define STATUS_REG_ERROR_VALUE 0xFF
+
+/**
+ * @brief Error value for channel.
+ *
+ * @note The max channel value is 125, so 0xFF represents an erro value.
+ */
+#define CHANNEL_ERROR_VALUE 0xFF
+
 /*****************************************
  * Private Macros
  *****************************************/
 
-#define BIT_SHIFT_LEFT(bits) (1 << (bits))
+/**
+ * @brief Get bit value
+ */
+#define _BV(num) (1 << (num))
 
 /*****************************************
  * Private Variables
@@ -175,9 +192,9 @@ rf24_status_t rf24_init(rf24_dev_t* p_dev) {
     }
 
     if (dev_status == RF24_SUCCESS) {
-        // If setup is 0 or ff then there was no response from module
+        // If setup is 0x00 or 0xFF then there was no response from module
         if ((rf_setup_reg.value == 0) || (rf_setup_reg.value == 0xFF)) {
-            dev_status = RF24_UNKNOWN_ERRO;
+            dev_status = RF24_UNKNOWN_ERROR;
         }
     }
 
@@ -253,7 +270,7 @@ uint8_t rf24_get_channel(rf24_dev_t* p_dev) {
     dev_status = (platform_status == RF24_PLATFORM_SUCCESS) ? (RF24_SUCCESS) : (RF24_ERROR_CONTROL_INTERFACE);
 
     if (dev_status != RF24_SUCCESS) {
-        return 0xFF;  // Invalid value, meaning error
+        return CHANNEL_ERROR_VALUE;
     }
 
     return reg.rf_ch;
@@ -319,7 +336,7 @@ rf24_status_t rf24_set_datarate(rf24_dev_t* p_dev, rf24_datarate_t datarate) {
 
         if (dev_status == RF24_SUCCESS) {
             if (temp_reg != reg_rf_setup.value) {
-                dev_status = RF24_UNKNOWN_ERRO;
+                dev_status = RF24_UNKNOWN_ERROR;
             }
         }
     }
@@ -352,7 +369,7 @@ rf24_status_t rf24_set_output_power(rf24_dev_t* p_dev, rf24_output_power_t outpu
 
         if (dev_status == RF24_SUCCESS) {
             if (temp_reg != reg_rf_setup.value) {
-                dev_status = RF24_UNKNOWN_ERRO;
+                dev_status = RF24_UNKNOWN_ERROR;
             }
         }
     }
@@ -439,7 +456,7 @@ rf24_status_t rf24_open_reading_pipe(rf24_dev_t* p_dev, uint8_t pipe_number, uin
     }
 
     if (dev_status == RF24_SUCCESS) {
-        reg_en_rx_addr.value |= BIT_SHIFT_LEFT(m_child_pipe_enable[pipe_number]);
+        reg_en_rx_addr.value |= _BV(m_child_pipe_enable[pipe_number]);
         platform_status = rf24_platform_write_reg8(&(p_dev->platform_setup), NRF24L01_REG_EN_RXADDR,
                                                    reg_en_rx_addr.value);
         dev_status = (platform_status == RF24_PLATFORM_SUCCESS) ? (RF24_SUCCESS) : (RF24_ERROR_CONTROL_INTERFACE);
@@ -461,7 +478,7 @@ rf24_status_t rf24_close_reading_pipe(rf24_dev_t* p_dev, uint8_t pipe_number) {
     }
 
     if (dev_status == RF24_SUCCESS) {
-        reg_en_rx_addr.value &= (~BIT_SHIFT_LEFT(m_child_pipe_enable[pipe_number]));
+        reg_en_rx_addr.value &= (~_BV(m_child_pipe_enable[pipe_number]));
         platform_status = rf24_platform_write_reg8(&(p_dev->platform_setup), NRF24L01_REG_EN_RXADDR,
                                                    reg_en_rx_addr.value);
         dev_status = (platform_status == RF24_PLATFORM_SUCCESS) ? (RF24_SUCCESS) : (RF24_ERROR_CONTROL_INTERFACE);
@@ -481,8 +498,8 @@ rf24_status_t rf24_start_listening(rf24_dev_t* p_dev) {
         platform_status = rf24_platform_read_reg8(&(p_dev->platform_setup), NRF24L01_REG_CONFIG, &(reg_config.value));
         dev_status = (platform_status == RF24_PLATFORM_SUCCESS) ? (RF24_SUCCESS) : (RF24_ERROR_CONTROL_INTERFACE);
 
-        reg_config.value |= BIT_SHIFT_LEFT(PRIM_RX);
-        reg_status.value = (BIT_SHIFT_LEFT(RX_DR) | BIT_SHIFT_LEFT(TX_DS) | BIT_SHIFT_LEFT(MAX_RT));
+        reg_config.value |= _BV(PRIM_RX);
+        reg_status.value = (_BV(RX_DR) | _BV(TX_DS) | _BV(MAX_RT));
 
         if (dev_status == RF24_SUCCESS) {
             platform_status = rf24_platform_write_reg8(&(p_dev->platform_setup), NRF24L01_REG_CONFIG, reg_config.value);
@@ -559,7 +576,7 @@ rf24_status_t rf24_stop_listening(rf24_dev_t* p_dev) {
         dev_status = (platform_status == RF24_PLATFORM_SUCCESS) ? (RF24_SUCCESS) : (RF24_ERROR_CONTROL_INTERFACE);
 
         if (dev_status == RF24_SUCCESS) {
-            reg_config.value &= (~BIT_SHIFT_LEFT(PRIM_RX));
+            reg_config.value &= (~_BV(PRIM_RX));
             platform_status = rf24_platform_write_reg8(&(p_dev->platform_setup), NRF24L01_REG_CONFIG, reg_config.value);
             dev_status = (platform_status == RF24_PLATFORM_SUCCESS) ? (RF24_SUCCESS) : (RF24_ERROR_CONTROL_INTERFACE);
         }
@@ -570,7 +587,7 @@ rf24_status_t rf24_stop_listening(rf24_dev_t* p_dev) {
         platform_status =
             rf24_platform_read_reg8(&(p_dev->platform_setup), NRF24L01_REG_EN_RXADDR, &(reg_en_rx_addr.value));
         dev_status = (platform_status == RF24_PLATFORM_SUCCESS) ? (RF24_SUCCESS) : (RF24_ERROR_CONTROL_INTERFACE);
-        reg_en_rx_addr.value |= BIT_SHIFT_LEFT(m_child_pipe_enable[0]);
+        reg_en_rx_addr.value |= _BV(m_child_pipe_enable[0]);
 
         if (dev_status == RF24_SUCCESS) {
             platform_status = rf24_platform_write_reg8(&(p_dev->platform_setup), NRF24L01_REG_EN_RXADDR,
@@ -713,7 +730,7 @@ nrf24l01_reg_status_t rf24_get_status(rf24_dev_t* p_dev) {
     rf24_platform_status_t platform_status = rf24_platform_get_status(&(p_dev->platform_setup), &status_reg);
 
     if (platform_status != RF24_PLATFORM_SUCCESS) {
-        status_reg.value = 0xFF;  // Bit 7 only allows 0, so 0xFF represents an erro value.
+        status_reg.value = STATUS_REG_ERROR_VALUE;
     }
 
     return status_reg;