Stefan Lohmaier
ba7a3ebd27
Last German folder name in demo-epb. Pairs cleanly with docs/plans-md/ (markdown source) following the project convention. All references in landing page generator, CI workflows, and cross-doc links updated.
179 lines
6.7 KiB
Markdown
179 lines
6.7 KiB
Markdown
# demo-epb — Electric Parking Brake
|
|
|
|
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-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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```c
|
|
/**
|
|
* @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](https://gitea.slohmaier.com/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](LICENSE).
|