demo-epb/README.md

demo-epb — Electric Parking Brake

Complete demonstration of the 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-refreshed on every push to main and every release tag.

This software is intentionally not production code — it is a demonstration of the engineering method. Code volume kept small on purpose; process depth complete.

What the demo shows

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

git clone https://gitea.slohmaier.com/slohmaier/demo-epb.git
cd demo-epb

# Tests
make test                  # 46 tests, all green

# With coverage (needs lcov)
make coverage
open build/coverage-html/index.html

# Test summary report (HTML)
make test-report
open build/test-report.html

# Static analysis + MISRA (needs cppcheck)
make static
make misra

# API doc (needs 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 diagrams (SVG)
python3 tools/render_plantuml.py

Guided tour (~30 min)

1. Project planning (Word)

docs/plans/:

• 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. 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 — Driver manual (apply, release, hill-hold, LED codes)
• Service-Manual.docx — Workshop doc with UDS DTCs, service mode, sensor checks

4. Safety logic (the ASIL-D piece)

Traceability chain:

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. 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 with mapping tags

Every .c file carries @arch, @reqs, @asil in the header:

/**
 * @file apply_controller.c
 * @arch SWA-002
 * @reqs SWE-001 SWE-002 SWE-003 SWE-004 SWE-005
 *
 * ASIL: D.
 */

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 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)

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 (bidirectional)
6. PlantUML render (all diagrams as SVG)
7. Doxygen API doc
8. Test summary report

All available as Gitea artefacts.

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

Example: https://gitea.slohmaier.com/slohmaier/demo-epb/releases

Architecture overview

                  EPB ECU (SA-001)
       +----------------------------------+
       | Safety Manager (D)               |  ← arch/swe/SWA-001.md
       | Apply Controller (D)             |  ← arch/swe/SWA-002.md
       | Actuator Driver (B)              |  ← arch/swe/SWA-003.md
       | Wheel Speed Plausi (B) [stub]    |
       | Inclino Filter (B) [stub]        |
       | Switch Debouncer (QM)            |  ← arch/swe/SWA-006.md
       | Display Manager (QM) [stub]      |
       | Diag Manager (QM) [stub]         |
       | Service Mode (QM) [stub]         |
       | Logger (QM) [stub]               |
       +----------------------------------+
              |                  |
       Actuator L (SA-002)   Actuator R (SA-002)

Format strategy

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 is the source of truth; Word is built via pandoc.

References

• slohmaier/dev-process — Methodology repo
• ASPICE 4.0
• ISO 26262 (in particular Part 2, 3, 5, 6, 8, 10)
• MISRA C:2012

Licence

MIT — see LICENSE.