C Programming Refresher¶

#include <stdio.h>        // Include the standard I/O library (for printf)

int main(void) {          // Every C program starts here — the "main" function
    printf("Hello, World!\n");   // Print a message to the screen
    return 0;             // Tell the OS: "everything went OK"
}

// This is a single-line comment
// The compiler ignores comments — they're for humans

/* This is a multi-line comment
   Useful for longer explanations
   The compiler ignores everything between /* and */

// USE COMMENTS TO:
// 1. Explain WHY you're doing something (not WHAT — the code shows what)
// 2. Mark sections of your code
// 3. Temporarily disable code while debugging

int age = 25;           // "age" is a box that holds a whole number (integer)
float temperature = 36.6;  // "temperature" holds a decimal number
char grade = 'A';       // "grade" holds a single character

// ✅ Good names — descriptive, clear
int sensor_count = 0;
float battery_voltage = 3.7;
uint8_t led_brightness = 128;

// ❌ Bad names — unclear, too short
int x = 0;          // what is x?
float f = 3.7;      // what does f mean?
uint8_t n = 128;    // n could be anything

// ❌ Invalid names — C has rules
int 2nd_reading = 0;    // can't start with a number
int my-var = 0;         // can't use hyphens (use underscores)
int float = 0;          // can't use C keywords (float is a type name)

int count = 0;       // count is 0
count = 5;           // now count is 5 — we overwrote the old value
count = count + 1;   // now count is 6 — we added 1 to the old value

// Shorthand versions (very common):
count += 1;          // same as count = count + 1
count++;             // same as count = count + 1 (add 1)
count--;             // same as count = count - 1 (subtract 1)
count *= 2;          // same as count = count * 2

#include <stdio.h>

// Step 1: DEFINE the function (write the recipe)
// "int" = return type (what comes out)
// "a" and "b" = parameters (what goes in)
int add(int a, int b) {
    int result = a + b;    // do the calculation
    return result;          // send the answer back
}

// Step 2: CALL the function (use the recipe)
int main(void) {
    int sum = add(3, 4);    // call add with 3 and 4 → sum becomes 7
    printf("3 + 4 = %d\n", sum);   // prints: 3 + 4 = 7

    // You can call it multiple times with different inputs
    int another = add(10, 20);
    printf("10 + 20 = %d\n", another);  // prints: 10 + 20 = 30

    return 0;
}

void greet(const char *name) {    // void = "nothing comes out"
    printf("Hello, %s!\n", name);  // just print, no return
}

// Call it:
greet("Rajath");    // prints: Hello, Rajath!
greet("ESP32");     // prints: Hello, ESP32!

gpio_set_level(2, 1);           // Turn on LED on GPIO 2
gpio_set_level(2, 0);           // Turn off LED on GPIO 2
vTaskDelay(pdMS_TO_TICKS(500)); // Wait 500ms

int age = 25;
float temp = 36.6f;
char grade = 'A';
char name[] = "ESP32";

// Format specifiers start with % and are replaced by the variable value
printf("I am %d years old\n", age);        // %d → integer → "I am 25 years old"
printf("Temperature: %.1f°C\n", temp);     // %.1f → float with 1 decimal → "Temperature: 36.6°C"
printf("Grade: %c\n", grade);              // %c → single character → "Grade: A"
printf("Device: %s\n", name);              // %s → string → "Device: ESP32"

// ── Normal C (desktop application) ──
int count = 0;
unsigned int timestamp = 0;
char initial = 'A';
unsigned char byte_val = 255;
float temperature = 25.5;

// ── Embedded C (ESP-IDF firmware) ──
int32_t count = 0;           // guaranteed 32-bit signed
uint32_t timestamp = 0;      // guaranteed 32-bit unsigned
char initial = 'A';          // char is fine for ASCII
uint8_t byte_val = 255;      // guaranteed 8-bit unsigned
float temperature = 25.5f;   // float with 'f' suffix — no double promotion

// ❌ Dangerous — int size varies
int sensor_value = 0;
if (sensor_value > 32767) {  // works on 32-bit, overflows on 16-bit int!
    handle_overflow();
}

// ✅ Safe — exact width guaranteed
int32_t sensor_value = 0;
if (sensor_value > 32767) {  // always works correctly
    handle_overflow();
}

