SmartFlow · STSP Reference Implementation

Smart Traffic Synchronization Protocol — Reference Implementation v0.1

The open protocol for intelligent urban traffic signal coordination.

---

Author & Protocol Origin

Gustavo Angel Aldana Flores
Mexican citizen · Peachtree City, Georgia, USA
Protocol conceived: ~2015 · First implementation: May 1, 2026

STSP (Smart Traffic Synchronization Protocol) is an open, implementable standard for Infrastructure-to-Infrastructure (I2I) coordination between traffic signal nodes. It is the first open protocol addressing this layer — distinct from existing V2I standards (SAE J2735 SPaT/MAP, ETSI ITS-G5) which only inform vehicles of signal state.

Formal specification: draft-aldana-stsp-00
Published in the IETF Internet-Draft repository, May 1, 2026.

Attribution requirement: Any implementation of STSP must include the following notice in its documentation and source code:

Implements STSP, designed by Gustavo Angel Aldana Flores
(draft-aldana-stsp — https://datatracker.ietf.org/doc/draft-aldana-stsp/)

---

What is STSP?

STSP defines the language that traffic signals use to talk to each other.

Without STSP          │  With STSP
──────────────────────│──────────────────────────────────────
Each signal is        │  Signals form a federated network
isolated, fixed-timer │  coordinating phase transitions
                      │
No signal knows       │  Every signal knows its neighbors'
its neighbors         │  queue lengths and upcoming phases
                      │
No green wave         │  Green wave propagates automatically:
possible              │  Δt = distance / design_speed
                      │
Proprietary and       │  Open protocol — any city,
city-locked           │  any vendor, any country

---

Quick Start

Prerequisites

• Docker & Docker Compose
• ARM64 (Raspberry Pi 4/5, Apple Silicon) or x86_64
• 2GB RAM minimum · 4GB recommended

Run the full stack

git clone https://github.com/smartflow-stsp/reference.git
cd reference
docker compose up --build

Verify the engine is alive

curl http://localhost:8000/health

{
  "status": "ok",
  "uptime_s": 42.3,
  "sim_time_s": 38.1,
  "mode": "ADAPTIVE",
  "nodes": 20,
  "connected_clients": 0
}

Connect to the live STSP stream

# Install wscat
npm install -g wscat

# Connect
wscat -c ws://localhost:8765

Every 200ms you will receive a STATE_UPDATE broadcast:

{
  "type": "STATE_UPDATE",
  "sim_time": 142.3,
  "mode": "ADAPTIVE",
  "nodes": [
    {
      "id": "LOCAL-0-0",
      "ph": "NS_GREEN",
      "rm": 18400,
      "qns": 2,
      "qew": 0,
      "ts": 1746123456.789
    }
  ],
  "stats": {
    "completed": 47,
    "avg_wait_s": 8.3,
    "congestion_pct": 12.5
  }
}

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    STSP Reference Stack                     │
├─────────────┬───────────────────────────────────────────────┤
│ Engine      │ Python 3.12 · asyncio · WebSocket · REST API  │
│             │ AdaptiveController · GreenWaveCoordinator      │
├─────────────┼───────────────────────────────────────────────┤
│ Protocol    │ STSP/1.0 · JSON over WebSocket (RFC 6455)     │
│             │ Compact form · Standard form · Commands       │
├─────────────┼───────────────────────────────────────────────┤
│ Storage     │ TimescaleDB (metrics) · Redis (live state)    │
├─────────────┼───────────────────────────────────────────────┤
│ Events      │ Apache Kafka KRaft (no Zookeeper)             │
├─────────────┼───────────────────────────────────────────────┤
│ Dashboard   │ Grafana · real-time traffic metrics           │
├─────────────┴───────────────────────────────────────────────┤
│ Hardware    │ Raspberry Pi 4/5 · Apple Silicon · x86_64     │
└─────────────────────────────────────────────────────────────┘

Three-layer protocol model

LAYER 3 — Federation    Cross-city coordination · Federated Learning
                                     ↕  gRPC / TLS 1.3
LAYER 2 — Corridor      Green wave · 2-4 nodes · offset = D/V_design
                                     ↕  STSP/1.0 WebSocket
LAYER 1 — Node          Autonomous state machine · Degraded Mode
                        Adaptive phase control · STSP broadcast

---

Repository Structure

smartflow-stsp/
├── engine/
│   ├── main.py                 ← Engine entrypoint
│   ├── config.py               ← Environment configuration
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── models/
│   │   ├── intersection.py     ← Node state machine
│   │   └── network.py          ← Grid of intersections
│   ├── algorithms/
│   │   ├── adaptive.py         ← Adaptive phase controller
│   │   └── green_wave.py       ← Green wave coordinator
│   └── protocol/
│       └── stsp.py             ← STSP/1.0 message format
├── db/
│   └── init.sql                ← TimescaleDB schema
├── docs/
│   ├── STSP_SPEC.md            ← Protocol specification (summary)
│   ├── HARDWARE.md             ← Physical node requirements
│   └── SECURITY.md             ← Security considerations
├── simulator/                  ← Visual browser simulator
├── scripts/                    ← Utilities and tools
├── docker-compose.yml
├── LICENSE                     ← Apache 2.0
├── NOTICE                      ← Attribution notice (required)
└── README.md

---

STSP Commands (WebSocket)

Send JSON commands to the engine at ws://host:8765:

// Change operating mode
{"action": "set_mode", "mode": "ADAPTIVE"}
{"action": "set_mode", "mode": "FIXED"}

// Simulation speed (local sim only)
{"action": "set_speed", "speed": 3.0}

// Emergency override on a specific node
{"action": "emergency", "row": 2, "col": 1, "allow_ns": true}

// Full reset
{"action": "reset"}

---

REST API

Method	Endpoint	Description
GET	/health	Engine status and uptime
GET	/state	Full grid state (all nodes)
GET	/stats	Aggregated traffic metrics
POST	/mode	Change operating mode

---

Services

Service	Port	Description
STSP Engine WebSocket	8765	Live STSP broadcast
STSP Engine REST	8000	HTTP control API
Grafana Dashboard	3000	Real-time metrics
TimescaleDB	5432	Metrics storage
Kafka	9092	Event bus
Redis	6379	Live state cache

Grafana credentials: admin / smartflow

---

Hardware

This implementation has been validated on:

Platform	Architecture	RAM	Result
Raspberry Pi 4	ARM64	8GB	✅ Full stack
Apple Silicon M3 Pro	ARM64	18GB	✅ Full stack

Minimum requirements for production node deployment:

• Raspberry Pi 4 (4GB RAM) or equivalent ARM64 SBC
• 5G / LTE connectivity with LoRaWAN fallback
• Solar panel + battery UPS (8h minimum autonomy)
• IP67 weatherproof enclosure
• GPS module for precise UTC synchronization

---

Roadmap

Phase 0 (now)     Reference implementation — this repository
Phase 1 (month 6) Physical pilot — 3-5 real intersections
Phase 2 (year 2)  Full corridor — 20-50 nodes, one city
Phase 3 (year 3)  Complete city + trained ML model
Phase 4 (year 5)  STSP Foundation + multi-city federation
Phase 5 (year 10) Global protocol standard

---

Contributing

STSP is an open protocol. Contributions to the reference implementation are welcome. All contributors must:

1. Agree to the Contributor License Agreement
2. Include the STSP attribution notice in any modified files
3. Not submit changes that restrict the open nature of the protocol

---

License

Copyright 2026 Gustavo Angel Aldana Flores

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

The STSP protocol specification (draft-aldana-stsp) is additionally
covered by CC BY 4.0. See NOTICE for attribution requirements.

See LICENSE and NOTICE for full details.

---

Citation

If you use STSP in academic work, please cite:

@techreport{aldana2026stsp,
  author      = {Aldana Flores, Gustavo Angel},
  title       = {{Smart Traffic Synchronization Protocol (STSP) Version 1.0}},
  type        = {Internet-Draft},
  number      = {draft-aldana-stsp-00},
  institution = {IETF},
  year        = {2026},
  month       = {May},
  url         = {https://datatracker.ietf.org/doc/draft-aldana-stsp/}
}

---

_{STSP was conceived by Gustavo Angel Aldana Flores circa 2015.
First implementation completed May 1, 2026 · Peachtree City, Georgia, USA.
draft-aldana-stsp-00 · IETF Datatracker}