mharisnaveed/iso15118_evcat

1. System shape

- This repo is a two-node ISO 15118 deployment: an EVCC process on one Raspberry Pi and a SECC process on another, connected only through a PLC bridge.

- The physical/data-link side is handled by the PLC network; the application side is the ISO 15118 session implemented in Python under iso15118_core.

2. Top-level deployment boundaries

- EVCC_Client/ contains the vehicle-side runner scripts.

- SECC_Master/ contains the charger-side runner scripts.

- config/ holds network and host setup for the Raspberry Pi/PLC environment.

- logs/ stores captured session logs and historical runs.

- iso15118_core/ is the actual protocol stack and custom battery-test extension layer.

3. Startup and process ownership

- Each side is a separate process with its own configuration and controller state; there is no shared memory between EVCC and SECC.

- The main.py modules under iso15118/evcc/ and iso15118/secc/ are the primary application entry points into the protocol stack.

4. Transport path

- Discovery starts with SDP over UDP multicast on link-local IPv6.

- After discovery, the nodes establish TCP, then upgrade to TLS 1.3 before exchanging V2G application messages.

- The transport layer is split cleanly into udp_client.py / udp_server.py and tcp_client.py / tcp_server.py.

5. Protocol engine and message model

- The repo follows the ISO 15118 layering: shared message definitions, schema-backed message types, and protocol state machines.

- iso15118/shared/messages/ and iso15118/shared/schemas/ define the protocol payloads for DIN SPEC, ISO 15118-2, and ISO 15118-20.

- The state-machine implementations live in evcc/states/ and secc/states/, separated by protocol version and energy-service family.

6. Session orchestration

- comm_session_handler.py on each side coordinates the session lifecycle: protocol negotiation, authorization, service discovery, service selection, and charge-loop execution.

- shared/comm_session.py holds the common session abstractions used by both roles.

- This is the main boundary where transport events are converted into protocol-state transitions.

7. Controller abstraction

- Both EVCC and SECC use controller interfaces to isolate protocol logic from the “real world.”

- controller/interface.py defines the expected controller contract, while controller/simulator.py provides simulated implementations.

- On the SECC side, ev_data.py and evse_data.py package the negotiated limits and runtime state that flow through the session.

8. Battery diagnostic extension layer

- The project’s main custom addition is shared/battery_diagnostics/, which implements a Value-Added Services framework on top of ISO 15118-20.

- registry.py routes a selected diagnostic service by service ID.

- base_service.py defines the service interface, and telemetry.py writes the final report.

- services/health_test.py is the implemented battery discharge-capacity service; EIS and HPPC are planned placeholders in the architecture.

9. Battery physics model

- battery_simulator.py is intentionally separated from protocol and service logic.

- It provides the SOC/voltage/thermal behavior used by the diagnostic service, so the protocol layer only sees charging/discharging commands and measured telemetry.

- This separation is important for diagramming: protocol state machine, diagnostic service sequencing, and battery model are three distinct layers.

10. Security and PKI

- Security is not optional glue here; it is part of the main architecture.

- shared/security.py, shared/pki/, and the cert config files support the TLS/Plug-and-Charge-style certificate chain.

- The repo includes certificate generation tooling and sample configs, indicating that security setup is an explicit deployment step, not a runtime afterthought.

11. Standard and version partitioning

- The implementation supports multiple standards branches: DIN SPEC, ISO 15118-2, and ISO 15118-20.

- The current project focus is ISO 15118-20 because it natively supports BPT and VAS, which are required for the discharge-based battery tests.

- This means there are parallel protocol trees, but the architecture is centered on ISO 15118-20 for the diagnostic use case.

12. Infrastructure and operational tooling

- docker-compose*.yml, Makefile, and .env files support local and containerized execution of the protocol stack.

- config/setup_plc_network.sh and config/dhcpcd.conf reflect the Raspberry Pi + PLC networking setup.

- tests/ covers protocol states, message validation, security, and the new diagnostic framework, showing that behavior is validated at both the standards and service layers.

13. External integration points

- The physical PLC hardware is the transport boundary to the real world.

- The current architecture also leaves room for future hardware/BMS integration, but today the diagnostic layer runs on the simulated battery model.

- Diagnostic telemetry is emitted as a JSON report at session end, which is the main data product produced outside the live protocol exchange.

14. How to draw the diagram

- Draw two separate runtime nodes: EVCC client and SECC master.

- Between them, show SDP discovery over UDP, then TCP/TLS 1.3, then the ISO 15118-20 session.

- Inside the SECC node, show the flow from session handler to controller to diagnostic service registry to battery simulator/telemetry.

- Inside the EVCC node, show the mirrored session/state machine path and the client-side controller/transport boundary.