From 07a437308ef2e5d052c3ceb054a14572c64242b7 Mon Sep 17 00:00:00 2001 From: fjarmula Date: Fri, 30 Oct 2026 10:16:10 +0100 Subject: [PATCH] docs: explain corridor benefits and signal operating modes --- README.md | 24 +++++- .../src/components/docs/docs-blocks.test.tsx | 9 +++ frontend/src/lib/docs/content.test.ts | 14 ++++ frontend/src/lib/docs/content.ts | 7 +- frontend/src/lib/docs/operating-modes.ts | 80 +++++++++++++++++++ 5 files changed, 128 insertions(+), 6 deletions(-) create mode 100644 frontend/src/lib/docs/operating-modes.ts diff --git a/README.md b/README.md index 6238db7..2675b7f 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/frontend/src/components/docs/docs-blocks.test.tsx b/frontend/src/components/docs/docs-blocks.test.tsx index c6cc8ec..f5172b9 100644 --- a/frontend/src/components/docs/docs-blocks.test.tsx +++ b/frontend/src/components/docs/docs-blocks.test.tsx @@ -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(); + for (const state of ["NORMAL", "CLEARING", "PRIORITY_GREEN", "RECOVERY"]) + expect(html).toContain(`class="docs-card-label">${state}`); + } +}); diff --git a/frontend/src/lib/docs/content.test.ts b/frontend/src/lib/docs/content.test.ts index 5a9a4b2..6c28671 100644 --- a/frontend/src/lib/docs/content.test.ts +++ b/frontend/src/lib/docs/content.test.ts @@ -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")); +}); diff --git a/frontend/src/lib/docs/content.ts b/frontend/src/lib/docs/content.ts index c3ac30b..2f74261 100644 --- a/frontend/src/lib/docs/content.ts +++ b/frontend/src/lib/docs/content.ts @@ -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"; @@ -81,7 +82,7 @@ export const docsContent: Record = { 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", @@ -270,6 +271,7 @@ export const docsContent: Record = { 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", @@ -424,7 +426,7 @@ export const docsContent: Record = { 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", @@ -613,6 +615,7 @@ export const docsContent: Record = { 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", diff --git a/frontend/src/lib/docs/operating-modes.ts b/frontend/src/lib/docs/operating-modes.ts new file mode 100644 index 0000000..2a6a60c --- /dev/null +++ b/frontend/src/lib/docs/operating-modes.ts @@ -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.", + ), + ], + ], + }, + ]; +}