EoS Developer Documentation v0.1.0

Initialize the HAL subsystem for the current platform. Must be called before any other HAL function.

int ret = eos_hal_init();
if (ret != 0) { printf("HAL init failed: %d\n", ret); return ret; }

Deinitialize the HAL subsystem, releasing all resources.

Blocking delay for ms milliseconds. For RTOS tasks use eos_task_delay_ms() instead.

eos_gpio_write(13, true);
eos_delay_ms(500);
eos_gpio_write(13, false);

Get system tick count in milliseconds since eos_hal_init(). Wraps at UINT32_MAX (~49.7 days).

uint32_t start = eos_get_tick_ms();
do_work();
printf("Elapsed: %u ms\n", eos_get_tick_ms() - start);

Initialize a GPIO pin. Must be called before read/write/toggle on the pin.

eos_gpio_config_t led = {
    .pin = 13, .mode = EOS_GPIO_OUTPUT,
    .pull = EOS_GPIO_PULL_NONE, .speed = EOS_GPIO_SPEED_LOW
};
eos_gpio_init(&led);

Release a GPIO pin, resetting it to default state.

Set GPIO output pin high or low.

eos_gpio_write(13, true);  // LED on
eos_delay_ms(1000);
eos_gpio_write(13, false); // LED off

Read current state of a GPIO pin. Works for input and output pins.

eos_gpio_config_t btn = { .pin=2, .mode=EOS_GPIO_INPUT, .pull=EOS_GPIO_PULL_UP };
eos_gpio_init(&btn);
if (!eos_gpio_read(2)) printf("Button pressed!\n");

Toggle a GPIO output pin (high→low or low→high).

while (1) { eos_gpio_toggle(13); eos_delay_ms(500); } // 1 Hz blink

Attach interrupt callback to a GPIO pin on specified edge(s).

void on_btn(uint16_t pin, void *ctx) { *(int*)ctx += 1; }
int count = 0;
eos_gpio_set_irq(2, EOS_GPIO_EDGE_FALLING, on_btn, &count);

Initialize a UART port with baud rate, parity, and stop bits.

eos_uart_config_t uart = { .port=0, .baudrate=115200, .data_bits=8,
    .parity=EOS_UART_PARITY_NONE, .stop_bits=EOS_UART_STOP_1 };
eos_uart_init(&uart);

Write data to UART. Blocks until all bytes transmitted.

const char *msg = "Hello UART\r\n";
eos_uart_write(0, (const uint8_t *)msg, strlen(msg));

Read data from UART. Blocks until len bytes received or timeout expires.

Deinitialize UART port, releasing resources.

Register per-byte receive callback. Fires from ISR context.

Initialize SPI port with clock speed, mode (CPOL/CPHA 0-3), bits per word, and CS pin.

eos_spi_config_t spi = { .port=0, .clock_hz=1000000,
    .mode=EOS_SPI_MODE_0, .bits_per_word=8, .cs_pin=10 };
eos_spi_init(&spi);

Full-duplex SPI transfer. Either tx or rx may be NULL for half-duplex.

Write-only SPI transfer (discards received data).

Read-only SPI transfer (clocks out zeros).

Initialize I2C port with clock frequency and optional own address.

eos_i2c_config_t i2c = { .port=0, .clock_hz=400000, .own_addr=0 };
eos_i2c_init(&i2c);

Write data to I2C device at 7-bit address.

Read data from I2C device.

Write to a specific register on an I2C device (register address + data in one transaction).

Read from a specific register on an I2C device.

uint8_t who;
eos_i2c_read_reg(0, 0x68, 0x75, &who, 1); // MPU6050 WHO_AM_I
printf("WHO_AM_I = 0x%02X\n", who);

Initialize a hardware timer with period, auto-reload, and callback.

void tick(uint8_t id, void *ctx) { eos_gpio_toggle(13); }
eos_timer_config_t t = { .timer_id=0, .period_us=1000000,
    .auto_reload=true, .callback=tick };
eos_timer_init(&t);
eos_timer_start(0);

Start a previously initialized timer.

Stop a running timer. Can be restarted with eos_timer_start().

Get current timer counter value.

Globally disable interrupts. Pair with eos_irq_enable().

Re-enable globally disabled interrupts.

Register an ISR for a specific IRQ number with given priority.

Unregister an ISR for the specified IRQ.

Initialize/deinitialize the OTA subsystem.

Check if a firmware update is available at the given URL.

Begin OTA download to the inactive slot.

Write a firmware chunk. Call repeatedly until all data written.

Finalize OTA write. Pads and commits to flash.

Verify the downloaded image (CRC, SHA-256, signature).

