Github Repo: https://github.com/KoukiXia/Emergency-Vehicle-Traffic-Preemption-System

Link to Proposal Slides: https://github.com/KoukiXia/Emergency-Vehicle-Traffic-Preemption-System/blob/main/Slides%201.pdf

Link to Progress Slides: https://github.com/KoukiXia/Emergency-Vehicle-Traffic-Preemption-System/blob/main/Slides%202.pdf

Link to Final Slides: https://github.com/KoukiXia/Emergency-Vehicle-Traffic-Preemption-System/blob/main/Slides%201.pdf

Figure 1. Physical deployment concept. The Ambulance Unit (foreground) carries the GPS antenna, emergency-mode toggle, OLED link-status display, and LoRa radio. The Intersection Unit (mounted on the signal pole, cutaway shown inset) hosts the second ESP32, LoRa receiver, OLED, and buzzer, and drives a standard 4-approach signal head. The two communicate over LoRa at 868 MHz.

This wiki documents GreenWave's full lifecycle: the original proposal, the M3 simulation-based progress demo, the as-built hardware system delivered at M4, and an honest accounting of what was and wasn't implemented relative to the original scope.

• §1 is the proposal as submitted. Some details (ESP32, 868 MHz, OLEDs, GPS, 4-approach signal head) were later revised — see §2 and §4 for the as-built design.
• §2 is the as-built architecture (the truthful version).
• §3 is the M3 simulation progress checkpoint.
• §4 is the Checkpoint B hardware integration update.
• §5 is the final implementation: firmware architecture, RTOS task design, protocol, state machine.
• §6 is testing and validation, including the honest FR status table.
• §7 is project management.
• §8 is lessons learned and known limitations.
• §9 is media: photos, video, and serial captures.

In Cairo and most Egyptian cities, ambulances lose critical minutes stuck in gridlock. Published figures put the average ambulance response time in Egypt at 8 to 15 minutes, and it is common to see emergency vehicles trapped behind traffic with sirens blaring. For conditions like cardiac arrest, stroke, or major trauma, every minute of delay measurably reduces survival rate. Meanwhile, cities like Dubai, several US metros, and parts of Germany and the UK already deploy Emergency Vehicle Preemption (EVP) systems (Opticom, EMTRAC, Commsignia V2X) that turn intersections green for approaching emergency vehicles, cutting response times by 14 to 23 percent. No comparable system is deployed in Egypt.

GreenWave is a prototype Emergency Vehicle Preemption system built around two microcontrollers running FreeRTOS, connected by a LoRa radio link. An "ambulance unit" carries a physical "Emergency Mode" switch. When the driver asserts the switch, it broadcasts a signed preemption request packet over LoRa every two seconds. A stationary "intersection unit" runs a multi-phase traffic light state machine with red/yellow/green LEDs for two approaches (priority direction and cross-traffic). On receiving a valid preemption request, the intersection controller safely aborts its current phase (respecting yellow-clearance and all-red intervals), grants a green to the priority approach, holds it while packets keep arriving, then returns to normal cycle when the ambulance has passed.

The project demonstrates hardware-software co-design (microcontrollers + LoRa + actuated signal head), non-trivial real-time behavior (phase safety, clearance timing, preemption arbitration), an RTOS architecture with multiple concurrent tasks communicating through binary semaphores, and authenticated wireless V2I (vehicle-to-infrastructure) communication.

[See the original proposal for the full literature scan and motivation.]

