slohmaier/demo-epb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

docs: README mit kompletter Tour durch Safety + Manuals + Reports
Validate / build-test (macos-latest) (push) Failing after 3s
Details
Validate / build-test (windows-latest) (push) Failing after 17s
Details
Validate / build-test (ubuntu-latest) (push) Failing after 15s
Details
Validate / reports (push) Has been skipped
Details

Browse Source
This commit is contained in:
Stefan Lohmaier
2026-05-12 00:56:24 -07:00
parent c54a9c55d2
commit 17910835ad
1 changed files with 114 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+112 -83
View File
@@ -1,23 +1,27 @@
# demo-epb — Elektrische Parkbremse # demo-epb — Elektrische Parkbremse
Vollstaendige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) anhand einer EPB-Steuergeraet-Software. Zeigt ASPICE 4.0 / ISO 26262-konforme Entwicklung in einem Monorepo: Anforderungen, Architektur, Code, Tests, Reviews, MISRA — alles auf einen Pull-Request-Klick verifizierbar. 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.
> Diese Software ist **bewusst kein Produktivcode** — sie ist die Demonstration des Engineering-Verfahrens. Code-Umfang absichtlich klein, Prozess-Tiefe vollstaendig. > Diese Software ist **bewusst kein Produktivcode** — sie ist die Demonstration des Engineering-Verfahrens. Code-Umfang bewusst klein, Prozess-Tiefe vollständig.
## Was die Demo zeigt ## Was die Demo zeigt
| Artefakt-Typ | Anzahl | Pfad | | Kategorie | Inhalt |
|---------------------|--------|---------------------| |-----------|--------|
| Plaene (Word) | 5 | `docs/*.docx` | | **Pläne** (Word) | 5 (PID, PM-, QA-, SWE-, Test-Plan) |
| Audit-Artefakte (Word) | 3 | `docs/reviews/`, `docs/non-conformities/`, `misra/records/` | | **Safety-Doku** (Word) | 6 (HARA, Safety Case, FMEDA, MISRA-Compliance, Verification-Report, Tool-Qualification) |
| System-Anforderungen| 10 | `reqs/sys/` | | **Manuals** (Word) | 2 (User-Manual, Service-Manual) |
| Software-Anforderungen | 25 | `reqs/swe/` | | **Audit-Artefakte** (Word) | 3 (Review-Protokoll, Non-Conformity, MISRA-Deviation-Record) |
| System-Architektur | 5 | `arch/sys/` | | **System-Anforderungen** | 10 in `reqs/sys/` (Markdown + Doorstop-Style) |
| Software-Architektur| 10 | `arch/swe/` | | **Software-Anforderungen** | 25 in `reqs/swe/` |
| Implementierte Komponenten | 3 (1×ASIL-D, 1×ASIL-B, 1×QM) | `src/` | | **System-Architektur** | 5 in `arch/sys/` mit PlantUML |
| Stub-Komponenten | 7 | `src/stubs/` | | **Software-Architektur** | 10 in `arch/swe/` mit PlantUML |
| Unit-Tests | 28 | `tests/unit/` | | **Implementierte C-Komponenten** | 4 (Apply Ctrl D, Safety Mgr D, Actuator Drv B, Switch Db QM) |
| CI-Pipeline | 1 | `.gitea/workflows/` | | **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 |
## Quick Start ## Quick Start
@@ -25,39 +29,67 @@ Vollstaendige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohm
git clone https://gitea.slohmaier.com/slohmaier/demo-epb.git git clone https://gitea.slohmaier.com/slohmaier/demo-epb.git
cd demo-epb cd demo-epb
# Build + Tests # Tests
make test make test # 41 Tests, alle grün
# Mit Coverage (benoetigt lcov) # Mit Coverage (braucht lcov)
make coverage make coverage
open build/coverage-html/index.html open build/coverage-html/index.html
# Statische Analyse + MISRA (benoetigt cppcheck) # Test-Summary-Report (HTML)
make test-report
open build/test-report.html
# Statische Analyse + MISRA (braucht cppcheck)
make static make static
make misra make misra
# API-Doku (braucht doxygen)
make docs
open build/api-doc/html/index.html
# Traceability-Matrix (HTML)
python3 tools/traceability.py publish docs/traceability
open docs/traceability/index.html
# PlantUML-Diagramme rendern (SVG)
python3 tools/render_plantuml.py
``` ```
## Gefuehrte Tour (~30 min) ## Geführte Tour (~30 min)
### 1. Projektplanung ### 1. Projektplanung (Word)
Start in `docs/`: `docs/`:
- **PID.docx** — Was wird gebaut und warum - **PID.docx** — Was wird gebaut und warum
- **SWE-Plan.docx** — Wie wird gebaut: Sprache, Standards, Branching, Review-Regeln, Coverage-Ziele pro ASIL - **SWE-Plan.docx** — Sprache, Standards, Branching, Reviews, Coverage-Ziele
- **QA-Plan.docx** — Qualitaetsmassnahmen, Reviews, NC-Management - **QA-Plan.docx** — Qualitätsmaßnahmen, Reviews, NC-Management
- **PM-Plan.docx**, **Test-Plan.docx** — Arbeitspakete + Teststrategie - **PM-Plan.docx**, **Test-Plan.docx** — Arbeitspakete + Teststrategie
### 2. Sicherheits-Logik (das ASIL-D Stueck) ### 2. Funktionale Sicherheit (Word — `docs/safety/`)
`reqs/sys/SYS-001.md` → `arch/swe/SWA-002.md` → `src/apply_controller.c` → `tests/unit/test_apply_controller.c` - **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
Das ist die Traceability-Kette: System-Sicherheitsziel → Software-Architektur → Code → Test. ### 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
### 3. Anforderungen + Architektur (Doorstop in Markdown) ### 4. Sicherheits-Logik (das ASIL-D Stück)
- `reqs/sys/` und `reqs/swe/` — alle Anforderungen mit Mapping Traceability-Kette:
- `arch/sys/` und `arch/swe/` — Architektur mit Mapping per `links:` im Frontmatter ```
- Eingebettete PlantUML-Diagramme rendern direkt in Gitea reqs/sys/SYS-001.md → arch/swe/SWA-002.md → src/apply_controller.c → tests/unit/test_apply_controller.c
```
### 4. Code mit Mapping-Tags ### 5. Anforderungen + Architektur (Doorstop in Markdown)
Jede `.c`-Datei traegt `@arch`, `@reqs` im Header: - `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
### 6. Code mit Mapping-Tags
Jede `.c`-Datei trägt `@arch`, `@reqs`, `@asil` im Header:
```c ```c
/** /**
@@ -69,76 +101,73 @@ Jede `.c`-Datei traegt `@arch`, `@reqs` im Header:
*/ */
``` ```
So ist Code -> Architektur -> Anforderung auf einen `grep` durchsuchbar. ### 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.
### 5. Tests mit Anforderungs-Tags ### 8. Audit-Artefakte
`tests/unit/test_apply_controller.c` referenziert die Requirements per `@reqs`. CI mit Coverage-Report belegt, dass jede Anforderung getestet ist. - `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
### 6. Audit-Artefakte ### 9. CI-Pipeline (`.gitea/workflows/validate.yml`)
- `docs/reviews/REV-001.docx` — Review-Protokoll fuer die ASIL-D-Komponente Bei jedem Push:
- `docs/non-conformities/NC-001.docx` — Beispiel einer Non-Conformity mit Korrekturmassnahme 1. **Cross-Platform Build + Test** auf Linux + macOS + Windows
- `misra/records/MISRA-REC-001.docx` — MISRA Deviation Record fuer eine bewusste Advisory-Abweichung 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**
### 7. CI-Pipeline Alles als Gitea-Artefakte abrufbar.
`.gitea/workflows/validate.yml` — bei jedem Push laeuft:
1. Cppcheck (Static Analysis)
2. Cppcheck + MISRA-Addon
3. Build + Unit Tests
4. Coverage (gcov/lcov)
5. Doorstop-Traceability-Check
## Architektur-Ueberblick ### 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
Beispiel: https://gitea.slohmaier.com/slohmaier/demo-epb/releases
## Architektur-Überblick
``` ```
+----------------------+ EPB ECU (SA-001)
| EPB ECU (SA-001) | +----------------------------------+
| +-----------------+ | | Safety Manager (D) | ← arch/swe/SWA-001.md
| | Safety Mgr (D) | | | Apply Controller (D) | ← arch/swe/SWA-002.md
| +-----------------+ | | Actuator Driver (B) | ← arch/swe/SWA-003.md
| | Apply Ctrl (D) | | | Wheel Speed Plausi (B) [stub] |
| +-----------------+ | | Inclino Filter (B) [stub] |
| | Actuator Drv (B)| | | Switch Debouncer (QM) | ← arch/swe/SWA-006.md
| +-----------------+ | | Display Manager (QM) [stub] |
| | Wheel Speed (B) | | | Diag Manager (QM) [stub] |
| | Inclino (B) | | | Service Mode (QM) [stub] |
| +-----------------+ | | Logger (QM) [stub] |
| | Switch DB (QM) | | +----------------------------------+
| | Display (QM) | |
| | Diag (QM) | |
| | Service (QM) | |
| | Logger (QM) | |
| +-----------------+ |
+----------------------+
| | | |
Aktor L Aktor R Aktor L (SA-002) Aktor R (SA-002)
(SA-002) (SA-002)
``` ```
## Format-Strategie ## Format-Strategie
| Inhalt | Format | Begruendung | | Inhalt | Format | Begründung |
|---------------------|-------------------|-------------------------------------------------| |--------|--------|------------|
| Plaene + Audit-Doku | **Word** (.docx) | Industriestandard fuer ISO-9001-Freigabe | | Pläne + Safety + Audit + Manuals | **Word** (.docx) | Industriestandard für ISO-9001-Freigabe |
| Requirements + Arch | **Markdown** (Doorstop) | Lebendig, diff-bar, Traceability per Skript | | Requirements + Architektur | **Markdown** (Doorstop-Stil) | Lebendig, diff-bar, Traceability per Skript |
| Code, Tests, CI | C / YAML | klar | | Code, Tests, CI | C / YAML | klar |
| Release-Bundle | tar.gz mit allem | Eine Datei für den Auditor |
Beide Welten gehen ueber `tools/`-Skripte ineinander ueber: Markdown ist Source of Truth, Word wird per pandoc daraus gebaut. Markdown ist Source of Truth, Word wird per pandoc daraus gebaut.
## Generatoren
| Skript | Zweck |
|---------------------------------------|----------------------------------------------------|
| `tools/generate_doorstop_items.py` | Erzeugt alle 50 Requirements + Arch-Elemente aus Strukturdaten |
## Referenzen ## Referenzen
- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — die Methodik - [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — Methodik-Repo
- ASPICE 4.0 - ASPICE 4.0
- ISO 26262 (insbesondere Part 6 — Software) - ISO 26262 (insbesondere Part 2, 3, 5, 6, 8, 10)
- MISRA C:2012 - MISRA C:2012
## Lizenz ## Lizenz
MIT — siehe [LICENSE](LICENSE). MIT — siehe [LICENSE](LICENSE).