From ece6aef3b4404879112288665408aaf58dd27c3a Mon Sep 17 00:00:00 2001
From: webbrain-one <295484252+webbrain-one@users.noreply.github.com>
Date: Wed, 5 Aug 2026 00:56:15 +0300
Subject: [PATCH] docs: add README

---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..350c8c2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+
+
+# ubx_parser
+
+## Overview
+`ubx_parser` is a lightweight, embedded C library designed to parse binary UBX protocol messages from u-blox NEO-M8 series GNSS receivers. Built for ARM Cortex-M microcontrollers, it provides a robust, interrupt-driven UART reception pipeline, ring-buffered data handling, CRC validation, and structured C type conversions for common navigation messages.
+
+## Features
+- **Full UBX Framing**: Automatic sync-byte detection (`0xB5 0x62`), header parsing, and payload extraction
+- **Interrupt-Driven Reception**: Hardware UART ISR queues bytes into a lock-free ring buffer
+- **State Machine Parser**: Handles partial packets, buffer underflows, and malformed data gracefully
+- **Fletcher Checksum Validation**: Verifies `CK_A` and `CK_B` fields per u-blox specification
+- **Structured Data Conversion**: Zero-overhead mapping of raw payloads to strongly-typed C structs
+- **FreeRTOS Ready**: Includes a sample task wrapper for asynchronous message processing
+
+## Supported UBX Messages
+| Message ID | Class | Description |
+|:---:|:---:|:---|
+| `NAV-PVT` | `0x01` | Position, Velocity, Time (UTC, 3D fix, speed, heading, DOP) |
+| `NAV-ATT` | `0x01` | Attitude (Roll, Pitch, Heading with accuracies) |
+| `NAV-DOP` | `0x01` | Dilution of Precision (G/P/T/V/H/N/E DOP) |
+| `NAV-ODO` | `0x01` | Odometer (Traveled distance, total distance, accuracy) |
+
+## Installation & Setup
+This library is intended for integration into STM32CubeIDE/STM32CubeMX projects running FreeRTOS.
+
+1. **Copy Source Files**  
+   Add `neo_m8_*.c`, `neo_m8_*.h`, `ringbuffer_char.c`, and `ringbuffer_char.h` to your project source tree.
+
+2. **Configure USART in CubeMX**  
+   - Enable the UART connected to your GPS module (e.g., `UART6`)
+   - Set baud rate to match your GNSS module (typically `9600` or `38400`)
+   - Enable **RX Interrupt**
+   - Generate code
+
+3. **Link Interrupt Handler**  
+   Ensure the GPS UART's IRQ handler (e.g., `USART6_IRQHandler`) is routed to the provided `neo_m8_gps.c` implementation. Update the HAL handle name (`huart6`) and IRQ name (`USART6_IRQn`) if your UART differs.
+
+4. **Integrate with FreeRTOS**  
+   Include `neo_m8_app.h` and create a FreeRTOS task that calls `GPSTask(NULL)` or manually invoke the parsing API from your application loop.
+
+## Usage Example
+```c
+#include "neo_m8_gps.h"
+#include "neo_m8_conversion.h"
+#include "neo_m8_ubx_structs.h"
+
+ubx_nav_pvt_msg_t navPvt;
+
+void GPS_Task(void const * argument)
+{
+    // Initialize ring buffer and enable UART RX interrupts
+    neoInit();
+
+    for (;;) {
+        // Poll state machine to extract complete UBX packets
+        if (neoRetrieveMsg() == UBX_NEW_DATA) {
+            // Check message class and ID
+            if (neoGetMsgClass() == UBX_MSG_CLASS_NAV && 
+                neoGetMsgId() == UBX_MSG_ID_NAV_PVT) {
+                
+                // Parse raw payload into structured data
+                UBXUpdate_NAV_PVT(&navPvt);
+                
+                // Example: Print latitude/longitude (scaled by 1e7 per u-blox spec)
+                // printf("Lat: %.7f, Lon: %.7f\n", 
+                //        (double)navPvt.lat / 1e7, 
+                //        (double)navPvt.lon / 1e7);
+            }
+        }
+        osDelay(10); // Yield to RTOS
+    }
+}
+```
+
+## Architecture & Design
+- **`ringbuffer_char.c/h`**: Thread-safe, power-of-two sized circular buffer for high-throughput UART data ingestion.
+- **`neo_m8_ubx_checksum.h`**: Implements the 8-bit Fletcher algorithm used by u-blox for frame validation.
+- **`neo_m8_messages.h`**: Constants for UBX class IDs, message IDs, and sync bytes.
+- **`neo_m8_gps.c/h`**: Core driver. Manages the decode state machine (`UBX_LOOKING_FOR_SYNC` → `UBX_BUILDING_MSG_INFOS` → `UBX_CHECKING_CRC`), handles ring buffer operations, and exposes retrieval APIs.
+- **`neo_m8_conversion.c/h`**: Byte-level parsers that map raw payload offsets to C struct members. Handles little-endian multi-byte fields and bit-masked flags.
+- **`neo_m8_ubx_structs.h`**: Strongly-typed representations of UBX NAV messages, mirroring the official u-blox protocol specification.
+- **`neo_m8_app.c/h`**: Example FreeRTOS task demonstrating integration and periodic polling.
+
+## Dependencies
+- **FreeRTOS**: For task scheduling and `osDelay()` (CMSIS-OS v1 API)
+- **STM32 HAL**: `usart.h`, `stm32xxxx_hal_uart.h` for UART transmission/reception
+- **Standard C Library**: `<stdint.h>`, `<stdbool.h>`, `<string.h>`, `<stdio.h>`
+
+## Notes & Limitations
+- Max payload size is hardcoded to `172` bytes (sufficient for all supported NAV messages)
+- Ring buffer size is fixed at `2048` bytes (`RING_BUFFER_SIZE` in `ringbuffer_char.h`)
+- UART handle and IRQ macros (`huart6`, `USART6_IRQn`) may need adjustment for your target board
+- Bitfield parsing in `UBX_Parse_Raw_To_NAV_PVT` assumes u-blox NEO-M8 R15+ protocol specification
+
+## License
+- The ring buffer implementation (`ringbuffer_char.c/h`) is licensed under the **MIT License** (© 2014 Anders Kalør)
+- Remaining source code is original work by Alexis (alc6). Please check project root for specific licensing terms.