// ❌ Dangerous — unsigned int may be 16-bit on some platforms
unsigned int address = 0x40000000;  // overflow if int is 16-bit!

// ✅ Safe — uint32_t is always 32-bit
uint32_t address = 0x40000000;      // always correct

#include "esp_err.h"
esp_err_t result = ESP_OK;      // int32_t — error codes (ESP_OK, ESP_FAIL, etc.)

#include "driver/gpio.h"
gpio_num_t led = GPIO_NUM_2;    // enum — GPIO pin number

#include "freertos/FreeRTOS.h"
TickType_t delay = pdMS_TO_TICKS(100);  // uint32_t — FreeRTOS tick count
TaskHandle_t task_handle = NULL;         // void * — opaque task handle
BaseType_t priority = 1;                 // long — task priority (use int32_t in your code)

#include <inttypes.h>  // provides PRId32, PRIu32, etc.

uint32_t timestamp = 1713427200;
printf("Timestamp: %" PRIu32 "\n", timestamp);  // portable across all platforms

// Arithmetic
int sum = a + b;
int diff = a - b;
int product = a * b;
int quotient = a / b;   // integer division — 7/2 = 3
int remainder = a % b;  // modulo — 7%2 = 1

// Comparison (returns 0 or 1)
if (a == b) { /* equal */ }
if (a != b) { /* not equal */ }
if (a > b)  { /* greater than */ }
if (a <= b) { /* less than or equal */ }

// Logical
if (a > 0 && b > 0) { /* both true */ }
if (a > 0 || b > 0) { /* at least one true */ }
if (!flag) { /* flag is false */ }

// Bitwise (very common in embedded — setting/clearing register bits)
uint8_t reg = 0x00;
reg |= (1 << 3);    // set bit 3
reg &= ~(1 << 3);   // clear bit 3
reg ^= (1 << 3);    // toggle bit 3
if (reg & (1 << 3)) { /* bit 3 is set */ }

int sensor_value = 512;

if (sensor_value > 800) {
    printf("High\n");
} else if (sensor_value > 200) {
    printf("Normal\n");
} else {
    printf("Low\n");
}

typedef enum {
    MODE_STA,
    MODE_AP,
    MODE_STA_AP
} wifi_mode_t;

wifi_mode_t mode = MODE_STA;

switch (mode) {
    case MODE_STA:
        printf("Station mode\n");
        break;
    case MODE_AP:
        printf("Access Point mode\n");
        break;
    case MODE_STA_AP:
        printf("Combined mode\n");
        break;
    default:
        printf("Unknown mode\n");
        break;
}

// for loop — used when you know the iteration count
for (int i = 0; i < 10; i++) {
    printf("i = %d\n", i);
}

// while loop — used when condition determines termination
int retries = 0;
while (!wifi_connected() && retries < 5) {
    retry_connect();
    retries++;
}

// infinite loop — the main pattern in embedded firmware
while (1) {
    // Super loop: read sensors, process, act
    read_sensors();
    process_data();
    vTaskDelay(pdMS_TO_TICKS(100));
}

// Function declaration (prototype) — common in header files
int add(int a, int b);

// Function definition
int add(int a, int b) {
    return a + b;
}

// void return — function does something but returns nothing
void blink_led(int gpio, int delay_ms) {
    gpio_set_level(gpio, 1);
    vTaskDelay(pdMS_TO_TICKS(delay_ms));
    gpio_set_level(gpio, 0);
}

// static — limits scope to this translation unit (.c file)
static void helper_function(void) {
    // only callable from within this file
}

// const — promises not to modify the parameter
void print_label(const char *label) {
    printf("%s\n", label);
    // label[0] = 'X';  // compiler error — can't modify const
}

// Array
int readings[5] = {100, 200, 300, 400, 500};
int first = readings[0];  // 100

// C strings are char arrays terminated by '\0'
char name[] = "ESP32";    // compiler adds '\0' automatically
// name is {'E', 'S', 'P', '3', '2', '\0'} — 6 bytes

// String operations (from string.h)
#include <string.h>
int len = strlen(name);              // 5
int cmp = strcmp(name, "ESP32");     // 0 means equal
char *found = strstr(name, "SP");    // pointer to "SP32"

