Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 20 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,29 @@
# ER-GreenWave

Emergency vehicles lose time at red lights. ER-GreenWave is a proof of concept for Kraków that
picks the dispatch station, routes the vehicle over the real road network and simulates a
**green corridor**: the signals ahead of an ambulance, fire truck or police car are asked to turn
green in time, and the run shows how many seconds that saves against standard traffic.
ER-GreenWave is a Kraków emergency-corridor proof of concept with two intended benefits:
shorter emergency response and less disruption to general traffic. Coordinating signals ahead
of an emergency vehicle is intended to flush queues before arrival and avoid downstream
blocking when emergency vehicles move through heavy traffic. The PoC selects a dispatch base,
plans a road route and compares simulated journeys with and without signal priority.
It does not simulate traffic queues or measure reductions in congestion.

**Simulation only.** ER-GreenWave never connects to or controls real traffic infrastructure. Every
signal state, ITS message, delay and priority command it shows is simulated.

## Traffic signal operating modes

These are intersection phases, separate from the `ENABLED` / `DISABLED` run modes.

| Phase | Intended traffic-management role | Current PoC behavior |
| --- | --- | --- |
| `NORMAL` — baseline | Serve ordinary traffic without an active emergency corridor. | Ordinary two-group cycle; a pending request alone does not alter it. |
| `CLEARING` — pre-arrival queue flushing | Open coordinated phases ahead of arrival to discharge queues and keep downstream junctions moving. | After acceptance, conflicting movements and pedestrians target red; route movements keep their ordinary programme. No queue discharge is simulated. |
| `PRIORITY_GREEN` — corridor preemption | Hold route green for continuous emergency passage. | Accepted request, TTI ≤25 s by default and shown-green confirmation required. Delays and fallback mean passage is not guaranteed to be uninterrupted. |
| `RECOVERY` — post-passage stabilization | Gradually restore cycle lengths and offsets to limit shockwaves, secondary bottlenecks and gridlock. | After protected passage, the ordinary programme resumes immediately with shown-head clearance transitions; recovery state lasts 15 s by default. No gradual offset/cycle restoration is implemented. |

The bilingual `/docs` Architecture section presents these roles alongside implementation
behavior; Details retains the equations, transition conditions and parameter reference.

## Features

- **Green Wave vs standard traffic.** Run the same scenario with priority signals or with ordinary
Expand Down
9 changes: 9 additions & 0 deletions frontend/src/components/docs/docs-blocks.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -224,3 +224,12 @@ describe("details reference", () => {
expect(JSON.stringify(details("pl"))).not.toContain("Ten opis odtwarza");
});
});

it("preserves canonical state identifiers when the operating-mode descriptions change language", () => {
for (const language of ["pl", "en"] as const) {
const architecture = docsContent[language].find((section) => section.id === "architecture")!;
const html = renderToStaticMarkup(<DocsSectionView section={architecture} />);
for (const state of ["NORMAL", "CLEARING", "PRIORITY_GREEN", "RECOVERY"])
expect(html).toContain(`class="docs-card-label">${state}</span>`);
}
});
14 changes: 14 additions & 0 deletions frontend/src/lib/docs/content.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -133,3 +133,17 @@ it("explains the dashed ITS exchange in both diagram captions", () => {
expect(caption("en")).toContain("dashed two-way arrow");
expect(caption("en")).toContain("within the simulation");
});

