📡 HAL-Zero-Protocols: Bare-Metal Communication Suite

Welcome to HAL-Zero-Protocols, a professional-grade repository dedicated to Bare-Metal Firmware Development, Industrial Protocol Stacks, and Silicon Verification. This project bridges the gap between educational foundations and production-ready firmware, providing high-performance implementations for UART, SPI, I2C, CAN, and USB.

---

🚀 Key Engineering Highlights

• Zero-Dependency Architecture: Custom STM32F4xx drivers written from scratch via direct register manipulation (No HAL, No CMSIS).
• Cross-Domain Verification: Functional parity across RTL (SystemVerilog), Embedded C, and Python host scripts.
• Defensive Design: Built-in error detection (Parity, NACK, Watchdogs) and robust Finite State Machine (FSM) control logic.
• Continuous Integration Ready: Comprehensive verification suite for both hardware-in-the-loop and host-side simulations.

---

📚 Table of Contents

• Core Design Philosophy
• Protocol Design Lifecycle
• Industrial Standards Compliance
• Protocols Overview
• Comparison Matrix
• Verification Status
• Repository Structure
• Build & Verification
• Getting Started
• Contributing
• License

---

🏗️ Core Design Philosophy

This repository is built on three pillars of professional embedded engineering:

1. Reliability First: Every implementation includes error detection and recovery mechanisms.
2. Logic Parity: Ensuring identical protocol logic across low-level FPGA gates and high-level software.
3. Deterministic Execution: All digital logic is governed by explicit FSMs to prevent undefined states.

---

🛠️ Protocol Design Lifecycle

graph TD
    Start([Requirement Analysis]) --> Spec[Protocol Specification Review]
    Spec --> FSM[FSM Design & State Analysis]
    FSM --> RTL[RTL Coding / C implementation]
    RTL --> Sim[Block-Level Simulation]
    Sim --> |Fails| FSM
    Sim --> |Passes| E2E[End-to-End Verification]
    E2E --> |Fails| RTL
    E2E --> Docs[Documentation & Maintenance]
    Docs --> Finish([Verified Release])

    style Start fill:#1565c0,stroke:#0d47a1,color:#ffffff
    style Finish fill:#1565c0,stroke:#0d47a1,color:#ffffff
    style Spec fill:#e3f2fd,stroke:#1565c0,color:#000000
    style FSM fill:#fff9c4,stroke:#fbc02d,color:#000000
    style RTL fill:#f3e5f5,stroke:#7b1fa2,color:#000000
    style Sim fill:#ffe0b2,stroke:#e65100,color:#000000
    style E2E fill:#2e7d32,stroke:#1b5e20,color:#ffffff
    style Docs fill:#e0f2f1,stroke:#00695c,color:#000000

Loading

---

🏛️ Industrial Standards Compliance

To ensure production-readiness, all implementations adhere to the following industry specifications:

• UART: Standard 8-N-1 framing with configurable parity and baud rates up to 921,600 bps.
• SPI: Full support for all 4 Motorola SPI modes (CPOL/CPHA) and multi-slave topology.
• I2C: NXP I2C-bus specification compliant, including clock stretching and 7-bit addressing.
• CAN: Bosch CAN 2.0B Active/Passive support for automotive-grade reliability.
• Modbus: Modbus Application Protocol Specification V1.1b3 (RTU Mode).

---

🚀 Protocols Overview

1. UART (Universal Asynchronous Receiver-Transmitter)

The simple, point-to-point workhorse.

• Used for: Debugging (Serial Monitor), GPS modules, Bluetooth (HC-05), basic PC-to-controller communication.
• Key Features: Asynchronous (no clock line), full-duplex (TX/RX).

2. SPI (Serial Peripheral Interface)

The speed demon.

• Used for: SD cards, TFT displays, Flash memory, high-speed sensors.
• Key Features: Synchronous (Clock line), full-duplex, Master-Slave architecture, specific Chip Select (CS) lines.

3. I2C (Inter-Integrated Circuit)

The multi-master bus.

• Used for: IMUs (Accelerometers/Gyros), EEPROMs, RTCs, connecting many slow devices on just two wires.
• Key Features: Synchronous, half-duplex, addressed-based (software addressing), requires pull-up resistors.

---

📐 Engineering Principles

