style: enforce coding standard — headers, @brief on #define, Doxygen on statics, remove _ prefix, max 8 lines per function

0x001a_operators/0x001a_operators.c

@@ -1,36 +1,126 @@
+/**
+ * @file 0x001a_operators.c
+ * @brief Operators: demonstrate C operators with DHT11 temperature sensor
+ * @author Kevin Thomas
+ * @date 2025
+ *
+ * MIT License
+ *
+ * Copyright (c) 2025 Kevin Thomas
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * -----------------------------------------------------------------------------
+ *
+ * Demonstrates arithmetic, increment, relational, logical, bitwise, and
+ * assignment operators in C. Also reads humidity and temperature from a
+ * DHT11 sensor on GPIO4.
+ *
+ * Wiring:
+ *   GPIO4 -> DHT11 data pin (with 10k pull-up to 3V3)
+ *   3V3   -> DHT11 VCC
+ *   GND   -> DHT11 GND
+ */
+
 #include <stdio.h>
 #include "pico/stdlib.h"
 #include "dht11.h"
 
+/**
+ * @brief Print pre-computed operator results
+ *
+ * @details Prints all six operator demonstration values over UART.
+ *
+ * @param arith   arithmetic operator result
+ * @param inc     increment operator result
+ * @param rel     relational operator result
+ * @param logic   logical operator result
+ * @param bitw    bitwise operator result
+ * @param assign  assignment operator result
+ * @retval None
+ */
+static void print_operator_results(int arith, int inc, bool rel,
+                                    bool logic, int bitw, int assign) {
+    printf("arithmetic_operator: %d\r\n", arith);
+    printf("increment_operator: %d\r\n", inc);
+    printf("relational_operator: %d\r\n", rel);
+    printf("logical_operator: %d\r\n", logic);
+    printf("bitwise_operator: %d\r\n", bitw);
+    printf("assignment_operator: %d\r\n", assign);
+}
+
+/**
+ * @brief Compute arithmetic and increment operator results
+ *
+ * @param arith pointer to store multiplication result
+ * @param incr  pointer to store post-increment result
+ * @param x     left operand
+ * @param y     right operand
+ * @retval None
+ */
+static void compute_arithmetic_ops(int *arith, int *incr, int x, int y) {
+    *arith = (x * y);
+    *incr = x++;
+}
+
+/**
+ * @brief Compute all operator values and print results
+ *
+ * @details Performs arithmetic, relational, logical, bitwise,
+ *          and assignment operations, then prints each result.
+ *
+ * @retval None
+ */
+static void compute_operators(void) {
+    int x = 5, y = 10;
+    int arith, incr;
+    compute_arithmetic_ops(&arith, &incr, x, y);
+    bool rel = (x > y);
+    bool logic = (x > y) && (y > x);
+    int bits = (x << 1);
+    int assign = (x += 5);
+    print_operator_results(arith, incr, rel, logic, bits, assign);
+}
+
+/**
+ * @brief Read and print DHT11 humidity and temperature
+ *
+ * @details Attempts a DHT11 read; on success prints humidity and
+ *          temperature, on failure prints an error message.
+ *
+ * @retval None
+ */
+static void print_dht11_reading(void) {
+    float hum, temp;
+    if (dht11_read(&hum, &temp)) {
+        printf("Humidity: %.1f%%, Temperature: %.1f°C\r\n", hum, temp);
+    } else {
+        printf("DHT11 read failed\r\n");
+    }
+}
+
 int main(void) {
     stdio_init_all();
-
     dht11_init(4);
-
-    int x = 5;
-    int y = 10;
-    int arithmetic_operator = (x * y);
-    int increment_operator = x++;
-    bool relational_operator = (x > y);
-    bool logical_operator = (x > y) && (y > x);
-    int bitwise_operator = (x<<1);  // x is now 6 because of x++ or 0b00000110 and (x<<1) is 0b00001100 or 12 
-    int assignment_operator = (x += 5);
-
     while (true) {
-        printf("arithmetic_operator: %d\r\n", arithmetic_operator);
-        printf("increment_operator: %d\r\n", increment_operator);
-        printf("relational_operator: %d\r\n", relational_operator);
-        printf("logical_operator: %d\r\n", logical_operator);
-        printf("bitwise_operator: %d\r\n", bitwise_operator);
-        printf("assignment_operator: %d\r\n", assignment_operator);
-        
-        float hum, temp;
-        if (dht11_read(&hum, &temp)) {
-            printf("Humidity: %.1f%%, Temperature: %.1f°C\r\n", hum, temp);
-        } else {
-            printf("DHT11 read failed\r\n");
-        }
-        
+        compute_operators();
+        print_dht11_reading();
         sleep_ms(2000);
     }
 }

0x001a_operators/dht11.c

@@ -31,8 +31,97 @@
 #include "hardware/gpio.h"
 #include "pico/time.h"
 
+/** @brief GPIO pin connected to the DHT11 sensor */
 static uint dht_pin;
 
