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

0x0017_constants/0x0017_constants.c

@@ -1,33 +1,98 @@
+/**
+ * @file 0x0017_constants.c
+ * @brief Constants: demonstrate #define and const with LCD1602 I2C display
+ * @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 #define macro constants and const-qualified variables.
+ * Initializes an LCD1602 display over I2C and prints constant values
+ * over UART in an infinite loop.
+ *
+ * Wiring:
+ *   GPIO2 (SDA) -> LCD1602 PCF8574 SDA
+ *   GPIO3 (SCL) -> LCD1602 PCF8574 SCL
+ *   3V3         -> LCD1602 VCC
+ *   GND         -> LCD1602 GND
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include "pico/stdlib.h"
 #include "hardware/i2c.h"
 #include "lcd_1602.h"
 
-#define FAV_NUM 42
-
-#define I2C_PORT i2c1
+/** @brief Macro constant for favorite number */
+#define FAV_NUM     42
+/** @brief I2C peripheral instance */
+#define I2C_PORT    i2c1
+/** @brief GPIO pin for I2C SDA */
 #define I2C_SDA_PIN 2
+/** @brief GPIO pin for I2C SCL */
 #define I2C_SCL_PIN 3
 
+/** @brief Const-qualified favorite number */
 const int OTHER_FAV_NUM = 1337;
 