Briefly: Egypt has no deployed EVP system; international precedent exists (Opticom in US since the 1970s, modern GPS-radio EVP in Seattle/Minneapolis showing 14–23% response-time reduction, Dubai RTA's smart-ambulance program). We address the gap with a student-scale, open, inexpensive prototype.

Two ESP32 nodes running FreeRTOS, LoRa as the V2I radio, GPS on the vehicle, a 4-approach signal head with 12 LEDs. The ambulance unit was intended to fuse GPS speed, heading, and distance-to-intersection to gate preemption requests. The intersection unit was to run a 4-phase signal FSM with directional filtering (±45° heading match) and GPS-based clearance detection.

The original FR list (FR1–FR11) defined RTOS architecture, GPS-gated transmission, directional filtering, safe phase transitions, HMAC authentication, replay protection, fail-safe flashing red, manual override, and OLED observability.

Several of these were revised, partially completed, or descoped during implementation — see §2 (as-built) and §6.4 (honest FR status table) for the current state.

This section documents the actual delivered system. Where the proposal differs, the as-built version takes precedence and the divergence is noted.

flowchart LR
    subgraph AMBULANCE["🚑 AMBULANCE UNIT"]
        direction TB
        BTN_A["Emergency<br>Button (PA8)"]
        MCU_A["STM32L432KC<br>Nucleo-L432KC<br><br>FreeRTOS<br>• buttonTask<br>• radioTask (2s)<br>• sirenTask (2Hz)<br>• defaultTask (1Hz)"]
        LED_A["LD3<br>Siren Indicator<br>(PB3)"]
        LORA_A["SX1278 LoRa<br>433 MHz"]
        ANT_A["λ/4 Antenna<br>17 cm wire"]
        BTN_A -->|EXTI falling<br>+ semaphore| MCU_A
        MCU_A -->|GPIO toggle| LED_A
        MCU_A <-->|SPI1| LORA_A
        LORA_A --- ANT_A
    end

    subgraph INTERSECTION["🚦 INTERSECTION UNIT"]
        direction TB
        ANT_I["λ/4 Antenna<br>17 cm wire"]
        LORA_I["SX1278 LoRa<br>433 MHz"]
        MCU_I["STM32L432KC<br>Nucleo-L432KC<br><br>FreeRTOS<br>• radioRxTask (sem)<br>• stateMachineTask (10Hz)<br>• buttonTask (sem + long-press)<br>• defaultTask (1Hz)"]
        BTN_I["Test Button<br>(PA8)<br>short=preempt<br>long=override"]
        LED_LD3["LD3<br>RX Indicator"]
        LEDS_NS["NS LEDs<br>RED · YEL · GRN<br>PA0 PA1 PA4"]
        LEDS_EW["EW LEDs<br>RED · YEL · GRN<br>PA11 PA12 PB5"]
        ANT_I --- LORA_I
        LORA_I <-->|SPI1| MCU_I
        LORA_I -.->|DIO0 EXTI<br>+ semaphore| MCU_I
        BTN_I -->|EXTI + semaphore| MCU_I
        MCU_I -->|GPIO| LED_LD3
        MCU_I -->|GPIO| LEDS_NS
        MCU_I -->|GPIO| LEDS_EW
    end

    ANT_A <==>|"LoRa 433 MHz<br>SF7 · BW 125 kHz<br>HMAC-signed<br>24-byte packet<br>every 2 seconds"| ANT_I

    style AMBULANCE fill:#fff5e6,stroke:#cc7700,stroke-width:2px
    style INTERSECTION fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style LORA_A fill:#ffe6e6
    style LORA_I fill:#ffe6e6
    style MCU_A fill:#f0f0f0
    style MCU_I fill:#f0f0f0

                    ===========  AMBULANCE UNIT  ============
                    |                                        |
  +-----------+ EXTI|   +--------------------------------+   |
  | Emergency |---->|-->|                                |   |
  | Switch    |     |   |   STM32L432KC (Nucleo board)   |   |
  +-----------+     |   |       FreeRTOS Kernel          |   |
  +-----------+ GPIO|   |                                |SPI|  LoRa 433 MHz
  | LD3 LED   |<----|---|  Tasks (4):                    |---| ===========>>
  | (siren)   |     |   |   - buttonTask    (sem-driven) |   |  (SX1278 TX)
  +-----------+     |   |   - radioTask     (every 2 s)  |   |  HMAC-signed
                    |   |   - sirenTask     (2 Hz blink) |   |  preempt pkt
                    |   |   - defaultTask   (1 Hz hb)    |   |  while EMRG on
                    |   +--------------------------------+   |
                    |   Power: USB 5V -> Nucleo onboard 3V3  |
                    ==========================================

                                        | ~ a few meters of free space (demo)
                                        v

                    ==========  INTERSECTION UNIT  ==========
                    |                                        |
                    |   +--------------------------------+   |  GPIO  +------+
                    |   |                                |-->|  NS R/Y/G    |
        LoRa  SPI   |   |   STM32L432KC (Nucleo board)   |   |  (3 LEDs)    |
  >>===============>|-->|       FreeRTOS Kernel          |   +------+
        (SX1278 RX) |   |                                |   |  GPIO  +------+
                    |   |  Tasks (4):                    |-->|  EW R/Y/G    |
                    |   |   - radioRxTask   (sem-driven) |   |  (3 LEDs)    |
                    |   |   - stateMachine  (10 Hz)      |   +------+
                    |   |   - buttonTask    (sem-driven, |GPIO|  +------+
                    |   |                    long-press) |--->|  LD3   |
                    |   |   - defaultTask   (1 Hz hb)    |    |  (RX)  |
                    |   +--------------------------------+    |  +------+
                    |             ^                           |
                    |             | EXTI                      |
                    |          (test button)                  |
                    |   Power: USB 5V -> Nucleo onboard 3V3   |
                    ===========================================
                              ^
                              |
                  FR9: Failsafe — both reds flash 1 Hz on
                  LoRa init failure or manual override

LoRa 433 MHz, SF7, BW 125 kHz, CR 4/5, sync word 0xF3, TX power 2 dBm. Packet format:

emergency_packet_t {
    uint32_t magic;             // 0x47573138 ("GW18")
    uint8_t  ambulance_id;      // 0x01
    uint8_t  direction;         // hardcoded DIR_EAST
    uint8_t  flags;             // 0x01 = emergency active
    uint8_t  reserved;
    uint32_t sequence;          // monotonically increasing
    uint32_t timestamp_ms;      // ambulance HAL_GetTick()
    uint8_t  hmac[8];           // truncated HMAC-SHA256
}

Total 24 bytes. Signed with HMAC-SHA256 on the ambulance side using a 32-byte shared secret compiled into both nodes' firmware. Note: HMAC verification on the intersection side is implemented but has an integration issue — see §6.4 (FR7, FR8 status) for honest details.

Both nodes are powered over USB (Nucleo's onboard ST-LINK USB) at 5 V, with the Nucleo's LDO providing 3.3 V to the LoRa module.

Firmware for both nodes was complete and validated end-to-end in the Wokwi simulator at M3. Hardware procurement was running behind schedule, so M3 was delivered as a Wokwi-based simulation demo. Every safety-critical behavior — phase FSM with min-green/yellow/all-red clearance, preemption arbitration, manual override, fail-safe — was exercised in simulation.

Figure 4. Ambulance unit in Wokwi. ESP32 with the EMERGENCY momentary switch and the STATUS LED. With the switch asserted, the firmware enters emergency state, lights the status LED, and begins broadcasting authenticated preemption packets at the configured rate.

Figure 5. Intersection unit in Wokwi. Twelve LEDs implement the 4-approach signal head (N/S/E/W × R/Y/G). The four blue buttons (N/S/E/W AMBULANCE) inject a simulated preempt request from each approach, replacing the LoRa receive path during simulation. The red OVERRIDE button forces flashing-red fail-safe; the green CLEAR button releases an active preempt. The buzzer chirps while preempt is active. The screenshot captures a yellow-clearance phase mid-transition — proof that the FSM honors the mandatory clearance interval before changing approaches.

Ambulance Unit https://github.com/user-attachments/assets/7c5acce0-8f6f-4bad-ae81-6abd9b0f873b

Intersection Unit https://github.com/user-attachments/assets/3bd3108f-365d-47e8-95f4-dbacfad1dd52

• Serial-log capture of one full preempt event (entry → hold → release), with timestamps.
• Wokwi capture of the manual-override flashing-red fail-safe.
• *Wokwi capture of the all-red clearance interval between phases.

Original (proposal): Ambulance carried a NEO-6M GPS module; preempt packets included lat/lon/heading/speed; the intersection rejected requests whose heading did not match an approach within ±45° and released the green when GPS showed the vehicle had cleared.

Revised (M3): GPS removed entirely. Approach identification was originally going to be replaced with packet-carried approach ID + RSSI-trend detection on the intersection.

Status post-implementation: The GPS removal stuck; that was the right call. The RSSI-trend replacement, however, was never implemented — the system instead uses a fixed 15-second preempt-hold timer that refreshes on every received packet, which is simpler and adequate for a tabletop demo but isn't the proximity-aware design we described at M3.

The simulation proved the phase FSM, the preempt arbitration, the HMAC verification (in simulation only), and the safe transitions through yellow and all-red clearances. The firmware was structured for FreeRTOS-style task separation even though the M3 build was on ESP-IDF and we later ported to STM32 + ARM Compiler 6 + the FreeRTOS provided by STM32CubeMX. The architecture survived the port; the file structure and task names changed.

Between M3 and Checkpoint B we migrated from ESP32 to STM32 Nucleo-L432KC (lecturer-mandated). The migration consisted of:

• Re-implementing the LoRa driver to talk to SX1278 over STM32 HAL SPI rather than ESP-IDF SPI.
• Re-implementing HMAC-SHA256 in plain C without depending on mbedTLS (to avoid Keil pack dependencies — the workshop's Pack Installer had broken vendor PDSC files).
• Switching the build toolchain to Keil µVision MDK with ARM Compiler 6.24.
• Switching CubeMX to generate FreeRTOS scaffolding (CMSIS-RTOS v2).

The application logic — phase FSM, preempt arbitration, packet format, task structure — was preserved.

• Ambulance unit: Nucleo-L432KC + SX1278 (Ra-02) + tactile button + onboard LD3 LED + 17 cm wire antenna, all on a breadboard mounted to a wooden laser-cut box.
• Intersection unit: Same Nucleo + SX1278 + 6 LEDs (R/Y/G × 2) + tactile button + onboard LD3 + 17 cm wire antenna, breadboard on a wooden laser-cut box.
• LED wiring: Each direction group (NS and EW) shares one current-limiting resistor on its common cathode — safe because the FSM guarantees only one LED in each group is lit at any time. NS group uses 330 Ω; EW group uses 100 Ω.

We added a counter for DIO0 interrupts (dio0_irq_count) and a counter for failed packet reads (read_failures) to the intersection's heartbeat output. These were instrumental in diagnosing the FreeRTOS re-arm bug: we could see that DIO0 was firing (so RF link worked) but reads were failing (so it was a software-side bug, not an antenna/hardware issue).

Both nodes run FreeRTOS (CMSIS-RTOS v2 API) on the STM32L432KC with the SysTick reserved for the kernel and TIM6 used as the HAL timebase source. Each node has four concurrent tasks plus the FreeRTOS idle task.

• ISR → task signaling: binary semaphores (packetSemHandle, buttonSemHandle). The ISR calls osSemaphoreRelease() (CMSIS-RTOS v2's ISR-safe API); the task blocks on osSemaphoreAcquire(..., osWaitForever). Zero CPU usage while idle, microsecond-latency wakeup on event.
• Task → task shared state: volatile flags and counters for state read by multiple tasks (e.g., emergency_active, current_phase, last_packet_ms, failsafe_active). On Cortex-M4 these are atomic for word-sized accesses, so no mutex was needed.
• SPI bus: shared between tasks and the EXTI ISR. The LoRa driver's ISR work is brief; in practice the timing does not collide. A production version would add a mutex.

The intersection runs a 6-phase cycle:

PHASE_NS_GREEN  (10 s)
   ↓
PHASE_NS_YELLOW (3 s)
   ↓
PHASE_ALLRED_1  (1.5 s)
   ↓
PHASE_EW_GREEN  (10 s normal, 15 s during preempt)
   ↓
PHASE_EW_YELLOW (3 s)
   ↓
PHASE_ALLRED_2  (1.5 s)
   ↓
[back to PHASE_NS_GREEN]

Full cycle: 29 seconds (normal), or up to 34 seconds with active preemption.

When failsafe_active is set (LoRa init failure OR manual override via long-press), this normal state machine is bypassed: both red LEDs flash at 1 Hz; all other LEDs are forced off; preempt requests (LoRa or button) are ignored until failsafe is cleared.

stateDiagram-v2
    direction TB
    [*] --> NS_GREEN : Power-on (default)
    [*] --> FAILSAFE : LoRa init fail

    state "NS_GREEN<br>(10 s)" as NS_GREEN
    state "NS_YELLOW<br>(3 s)" as NS_YELLOW
    state "ALLRED_1<br>(1.5 s)" as ALLRED_1
    state "EW_GREEN<br>(10 s normal<br>15 s preempt)" as EW_GREEN
    state "EW_YELLOW<br>(3 s)" as EW_YELLOW
    state "ALLRED_2<br>(1.5 s)" as ALLRED_2
    state "FAILSAFE<br>both reds<br>flash 1 Hz" as FAILSAFE

    NS_GREEN --> NS_YELLOW : timeout
    NS_YELLOW --> ALLRED_1 : timeout
    ALLRED_1 --> EW_GREEN : timeout
    EW_GREEN --> EW_YELLOW : timeout AND no preempt
    EW_YELLOW --> ALLRED_2 : timeout
    ALLRED_2 --> NS_GREEN : timeout

    NS_GREEN --> NS_YELLOW : ⚡ preempt packet<br>(cut early)
    EW_YELLOW --> EW_GREEN : ⚡ preempt packet<br>(snap back)
    ALLRED_2 --> EW_GREEN : ⚡ preempt packet<br>(snap back)
    EW_GREEN --> EW_GREEN : ⚡ preempt packet<br>(refresh 15s timer)

    NS_GREEN --> FAILSAFE : long-press button
    NS_YELLOW --> FAILSAFE : long-press button
    ALLRED_1 --> FAILSAFE : long-press button
    EW_GREEN --> FAILSAFE : long-press button
    EW_YELLOW --> FAILSAFE : long-press button
    ALLRED_2 --> FAILSAFE : long-press button

    FAILSAFE --> NS_GREEN : long-press button<br>(clean reset)

When a valid packet arrives (or the test button is short-pressed), activate_preempt() decides what to do based on the current phase:

Each new packet refreshes the 15-second timer, so as long as the ambulance keeps transmitting, EW stays green.

/Ambulance/
  Core/Src/main.c           – tasks + init
  Core/Inc/main.h           – pin defines
  Core/Inc/FreeRTOSConfig.h
  Drivers/lora.c, lora.h    – SX1278 driver
  Drivers/packet.c, packet.h – packet struct, HMAC, signing
  Middlewares/FreeRTOS/...
/Intersection/
  [same structure]

End-to-end demo:

1. Both nodes powered up. Both report LoRa initialized OK (ambulance) / LoRa receiver active (intersection) on serial.
2. Intersection begins normal phase cycle.
3. Operator presses ambulance button. Ambulance's LD3 blinks. Serial shows TX seq=1, 2, 3, ....
4. Within 2 seconds the intersection's serial shows RX OK seq=1, PREEMPT ACTIVATED, and the EW direction transitions to green via the appropriate clearance.
5. Intersection's LD3 lights solid (RX indicator).
6. EW stays green while ambulance continues to transmit.
7. Operator presses ambulance button again to disable emergency. Ambulance LD3 stops blinking. Transmissions stop.
8. After 15 seconds of no packets, intersection logs PREEMPT DEACTIVATED. Intersection's LD3 turns off. Normal cycle resumes.

Honest reading: of 11 FRs, 6 are fully implemented, 5 are partial or revised (FR3, FR4, FR7, FR8, FR11), and 0 are missing entirely. The two safety-related partials (FR7 HMAC verification, FR8 replay protection) are blocked by a single integration issue in the packet_verify function — a known target for post-demo cleanup. All other safety mechanisms (FR5 safe transitions, FR6 timeout release, FR9 failsafe, FR10 override) are fully working.

All three members share responsibility for integration testing, the proposal and progress presentations, the final demo, and the wiki.

• The state machine design held up. The 6-phase FSM with hard-enforced yellow and all-red clearance survived every test, every preempt-arrival timing, and the entire platform migration from ESP32-Wokwi to STM32 hardware.
• The pivot to remove GPS at M3 was the right call. Indoor GPS was always going to be a demo-day liability.
• Splitting the project into ambulance + intersection let us debug in isolation. When the intersection wasn't receiving packets after the FreeRTOS port, we could confirm the ambulance was transmitting before suspecting the RF link.
• Diagnostic counters paid for themselves. dio0_irq_count and read_failures localized the post-RTOS RX bug to software in minutes.
• FreeRTOS conversion taught us real RTOS primitives. The binary-semaphore design for ISR-to-task signaling is genuinely better than polling and gave us something defensible to show.
• Failsafe and override (FR9, FR10) shipped fully working. These are the safety promises the proposal made; getting them done in the polish sprint matters.

• Start with the real hardware platform from day one. ESP32-Wokwi was educationally useful but every hour spent on it had to be re-spent on STM32.
• Use Keil MDK Community Edition from the start. The free MDK-Lite's 32 KB limit forced a late optimization scramble.
• Test HMAC verification end-to-end earlier. We had HMAC working in simulation, but the TX/RX integration bug in packet_verify only surfaced in the polish sprint when there wasn't time to fully debug it. A simple loopback test between the two firmware images at M3 would have caught it.
• Use a mutex for SPI bus access. The current design works because the ISR's SPI use happens not to collide with task SPI use. This is fragile; a FreeRTOS mutex would make it correct.

• HMAC verification is bypassed in the RX path (see FR7 / FR8 in §6.4). The signing infrastructure is fully in place — only the verifier function needs the final integration fix. This is a documented, time-boxed scope cut, not an architectural decision.
• No OLED display — observability is via UART through the ST-Link USB. Fine for development but unusual for a fielded device.
• No buzzer — visual-only signaling.
• Single hardcoded priority direction — the system assumes EW is the priority approach. A real system would receive direction from the ambulance and switch which approach is preempted.
• No replay protection across power cycles — if the ambulance is reset mid-session (seq goes back to 1) while the intersection retains last_seq_seen = 50, all post-reset packets are rejected as replays. Workaround: reset both devices together.
• Antennas are wire pressed into through-hole — no SMA connectors or soldered joints. Works at room scale but flaky for any longer range.
• No hardware watchdog — the "watchdog task" is a heartbeat for human observability, not an IWDG-backed fault recovery mechanism.

• Fix packet_verify to close out FR7 and unblock FR8.
• Implement RSSI-trend proximity detection (the M3 pivot promised).
• Add a second intersection for a real "green wave" along a corridor.
• Add an OLED display so the demo doesn't require a serial console.
• Solder antennas instead of wire-in-through-hole.
• Power from batteries to free the demo from the lab bench.
• Field test at >100 m line-of-sight to characterize actual range.

GreenWave proves that a useful subset of an emergency vehicle preemption system can be built from $30 of parts and a few weeks of student work. The honest gaps in the implementation, documented in §6.4, are real and we don't paper over them. But the core demonstration — press a button on the ambulance, watch the intersection respond authentically with yellow-clearance before stopping cross traffic, watch the failsafe activate on fault — is fully working, and is a faithful tabletop model of what Opticom and EMTRAC do at city scale.

• Opticom Infrared and GPS Preemption Systems (Global Traffic Technologies)
• EMTRAC GPS preemption documentation
• "Effects of Emergency Vehicle Preemption on Crash Frequency" (FHWA studies, 2010s)
• Dubai RTA SCOOT and UTC-UX Fusion announcements
• C-V2X / ITS-G5 emergency preemption pilots (Ford / Commsignia 2021–2024)
• FreeRTOS Real-Time Kernel — Reference Manual (Amazon Web Services)
• Semtech SX1278 datasheet
• STM32L4xx HAL reference manual