// printf format strings
printf("Device: %s, Value: %d, Temp: %.1f\n", name, readings[0], 25.5);

int value = 42;
int *ptr = &value;   // ptr holds the ADDRESS of value

printf("Value: %d\n", value);     // 42
printf("Address: %p\n", (void *)ptr);
printf("Dereference: %d\n", *ptr); // 42 — *ptr reads the value at the address

*ptr = 100;                        // write through the pointer
printf("Value now: %d\n", value);  // 100 — value was changed via pointer

int data[4] = {10, 20, 30, 40};

// Array name decays to a pointer to the first element
int *p = data;          // same as &data[0]
printf("%d\n", *p);     // 10
printf("%d\n", *(p+1)); // 20 — pointer arithmetic
printf("%d\n", p[2]);   // 30 — pointer[index] is equivalent to *(pointer + index)

typedef struct {
    float temperature;
    float humidity;
} sensor_data_t;

sensor_data_t reading = {25.5, 60.0};
sensor_data_t *ptr = &reading;

// Access struct members through pointer using ->
printf("Temp: %.1f\n", ptr->temperature);   // 25.5
printf("Humidity: %.1f\n", ptr->humidity);  // 60.0

// Equivalent to:
printf("Temp: %.1f\n", (*ptr).temperature); // 25.5

void create_task(TaskHandle_t *out_handle) {
    // Function writes a handle back through the caller's pointer
    TaskHandle_t handle = xTaskCreate(...);
    *out_handle = handle;  // write the handle back
}

// Caller:
TaskHandle_t my_task;
create_task(&my_task);  // passes address of my_task
// my_task now contains the created handle

// Define a struct type
typedef struct {
    int gpio_num;
    int brightness;
    bool is_on;
} led_config_t;

// Initialize
led_config_t led = {
    .gpio_num = 2,
    .brightness = 128,
    .is_on = true
};

// Access members
printf("GPIO: %d, Brightness: %d\n", led.gpio_num, led.brightness);

// Pass to function
void configure_led(const led_config_t *config) {
    gpio_set_direction(config->gpio_num, GPIO_MODE_OUTPUT);
    if (config->is_on) {
        gpio_set_level(config->gpio_num, 1);
    }
}

typedef struct {
    float temperature;
    float humidity;
} dht_reading_t;

typedef struct {
    dht_reading_t sensor;
    char device_id[16];
    uint32_t timestamp;
} telemetry_t;

telemetry_t data = {
    .sensor = { .temperature = 25.5, .humidity = 60.0 },
    .device_id = "XIAO-S3-01",
    .timestamp = 1713427200
};

printf("Temp: %.1f\n", data.sensor.temperature);

typedef enum {
    ESP_OK          = 0,   // Success
    ESP_FAIL        = -1,  // Generic failure
    ESP_ERR_NO_MEM  = 0x101,  // Out of memory
    ESP_ERR_TIMEOUT = 0x102,  // Operation timed out
} esp_err_t;

esp_err_t result = wifi_connect();
if (result != ESP_OK) {
    printf("Connection failed: 0x%x\n", result);
}

// Object-like macro — constant replacement
#define LED_GPIO 2
#define MAX_RETRIES 3

// Function-like macro
#define MIN(a, b) ((a) < (b) ? (a) : (b))
#define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0]))

// Conditional compilation
#define CONFIG_ENABLE_WIFI 1

#if CONFIG_ENABLE_WIFI
    void wifi_init(void) { /* ... */ }
#endif

// ESP-IDF logging macros (you'll use these constantly)
#include "esp_log.h"
#define TAG "MAIN"

ESP_LOGI(TAG, "Temperature: %.1f", temp);   // Info
ESP_LOGW(TAG, "Low battery: %d%%", level);  // Warning
ESP_LOGE(TAG, "Sensor read failed!");        // Error

const int max_retries = 3;
// max_retries = 5;  // ❌ compiler error — can't modify const

// Common use: function parameters that shouldn't be changed
void print_sensor(const sensor_data_t *data) {
    printf("Temp: %.1f\n", data->temperature);
    // data->temperature = 0;  // ❌ compiler error — data is const
}