• Modular Portability: Logic encapsulated for seamless migration between MCU families or FPGA vendors.
• Metastability Mitigation: Rigorous clock domain crossing (CDC) management and synchronization.
• Timing Integrity: Precise control over setup/hold times and signal sampling windows.
• Observability: Rich telemetry and error reporting for rapid system-level debugging.

---

✅ Verification Status

Protocol	FPGA (SV)	Arduino (C++)	Python	STM32 (Bare-Metal)
UART	✅ PASSED	✅ PASSED	✅ PASSED	✅ PASSED
SPI	✅ PASSED	✅ PASSED	✅ PASSED	✅ PASSED
I2C	✅ PASSED	✅ PASSED	✅ PASSED	✅ PASSED

• FPGA: Verified via Icarus Verilog simulation suites.
• Arduino (C++): Logic verified against official library specifications and serial timing.
• Python: Logic verified via mock-hardware test runners.
• STM32: Verified on hardware against logic analyzers and official timing requirements.

---

📊 Comparison Matrix

Feature	UART	SPI	I2C
Type	Asynchronous	Synchronous	Synchronous
Wires (Min)	2 (TX, RX) + GND	4 (MOSI, MISO, SCK, CS) + GND	2 (SDA, SCL) + GND
Speed	< 1 Mbps	> 10 Mbps	100kHz - 3.4MHz
Topology	Point-to-Point	Single Master, Multi-Slave	Multi-Master, Multi-Slave
Pros	Simple, ubiquitous	Fast, high throughput	Scalable, low pin count
Complexity	Low	Low/Medium	Medium/High

---

📂 Repository Structure

HAL-Zero-Protocols/
├── 📂 UART/              # Educational: Protocol fundamentals & cross-platform logic
├── 📂 SPI/               # Educational: High-speed synchronous logic
├── 📂 I2C/               # Educational: Adressed multi-device bus logic
├── 📂 drivers/           # Production: Bare-metal STM32F4xx drivers (Zero HAL)
│   ├── 📂 common/        # Base register defs & error handling
│   ├── 📂 gpio/          # GPIO & EXTI interrupt driver
│   ├── 📂 uart/          # Interrupt-driven & DMA UART driver
│   ├── 📂 spi/           # Full-duplex SPI Master/Slave driver
│   └── 📂 ...            # Timer, ADC, PWM, DMA, NVIC
├── 📂 protocol_stacks/   # Industrial: Modbus RTU, CAN 2.0B, USB CDC
└── 📂 verification/      # Quality Assurance: Python mocks & C unit tests

---

🔨 Build & Verification

1. Toolchain Prerequisites

• ARM GCC: arm-none-eabi-gcc for firmware.
• GNU Make: Build automation.
• Python 3: Mock verification.
• Icarus Verilog: FPGA simulation.

2. Compilation

make -j$(nproc)

Generates build/firmware.elf, .hex, and .bin for flashing to STM32F401RETx.

3. Verification Suite

Windows:

verification\run_verification.bat

Note: This script automatically checks for the MSVC compiler (cl.exe). If it is not in your PATH, you may need to run this from the "x64 Native Tools Command Prompt for VS 2022" or manually run vcvarsall.bat first.

Linux/macOS:

# Run Python tests
python3 verification/mock_verify.py

# Compile and run C tests
gcc -std=c11 -DUNIT_TEST -I./drivers/common -I./protocol_stacks/modbus -I./protocol_stacks/usb_cdc -I./protocol_stacks/can_bus verification/test_drivers.c -o test_drivers
./test_drivers

---

🏁 Getting Started

1. Select a Protocol: Navigate to the directory of the protocol you wish to learn.
2. Read the Theory: Open the README.md in that folder to understand the signal lines and packet structure.
3. Run the Code:
   • Arduino: Open the .ino files in the Arduino IDE and flash to your board (Uno, Nano, ESP32, etc.).
   • STM32: Create a new project in STM32CubeMX matching the configuration described in the main.c header, then copy the user code logic.
   • FPGA: Import the .sv files into Vivado, Quartus, or ModelSim for simulation/synthesis.
   • Python: Install PySerial or required libraries and run the scripts on your PC or Raspberry Pi.

---

🤝 Contributing

Contributions that enhance reliability or add new protocols are welcome. Please refer to the Contribution Guidelines.

---

📜 License

Distributed under the MIT License. See LICENSE for more information.