Mark update slot as pending and trigger reboot.

Rollback to the previous firmware slot.

Get current OTA status: state, progress, active/update slot, versions.

Register progress callback: void (*)(uint8_t pct, void *ctx)

Initialize/deinitialize the sensor subsystem.

Register a sensor with ID, name, type, filter, sample interval, and read function.

int read_temp(uint8_t id, float *val) { *val = adc_to_celsius(adc_read(0)); return 0; }
eos_sensor_config_t cfg = { .id=0, .name="temp", .type=EOS_SENSOR_TEMPERATURE,
    .filter=EOS_FILTER_KALMAN, .filter_window=8, .sample_interval_ms=1000, .read_fn=read_temp };
eos_sensor_register(&cfg);

Read raw sensor value. Returns value, min, max, timestamp, valid flag.

Read filtered sensor value using configured filter (average, median, lowpass, Kalman).

Set calibration offset and scale for a sensor.

Automatically calibrate sensor using built-in algorithm.

Change filter type and window size at runtime.

Initialize power management. Config: ADC channel, battery full/empty voltages, divider ratio.

Enter a power mode: EOS_POWER_RUN, SLEEP, DEEP_SLEEP, or SHUTDOWN.

eos_power_set_wake_sources(EOS_WAKE_GPIO | EOS_WAKE_RTC);
eos_power_enter_mode(EOS_POWER_DEEP_SLEEP); // wakes on GPIO or RTC

Configure wake sources: EOS_WAKE_GPIO, TIMER, RTC, UART, BLE, USB, INTERRUPT (bitwise OR).

Get battery voltage in millivolts or percentage (0-100).

Get full battery info: voltage_mv, percentage, charging, charger_connected, current_ma, temperature_c.

Enable/disable power to individual peripherals (GPIO, UART, SPI, I2C, WiFi, BLE, etc.).

Set/get CPU frequency for dynamic voltage-frequency scaling.

Create a socket. EOS_NET_TCP or EOS_NET_UDP.

Connect a TCP socket to a remote address (ip + port).

Send data on a connected socket. Returns bytes sent.

Receive data. Returns bytes received or negative on error/timeout.

Server socket operations: bind to port, listen, accept connections.

Close a socket.

DNS resolve hostname to IP address.

HTTP GET request. Response contains status_code, body, body_len, content_type.

eos_http_response_t resp;
eos_http_get("http://api.example.com/data", &resp);
printf("Status: %d, Body: %.*s\n", resp.status_code, (int)resp.body_len, resp.body);
eos_http_response_free(&resp);

HTTP POST with body and content type.

Connect to MQTT broker. Config: broker_host, port, client_id, username, password, keepalive_sec.

eos_mqtt_config_t cfg = { .broker_host="mqtt.example.com", .broker_port=1883,
    .client_id="sensor01", .keepalive_sec=60 };
eos_mqtt_handle_t mqtt = eos_mqtt_connect(&cfg);
eos_mqtt_publish(mqtt, "sensors/temp", "23.5", 4, 1);

Publish a message to an MQTT topic with QoS 0, 1, or 2.

Subscribe to topic with callback: void (*)(const char *topic, const uint8_t *payload, size_t len, void *ctx)

Process MQTT events. Call periodically to handle incoming messages and keepalive.

Register a service for mDNS discovery.

Discover a service via mDNS.

Initialize GDB stub with UART or TCP transport.

EosGdbStub stub;
eos_gdb_init(&stub, EOS_GDB_TRANSPORT_UART);
eos_gdb_start(&stub, 115200); // baud rate for UART
// For TCP: eos_gdb_start(&stub, 3333); // port

Start listening for GDB connections. For UART: baud rate; for TCP: port number.

Stop GDB stub and disconnect.

Handle a debug exception — call from your fault handler.

Add/remove software breakpoints at memory address. Max 16 breakpoints.

Trigger a breakpoint programmatically (like BKPT instruction).

Check if a GDB client is connected.

Initialize core dump subsystem. Target: EOS_DUMP_TARGET_FLASH, UART, or RAM.

Capture crash state. Reasons: HARDFAULT, MEMFAULT, BUSFAULT, USAGEFAULT, ASSERT, WATCHDOG, STACK_OVF.

void HardFault_Handler(void) {
    EosCrashRegs regs;
    // ... populate regs from exception frame ...
    eos_coredump_capture(EOS_CRASH_HARDFAULT, &regs);
}

Save/load core dump to/from configured target. Magic: 0xC0DEDEAD.

Print formatted crash report to serial/stderr.

Check if dump exists, clear saved dump, or validate CRC32.