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

0x0023_structures/ir.c

@@ -32,19 +32,89 @@
 #include "pico/time.h"
 #include "hardware/gpio.h"
 
+/** @brief GPIO pin connected to the IR receiver */
 static unsigned int ir_pin = 0;
 
-// Wait for 'gpio' to reach 'level' or timeout (microseconds). Return elapsed us or -1.
+/**
+ * @brief Wait for a GPIO pin to reach a given logic level
+ *
+ * Spins until the pin matches the requested level or a microsecond timeout
+ * is exceeded. Returns the elapsed time in microseconds, or -1 on timeout.
+ *
+ * @param gpio       GPIO pin to monitor
+ * @param level      Desired logic level (true = HIGH, false = LOW)
+ * @param timeout_us Maximum wait in microseconds
+ * @return int64_t   Elapsed microseconds, or -1 on timeout
+ */
 static int64_t wait_for_level(unsigned int gpio, bool level, uint32_t timeout_us) {
     absolute_time_t start = get_absolute_time();
     while (gpio_get(gpio) != level) {
-        if (absolute_time_diff_us(start, get_absolute_time()) > (int64_t)timeout_us) {
+        if (absolute_time_diff_us(start, get_absolute_time()) > (int64_t)timeout_us)
             return -1;
-        }
     }
     return absolute_time_diff_us(start, get_absolute_time());
 }
 
+/**
+ * @brief Wait for the NEC 9 ms leader pulse and 4.5 ms space
+ *
+ * @return bool true if a valid leader was detected, false on timeout
+ */
+static bool wait_leader(void) {
+    if (wait_for_level(ir_pin, 0, 150000) < 0) return false;
+    int64_t t = wait_for_level(ir_pin, 1, 12000);
+    if (t < 8000 || t > 10000) return false;
+    t = wait_for_level(ir_pin, 0, 7000);
+    if (t < 3500 || t > 5000) return false;
+    return true;
+}
+
+/**
+ * @brief Read a single NEC-encoded bit from the IR receiver
+ *
+ * Measures the mark/space timing and shifts the result into the
+ * appropriate byte of the data array.
+ *
+ * @param data 4-byte array accumulating received bits
+ * @param i    Bit index (0-31)
+ * @return bool true on success, false on timeout or protocol error
+ */
+static bool read_nec_bit(uint8_t *data, int i) {
+    if (wait_for_level(ir_pin, 1, 1000) < 0) return false;
+    int64_t t = wait_for_level(ir_pin, 0, 2500);
+    if (t < 200) return false;
+    int byte_idx = i / 8;
+    int bit_idx = i % 8;
+    if (t > 1200) data[byte_idx] |= (1 << bit_idx);
+    return true;
+}
+
+/**
+ * @brief Read all 32 data bits of an NEC frame
+ *
+ * @param data 4-byte array filled with the received address and command
+ * @return bool true if all 32 bits were read, false on timeout
+ */
+static bool read_32_bits(uint8_t *data) {
+    for (int i = 0; i < 32; ++i)
+        if (!read_nec_bit(data, i)) return false;
+    return true;
+}
+
+/**
+ * @brief Validate an NEC frame and extract the command byte
+ *
+ * Checks that the address and command pairs are bitwise-inverted.
+ *
+ * @param data 4-byte NEC frame (addr, ~addr, cmd, ~cmd)
+ * @return int Command byte (0-255) on success, -1 on validation failure
+ */
+static int validate_nec_frame(const uint8_t *data) {
+    if ((uint8_t)(data[0] + data[1]) == 0xFF && (uint8_t)(data[2] + data[3]) == 0xFF)
+        return data[2];
+    return -1;
+}
+
 void ir_init(uint8_t pin) {
     ir_pin = pin;
     gpio_init(pin);
@@ -53,28 +123,8 @@ void ir_init(uint8_t pin) {
 }
 
 int ir_getkey(void) {
-    // leader low (~9 ms)
-    if (wait_for_level(ir_pin, 0, 150000) < 0) return -1;
-
-    int64_t t = wait_for_level(ir_pin, 1, 12000);
-    if (t < 8000 || t > 10000) return -1;
-
-    t = wait_for_level(ir_pin, 0, 7000);
-    if (t < 3500 || t > 5000) return -1;
-
+    if (!wait_leader()) return -1;
     uint8_t data[4] = {0, 0, 0, 0};
-    for (int i = 0; i < 32; ++i) {
-        if (wait_for_level(ir_pin, 1, 1000) < 0) return -1;
-        t = wait_for_level(ir_pin, 0, 2500);
-        if (t < 200) return -1;
-        int byte_idx = i / 8;
-        int bit_idx = i % 8;
-        if (t > 1200) data[byte_idx] |= (1 << bit_idx); // logical '1'
-    }
-
-    // Validate address/data inverted pairs
-    if ((uint8_t)(data[0] + data[1]) == 0xFF && (uint8_t)(data[2] + data[3]) == 0xFF) {
-        return data[2];
-    }
-    return -1;
+    if (!read_32_bits(data)) return -1;
+    return validate_nec_frame(data);
 }