// Common use: const pointers — pointer can't change what it points to
const char *device_name = "ESP32-S3";  // can't modify the string
// device_name[0] = 'X';  // ❌ compiler error

// ❌ WITHOUT volatile — the compiler optimizes this to an infinite loop
bool flag = false;

void isr_handler(void) {
    flag = true;  // set by interrupt — happens asynchronously
}

while (!flag) {
    // Compiler sees: flag is never modified in this loop
    // It optimizes to: while(true) — your program hangs forever!
}

// ✅ WITH volatile — the compiler reads flag from memory every iteration
volatile bool flag = false;

void isr_handler(void) {
    flag = true;  // interrupt sets it
}

while (!flag) {
    // Compiler MUST re-read flag each time — loop exits when ISR fires
}

// Memory-mapped register — hardware changes this without CPU involvement
volatile uint32_t *gpio_input = (volatile uint32_t *)0x6000403C;
uint32_t pin_state = *gpio_input;  // always reads the real hardware value

// FreeRTOS task notification — another task can modify this at any time
volatile TaskHandle_t x_notify_task = NULL;

// Shared flag between ISR and main task
volatile bool s_wifi_connected = false;

void wifi_event_handler(void *arg, esp_event_base_t base,
                         int32_t id, void *event_data) {
    if (id == WIFI_EVENT_STA_CONNECTED) {
        s_wifi_connected = true;  // ISR / event callback sets flag
    }
}

// Read-only register — you can't write to it, but hardware can change it
const volatile uint32_t *status_reg = (const volatile uint32_t *)0x60004000;
uint32_t val = *status_reg;    // read current value (hardware may have changed it)
// *status_reg = 0;           // ❌ can't write — it's const

// Without static — count resets to 0 every call
void counter_bad(void) {
    int count = 0;      // created fresh on the stack each call
    count++;
    printf("Count: %d\n", count);  // always prints 1
}

// With static — count persists across calls
void counter_good(void) {
    static int count = 0;  // initialized ONCE, lives for the entire program
    count++;               // value carries over from last call
    printf("Count: %d\n", count);  // 1, 2, 3, 4, ...
}

// Pattern 1: One-time initialization flag
void init_wifi(void) {
    static bool initialized = false;  // persists across calls
    if (initialized) {
        ESP_LOGI(TAG, "WiFi already initialized");
        return;  // skip re-initialization
    }
    // ... do expensive init ...
    initialized = true;
}