-int main(void) {
-    stdio_init_all();
-
+/**
+ * @brief Initialize I2C bus and LCD1602 display
+ *
+ * @details Configures I2C1 at 100kHz on GPIO2/3, initializes the
+ *          LCD via PCF8574 at address 0x27, and writes two lines.
+ *
+ * @retval None
+ */
+static void init_i2c_and_lcd(void) {
     i2c_init(I2C_PORT, 100000);
     gpio_set_function(I2C_SDA_PIN, GPIO_FUNC_I2C);
     gpio_set_function(I2C_SCL_PIN, GPIO_FUNC_I2C);
     gpio_pull_up(I2C_SDA_PIN);
     gpio_pull_up(I2C_SCL_PIN);
-
     lcd_i2c_init(I2C_PORT, 0x27, 4, 0x08);
+}
 
+/**
+ * @brief Write greeting text to the LCD display
+ *
+ * @details Sets cursor to line 0 and writes "Reverse", then sets
+ *          cursor to line 1 and writes "Engineering".
+ *
+ * @retval None
+ */
+static void write_lcd_greeting(void) {
     lcd_set_cursor(0, 0);
     lcd_puts("Reverse");
     lcd_set_cursor(1, 0);
     lcd_puts("Engineering");
+}
 
+int main(void) {
+    stdio_init_all();
+    init_i2c_and_lcd();
+    write_lcd_greeting();
     while (true) {
         printf("FAV_NUM: %d\r\n", FAV_NUM);
         printf("OTHER_FAV_NUM: %d\r\n", OTHER_FAV_NUM);

0x0017_constants/lcd_1602.c

@@ -31,21 +31,37 @@
 #include <string.h>
 #include <stdint.h>
 
+/** @brief I2C instance pointer for the LCD */
 static i2c_inst_t *lcd_i2c = NULL;
+/** @brief I2C address of the PCF8574 backpack */
 static uint8_t lcd_addr = 0x27;
+/** @brief Bit shift for 4-bit nibble position */
 static int lcd_nibble_shift = 4;
+/** @brief PCF8574 bit mask controlling the backlight */
 static uint8_t lcd_backlight_mask = 0x08;
 
-/* PCF8574 -> LCD control pins */
+/** @brief PCF8574 bit mask for Register Select */
 #define PIN_RS 0x01
+/** @brief PCF8574 bit mask for Read/Write */
 #define PIN_RW 0x02
+/** @brief PCF8574 bit mask for Enable */
 #define PIN_EN 0x04
 
+/**
+ * @brief Write one raw byte to the PCF8574 expander over I2C
+ *
+ * @param data Output byte to send to the expander
+ */
 static void pcf_write_byte(uint8_t data) {
     if (!lcd_i2c) return;
     i2c_write_blocking(lcd_i2c, lcd_addr, &data, 1, false);
 }
 
+/**
+ * @brief Toggle EN to latch a nibble into the LCD controller
+ *
+ * @param data Current control/data bus byte (with RS and backlight already set)
+ */
 static void pcf_pulse_enable(uint8_t data) {
     pcf_write_byte(data | PIN_EN);
     sleep_us(1);
@@ -53,6 +69,12 @@ static void pcf_pulse_enable(uint8_t data) {
     sleep_us(50);
 }
 
+/**
+ * @brief Write one 4-bit nibble to the LCD
+ *
+ * @param nibble Lower 4 bits to write
+ * @param mode   0 for command, non-zero for character data
+ */
 static void lcd_write4(uint8_t nibble, uint8_t mode) {
     uint8_t data = (nibble & 0x0F) << lcd_nibble_shift;
     data |= mode ? PIN_RS : 0;
@@ -60,18 +82,37 @@ static void lcd_write4(uint8_t nibble, uint8_t mode) {
     pcf_pulse_enable(data);
 }
 
+/**
+ * @brief Send one full 8-bit command/data value as two nibbles
+ *
+ * @param value Byte to send to the LCD
+ * @param mode  0 for command, non-zero for character data
+ */
 static void lcd_send(uint8_t value, uint8_t mode) {
     lcd_write4((value >> 4) & 0x0F, mode);
     lcd_write4(value & 0x0F, mode);
 }
 
-void lcd_i2c_init(i2c_inst_t *i2c, uint8_t pcf_addr, int nibble_shift, uint8_t backlight_mask) {
+/**
+ * @brief Store LCD driver configuration in module-level state
+ *
+ * @param i2c            Pointer to the I2C instance
+ * @param pcf_addr       7-bit PCF8574 address
+ * @param nibble_shift   Bit shift for 4-bit nibbles
+ * @param backlight_mask Backlight control bit mask
+ */
+static void lcd_store_config(i2c_inst_t *i2c, uint8_t pcf_addr,
+                             int nibble_shift, uint8_t backlight_mask) {
     lcd_i2c = i2c;
     lcd_addr = pcf_addr;
     lcd_nibble_shift = nibble_shift;
     lcd_backlight_mask = backlight_mask;
+}
 
-    // Follow init sequence for HD44780 in 4-bit mode
+/**
+ * @brief Execute the HD44780 4-bit mode power-on reset sequence
+ */
+static void lcd_hd44780_reset(void) {
     lcd_write4(0x03, 0);
     sleep_ms(5);
     lcd_write4(0x03, 0);
@@ -80,21 +121,28 @@ void lcd_i2c_init(i2c_inst_t *i2c, uint8_t pcf_addr, int nibble_shift, uint8_t b
     sleep_us(150);
     lcd_write4(0x02, 0);
     sleep_us(150);
+}
 
-    // Function set: 4-bit, 2 lines
+/**
+ * @brief Send post-reset configuration commands to the HD44780
+ *
+ * Sets 4-bit mode with 2 display lines, turns the display on with
+ * cursor hidden, clears the screen, and selects left-to-right entry mode.
+ */
+static void lcd_hd44780_configure(void) {
     lcd_send(0x28, 0);
-
-    // Display on, cursor off
     lcd_send(0x0C, 0);
-
-    // Clear
     lcd_send(0x01, 0);
     sleep_ms(2);
-
-    // Entry mode set
     lcd_send(0x06, 0);
 }
 
+void lcd_i2c_init(i2c_inst_t *i2c, uint8_t pcf_addr, int nibble_shift, uint8_t backlight_mask) {
+    lcd_store_config(i2c, pcf_addr, nibble_shift, backlight_mask);
+    lcd_hd44780_reset();
+    lcd_hd44780_configure();
+}
+
 void lcd_clear(void) {
     lcd_send(0x01, 0);
     sleep_ms(2);
@@ -102,13 +150,11 @@ void lcd_clear(void) {
 
 void lcd_set_cursor(int line, int position) {
     const uint8_t row_offsets[] = {0x00, 0x40};
-
     if (line > 1) line = 1;
     lcd_send(0x80 | (position + row_offsets[line]), 0);
 }
 
 void lcd_puts(const char *s) {
-    while (*s) {
+    while (*s)
         lcd_send((uint8_t)*s++, 1);
-    }
 }