it("preserves configuration identifiers and equations between languages", () => {
const reference = (language: "pl" | "en") => docsContent[language].flatMap((s) => s.blocks);
const identifiers = (language: "pl" | "en") =>
reference(language).flatMap((block) =>
block.kind === "table"
? block.rows.filter((row) => /^[a-zA-Z][a-zA-Z0-9]*_/.test(row[0]))
: [],
);
expect(identifiers("pl").map((row) => row[0])).toEqual(identifiers("en").map((row) => row[0]));
const equations = (language: "pl" | "en") =>
reference(language).flatMap((block) => (block.kind === "formula" ? [block.expression] : []));
expect(equations("pl")).toEqual(equations("en"));
});
7 changes: 5 additions & 2 deletions frontend/src/lib/docs/content.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { operatingModeBlocks } from "./operating-modes";
import { detailsSections } from "./details-content";
import type { Language } from "@/lib/localization";
import type { DocsSectionId } from "./tabs";
Expand Down Expand Up @@ -81,7 +82,7 @@ export const docsContent: Record<Language, DocsSection[]> = {
blocks: [
{
kind: "paragraph",
text: "ER-GreenWave porównuje czas dojazdu pojazdu uprzywilejowanego z priorytetem na skrzyżowaniach i bez niego. Symulacja korzysta z sieci drogowej Krakowa, lokalizacji jednostek ratunkowych i miejskich danych adresowych.",
text: "ER-GreenWave porównuje czas dojazdu pojazdu uprzywilejowanego z priorytetem na skrzyżowaniach i bez niego. Symulacja korzysta z sieci drogowej Krakowa, lokalizacji jednostek ratunkowych i miejskich danych adresowych. Wartość korytarza obejmuje dwa cele: szybszy dojazd służb i wcześniejsze uporządkowanie ruchu ogólnego. Docelowo skoordynowane otwieranie sygnalizacji przed pojazdem ma opróżniać kolejki i zapobiegać blokowaniu skrzyżowań oraz zatorom w dalszej części trasy, zamiast tylko podawać zielone nadjeżdżającemu pojazdowi. Obecny PoC prezentuje koordynację priorytetu; efektu na kolejki jeszcze nie oblicza.",
},
{
kind: "paragraph",
Expand Down Expand Up @@ -270,6 +271,7 @@ export const docsContent: Record<Language, DocsSection[]> = {
caption:
"Szare linie ciągłe pokazują przygotowanie i wczytanie danych. Zielone strzałki oznaczają przesyłanie stanów symulacji do panelu przez SSE. Przerywana strzałka w obu kierunkach oznacza żądania priorytetu i odpowiedzi symulowanego sterownika ITS. Ta wymiana odbywa się wewnątrz procesu symulacji.",
},
...operatingModeBlocks("pl"),
{ kind: "heading", text: "Przygotowanie danych" },
{
kind: "paragraph",
Expand Down Expand Up @@ -424,7 +426,7 @@ export const docsContent: Record<Language, DocsSection[]> = {
blocks: [
{
kind: "paragraph",
text: "ER-GreenWave compares emergency-vehicle travel times with and without signal priority. The simulation uses Kraków’s road network, emergency-service locations and municipal address data.",
text: "ER-GreenWave compares emergency-vehicle travel times with and without signal priority. The simulation uses Kraków’s road network, emergency-service locations and municipal address data. The corridor has two intended benefits: faster emergency response and proactive reorganisation of general traffic. Coordinated green phases ahead of the vehicle are intended to flush queues and prevent gridlock and downstream jams caused by emergency passage through heavy traffic. The current PoC demonstrates signal-priority coordination; it does not yet calculate queue discharge or congestion reduction.",
},
{
kind: "paragraph",
Expand Down Expand Up @@ -613,6 +615,7 @@ export const docsContent: Record<Language, DocsSection[]> = {
caption:
"Solid grey arrows show data preparation and loading. Green arrows carry simulation states to the dashboard over SSE. The dashed two-way arrow shows priority requests and responses exchanged with the simulated ITS controller, entirely within the simulation.",
},
...operatingModeBlocks("en"),
{ kind: "heading", text: "Data preparation" },
{
kind: "paragraph",
Expand Down
80 changes: 80 additions & 0 deletions frontend/src/lib/docs/operating-modes.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
import type { Language } from "@/lib/localization";
import type { DocsBlock } from "./content";

/** State identifiers remain verbatim; descriptions distinguish design intent from the PoC. */
export function operatingModeBlocks(language: Language): DocsBlock[] {
const t = (pl: string, en: string) => (language === "pl" ? pl : en);
return [
{ kind: "heading", text: t("Tryby pracy sygnalizacji", "Traffic Signal Operating Modes") },
{
kind: "paragraph",
text: t(
"Cztery fazy opisują pracę pojedynczego skrzyżowania, niezależnie od trybu przejazdu ENABLED lub DISABLED. Celem zarządzania korytarzem jest zarówno skrócenie dojazdu służb, jak i ograniczenie blokowania kolejnych skrzyżowań przez ruch ogólny. Poniżej oddzielono rolę docelowego systemu od działania obecnej symulacji.",
"These four phases describe one intersection, separately from the ENABLED or DISABLED run mode. Corridor management aims to shorten emergency response and reduce downstream junction blocking by general traffic. Each phase below separates its intended traffic-management role from the current simulation behavior.",
),
},
{
kind: "table",
cards: true,
columns: [
t("Stan", "State"),
t("Faza", "Phase"),
t("Rola w zarządzaniu ruchem", "Traffic-management role"),
t("Obecna implementacja", "Current implementation"),
],
rows: [
[
"NORMAL",
t("Tryb normalny / bazowy", "Normal / Baseline Mode"),
t(
"Zwykłe plany sygnalizacji obsługują ruch, gdy skrzyżowanie nie ma aktywnego priorytetu korytarza ratunkowego.",
"Regular signal timing plans serve baseline traffic when no emergency corridor priority is active at the intersection.",
),
t(
"Symulowany program dwóch grup: 30 s zielonego, 3 s żółtego i 2 s all-red na grupę. Oczekujące żądanie samo nie zmienia stanu.",
"A simulated two-group programme: 30 s green, 3 s yellow and 2 s all-red per group. A pending request alone changes no reported state.",
),
],
[
"CLEARING",
t("Oczyszczanie przed przyjazdem", "Clearing Mode — Pre-arrival Queue Flushing"),
t(
"Docelowo wcześniejsze otwieranie faz na kolejnych skrzyżowaniach ma odprowadzać kolejki, aby pojazd uprzywilejowany napotkał ruchomy, drożny pas zamiast zatrzymanego ruchu. Koordynacja w przód ogranicza ryzyko przenoszenia zatoru na następne skrzyżowanie.",
"In the intended system, opening coordinated phases ahead of arrival flushes queued vehicles so the emergency vehicle reaches an open, moving lane. Preparing downstream junctions is intended to prevent displaced traffic from blocking the next intersection.",
),
t(
"Żądania kwalifikują się przy TTI ≤40 s; po akceptacji CLEARING kieruje ruch konfliktowy i pieszych na czerwone, a trasie pozostawia zwykły program. Kaskada obejmuje cele w przód do 250 m. PoC nie symuluje kolejek ani ich opróżniania i nie wymusza tu zielonego trasy.",
"Requests become eligible at TTI ≤40 s. After acceptance, CLEARING targets conflicting movements and pedestrians red while the route retains its ordinary programme. Cascade includes forward targets within 250 m. The PoC neither simulates queues and their discharge nor forces route green in this phase.",
),
],
[
"PRIORITY_GREEN",
t(
"Zielona fala / przejęcie priorytetu",
"Green Wave / Priority Mode — Corridor Preemption",
),
t(
"Utrzymanie zielonego dla zbliżającego się pojazdu ma umożliwić ciągły przejazd przez kluczowe skrzyżowania przygotowanego korytarza.",
"Holding route signals green for the approaching emergency vehicle aims to provide continuous passage through the prepared corridor’s critical intersections.",
),
t(
"Wymaga zaakceptowanego żądania, TTI ≤25 s i potwierdzenia pokazanych zielonych świateł trasy. Opóźnienia sterownika mogą zatrzymać pojazd, a nieudane żądanie daje STANDARD_FALLBACK tylko swoim celom. Nie jest to gwarancja nieprzerwanego przejazdu.",
"Requires an accepted request, TTI ≤25 s and confirmation that route heads are shown green. Controller delay may hold the vehicle; failed requests put only their targets into STANDARD_FALLBACK. Uninterrupted passage is not guaranteed.",
),
],
[
"RECOVERY",
t("Stabilizacja po przejeździe", "Recovery Mode — Post-passage Stabilization"),
t(
"Docelowe stopniowe przywracanie długości cykli i przesunięć fazowych ma ograniczać fale hamowania, wtórne przewężenia i wzajemne blokowanie skrzyżowań po przejeździe służb.",
"A deployment would gradually restore normal cycle lengths and offsets to limit traffic shockwaves, secondary bottlenecks and gridlock after emergency passage.",
),
t(
"Po przejechaniu ostatniej linii skrzyżowania objętego aktywnym priorytetem wraca od razu zwykły program; stan RECOVERY trwa domyślnie 15 s. Żółte i blokady pokazanych świateł nadal obowiązują. PoC nie interpoluje długości cykli ani offsetów i nie modeluje fal zatorowych.",
"After the last line of an actively prioritised intersection is passed, the ordinary programme resumes immediately; RECOVERY lasts 15 s by default. Shown-head yellow transitions and interlocks still apply. The PoC does not interpolate cycle lengths/offsets or model traffic shockwaves.",
),
],
],
},
];
}
Loading