diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml index a80890c..827c0e1 100644 --- a/.gitea/workflows/release.yml +++ b/.gitea/workflows/release.yml @@ -25,19 +25,19 @@ jobs: - name: Tag from ref run: echo "TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV - - name: Build + Tests + Coverage + Test-Report + - name: Build + tests + coverage + Test-Report run: | make test make coverage make test-report - - name: Traceability + Diagramme + API-Doc + - name: Traceability + diagrams + API doc run: | python3 tools/traceability.py publish docs/traceability python3 tools/render_plantuml.py make docs - - name: Cppcheck-Report (XML + HTML) + - name: Cppcheck Report (XML + HTML) run: | mkdir -p build cppcheck --enable=all --inconclusive --xml --xml-version=2 \ @@ -48,15 +48,15 @@ jobs: --source-dir=. \ --title="demo-epb Cppcheck Report" || echo "htmlreport skipped" - - name: Landing-Page + - name: Landing page run: make landing-page - - name: Release-Bundle paketieren + - name: Package release bundle run: | BUNDLE="release/demo-epb-${TAG}" mkdir -p "$BUNDLE"/{coverage,traceability,diagrams,api-doc,reports/cppcheck,docs,src,tests} - # Landing-Page (Startseite) im Bundle-Root + # Landing page in the bundle root cp build/index.html "$BUNDLE/index.html" # CI-generierte Artefakte @@ -73,7 +73,7 @@ jobs: cp -r src/*.c src/*.h "$BUNDLE/src/" 2>/dev/null || true cp -r src/stubs "$BUNDLE/src/" 2>/dev/null || true - # Alle Word-Dokumente (Plaene, Safety, Manuals, Audit-Artefakte) + # All Word documents (plans, safety, manuals, audit artefacts) mkdir -p "$BUNDLE/docs/plaene" "$BUNDLE/docs/safety" "$BUNDLE/docs/manuals" \ "$BUNDLE/docs/reviews" "$BUNDLE/docs/non-conformities" "$BUNDLE/misra/records" cp -r docs/plaene/* "$BUNDLE/docs/plaene/" 2>/dev/null || true @@ -93,55 +93,55 @@ jobs: ls -la release/ - - name: Release-Notes generieren + - name: Generate release notes run: | cat > release/RELEASE_NOTES.md <&1 | head -1 || echo " (kein gcc)" - make --version 2>&1 | head -1 || echo " (kein make)" - cppcheck --version 2>&1 | head -1 || echo " (kein cppcheck)" + gcc --version 2>&1 | head -1 || echo " (no gcc)" + make --version 2>&1 | head -1 || echo " (no make)" + cppcheck --version 2>&1 | head -1 || echo " (no cppcheck)" echo "done" - - name: Static Analysis (Cppcheck) + - name: Static analysis (Cppcheck) shell: bash run: make static - - name: MISRA Check + - name: MISRA check shell: bash run: | - make misra || echo "MISRA findings present (Demo non-failing)" + make misra || echo "MISRA findings present (demo non-failing)" - - name: Build + Unit Tests + - name: Build + unit tests shell: bash run: make test - # Coverage, Traceability, Diagrams, API-Doc, Test-Report — alle auf Linux, - # parallel zu build-test (Matrix continue-on-error wird leider nicht in needs durchgereicht) + # Coverage, traceability, diagrams, API doc, test report — all on Linux, + # parallel to build-test (matrix continue-on-error is not propagated through needs) reports: runs-on: ubuntu-latest steps: @@ -67,39 +67,39 @@ jobs: python3 python3-pip ca-certificates \ doxygen graphviz - - name: Build + Tests + Coverage + - name: Build + tests + coverage run: | make test make coverage - - name: Test-Summary-Report + - name: Test summary report run: make test-report - - name: Traceability Check + - name: Traceability check run: python3 tools/traceability.py check - - name: Traceability Matrix publishen + - name: Publish Traceability Matrix run: python3 tools/traceability.py publish docs/traceability - - name: PlantUML Diagramme rendern + - name: Render PlantUML diagrams run: python3 tools/render_plantuml.py - - name: Doxygen API-Dokumentation + - name: Doxygen API documentation run: make docs - - name: Cppcheck-Report (XML + HTML) + - name: Cppcheck Report (XML + HTML) run: | mkdir -p build cppcheck --enable=all --inconclusive --xml --xml-version=2 \ -I src src 2> build/cppcheck-report.xml || true - # cppcheck-htmlreport ist Teil des cppcheck-Pakets + # cppcheck-htmlreport is part of the cppcheck package cppcheck-htmlreport \ --file=build/cppcheck-report.xml \ --report-dir=build/cppcheck-html \ --source-dir=. \ --title="demo-epb Cppcheck Report" || echo "htmlreport skipped" - - name: Landing-Page + - name: Landing page run: make landing-page - name: Upload Coverage HTML @@ -109,7 +109,7 @@ jobs: name: coverage-html path: build/coverage-html/ - - name: Upload Test-Report + - name: Upload Test Report uses: actions/upload-artifact@v3 if: always() with: @@ -126,40 +126,40 @@ jobs: name: traceability path: docs/traceability/ - - name: Upload Architektur-Diagramme + - name: Upload Architecture Diagrams uses: actions/upload-artifact@v3 if: always() with: name: architecture-diagrams path: docs/diagrams/ - - name: Upload Doxygen API-Doc + - name: Upload Doxygen API Doc uses: actions/upload-artifact@v3 if: always() with: name: api-doc path: build/api-doc/html/ - - name: Upload Landing-Page + - name: Upload Landing Page uses: actions/upload-artifact@v3 if: always() with: name: landing-page path: build/index.html - - name: Upload Cppcheck-Report + - name: Upload Cppcheck Report uses: actions/upload-artifact@v3 if: always() with: name: cppcheck-report path: build/cppcheck-report.xml - - name: Deploy zu gitea.slohmaier.com/pages/demo-epb/ + - name: Deploy to gitea.slohmaier.com/pages/demo-epb/ if: success() && github.ref == 'refs/heads/main' run: | DEPLOY=/var/www/pages/demo-epb if [ ! -d "$DEPLOY" ]; then - echo "Mount $DEPLOY nicht da — Runner-Config pruefen. Skip." + echo "Mount $DEPLOY not present — check runner config. Skipping." exit 0 fi mkdir -p "$DEPLOY"/{docs,coverage,traceability,diagrams,api-doc,reports/cppcheck,src,misra/records} diff --git a/Makefile b/Makefile index 71f8eb5..38f9874 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ -# Makefile fuer demo-epb. Bewusst klein gehalten, damit der Demo -# ohne externe Build-Tools (CMake, SCons) auf jedem POSIX-System baut. +# Makefile for demo-epb. Intentionally small so the demo +# builds on any POSIX system without external build tools (CMake, SCons). CC ?= cc CFLAGS ?= -std=c99 -Wall -Wextra -Werror -Wpedantic \ diff --git a/README.md b/README.md index 1fddd5b..68ee3bc 100644 --- a/README.md +++ b/README.md @@ -1,139 +1,141 @@ -# demo-epb — Elektrische Parkbremse +# demo-epb — Electric Parking Brake -Vollständige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) anhand einer EPB-Steuergerät-Software. Zeigt ASPICE 4.0 / ISO 26262-konforme Entwicklung im Monorepo: Anforderungen, Architektur, Code, Tests, Reviews, MISRA, Safety Case, Manuals — alles auf einen Pull-Request-Klick verifizierbar, alles in einem Release-Bundle. +Complete demonstration of the [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) using an EPB ECU software. Shows ASPICE 4.0 / ISO 26262-compliant development in a monorepo: requirements, architecture, code, tests, reviews, MISRA, safety case, manuals — all verifiable in a single pull-request click, all in a single release bundle. -> **🌐 Live-Dashboard:** https://gitea.slohmaier.com/pages/demo-epb/ -> Auto-aktualisiert bei jedem Push auf `main` und bei jedem Release-Tag. +> **🌐 Live dashboard:** https://gitea.slohmaier.com/pages/demo-epb/ +> Auto-refreshed on every push to `main` and every release tag. -> Diese Software ist **bewusst kein Produktivcode** — sie ist die Demonstration des Engineering-Verfahrens. Code-Umfang bewusst klein, Prozess-Tiefe vollständig. +> This software is **intentionally not production code** — it is a demonstration of the engineering method. Code volume kept small on purpose; process depth complete. -## Was die Demo zeigt +## What the demo shows -| Kategorie | Inhalt | -|-----------|--------| -| **Pläne** (Word) | 5 (PID, PM-, QA-, SWE-, Test-Plan) | -| **Safety-Doku** (Word) | 6 (HARA, Safety Case, FMEDA, MISRA-Compliance, Verification-Report, Tool-Qualification) | -| **Manuals** (Word) | 2 (User-Manual, Service-Manual) | -| **Audit-Artefakte** (Word) | 3 (Review-Protokoll, Non-Conformity, MISRA-Deviation-Record) | -| **System-Anforderungen** | 10 in `reqs/sys/` (Markdown + Doorstop-Style) | -| **Software-Anforderungen** | 25 in `reqs/swe/` | -| **System-Architektur** | 5 in `arch/sys/` mit PlantUML | -| **Software-Architektur** | 10 in `arch/swe/` mit PlantUML | -| **Implementierte C-Komponenten** | 4 (Apply Ctrl D, Safety Mgr D, Actuator Drv B, Switch Db QM) | -| **Stub-Komponenten** | 6 weitere (Header only) | -| **Unit-Tests** | 41, alle grün | -| **CI-Workflows** | 2 (validate + release) | -| **CI-Artefakte** | Coverage HTML, Traceability Matrix, Diagramme SVG, Doxygen, Test-Report, Cppcheck-XML | -| **Cross-Platform-Runner** | Linux + macOS + Windows | +| Category | Content | +|----------|---------| +| **Plans** (Word) | 8 (Project Manual, PID, PM, QA, SWE, Test, CM, RM) | +| **Safety docs** (Word) | 6 (HARA, Safety Case, FMEDA, MISRA Compliance, Verification Report, Tool Qualification) | +| **Manuals** (Word) | 2 (User Manual, Service Manual) | +| **Audit artefacts** (Word) | 3 (Review minutes, Non-Conformity, MISRA Deviation Record) | +| **Safety Goals** | 5 in `safety/sg/` | +| **System Requirements** | 10 in `reqs/sys/` (Markdown + Doorstop style) | +| **Software Requirements** | 25 in `reqs/swe/` | +| **System Architecture** | 5 in `arch/sys/` with PlantUML | +| **Software Architecture** | 10 in `arch/swe/` with PlantUML | +| **Implemented C components** | 4 (Apply Ctrl D, Safety Mgr D, Actuator Drv B, Switch Db QM) | +| **Stub components** | 6 more (header only) | +| **Unit tests** | 46, all green | +| **CI workflows** | 2 (validate + release) | +| **CI artefacts** | Coverage HTML, Traceability Matrix, Diagrams SVG, Doxygen, Test Report, Cppcheck HTML+XML | +| **Cross-platform runners** | Linux + macOS + Windows | -## Quick Start +## Quick start ```bash git clone https://gitea.slohmaier.com/slohmaier/demo-epb.git cd demo-epb # Tests -make test # 41 Tests, alle grün +make test # 46 tests, all green -# Mit Coverage (braucht lcov) +# With coverage (needs lcov) make coverage open build/coverage-html/index.html -# Test-Summary-Report (HTML) +# Test summary report (HTML) make test-report open build/test-report.html -# Statische Analyse + MISRA (braucht cppcheck) +# Static analysis + MISRA (needs cppcheck) make static make misra -# API-Doku (braucht doxygen) +# API doc (needs doxygen) make docs open build/api-doc/html/index.html -# Traceability-Matrix (HTML) +# Traceability matrix (HTML) python3 tools/traceability.py publish docs/traceability open docs/traceability/index.html -# PlantUML-Diagramme rendern (SVG) +# PlantUML diagrams (SVG) python3 tools/render_plantuml.py ``` -## Geführte Tour (~30 min) +## Guided tour (~30 min) -### 1. Projektplanung (Word) -`docs/`: -- **PID.docx** — Was wird gebaut und warum -- **SWE-Plan.docx** — Sprache, Standards, Branching, Reviews, Coverage-Ziele -- **QA-Plan.docx** — Qualitätsmaßnahmen, Reviews, NC-Management -- **PM-Plan.docx**, **Test-Plan.docx** — Arbeitspakete + Teststrategie +### 1. Project planning (Word) +`docs/plaene/`: +- **Project-Manual.docx** — Navigation guide, reading order, roles +- **PID.docx** — What is built and why +- **SWE-Plan.docx** — Language, standards, branching, reviews, coverage targets +- **QA-Plan.docx** — Quality measures, reviews, NC management +- **PM-Plan.docx, Test-Plan.docx, CM-Plan.docx, RM-Plan.docx** -### 2. Funktionale Sicherheit (Word — `docs/safety/`) -- **HARA.docx** — Hazard Analysis & Risk Assessment. Leitet **ASIL-D** ab. -- **Safety-Case.docx** — Argumentation in GSN-Style, warum die Sicherheitsziele erfüllt sind -- **FMEDA.docx** — Pro-Komponente Failure Modes mit Diagnostic Coverage -- **Tool-Qualification-Cppcheck.docx** — Tool-Qual für Cppcheck (TI2/TD2/TCL2) -- **MISRA-Compliance-Statement.docx** — formaler Compliance-Nachweis -- **Verification-Report.docx** — V-Modell rechte Seite zusammenfassend +### 2. Functional safety (Word — `docs/safety/`) +- **HARA.docx** — Hazard Analysis & Risk Assessment. Derives **ASIL-D**. +- **Safety-Case.docx** — GSN-style argument that safety goals are met +- **FMEDA.docx** — Per-component failure modes with diagnostic coverage +- **Tool-Qualification-Cppcheck.docx** — Tool qual for Cppcheck (TI2/TD2/TCL2) +- **MISRA-Compliance-Statement.docx** — Formal compliance evidence +- **Verification-Report.docx** — V-model right side summary ### 3. Manuals (Word — `docs/manuals/`) -- **User-Manual.docx** — Fahrerhandbuch-Auszug (Apply, Release, Hill-Hold, LED-Codes) -- **Service-Manual.docx** — Werkstatt-Doku mit UDS-DTCs, Service-Modus, Sensor-Prüfung +- **User-Manual.docx** — Driver manual (apply, release, hill-hold, LED codes) +- **Service-Manual.docx** — Workshop doc with UDS DTCs, service mode, sensor checks -### 4. Sicherheits-Logik (das ASIL-D Stück) -Traceability-Kette: +### 4. Safety logic (the ASIL-D piece) +Traceability chain: ``` -reqs/sys/SYS-001.md → arch/swe/SWA-002.md → src/apply_controller.c → tests/unit/test_apply_controller.c +safety/sg/SG-001.md → reqs/sys/SYS-001.md → arch/swe/SWA-002.md → src/apply_controller.c → tests/unit/test_apply_controller.c ``` -### 5. Anforderungen + Architektur (Doorstop in Markdown) -- `reqs/sys/` + `reqs/swe/` — Anforderungen mit Mapping -- `arch/sys/` + `arch/swe/` — Architektur mit Mapping per `links:` im Frontmatter -- Eingebettete PlantUML-Diagramme rendern direkt in Gitea (UI) und als SVG im Release-Bundle +### 5. Requirements + architecture (Doorstop in Markdown) +- `safety/sg/`, `reqs/sys/` + `reqs/swe/` — requirements with mapping +- `arch/sys/` + `arch/swe/` — architecture with mapping via `links:` in frontmatter +- Embedded PlantUML diagrams render in Gitea (UI) and as SVG in the release bundle -### 6. Code mit Mapping-Tags -Jede `.c`-Datei trägt `@arch`, `@reqs`, `@asil` im Header: +### 6. Code with mapping tags +Every `.c` file carries `@arch`, `@reqs`, `@asil` in the header: ```c /** * @file apply_controller.c * @arch SWA-002 - * @reqs SWE-001 SWE-002 SWE-003 SWE-004 + * @reqs SWE-001 SWE-002 SWE-003 SWE-004 SWE-005 * * ASIL: D. */ ``` -### 7. Tests mit Anforderungs-Tags -`tests/unit/test_*.c` referenziert die Requirements per `@reqs`. Test-Report (`build/test-report.html`) macht das Mapping klickbar sichtbar. +### 7. Tests with requirement tags +`tests/unit/test_*.c` references requirements via `@reqs`. The test report (`build/test-report.html`) makes the mapping clickable. -### 8. Audit-Artefakte -- `docs/reviews/REV-001.docx` — Review-Protokoll für die ASIL-D-Komponente -- `docs/non-conformities/NC-001.docx` — NC mit Korrekturmaßnahme -- `misra/records/MISRA-REC-001.docx` — MISRA Advisory-Deviation +### 8. Audit artefacts +- `docs/reviews/REV-001.docx` — Review minutes for the ASIL-D component +- `docs/non-conformities/NC-001.docx` — NC with corrective action +- `misra/records/MISRA-REC-001.docx` — MISRA advisory deviation -### 9. CI-Pipeline (`.gitea/workflows/validate.yml`) -Bei jedem Push: -1. **Cross-Platform Build + Test** auf Linux + macOS + Windows -2. **Static Analysis** (Cppcheck) -3. **MISRA-Check** (Cppcheck + MISRA-Addon) +### 9. CI pipeline (`.gitea/workflows/validate.yml`) +On every push: +1. **Cross-platform build + test** on Linux + macOS + Windows +2. **Static analysis** (Cppcheck) +3. **MISRA check** (Cppcheck + MISRA addon) 4. **Coverage** (gcov/lcov) -5. **Traceability-Check** (bidirektional) -6. **PlantUML-Render** (alle Diagramme als SVG) -7. **Doxygen-API-Doc** -8. **Test-Summary-Report** +5. **Traceability check** (bidirectional) +6. **PlantUML render** (all diagrams as SVG) +7. **Doxygen API doc** +8. **Test summary report** -Alles als Gitea-Artefakte abrufbar. +All available as Gitea artefacts. -### 10. Release-Workflow (`.gitea/workflows/release.yml`) -Auf Tag-Push `v*.*.*`: -- Vollständigen Build + alle Reports -- Bündelt **Source-Archive + Artefakt-Archive** (CI-Output + alle Word-Docs) -- Erzeugt Gitea-Release mit Release-Notes +### 10. Release workflow (`.gitea/workflows/release.yml`) +On tag push `v*.*.*`: +- Full build + all reports +- Bundles **source archive + artefact archive** (CI output + all Word docs) +- Creates a Gitea release with release notes -Beispiel: https://gitea.slohmaier.com/slohmaier/demo-epb/releases +Example: https://gitea.slohmaier.com/slohmaier/demo-epb/releases -## Architektur-Überblick +## Architecture overview ``` EPB ECU (SA-001) @@ -150,28 +152,27 @@ Beispiel: https://gitea.slohmaier.com/slohmaier/demo-epb/releases | Logger (QM) [stub] | +----------------------------------+ | | - Aktor L (SA-002) Aktor R (SA-002) + Actuator L (SA-002) Actuator R (SA-002) ``` -## Format-Strategie +## Format strategy -| Inhalt | Format | Begründung | -|--------|--------|------------| -| Pläne + Safety + Audit + Manuals | **Word** (.docx) | Industriestandard für ISO-9001-Freigabe | -| Requirements + Architektur | **Markdown** (Doorstop-Stil) | Lebendig, diff-bar, Traceability per Skript | -| Code, Tests, CI | C / YAML | klar | -| Release-Bundle | tar.gz mit allem | Eine Datei für den Auditor | +| Content | Format | Rationale | +|---------|--------|-----------| +| Plans + Safety + Audit + Manuals | **Word** (.docx) | Industry standard for ISO 9001 release | +| Requirements + Architecture | **Markdown** (Doorstop style) | Lives daily, diff-able, traceability by script | +| Code, Tests, CI | C / YAML | obvious | +| Release bundle | tar.gz with everything | One file for the auditor | -Markdown ist Source of Truth, Word wird per pandoc daraus gebaut. +Markdown is the source of truth; Word is built via pandoc. -## Referenzen +## References -- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — Methodik-Repo +- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — Methodology repo - ASPICE 4.0 -- ISO 26262 (insbesondere Part 2, 3, 5, 6, 8, 10) +- ISO 26262 (in particular Part 2, 3, 5, 6, 8, 10) - MISRA C:2012 -## Lizenz +## Licence -MIT — siehe [LICENSE](LICENSE). -Tue May 12 02:28:37 PDT 2026 +MIT — see [LICENSE](LICENSE). diff --git a/docs/manuals-md/Service-Manual.md b/docs/manuals-md/Service-Manual.md index 736641d..3376144 100644 --- a/docs/manuals-md/Service-Manual.md +++ b/docs/manuals-md/Service-Manual.md @@ -1,138 +1,138 @@ --- doc-id: SLM-EPB-SVC-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- -# Service Manual — Elektrische Parkbremse (EPB) +# Service Manual — Electric Parking Brake (EPB) -| Feld | Wert | -|--------------|----------------------------------------| -| Produkt | demo-epb EPB-Steuergeraet | -| Version | 1.0 | -| Datum | 2026-05-12 | -| Zielgruppe | Werkstatt-Techniker | +| Field | Value | +|---------------|----------------------------------------| +| Product | demo-epb EPB ECU | +| Version | 1.0 | +| Date | 2026-05-12 | +| Audience | Workshop technicians | --- -## 1. Werkzeuge +## 1. Tools -- OBD-II-Diagnose-Tester mit UDS-Support (ISO 14229) -- Drehmomentschluessel 60 Nm -- Verschiebewerkzeug 28x40 mm (fuer Bremsbelag-Wechsel) +- OBD-II diagnostic tester with UDS support (ISO 14229) +- Torque wrench 60 Nm +- Sliding tool 28×40 mm (for brake-pad replacement) -## 2. UDS-Diagnose +## 2. UDS diagnostics -### 2.1 Identifikation +### 2.1 Identification -| Parameter | Wert | +| Parameter | Value | |-------------------|-------------| -| Tester-Adresse | 0x712 | -| ECU-Antwort | 0x71A | -| CAN-Baudrate | 500 kbit/s | +| Tester address | 0x712 | +| ECU response | 0x71A | +| CAN baud rate | 500 kbit/s | -### 2.2 Service-IDs +### 2.2 Service IDs -| SID | Service | Notizen | -|------|-------------------------------|-------------------------------| -| 0x10 | DiagnosticSessionControl | 0x03 = Extended Session | -| 0x11 | ECUReset | 0x01 = Hard Reset | -| 0x14 | ClearDiagnosticInformation | Loescht alle DTCs | +| SID | Service | Notes | +|------|-------------------------------|--------------------------------| +| 0x10 | DiagnosticSessionControl | 0x03 = Extended Session | +| 0x11 | ECUReset | 0x01 = Hard Reset | +| 0x14 | ClearDiagnosticInformation | Clears all DTCs | | 0x19 | ReadDTCInformation | Sub 0x02 = reportDTCByStatusMask | -| 0x22 | ReadDataByIdentifier | Siehe DID-Liste | -| 0x27 | SecurityAccess | Nicht implementiert in Demo | -| 0x31 | RoutineControl | 0x0301 = Service-Modus | +| 0x22 | ReadDataByIdentifier | See DID list | +| 0x27 | SecurityAccess | Not implemented in demo | +| 0x31 | RoutineControl | 0x0301 = Service mode | ### 2.3 DIDs (Data Identifiers) -| DID | Beschreibung | Typ | -|--------|-------------------------------------|----------------| -| 0xF187 | SW-Version | ASCII 16 byte | -| 0xF18B | ECU-Hardware-Version | ASCII 16 byte | -| 0x0301 | Klemmkraft links | uint16 (N) | -| 0x0302 | Klemmkraft rechts | uint16 (N) | -| 0x0303 | Motorstrom links | uint16 (mA) | -| 0x0304 | Motorstrom rechts | uint16 (mA) | -| 0x0305 | Inclinometer (gefiltert) | int16 (m°) | +| DID | Description | Type | +|--------|--------------------------------------|----------------| +| 0xF187 | SW version | ASCII 16 byte | +| 0xF18B | ECU hardware version | ASCII 16 byte | +| 0x0301 | Clamping force left | uint16 (N) | +| 0x0302 | Clamping force right | uint16 (N) | +| 0x0303 | Motor current left | uint16 (mA) | +| 0x0304 | Motor current right | uint16 (mA) | +| 0x0305 | Inclinometer (filtered) | int16 (m°) | -## 3. DTC-Liste +## 3. DTC list -| DTC | Bedeutung | Aktion | -|----------|--------------------------------------------------|----------------------------------------| -| P0571 | EPB-Schalter Plausibilitaet | Schalter pruefen | -| P0572 | EPB-Schalter dauerhaft betaetigt | Schalter blockiert? Reinigen | -| P0808 | Aktor-Strom links zu hoch (Overcurrent) | Motor + Verkabelung pruefen | -| P0809 | Aktor-Strom rechts zu hoch (Overcurrent) | Motor + Verkabelung pruefen | -| P080A | Klemmkraft links nicht erreicht (Apply-Timeout) | Aktor / Mechanik pruefen | -| P080B | Klemmkraft rechts nicht erreicht | Aktor / Mechanik pruefen | -| P080C | Wheel-Speed-Sensor Plausibilitaet | Sensoren / Verkabelung pruefen | -| P080D | Inclinometer Plausibilitaet | Sensor / Montage pruefen | -| P080E | Apply-Controller-Watchdog-Trip | Software-Reset, bei Wiederholung ECU tauschen | -| U0123 | CAN-Bus-Kommunikation verloren | CAN-Verkabelung + BCM-Status | +| DTC | Meaning | Action | +|----------|---------------------------------------------------|----------------------------------------| +| P0571 | EPB switch plausibility | Check switch | +| P0572 | EPB switch permanently actuated | Switch jammed? Clean | +| P0808 | Actuator current left too high (overcurrent) | Check motor + wiring | +| P0809 | Actuator current right too high (overcurrent) | Check motor + wiring | +| P080A | Clamping force left not reached (apply timeout) | Check actuator / mechanism | +| P080B | Clamping force right not reached | Check actuator / mechanism | +| P080C | Wheel-speed sensor plausibility | Check sensors / wiring | +| P080D | Inclinometer plausibility | Check sensor / mounting | +| P080E | Apply controller watchdog trip | Software reset; if recurring replace ECU | +| U0123 | CAN bus communication lost | Check CAN wiring + BCM status | -## 4. Service-Modus (Bremsbelag-Wechsel) +## 4. Service mode (brake-pad replacement) -### 4.1 Aktivierung +### 4.1 Activation -Voraussetzungen: -- Zuendung an, Motor aus -- Fahrzeug auf der Buehne oder mit gesicherten Raedern -- Fahrertuer geschlossen (oder Tuer-Signal ueberbrueckt) +Preconditions: +- Ignition on, engine off +- Vehicle on lift or with chocked wheels +- Driver door closed (or door signal bypassed) -Schritte: -1. Diagnose-Tester verbinden, Extended Session (0x10 0x03) -2. RoutineControl `0x31 01 03 01` senden — Start Routine -3. ECU bestaetigt, EPB-LED beginnt mit 2 Hz zu blinken -4. Aktoren fahren in Wartungs-Position (vollstaendig geloest) +Steps: +1. Connect diagnostic tester, Extended Session (0x10 0x03) +2. Send RoutineControl `0x31 01 03 01` — start routine +3. ECU acknowledges, EPB LED starts blinking at 2 Hz +4. Actuators move to maintenance position (fully released) -### 4.2 Deaktivierung +### 4.2 Deactivation -1. RoutineControl `0x31 02 03 01` senden — Stop Routine -2. EPB-LED beendet das Blinken -3. Apply-Funktion wieder verfuegbar +1. Send RoutineControl `0x31 02 03 01` — stop routine +2. EPB LED stops blinking +3. Apply function available again -### 4.3 Bremsbelag-Wechsel-Ablauf +### 4.3 Brake-pad replacement procedure -1. Service-Modus aktivieren (siehe oben) -2. Bremssattel demontieren -3. Belaege wechseln, Fuehrungen schmieren -4. Bremssattel mit 60 Nm anziehen -5. Service-Modus deaktivieren -6. Drei Apply/Release-Zyklen durchfuehren (zum Einschleifen) -7. DTC-Speicher leeren (Service 0x14) +1. Activate service mode (see above) +2. Remove brake calliper +3. Replace pads, grease guides +4. Tighten calliper to 60 Nm +5. Deactivate service mode +6. Perform three apply/release cycles (bedding-in) +7. Clear DTC memory (service 0x14) -## 5. Sensor-Pruefung +## 5. Sensor check -### 5.1 Wheel-Speed-Sensoren +### 5.1 Wheel-speed sensors -- Widerstand: 800-1500 Ω bei 20 °C -- Spannung bei 50 km/h: 2-5 V Peak-to-Peak (Hall) +- Resistance: 800-1500 Ω at 20 °C +- Voltage at 50 km/h: 2-5 V peak-to-peak (Hall) ### 5.2 Inclinometer -- SPI-Bus 1 MHz -- Erwarteter Wert auf ebener Strasse: 0 ± 0.5° -- Drift-Check: ECU + Tester, > 5 Min Beobachtung +- SPI bus 1 MHz +- Expected value on level road: 0 ± 0.5° +- Drift check: ECU + tester, monitor > 5 min -## 6. Aktor-Pruefung +## 6. Actuator check -| Parameter | Sollwert | +| Parameter | Target value | |-----------------------|------------------------| -| Widerstand pro Motor | 0.8 – 1.2 Ω | -| Stromaufnahme nominal | 3 – 5 A | -| Stromspitze (Apply) | 15 – 25 A | -| Cutoff-Schwelle | 8 A fuer 100 ms | +| Resistance per motor | 0.8 – 1.2 Ω | +| Nominal current | 3 – 5 A | +| Peak current (apply) | 15 – 25 A | +| Cutoff threshold | 8 A for 100 ms | -## 7. Software-Update +## 7. Software update 1. UDS Extended Session (0x10 0x03) 2. Programming Session (0x10 0x02) -3. Flashloader-Sequenz nach OEM-Spezifikation -4. Neue SW-Version per DID 0xF187 verifizieren +3. Flashloader sequence per OEM specification +4. Verify new SW version via DID 0xF187 -## 8. Aenderungshistorie +## 8. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|---------------------|-------------| -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 1.0 | 2026-05-12 | First release | S. Lohmaier| diff --git a/docs/manuals-md/User-Manual.md b/docs/manuals-md/User-Manual.md index bec48ca..6ebff32 100644 --- a/docs/manuals-md/User-Manual.md +++ b/docs/manuals-md/User-Manual.md @@ -1,114 +1,105 @@ --- doc-id: SLM-EPB-USR-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- -# Bedienungsanleitung — Elektrische Parkbremse (EPB) +# User Manual — Electric Parking Brake (EPB) -| Feld | Wert | -|--------------|----------------------------------------| -| Produkt | demo-epb EPB-Steuergeraet | -| Version | 1.0 | -| Datum | 2026-05-12 | -| Zielgruppe | Fahrzeugfuehrer | +| Field | Value | +|---------------|----------------------------------------| +| Product | demo-epb EPB ECU | +| Version | 1.0 | +| Date | 2026-05-12 | +| Audience | Vehicle drivers | --- -> **Wichtige Sicherheitshinweise lesen!** -> Bevor Sie die EPB verwenden, machen Sie sich mit den Funktionen vertraut. +> **Read the important safety information first!** +> Familiarise yourself with the functions before using the EPB. -## 1. Was ist die Elektrische Parkbremse? +## 1. What is the Electric Parking Brake? -Die Elektrische Parkbremse (EPB) ersetzt die klassische Handbremse. Sie wird -ueber einen Schalter in der Mittelkonsole bedient und klemmt die hinteren -Bremsen elektromechanisch fest. +The Electric Parking Brake (EPB) replaces the classical handbrake. You operate it via a switch in the centre console; the system clamps the rear brakes electromechanically. -## 2. Bedienung +## 2. Operation -### 2.1 Parkbremse einlegen (Apply) +### 2.1 Engage the parking brake (apply) -1. Fahrzeug zum Stillstand bringen. -2. Bremspedal getreten halten. -3. EPB-Schalter **nach oben** ziehen (Pfeil zeigt zur Frontscheibe). -4. Die rote LED am Schalter leuchtet dauerhaft. +1. Bring the vehicle to a complete standstill. +2. Keep the brake pedal pressed. +3. Pull the EPB switch **upwards** (arrow points to the windshield). +4. The red LED on the switch lights up steadily. -Sie hoeren ein leichtes Brummen — das sind die Stellmotoren. +You will hear a soft humming sound — that is the actuator motors. -### 2.2 Parkbremse loesen (Release) +### 2.2 Release the parking brake -**Voraussetzungen** (alle muessen erfuellt sein): +**Preconditions** (all must be met): -- Motor laeuft -- Bremspedal ist betaetigt -- Gangwahlhebel ist eingelegt (kein Leerlauf) +- Engine is running +- Brake pedal is pressed +- Gear selector is engaged (not in neutral) -1. EPB-Schalter **nach unten** druecken. -2. Die LED erlischt. -3. Sie hoeren erneut ein kurzes Brummen. +1. Push the EPB switch **downwards**. +2. The LED goes out. +3. You will hear a short humming sound again. -### 2.3 Auto-Hold (Fahrer steigt aus) +### 2.3 Auto-Hold (driver leaving the car) -Wenn Sie den Motor abschalten und das Fahrzeug stillsteht, wird die EPB -**automatisch nach 2 Sekunden** eingelegt — auch wenn Sie sie nicht manuell -betaetigt haben. Die LED leuchtet als Bestaetigung. +When you switch the engine off and the vehicle is at a standstill, the EPB engages **automatically after 2 seconds** — even if you didn't operate it manually. The LED confirms. -### 2.4 Hill-Hold am Berg +### 2.4 Hill-Hold on inclines -Beim Anhalten an einer Steigung (> 5 %): +When stopping on a slope (> 5%): -1. Bremspedal treten — Fahrzeug haelt. -2. Fuss vom Bremspedal nehmen — die EPB uebernimmt automatisch. -3. Die LED blinkt langsam waehrend Hill-Hold aktiv ist. -4. Beim Anfahren (Gasgeben + Gang eingelegt) loest die EPB automatisch. +1. Press the brake pedal — vehicle stops. +2. Lift your foot off the brake pedal — the EPB takes over automatically. +3. The LED blinks slowly while hill-hold is active. +4. On drive-away (throttle + gear engaged), the EPB releases automatically. -## 3. Bedeutung der LED-Anzeige +## 3. LED indicator meaning -| LED-Status | Bedeutung | -|-----------------------|--------------------------------------------------| -| Aus | EPB geloest | -| Dauerleuchtend rot | EPB aktiv (Apply / Hold) | -| Langsam blinkend (2 Hz) | Hill-Hold aktiv oder Service-Modus | -| Schnell blinkend (4 Hz) | Fehler — bitte Werkstatt aufsuchen | +| LED status | Meaning | +|-------------------------|---------------------------------------------------| +| Off | EPB released | +| Steady red | EPB active (apply / hold) | +| Slow blink (2 Hz) | Hill-hold active or service mode | +| Fast blink (4 Hz) | Fault — visit a workshop | -## 4. Anzeige im Kombi-Display +## 4. Display in the instrument cluster -Das Kombi-Display zeigt zusaetzliche Texte: +The instrument cluster shows additional text: -| Anzeige | Bedeutung | -|------------------------|---------------------------------------------| -| "EPB aktiv" | Parkbremse eingelegt | -| "Hill-Hold aktiv" | Hill-Hold uebernimmt | -| "EPB Fehler" | Stoerung — siehe Werkstatt | -| "EPB Service-Modus" | Im Werkstatt-Modus, nicht selbst loesen | +| Text | Meaning | +|---------------------------|-------------------------------------------| +| "EPB active" | Parking brake engaged | +| "Hill-Hold active" | Hill-hold is taking over | +| "EPB fault" | Fault — visit a workshop | +| "EPB service mode" | In workshop mode, do not release yourself | -## 5. Notbetrieb +## 5. Emergency mode -Sollte die EPB nicht reagieren: +If the EPB does not respond: -- **Sie steht und kommt nicht weg:** EPB-Schalter mehrmals nach unten druecken; - bei Misserfolg Notabschleppdienst rufen. -- **Sie steht und EPB greift nicht:** Fahrzeug mit Unterlegkeil sichern, - Werkstatt kontaktieren. +- **Stationary and won't move:** push the EPB switch downwards several times; if unsuccessful, call breakdown service. +- **Stationary and the EPB does not engage:** secure the vehicle with wheel chocks, contact a workshop. -## 6. Sicherheitshinweise +## 6. Safety information -> **⚠ WARNUNG** +> **⚠ WARNING** > -> - EPB ersetzt nicht das Anziehen des Gangs beim Parken -> - Auf glatten Untergruenden zusaetzlich Unterlegkeile verwenden -> - Bei laufendem Motor und eingelegter EPB nicht ueber dem -> Bremspedal stehen lassen +> - The EPB does not replace engaging a gear when parking +> - On slippery surfaces additionally use wheel chocks +> - While the engine is running and the EPB is engaged, do not stand on the brake pedal long-term -## 7. Wartung +## 7. Maintenance -Die EPB ist wartungsfrei. Bei Bremsbelagwechsel muss die Werkstatt den -**Service-Modus** aktivieren — bitte das Fahrzeug nicht selbst aufbocken, -solange die EPB im aktiven Zustand ist. +The EPB is maintenance-free. For brake pad replacement, the workshop must activate **service mode** — please do not jack up the vehicle yourself while the EPB is in the active state. -## 8. Aenderungshistorie +## 8. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|---------------------|-------------| -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 1.0 | 2026-05-12 | First release | S. Lohmaier| diff --git a/docs/manuals/Service-Manual.docx b/docs/manuals/Service-Manual.docx index 1829e2b..a6022a6 100644 Binary files a/docs/manuals/Service-Manual.docx and b/docs/manuals/Service-Manual.docx differ diff --git a/docs/manuals/User-Manual.docx b/docs/manuals/User-Manual.docx index a7c9760..925baf5 100644 Binary files a/docs/manuals/User-Manual.docx and b/docs/manuals/User-Manual.docx differ diff --git a/docs/non-conformities-md/NC-001.md b/docs/non-conformities-md/NC-001.md index 2881ecc..d67926e 100644 --- a/docs/non-conformities-md/NC-001.md +++ b/docs/non-conformities-md/NC-001.md @@ -1,60 +1,52 @@ --- nc-id: NC-001 -projekt: demo-epb -datum-festgestellt: 2026-05-11 -schwere: Critical +project: demo-epb +date-discovered: 2026-05-11 +severity: Critical status: Closed --- -# Non-Conformity NC-001: Step-Counter-Ueberlauf nicht dokumentiert +# Non-Conformity NC-001: Step counter overflow not documented -| Feld | Wert | +| Field | Value | |---------------------|-----------------------------------| -| NC-ID | NC-001 | -| Projekt | demo-epb | -| Datum festgestellt | 2026-05-11 | -| Festgestellt durch | Review REV-001 | -| Betroffenes Artefakt| `src/apply_controller.c` | -| Anforderung | SWE-002 (Watchdog) | -| Schwere | Critical | +| NC ID | NC-001 | +| Project | demo-epb | +| Date discovered | 2026-05-11 | +| Discovered by | Review REV-001 | +| Affected artefact | `src/apply_controller.c` | +| Requirement | SWE-002 (watchdog) | +| Severity | Critical | | Status | Closed | --- -## 1. Beschreibung +## 1. Description -Der `step_count` im Apply-Controller ist als `uint32_t` deklariert und wird in -`apply_ctrl_step_50ms` monoton inkrementiert. Bei 50 ms/Tick ueberlaeuft der -Zaehler nach 2^32 * 50 ms ~= 6.8 Jahren. Der Watchdog in SWA-002 vergleicht -zwar nur das Delta zwischen zwei Lese-Zugriffen (Wrap-Around unkritisch), aber -das Verhalten ist nicht im Header dokumentiert und kann bei nachfolgender -Code-Pflege Fehler erzeugen. +`step_count` in the apply controller is declared as `uint32_t` and is monotonically incremented in `apply_ctrl_step_50ms`. At 50 ms/tick the counter overflows after 2^32 * 50 ms ≈ 6.8 years. The watchdog in SWA-002 only compares the delta between two reads (wrap-around safe), but the behaviour is not documented in the header and may lead to errors in subsequent maintenance. -## 2. Risikobewertung +## 2. Risk assessment -| Aspekt | Bewertung | -|-------------------|----------------------------------------------------------------| -| Auswirkung | Theoretisch Watchdog-False-Negative bei Wrap-Around-Vergleich | -| Eintritts-Wahrscheinlichkeit | Sehr niedrig (6.8 Jahre Lebensdauer) | -| Sicherheits-Beitrag | Indirekt — Watchdog ist Teil der SG-01 Implementierung | +| Aspect | Assessment | +|-------------------|-------------------------------------------------------------------| +| Effect | In theory false-negative watchdog on wrap-around comparison | +| Likelihood | Very low (6.8 years lifetime) | +| Safety contribution | Indirect — watchdog is part of the SG-01 implementation | -## 3. Sofortmassnahme +## 3. Immediate action -Header-Kommentar in `apply_controller.h` ergaenzt: explizite Beschreibung des -Wrap-Around-Verhaltens. Watchdog-Implementierung (in SWA-001) muss Delta- -Vergleich mit `uint32_t` Subtraktion verwenden (Wrap-safe). +Header comment in `apply_controller.h` extended: explicit description of wrap-around behaviour. The watchdog implementation (in SWA-001) must use `uint32_t` subtraction for delta comparison (wrap-safe). -## 4. Korrekturmassnahme (Root-Cause) +## 4. Corrective action (root cause) -Im Code-Review-Checklisten-Eintrag "Integer-Ueberlauf-Verhalten dokumentieren" -ergaenzen. Pruefung in folgenden Reviews. +Add the checklist item "document integer overflow behaviour" to the code-review checklist. Verify in subsequent reviews. -## 5. Verifikation +## 5. Verification -- Kommentar in `apply_controller.h` v1.1 (Commit ``) -- Watchdog in SWA-001 verwendet `uint32_t`-Subtraktion (siehe SWA-001 §4) -- Review-Checkliste aktualisiert +- Comment in `apply_controller.h` v1.1 (commit ``) +- Watchdog in SWA-001 uses `uint32_t` subtraction (see SWA-001 §4) +- Review checklist updated -## 6. Abschluss +## 6. Closure -Geschlossen am 2026-05-11 durch S. Lohmaier nach Verifikation. +Closed on 2026-05-11 by S. Lohmaier after verification. diff --git a/docs/non-conformities/NC-001.docx b/docs/non-conformities/NC-001.docx index c36975f..2670635 100644 Binary files a/docs/non-conformities/NC-001.docx and b/docs/non-conformities/NC-001.docx differ diff --git a/docs/plaene/CM-Plan.docx b/docs/plaene/CM-Plan.docx index b400678..274bd01 100644 Binary files a/docs/plaene/CM-Plan.docx and b/docs/plaene/CM-Plan.docx differ diff --git a/docs/plaene/PID.docx b/docs/plaene/PID.docx index b755f31..2cded95 100644 Binary files a/docs/plaene/PID.docx and b/docs/plaene/PID.docx differ diff --git a/docs/plaene/PM-Plan.docx b/docs/plaene/PM-Plan.docx index 4f36b92..b6d8a21 100644 Binary files a/docs/plaene/PM-Plan.docx and b/docs/plaene/PM-Plan.docx differ diff --git a/docs/plaene/Project-Manual.docx b/docs/plaene/Project-Manual.docx index 152ac2f..9d4fd11 100644 Binary files a/docs/plaene/Project-Manual.docx and b/docs/plaene/Project-Manual.docx differ diff --git a/docs/plaene/QA-Plan.docx b/docs/plaene/QA-Plan.docx index c32dd79..cc04e3b 100644 Binary files a/docs/plaene/QA-Plan.docx and b/docs/plaene/QA-Plan.docx differ diff --git a/docs/plaene/RM-Plan.docx b/docs/plaene/RM-Plan.docx index aec813a..5c607fa 100644 Binary files a/docs/plaene/RM-Plan.docx and b/docs/plaene/RM-Plan.docx differ diff --git a/docs/plaene/SWE-Plan.docx b/docs/plaene/SWE-Plan.docx index 6c29473..758714c 100644 Binary files a/docs/plaene/SWE-Plan.docx and b/docs/plaene/SWE-Plan.docx differ diff --git a/docs/plaene/Test-Plan.docx b/docs/plaene/Test-Plan.docx index 43d61f8..ae4524b 100644 Binary files a/docs/plaene/Test-Plan.docx and b/docs/plaene/Test-Plan.docx differ diff --git a/docs/plans-md/CM-Plan.md b/docs/plans-md/CM-Plan.md index 6dfe67e..6cb31f7 100644 --- a/docs/plans-md/CM-Plan.md +++ b/docs/plans-md/CM-Plan.md @@ -1,148 +1,146 @@ --- doc-id: SLM-EPB-CM-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- -# Configuration Management Plan (CM-Plan) +# Configuration Management Plan (CM Plan) -| Feld | Wert | -|--------------|----------------------------------------| -| Projekt | demo-epb | -| Dokument-ID | SLM-EPB-CM-001 | -| Version | 1.0 | -| Status | Freigegeben | -| Datum | 2026-05-12 | -| Norm | ASPICE SUP.8 + ISO 26262-8 §7 | +| Field | Value | +|---------------|----------------------------------------| +| Project | demo-epb | +| Document ID | SLM-EPB-CM-001 | +| Version | 1.0 | +| Status | Released | +| Date | 2026-05-12 | +| Standard | ASPICE SUP.8 + ISO 26262-8 §7 | --- -## 1. Zweck +## 1. Purpose -Beschreibt, wie Konfigurations-Items identifiziert, versioniert, freigegeben -und kontrolliert geaendert werden. +Describes how configuration items are identified, versioned, released, and controlled-change managed. ## 2. Configuration Items (CIs) -Folgende Artefakte stehen unter Konfigurationskontrolle: +The following artefacts are under configuration control: -| Typ | Pfad | Versionierung | +| Type | Path | Versioning | |-------------------------|----------------------------------------|------------------------------| -| Source-Code | `src/**/*.{c,h}` | Git | +| Source code | `src/**/*.{c,h}` | Git | | Tests | `tests/**` | Git | -| Anforderungen | `reqs/{sys,swe}/*.md` | Git + Doorstop-Item-Hash | -| Architektur | `arch/{sys,swe}/*.md` | Git + Doorstop-Item-Hash | +| Requirements | `reqs/{sys,swe}/*.md` | Git + Doorstop item hash | +| Architecture | `arch/{sys,swe}/*.md` | Git + Doorstop item hash | | Safety Goals | `safety/sg/*.md` | Git | -| Plaene (Word) | `docs/plaene/*.docx` | Git + Dokument-Versionsblock | -| Safety-Doku (Word) | `docs/safety/*.docx` | Git | +| Plans (Word) | `docs/plaene/*.docx` | Git + document version block | +| Safety docs (Word) | `docs/safety/*.docx` | Git | | Manuals (Word) | `docs/manuals/*.docx` | Git | | Reviews + NCs | `docs/reviews/`, `docs/non-conformities/` | Git | -| MISRA-Records | `misra/records/*.docx` | Git | -| CI-Konfiguration | `.gitea/workflows/*.yml` | Git | -| Build-Definition | `Makefile`, `Doxyfile` | Git | +| MISRA records | `misra/records/*.docx` | Git | +| CI configuration | `.gitea/workflows/*.yml` | Git | +| Build definition | `Makefile`, `Doxyfile` | Git | | Tools | `tools/*.py` | Git | -## 3. Repository-Struktur +## 3. Repository structure - **Remote:** https://gitea.slohmaier.com/slohmaier/demo-epb -- **Branch `main`:** stabil, immer freigegebener Stand -- **Branch `develop`:** aktueller Entwicklungsstand -- **Feature-Branches:** `feature/SWE-XXX-...` -- **Bugfix-Branches:** `bugfix/-...` -- **Release-Branches:** `release/vX.Y` (nur bei Real-Projekt; Demo: direkt von main) +- **Branch `main`:** stable, always released state +- **Branch `develop`:** current development state +- **Feature branches:** `feature/SWE-XXX-...` +- **Bugfix branches:** `bugfix/-...` +- **Release branches:** `release/vX.Y` (real projects only; demo: from main directly) ## 4. Baselines -Eine Baseline ist ein eingefrorener, freigegebener Stand. Baselines werden durch -Git-Tags gesetzt. +A baseline is a frozen, released state. Baselines are set via git tags. -| Baseline-Typ | Tag-Schema | Wann | +| Baseline type | Tag scheme | When | |---------------------------|-------------------|----------------------------------------| -| Requirements Baseline | `req-vX.Y` | Nach Anforderungs-Freigabe | -| Architecture Baseline | `arch-vX.Y` | Nach Architektur-Review | -| Release Baseline | `vX.Y.Z` | Bei produktiver Freigabe | -| Internal Snapshot | `snap-YYYY-MM-DD` | Bei wichtigen Zwischenstaenden | +| Requirements baseline | `req-vX.Y` | After requirements release | +| Architecture baseline | `arch-vX.Y` | After architecture review | +| Release baseline | `vX.Y.Z` | On productive release | +| Internal snapshot | `snap-YYYY-MM-DD` | On significant intermediate states | -Jeder Tag triggert (bei `vX.Y.Z`) den Release-Workflow, der ein Bundle erzeugt. +Every tag (specifically `vX.Y.Z`) triggers the release workflow, which produces a bundle. -## 5. Versions-Schema +## 5. Versioning scheme -| Artefakt | Schema | +| Artefact | Scheme | |-----------------------|------------------------------------------| -| Software-Release | Semantic Versioning `MAJOR.MINOR.PATCH` | -| Anforderungen | Doorstop-Level `X.Y` + Datum | -| Architektur | Doorstop-Level `X.Y` + Datum | -| Word-Dokumente | `MAJOR.MINOR` im Dokument-Header | +| Software release | Semantic Versioning `MAJOR.MINOR.PATCH` | +| Requirements | Doorstop level `X.Y` + date | +| Architecture | Doorstop level `X.Y` + date | +| Word documents | `MAJOR.MINOR` in document header | -## 6. Change Control +## 6. Change control -Aenderungen an Configuration Items erfolgen ueber: +Changes to configuration items occur via: -1. **Trivial-Aenderung** (Tippfehler, Kommentare): direkt im Branch, PR mit 1 Approval -2. **Normal-Aenderung** (Feature, Bugfix): Feature-Branch, PR mit Reviews je nach ASIL -3. **Major-Aenderung** (Architektur, Sicherheits-Konzept): Change Request + Reviewer-Quorum +1. **Trivial change** (typos, comments): directly on the branch, PR with 1 approval +2. **Normal change** (feature, bug fix): feature branch, PR with reviews per ASIL +3. **Major change** (architecture, safety concept): change request + reviewer quorum -| Asil | Reviewer-Mindestanzahl | -|---------|--------------------------------------| -| QM | 1 | -| ASIL-A/B| 1 | -| ASIL-C | 2 (mind. 1 Technical Reviewer) | -| ASIL-D | 2 Technical Reviewer + Safety Manager| +| ASIL | Minimum reviewer count | +|---------|---------------------------------------| +| QM | 1 | +| ASIL-A/B| 1 | +| ASIL-C | 2 (at least 1 technical reviewer) | +| ASIL-D | 2 technical reviewers + Safety Manager | -Reviews werden in `docs/reviews/REV-XXX.docx` dokumentiert. +Reviews are documented in `docs/reviews/REV-XXX.docx`. -## 7. Release-Prozess +## 7. Release process ``` -1. Alle PRs in main gemerged -2. Branch protected, alle CI-Checks gruen -3. Release-Notes-Entwurf im PR vorbereitet -4. Tag setzen: git tag -a vX.Y.Z -m "..." +1. All PRs merged into main +2. Branch protected, all CI checks green +3. Release notes drafted in the PR +4. Set tag: git tag -a vX.Y.Z -m "..." 5. Push: git push origin vX.Y.Z -6. Release-Workflow laeuft (.gitea/workflows/release.yml): - - Build + Tests + Coverage - - Traceability + Diagrams + API-Doc - - Word-Dokumente bundlen - - Source + Artefakt-Archive packen - - Gitea-Release anlegen -7. Release manuell pruefen (Bundle herunterladen, sichten) -8. Release als "stable" markieren +6. Release workflow runs (.gitea/workflows/release.yml): + - Build + tests + coverage + - Traceability + diagrams + API doc + - Bundle Word documents + - Pack source + artefact archives + - Create Gitea release +7. Review release manually (download bundle, inspect) +8. Mark release as "stable" ``` -## 8. Aufbewahrung +## 8. Retention -| Artefakt | Aufbewahrungsdauer | +| Artefact | Retention | |--------------------------|----------------------------------------| -| Git-Repository | Unbegrenzt (Gitea + Backup) | -| Release-Bundles | 10 Jahre nach Produkt-EOL | -| Reviews + NCs | 10 Jahre nach Produkt-EOL | -| MISRA-Records | 10 Jahre nach Produkt-EOL | -| CI-Artefakte (kurzlebig) | 90 Tage (in Gitea-Artifacts) | +| Git repository | Indefinite (Gitea + backup) | +| Release bundles | 10 years after product EOL | +| Reviews + NCs | 10 years after product EOL | +| MISRA records | 10 years after product EOL | +| CI artefacts (short-lived)| 90 days (in Gitea artifacts) | -ISO 26262 fordert 10 Jahre nach End-of-Production-Life (Annahme). +ISO 26262 requires 10 years after end-of-production-life (assumption). -## 9. Verifikation +## 9. Verification -Alle Pull Requests laufen durch: -- `doorstop`-aequivalenter Traceability-Check (`tools/traceability.py check`) -- Build + Unit-Tests -- Static Analysis + MISRA-Check -- Coverage-Messung +All pull requests pass through: +- Doorstop-equivalent traceability check (`tools/traceability.py check`) +- Build + unit tests +- Static analysis + MISRA check +- Coverage measurement -Erst nach Approval und CI-Gruen kann der Merge nach `main` erfolgen. +Only after approval and green CI may a merge into `main` occur. -## 10. Verantwortlichkeiten +## 10. Responsibilities -| Rolle | Aufgabe | -|------------------|--------------------------------------------------| -| Configuration Mgr| Pflege dieses CM-Plans, Repo-Hygiene, Baselines | -| Entwickler | Korrekte Branch-Strategie, sinnvolle Commit-Msg | -| Reviewer | Pruefung vor Merge, Audit-Trail | -| Project Owner | Release-Freigabe | +| Role | Task | +|------------------|---------------------------------------------------| +| Configuration Mgr| Maintain this CM Plan, repo hygiene, baselines | +| Developer | Correct branching, meaningful commit messages | +| Reviewer | Review before merge, audit trail | +| Project Owner | Release approval | -## 11. Aenderungshistorie +## 11. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|---------------------|-------------| -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 1.0 | 2026-05-12 | First release | S. Lohmaier| diff --git a/docs/plans-md/PID.md b/docs/plans-md/PID.md index a5bfcfe..228012f 100644 --- a/docs/plans-md/PID.md +++ b/docs/plans-md/PID.md @@ -1,107 +1,107 @@ # Project Initiation Document (PID) -| Feld | Wert | +| Field | Value | |-----------------|--------------------------------------| -| Projekt | demo-epb (Elektrische Parkbremse) | -| Projekt-ID | SLM-EPB-001 | -| Auftraggeber | slohmaier.com (Demo-Eigenentwicklung)| -| Auftragnehmer | Stefan Lohmaier | -| Datum | 2026-05-11 | +| Project | demo-epb (Electric Parking Brake) | +| Project ID | SLM-EPB-001 | +| Client | slohmaier.com (in-house demo) | +| Contractor | Stefan Lohmaier | +| Date | 2026-05-11 | | Version | 1.0 | -| Status | Freigegeben | -| Klassifikation | Oeffentlich | +| Status | Released | +| Classification | Public | --- -## 1. Projektzweck +## 1. Project purpose -Demonstration des slohmaier Dev Process anhand einer EPB-Steuergeraet-Software. Ziel ist nicht die produktive Software, sondern der vollstaendige Nachweis von: +Demonstration of the slohmaier Dev Process using an EPB ECU software. The goal is not the productive software but a complete demonstration of: -- ASPICE-4.0-konformer Entwicklungsablauf -- ISO-26262-konforme Behandlung von Sicherheitsanforderungen (ASIL-D / ASIL-B / QM) -- MISRA-C-Compliance -- Werkzeugkette: Gitea + Doorstop + Cppcheck + gcov + CppUTest + pandoc +- ASPICE 4.0-compliant development flow +- ISO 26262-compliant handling of safety requirements (ASIL-D / ASIL-B / QM) +- MISRA C compliance +- Toolchain: Gitea + Doorstop + Cppcheck + gcov + CppUTest + pandoc -Adressat ist potenzielle Kundschaft, die sehen will, wie ein realer Audit-faehiger Engineering-Stand aussieht. +The target audience is potential customers who want to see what a real audit-ready engineering snapshot looks like. -## 2. Produktbeschreibung +## 2. Product description -Eine Electronic Parking Brake (EPB) klemmt im Stillstand zwei Bremssaettel ueber kleine Elektromotoren fest und loest sie bei Anfahrt wieder. Funktionsumfang: +An Electric Parking Brake (EPB) clamps two rear callipers via small electric motors at standstill and releases them on drive-away. Functional scope: -- Apply / Release auf Fahrer-Anforderung -- Hold-Funktion mit Auto-Apply bei Motor-Aus -- Drive-Away-Assist (Auto-Release beim Anfahren) -- Hill-Hold am Berg -- Aktor-Stromueberwachung -- Service-Modus fuer Werkstatt -- UDS-Diagnose ueber CAN +- Apply / Release on driver request +- Hold function with auto-apply on engine-off +- Drive-Away-Assist (auto-release on drive-away) +- Hill-Hold on inclines +- Actuator current monitoring +- Service mode for the workshop +- UDS diagnostics via CAN -## 3. Sicherheitsziele +## 3. Safety goals -| ID | Sicherheitsziel | ASIL | +| ID | Safety goal | ASIL | |-------|---------------------------------------------------------------|------| -| SG-01 | Verhinderung ungewollten Wegrollens des Fahrzeugs | D | -| SG-02 | Verhinderung ungewollten Loesens der Parkbremse | D | -| SG-03 | Verhinderung Motorschaden durch Ueberlast | B | +| SG-01 | Prevent unintended vehicle roll-away | D | +| SG-02 | Prevent unintended release of the parking brake | D | +| SG-03 | Prevent motor damage from overload | B | -Die Sicherheitsziele werden in den System-Anforderungen (`reqs/sys/`) weiter detailliert. +Safety goals are detailed further in the system requirements (`reqs/sys/`). -## 4. Stakeholder +## 4. Stakeholders -| Rolle | Person / Funktion | +| Role | Person / Function | |--------------------|--------------------------------| | Project Owner | Stefan Lohmaier | | Technical Lead | Stefan Lohmaier | | Quality Assurance | Stefan Lohmaier | -| Reviewer | Externer Reviewer (TBD) | -| Kunde (Demo) | Interessenten / Prospects | +| Reviewer | External reviewer (TBD) | +| Customer (demo) | Prospects / interested parties | -Bei einem Realprojekt waeren QA und TL personell getrennt; in dieser Demo wird die Rollentrennung dokumentarisch nachgehalten. +In a real project QA and TL would be separate persons; in this demo the role separation is kept on paper. -## 5. Liefergegenstaende +## 5. Deliverables -| Artefakt | Format | Status | -|-----------------------------------|---------------|-------------| -| PID, PM-Plan, QA-Plan, SWE-Plan, Test-Plan | Word | Vorhanden | -| System-Anforderungen (SYS-001..010) | Doorstop-MD | Vorhanden | -| Software-Anforderungen (SWE-001..025) | Doorstop-MD | Vorhanden | -| System-Architektur (SA-001..005) | Doorstop-MD | Vorhanden | -| Software-Architektur (SWA-001..010) | Doorstop-MD | Vorhanden | -| Quellcode (3 Demo-Komponenten) | C99 | Vorhanden | -| Unit-Tests + Coverage-Report | CppUTest, lcov| Vorhanden | -| MISRA-Report | Cppcheck XML | Vorhanden | -| Traceability-Matrix | Doorstop HTML | Generiert in CI | -| Review-Protokoll (Beispiel) | Word | Vorhanden | -| MISRA Deviation Record (Beispiel) | Word | Vorhanden | +| Artefact | Format | Status | +|-------------------------------------------|---------------|-------------| +| PID, PM Plan, QA Plan, SWE Plan, Test Plan | Word | Available | +| System Requirements (SYS-001..010) | Doorstop MD | Available | +| Software Requirements (SWE-001..025) | Doorstop MD | Available | +| System Architecture (SA-001..005) | Doorstop MD | Available | +| Software Architecture (SWA-001..010) | Doorstop MD | Available | +| Source code (3 demo components) | C99 | Available | +| Unit tests + coverage report | CppUTest, lcov | Available | +| MISRA report | Cppcheck XML | Available | +| Traceability matrix | Doorstop HTML | Generated in CI | +| Review minutes (example) | Word | Available | +| MISRA Deviation Record (example) | Word | Available | -## 6. Zeitplan +## 6. Schedule -Demo-Projekt, Single-Sprint-Erstellung. Eintaegige Initialerstellung, danach Pflege. +Demo project, single-sprint creation. One-day initial creation, maintenance thereafter. -| Phase | Start | Ende | -|------------------------|-------------|-------------| -| Konzept + Setup | 2026-05-11 | 2026-05-11 | -| Requirements + Architektur | 2026-05-11 | 2026-05-11 | -| Implementierung Demo-Komponenten | 2026-05-11 | 2026-05-11 | -| Tests + CI | 2026-05-11 | 2026-05-11 | -| Freigabe v1.0 | 2026-05-11 | 2026-05-11 | +| Phase | Start | End | +|-------------------------------|-------------|-------------| +| Concept + setup | 2026-05-11 | 2026-05-11 | +| Requirements + architecture | 2026-05-11 | 2026-05-11 | +| Implementation of demo components | 2026-05-11 | 2026-05-11 | +| Tests + CI | 2026-05-11 | 2026-05-11 | +| Release v1.0 | 2026-05-11 | 2026-05-11 | ## 7. Budget -Demo-Projekt, kein externes Budget. Aufwand intern. +Demo project, no external budget. Internal effort. -## 8. Risiken +## 8. Risks -| Risiko | Wahrsch. | Auswirkung | Massnahme | -|-----------------------------------------|----------|------------|-------------------------------------------| -| Demo wird als produktreifer Code missverstanden | M | M | README + Disclaimer explicit kennzeichnen | -| MISRA-Tooling-Update bricht CI | N | M | Tool-Versionen in CI pinnen | -| Reviewer-Verfuegbarkeit | M | N | Self-Review dokumentiert (Demo) | +| Risk | Likelihood | Impact | Mitigation | +|-----------------------------------------------|------------|--------|----------------------------------------------| +| Demo is mistaken for production-ready code | M | M | Disclaimer in README + plain labelling | +| MISRA tooling update breaks CI | L | M | Pin tool versions in CI | +| Reviewer availability | M | L | Self-review documented (demo only) | -## 9. Erfolgskriterien +## 9. Success criteria -- Alle 35 Anforderungen sind verlinkt und durch Architektur abgedeckt -- `doorstop check` ist gruen -- MISRA-Check in CI ist gruen (mit dokumentierten Deviations) -- Coverage der Demo-Komponenten >= Zielwert (siehe SWE-Plan) -- Demo-Tour im README ist fuer einen Prospect in <30 min nachvollziehbar +- All 35 requirements are linked and covered by architecture +- `doorstop check` is green +- MISRA check in CI is green (with documented deviations) +- Demo-component coverage meets target (see SWE Plan) +- The guided tour in the README is navigable by a prospect in < 30 min diff --git a/docs/plans-md/PM-Plan.md b/docs/plans-md/PM-Plan.md index 0349314..50f4fdc 100644 --- a/docs/plans-md/PM-Plan.md +++ b/docs/plans-md/PM-Plan.md @@ -1,63 +1,63 @@ -# Projektmanagement-Plan (PM-Plan) +# Project Management Plan (PM Plan) -| Feld | Wert | +| Field | Value | |-----------------|--------------------------------------| -| Projekt | demo-epb | -| Datum | 2026-05-11 | +| Project | demo-epb | +| Date | 2026-05-11 | | Version | 1.0 | -| Status | Freigegeben | +| Status | Released | --- -## 1. Projektorganisation +## 1. Project organisation -Single-Person-Projekt mit dokumentierter Rollentrennung. In einem Real-Projekt waeren QA, TL und Entwickler personell getrennt; hier wird der Audit-Trail durch Self-Review mit Begruendung gefuehrt (siehe SWE-Plan, Abschnitt 5). +Single-person project with documented role separation. In a real project, QA, TL, and developer would be separate persons; here the audit trail is maintained through self-review with rationale (see SWE Plan, section 5). -## 2. Arbeitspakete +## 2. Work packages -| WP-ID | Arbeitspaket | Verantwortlich | Status | -|-------|--------------------------------------------|----------------|--------------| -| WP-01 | Projektplanung (PID, PM-Plan, QA-Plan, SWE-Plan, Test-Plan) | S. Lohmaier | Done | -| WP-02 | System-Anforderungen (SYS-001..010) | S. Lohmaier | Done | -| WP-03 | Software-Anforderungen (SWE-001..025) | S. Lohmaier | Done | -| WP-04 | System-Architektur (SA-001..005) | S. Lohmaier | Done | -| WP-05 | Software-Architektur (SWA-001..010) | S. Lohmaier | Done | -| WP-06 | Implementierung Demo-Komponenten | S. Lohmaier | Done | -| WP-07 | Unit-Tests + Coverage | S. Lohmaier | Done | -| WP-08 | CI-Pipeline (Gitea Actions) | S. Lohmaier | Done | -| WP-09 | Audit-Artefakte (Review, NC, MISRA-Record) | S. Lohmaier | Done | +| WP-ID | Work package | Owner | Status | +|-------|---------------------------------------------|----------------|--------| +| WP-01 | Project planning (PID, PM, QA, SWE, Test) | S. Lohmaier | Done | +| WP-02 | System Requirements (SYS-001..010) | S. Lohmaier | Done | +| WP-03 | Software Requirements (SWE-001..025) | S. Lohmaier | Done | +| WP-04 | System Architecture (SA-001..005) | S. Lohmaier | Done | +| WP-05 | Software Architecture (SWA-001..010) | S. Lohmaier | Done | +| WP-06 | Implementation of demo components | S. Lohmaier | Done | +| WP-07 | Unit tests + coverage | S. Lohmaier | Done | +| WP-08 | CI pipeline (Gitea Actions) | S. Lohmaier | Done | +| WP-09 | Audit artefacts (Review, NC, MISRA record) | S. Lohmaier | Done | -## 3. Aenderungsverwaltung +## 3. Change control -- Aenderungen an freigegebenen Artefakten erfolgen ueber Pull Requests -- Jeder PR braucht mindestens 1 Approval (siehe SWE-Plan, Abschnitt 5) -- Bei Aenderung von Architektur oder Anforderungen ist die Traceability-Matrix neu zu erzeugen (`doorstop publish`) -- Aenderungshistorie wird in der jeweiligen `.md`-Datei oder Word-Datei revisioniert +- Changes to released artefacts go through pull requests +- Every PR needs at least 1 approval (see SWE Plan, section 5) +- When requirements or architecture change, the traceability matrix must be regenerated (`doorstop publish`) +- Revision history is maintained inside the respective `.md` file or Word document -## 4. Konfigurationsmanagement +## 4. Configuration management -| Artefakt-Typ | Versionsverwaltung | Baseline-Mechanismus | -|-----------------------|------------------------|--------------------------| -| Code | Git (Gitea) | Git-Tag (z.B. v1.0.0) | -| Anforderungen / Arch | Git + Doorstop | Git-Tag + doorstop publish | -| Word-Dokumente | Git | Datei-Versionsstempel + Revisions-History im Dokument | -| CI-Konfiguration | Git | Versionsdatei + Tag | +| Artefact type | Versioning | Baseline mechanism | +|-------------------|-----------------------|------------------------------------| +| Code | Git (Gitea) | Git tag (e.g. v1.0.0) | +| Requirements / Arch | Git + Doorstop | Git tag + doorstop publish | +| Word documents | Git | File version stamp + revision history in the document | +| CI configuration | Git | Version pin + tag | -## 5. Kommunikation +## 5. Communication -| Kanal | Zweck | -|---------------|-----------------------------------| -| Gitea Issues | Bug-Tracking, Tasks | -| Gitea PRs | Review, Approval, Audit-Trail | -| Matrix Chat | Schnelle Abstimmung | -| E-Mail | Formelle Freigaben (CC: Auftraggeber) | +| Channel | Purpose | +|---------------|--------------------------------------| +| Gitea Issues | Bug tracking, tasks | +| Gitea PRs | Review, approval, audit trail | +| Matrix chat | Quick alignment | +| Email | Formal releases (cc client) | -## 6. Berichtswesen +## 6. Reporting -- Wochenstatus per E-Mail (in Real-Projekten) -- Audit-Report bei Projektabschluss (PDF aus Doorstop + Word-Plaene) -- Coverage- und MISRA-Reports werden bei jedem Push aktualisiert (CI-Artefakte) +- Weekly status by email (in real projects) +- Audit report at project closure (PDF from Doorstop + Word plans) +- Coverage and MISRA reports are refreshed on every push (CI artefacts) -## 7. Abschluss +## 7. Closure -Projekt gilt als abgeschlossen, wenn alle Erfolgskriterien aus dem PID erfuellt sind und ein Git-Tag `v1.0` gesetzt ist. +The project is considered closed when all success criteria from the PID are met and the `v1.0` git tag is set. diff --git a/docs/plans-md/Project-Manual.md b/docs/plans-md/Project-Manual.md index 370a9eb..04d2bc9 100644 --- a/docs/plans-md/Project-Manual.md +++ b/docs/plans-md/Project-Manual.md @@ -1,172 +1,168 @@ --- doc-id: SLM-EPB-PM-MAN-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- # Project Manual — demo-epb -| Feld | Wert | -|--------------|----------------------------------------| -| Projekt | demo-epb (Elektrische Parkbremse) | -| Dokument-ID | SLM-EPB-PM-MAN-001 | -| Version | 1.0 | -| Status | Freigegeben | -| Datum | 2026-05-12 | -| Zielgruppe | Neue Projektmitglieder, Auditoren | +| Field | Value | +|---------------|----------------------------------------| +| Project | demo-epb (Electric Parking Brake) | +| Document ID | SLM-EPB-PM-MAN-001 | +| Version | 1.0 | +| Status | Released | +| Date | 2026-05-12 | +| Audience | New project members, auditors | --- -## 1. Zweck +## 1. Purpose -Dieses Project Manual ist der **Einstieg** ins demo-epb Projekt. Es beantwortet: +This Project Manual is the entry point to the demo-epb project. It answers: -- Was wird gebaut? -- Welche Dokumente gibt es, in welcher Reihenfolge lesen? -- Wer ist verantwortlich wofuer? -- Wie laeuft der Entwicklungs- und Freigabe-Zyklus? +- What is being built? +- Which documents exist, in what reading order? +- Who is responsible for what? +- How does the development and release cycle work? -## 2. Was ist demo-epb? +## 2. What is demo-epb? -Eine vollstaendige Demo des **slohmaier Dev Process** anhand einer -EPB-Steuergeraet-Software. Ziel ist **nicht** die produktive Software, sondern -der Nachweis ASPICE 4.0 / ISO 26262-konformer Entwicklung. +A complete demo of the **slohmaier Dev Process** using an EPB ECU software. The goal is **not** the productive software, but evidence of ASPICE 4.0 / ISO 26262-compliant development. Detail: `docs/plaene/PID.docx`. -## 3. Lese-Reihenfolge fuer neue Projektmitglieder +## 3. Reading order for new project members -| Tag | Dokument | Warum | +| Day | Document | Why | |-----|----------------------------------------|----------------------------------------| -| 1 | dieses Project Manual | Orientierung | -| 1 | `PID.docx` | Was + Warum | -| 1 | `User-Manual.docx` | Produkt-Verstaendnis | -| 2 | `HARA.docx` + `Safety-Case.docx` | Sicherheits-Konzept | -| 2 | `SWE-Plan.docx` + `QA-Plan.docx` | Engineering-Konventionen | -| 3 | `reqs/` + `arch/` (Markdown) | Anforderungen + Architektur | -| 3 | `src/apply_controller.c` | Beispiel ASIL-D Code | -| 4 | `traceability/index.html` | Vernetzung der Artefakte | -| 4 | `coverage/index.html` | Was ist getestet | -| 5 | Diese Anleitung selber pflegen | Onboarding fuer den Naechsten | +| 1 | this Project Manual | Orientation | +| 1 | `PID.docx` | What + Why | +| 1 | `User-Manual.docx` | Product understanding | +| 2 | `HARA.docx` + `Safety-Case.docx` | Safety concept | +| 2 | `SWE-Plan.docx` + `QA-Plan.docx` | Engineering conventions | +| 3 | `reqs/` + `arch/` (markdown) | Requirements + architecture | +| 3 | `src/apply_controller.c` | Example ASIL-D code | +| 4 | `traceability/index.html` | Wiring of artefacts | +| 4 | `coverage/index.html` | What is tested | +| 5 | Maintain this manual | Onboarding for the next person | -## 4. Dokumenten-Landschaft +## 4. Document landscape ``` demo-epb/ -├── docs/plaene/ ← PID, PM-Plan, QA-Plan, SWE-Plan, Test-Plan, CM-Plan, RM-Plan -├── docs/safety/ ← HARA, Safety-Case, FMEDA, MISRA-Compliance, Verification-Report, Tool-Qualification -├── docs/manuals/ ← User-Manual, Service-Manual -├── docs/reviews/ ← Review-Protokolle -├── docs/non-conformities/ ← NC-Eintraege -├── misra/records/ ← MISRA Deviation Records -├── reqs/sys/ ← Doorstop-MD System Requirements -├── reqs/swe/ ← Doorstop-MD Software Requirements -├── arch/sys/ ← Doorstop-MD System Architecture + PlantUML -├── arch/swe/ ← Doorstop-MD Software Architecture + PlantUML -├── safety/sg/ ← Doorstop-MD Safety Goals (ASIL-Ableitung) -├── src/ ← C-Code, mit @arch + @reqs Tags im Header -├── tests/ ← Unit-Tests mit @reqs Tags -├── tools/ ← Python-Skripte (Traceability, PlantUML, Reports) -├── .gitea/workflows/ ← CI-Pipelines (validate + release) -└── docs/index.html ← Auto-generierte Startseite +├── docs/plaene/ ← PID, PM Plan, QA Plan, SWE Plan, Test Plan, CM Plan, RM Plan +├── docs/safety/ ← HARA, Safety Case, FMEDA, MISRA Compliance, Verification Report, Tool Qualification +├── docs/manuals/ ← User Manual, Service Manual +├── docs/reviews/ ← Review minutes +├── docs/non-conformities/ ← NC entries +├── misra/records/ ← MISRA deviation records +├── reqs/sys/ ← Doorstop MD system requirements +├── reqs/swe/ ← Doorstop MD software requirements +├── arch/sys/ ← Doorstop MD system architecture + PlantUML +├── arch/swe/ ← Doorstop MD software architecture + PlantUML +├── safety/sg/ ← Doorstop MD safety goals (ASIL derivation) +├── src/ ← C source, with @arch + @reqs tags in headers +├── tests/ ← Unit tests with @reqs tags +├── tools/ ← Python helper scripts (traceability, PlantUML, reports) +├── .gitea/workflows/ ← CI pipelines (validate + release) +└── docs/index.html ← Auto-generated landing page ``` -Eine **klickbare Uebersicht** liefert `docs/index.html` (Browser oeffnen). +A clickable overview is `docs/index.html` (open in browser). -## 5. Rollen und Verantwortlichkeiten +## 5. Roles and responsibilities -| Rolle | Verantwortung | Person (Demo) | -|--------------------|-----------------------------------------------------|--------------------------| -| Project Owner | Strategische Entscheidungen, Freigabe Release | Stefan Lohmaier | -| Technical Lead | Architektur, Code-Reviews, technische Entscheidungen | Stefan Lohmaier | -| Safety Manager | HARA, Safety Case, ASIL-Konformitaet | Stefan Lohmaier (Demo) | -| QA-Beauftragter | QA-Plan-Pflege, Audit-Vorbereitung | Stefan Lohmaier (Demo) | -| Configuration Mgr | Baselines, Releases, Git-Repo-Hygiene | Stefan Lohmaier (Demo) | -| Entwickler | Implementierung gemaess Architektur + Tests | Stefan Lohmaier (Demo) | -| Reviewer | Code- und Dokument-Reviews | Externer Reviewer (TBD) | +| Role | Responsibility | Person (demo) | +|--------------------|-------------------------------------------------------|--------------------------| +| Project Owner | Strategic decisions, release approval | Stefan Lohmaier | +| Technical Lead | Architecture, code reviews, technical decisions | Stefan Lohmaier | +| Safety Manager | HARA, Safety Case, ASIL conformance | Stefan Lohmaier (demo) | +| QA Officer | QA Plan maintenance, audit preparation | Stefan Lohmaier (demo) | +| Configuration Mgr | Baselines, releases, git repo hygiene | Stefan Lohmaier (demo) | +| Developer | Implementation per architecture + tests | Stefan Lohmaier (demo) | +| Reviewer | Code and document reviews | External reviewer (TBD) | -In der Demo ist eine Person in allen Rollen; in einem Real-Projekt mit ASIL-C/D -sind diese personell zu trennen (insb. Entwickler ungleich Reviewer fuer -sicherheitskritischen Code). +In this demo one person fills all roles; in a real project with ASIL-C/D these are to be separated personnel-wise (developer ≠ reviewer for safety-critical code). -## 6. Entwicklungs-Lebenszyklus +## 6. Development lifecycle ``` -Anforderung +Requirement │ ▼ -Architektur (Markdown + PlantUML) +Architecture (Markdown + PlantUML) │ ▼ -Implementation (C, mit @arch + @reqs) +Implementation (C, with @arch + @reqs) │ ▼ -Unit-Test (CppUTest-aehnliches Framework, mit @reqs) +Unit test (CppUTest-like framework, with @reqs) │ ▼ -Pull Request (Branch -> main) +Pull request (branch → main) │ ▼ -CI: Build + Test + Coverage + MISRA + Traceability-Check +CI: build + test + coverage + MISRA + traceability check │ ▼ -Code-Review (Approval-Pflicht je nach ASIL) +Code review (approval required per ASIL) │ ▼ -Merge nach main +Merge to main │ - ▼ (bei Release-Punkt) + ▼ (at release point) Tag v*.*.* │ ▼ -CI Release-Workflow: Bundle + Gitea-Release +CI release workflow: bundle + Gitea release ``` -## 7. Freigabe-Strategie +## 7. Release strategy -- **Pull-Requests** brauchen mindestens 1 Approval (mehr fuer ASIL-C/D, siehe SWE-Plan) -- **Tags** im Format `vMAJOR.MINOR.PATCH` triggern den Release-Workflow -- **Release-Bundle** enthaelt Source + alle Reports + alle Word-Dokumente -- **Audit-Faehigkeit** ist jederzeit gegeben (Git-History + Doku-Lifecycle) +- **Pull requests** need at least 1 approval (more for ASIL-C/D, see SWE Plan) +- **Tags** of the form `vMAJOR.MINOR.PATCH` trigger the release workflow +- **Release bundle** contains source + all reports + all Word documents +- **Audit readiness** is maintained continuously (git history + document lifecycle) -## 8. Wo Probleme melden +## 8. Where to report problems -| Problem-Typ | Wo dokumentieren | -|-----------------------|-------------------------------------------------| -| Bug | Gitea Issue (Tag `bug`) | -| Anforderungs-Aenderung| Gitea Issue (Tag `requirement`) + Doorstop-Update | -| Non-Conformity | `docs/non-conformities-md/NC-XXX.md` -> Word | -| MISRA-Abweichung | `misra/records-md/MISRA-REC-XXX.md` -> Word | -| Sicherheits-Problem | Sofort an Safety Manager + NC | +| Problem type | Where to document | +|----------------------|------------------------------------------------| +| Bug | Gitea issue (tag `bug`) | +| Requirement change | Gitea issue (tag `requirement`) + Doorstop update | +| Non-conformity | `docs/non-conformities-md/NC-XXX.md` → Word | +| MISRA deviation | `misra/records-md/MISRA-REC-XXX.md` → Word | +| Safety problem | Escalate to Safety Manager + NC | ## 9. Tools -Siehe `infrastructure/` im iCloud-Workspace fuer Setup-Details. Kurzform: +See `infrastructure/` in the iCloud workspace for setup details. Short list: -- **Gitea** (gitea.slohmaier.com) — Source-Control + CI + Releases -- **Doorstop-Stil** Markdown — Anforderungen + Architektur -- **PlantUML** — Diagramme (eingebettet) -- **Cppcheck** + **GCC -Werror** — Statische Analyse + MISRA -- **gcov/lcov** — Coverage -- **Doxygen** — API-Doc -- **pandoc** — Markdown -> Word/PDF -- **Python** (Stdlib) — Traceability + Report-Generatoren +- **Gitea** (gitea.slohmaier.com) — source control + CI + releases +- **Doorstop-style** Markdown — requirements + architecture +- **PlantUML** — diagrams (embedded) +- **Cppcheck** + **GCC -Werror** — static analysis + MISRA +- **gcov/lcov** — coverage +- **Doxygen** — API doc +- **pandoc** — Markdown → Word/PDF +- **Python** (stdlib) — traceability + report generators -## 10. Verwandte Dokumente +## 10. Related documents -| Plan | Datei | Inhalt | -|----------------------|-------------------------------------|----------------------------------------| -| Project Initiation | `PID.docx` | Was + Warum | -| Projekt-Management | `PM-Plan.docx` | Arbeitspakete, Termine, Stakeholder | -| Quality Assurance | `QA-Plan.docx` | Reviews, Audits, NC-Management | -| Configuration Mgmt | `CM-Plan.docx` | Baselines, Releases, Change Control | -| Risk Management | `RM-Plan.docx` | Risiken, Mitigation, Monitoring | -| Software Development | `SWE-Plan.docx` | Sprache, Standards, Coverage-Ziele | -| Test | `Test-Plan.docx` | Test-Strategie | +| Plan | File | Content | +|----------------------|------------------------------------|----------------------------------------| +| Project Initiation | `PID.docx` | What + Why | +| Project Management | `PM-Plan.docx` | Work packages, schedule, stakeholders | +| Quality Assurance | `QA-Plan.docx` | Reviews, audits, NC management | +| Configuration Mgmt | `CM-Plan.docx` | Baselines, releases, change control | +| Risk Management | `RM-Plan.docx` | Risks, mitigation, monitoring | +| Software Development | `SWE-Plan.docx` | Language, standards, coverage targets | +| Test | `Test-Plan.docx` | Test strategy | -## 11. Aenderungshistorie +## 11. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|---------------------|-------------| -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 1.0 | 2026-05-12 | First release | S. Lohmaier| diff --git a/docs/plans-md/QA-Plan.md b/docs/plans-md/QA-Plan.md index fe94571..dfdc9e0 100644 --- a/docs/plans-md/QA-Plan.md +++ b/docs/plans-md/QA-Plan.md @@ -1,67 +1,67 @@ -# Qualitaetssicherungs-Plan (QA-Plan) +# Quality Assurance Plan (QA Plan) -| Feld | Wert | +| Field | Value | |-----------------|--------------------------------------| -| Projekt | demo-epb | -| Datum | 2026-05-11 | +| Project | demo-epb | +| Date | 2026-05-11 | | Version | 1.0 | -| Status | Freigegeben | +| Status | Released | --- -## 1. Qualitaetsziele +## 1. Quality goals -- Vollstaendige Traceability: SYS → SA → SWE → SWA → Code → Test -- 0 MISRA-Required-Violations (Deviations dokumentiert) -- 0 statische-Analyse-Findings auf High/Error-Level -- Coverage-Ziele (siehe SWE-Plan Abschnitt 8) eingehalten -- Alle PRs reviewed und approved +- Complete traceability: SYS → SA → SWE → SWA → Code → Test +- 0 MISRA Required violations (deviations documented) +- 0 static-analysis findings at High / Error level +- Coverage targets met (see SWE Plan section 8) +- All PRs reviewed and approved -## 2. Qualitaetsmassnahmen +## 2. Quality measures -| Massnahme | Tool / Methode | Frequenz | -|---------------------------------|----------------------------|----------------| -| Traceability-Check | `doorstop check` | jeder Push | -| MISRA-Check | Cppcheck + MISRA-Addon | jeder Push | -| Static Analysis | Cppcheck, clang-tidy | jeder Push | -| Unit Tests | CppUTest | jeder Push | -| Coverage | gcov / lcov | jeder Push | -| Peer Review | Gitea PRs | jede Aenderung | -| Architektur-Review | Technical Review, 2 Approver | bei Aenderung | -| Audit-Vorbereitung | doorstop publish + Word-Doku | bei Release | +| Measure | Tool / Method | Frequency | +|----------------------------------|------------------------------|------------------| +| Traceability check | `doorstop check` | every push | +| MISRA check | Cppcheck + MISRA addon | every push | +| Static analysis | Cppcheck, clang-tidy | every push | +| Unit tests | CppUTest | every push | +| Coverage | gcov / lcov | every push | +| Peer review | Gitea PRs | every change | +| Architecture review | Technical review, 2 approvers | on changes | +| Audit preparation | doorstop publish + Word docs | on release | ## 3. Reviews -| Artefakt | Review-Typ | Min. Approver | -|-----------------------------|-------------------|----------------| -| Anforderungen | Technical Review | 1 | -| Architektur-Element | Technical Review | 2 | -| Code (QM / ASIL-A/B) | Peer Review | 1 | -| Code (ASIL-C/D) | Technical Review | 2 | -| Plaene und Berichte | Peer Review | 1 | -| MISRA Deviation Permit | Technical Lead | 1 | +| Artefact | Review type | Min. approvers | +|--------------------------------|---------------------|-----------------| +| Requirements | Technical review | 1 | +| Architecture element | Technical review | 2 | +| Code (QM / ASIL-A/B) | Peer review | 1 | +| Code (ASIL-C/D) | Technical review | 2 | +| Plans and reports | Peer review | 1 | +| MISRA deviation permit | Technical lead | 1 | -## 4. Non-Conformity Management +## 4. Non-conformity management -Abweichungen vom Plan oder von Anforderungen werden als Non-Conformity (NC) dokumentiert: +Deviations from the plan or from requirements are documented as a non-conformity (NC): -- Pfad: `docs/non-conformities/NC-XXX.docx` -- Jede NC erhaelt eine eindeutige ID -- Schwere-Klassifizierung: Critical / Major / Minor -- Korrekturmassnahme und Verifikation werden nachgehalten -- Beispiel-NC vorhanden: NC-001 +- Path: `docs/non-conformities/NC-XXX.docx` +- Each NC has a unique ID +- Severity classification: Critical / Major / Minor +- Corrective action and verification are tracked +- Example NC present: NC-001 -## 5. Audit-Vorbereitung +## 5. Audit preparation -Audit-Faehigkeit wird durchgehend erhalten: +Audit readiness is maintained continuously: -- Git-History ist Audit-Trail (kein direkter Push auf `main`) -- `docs/plans-md/` enthaelt die freigegebenen Plaene (Word in `docs/` daneben) -- `docs/traceability/` enthaelt automatisch generierte Matrizen -- `misra/records/` enthaelt MISRA-Deviation-Records -- `tests/results/` enthaelt Test- und Coverage-Reports (CI-Artefakte) -- `docs/reviews/` enthaelt Review-Protokolle +- Git history is the audit trail (no direct push to `main`) +- `docs/plans-md/` holds the released plans (Word in `docs/` alongside) +- `docs/traceability/` holds the auto-generated matrices +- `misra/records/` holds MISRA deviation records +- `tests/results/` holds test and coverage reports (CI artefacts) +- `docs/reviews/` holds review minutes -## 6. Verbesserungsmassnahmen +## 6. Improvement actions -Jeder Sprint-Abschluss enthaelt eine kurze Lessons-Learned-Notiz in `docs/lessons-learned/`. In dieser Demo verzichtet, da Single-Sprint-Projekt. +Every sprint closure includes a brief lessons-learned note in `docs/lessons-learned/`. Skipped in this demo because it is a single-sprint project. diff --git a/docs/plans-md/RM-Plan.md b/docs/plans-md/RM-Plan.md index f705881..be22eb9 100644 --- a/docs/plans-md/RM-Plan.md +++ b/docs/plans-md/RM-Plan.md @@ -1,111 +1,108 @@ --- doc-id: SLM-EPB-RM-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- -# Risk Management Plan (RM-Plan) +# Risk Management Plan (RM Plan) -| Feld | Wert | -|--------------|----------------------------------------| -| Projekt | demo-epb | -| Dokument-ID | SLM-EPB-RM-001 | -| Version | 1.0 | -| Status | Freigegeben | -| Datum | 2026-05-12 | -| Norm | ASPICE MAN.5 | +| Field | Value | +|---------------|----------------------------------------| +| Project | demo-epb | +| Document ID | SLM-EPB-RM-001 | +| Version | 1.0 | +| Status | Released | +| Date | 2026-05-12 | +| Standard | ASPICE MAN.5 | --- -## 1. Zweck +## 1. Purpose -Identifiziert, bewertet und behandelt **Projekt-Risiken** (organisatorisch, -technisch, Zeitplan, Resource). Abgegrenzt von **funktionalen Sicherheits- -Risiken** (Hazards), die im HARA behandelt werden. +Identifies, assesses, and treats **project risks** (organisational, technical, schedule, resource). Distinct from **functional safety risks** (hazards), which live in the HARA. -## 2. Methodik +## 2. Methodology -| Schritt | Aktion | -|--------------------|-------------------------------------------------| -| 1. Identifikation | Workshops, Lessons-Learned, Stakeholder-Input | -| 2. Klassifikation | Wahrscheinlichkeit (W) x Auswirkung (A) | -| 3. Bewertung | Risk Score = W * A (1-25) | -| 4. Behandlung | Vermeiden / Mindern / Akzeptieren / Transferieren | -| 5. Monitoring | Quartalsweise Review, Statusupdate | +| Step | Activity | +|-------------------|---------------------------------------------------| +| 1. Identification | Workshops, lessons learned, stakeholder input | +| 2. Classification | Probability (P) × Impact (I) | +| 3. Assessment | Risk score = P × I (1-25) | +| 4. Treatment | Avoid / Mitigate / Accept / Transfer | +| 5. Monitoring | Quarterly review, status updates | -### 2.1 Klassifikations-Skala +### 2.1 Classification scale -| Wahrscheinlichkeit | Bedeutung | -|--------------------|----------------------------| -| 1 | Sehr unwahrscheinlich | -| 2 | Unwahrscheinlich | -| 3 | Moeglich | -| 4 | Wahrscheinlich | -| 5 | Sehr wahrscheinlich | +| Probability | Meaning | +|-------------|----------------------------| +| 1 | Very unlikely | +| 2 | Unlikely | +| 3 | Possible | +| 4 | Likely | +| 5 | Very likely | -| Auswirkung | Bedeutung | -|------------|--------------------------------------------| -| 1 | Vernachlaessigbar | -| 2 | Geringe Verzoegerung / Mehraufwand | -| 3 | Spuerbare Auswirkung auf Termin/Budget | -| 4 | Erhebliche Auswirkung, Projekt gefaehrdet | -| 5 | Projekt-Stop | +| Impact | Meaning | +|--------|------------------------------------------| +| 1 | Negligible | +| 2 | Minor delay / additional effort | +| 3 | Noticeable impact on schedule/budget | +| 4 | Significant impact, project at risk | +| 5 | Project stop | -| Score-Bereich | Aktion | -|---------------|------------------------------------------| -| 1-4 | Akzeptieren, monitoren | -| 5-9 | Mindern (Plan) | -| 10-15 | Mindern (sofort, mit Eskalation) | -| 16-25 | Eskalation an Project Owner | +| Score range | Action | +|-------------|----------------------------------------| +| 1-4 | Accept, monitor | +| 5-9 | Mitigate (plan) | +| 10-15 | Mitigate (immediate, with escalation) | +| 16-25 | Escalate to Project Owner | -## 3. Risiko-Register +## 3. Risk register -| ID | Beschreibung | W | A | Score | Behandlung | Status | -|-------|---------------------------------------------------------|---|---|-------|------------------------------------------|----------| -| R-01 | Demo wird als produktreifer Code missverstanden | 3 | 3 | 9 | Disclaimer im README + Project Manual | Mitigated | -| R-02 | MISRA-Tooling-Update bricht CI (false positives) | 2 | 3 | 6 | Tool-Versionen pinnen, Regression-Suite | Mitigated | -| R-03 | Reviewer-Verfuegbarkeit fuer ASIL-D | 3 | 4 | 12 | Self-Review dokumentiert (nur Demo) | Akzeptiert (Demo) | -| R-04 | Gitea-Server-Ausfall | 2 | 4 | 8 | Lokale Klone, regelmaessige Backups | Mitigated | -| R-05 | Apple-Cert-Ablauf ohne Vorwarnung | 3 | 3 | 9 | Renewal-Reminder + 30-Tage-Vorwarnung | Mitigated | -| R-06 | Windows-Build-VM unzuverlaessig (busybox-PATH-Konflikte)| 4 | 2 | 8 | MSYS2 dokumentiert, alt PATH vorne | Open | -| R-07 | macOS act_runner host-mode Cache-Bug | 3 | 2 | 6 | continue-on-error, dokumentiert | Open | -| R-08 | Doorstop-Tooling-Kompatibilitaet bei Update | 2 | 3 | 6 | Eigenes traceability.py, kein doorstop-Dep | Mitigated | -| R-09 | Wissensverlust bei Single-Person-Setup | 4 | 4 | 16 | Project Manual + Dokumentation pflegen | Open | +| ID | Description | P | I | Score | Treatment | Status | +|-------|----------------------------------------------------------|---|---|-------|------------------------------------------|------------| +| R-01 | Demo is mistaken for production-ready code | 3 | 3 | 9 | Disclaimer in README + Project Manual | Mitigated | +| R-02 | MISRA tooling update breaks CI (false positives) | 2 | 3 | 6 | Pin tool versions, regression suite | Mitigated | +| R-03 | Reviewer availability for ASIL-D | 3 | 4 | 12 | Self-review documented (demo only) | Accepted (demo) | +| R-04 | Gitea server outage | 2 | 4 | 8 | Local clones, regular backups | Mitigated | +| R-05 | Apple certificate expiry without warning | 3 | 3 | 9 | Renewal reminder + 30-day notice | Mitigated | +| R-06 | Windows build VM unreliable (busybox-PATH conflicts) | 4 | 2 | 8 | MSYS2 documented, alt PATH ordering | Open | +| R-07 | macOS act_runner host-mode cache bug | 3 | 2 | 6 | continue-on-error, documented | Open | +| R-08 | Doorstop tool compatibility on upgrade | 2 | 3 | 6 | Own traceability.py, no doorstop dep | Mitigated | +| R-09 | Knowledge loss with single-person setup | 4 | 4 | 16 | Maintain Project Manual + documentation | Open | -## 4. Risiko-Reviews +## 4. Risk reviews -| Frequenz | Teilnehmer | Outputs | -|--------------|-------------------------|--------------------------------------| -| Quartalsweise| Project Owner + TL | Aktualisiertes Register, Action-Items | -| Bei Aenderung| Betroffene Rollen | Risiko-Score-Update | -| Bei Release | Project Owner + QA | Restrisiken-Bewertung | +| Frequency | Participants | Outputs | +|--------------|--------------------------|--------------------------------------| +| Quarterly | Project Owner + TL | Updated register, action items | +| On change | Affected roles | Risk score update | +| At release | Project Owner + QA | Residual-risk assessment | -## 5. Eskalations-Pfad +## 5. Escalation path ``` -R-Owner (taeglich) +Risk owner (daily) │ Score > 9 ▼ -Project Owner (woechentlich) +Project Owner (weekly) │ Score > 15 ▼ -Stakeholder / Auftraggeber (sofort) +Stakeholder / Client (immediately) ``` -## 6. Lessons Learned +## 6. Lessons learned -Geschlossene Risiken werden bei Projektabschluss in `docs/lessons-learned/` -zusammengefasst, um in Folge-Projekten besser einschaetzen zu koennen. +Closed risks are summarised at project closure under `docs/lessons-learned/`, to better assess follow-up projects. -## 7. Verwandte Dokumente +## 7. Related documents -- `PM-Plan.docx` — Top-Level-Risiken (Auszug) -- `HARA.docx` — Funktionale Sicherheits-Risiken (Hazards, getrennt von Projekt-Risiken) -- `QA-Plan.docx` — Non-Conformity-Management +- `PM-Plan.docx` — Top-level risks (summary) +- `HARA.docx` — Functional safety risks (hazards, separate from project risks) +- `QA-Plan.docx` — Non-conformity management -## 8. Aenderungshistorie +## 8. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|---------------------|-------------| -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 1.0 | 2026-05-12 | First release | S. Lohmaier| diff --git a/docs/plans-md/SWE-Plan.md b/docs/plans-md/SWE-Plan.md index 2bff111..c5d3ff3 100644 --- a/docs/plans-md/SWE-Plan.md +++ b/docs/plans-md/SWE-Plan.md @@ -1,114 +1,114 @@ -# Software Development Plan (SWE-Plan) +# Software Development Plan (SWE Plan) -| Feld | Wert | +| Field | Value | |-----------------|--------------------------------------| -| Projekt | demo-epb | -| Datum | 2026-05-11 | +| Project | demo-epb | +| Date | 2026-05-11 | | Version | 1.0 | -| Status | Freigegeben | -| ASIL | D (hoechste Komponente) | +| Status | Released | +| ASIL | D (highest component) | --- -## 1. Entwicklungsmethode +## 1. Development method -V-Modell nach ISO 26262 Part 6, iterativ innerhalb der Phasen. Linke Seite: Anforderungen → Architektur → Detailentwurf → Implementierung. Rechte Seite: Unit-Test → Integrationstest → Systemtest. +V-model per ISO 26262 Part 6, iterative within phases. Left side: requirements → architecture → detailed design → implementation. Right side: unit test → integration test → system test. -Aenderungen erfolgen ueber Pull Requests (Change Requests werden in einem Real-Projekt zusaetzlich gefuehrt). +Changes go through pull requests (change requests are tracked separately in a real project). -## 2. Programmiersprache und Standards +## 2. Programming language and standards -| Aspekt | Festlegung | +| Aspect | Decision | |---------------------|-----------------------------------------------------| -| Sprache | C (C99) | -| Coding Standard | MISRA C:2012 (Required + Mandatory einzuhalten) | -| Naming | snake_case fuer Funktionen, UPPER_CASE fuer Makros | -| Header-Format | `@file`, `@arch`, `@reqs` Tags fuer Code → Doku-Link | +| Language | C (C99) | +| Coding standard | MISRA C:2012 (Required + Mandatory mandatory) | +| Naming | snake_case for functions, UPPER_CASE for macros | +| Header format | `@file`, `@arch`, `@reqs` tags linking code to docs | -### MISRA-Handhabung +### MISRA handling -- Required- und Mandatory-Regeln verpflichtend -- Advisory-Regeln projektspezifisch (siehe `misra/permits/`) -- Abweichungen pro Stelle: MISRA Deviation Record (`misra/records/`) -- Projektweite Abweichungen: MISRA Deviation Permit (`misra/permits/`) -- MISRA-Pruefung in der CI (`cppcheck --addon=misra --error-exitcode=1`) +- Required and Mandatory rules are mandatory +- Advisory rules are project-specific (see `misra/permits/`) +- Per-site deviations: MISRA deviation record (`misra/records/`) +- Project-wide deviations: MISRA deviation permit (`misra/permits/`) +- MISRA check runs in CI (`cppcheck --addon=misra --error-exitcode=1`) -## 3. Build-Umgebung +## 3. Build environment -| Komponente | Tool / Version | +| Component | Tool / Version | |--------------------|-----------------------------------------------------| -| Build-System | CMake 3.20+ | -| Compiler | GCC (Host fuer Demo-Tests; ARM-GCC fuer Target) | -| Zielplattform | ARM Cortex-M4 (Annahme; Demo-Tests auf x86_64 Host) | -| Host-Plattform | macOS / Linux x86_64 | -| CI-Runner | Gitea Actions Docker-Image | +| Build system | CMake 3.20+ | +| Compiler | GCC (host for demo tests; ARM-GCC for target) | +| Target platform | ARM Cortex-M4 (assumption; demo tests run on x86_64 host) | +| Host platform | macOS / Linux x86_64 | +| CI runner | Gitea Actions Docker image | -## 4. Branching-Strategie +## 4. Branching strategy ``` -main — Stabiler, freigegebener Stand -develop — Aktueller Entwicklungsstand -feature/SWE-XXX — Feature-Branch pro Anforderung -bugfix/BUG-XXX — Bugfix-Branch +main — stable, released state +develop — current development state +feature/SWE-XXX — feature branch per requirement +bugfix/BUG-XXX — bug-fix branch ``` -- `main` und `develop` sind geschuetzt (kein direkter Push) -- Merge nur ueber PR mit Approval -- Branch-Name enthaelt Issue- oder Anforderungs-Nummer +- `main` and `develop` are protected (no direct push) +- Merge only via PR with approval +- Branch name includes the issue or requirement number -## 5. Review-Verpflichtungen +## 5. Review obligations -| Artefakt | Review-Art | Mindest-Approvals | -|-----------------------------|-------------------|--------------------| -| Quellcode QM / ASIL-A/B | Peer Review | 1 | -| Quellcode ASIL-C/D | Technical Review | 2 | -| Architektur-Dokument | Technical Review | 2 | -| Anforderung | Technical Review | 1 | -| Testfaelle | Peer Review | 1 | -| MISRA Permit | Technical Lead | 1 | +| Artefact | Review type | Min. approvals | +|-----------------------------|---------------------|-----------------| +| Source code QM / ASIL-A/B | Peer review | 1 | +| Source code ASIL-C/D | Technical review | 2 | +| Architecture document | Technical review | 2 | +| Requirement | Technical review | 1 | +| Test cases | Peer review | 1 | +| MISRA permit | Technical lead | 1 | -Single-Person-Demo: Self-Review mit dokumentierter Pruefliste; in einem Real-Projekt nicht zulaessig. +Single-person demo: self-review with documented checklist; not permissible in a real project. ## 6. Definition of Done -- Code kompiliert fehlerfrei -- MISRA-Check in CI ist gruen -- Statische Analyse (Cppcheck, clang-tidy) ohne neue Findings -- Unit Tests gruen -- Coverage-Ziel erreicht -- PR reviewed und approved -- Anforderung mit Test verlinkt (`@reqs` Tag im Code + Test-Datei) -- Architektur-Element verlinkt (`@arch` Tag im Code) +- Code compiles without errors +- MISRA check in CI is green +- Static analysis (Cppcheck, clang-tidy) has no new findings +- Unit tests are green +- Coverage target reached +- PR reviewed and approved +- Requirement linked to a test (`@reqs` tag in code + test file) +- Architecture element linked (`@arch` tag in code) -## 7. Integration und Test-Strategie +## 7. Integration and test strategy -| Teststufe | Verantwortlich | Umgebung | Automatisierung | -|---------------------|----------------|----------------|-----------------| -| Unit Test | Entwickler | Host (x86) | CI | -| Integrationstest | Entwickler | Host / SiL | CI / manuell | -| Systemtest | QA | SiL / HiL | teilweise | -| Abnahmetest | Auftraggeber | HiL / Fahrzeug | manuell | +| Test level | Owner | Environment | Automation | +|--------------------|----------------|---------------|------------------| +| Unit test | Developer | Host (x86) | CI | +| Integration test | Developer | Host / SiL | CI / manual | +| System test | QA | SiL / HiL | partial | +| Acceptance test | Customer | HiL / vehicle | manual | -Demo: nur Unit-Tests auf Host. +Demo: only unit tests on host. -## 8. Coverage-Ziele +## 8. Coverage targets -| ASIL | Statement | Branch | MC/DC | Konkret im Projekt | -|------|-----------|--------|----------|---------------------| -| QM | >= 80% | — | — | Switch Debouncer | -| B | >= 80% | >= 80% | — | Actuator Driver | -| D | >= 90% | >= 90% | >= 80% | Apply Controller | +| ASIL | Statement | Branch | MC/DC | Concrete in this project | +|------|-----------|--------|----------|---------------------------| +| QM | ≥ 80% | — | — | Switch Debouncer | +| B | ≥ 80% | ≥ 80% | — | Actuator Driver | +| D | ≥ 90% | ≥ 90% | ≥ 80% | Apply Controller | -Coverage wird per `gcov` / `lcov` in der CI gemessen und nach `tests/results/coverage/` abgelegt. +Coverage is measured via `gcov` / `lcov` in CI and stored under `tests/results/coverage/`. -## 9. Toolqualifikation +## 9. Tool qualification -| Tool | Verwendung | Qualifikations-Status (Demo) | -|-------------------|------------------------------|----------------------------------------------| -| GCC | Compilation | Eigene Qualifizierung (in Realprojekt) | -| Cppcheck + MISRA | Statische Analyse / MISRA | Tool-Confidence Level TCL2 / Tool-Class T2 | -| CppUTest | Unit-Tests | TCL1 / T1 (Fehler vom Entwickler erkannt) | -| gcov / lcov | Coverage | TCL1 / T1 | -| Doorstop | Traceability | TCL1 / T1 | +| Tool | Use | Qualification status (demo) | +|-------------------|------------------------------|-----------------------------------------------| +| GCC | Compilation | Own qualification (in real project) | +| Cppcheck + MISRA | Static analysis / MISRA | Tool Confidence Level TCL2 / Tool Class T2 | +| CppUTest | Unit tests | TCL1 / T1 (defects caught by developer) | +| gcov / lcov | Coverage | TCL1 / T1 | +| Doorstop | Traceability | TCL1 / T1 | -Demo enthaelt keine vollstaendigen Tool-Qualification-Reports; in einem Real-Projekt waeren diese im Anhang. +The demo does not include full tool-qualification reports; in a real project these would live in an appendix. diff --git a/docs/plans-md/Test-Plan.md b/docs/plans-md/Test-Plan.md index aa61abc..ddb4d65 100644 --- a/docs/plans-md/Test-Plan.md +++ b/docs/plans-md/Test-Plan.md @@ -1,63 +1,63 @@ -# Test-Plan +# Test Plan -| Feld | Wert | +| Field | Value | |-----------------|--------------------------------------| -| Projekt | demo-epb | -| Datum | 2026-05-11 | +| Project | demo-epb | +| Date | 2026-05-11 | | Version | 1.0 | -| Status | Freigegeben | +| Status | Released | --- -## 1. Teststrategie +## 1. Test strategy -Test-First fuer alle Demo-Komponenten. Jede Anforderung erhaelt mindestens einen Test (`@reqs` Tag im Test). Coverage-Ziele wie im SWE-Plan Abschnitt 8. +Test-first for all demo components. Every requirement has at least one test (`@reqs` tag in the test). Coverage targets as in the SWE Plan section 8. -## 2. Teststufen +## 2. Test levels -| Stufe | Scope | Tool | Umgebung | Demo-Status | -|---------------|--------------------|------------|------------|-------------| -| Unit | Funktionen / Module| CppUTest | Host x86 | Vorhanden | -| Integration | Modulzusammenspiel | CppUTest | Host x86 | TBD | -| System | End-to-end | manuell | SiL / HiL | nicht im Demo | -| Abnahme | Kundenabnahme | manuell | HiL / KFZ | nicht im Demo | +| Level | Scope | Tool | Environment | Demo status | +|---------------|--------------------|------------|-------------|---------------| +| Unit | Functions / modules| CppUTest | host x86 | Available | +| Integration | Module interaction | CppUTest | host x86 | TBD | +| System | End-to-end | manual | SiL / HiL | not in demo | +| Acceptance | Customer acceptance| manual | HiL / vehicle | not in demo | -## 3. Test-Verwaltung +## 3. Test management -- Tests liegen in `tests/unit/` (eine Datei pro Modul) -- Test-Datei enthaelt `@reqs` Tag mit den abgedeckten Anforderungs-IDs -- Test-Lauf erfolgt automatisch in der CI bei jedem Push -- Coverage-Report wird als CI-Artefakt unter `tests/results/coverage/` abgelegt +- Tests live in `tests/unit/` (one file per module) +- Each test file carries an `@reqs` tag with the covered requirement IDs +- Tests run automatically in CI on every push +- Coverage report is uploaded as a CI artefact under `tests/results/coverage/` -## 4. Test-Auswahl je Komponente +## 4. Test selection per component -| Komponente | ASIL | Test-Datei | Methodik | -|--------------------|------|--------------------------------------|--------------------------| -| Apply Controller | D | tests/unit/test_apply_controller.cpp | Equivalence Classes + Boundary + MC/DC | -| Actuator Driver | B | tests/unit/test_actuator_driver.cpp | Equivalence Classes + Boundary | -| Switch Debouncer | QM | tests/unit/test_switch_debouncer.cpp | Equivalence Classes | +| Component | ASIL | Test file | Method | +|--------------------|------|---------------------------------------|---------------------------------| +| Apply Controller | D | tests/unit/test_apply_controller.c | Equivalence classes + boundary + MC/DC | +| Actuator Driver | B | tests/unit/test_actuator_driver.c | Equivalence classes + boundary | +| Switch Debouncer | QM | tests/unit/test_switch_debouncer.c | Equivalence classes | -## 5. Eingangs- und Abschlusskriterien +## 5. Entry and exit criteria -**Eingang fuer Testdurchfuehrung:** -- Code kompiliert -- Doorstop-Check gruen -- Statische Analyse ohne kritische Findings +**Entry to test execution:** +- Code compiles +- Doorstop check is green +- Static analysis has no critical findings -**Abschluss:** -- Alle Tests gruen -- Coverage-Ziel erreicht -- Test-Report archiviert +**Exit:** +- All tests green +- Coverage target reached +- Test report archived -## 6. Fehlerverwaltung +## 6. Defect handling -- Test-Fehlschlag = blockendes Issue -- Issue wird ueber Gitea Issues angelegt, im PR referenziert -- Schwere-Kategorisierung wie in QA-Plan Abschnitt 4 +- Test failure = blocking issue +- Issue is filed via Gitea Issues, referenced in the PR +- Severity classification per QA Plan section 4 ## 7. Reporting -Test-Reports werden automatisch erzeugt: -- Konsolen-Output von CppUTest (TAP / JUnit XML) -- Coverage-HTML aus lcov -- Beides als CI-Artefakt unter `tests/results/` +Test reports are generated automatically: +- Console output of CppUTest (TAP / JUnit XML) +- Coverage HTML from lcov +- Both as CI artefacts under `tests/results/` diff --git a/docs/reviews-md/Review-001.md b/docs/reviews-md/Review-001.md index 3f3b709..4988149 100644 --- a/docs/reviews-md/Review-001.md +++ b/docs/reviews-md/Review-001.md @@ -1,56 +1,55 @@ --- review-id: REV-001 -projekt: demo-epb -datum: 2026-05-11 -typ: Technical Review (ASIL-D Code) -artefakt: src/apply_controller.c (SWA-002) -status: Approved (mit Anmerkungen) +project: demo-epb +date: 2026-05-11 +type: Technical Review (ASIL-D code) +artefact: src/apply_controller.c (SWA-002) +status: Approved (with comments) --- -# Review-Protokoll REV-001 +# Review Minutes REV-001 -| Feld | Wert | -|--------------|--------------------------------------| -| Review-ID | REV-001 | -| Projekt | demo-epb | -| Datum | 2026-05-11 | -| Reviewer 1 | Stefan Lohmaier (Self-Review) | -| Reviewer 2 | (Tech Lead, in Realprojekt) | -| Artefakt | `src/apply_controller.c` v1.0 | +| Field | Value | +|---------------|--------------------------------------| +| Review ID | REV-001 | +| Project | demo-epb | +| Date | 2026-05-11 | +| Reviewer 1 | Stefan Lohmaier (self-review) | +| Reviewer 2 | (Tech Lead, in real project) | +| Artefact | `src/apply_controller.c` v1.0 | | ASIL | D | | Status | Approved with comments | --- -## 1. Pruefumfang +## 1. Scope of review -- Code-Inspektion `apply_controller.c` + `.h` -- Pruefung auf Vollstaendigkeit der State Machine (Coverage gegen SWA-002) -- Pruefung der MISRA-Compliance (Cppcheck-Report) -- Pruefung der Mapping-Tags (`@arch`, `@reqs`) -- Pruefung der Unit-Tests gegen verlinkte Anforderungen SWE-001..SWE-004 +- Code inspection of `apply_controller.c` + `.h` +- Check for completeness of the state machine (coverage against SWA-002) +- Check for MISRA compliance (Cppcheck report) +- Check of mapping tags (`@arch`, `@reqs`) +- Check of unit tests against the linked requirements SWE-001..SWE-004 ## 2. Findings -| Nr | Schwere | Beschreibung | Aktion | +| Nr | Severity | Description | Action | |----|-----------|--------------------------------------------------------------------|---------------------| -| 1 | Minor | Kommentar "/* @reqs SWE-005 */" konsumiert Anforderung, die formal SWA-002 zugeordnet ist — Mapping-Tabelle bestaetigt aber Mehrfachzuordnung. | Akzeptiert mit Hinweis in SWA-002 §8. | -| 2 | Major | Kein expliziter Test fuer das Verhalten "release im RELEASING-Zustand wird ignoriert". | Test ergaenzt in nachfolgendem PR. | -| 3 | Critical | `s_ctx.step_count` ueberlaeuft alle 2^32 * 50 ms = ~7 Jahre. Im sicheren Zustand ist Ueberlauf unkritisch (Watchdog vergleicht Delta), aber sollte dokumentiert sein. | Kommentar im Header ergaenzt. | +| 1 | Minor | The comment "/* @reqs SWE-005 */" consumes a requirement formally assigned to SWA-002 — mapping table confirms multi-assignment though. | Accepted with note in SWA-002 §8. | +| 2 | Major | No explicit test for the behaviour "release during the RELEASING state is ignored". | Test added in follow-up PR. | +| 3 | Critical | `s_ctx.step_count` overflows after 2^32 * 50 ms = ~7 years. Overflow is harmless in the safe state (watchdog compares deltas) but should be documented. | Comment added in header. | -Critical-Finding 3 wurde als Non-Conformity NC-001 erfasst und in v1.1 geschlossen. +Critical finding 3 was raised as Non-Conformity NC-001 and closed in v1.1. -## 3. Pruefung der Mapping-Tags +## 3. Check of mapping tags ``` @arch SWA-002 OK @reqs SWE-001 SWE-002 SWE-003 SWE-004 OK ``` -Alle vier SWE-Reqs werden durch Test-Faelle in `tests/unit/test_apply_controller.c` -abgedeckt: +All four SWE requirements are covered by test cases in `tests/unit/test_apply_controller.c`: -| SWE | Test-Funktion | +| SWE | Test function | |---------|---------------------------------------------------------| | SWE-001 | `test_applied_holds_force` | | SWE-002 | `test_watchdog_alive_counter` | @@ -59,20 +58,18 @@ abgedeckt: ## 4. Coverage -| Metrik | Ziel | Erreicht | +| Metric | Target | Achieved | |---------------------|------------|-----------| -| Statement Coverage | >= 90% | 92.3% | -| Branch Coverage | >= 90% | 91.0% | -| MC/DC | >= 80% | 84% | +| Statement Coverage | ≥ 90% | 92.3% | +| Branch Coverage | ≥ 90% | 91.0% | +| MC/DC | ≥ 80% | 84% | -Coverage-Report: CI-Artefakt `coverage-html` (Build #N). +Coverage report: CI artefact `coverage-html` (build #N). -## 5. Freigabe-Entscheidung +## 5. Release decision -**Approved with comments.** Critical-Finding wird als NC-001 separat behandelt. -Empfehlung fuer Real-Projekt: zweiter unabhaengiger Reviewer fuer ASIL-D. +**Approved with comments.** Critical finding tracked as NC-001 separately. Recommendation for real project: second independent reviewer for ASIL-D. --- -*Single-Person-Demo: Self-Review nach dokumentierter Pruefliste. In einem Real-Projekt -ist Self-Review fuer ASIL-D unzulaessig (SWE-Plan, Abschnitt 5).* +*Single-person demo: self-review per documented checklist. In a real project, self-review for ASIL-D is not admissible (SWE Plan section 5).* diff --git a/docs/reviews/REV-001.docx b/docs/reviews/REV-001.docx index f29a454..2fa3836 100644 Binary files a/docs/reviews/REV-001.docx and b/docs/reviews/REV-001.docx differ diff --git a/docs/safety-md/FMEDA.md b/docs/safety-md/FMEDA.md index 4503275..2fc1171 100644 --- a/docs/safety-md/FMEDA.md +++ b/docs/safety-md/FMEDA.md @@ -1,119 +1,111 @@ --- doc-id: SLM-EPB-FMEDA-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- # Failure Mode Effects and Diagnostic Analysis (FMEDA) -| Feld | Wert | -|--------------|----------------------------------------| -| Projekt | demo-epb | -| Dokument-ID | SLM-EPB-FMEDA-001 | -| Version | 1.0 | -| Status | Freigegeben | -| Datum | 2026-05-12 | -| Norm | ISO 26262 Part 5 §8 + Part 10 | +| Field | Value | +|---------------|----------------------------------------| +| Project | demo-epb | +| Document ID | SLM-EPB-FMEDA-001 | +| Version | 1.0 | +| Status | Released | +| Date | 2026-05-12 | +| Standard | ISO 26262 Part 5 §8 + Part 10 | --- -## 1. Zweck +## 1. Purpose -Bottom-up-Analyse der Hardware- und Software-Fehlermoeglichkeiten der EPB, -Quantifizierung der Diagnostic Coverage (DC) und Berechnung der Single-Point -Fault Metric (SPFM) und Latent Fault Metric (LFM). Wird zur Bewertung der -Hardware-Architektur-Metriken nach ISO 26262-5 benoetigt. +Bottom-up analysis of EPB hardware and software failure modes, quantifying Diagnostic Coverage (DC) and computing the Single-Point Fault Metric (SPFM) and Latent Fault Metric (LFM). Required for hardware architecture metrics per ISO 26262-5. -In dieser Demo wird der **Software-Anteil** behandelt; der Hardware-FMEDA -ergeht separat (Komponenten-Hersteller). +This demo covers the **software** portion; the hardware FMEDA is provided separately (component manufacturer). -## 2. Methodik +## 2. Methodology -Pro Software-Komponente werden mogliche Failure Modes aufgelistet, ihre -Effekte beschrieben, Detection-Mechanismen identifiziert und die -Diagnostic Coverage abgeschaetzt. +For each software component, possible failure modes are listed, their effects described, detection mechanisms identified, and the diagnostic coverage estimated. -DC-Klassen nach ISO 26262-5 §C.2: +DC classes per ISO 26262-5 §C.2: -| DC-Klasse | DC % | Bedeutung | +| DC class | DC % | Meaning | |-----------|-------|--------------------------------------| -| Low | < 60% | Schwache Diagnose | -| Medium | 60-90%| Mittlere Diagnose | -| High | > 90% | Starke Diagnose | +| Low | < 60% | Weak diagnostics | +| Medium | 60-90%| Medium diagnostics | +| High | > 90% | Strong diagnostics | -## 3. FMEDA-Tabelle pro Komponente +## 3. FMEDA table per component ### 3.1 SWA-002 Apply Controller (ASIL-D) -| FM-ID | Failure Mode | Effekt | Detection | DC | Safe State erreicht? | +| FM-ID | Failure mode | Effect | Detection | DC | Safe state reached? | |-------|---------------------------------------|--------------------------------------|---------------------------------|-------|----------------------| -| FM-01 | State-Machine bleibt in APPLYING haengen | Bremse nie applied | Timeout 30*50ms -> ERROR | High | Ja (ERROR-State) | -| FM-02 | Falscher State-Uebergang APPLIED->RELEASED ohne Bedingung | Wegrollen | Vorbedingungs-Check (`release_preconditions_ok`) | High | Ja | -| FM-03 | Watchdog-Counter ueberlaeuft | Watchdog feuert false-positive | Wrap-safe Subtraktion in Watchdog (NC-001) | High | Ja (Reset) | -| FM-04 | Hold-Loop regelt nicht nach | Klemmkraftverlust unerkannt | Periodische Pruefung alle 50ms + force-tolerance | High | Ja (Re-Apply) | -| FM-05 | NULL-Pointer-Dereferenzierung Input | Crash | Early-Exit Check | High | Ja (Letzter Zustand bleibt) | +| FM-01 | State machine stuck in APPLYING | Brake never applied | Timeout 30×50ms → ERROR | High | Yes (ERROR state) | +| FM-02 | Wrong state transition APPLIED → RELEASED without condition | Roll-away | Precondition check (`release_preconditions_ok`) | High | Yes | +| FM-03 | Watchdog counter overflow | Watchdog fires false positive | Wrap-safe subtraction in watchdog (NC-001) | High | Yes (reset) | +| FM-04 | Hold loop does not re-clamp | Clamping force loss undetected | Periodic check every 50ms + force tolerance | High | Yes (re-apply) | +| FM-05 | NULL pointer dereference on input | Crash | Early-exit check | High | Yes (last state remains) | -Aggregierte DC fuer Apply Controller: **96 %** (High). +Aggregated DC for Apply Controller: **96%** (High). ### 3.2 SWA-003 Actuator Driver (ASIL-B) -| FM-ID | Failure Mode | Effekt | Detection | DC | +| FM-ID | Failure mode | Effect | Detection | DC | |-------|------------------------------------------|--------------------------------------|---------------------------------|-------| -| FM-06 | PWM-Wert ausserhalb 0..100 | Hardware-Schaden | Parameter-Check, return EINVAL | High | -| FM-07 | ISR misst zu hohen Strom kontinuierlich | Motor-Brand | Overcurrent-Cutoff > 8A > 100ms | High | -| FM-08 | ISR misst zu niedrigen Strom (Sensor-Fehler) | Klemmkraft falsch geschaetzt | Cross-Check beider Aktoren | Medium | -| FM-09 | Beide Aktoren gleichzeitiger Cutoff | EPB inoperativ | DTC + Service-Mode bleibt zugaenglich | Medium | +| FM-06 | PWM value outside 0..100 | Hardware damage | Parameter check, return EINVAL | High | +| FM-07 | ISR measures continuously high current | Motor fire | Overcurrent cutoff > 8A > 100ms | High | +| FM-08 | ISR measures too-low current (sensor fault) | Clamping force estimated wrong | Cross-check between actuators | Medium | +| FM-09 | Both actuators simultaneous cutoff | EPB inoperative | DTC + service mode remains reachable | Medium | -Aggregierte DC fuer Actuator Driver: **85 %** (Medium). +Aggregated DC for Actuator Driver: **85%** (Medium). ### 3.3 SWA-001 Safety Manager (ASIL-D) -| FM-ID | Failure Mode | Effekt | Detection | DC | +| FM-ID | Failure mode | Effect | Detection | DC | |-------|------------------------------------------|--------------------------------------|---------------------------------|-------| -| FM-10 | Auto-Apply-Timer feuert nicht | Fahrzeug rollt nach Motor-Aus | Watchdog Safety-Manager | High | -| FM-11 | Hill-Hold-Uebergabe verzoegert | Rollen am Berg | Bremspedal-Signal-Verfolgung | High | -| FM-12 | False-Positive Hill-Hold-Aktivierung | Unnoetiges Apply | Filter-Tiefpass Inclinometer | Medium | -| FM-13 | Grade-Filter Saturation | Hill-Hold verpasst | Plausibilitaets-Check (Range) | Medium | +| FM-10 | Auto-apply timer does not fire | Vehicle rolls after engine off | Watchdog Safety Manager | High | +| FM-11 | Hill-hold handover delayed | Roll-away on incline | Brake-pedal signal tracking | High | +| FM-12 | False-positive hill-hold activation | Unnecessary apply | Low-pass filter inclinometer | Medium | +| FM-13 | Grade filter saturation | Hill-hold missed | Plausibility range check | Medium | -Aggregierte DC fuer Safety Manager: **88 %** (Medium-High). +Aggregated DC for Safety Manager: **88%** (Medium-High). -### 3.4 SWA-004 Wheel Speed Plausibilisierung (ASIL-B) +### 3.4 SWA-004 Wheel Speed Plausibilisation (ASIL-B) -| FM-ID | Failure Mode | Effekt | Detection | DC | +| FM-ID | Failure mode | Effect | Detection | DC | |-------|------------------------------------------|--------------------------------------|---------------------------------|-------| -| FM-14 | Stuck-At-Zero auf einem Rad | Falscher Stillstand erkannt | Spreizung > 3 km/h Check + DTC | High | -| FM-15 | Alle 4 Sensoren ausgefallen | Stillstand unerkannt | Komplettausfall-DTC + Vorlast-Annahme | High | +| FM-14 | Stuck-at-zero on one wheel | False standstill detected | Spread > 3 km/h check + DTC | High | +| FM-15 | All 4 sensors failed | Standstill undetected | Total-failure DTC + load assumption | High | -DC: **95 %** (High). +DC: **95%** (High). -## 4. Aggregierte Metriken (Software) +## 4. Aggregated metrics (software) -| Metrik | Wert | Anforderung ASIL-D | -|------------------------------|---------|------------------------| -| SPFM (Single-Point Fault) | 95 % | >= 99 % (Software allein nicht ausreichend, HW erforderlich) | -| LFM (Latent Fault) | 90 % | >= 90 % | -| Aggregated DC | 92 % | High | +| Metric | Value | ASIL-D requirement | +|------------------------------|---------|--------------------------------------| +| SPFM (Single-Point Fault) | 95% | ≥ 99% (software alone insufficient; HW required) | +| LFM (Latent Fault) | 90% | ≥ 90% | +| Aggregated DC | 92% | High | -**Hinweis:** Die hier berichteten Software-DC-Werte sind keine ASIL-D-Hardware- -Metriken. ASIL-D-konforme SPFM/LFM benoetigen quantitative Hardware-FIT-Raten, -die auf HW-Ebene berechnet werden (Tier-1-Aktoren, ECU-Hardware). +**Note:** The software DC values reported here are not the ASIL-D hardware metrics. ASIL-D-compliant SPFM/LFM require quantitative hardware FIT rates, which are computed at the HW level (Tier-1 actuators, ECU hardware). -## 5. Diagnose-Massnahmen (Inventar) +## 5. Diagnostic measures (inventory) -| Mechanismus | Komponente | Trigger | +| Mechanism | Component | Trigger | |------------------------------|-----------------------|----------------------------------------| -| Timeout-Watchdog | Apply Controller | 30*50ms im APPLYING | -| Klemmkraft-Hold-Check | Apply Controller | alle 50ms | -| Overcurrent-Cutoff | Actuator Driver | 8A > 100ms | -| Sensor-Spreizungs-Check | Wheel Speed Plausi | jede 10ms-Periode | -| Inclinometer-Range-Check | Inclinometer Filter | jede 10ms | -| Watchdog Safety Manager | Safety Manager | 100ms Liveness | -| Diagnostic Manager UDS DTCs | Diag Manager | Aufruf von `diag_set_dtc()` | +| Timeout watchdog | Apply Controller | 30×50ms in APPLYING | +| Clamping force hold check | Apply Controller | every 50ms | +| Overcurrent cutoff | Actuator Driver | 8A > 100ms | +| Sensor spread check | Wheel Speed Plausi | every 10ms cycle | +| Inclinometer range check | Inclinometer Filter | every 10ms | +| Watchdog Safety Manager | Safety Manager | 100ms liveness | +| Diagnostic Manager UDS DTCs | Diag Manager | call of `diag_set_dtc()` | -## 6. Aenderungshistorie +## 6. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|-------------------------|----------------| -| 0.1 | 2026-05-11 | Initialer Entwurf | S. Lohmaier | -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 0.1 | 2026-05-11 | Initial draft | S. Lohmaier| +| 1.0 | 2026-05-12 | First release | S. Lohmaier| diff --git a/docs/safety-md/HARA.md b/docs/safety-md/HARA.md index 92cd1dd..0c4b43d 100644 --- a/docs/safety-md/HARA.md +++ b/docs/safety-md/HARA.md @@ -1,154 +1,145 @@ --- doc-id: SLM-EPB-HARA-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- # Hazard Analysis & Risk Assessment (HARA) -| Feld | Wert | -|----------------|------------------------------------------------| -| Projekt | demo-epb (Elektrische Parkbremse) | -| Dokument-ID | SLM-EPB-HARA-001 | -| Datum | 2026-05-12 | -| Version | 1.0 | -| Status | Freigegeben | -| Norm | ISO 26262 Part 3 (Concept Phase) | -| Erstellt von | Stefan Lohmaier | -| Geprueft von | (Tech Lead, im Realprojekt unabhaengig) | -| Freigegeben von| (Safety Manager, im Realprojekt unabhaengig) | +| Field | Value | +|-----------------|-------------------------------------------------| +| Project | demo-epb (Electric Parking Brake) | +| Document ID | SLM-EPB-HARA-001 | +| Date | 2026-05-12 | +| Version | 1.0 | +| Status | Released | +| Standard | ISO 26262 Part 3 (Concept Phase) | +| Author | Stefan Lohmaier | +| Reviewer | (Tech Lead, independent in real project) | +| Approver | (Safety Manager, independent in real project) | --- -## 1. Zweck +## 1. Purpose -Identifikation und Klassifikation aller relevanten Hazards der Elektrischen -Parkbremse (EPB) gemaess ISO 26262-3. Aus den Hazards werden Sicherheitsziele -abgeleitet und ein Automotive Safety Integrity Level (ASIL) zugewiesen. +Identification and classification of all relevant EPB hazards per ISO 26262-3. From the hazards, safety goals are derived and an Automotive Safety Integrity Level (ASIL) is assigned. -## 2. Item-Definition +## 2. Item definition -Die EPB ist ein elektromechanisches System, das die hinteren Bremssaettel mit -zwei kleinen Elektromotoren festklemmt und wieder loest. Item-Boundary -(ISO 26262-3 §5): +The EPB is an electromechanical system that clamps both rear callipers using two small electric motors and releases them. Item boundary (ISO 26262-3 §5): -- **Innerhalb:** EPB-ECU, beide Caliper-Motoren, EPB-Schalter, Status-LED -- **Aussen:** ESP, Motormanagement, Bremssystem (hydraulisch), Lenkung -- **Schnittstellen:** CAN-Bus, Wheel-Speed-Sensoren, Inclinometer +- **Inside:** EPB ECU, both calliper motors, EPB switch, status LED +- **Outside:** ESP, engine management, brake system (hydraulic), steering +- **Interfaces:** CAN bus, wheel-speed sensors, inclinometer -## 3. Operational Situations & Hazards +## 3. Operational situations & hazards -Die folgenden Betriebssituationen und Hazards wurden im Concept-Workshop -(2026-05-11) identifiziert: +The following operational situations and hazards were identified in the concept workshop (2026-05-11): -### 3.1 Hazard-Liste +### 3.1 Hazard list -| H-ID | Hazard | Betriebs-Situation | -|-------|------------------------------------------------------|------------------------------------| -| H-01 | Ungewolltes Loesen der Parkbremse im Stillstand | Fahrzeug parkt am Hang, Fahrer aus| -| H-02 | Ungewolltes Festklemmen waehrend der Fahrt | Fahrt > 10 km/h | -| H-03 | Keine Apply-Reaktion auf Fahrer-Anforderung | Stillstand, Fahrer betaetigt Schalter | -| H-04 | Verlust der Klemmkraft im Hold-Zustand | Parkphase laenger als 1 h | -| H-05 | Motorschaden durch Ueberstrom | Aktor-Mechanik blockiert | -| H-06 | Falsche Hill-Hold-Uebergabe (Rollen am Berg) | Anfahrt am Berg | -| H-07 | Keine Release-Reaktion bei Anfahrt | Stillstand, Fahrer will losfahren | -| H-08 | LED-Anzeige falsch | beliebig | +| H-ID | Hazard | Operational situation | +|-------|------------------------------------------------------|--------------------------------------| +| H-01 | Unintended release of the parking brake at standstill | Vehicle parked on incline, driver out| +| H-02 | Unintended clamping during driving | Driving > 10 km/h | +| H-03 | No apply reaction to driver request | Standstill, driver actuates switch | +| H-04 | Loss of clamping force in hold state | Parking phase longer than 1 h | +| H-05 | Motor damage from overcurrent | Actuator mechanics blocked | +| H-06 | Incorrect hill-hold handover (roll-away on incline) | Drive-away on incline | +| H-07 | No release reaction on drive-away | Standstill, driver wants to drive | +| H-08 | LED indicator wrong | any | ### 3.2 Severity / Exposure / Controllability -Klassifikation nach ISO 26262-3 §6: +Classification per ISO 26262-3 §6: -| Severity | Bedeutung | +| Severity | Meaning | |----------|------------------------------------------------------------| -| S0 | Keine Verletzungen | -| S1 | Leichte / moderate Verletzungen | -| S2 | Schwere Verletzungen (Ueberleben wahrscheinlich) | -| S3 | Lebensgefaehrliche Verletzungen (Ueberleben fraglich) | +| S0 | No injuries | +| S1 | Light / moderate injuries | +| S2 | Severe injuries (survival likely) | +| S3 | Life-threatening injuries (survival uncertain) | -| Exposure | Bedeutung | +| Exposure | Meaning | |----------|------------------------------------------------------------| -| E0 | Sehr unwahrscheinlich | -| E1 | Sehr seltene Situation | -| E2 | Seltene Situation | -| E3 | Mittlere Wahrscheinlichkeit | -| E4 | Haeufige Situation | +| E0 | Very unlikely | +| E1 | Very rare situation | +| E2 | Rare situation | +| E3 | Medium likelihood | +| E4 | Frequent situation | -| Controllability | Bedeutung | -|------------------|------------------------------------------------------| -| C0 | Allgemein beherrschbar | -| C1 | Einfach beherrschbar (>99% der Fahrer) | -| C2 | Normal beherrschbar (>90% der Fahrer) | -| C3 | Schwer beherrschbar oder unbeherrschbar | +| Controllability | Meaning | +|------------------|----------------------------------------------------| +| C0 | Generally controllable | +| C1 | Simply controllable (>99% of drivers) | +| C2 | Normally controllable (>90% of drivers) | +| C3 | Difficult to control or uncontrollable | -### 3.3 ASIL-Determination +### 3.3 ASIL determination -| H-ID | Beschreibung | S | E | C | ASIL | -|-------|-------------------------------------------|----|----|----|-------| -| H-01 | Ungewolltes Loesen, Parkphase | S3 | E4 | C3 | **D** | -| H-02 | Ungewolltes Festklemmen waehrend Fahrt | S3 | E4 | C3 | **D** | -| H-03 | Keine Apply-Reaktion auf Anforderung | S2 | E4 | C2 | B | -| H-04 | Klemmkraftverlust im Hold | S3 | E4 | C3 | **D** | -| H-05 | Motorschaden durch Ueberstrom | S1 | E3 | C2 | A | -| H-06 | Hill-Hold-Versagen (Rollen am Berg) | S3 | E3 | C3 | C | -| H-07 | Keine Release-Reaktion | S1 | E4 | C2 | A | -| H-08 | LED-Anzeige falsch | S0 | -- | -- | QM | +| H-ID | Description | S | E | C | ASIL | +|-------|------------------------------------------|----|----|----|-------| +| H-01 | Unintended release, parking phase | S3 | E4 | C3 | **D** | +| H-02 | Unintended clamping during driving | S3 | E4 | C3 | **D** | +| H-03 | No apply reaction to request | S2 | E4 | C2 | B | +| H-04 | Clamping force loss in hold | S3 | E4 | C3 | **D** | +| H-05 | Motor damage from overcurrent | S1 | E3 | C2 | A | +| H-06 | Hill-hold failure (roll-away on incline) | S3 | E3 | C3 | C | +| H-07 | No release reaction | S1 | E4 | C2 | A | +| H-08 | LED indicator wrong | S0 | -- | -- | QM | -ASIL-Matrix laut ISO 26262-3 Table 4 angewandt. H-06 wurde im Review von -ASIL-D auf ASIL-C zurueckgestuft, da Hill-Hold-Ausfall auf trockener Strasse -durch Fahrerreaktion noch beherrschbar (C2-C3-Grenzfall, konservativ C3). +ASIL matrix per ISO 26262-3 Table 4 applied. H-06 was downgraded from ASIL-D to ASIL-C in review, since hill-hold failure on dry road remains controllable through driver response (C2-C3 borderline, conservatively C3). -## 4. Sicherheitsziele (Safety Goals) +## 4. Safety goals -Aus den Hazards werden folgende Safety Goals abgeleitet: +From the hazards the following safety goals are derived: -| SG-ID | Sicherheitsziel | ASIL | Abgedeckte Hazards | -|-------|--------------------------------------------------------------------|-------|----------------------| -| SG-01 | EPB darf sich im Stillstand nicht ungewollt loesen | D | H-01, H-04 | -| SG-02 | EPB darf nicht ungewollt waehrend der Fahrt festklemmen | D | H-02 | -| SG-03 | EPB muss Schutz gegen Aktor-Ueberstrom bieten | A | H-05 | -| SG-04 | Hill-Hold muss zuverlaessig an Apply Controller uebergeben | C | H-06 | -| SG-05 | EPB muss auf Fahreranforderung in spezifizierter Zeit reagieren | B | H-03, H-07 | +| SG-ID | Safety goal | ASIL | Covered hazards | +|-------|-------------------------------------------------------------------|-------|----------------------| +| SG-01 | The EPB must not unintentionally release while at standstill | D | H-01, H-04 | +| SG-02 | The EPB must not unintentionally clamp while driving | D | H-02 | +| SG-03 | The EPB must protect against actuator overcurrent | A | H-05 | +| SG-04 | Hill-hold must reliably hand over to the apply controller | C | H-06 | +| SG-05 | The EPB must respond to driver requests within specified times | B | H-03, H-07 | -## 5. Safe State +## 5. Safe state -Definitionen aus ISO 26262-3 §7.4.2.5: +Definitions per ISO 26262-3 §7.4.2.5: -| Item / Funktion | Safe State | +| Item / Function | Safe state | |------------------------|------------------------------------------------------------| -| Apply-Phase | Aktor stoppen, Status auf APPLIED setzen | -| Hold-Phase | Klemmkraft beibehalten (passiv) | -| Release-Phase | Auf Apply zurueckkehren, Klemmkraft halten | -| Bei Hardware-Fehler | APPLIED-Zustand erzwingen (verhindert Wegrollen) | +| Apply phase | Stop actuator, set status to APPLIED | +| Hold phase | Maintain clamping force (passive) | +| Release phase | Return to apply, maintain clamping force | +| On hardware fault | Force APPLIED state (prevents roll-away) | -Der ueber alle Faelle "konservative" Safe State ist **APPLIED**: lieber zu -viel klemmen als zu wenig. +The conservative safe state across all cases is **APPLIED**: rather over-clamp than under-clamp. ## 6. FTTI (Fault Tolerant Time Interval) -| Hazard | FTTI | Begruendung | +| Hazard | FTTI | Rationale | |--------|---------|-----------------------------------------------------------| -| H-01 | 5 s | Wegrollen am Berg startet typ. nach 1-2 s, Hand-Aktion mglich nach ca. 5 s | -| H-02 | 100 ms | Stoss-Verlangsamung bei 50 km/h muss innerhalb 100 ms erkannt werden | -| H-04 | 30 s | Klemmkraftverlust akkumuliert langsam, periodische Pruefung alle 50ms reicht | -| H-06 | 500 ms | Hill-Hold-Uebergabe muss vor Rollbeginn (< 500ms) abgeschlossen sein | +| H-01 | 5 s | Roll-away on incline starts after ~1-2 s, hand action possible after ~5 s | +| H-02 | 100 ms | Shock deceleration at 50 km/h must be detected within 100 ms | +| H-04 | 30 s | Clamping force loss accumulates slowly, periodic check every 50 ms suffices | +| H-06 | 500 ms | Hill-hold handover must complete before roll-away begins (< 500 ms) | -## 7. Funktionale Sicherheitsanforderungen (FSR) +## 7. Functional Safety Requirements (FSR) -Aus den Safety Goals werden in `reqs/sys/` die SYS-Anforderungen abgeleitet -(siehe Traceability-Matrix). Mapping: +From the safety goals the SYS requirements in `reqs/sys/` are derived (see traceability matrix). Mapping: -| SG-ID | SYS-Anforderungen | +| SG-ID | SYS requirements | |-------|----------------------------------------------------| | SG-01 | SYS-001, SYS-004 | -| SG-02 | SYS-002 (Apply-Plausibilisierung), SYS-005 | +| SG-02 | SYS-002 (apply plausibility), SYS-005 | | SG-03 | SYS-007 | | SG-04 | SYS-005, SYS-006 | | SG-05 | SYS-002, SYS-003 | -## 8. Aenderungshistorie +## 8. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|-------------------------|----------------| -| 0.1 | 2026-05-11 | Initialer Entwurf | S. Lohmaier | -| 1.0 | 2026-05-12 | Erstfreigabe nach Review| S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|-------------------------|-----------------| +| 0.1 | 2026-05-11 | Initial draft | S. Lohmaier | +| 1.0 | 2026-05-12 | First release after review | S. Lohmaier | diff --git a/docs/safety-md/MISRA-Compliance-Statement.md b/docs/safety-md/MISRA-Compliance-Statement.md index ccc1cee..8933e64 100644 --- a/docs/safety-md/MISRA-Compliance-Statement.md +++ b/docs/safety-md/MISRA-Compliance-Statement.md @@ -1,58 +1,55 @@ --- doc-id: SLM-EPB-MISRA-COMP-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- # MISRA C:2012 Compliance Statement -| Feld | Wert | -|--------------|----------------------------------------| -| Projekt | demo-epb | -| Dokument-ID | SLM-EPB-MISRA-COMP-001 | -| Datum | 2026-05-12 | -| Standard | MISRA C:2012 (inkl. Amendment 1) | -| Compiler | GCC 11.2 (Linux CI) / GCC 16.1 (Win) | -| Checker | Cppcheck 2.7+ mit `--addon=misra` | +| Field | Value | +|---------------|----------------------------------------| +| Project | demo-epb | +| Document ID | SLM-EPB-MISRA-COMP-001 | +| Date | 2026-05-12 | +| Standard | MISRA C:2012 (incl. Amendment 1) | +| Compiler | GCC 11.2 (Linux CI) / GCC 16.1 (Win) | +| Checker | Cppcheck 2.7+ with `--addon=misra` | --- -## 1. Zusammenfassung +## 1. Summary -Der Quellcode von demo-epb wurde gegen MISRA C:2012 geprueft. -Alle **Required** und **Mandatory** Regeln werden eingehalten, mit Ausnahme -von einer dokumentierten Deviation (siehe MISRA-REC-001). +The source code of demo-epb has been checked against MISRA C:2012. All **Required** and **Mandatory** rules are observed, with the exception of one documented deviation (see MISRA-REC-001). -**Compliance-Erklaerung:** demo-epb v1.0 ist **MISRA C:2012 compliant** unter -Beruecksichtigung dokumentierter Deviation Records. +**Compliance statement:** demo-epb v1.0 is **MISRA C:2012 compliant** taking into account the documented deviation records. -## 2. Geltungsbereich +## 2. Scope -| Modul | MISRA-konform geprueft | -|----------------------|-----------------------------| -| `src/switch_debouncer.{c,h}` | Ja | -| `src/actuator_driver.{c,h}` | Ja | -| `src/apply_controller.{c,h}` | Ja | -| `src/safety_manager.{c,h}` | Ja | -| `src/epb_types.h` | Ja | -| `src/stubs/*.h` | Header-only, keine MISRA-relevanten Implementierungen | -| `tests/**/*` | Nicht im Geltungsbereich (Test-Code) | -| `tools/**/*` | Nicht im Geltungsbereich (Python-Skripte) | +| Module | MISRA-checked | +|------------------------------|--------------------------| +| `src/switch_debouncer.{c,h}` | Yes | +| `src/actuator_driver.{c,h}` | Yes | +| `src/apply_controller.{c,h}` | Yes | +| `src/safety_manager.{c,h}` | Yes | +| `src/epb_types.h` | Yes | +| `src/stubs/*.h` | Header-only, no MISRA-relevant implementations | +| `tests/**/*` | Out of scope (test code) | +| `tools/**/*` | Out of scope (Python scripts) | -## 3. Regel-Aktivierung +## 3. Rule activation -Cppcheck MISRA-Addon prueft die folgenden Regel-Kategorien: +The Cppcheck MISRA addon checks the following rule categories: -| Kategorie | Anzahl | Aktivierung im Projekt | -|-----------|--------|--------------------------------| -| Mandatory | 9 | Alle aktiviert, Verletzung blockt Build | -| Required | 119 | Alle aktiviert, Verletzung blockt Build | -| Advisory | 47 | Aktiviert mit Warning-Level, Deviations zulaessig per Record | +| Category | Count | Activation in project | +|-----------|--------|----------------------------------| +| Mandatory | 9 | All active, violation blocks build | +| Required | 119 | All active, violation blocks build | +| Advisory | 47 | Active at warning level, deviations allowed per record | -## 4. Compliance-Status pro Regel-Kategorie +## 4. Compliance status per rule category -### 4.1 Mandatory Rules (9) +### 4.1 Mandatory rules (9) | Rule | Status | |-------------|------------| @@ -61,15 +58,15 @@ Cppcheck MISRA-Addon prueft die folgenden Regel-Kategorien: | R 19.1, R 21.13, R 21.17 | Compliant | | R 21.18, R 21.19, R 21.20 | Compliant | -**Mandatory Status: 100 % Compliant.** +**Mandatory status: 100% Compliant.** -### 4.2 Required Rules +### 4.2 Required rules -Gesamt: 119 Required Rules. Verletzungen: **0**. +Total: 119 Required rules. Violations: **0**. -Top-relevante Rules fuer dieses Projekt: +Top relevant rules for this project: -| Rule | Beschreibung | Status | +| Rule | Description | Status | |---------|----------------------------------------------------------|----------| | R 8.1 | Type specifier shall be explicit | Compliant | | R 8.2 | Function parameters shall be explicitly named | Compliant | @@ -78,21 +75,21 @@ Top-relevante Rules fuer dieses Projekt: | R 14.1 | Loop counter shall not have essentially floating type | Compliant | | R 14.4 | Controlling expression shall have essentially Boolean type | Compliant | | R 15.4 | At most one break or goto per loop | Compliant | -| R 17.7 | Return value of non-void function shall be used | Compliant (oder explizit `(void)`) | -| R 21.3 | No dynamic memory allocation (malloc/free) | Compliant (keine Heap-Nutzung) | +| R 17.7 | Return value of non-void function shall be used | Compliant (or explicit `(void)`) | +| R 21.3 | No dynamic memory allocation (malloc/free) | Compliant (no heap use) | | R 21.4 | No setjmp/longjmp | Compliant | -### 4.3 Advisory Rules +### 4.3 Advisory rules -47 Advisory Rules. Verletzungen werden via MISRA Deviation Records dokumentiert. +47 Advisory rules. Violations are documented via MISRA deviation records. -| Record-ID | Rule | Datei | Begruendung-Auszug | +| Record ID | Rule | File | Rationale summary | |-------------------|---------|-------------------------------|-----------------------------| -| MISRA-REC-001 | R 15.5 | `src/apply_controller.c:64` | Early-Exit fuer NULL-Check | +| MISRA-REC-001 | R 15.5 | `src/apply_controller.c:64` | Early-exit for NULL check | -**Advisory Status: 1 Deviation Record, dokumentiert.** +**Advisory status: 1 deviation record, documented.** -## 5. Pruef-Pipeline +## 5. Check pipeline ```bash cppcheck \ @@ -105,26 +102,26 @@ cppcheck \ -I src src ``` -Pruefung erfolgt: -- Lokal vor jedem Commit (empfohlen) -- Automatisch in CI bei jedem Push und PR -- Vor jedem Release (Tag-Push triggert release.yml) +Checks are run: +- Locally before each commit (recommended) +- Automatically in CI on every push and PR +- Before each release (tag push triggers release.yml) -## 6. Deviation Permits (projektweit) +## 6. Deviation Permits (project-wide) -Keine projektweiten Permits aktiv. +No project-wide permits are active. -## 7. Re-Audit-Trigger +## 7. Re-audit triggers -Diese Compliance-Erklaerung muss bei folgenden Aenderungen neu erstellt werden: +This compliance statement must be re-created on the following changes: -- Compiler-Wechsel (z.B. GCC -> Clang) -- Major-Update von Cppcheck oder MISRA-Addon -- Neue Quelldateien ausserhalb `src/` -- MISRA-Standard-Update (z.B. C:2025 Release) +- Compiler change (e.g. GCC → Clang) +- Major update of Cppcheck or the MISRA addon +- New source files outside `src/` +- MISRA standard update (e.g. C:2025 release) -## 8. Aenderungshistorie +## 8. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|-------------------------|----------------| -| 1.0 | 2026-05-12 | Erstfreigabe v1.0 | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 1.0 | 2026-05-12 | First release v1.0 | S. Lohmaier| diff --git a/docs/safety-md/Safety-Case.md b/docs/safety-md/Safety-Case.md index 8a7c80b..0bbbd06 100644 --- a/docs/safety-md/Safety-Case.md +++ b/docs/safety-md/Safety-Case.md @@ -1,139 +1,136 @@ --- doc-id: SLM-EPB-SC-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- # Safety Case — demo-epb -| Feld | Wert | -|----------------|------------------------------------------------| -| Projekt | demo-epb | -| Dokument-ID | SLM-EPB-SC-001 | -| Datum | 2026-05-12 | -| Version | 1.0 | -| Status | Freigegeben | -| Norm | ISO 26262 Part 2 §6.5 + Part 6 §6 | -| Erstellt von | Stefan Lohmaier | -| Freigegeben von| (Safety Manager, im Realprojekt) | +| Field | Value | +|-----------------|-------------------------------------------------| +| Project | demo-epb | +| Document ID | SLM-EPB-SC-001 | +| Date | 2026-05-12 | +| Version | 1.0 | +| Status | Released | +| Standard | ISO 26262 Part 2 §6.5 + Part 6 §6 | +| Author | Stefan Lohmaier | +| Approver | (Safety Manager, in real project) | --- -## 1. Zweck +## 1. Purpose -Argumentation, dass das EPB-System die in der HARA identifizierten -Sicherheitsziele erfuellt. Strukturiert nach Goal Structuring Notation -(GSN), in tabellarischer Form fuer Audit-Zwecke. +Argument that the EPB system satisfies the safety goals identified in the HARA. Structured per Goal Structuring Notation (GSN), in tabular form for audit purposes. -## 2. Top-Goal +## 2. Top goal -**G0:** Die EPB-Software erfuellt alle Safety Goals (SG-01 bis SG-05) der HARA -mit angemessener Konfidenz fuer ASIL D / C / B / A. +**G0:** The EPB software satisfies all safety goals (SG-01 to SG-05) from the HARA with adequate confidence for ASIL D / C / B / A. -## 3. Argument-Struktur +## 3. Argument structure -| Goal | Behauptung | Strategie | Evidenz | -|------|------------------------------------------------------|------------------------------------------|------------------------------------------| -| G0 | EPB erfuellt alle SG aus HARA | Decomposition nach SG | G1, G2, G3, G4, G5 | -| G1 | SG-01 (kein ungewolltes Loesen) ist erfuellt | Architektonisch + Test + Review | SWA-002 + Tests + Code-Review | -| G2 | SG-02 (kein ungewolltes Apply) ist erfuellt | Architektonisch + Plausibilisierung | SWA-002 standstill-check + Tests | -| G3 | SG-03 (Schutz vor Ueberstrom) ist erfuellt | Architektonisch + Test | SWA-003 overcurrent-cutoff + Tests | -| G4 | SG-04 (Hill-Hold-Uebergabe) ist erfuellt | Architektonisch + Sequenz-Test | SWA-001 + Tests | -| G5 | SG-05 (Reaktionszeit) ist erfuellt | Performance-Messung + Test | Step-Timing-Tests | +| Goal | Claim | Strategy | Evidence | +|------|---------------------------------------------------------|------------------------------------------|--------------------------------------------| +| G0 | EPB satisfies all SGs from HARA | Decomposition by SG | G1, G2, G3, G4, G5 | +| G1 | SG-01 (no unintended release) is satisfied | Architectural + test + review | SWA-002 + tests + code review | +| G2 | SG-02 (no unintended apply) is satisfied | Architectural + plausibilisation | SWA-002 standstill check + tests | +| G3 | SG-03 (overcurrent protection) is satisfied | Architectural + test | SWA-003 overcurrent cutoff + tests | +| G4 | SG-04 (hill-hold handover) is satisfied | Architectural + sequence test | SWA-001 + tests | +| G5 | SG-05 (response time) is satisfied | Performance measurement + test | Step timing tests | -## 4. Detail-Argumente +## 4. Detail arguments -### G1 — SG-01: Kein ungewolltes Loesen +### G1 — SG-01: No unintended release **Argument:** -| # | Aussage | Beleg | -|---|-----------------------------------------------------------------------|--------------------------------------| -| 1 | Apply Controller verlaesst APPLIED nur bei expliziter Release-Anforderung mit Vorbedingungen | `apply_controller.c` Zeile 95-110 (`case EPB_STATE_APPLIED`) | -| 2 | Release-Vorbedingungen pruefen Engine + Brake + Gear | `release_preconditions_ok()` + SWE-005 | -| 3 | Watchdog erkennt Apply-Controller-Hang und faellt in Safe State (APPLIED) | SWE-002 + Watchdog in SWA-001 | -| 4 | Klemmkraft wird alle 50 ms verifiziert und bei Abfall nachgeregelt | SWE-001 + Test `test_applied_holds_force` | -| 5 | Unit-Test deckt das Verhalten ab: `test_release_requires_preconditions` | `tests/unit/test_apply_controller.c` | +| # | Statement | Evidence | +|---|-------------------------------------------------------------------------|----------------------------------------| +| 1 | Apply controller leaves APPLIED only on explicit release request with preconditions | `apply_controller.c` line 95-110 (`case EPB_STATE_APPLIED`) | +| 2 | Release preconditions check engine + brake + gear | `release_preconditions_ok()` + SWE-005 | +| 3 | Watchdog detects apply controller hang and falls into safe state (APPLIED) | SWE-002 + watchdog in SWA-001 | +| 4 | Clamping force is verified every 50 ms and re-applied on drop | SWE-001 + test `test_applied_holds_force` | +| 5 | Unit test covers the behaviour: `test_release_requires_preconditions` | `tests/unit/test_apply_controller.c` | -**Konfidenz:** ASIL-D. Architektonische Trennung + Tests + 2 Reviewer. +**Confidence:** ASIL-D. Architectural separation + tests + 2 reviewers. -### G2 — SG-02: Kein ungewolltes Apply waehrend Fahrt +### G2 — SG-02: No unintended apply during driving **Argument:** -| # | Aussage | Beleg | -|---|-----------------------------------------------------------------------|--------------------------------------| -| 1 | Apply-Anforderung wird nur bei Stillstand (v < 0.5 km/h) angenommen | `apply_controller.c` `in->standstill` check | -| 2 | Stillstand wird durch Wheel-Speed-Plausibilisierung von 4 Sensoren bestaetigt | SWE-022 + SWA-004 | -| 3 | Plausibilisierung erkennt einzelnen Sensor-Fehler (Spreizung > 3 km/h) | SWE-023 | -| 4 | Test deckt das Verhalten ab: `test_no_apply_without_standstill` | `tests/unit/test_apply_controller.c` | +| # | Statement | Evidence | +|---|-------------------------------------------------------------------------|----------------------------------------| +| 1 | Apply request is accepted only at standstill (v < 0.5 km/h) | `apply_controller.c` `in->standstill` check | +| 2 | Standstill is confirmed by wheel-speed plausibilisation of 4 sensors | SWE-022 + SWA-004 | +| 3 | Plausibilisation detects single sensor fault (spread > 3 km/h) | SWE-023 | +| 4 | Test covers the behaviour: `test_no_apply_without_standstill` | `tests/unit/test_apply_controller.c` | -**Konfidenz:** ASIL-D. Sensor-Redundanz + Test + 2 Reviewer. +**Confidence:** ASIL-D. Sensor redundancy + test + 2 reviewers. -### G3 — SG-03: Schutz vor Aktor-Ueberstrom +### G3 — SG-03: Protection against actuator overcurrent **Argument:** -| # | Aussage | Beleg | -|---|--------------------------------------------------------------------------------|------------------------------------| -| 1 | Motorstrom wird mit 1 kHz abgetastet | `actuator_isr_1khz` + SWE-013 | -| 2 | Bei > 8 A fuer > 100 ms wird der Motor abgeschaltet | `actuator_driver.c` Overcurrent-Logik + SWE-014 | -| 3 | Nach Overcurrent ist `actuator_apply` blockiert (returns EPB_EOVERCURRENT) | Test `test_overcurrent_blocks_subsequent_apply` | -| 4 | DTC wird gesetzt (Diagnostic Manager SWA-008) | SWE-014 (implicit DTC trigger) | +| # | Statement | Evidence | +|---|-------------------------------------------------------------------------|----------------------------------------| +| 1 | Motor current is sampled at 1 kHz | `actuator_isr_1khz` + SWE-013 | +| 2 | On > 8 A for > 100 ms the motor is shut down | `actuator_driver.c` overcurrent logic + SWE-014 | +| 3 | After overcurrent, `actuator_apply` is blocked (returns EPB_EOVERCURRENT) | Test `test_overcurrent_blocks_subsequent_apply` | +| 4 | DTC is set (Diagnostic Manager SWA-008) | SWE-014 (implicit DTC trigger) | -**Konfidenz:** ASIL-A (Hazard H-05). Lokale Logik + Test. +**Confidence:** ASIL-A (hazard H-05). Local logic + test. -### G4 — SG-04: Hill-Hold-Uebergabe +### G4 — SG-04: Hill-hold handover **Argument:** -| # | Aussage | Beleg | -|---|---------------------------------------------------------------------------------|------------------------------------| -| 1 | Hill-Hold wird aktiviert bei grade > 5%, v=0, Bremse | `safety_manager.c` SAFETY_HILL_HOLD_ARMED | -| 2 | Beim Loslassen der Bremse wird sofort apply_requested gesetzt | SWE-010, Tests `test_hillhold_active_on_brake_release` | -| 3 | Apply Controller reagiert auf safety_apply_request | `apply_controller.c` `apply_request_present()` | -| 4 | Inclinometer ist tiefpass-gefiltert (Robustheit gegen Sensorrauschen) | SWA-005 + SWE-024 | +| # | Statement | Evidence | +|---|-------------------------------------------------------------------------|----------------------------------------| +| 1 | Hill-hold activates at grade > 5%, v=0, brake pressed | `safety_manager.c` SAFETY_HILL_HOLD_ARMED | +| 2 | On brake release, apply_requested is set immediately | SWE-010, test `test_hillhold_active_on_brake_release` | +| 3 | Apply controller responds to safety_apply_request | `apply_controller.c` `apply_request_present()` | +| 4 | Inclinometer is low-pass filtered (robustness against sensor noise) | SWA-005 + SWE-024 | -**Konfidenz:** ASIL-C. Architektonisch + Tests + Filter. +**Confidence:** ASIL-C. Architectural + tests + filter. -### G5 — SG-05: Reaktionszeit +### G5 — SG-05: Response time **Argument:** -| # | Aussage | Beleg | -|---|---------------------------------------------------------------------------------|------------------------------------| -| 1 | Apply Controller laeuft alle 50 ms | `apply_ctrl_step_50ms` | -| 2 | Schalter wird in 50 ms entprellt (5 stable samples) | `switch_debouncer.c` | -| 3 | Gesamt-Reaktionszeit Schalter -> Aktor-Start: <= 100 ms | Timing-Analyse | -| 4 | Aktor-Apply abgeschlossen in <= 800 ms (Spec) und max. 1500 ms (Timeout) | Apply timeout, SWE-006 | +| # | Statement | Evidence | +|---|-------------------------------------------------------------------------|----------------------------------------| +| 1 | Apply controller runs every 50 ms | `apply_ctrl_step_50ms` | +| 2 | Switch is debounced in 50 ms (5 stable samples) | `switch_debouncer.c` | +| 3 | Total response switch → actuator start: ≤ 100 ms | Timing analysis | +| 4 | Actuator apply completes in ≤ 800 ms (spec) and max 1500 ms (timeout) | Apply timeout, SWE-006 | -**Konfidenz:** ASIL-B. Performance + Timeout. +**Confidence:** ASIL-B. Performance + timeout. -## 5. Common-Cause / Common-Mode +## 5. Common cause / common mode -Folgende Common-Cause-Risiken wurden geprueft: +The following common-cause risks were checked: -| Risiko | Massnahme | +| Risk | Mitigation | |---------------------------------------|-------------------------------------------------------------| -| Speicherfehler (Stack/Heap) | Statische Allokation, MISRA C 21.3 (kein Heap) | -| Compiler-Bug | GCC qualifiziert (siehe Tool-Qualification-Report), MISRA-Check | -| Konfigurations-Fehler | Build-Pipeline reproduzierbar, Version-pinning, CI-Verify | -| Shared-State-Race | Single-Threaded Step-Funktionen, ISR-Trennung via Volatile | +| Memory errors (stack/heap) | Static allocation, MISRA C 21.3 (no heap) | +| Compiler bug | GCC qualified (see tool qualification report), MISRA check | +| Configuration error | Build pipeline reproducible, version pinning, CI verify | +| Shared-state race | Single-threaded step functions, ISR separation via volatile | -## 6. Restrisiken +## 6. Residual risks -Folgende Risiken bleiben: +The following risks remain: -| Risiko | Bewertung | Begruendung | +| Risk | Assessment | Rationale | |----------------------------------------|--------------------------|------------------------------------| -| Sensor-Drift Inclinometer ueber Jahre | Akzeptiert | Periodische Kalibrierung im Service-Manual | -| EMV-Einfluss auf CAN | Auf System-Ebene gemildert | CAN ECU bietet eigene Fehlerbehandlung | -| Aktor-Lebenszeit | Aussen-Verantwortung | Tier-1 Komponente, Datenblatt | +| Inclinometer sensor drift over years | Accepted | Periodic calibration in service manual | +| EMC influence on CAN | Mitigated at system level | CAN ECU provides its own fault handling | +| Actuator lifetime | External responsibility | Tier-1 component, datasheet | -## 7. Aenderungshistorie +## 7. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|-------------------------|----------------| -| 0.1 | 2026-05-11 | Initialer Entwurf | S. Lohmaier | -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|-------------------------|-----------------| +| 0.1 | 2026-05-11 | Initial draft | S. Lohmaier | +| 1.0 | 2026-05-12 | First release | S. Lohmaier | diff --git a/docs/safety-md/Tool-Qualification-Cppcheck.md b/docs/safety-md/Tool-Qualification-Cppcheck.md index 7cb9e27..362ee6c 100644 --- a/docs/safety-md/Tool-Qualification-Cppcheck.md +++ b/docs/safety-md/Tool-Qualification-Cppcheck.md @@ -1,136 +1,127 @@ --- doc-id: SLM-EPB-TQ-Cppcheck-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- -# Tool-Qualification — Cppcheck + MISRA-Addon +# Tool Qualification — Cppcheck + MISRA addon -| Feld | Wert | -|--------------|----------------------------------------| -| Tool | Cppcheck mit MISRA-Addon | -| Version | 2.7+ (Linux apt) / 2.20.0 (Windows/macOS) | -| Hersteller | Daniel Marjamaeki et al. (Open Source)| -| Lizenz | GPLv3 | -| Verwendung | Statische Analyse, MISRA-C:2012-Check | -| Norm | ISO 26262 Part 8 §11 | +| Field | Value | +|---------------|----------------------------------------| +| Tool | Cppcheck with MISRA addon | +| Version | 2.7+ (Linux apt) / 2.20.0 (Windows/macOS) | +| Vendor | Daniel Marjamäki et al. (open source) | +| Licence | GPLv3 | +| Use | Static analysis, MISRA C:2012 check | +| Standard | ISO 26262 Part 8 §11 | --- -## 1. Zweck +## 1. Purpose -Dieser Bericht qualifiziert Cppcheck mit MISRA-Addon fuer den Einsatz in der -demo-epb Entwicklung. Tool-Qualifikation nach ISO 26262-8 §11 ist -verpflichtend, wenn: +This report qualifies Cppcheck with the MISRA addon for use in demo-epb development. Tool qualification per ISO 26262-8 §11 is mandatory when: -- Das Tool das Sicherheitsniveau der Software beeinflussen kann (TI > 1) -- Das Tool keine Off-the-Shelf-Zertifizierung besitzt +- The tool can influence the safety level of the software (TI > 1) +- The tool lacks off-the-shelf certification -## 2. Tool-Klassifikation +## 2. Tool classification -### 2.1 Use Cases +### 2.1 Use cases -| UC-ID | Use Case | Output verifiziert? | +| UC-ID | Use case | Output verified? | |-------|-----------------------------------|----------------------------| -| UC-01 | Statische Analyse waehrend Build | Per Review (CI-Log) | -| UC-02 | MISRA-C:2012-Konformitaetsbeleg | Per Deviation-Records | -| UC-03 | Identifikation von Bugs | Ergebnisse werden geprueft | +| UC-01 | Static analysis during build | Via review (CI log) | +| UC-02 | MISRA C:2012 compliance evidence | Via deviation records | +| UC-03 | Bug identification | Findings are reviewed | ### 2.2 Tool Impact (TI) -Definition nach ISO 26262-8 §11.4.5.1: +Definition per ISO 26262-8 §11.4.5.1: -| Frage | Antwort | +| Question | Answer | |------------------------------------------------------------------------|-----------| -| Kann ein Fehler des Tools zur Verletzung einer Sicherheitsanforderung fuehren? | Ja (Tool kann Bugs uebersehen) | -| Kann ein Fehler die Erkennung eines Bugs verhindern? | Ja | +| Can a tool error lead to a violation of a safety requirement? | Yes (the tool may miss bugs) | +| Can a tool error prevent detection of a bug? | Yes | -=> **TI = TI2** (Tool kann Sicherheit beeinflussen) +⇒ **TI = TI2** (the tool can influence safety) ### 2.3 Tool Error Detection (TD) -Definition nach ISO 26262-8 §11.4.5.4: +Definition per ISO 26262-8 §11.4.5.4: -| Frage | Antwort | -|------------------------------------------------------------------------|-------------| -| Wird das Tool-Output durch andere Massnahmen verifiziert? | Teilweise: Doppelgang via clang-tidy + Code-Review + Unit-Tests | -| Werden Bugs durch nachgelagerte Reviews / Tests erkannt? | Ja | +| Question | Answer | +|------------------------------------------------------------------------|--------------| +| Is the tool output verified by other measures? | Partially: redundant via clang-tidy + code review + unit tests | +| Are bugs detected by downstream reviews / tests? | Yes | -=> **TD = TD2** (Mittlere Detection-Wahrscheinlichkeit) +⇒ **TD = TD2** (medium detection probability) ### 2.4 Tool Confidence Level (TCL) -Mit TI2 + TD2 ergibt sich laut ISO 26262-8 Tabelle 4: **TCL2**. +With TI2 + TD2 we obtain per ISO 26262-8 Table 4: **TCL2**. -### 2.5 Qualification Method +### 2.5 Qualification method -Fuer TCL2 + ASIL-D ist eine **Tool-Qualifikation** notwendig (Tabelle 5). -Anwendbare Methoden: +For TCL2 + ASIL-D, a **tool qualification** is required (Table 5). Applicable methods: -- Increased confidence from use (§11.4.7) — fuer Cppcheck verfuegbar +- Increased confidence from use (§11.4.7) — available for Cppcheck - Evaluation of the tool development process (§11.4.8) - Validation of the software tool (§11.4.9) -In diesem Projekt: **Increased Confidence from Use**. +In this project: **Increased Confidence from Use**. -## 3. Increased Confidence from Use — Evidenz +## 3. Increased Confidence from Use — evidence -### 3.1 Reifegrad / Verbreitung +### 3.1 Maturity / adoption -| Kriterium | Bewertung | -|----------------------------------------|----------------------------------------| -| Tool-Alter | > 15 Jahre Entwicklung | -| Aktive Community | > 100 Contributors auf GitHub | -| Releases pro Jahr | ~6 Stable Releases | -| Bekannte Anwender im Automotive-Sektor | Documented users incl. mehrere OEMs | -| Bug-Tracker | Oeffentlich (GitHub Issues) | -| Test-Suite | Eigene Self-Test-Suite, > 5000 Tests | +| Criterion | Assessment | +|----------------------------------------|------------------------------------------| +| Tool age | > 15 years of development | +| Active community | > 100 contributors on GitHub | +| Releases per year | ~6 stable releases | +| Known automotive users | Documented users including several OEMs | +| Bug tracker | Public (GitHub Issues) | +| Test suite | Own self-test suite, > 5000 tests | -### 3.2 Frueheren Einsatz im Projekt-Kontext +### 3.2 Prior use in project context -Cppcheck wird seit 2023 in slohmaier-Projekten fuer Static-Analysis-Builds -eingesetzt (Anekdotisch: ControlNav, BrailleKit). Keine bekannten Faelle, in -denen Cppcheck eine echte Sicherheitsverletzung uebersehen hat, die durch -Code-Review nicht doch noch gefunden wurde. +Cppcheck has been used since 2023 in slohmaier projects for static-analysis builds (anecdotally: ControlNav, BrailleKit). No known cases where Cppcheck missed a real safety violation that wasn't subsequently caught by code review. -### 3.3 Validation-Tests im Projekt +### 3.3 Validation tests in project -Pro Build werden folgende Validierungs-Checks gegen Cppcheck durchgefuehrt: +Each build performs the following validation checks against Cppcheck: -| Test | Erwartetes Verhalten | Ergebnis | +| Test | Expected behaviour | Result | |--------------------------------------------|----------------------------------|-----------| -| Eingebauter Test-Case `tests/validation_cppcheck.c` mit bewusst injiziertem Bug | Cppcheck erkennt | OK | -| Cppcheck-Output ist deterministisch | Wiederholte Laeufe == identisch | OK | -| MISRA-Regeln werden gegen Referenz-Set geprueft | Erkennung min. 95% required-Regeln | OK | +| Built-in test case `tests/validation_cppcheck.c` with intentionally injected bug | Cppcheck detects it | OK | +| Cppcheck output is deterministic | Repeated runs == identical | OK | +| MISRA rules checked against reference set | Detection ≥ 95% required rules | OK | -## 4. Bekannte Einschraenkungen +## 4. Known limitations -| Einschraenkung | Mitigation | -|------------------------------------------|------------------------------------------| -| MISRA-Addon implementiert nicht alle 175 Regeln vollstaendig | Manuelle Review-Checklisten fuer fehlende Regeln | -| Geringere Erkennungsrate bei Heap-Bugs | Keine Heap-Nutzung im Projekt (MISRA 21.3) | -| False Positives bei komplexen Pointer-Aliasen | Deviation-Records pro Fall | +| Limitation | Mitigation | +|------------------------------------------|---------------------------------------------| +| MISRA addon does not implement all 175 rules completely | Manual review checklists for missing rules | +| Lower detection rate for heap bugs | No heap usage in this project (MISRA 21.3) | +| False positives on complex pointer aliasing | Per-instance deviation records | -## 5. Qualification-Verdict +## 5. Qualification verdict -Cppcheck mit MISRA-Addon ist **qualifiziert** fuer den Einsatz in demo-epb mit -TCL2 ASIL-D, basierend auf "Increased Confidence from Use". +Cppcheck with the MISRA addon is **qualified** for use in demo-epb at TCL2 ASIL-D, based on "Increased Confidence from Use". -Diese Qualifikation gilt fuer die Version 2.7+ auf Linux (CI) und Version -2.20.0 auf macOS/Windows (Entwickler-Workstations). Bei Tool-Update muss die -Validierung wiederholt werden (Regression-Suite). +This qualification applies to version 2.7+ on Linux (CI) and version 2.20.0 on macOS/Windows (developer workstations). On tool update the validation must be repeated (regression suite). -## 6. Geltungsbereich +## 6. Scope -Diese Tool-Qualifikation gilt **nur** fuer: -- Projekt: demo-epb -- ASIL: bis D -- Verwendung: statische Analyse + MISRA-Check (CI + lokal) -- Tool-Versionen: 2.7+ Linux / 2.20.0 macOS+Windows +This tool qualification applies **only** to: +- Project: demo-epb +- ASIL: up to D +- Use: static analysis + MISRA check (CI + local) +- Tool versions: 2.7+ Linux / 2.20.0 macOS+Windows -## 7. Aenderungshistorie +## 7. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|-------------------------|----------------| -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 1.0 | 2026-05-12 | First release | S. Lohmaier| diff --git a/docs/safety-md/Verification-Report.md b/docs/safety-md/Verification-Report.md index e3da92b..3be4728 100644 --- a/docs/safety-md/Verification-Report.md +++ b/docs/safety-md/Verification-Report.md @@ -1,132 +1,127 @@ --- doc-id: SLM-EPB-VER-001 version: 1.0 -status: Freigegeben -datum: 2026-05-12 +status: Released +date: 2026-05-12 --- -# Verifikations-Bericht (V-Modell rechte Seite) +# Verification Report (V-model right side) -| Feld | Wert | -|--------------|----------------------------------------| -| Projekt | demo-epb | -| Dokument-ID | SLM-EPB-VER-001 | -| Datum | 2026-05-12 | -| Version | 1.0 | -| Norm | ISO 26262 Part 6 §9 + §10 | +| Field | Value | +|---------------|----------------------------------------| +| Project | demo-epb | +| Document ID | SLM-EPB-VER-001 | +| Date | 2026-05-12 | +| Version | 1.0 | +| Standard | ISO 26262 Part 6 §9 + §10 | --- -## 1. Zweck +## 1. Purpose -Zusammenfassender Verifikations-Nachweis fuer die EPB-Software v1.0. Belegt, -dass die Implementierung die spezifizierten Anforderungen erfuellt -(V-Modell rechte Seite, Test- und Verifikationsphase). +Consolidated verification evidence for EPB software v1.0. Confirms that the implementation satisfies the specified requirements (V-model right side, test and verification phase). -## 2. Verifikations-Methoden +## 2. Verification methods -| Methode | Verwendung | -|-------------------------------|--------------------------------------------------| -| Statische Code-Analyse | Cppcheck, clang-tidy, GCC -Wall -Wextra -Werror | -| MISRA-C:2012 Compliance-Check | Cppcheck mit MISRA-Addon | -| Unit-Tests | 41 Tests, alle gruen | -| Coverage-Messung | gcov + lcov (Statement / Branch / MCDC-aequivalent) | -| Code-Reviews | Pull-Request-Reviews mit Approval-Pflicht | -| Traceability-Verifikation | `tools/traceability.py check` bidirektional | -| Architektur-Review | Technical Review mit 2 Approvern | +| Method | Use | +|---------------------------------|--------------------------------------------------| +| Static code analysis | Cppcheck, clang-tidy, GCC -Wall -Wextra -Werror | +| MISRA C:2012 compliance check | Cppcheck with MISRA addon | +| Unit tests | 46 tests, all green | +| Coverage measurement | gcov + lcov (statement / branch / MC/DC-equivalent) | +| Code reviews | Pull-request reviews with approval requirement | +| Traceability verification | `tools/traceability.py check` bidirectional | +| Architecture review | Technical review with 2 approvers | -## 3. Test-Ergebnisse +## 3. Test results -### 3.1 Unit-Tests (gesamt) +### 3.1 Unit tests (overall) -| Test-Suite | Anzahl Tests | Erfolgreich | Fehlgeschlagen | -|-------------------------------|--------------|-------------|-----------------| -| test_switch_debouncer | 5 | 5 | 0 | -| test_actuator_driver | 11 | 11 | 0 | -| test_apply_controller | 12 | 12 | 0 | -| test_safety_manager | 13 | 13 | 0 | -| **Total** | **41** | **41** | **0** | +| Test suite | Number of tests | Passed | Failed | +|-------------------------------|------------------|--------|--------| +| test_switch_debouncer | 5 | 5 | 0 | +| test_actuator_driver | 11 | 11 | 0 | +| test_apply_controller | 12 | 12 | 0 | +| test_safety_manager | 18 | 18 | 0 | +| **Total** | **46** | **46** | **0** | -### 3.2 Anforderungs-Coverage +### 3.2 Requirement coverage -Jede SWE-Anforderung wird durch mindestens einen Unit-Test referenziert -(via `@reqs` Tag im Test-File): +Every SWE requirement is referenced by at least one unit test (via `@reqs` tag in the test file): -| SWE-Req | Test-Funktion(en) | -|------------------------|------------------------------------------------------------| -| SWE-001 | `test_applied_holds_force` | -| SWE-002 | `test_watchdog_alive_counter` | -| SWE-003 | `test_apply_request_starts_applying` | -| SWE-004 | `test_applying_reaches_applied_on_target_force` | -| SWE-005 | (implizit) `test_release_requires_preconditions` | -| SWE-006 | `test_release_with_preconditions` | -| SWE-007 | `test_auto_apply_armed_on_engine_off` | -| SWE-008 | `test_auto_apply_triggers_after_2s` | -| SWE-009 | `test_hillhold_arms_on_grade_brake_standstill` | -| SWE-010 | `test_hillhold_active_on_brake_release` | -| SWE-013 | `test_isr_samples_current` | -| SWE-014 | `test_overcurrent_cutoff_after_100ms` | -| SWE-015 | `test_clamping_force_estimate` | -| SWE-025 | `test_debounce_apply_takes_5_samples` | +| SWE Req | Test function(s) | +|------------------------|--------------------------------------------------------------| +| SWE-001 | `test_applied_holds_force` | +| SWE-002 | `test_watchdog_alive_counter` | +| SWE-003 | `test_apply_request_starts_applying` | +| SWE-004 | `test_applying_reaches_applied_on_target_force` | +| SWE-005 | (implicit) `test_release_requires_preconditions` | +| SWE-006 | `test_release_with_preconditions` | +| SWE-007 | `test_auto_apply_armed_on_engine_off` | +| SWE-008 | `test_auto_apply_triggers_after_2s` | +| SWE-009 | `test_hillhold_arms_on_grade_brake_standstill` | +| SWE-010 | `test_hillhold_active_on_brake_release` | +| SWE-011 | `test_drive_away_armed_on_intent` | +| SWE-012 | `test_drive_away_blocked_without_safety` | +| SWE-013 | `test_isr_samples_current` | +| SWE-014 | `test_overcurrent_cutoff_after_100ms` | +| SWE-015 | `test_clamping_force_estimate` | +| SWE-025 | `test_debounce_apply_takes_5_samples` | -SWE-Reqs aus den nicht implementierten Komponenten (SWA-004..SWA-010, -Stubs) sind im Verifikations-Scope dieser Demo nicht abgedeckt — die -Komponenten sind als Stubs spezifiziert, aber nicht implementiert. Im -Realprojekt waeren auch diese vollstaendig geprueft. +SWE requirements of the not-implemented stub components (SWA-004..SWA-010) are out of scope for this demo verification — the components are specified but not implemented. In a real project they would all be verified. -### 3.3 Coverage-Metriken (Demo-Komponenten) +### 3.3 Coverage metrics (demo components) -| Komponente | Statement | Branch | MC/DC | Ziel ASIL | -|---------------------------|-----------|--------|-------|-----------| -| switch_debouncer (QM) | 100 % | 100 % | n/a | >= 80 % | -| actuator_driver (B) | 95 % | 92 % | n/a | >= 80 % | -| apply_controller (D) | 92 % | 91 % | 84 % | >= 90 % | -| safety_manager (D) | 96 % | 94 % | 87 % | >= 90 % | +| Component | Statement | Branch | MC/DC | ASIL target | +|----------------------------|-----------|--------|-------|--------------| +| switch_debouncer (QM) | 100% | 100% | n/a | ≥ 80% | +| actuator_driver (B) | 95% | 92% | n/a | ≥ 80% | +| apply_controller (D) | 92% | 91% | 84% | ≥ 90% | +| safety_manager (D) | 96% | 94% | 87% | ≥ 90% | -**Status:** Alle ASIL-Ziele erreicht. +**Status:** All ASIL targets met. -### 3.4 Statische Analyse +### 3.4 Static analysis -Cppcheck Run vom 2026-05-12: +Cppcheck run on 2026-05-12: -| Severity | Anzahl | -|------------|--------| -| Error | 0 | -| Warning | 0 | -| Style | 0 | -| Performance| 0 | -| Portability| 0 | +| Severity | Count | +|------------|-------| +| Error | 0 | +| Warning | 0 | +| Style | 0 | +| Performance| 0 | +| Portability| 0 | -### 3.5 MISRA-C:2012 +### 3.5 MISRA C:2012 -Siehe `MISRA-Compliance-Statement.docx`. Zusammenfassung: +See `MISRA-Compliance-Statement.docx`. Summary: -- Mandatory: 100 % Compliant -- Required: 100 % Compliant -- Advisory: 1 Deviation Record (MISRA-REC-001) +- Mandatory: 100% Compliant +- Required: 100% Compliant +- Advisory: 1 deviation record (MISRA-REC-001) -## 4. Reviews durchgefuehrt +## 4. Reviews conducted -| Review-ID | Artefakt | Reviewer | Status | +| Review ID | Artefact | Reviewer | Status | |-----------|------------------------------|----------|------------------------| -| REV-001 | `src/apply_controller.c` | S. Lohmaier (Self) | Approved with comments | -| (weitere) | (im Realprojekt voll) | mind. 2 Approver | -- | +| REV-001 | `src/apply_controller.c` | S. Lohmaier (self) | Approved with comments | +| (further) | (in real project, full) | ≥ 2 approvers | -- | -## 5. Non-Conformities +## 5. Non-conformities -| NC-ID | Beschreibung | Status | +| NC ID | Description | Status | |--------|------------------------------|---------| -| NC-001 | Step-Counter-Ueberlauf-Dok | Closed | +| NC-001 | Step counter overflow doc | Closed | -## 6. Verifications-Verdict +## 6. Verification verdict -demo-epb v1.0 erfuellt die in SWE-Plan, QA-Plan und Test-Plan spezifizierten -Verifikations-Kriterien. +demo-epb v1.0 satisfies the verification criteria specified in the SWE Plan, QA Plan, and Test Plan. -**Empfehlung:** Freigabe fuer Release v1.0. +**Recommendation:** Approve release v1.0. -## 7. Aenderungshistorie +## 7. Revision history -| Version | Datum | Aenderung | Autor | -|---------|-------------|---------------------|-------------| -| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier | +| Version | Date | Change | Author | +|---------|-------------|---------------------|------------| +| 1.0 | 2026-05-12 | First release | S. Lohmaier| diff --git a/docs/safety/FMEDA.docx b/docs/safety/FMEDA.docx index c5622bb..b28444b 100644 Binary files a/docs/safety/FMEDA.docx and b/docs/safety/FMEDA.docx differ diff --git a/docs/safety/HARA.docx b/docs/safety/HARA.docx index 5e23413..a1e9520 100644 Binary files a/docs/safety/HARA.docx and b/docs/safety/HARA.docx differ diff --git a/docs/safety/MISRA-Compliance-Statement.docx b/docs/safety/MISRA-Compliance-Statement.docx index 47a8174..86d01bd 100644 Binary files a/docs/safety/MISRA-Compliance-Statement.docx and b/docs/safety/MISRA-Compliance-Statement.docx differ diff --git a/docs/safety/Safety-Case.docx b/docs/safety/Safety-Case.docx index cf80929..daa60b1 100644 Binary files a/docs/safety/Safety-Case.docx and b/docs/safety/Safety-Case.docx differ diff --git a/docs/safety/Tool-Qualification-Cppcheck.docx b/docs/safety/Tool-Qualification-Cppcheck.docx index 7886c82..5750ecb 100644 Binary files a/docs/safety/Tool-Qualification-Cppcheck.docx and b/docs/safety/Tool-Qualification-Cppcheck.docx differ diff --git a/docs/safety/Verification-Report.docx b/docs/safety/Verification-Report.docx index 39b236f..8b6acce 100644 Binary files a/docs/safety/Verification-Report.docx and b/docs/safety/Verification-Report.docx differ diff --git a/misra/records-md/MISRA-Record-001.md b/misra/records-md/MISRA-Record-001.md index 6051f9f..881a3e7 100644 --- a/misra/records-md/MISRA-Record-001.md +++ b/misra/records-md/MISRA-Record-001.md @@ -1,52 +1,48 @@ --- record-id: MISRA-REC-001 -projekt: demo-epb -datum: 2026-05-11 +project: demo-epb +date: 2026-05-11 status: Approved --- # MISRA Deviation Record MISRA-REC-001 -| Feld | Wert | +| Field | Value | |-------------------|---------------------------------------------| -| Record-ID | MISRA-REC-001 | -| Datum | 2026-05-11 | -| Datei | `src/apply_controller.c` | -| Funktion | `apply_ctrl_step_50ms` | -| Zeile | 64 | +| Record ID | MISRA-REC-001 | +| Date | 2026-05-11 | +| File | `src/apply_controller.c` | +| Function | `apply_ctrl_step_50ms` | +| Line | 64 | | Standard | MISRA C:2012 | -| Regel | Rule 15.5 (Advisory) — "A function should have a single point of exit" | +| Rule | Rule 15.5 (Advisory) — "A function should have a single point of exit" | | ASIL | D | | Status | Approved | --- -## 1. Code-Ausschnitt +## 1. Code excerpt ```c void apply_ctrl_step_50ms(const ApplyInputs* in) { if (in == NULL) { s_ctx.last_error = EPB_EINVAL; - return; /* <-- frueher Exit */ + return; /* <-- early exit */ } ... } ``` -## 2. Begruendung +## 2. Rationale -NULL-Pointer-Check als frueher Exit-Punkt verbessert die Lesbarkeit deutlich -gegenueber einer geschachtelten Variante mit einem einzigen `return` am Ende. -MISRA Rule 15.5 ist **Advisory**, nicht **Required**. +The NULL pointer check as an early exit significantly improves readability versus a nested variant with a single `return` at the end. MISRA Rule 15.5 is **Advisory**, not **Required**. -Der frueh-Exit hat eine klar definierte Semantik (Input-Validierung) und -beeintraechtigt nicht die Verifizierbarkeit; im Gegenteil, der separate -Pfad ist im Unit-Test `test_null_input` eindeutig abgedeckt. +The early exit has clearly defined semantics (input validation) and does not impair verifiability; on the contrary, the separate path is unambiguously covered in the unit test `test_null_input`. -## 3. Alternative geprueft +## 3. Alternative considered -Variante mit einzigem Exit: +Single-exit variant: ```c void apply_ctrl_step_50ms(const ApplyInputs* in) @@ -54,28 +50,25 @@ void apply_ctrl_step_50ms(const ApplyInputs* in) if (in == NULL) { s_ctx.last_error = EPB_EINVAL; } else { - /* gesamte Step-Logik in else-Branch geschachtelt */ + /* entire step logic nested in else branch */ ... } } ``` -Verworfen, weil die zusaetzliche Schachtelung die State-Machine schwerer -lesbar macht und keine Funktionsaequivalenz mit der frueh-Exit-Variante -gewinnt. +Rejected because the additional nesting makes the state machine harder to read without gaining functional equivalence relative to the early-exit variant. -## 4. Auswirkung auf Sicherheit +## 4. Safety impact -Keine. Frueher Exit ist deterministisch und im Unit-Test abgedeckt. +None. The early exit is deterministic and covered by the unit test. -## 5. Freigabe +## 5. Approval -| Rolle | Name | Datum | Signatur | -|-----------------|------------------|-------------|----------| -| Technical Lead | Stefan Lohmaier | 2026-05-11 | (Demo) | -| Safety Manager | (im Realprojekt) | 2026-05-11 | (Demo) | +| Role | Name | Date | Signature | +|-----------------|------------------|-------------|-----------| +| Technical Lead | Stefan Lohmaier | 2026-05-11 | (demo) | +| Safety Manager | (in real project)| 2026-05-11 | (demo) | -## 6. Geltungsbereich +## 6. Scope -Nur fuer diese eine Code-Stelle. Andere Stellen mit frueh-Exit benoetigen -separate Records. +This deviation applies only to this specific code site. Other early-exit sites require separate records. diff --git a/misra/records/MISRA-REC-001.docx b/misra/records/MISRA-REC-001.docx index 989b590..3f6e22a 100644 Binary files a/misra/records/MISRA-REC-001.docx and b/misra/records/MISRA-REC-001.docx differ diff --git a/src/actuator_driver.c b/src/actuator_driver.c index 91887cf..1655739 100644 --- a/src/actuator_driver.c +++ b/src/actuator_driver.c @@ -11,7 +11,7 @@ typedef struct { ActuatorStatus status; - uint16_t over_ms; /* Millisekunden ueber Strom-Limit (zaehlt in 1 kHz ISR) */ + uint16_t over_ms; /* Milliseconds above current limit (counts in 1 kHz ISR) */ } ActuatorCtx; static ActuatorCtx s_ctx[ACTUATOR_COUNT]; @@ -100,7 +100,7 @@ void actuator_isr_1khz(ActuatorId id, uint16_t current_sample_ma) s_ctx[id].status.peak_current_ma = current_sample_ma; } - /* SWE-014: Overcurrent-Cutoff bei > 8 A fuer > 100 ms */ + /* SWE-014: Overcurrent cutoff at > 8 A for > 100 ms */ if (current_sample_ma > ACT_OVERCURRENT_LIMIT_MA) { if (s_ctx[id].over_ms < UINT16_MAX) { ++s_ctx[id].over_ms; @@ -115,7 +115,7 @@ void actuator_isr_1khz(ActuatorId id, uint16_t current_sample_ma) s_ctx[id].over_ms = 0U; } - /* SWE-015: Klemmkraft aus Peak-Strom schaetzen (nur bei Apply). */ + /* SWE-015: Estimate clamping force from peak current (only on apply). */ if (s_ctx[id].status.direction == ACT_DIR_APPLY) { const uint32_t force = ((uint32_t)s_ctx[id].status.peak_current_ma * ACT_FORCE_PER_AMP_N) / 1000U; diff --git a/src/actuator_driver.h b/src/actuator_driver.h index bb7cae9..42a4c05 100644 --- a/src/actuator_driver.h +++ b/src/actuator_driver.h @@ -1,6 +1,6 @@ /** * @file actuator_driver.h - * @brief Low-Level-Ansteuerung der EPB-Aktoren. + * @brief Low-level control of the EPB actuators. * * @arch SWA-003 * @reqs SWE-006 SWE-013 SWE-014 SWE-015 @@ -21,14 +21,14 @@ typedef enum { typedef struct { ActuatorDirection direction; uint8_t pwm_percent; /* 0..100 */ - uint16_t current_ma; /* aktueller Motorstrom */ + uint16_t current_ma; /* current motor current */ uint16_t peak_current_ma; - uint16_t clamping_force_n; /* geschaetzt aus Strom */ + uint16_t clamping_force_n; /* estimated from current */ bool overcurrent; EpbStatus last_error; } ActuatorStatus; -/** Strom-Limit (Spec) und Zeitfenster fuer Cutoff (Spec). */ +/** Current limit (spec) and time window for cutoff (spec). */ #define ACT_OVERCURRENT_LIMIT_MA 8000U #define ACT_OVERCURRENT_WINDOW_MS 100U #define ACT_FORCE_PER_AMP_N 2500U /* lineare Naeherung */ @@ -40,9 +40,9 @@ EpbStatus actuator_stop(ActuatorId id); ActuatorStatus actuator_get_status(ActuatorId id); /** - * @brief ISR-Hook fuer Strom-Sampling. Wird mit 1 kHz aufgerufen. + * @brief ISR hook for current sampling. Called at 1 kHz. * - * Fuer Tests durch Test-Doubles ersetzt. + * Replaced by test doubles for testing. */ void actuator_isr_1khz(ActuatorId id, uint16_t current_sample_ma); diff --git a/src/apply_controller.c b/src/apply_controller.c index 147099d..91ad28c 100644 --- a/src/apply_controller.c +++ b/src/apply_controller.c @@ -5,8 +5,8 @@ * @arch SWA-002 * @reqs SWE-001 SWE-002 SWE-003 SWE-004 * - * ASIL: D. Diese Komponente ist die sicherheitskritische Kernlogik. - * Aenderungen erfordern Technical Review mit 2 Approvals. + * ASIL: D. This is the safety-critical core logic. + * Changes require a technical review with 2 approvals. */ #include @@ -15,9 +15,9 @@ typedef struct { EpbState state; - uint8_t step_in_state; /* 50ms-Ticks im aktuellen State */ + uint8_t step_in_state; /* 50ms ticks in the current state */ EpbStatus last_error; - uint32_t step_count; /* Watchdog-Alive-Counter */ + uint32_t step_count; /* Watchdog alive counter */ } ApplyCtx; static ApplyCtx s_ctx; @@ -30,7 +30,7 @@ static void enter_state(EpbState new_state) static bool release_preconditions_ok(const ApplyInputs* in) { - /* @reqs SWE-005 (Release-Voraussetzungen) — hier konsumiert */ + /* @reqs SWE-005 (Release preconditions) — consumed here */ return in->engine_running && in->brake_pedal_pressed && in->gear_engaged; @@ -68,7 +68,7 @@ void apply_ctrl_step_50ms(const ApplyInputs* in) return; } - /* SWE-002: Watchdog-Alive-Counter erhoehen */ + /* SWE-002: Watchdog alive counter erhoehen */ ++s_ctx.step_count; if (s_ctx.step_in_state < UINT8_MAX) { @@ -85,7 +85,7 @@ void apply_ctrl_step_50ms(const ApplyInputs* in) break; case EPB_STATE_APPLYING: - /* SWE-004: Klemmkraft-Erreichen pruefen */ + /* SWE-004: Check target clamping force reached */ if (min_force(in) >= APPLY_TARGET_FORCE_N) { (void)actuator_stop(ACTUATOR_LEFT); (void)actuator_stop(ACTUATOR_RIGHT); @@ -99,7 +99,7 @@ void apply_ctrl_step_50ms(const ApplyInputs* in) break; case EPB_STATE_APPLIED: - /* SWE-001: Klemmkraft halten — bei Unterschreitung nachregeln */ + /* SWE-001: Hold clamping force — re-apply on drop */ if (min_force(in) < (APPLY_TARGET_FORCE_N - HOLD_TOLERANCE_N)) { (void)actuator_apply(ACTUATOR_LEFT, 60U); (void)actuator_apply(ACTUATOR_RIGHT, 60U); @@ -128,7 +128,7 @@ void apply_ctrl_step_50ms(const ApplyInputs* in) case EPB_STATE_ERROR: default: - /* Auf Reset warten; sicherer Zustand ist Apply, also kein Release */ + /* Wait for reset; safe state is Apply, hence no release */ if (!apply_request_present(in) && !release_request_present(in)) { s_ctx.last_error = EPB_OK; enter_state(EPB_STATE_RELEASED); diff --git a/src/apply_controller.h b/src/apply_controller.h index 3a708a2..0d7f070 100644 --- a/src/apply_controller.h +++ b/src/apply_controller.h @@ -1,6 +1,6 @@ /** * @file apply_controller.h - * @brief Apply/Hold/Release-Steuerung der EPB. + * @brief Apply/Hold/Release control of the EPB. * * @arch SWA-002 * @reqs SWE-001 SWE-002 SWE-003 SWE-004 @@ -23,14 +23,14 @@ typedef struct { uint16_t right_force_n; } ApplyInputs; -#define APPLY_TARGET_FORCE_N 12000U /* Ziel-Klemmkraft je Aktor */ +#define APPLY_TARGET_FORCE_N 12000U /* Target clamping force per actuator */ #define APPLY_TIMEOUT_50MS 30U /* 30 * 50ms = 1500 ms */ -#define HOLD_TOLERANCE_N 1200U /* 10% von Ziel */ +#define HOLD_TOLERANCE_N 1200U /* 10% of target */ EpbStatus apply_ctrl_init(void); /** - * @brief Step-Funktion 50 ms. + * @brief 50 ms step function. * * @reqs SWE-001 SWE-002 SWE-003 SWE-004 */ @@ -38,6 +38,6 @@ void apply_ctrl_step_50ms(const ApplyInputs* in); EpbState apply_ctrl_get_state(void); EpbStatus apply_ctrl_last_error(void); -uint32_t apply_ctrl_get_step_count(void); /* Watchdog-Alive-Counter */ +uint32_t apply_ctrl_get_step_count(void); /* Watchdog alive counter */ #endif /* APPLY_CONTROLLER_H */ diff --git a/src/epb_types.h b/src/epb_types.h index 27a3a4a..93141bf 100644 --- a/src/epb_types.h +++ b/src/epb_types.h @@ -1,6 +1,6 @@ /** * @file epb_types.h - * @brief Gemeinsame Typen fuer die EPB-Software. + * @brief Common types for the EPB software. * * @arch SA-001 */ diff --git a/src/safety_manager.c b/src/safety_manager.c index 0598ecb..70fb6e7 100644 --- a/src/safety_manager.c +++ b/src/safety_manager.c @@ -1,14 +1,14 @@ /** * @file safety_manager.c - * @brief Safety Manager — Hill-Hold, Auto-Apply, Drive-Away-Assist. + * @brief Safety Manager — Hill-Hold, Auto-Apply, Drive-Away Assist. * * @arch SWA-001 * @reqs SWE-007 SWE-008 SWE-009 SWE-010 SWE-011 SWE-012 * - * ASIL: D. Diese Komponente entscheidet, wann der Apply Controller eine - * Apply- oder Release-Anforderung erhaelt (Hill-Hold-Uebergabe, Auto-Apply - * bei Motor-Aus, Drive-Away-Assist). - * Aenderungen erfordern Technical Review mit 2 Approvals. + * ASIL: D. This component decides, when the Apply Controller receives an + * apply or release request (hill-hold handover, auto-apply on + * engine-off, drive-away assist). + * Changes require a technical review with 2 approvals. */ #include @@ -16,7 +16,7 @@ typedef struct { SafetyState state; - uint16_t ticks_in_state; /* 50ms-Ticks im aktuellen Zustand */ + uint16_t ticks_in_state; /* 50ms ticks in the current state */ bool apply_requested; bool release_requested; } SafetyCtx; @@ -36,7 +36,7 @@ static bool standstill(const SafetyInputs* in) static bool grade_steep(const SafetyInputs* in) { - /* @reqs SWE-009: Hill-Hold ab |grade| > 5% */ + /* @reqs SWE-009: Hill-hold above |grade| > 5% */ float g = in->grade_percent; if (g < 0.0f) { g = -g; @@ -45,7 +45,7 @@ static bool grade_steep(const SafetyInputs* in) } /** - * @reqs SWE-011 (Anfahrabsicht erkennen) + * @reqs SWE-011 (Detect drive-away intent) */ static bool drive_intent(const SafetyInputs* in) { @@ -55,7 +55,7 @@ static bool drive_intent(const SafetyInputs* in) } /** - * @reqs SWE-012 (Sicherheits-Check vor Auto-Release) + * @reqs SWE-012 (Safety check before auto-release) */ static bool drive_away_safety_ok(const SafetyInputs* in) { @@ -87,19 +87,19 @@ void safety_mgr_step_50ms(const SafetyInputs* in) switch (s_ctx.state) { case SAFETY_IDLE: - /* @reqs SWE-009: Hill-Hold-Aktivierung */ + /* @reqs SWE-009: Hill-hold activation */ if (grade_steep(in) && standstill(in) && in->brake_pedal_pressed) { enter(SAFETY_HILL_HOLD_ARMED); break; } - /* @reqs SWE-007: Motor-Aus-Bedingung erkennen */ + /* @reqs SWE-007: Detect engine-off condition */ if (!in->engine_running && standstill(in) && in->current_state != EPB_STATE_APPLIED && in->current_state != EPB_STATE_APPLYING) { enter(SAFETY_AUTO_APPLY_ARMED); break; } - /* @reqs SWE-011 + SWE-012: Drive-Away-Assist */ + /* @reqs SWE-011 + SWE-012: Drive-Away Assist */ if (in->current_state == EPB_STATE_APPLIED && drive_intent(in) && drive_away_safety_ok(in)) { s_ctx.release_requested = true; @@ -108,20 +108,20 @@ void safety_mgr_step_50ms(const SafetyInputs* in) break; case SAFETY_HILL_HOLD_ARMED: - /* @reqs SWE-010: Beim Loslassen des Bremspedals Apply triggern */ + /* @reqs SWE-010: Trigger apply on brake release */ if (!in->brake_pedal_pressed) { s_ctx.apply_requested = true; enter(SAFETY_HILL_HOLD_ACTIVE); break; } - /* Bedingung fuer Hill-Hold nicht mehr erfuellt? */ + /* Hill-hold condition no longer met? */ if (!grade_steep(in) || !standstill(in)) { enter(SAFETY_IDLE); } break; case SAFETY_HILL_HOLD_ACTIVE: - /* Beendet, wenn Fahrzeug rollt oder Bremse appliziert */ + /* Ends when vehicle rolls or brake is applied */ if (in->vehicle_speed_kmh > SAFETY_RELEASE_KMH || in->current_state == EPB_STATE_APPLIED) { enter(SAFETY_IDLE); @@ -131,12 +131,12 @@ void safety_mgr_step_50ms(const SafetyInputs* in) break; case SAFETY_AUTO_APPLY_ARMED: - /* Bedingung muss durchgaengig erfuellt sein */ + /* Condition must remain continuously satisfied */ if (in->engine_running || !standstill(in)) { enter(SAFETY_IDLE); break; } - /* @reqs SWE-008: Auto-Apply nach 2 s (40 Ticks) Verzoegerung */ + /* @reqs SWE-008: Auto-apply after 2 s (40 ticks) delay */ if (s_ctx.ticks_in_state >= SAFETY_AUTO_APPLY_DELAY_50MS) { s_ctx.apply_requested = true; enter(SAFETY_AUTO_APPLY_TRIGGERED); @@ -152,7 +152,7 @@ void safety_mgr_step_50ms(const SafetyInputs* in) break; case SAFETY_DRIVE_AWAY: - /* Beendet, wenn die Bremse geloest wurde oder Vorbedingungen nicht mehr ok. */ + /* Ends when the brake has been released or preconditions are no longer ok. */ if (in->current_state == EPB_STATE_RELEASED || in->current_state == EPB_STATE_RELEASING) { enter(SAFETY_IDLE); diff --git a/src/safety_manager.h b/src/safety_manager.h index f6ea35f..a8b912d 100644 --- a/src/safety_manager.h +++ b/src/safety_manager.h @@ -1,6 +1,6 @@ /** * @file safety_manager.h - * @brief Safety Manager — Hill-Hold, Auto-Apply, Drive-Away-Assist. + * @brief Safety Manager — hill-hold, auto-apply, drive-away assist. * * @arch SWA-001 * @reqs SWE-007 SWE-008 SWE-009 SWE-010 SWE-011 SWE-012 @@ -38,25 +38,25 @@ typedef struct { bool brake_pedal_pressed; float vehicle_speed_kmh; float grade_percent; - EpbState current_state; /* aus Apply Controller */ - /* Drive-Away-Assist Inputs (SWE-011, SWE-012) */ + EpbState current_state; /* from Apply Controller */ + /* Drive-Away Assist Inputs (SWE-011, SWE-012) */ float gas_pedal_percent; /* 0..100 */ - bool gear_in_drive; /* Vorwaerts oder Rueckwaerts */ - bool door_closed; /* Fahrertuer */ - bool seatbelt_fastened; /* Fahrer-Gurt */ + bool gear_in_drive; /* forward or reverse */ + bool door_closed; /* driver door */ + bool seatbelt_fastened; /* driver seatbelt */ } SafetyInputs; -/* Schwellwerte als Konstanten, damit Tests darauf zugreifen koennen. */ +/* Thresholds as constants, so tests can access them. */ #define SAFETY_AUTO_APPLY_DELAY_50MS 40U /* 40 * 50ms = 2.0 s */ #define SAFETY_STANDSTILL_KMH 0.5f #define SAFETY_RELEASE_KMH 2.0f #define SAFETY_HILLHOLD_GRADE_PCT 5.0f -#define SAFETY_DRIVE_INTENT_GAS_PCT 10.0f /* Gaspedal > 10% = Anfahrabsicht */ +#define SAFETY_DRIVE_INTENT_GAS_PCT 10.0f /* Throttle > 10% = drive-away intent */ EpbStatus safety_mgr_init(void); void safety_mgr_step_50ms(const SafetyInputs* in); bool safety_mgr_apply_requested(void); -bool safety_mgr_release_requested(void); /* Drive-Away-Assist */ +bool safety_mgr_release_requested(void); /* Drive-Away Assist */ SafetyState safety_mgr_get_state(void); #endif /* SAFETY_MANAGER_H */ diff --git a/src/switch_debouncer.h b/src/switch_debouncer.h index 7c84afb..47c6ebd 100644 --- a/src/switch_debouncer.h +++ b/src/switch_debouncer.h @@ -1,6 +1,6 @@ /** * @file switch_debouncer.h - * @brief EPB-Schalter mit Software-Entprellung. + * @brief EPB switch with software debounce. * * @arch SWA-006 * @reqs SWE-025 @@ -12,7 +12,7 @@ #include "epb_types.h" -/** Step-Zyklus 10 ms. Debounce-Schwelle 50 ms (5 stabile Samples). */ +/** Step cycle 10 ms. Debounce threshold 50 ms (5 stable samples). */ #define SWITCH_DEBOUNCE_SAMPLES 5 EpbStatus switch_init(void); diff --git a/tests/unit/test_actuator_driver.c b/tests/unit/test_actuator_driver.c index 250f18f..e627b50 100644 --- a/tests/unit/test_actuator_driver.c +++ b/tests/unit/test_actuator_driver.c @@ -1,6 +1,6 @@ /** * @file test_actuator_driver.c - * @brief Unit-Tests fuer den Actuator-Driver. + * @brief Unit tests for the Actuator Driver. * * @reqs SWE-006 SWE-013 SWE-014 SWE-015 * @arch SWA-003 @@ -12,7 +12,7 @@ TestStats g_test_stats = {0, 0}; static void test_init(void) { - TEST_BEGIN("init -> beide Aktoren STOP, 0 mA"); + TEST_BEGIN("init -> both actuators STOP, 0 mA"); ASSERT_EQ(actuator_init(), EPB_OK); ActuatorStatus l = actuator_get_status(ACTUATOR_LEFT); ActuatorStatus r = actuator_get_status(ACTUATOR_RIGHT); @@ -61,7 +61,7 @@ static void test_release_normal(void) static void test_isr_samples_current(void) { - TEST_BEGIN("ISR-Sample setzt current_ma und peak"); + TEST_BEGIN("ISR sample sets current_ma and peak"); (void)actuator_init(); (void)actuator_apply(ACTUATOR_LEFT, 80); actuator_isr_1khz(ACTUATOR_LEFT, 3000); @@ -73,10 +73,10 @@ static void test_isr_samples_current(void) static void test_overcurrent_cutoff_after_100ms(void) { - TEST_BEGIN("Overcurrent > 8 A fuer 100 ms -> STOP + overcurrent flag"); + TEST_BEGIN("Overcurrent > 8 A for 100 ms -> STOP + overcurrent flag"); (void)actuator_init(); (void)actuator_apply(ACTUATOR_LEFT, 80); - /* 100 Samples (= 100 ms bei 1 kHz) ueber 8 A */ + /* 100 samples (= 100 ms at 1 kHz) above 8 A */ for (int i = 0; i < 100; ++i) { actuator_isr_1khz(ACTUATOR_LEFT, 8500); } @@ -89,7 +89,7 @@ static void test_overcurrent_cutoff_after_100ms(void) static void test_overcurrent_below_window_no_cutoff(void) { - TEST_BEGIN("Overcurrent < 100 ms loest noch nicht aus"); + TEST_BEGIN("Overcurrent < 100 ms does not trip yet"); (void)actuator_init(); (void)actuator_apply(ACTUATOR_LEFT, 80); for (int i = 0; i < 50; ++i) { @@ -103,7 +103,7 @@ static void test_overcurrent_below_window_no_cutoff(void) static void test_overcurrent_blocks_subsequent_apply(void) { - TEST_BEGIN("nach Overcurrent: weiterer apply -> EOVERCURRENT"); + TEST_BEGIN("after overcurrent: subsequent apply -> EOVERCURRENT"); (void)actuator_init(); (void)actuator_apply(ACTUATOR_LEFT, 80); for (int i = 0; i < 120; ++i) { @@ -116,11 +116,11 @@ static void test_overcurrent_blocks_subsequent_apply(void) static void test_clamping_force_estimate(void) { - TEST_BEGIN("Klemmkraft-Schaetzung aus Peak-Strom (SWE-015)"); + TEST_BEGIN("Clamping force estimation from peak current (SWE-015)"); (void)actuator_init(); (void)actuator_apply(ACTUATOR_LEFT, 80); - actuator_isr_1khz(ACTUATOR_LEFT, 4000); /* 4 A Peak */ - actuator_isr_1khz(ACTUATOR_LEFT, 3500); /* danach niedriger */ + actuator_isr_1khz(ACTUATOR_LEFT, 4000); /* 4 A peak */ + actuator_isr_1khz(ACTUATOR_LEFT, 3500); /* then lower */ ActuatorStatus s = actuator_get_status(ACTUATOR_LEFT); /* F = (4000 * 2500) / 1000 = 10000 N */ ASSERT_EQ(s.clamping_force_n, 10000); diff --git a/tests/unit/test_apply_controller.c b/tests/unit/test_apply_controller.c index 1be47eb..93c9313 100644 --- a/tests/unit/test_apply_controller.c +++ b/tests/unit/test_apply_controller.c @@ -1,6 +1,6 @@ /** * @file test_apply_controller.c - * @brief Unit-Tests fuer den Apply-Controller (ASIL-D Kern). + * @brief Unit tests for the Apply Controller (ASIL-D core). * * @reqs SWE-001 SWE-002 SWE-003 SWE-004 SWE-005 * @arch SWA-002 @@ -56,7 +56,7 @@ static void test_null_input(void) static void test_apply_request_starts_applying(void) { - TEST_BEGIN("Apply-Request bei Stillstand -> APPLYING"); + TEST_BEGIN("Apply request at standstill -> APPLYING"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); @@ -68,7 +68,7 @@ static void test_apply_request_starts_applying(void) static void test_no_apply_without_standstill(void) { - TEST_BEGIN("Apply-Request ohne Stillstand wird ignoriert"); + TEST_BEGIN("Apply request without standstill is ignored"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); @@ -81,7 +81,7 @@ static void test_no_apply_without_standstill(void) static void test_applying_reaches_applied_on_target_force(void) { - TEST_BEGIN("APPLYING -> APPLIED wenn beide Klemmkraefte >= Target"); + TEST_BEGIN("APPLYING -> APPLIED when both clamping forces >= target"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); @@ -97,14 +97,14 @@ static void test_applying_reaches_applied_on_target_force(void) static void test_applying_timeout_to_error(void) { - TEST_BEGIN("APPLYING-Timeout (>30 Steps) -> ERROR"); + TEST_BEGIN("APPLYING timeout (>30 steps) -> ERROR"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); in.sw_state = SWITCH_APPLY; apply_ctrl_step_50ms(&in); /* -> APPLYING */ in.sw_state = SWITCH_NEUTRAL; - /* Klemmkraefte bleiben bei 0 -> Timeout nach 30 Steps */ + /* Clamping forces stay at 0 -> timeout after 30 steps */ apply_full_cycle_until_state(&in, EPB_STATE_ERROR, 35); ASSERT_EQ(apply_ctrl_get_state(), EPB_STATE_ERROR); ASSERT_EQ(apply_ctrl_last_error(), EPB_ETIMEOUT); @@ -113,7 +113,7 @@ static void test_applying_timeout_to_error(void) static void test_applied_holds_force(void) { - TEST_BEGIN("APPLIED haelt Klemmkraft (SWE-001)"); + TEST_BEGIN("APPLIED maintains clamping force (SWE-001)"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); @@ -124,18 +124,18 @@ static void test_applied_holds_force(void) in.right_force_n = 12000; apply_ctrl_step_50ms(&in); /* -> APPLIED */ - /* Klemmkraft sinkt auf 10000 (unter Toleranz-Schwelle 10800) */ + /* Clamping force drops to 10000 (below tolerance threshold 10800) */ in.left_force_n = 10000; in.right_force_n = 10000; apply_ctrl_step_50ms(&in); - /* Apply-Controller muss nachregeln -> APPLYING */ + /* Apply controller must re-apply -> APPLYING */ ASSERT_EQ(apply_ctrl_get_state(), EPB_STATE_APPLYING); TEST_END(); } static void test_release_requires_preconditions(void) { - TEST_BEGIN("Release ohne Engine wird abgelehnt"); + TEST_BEGIN("Release without engine is rejected"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); @@ -155,7 +155,7 @@ static void test_release_requires_preconditions(void) static void test_release_with_preconditions(void) { - TEST_BEGIN("Release mit allen Voraussetzungen -> RELEASING -> RELEASED"); + TEST_BEGIN("Release with all preconditions -> RELEASING -> RELEASED"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); @@ -180,7 +180,7 @@ static void test_release_with_preconditions(void) static void test_safety_apply_request(void) { - TEST_BEGIN("Safety-Manager Apply-Request (Hill-Hold/Auto-Apply)"); + TEST_BEGIN("Safety Manager apply request (Hill-Hold/Auto-Apply)"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); @@ -193,7 +193,7 @@ static void test_safety_apply_request(void) static void test_watchdog_alive_counter(void) { - TEST_BEGIN("Step-Counter steigt monoton (SWE-002 Watchdog-Alive)"); + TEST_BEGIN("Step counter increases monotonically (SWE-002 watchdog alive)"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); @@ -207,7 +207,7 @@ static void test_watchdog_alive_counter(void) static void test_error_state_recoverable(void) { - TEST_BEGIN("ERROR -> RELEASED bei neutralem Switch"); + TEST_BEGIN("ERROR -> RELEASED on neutral switch"); (void)actuator_init(); (void)apply_ctrl_init(); ApplyInputs in = make_idle_inputs(); diff --git a/tests/unit/test_safety_manager.c b/tests/unit/test_safety_manager.c index a301403..9b6d6e5 100644 --- a/tests/unit/test_safety_manager.c +++ b/tests/unit/test_safety_manager.c @@ -1,6 +1,6 @@ /** * @file test_safety_manager.c - * @brief Unit-Tests fuer den Safety Manager (ASIL-D). + * @brief Unit tests for the Safety Manager (ASIL-D). * * @reqs SWE-007 SWE-008 SWE-009 SWE-010 SWE-011 SWE-012 * @arch SWA-001 @@ -38,7 +38,7 @@ static void step_n(SafetyInputs* in, int n) static void test_init(void) { - TEST_BEGIN("init -> IDLE, kein Apply-Request"); + TEST_BEGIN("init -> IDLE, no apply request"); ASSERT_EQ(safety_mgr_init(), EPB_OK); ASSERT_EQ(safety_mgr_get_state(), SAFETY_IDLE); ASSERT_TRUE(!safety_mgr_apply_requested()); @@ -47,7 +47,7 @@ static void test_init(void) static void test_null_input(void) { - TEST_BEGIN("NULL Input ist no-op"); + TEST_BEGIN("NULL input is a no-op"); (void)safety_mgr_init(); safety_mgr_step_50ms(NULL); ASSERT_EQ(safety_mgr_get_state(), SAFETY_IDLE); @@ -58,7 +58,7 @@ static void test_null_input(void) static void test_auto_apply_armed_on_engine_off(void) { - TEST_BEGIN("SWE-007: Motor aus + Stillstand -> AUTO_APPLY_ARMED"); + TEST_BEGIN("SWE-007: engine off + standstill -> AUTO_APPLY_ARMED"); (void)safety_mgr_init(); SafetyInputs in = make_driving(); in.engine_running = false; @@ -71,7 +71,7 @@ static void test_auto_apply_armed_on_engine_off(void) static void test_auto_apply_triggers_after_2s(void) { - TEST_BEGIN("SWE-008: nach ca. 2s -> TRIGGERED + Apply-Request"); + TEST_BEGIN("SWE-008: after ~2s -> TRIGGERED + apply request"); (void)safety_mgr_init(); SafetyInputs in = make_driving(); in.engine_running = false; @@ -92,7 +92,7 @@ static void test_auto_apply_triggers_after_2s(void) static void test_auto_apply_aborts_on_engine_on(void) { - TEST_BEGIN("Auto-Apply bricht ab wenn Motor wieder an"); + TEST_BEGIN("Auto-Apply aborts when engine comes back on"); (void)safety_mgr_init(); SafetyInputs in = make_driving(); in.engine_running = false; @@ -107,7 +107,7 @@ static void test_auto_apply_aborts_on_engine_on(void) static void test_auto_apply_returns_idle_when_applied(void) { - TEST_BEGIN("AUTO_APPLY_TRIGGERED -> IDLE wenn Apply Controller fertig"); + TEST_BEGIN("AUTO_APPLY_TRIGGERED -> IDLE when Apply Controller is done"); (void)safety_mgr_init(); SafetyInputs in = make_driving(); in.engine_running = false; @@ -129,7 +129,7 @@ static void test_auto_apply_returns_idle_when_applied(void) static void test_hillhold_arms_on_grade_brake_standstill(void) { - TEST_BEGIN("SWE-009: Grad >5% + Stillstand + Bremse -> HILL_HOLD_ARMED"); + TEST_BEGIN("SWE-009: grade >5% + standstill + brake -> HILL_HOLD_ARMED"); (void)safety_mgr_init(); SafetyInputs in = make_standstill(); in.grade_percent = 8.0f; @@ -141,7 +141,7 @@ static void test_hillhold_arms_on_grade_brake_standstill(void) static void test_hillhold_negative_grade_also_triggers(void) { - TEST_BEGIN("Hill-Hold auch bei negativem Grad (abschuessig)"); + TEST_BEGIN("Hill-hold also on negative grade (downhill)"); (void)safety_mgr_init(); SafetyInputs in = make_standstill(); in.grade_percent = -7.0f; @@ -152,7 +152,7 @@ static void test_hillhold_negative_grade_also_triggers(void) static void test_hillhold_below_threshold_no_arm(void) { - TEST_BEGIN("Grad < 5% -> kein Hill-Hold"); + TEST_BEGIN("Grade < 5% -> no hill-hold"); (void)safety_mgr_init(); SafetyInputs in = make_standstill(); in.grade_percent = 4.0f; @@ -163,7 +163,7 @@ static void test_hillhold_below_threshold_no_arm(void) static void test_hillhold_active_on_brake_release(void) { - TEST_BEGIN("SWE-010: Bremse losgelassen -> HILL_HOLD_ACTIVE + Apply-Request"); + TEST_BEGIN("SWE-010: brake released -> HILL_HOLD_ACTIVE + apply request"); (void)safety_mgr_init(); SafetyInputs in = make_standstill(); in.grade_percent = 8.0f; @@ -177,7 +177,7 @@ static void test_hillhold_active_on_brake_release(void) static void test_hillhold_active_ends_on_vehicle_rolling(void) { - TEST_BEGIN("HILL_HOLD_ACTIVE endet wenn Fahrzeug rollt (v > 2 km/h)"); + TEST_BEGIN("HILL_HOLD_ACTIVE ends when vehicle rolls (v > 2 km/h)"); (void)safety_mgr_init(); SafetyInputs in = make_standstill(); in.grade_percent = 8.0f; @@ -193,7 +193,7 @@ static void test_hillhold_active_ends_on_vehicle_rolling(void) static void test_hillhold_armed_to_idle_if_grade_drops(void) { - TEST_BEGIN("HILL_HOLD_ARMED -> IDLE wenn Grad < 5% wird"); + TEST_BEGIN("HILL_HOLD_ARMED -> IDLE when grade < 5%"); (void)safety_mgr_init(); SafetyInputs in = make_standstill(); in.grade_percent = 8.0f; @@ -226,7 +226,7 @@ static SafetyInputs make_applied_at_rest(void) static void test_drive_away_armed_on_intent(void) { - TEST_BEGIN("SWE-011 + SWE-012: Anfahrabsicht + Safety -> DRIVE_AWAY + Release-Request"); + TEST_BEGIN("SWE-011 + SWE-012: intent + safety -> DRIVE_AWAY + release request"); (void)safety_mgr_init(); SafetyInputs in = make_applied_at_rest(); in.gas_pedal_percent = 25.0f; @@ -239,12 +239,12 @@ static void test_drive_away_armed_on_intent(void) static void test_drive_away_blocked_without_safety(void) { - TEST_BEGIN("SWE-012: Tuer offen blockiert Drive-Away"); + TEST_BEGIN("SWE-012: door open blocks drive-away"); (void)safety_mgr_init(); SafetyInputs in = make_applied_at_rest(); in.gas_pedal_percent = 25.0f; in.gear_in_drive = true; - in.door_closed = false; /* Tuer offen */ + in.door_closed = false; /* door open */ safety_mgr_step_50ms(&in); ASSERT_EQ(safety_mgr_get_state(), SAFETY_IDLE); ASSERT_TRUE(!safety_mgr_release_requested()); @@ -253,7 +253,7 @@ static void test_drive_away_blocked_without_safety(void) static void test_drive_away_blocked_without_seatbelt(void) { - TEST_BEGIN("SWE-012: Gurt nicht angelegt blockiert Drive-Away"); + TEST_BEGIN("SWE-012: seatbelt not fastened blocks drive-away"); (void)safety_mgr_init(); SafetyInputs in = make_applied_at_rest(); in.gas_pedal_percent = 25.0f; @@ -266,7 +266,7 @@ static void test_drive_away_blocked_without_seatbelt(void) static void test_drive_away_blocked_below_gas_threshold(void) { - TEST_BEGIN("SWE-011: Gas < 10% loest kein Drive-Away aus"); + TEST_BEGIN("SWE-011: throttle < 10% does not trigger drive-away"); (void)safety_mgr_init(); SafetyInputs in = make_applied_at_rest(); in.gas_pedal_percent = 5.0f; @@ -278,7 +278,7 @@ static void test_drive_away_blocked_below_gas_threshold(void) static void test_drive_away_ends_when_released(void) { - TEST_BEGIN("DRIVE_AWAY -> IDLE wenn Apply Controller geloest hat"); + TEST_BEGIN("DRIVE_AWAY -> IDLE when Apply Controller has released"); (void)safety_mgr_init(); SafetyInputs in = make_applied_at_rest(); in.gas_pedal_percent = 25.0f; @@ -293,7 +293,7 @@ static void test_drive_away_ends_when_released(void) static void test_already_applied_does_not_arm_auto_apply(void) { - TEST_BEGIN("Bereits Applied: kein Auto-Apply Arming"); + TEST_BEGIN("Already applied: no auto-apply arming"); (void)safety_mgr_init(); SafetyInputs in = make_driving(); in.engine_running = false; diff --git a/tests/unit/test_switch_debouncer.c b/tests/unit/test_switch_debouncer.c index 7c31e2c..55b2a99 100644 --- a/tests/unit/test_switch_debouncer.c +++ b/tests/unit/test_switch_debouncer.c @@ -1,6 +1,6 @@ /** * @file test_switch_debouncer.c - * @brief Unit-Tests fuer den Switch-Debouncer. + * @brief Unit tests for the Switch Debouncer. * * @reqs SWE-025 * @arch SWA-006