# 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/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. 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).