// Pattern 2: Persistent state in a task
void sensor_task(void *param) {
    static uint32_t sample_count = 0;  // survives across loop iterations
    while (1) {
        read_sensor();
        sample_count++;
        if (sample_count % 100 == 0) {
            ESP_LOGI(TAG, "Collected %" PRIu32 " samples", sample_count);
        }
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

// Pattern 3: File-scope static (we already covered this)
// Limits visibility to this .c file — other files can't access it
static const char *TAG = "MAIN";  // only visible in this translation unit
static int s_gpio_num = 0;       // "s_" prefix is an ESP-IDF convention for statics

#define LED_GPIO      2
#define MAX_RETRIES   3
#define TIMEOUT_MS    5000

const uint8_t led_gpio = 2;
const int max_retries = 3;
const uint32_t timeout_ms = 5000;

typedef enum {
    LED_GPIO    = 2,
    MAX_RETRIES = 3,
    TIMEOUT_MS  = 5000,
} app_config_t;

// ESP-IDF uses #define for most constants (generated by menuconfig)
#define CONFIG_ESP_WIFI_SSID "MyNetwork"
#define CONFIG_ESP_WIFI_PASSWORD "MyPassword"

// ESP-IDF uses enum for error codes and modes
typedef enum {
    ESP_OK = 0,
    ESP_FAIL = -1,
    // ...
} esp_err_t;

// ESP-IDF uses static const for strings (not #define)
static const char *TAG = "MAIN";  // NOT: #define TAG "MAIN"

// Stack — automatic, fast, limited size (typically 4-8KB per FreeRTOS task)
void stack_example(void) {
    int local_var = 42;           // on the stack
    sensor_data_t data = {0};     // on the stack
    // freed automatically when function returns
}

// Heap — manual allocation, larger pool, must free
void heap_example(void) {
    sensor_data_t *data = malloc(sizeof(sensor_data_t));
    if (data == NULL) {
        ESP_LOGE(TAG, "Out of memory!");
        return;
    }
    data->temperature = 25.5;
    // ... use data ...
    free(data);  // MUST free — no garbage collector in C!
}

// ── Normal C (desktop) ──
// Program runs once and exits
int main(int argc, char *argv[]) {
    printf("Hello!\n");
    process_data();
    return 0;  // OS cleans up everything
}

// ── Embedded C (ESP-IDF) ──
// Program runs forever — there is no OS to return to
void app_main(void) {
    init_hardware();

    while (1) {  // super loop — or use FreeRTOS tasks
        read_sensors();
        process_data();
        actuate_outputs();
        vTaskDelay(pdMS_TO_TICKS(100));  // yield CPU — don't busy-wait!
    }
    // never reaches here
}

// ── Normal C (desktop) ──
// Print error and exit — OS handles cleanup
FILE *f = fopen("data.txt", "r");
if (f == NULL) {
    perror("Failed to open file");
    exit(1);  // just quit
}

// ── Embedded C (ESP-IDF) ──
// Must handle error and continue — there is no OS to exit to
esp_err_t ret = i2c_master_init();
if (ret != ESP_OK) {
    ESP_LOGE(TAG, "I2C init failed: %s", esp_err_to_name(ret));
    // Options: retry, use fallback, or restart the device
    esp_restart();  // last resort — reboot the chip
}

// ── Normal C (desktop) ──
// Generous heap — allocate freely, OS reclaims on exit
char *buffer = malloc(1024 * 1024);  // 1 MB — no problem
if (buffer) { /* use it */ }

// ── Embedded C (ESP-IDF) ──
// Limited heap — ESP32-S3 has ~320KB internal + 8MB PSRAM
// Must be frugal and always check for NULL
char *buffer = malloc(256);  // small allocation
if (buffer == NULL) {
    ESP_LOGE(TAG, "Out of memory!");
    return;  // can't proceed — handle gracefully
}
// ... use buffer ...
free(buffer);  // ALWAYS free when done
buffer = NULL; // prevent use-after-free

// ── Normal C (desktop) ──
// Standard I/O — keyboard, screen, files
printf("Enter value: ");
scanf("%d", &value);
fprintf(fp, "Result: %d\n", value);

// ── Embedded C (ESP-IDF) ──
// Hardware I/O — GPIO, I2C, SPI, UART
gpio_set_level(LED_GPIO, 1);                    // digital output
int adc_val = adc_read(ADC_CHANNEL_0);           // analog input
i2c_write(I2C_NUM_0, OLED_ADDR, &data, len);     // I2C communication
uart_write_bytes(UART_NUM_0, msg, strlen(msg));  // serial output

// ── Normal C (desktop) ──
// OS-managed sleep — imprecise, minimum ~1ms granularity
#include <unistd.h>
usleep(100000);  // sleep 100ms — not precise

// ── Embedded C (ESP-IDF) ──
// FreeRTOS delays — precise, task-aware
vTaskDelay(pdMS_TO_TICKS(100));  // delay 100ms, yields CPU to other tasks
// NEVER use busy-wait loops for timing!

// ── Normal C (desktop) ──
// POSIX threads — OS handles scheduling
#include <pthread.h>
pthread_t thread;
pthread_create(&thread, NULL, worker_fn, NULL);

// ── Embedded C (ESP-IDF) ──
// FreeRTOS tasks — deterministic, priority-based
TaskHandle_t task_handle;
xTaskCreatePinnedToCore(
    worker_task,       // function
    "worker",          // name
    4096,              // stack size in bytes
    NULL,              // parameter
    1,                 // priority
    &task_handle,      // handle output
    1                  // core 1 (ESP32-S3 is dual-core!)
);

#include <stdio.h>     // angle brackets → system/library headers
#include "my_sensor.h"  // quotes → your own project headers

// ── sensor.h — declare what's available ──
#ifndef SENSOR_H          // include guard — prevent double inclusion
#define SENSOR_H

typedef struct {
    float temperature;
    float humidity;
} sensor_data_t;

sensor_data_t sensor_read(void);       // function prototype
void sensor_init(int port);            // function prototype

#endif // SENSOR_H

// ── sensor.c — implement the functions ──
#include "sensor.h"        // include our own header
#include <stdio.h>         // for printf

static int s_port = 0;     // file-private variable — only sensor.c can see it

void sensor_init(int port) {
    s_port = port;
    printf("Sensor on port %d\n", port);
}

sensor_data_t sensor_read(void) {
    sensor_data_t data = {25.5, 60.0};  // simulated reading
    return data;
}

// ── main.c — use the sensor module ──
#include "sensor.h"        // now main.c knows about sensor_data_t and sensor_read
#include <stdio.h>

int main(void) {
    sensor_init(1);
    sensor_data_t reading = sensor_read();
    printf("Temp: %.1f\n", reading.temperature);
    return 0;
}

// ── main/sensor.h ──
#ifndef SENSOR_H
#define SENSOR_H

#include "driver/i2c.h"       // ESP-IDF driver header

typedef struct {
    float temperature;
    float humidity;
} sensor_data_t;

esp_err_t sensor_init(i2c_port_t port);          // returns esp_err_t, not int
esp_err_t sensor_read(sensor_data_t *out_data);  // output via pointer (ESP-IDF pattern)

#endif // SENSOR_H

// ── main/sensor.c ──
#include "sensor.h"
#include "esp_log.h"

static const char *TAG = "SENSOR";      // ESP-IDF convention: static const for TAG
static i2c_port_t s_i2c_port = 0;      // "s_" prefix = static (file-private)

esp_err_t sensor_init(i2c_port_t port) {
    s_i2c_port = port;
    ESP_LOGI(TAG, "Sensor initialized on I2C port %d", port);
    return ESP_OK;
}

esp_err_t sensor_read(sensor_data_t *out_data) {
    if (out_data == NULL) return ESP_ERR_INVALID_ARG;
    // Read from I2C hardware...
    out_data->temperature = 25.5f;
    out_data->humidity = 60.0f;
    return ESP_OK;
}

// ── main/main.c ──
#include "sensor.h"
#include "esp_log.h"

static const char *TAG = "MAIN";

void app_main(void) {
    ESP_ERROR_CHECK(sensor_init(I2C_NUM_0));

    while (1) {
        sensor_data_t reading = {0};
        esp_err_t ret = sensor_read(&reading);
        if (ret == ESP_OK) {
            ESP_LOGI(TAG, "Temp: %.1f°C, Hum: %.1f%%",
                     reading.temperature, reading.humidity);
        }
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

#ifndef SENSOR_H       // "if SENSOR_H is NOT defined, process this file"
#define SENSOR_H       // "now SENSOR_H IS defined"
// ... all your declarations ...
#endif // SENSOR_H     // end of guard

// Define a function pointer type
typedef void (*event_handler_t)(int event_id, void *event_data);

// A function that matches the signature
void wifi_event_handler(int event_id, void *event_data) {
    printf("WiFi event: %d\n", event_id);
}

// Register the callback
void register_handler(event_handler_t handler) {
    // Store handler, call it later when event occurs
    handler(WIFI_EVENT_CONNECTED, NULL);
}

// Usage
register_handler(wifi_event_handler);

esp_err_t ret = nvs_flash_init();
if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
    ESP_ERROR_CHECK(nvs_flash_erase());
    ret = nvs_flash_init();
}
ESP_ERROR_CHECK(ret);  // aborts if ret != ESP_OK

// 1. Get default configuration
gpio_config_t io_conf = {
    .pin_bit_mask = (1ULL << LED_GPIO),
    .mode = GPIO_MODE_OUTPUT,
    .pull_up_en = GPIO_PULLUP_DISABLE,
    .pull_down_en = GPIO_PULLDOWN_DISABLE,
    .intr_type = GPIO_INTR_DISABLE,
};

// 2. Apply configuration
gpio_config(&io_conf);

// 3. Use the peripheral
gpio_set_level(LED_GPIO, 1);

gpio_num_t button_gpio = GPIO_NUM_9;
gpio_install_isr_service(0);
gpio_isr_handler_add(button_gpio, button_isr, NULL);