+/**
+ * @brief Send the DHT11 start signal on the data pin
+ *
+ * Drives the pin LOW for 18 ms then HIGH for 40 us before switching
+ * the pin to input mode to listen for the sensor response.
+ */
+static void send_start_signal(void) {
+    gpio_set_dir(dht_pin, GPIO_OUT);
+    gpio_put(dht_pin, 0);
+    sleep_ms(18);
+    gpio_put(dht_pin, 1);
+    sleep_us(40);
+    gpio_set_dir(dht_pin, GPIO_IN);
+}
+
+/**
+ * @brief Wait for the pin to leave a given logic level
+ *
+ * Spins until the pin no longer reads the specified level, returning
+ * false if a timeout of 10 000 iterations is exceeded.
+ *
+ * @param level Logic level to wait through (0 or 1)
+ * @return bool true once the level changed, false on timeout
+ */
+static bool wait_for_level(int level) {
+    uint32_t timeout = 10000;
+    while (gpio_get(dht_pin) == level)
+        if (--timeout == 0) return false;
+    return true;
+}
+
+/**
+ * @brief Wait for the DHT11 response after the start signal
+ *
+ * The sensor pulls LOW then HIGH then LOW again; each transition
+ * is awaited with a timeout.
+ *
+ * @return bool true if the full response was received, false on timeout
+ */
+static bool wait_response(void) {
+    if (!wait_for_level(1)) return false;
+    if (!wait_for_level(0)) return false;
+    if (!wait_for_level(1)) return false;
+    return true;
+}
+
+/**
+ * @brief Read a single bit from the DHT11 data stream
+ *
+ * Waits for the low-period to end, measures the high-period duration,
+ * and shifts the result into the appropriate byte of the data array.
+ *
+ * @param data 5-byte array accumulating the received bits
+ * @param i    Bit index (0-39)
+ * @return bool true on success, false on timeout
+ */
+static bool read_bit(uint8_t *data, int i) {
+    if (!wait_for_level(0)) return false;
+    uint32_t start = time_us_32();
+    if (!wait_for_level(1)) return false;
+    uint32_t duration = time_us_32() - start;
+    data[i / 8] <<= 1;
+    if (duration > 40) data[i / 8] |= 1;
+    return true;
+}
+
+/**
+ * @brief Read all 40 data bits from the DHT11
+ *
+ * @param data 5-byte array filled with the received data
+ * @return bool true if all 40 bits were read, false on timeout
+ */
+static bool read_40_bits(uint8_t *data) {
+    for (int i = 0; i < 40; i++)
+        if (!read_bit(data, i)) return false;
+    return true;
+}
+
+/**
+ * @brief Verify the DHT11 checksum byte
+ *
+ * @param data 5-byte received data (bytes 0-3 plus checksum in byte 4)
+ * @return bool true if the checksum matches, false otherwise
+ */
+static bool validate_checksum(const uint8_t *data) {
+    return data[4] == ((data[0] + data[1] + data[2] + data[3]) & 0xFF);
+}
+
 void dht11_init(uint8_t pin) {
     dht_pin = pin;
     gpio_init(pin);
@@ -41,38 +130,10 @@ void dht11_init(uint8_t pin) {
 
 bool dht11_read(float *humidity, float *temperature) {
     uint8_t data[5] = {0};
-    
-    // Start signal
-    gpio_set_dir(dht_pin, GPIO_OUT);
-    gpio_put(dht_pin, 0);
-    sleep_ms(18);
-    gpio_put(dht_pin, 1);
-    sleep_us(40);
-    gpio_set_dir(dht_pin, GPIO_IN);
-    
-    // Wait for response
-    uint32_t timeout = 10000;
-    while (gpio_get(dht_pin) == 1) if (--timeout == 0) return false;
-    timeout = 10000;
-    while (gpio_get(dht_pin) == 0) if (--timeout == 0) return false;
-    timeout = 10000;
-    while (gpio_get(dht_pin) == 1) if (--timeout == 0) return false;
-    
-    // Read 40 bits
-    for (int i = 0; i < 40; i++) {
-        timeout = 10000;
-        while (gpio_get(dht_pin) == 0) if (--timeout == 0) return false;
-        uint32_t start = time_us_32();
-        timeout = 10000;
-        while (gpio_get(dht_pin) == 1) if (--timeout == 0) return false;
-        uint32_t duration = time_us_32() - start;
-        data[i / 8] <<= 1;
-        if (duration > 40) data[i / 8] |= 1;
-    }
-    
-    // Check checksum
-    if (data[4] != ((data[0] + data[1] + data[2] + data[3]) & 0xFF)) return false;
-    
+    send_start_signal();
+    if (!wait_response()) return false;
+    if (!read_40_bits(data)) return false;
+    if (!validate_checksum(data)) return false;
     *humidity = data[0] + data[1] * 0.1f;
     *temperature = data[2] + data[3] * 0.1f;
     return true;