Kai Chappell
afb5bd2075
- Reorder sprints for visual-first development - Dashboard (Sprint 4) now follows Physics Engine (Sprint 3) - Infrastructure layers (SCPI, TCP, HAL) follow visual demo - Update project references to py-dvt-ate
363 lines
16 KiB
Markdown
363 lines
16 KiB
Markdown
# Business Requirements Document
|
|
## py_dvt_ate: Coupled Physics DVT Simulation Platform
|
|
|
|
| Document ID | BRD-001 |
|
|
|-------------|---------|
|
|
| Version | 1.1.0 |
|
|
| Status | Draft |
|
|
| Author | Kai Chappell |
|
|
| Created | 2025-12-01 |
|
|
| Last Updated | 2025-12-01 |
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
This document defines **what** the py_dvt_ate system must do. It specifies the functional and non-functional requirements, constraints, and success criteria.
|
|
|
|
For **why** decisions were made, see `03_architecture_decisions.md`.
|
|
For **how** to implement the system, see `02_technical_specification.md`.
|
|
|
|
---
|
|
|
|
## Related Documents
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| `01_requirements.md` | Defines **what** the system must do (this document) |
|
|
| `02_technical_specification.md` | Specifies **how** to implement the system |
|
|
| `03_architecture_decisions.md` | Explains **why** decisions were made |
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Executive Summary](#1-executive-summary)
|
|
2. [Problem Statement](#2-problem-statement)
|
|
3. [Business Objectives](#3-business-objectives)
|
|
4. [Stakeholders](#4-stakeholders)
|
|
5. [Scope](#5-scope)
|
|
6. [Functional Requirements](#6-functional-requirements)
|
|
7. [Non-Functional Requirements](#7-non-functional-requirements)
|
|
8. [Constraints](#8-constraints)
|
|
9. [Assumptions](#9-assumptions)
|
|
10. [Success Criteria](#10-success-criteria)
|
|
11. [Risks](#11-risks)
|
|
12. [Glossary](#12-glossary)
|
|
|
|
---
|
|
|
|
## 1. Executive Summary
|
|
|
|
### 1.1 Purpose
|
|
|
|
py_dvt_ate is a coupled-physics Device Validation Test (DVT) simulation platform that enables engineers to develop, validate, and debug characterisation test sequences without physical access to laboratory equipment.
|
|
|
|
### 1.2 Background
|
|
|
|
DVT engineers require access to expensive Automated Test Equipment (ATE) to develop and validate characterisation algorithms. Physical equipment is a shared resource with limited availability, creating bottlenecks in the development process.
|
|
|
|
### 1.3 Proposed Solution
|
|
|
|
A software simulation environment that accurately models the physical coupling between thermal and electrical domains, allowing complete test sequence development and validation without hardware access.
|
|
|
|
---
|
|
|
|
## 2. Problem Statement
|
|
|
|
### 2.1 Current Challenges
|
|
|
|
| Challenge | Impact |
|
|
|-----------|--------|
|
|
| **Limited Equipment Access** | ATE racks cost $100k+ and are shared resources; engineers must schedule lab time |
|
|
| **Slow Development Iteration** | Cannot iterate on test algorithms without physical equipment reservation |
|
|
| **Difficult Edge Case Testing** | Testing failure modes or boundary conditions risks damaging equipment |
|
|
| **Training Barriers** | New engineers cannot practise without supervision on expensive equipment |
|
|
| **Remote Work Limitations** | Engineers cannot develop tests without physical lab presence |
|
|
|
|
### 2.2 Gap Analysis
|
|
|
|
| Need | Current State | Desired State |
|
|
|------|---------------|---------------|
|
|
| Algorithm Development | Requires physical equipment | Fully offline development |
|
|
| Thermal-Electrical Coupling | Not modelled in simple mocks | Realistic coupled physics |
|
|
| Hardware Transition | Separate code for simulation vs real | Single codebase, configuration-driven |
|
|
| Test Validation | Only possible in lab | Complete validation before lab time |
|
|
|
|
---
|
|
|
|
## 3. Business Objectives
|
|
|
|
### 3.1 Primary Objectives
|
|
|
|
| ID | Objective | Measurable Outcome |
|
|
|----|-----------|-------------------|
|
|
| BO-1 | Enable offline DVT algorithm development | Engineers can develop complete characterisation tests without equipment access |
|
|
| BO-2 | Reduce equipment contention | Test code validated before consuming lab time |
|
|
| BO-3 | Demonstrate professional software engineering | Portfolio-quality project following industry best practices |
|
|
|
|
### 3.2 Secondary Objectives
|
|
|
|
| ID | Objective | Measurable Outcome |
|
|
|----|-----------|-------------------|
|
|
| BO-4 | Provide training platform | Safe environment for learning ATE concepts |
|
|
| BO-5 | Enable remote development | Full DVT development capability without lab presence |
|
|
|
|
---
|
|
|
|
## 4. Stakeholders
|
|
|
|
| Stakeholder | Role | Interest |
|
|
|-------------|------|----------|
|
|
| DVT Engineer (Primary User) | Develops characterisation tests | Needs realistic simulation for algorithm validation |
|
|
| Test Manager | Oversees test development | Wants reduced equipment contention, faster delivery |
|
|
| New Engineers | Learning ATE workflows | Needs safe practice environment |
|
|
| Portfolio Reviewer | Evaluates project quality | Assesses software engineering competence |
|
|
|
|
---
|
|
|
|
## 5. Scope
|
|
|
|
### 5.1 In Scope
|
|
|
|
| Category | Items |
|
|
|----------|-------|
|
|
| **Simulated Instruments** | Thermal Chamber, Programmable Power Supply, Digital Multimeter |
|
|
| **DUT Models** | Voltage Regulator (LDO) with thermal-electrical coupling |
|
|
| **Test Types** | Temperature Coefficient characterisation, Load Regulation |
|
|
| **User Interfaces** | Command-line interface, Streamlit dashboard, Programmatic API |
|
|
| **Data Management** | Test result persistence, Data export |
|
|
| **Reporting** | Automated test reports (future phase) |
|
|
|
|
### 5.2 Out of Scope
|
|
|
|
| Category | Items | Rationale |
|
|
|----------|-------|-----------|
|
|
| Additional Instruments | Oscilloscope, Signal Generator | Future phase |
|
|
| Additional DUT Models | Op-Amp, ADC, MOSFET | Future phase |
|
|
| Multi-user Operation | Concurrent users, access control | Not required for portfolio |
|
|
| Cloud Deployment | Hosted service | Local execution sufficient |
|
|
| Legacy Protocols | GPIB, USB-TMC hardware | Focus on TCP/IP simulation |
|
|
|
|
### 5.3 Boundaries
|
|
|
|
The system SHALL:
|
|
- Operate as a standalone local application
|
|
- Simulate instrument behaviour, not replicate specific vendor implementations
|
|
- Model physics at a level sufficient for algorithm validation, not device design
|
|
|
|
---
|
|
|
|
## 6. Functional Requirements
|
|
|
|
### 6.1 Physics Simulation
|
|
|
|
| ID | Requirement | Priority |
|
|
|----|-------------|----------|
|
|
| FR-PS-1 | The system SHALL simulate thermal chamber temperature control with realistic ramp and settling behaviour | Must |
|
|
| FR-PS-2 | The system SHALL model thermal coupling between chamber ambient and DUT case temperature | Must |
|
|
| FR-PS-3 | The system SHALL model DUT self-heating based on power dissipation | Must |
|
|
| FR-PS-4 | The system SHALL calculate DUT junction temperature from case temperature and thermal resistance | Must |
|
|
| FR-PS-5 | The system SHALL compute DUT electrical parameters as functions of junction temperature | Must |
|
|
| FR-PS-6 | The system SHALL update physics state at a rate sufficient for realistic transient behaviour | Must |
|
|
| FR-PS-7 | The system SHALL model thermal time constants for chamber and DUT thermal mass | Should |
|
|
|
|
### 6.2 Instrument Simulation
|
|
|
|
| ID | Requirement | Priority |
|
|
|----|-------------|----------|
|
|
| FR-IS-1 | The system SHALL provide a simulated Thermal Chamber with temperature setpoint and readback | Must |
|
|
| FR-IS-2 | The system SHALL provide a simulated Power Supply with voltage/current control and measurement | Must |
|
|
| FR-IS-3 | The system SHALL provide a simulated Multimeter with DC voltage measurement | Must |
|
|
| FR-IS-4 | All simulated instruments SHALL respond to industry-standard SCPI commands | Must |
|
|
| FR-IS-5 | Instruments SHALL communicate over TCP/IP network sockets | Must |
|
|
| FR-IS-6 | Instruments SHALL maintain state between commands within a session | Must |
|
|
| FR-IS-7 | Instruments SHALL return measurement values derived from the physics simulation | Must |
|
|
| FR-IS-8 | Instruments SHALL simulate realistic timing (settling, acquisition delays) | Should |
|
|
|
|
### 6.3 Hardware Abstraction
|
|
|
|
| ID | Requirement | Priority |
|
|
|----|-------------|----------|
|
|
| FR-HA-1 | The system SHALL provide abstract interfaces for each instrument type | Must |
|
|
| FR-HA-2 | Test code SHALL interact only with abstract interfaces, not concrete implementations | Must |
|
|
| FR-HA-3 | The system SHALL support swapping between simulated and real instruments via configuration | Must |
|
|
| FR-HA-4 | The abstraction layer SHALL not expose simulation-specific or hardware-specific details | Must |
|
|
|
|
### 6.4 Test Execution
|
|
|
|
| ID | Requirement | Priority |
|
|
|----|-------------|----------|
|
|
| FR-TE-1 | The system SHALL support defining multi-step test sequences | Must |
|
|
| FR-TE-2 | The system SHALL execute test sequences with proper instrument coordination | Must |
|
|
| FR-TE-3 | The system SHALL log all measurements during test execution | Must |
|
|
| FR-TE-4 | The system SHALL evaluate measurements against defined limits | Must |
|
|
| FR-TE-5 | The system SHALL determine overall pass/fail status for tests | Must |
|
|
| FR-TE-6 | The system SHALL support Temperature Coefficient characterisation test | Must |
|
|
| FR-TE-7 | The system SHALL support Load Regulation vs Temperature test | Should |
|
|
|
|
### 6.5 Data Management
|
|
|
|
| ID | Requirement | Priority |
|
|
|----|-------------|----------|
|
|
| FR-DM-1 | The system SHALL persist test run metadata (test name, timestamp, status) | Must |
|
|
| FR-DM-2 | The system SHALL persist all measurements with timestamps and conditions | Must |
|
|
| FR-DM-3 | The system SHALL persist calculated results with pass/fail status | Must |
|
|
| FR-DM-4 | The system SHALL support querying historical test results | Should |
|
|
| FR-DM-5 | The system SHALL support exporting data in common formats (CSV) | Should |
|
|
|
|
### 6.6 Reporting
|
|
|
|
| ID | Requirement | Priority |
|
|
|----|-------------|----------|
|
|
| FR-RP-1 | The system SHALL generate test reports containing results and pass/fail status | Could |
|
|
| FR-RP-2 | Reports SHALL include data visualisation (charts/graphs) | Could |
|
|
| FR-RP-3 | Reports SHALL be exportable in portable format (PDF or HTML) | Could |
|
|
|
|
### 6.7 User Interface
|
|
|
|
| ID | Requirement | Priority |
|
|
|----|-------------|----------|
|
|
| FR-UI-1 | The system SHALL provide a command-line interface for test execution | Must |
|
|
| FR-UI-2 | The system SHALL provide a programmatic API for integration | Must |
|
|
| FR-UI-3 | The system SHALL provide a Streamlit dashboard for real-time monitoring | Should |
|
|
| FR-UI-4 | Real-time instrument status SHALL be observable during test execution | Should |
|
|
|
|
---
|
|
|
|
## 7. Non-Functional Requirements
|
|
|
|
### 7.1 Performance
|
|
|
|
| ID | Requirement | Metric |
|
|
|----|-------------|--------|
|
|
| NFR-P-1 | Physics simulation SHALL run in real-time or faster | Update rate ≥ 100 Hz |
|
|
| NFR-P-2 | Instrument command latency SHALL be negligible | < 50 ms round-trip (localhost) |
|
|
| NFR-P-3 | Data logging SHALL not impact test execution | No dropped measurements |
|
|
|
|
### 7.2 Reliability
|
|
|
|
| ID | Requirement | Metric |
|
|
|----|-------------|--------|
|
|
| NFR-R-1 | System SHALL handle instrument communication errors gracefully | Clear error messages, no crashes |
|
|
| NFR-R-2 | Data SHALL be persisted before system exit | No data loss on normal shutdown |
|
|
| NFR-R-3 | System SHALL recover from transient connection failures | Auto-reconnect capability |
|
|
|
|
### 7.3 Maintainability
|
|
|
|
| ID | Requirement | Metric |
|
|
|----|-------------|--------|
|
|
| NFR-M-1 | Code SHALL follow consistent style and formatting | Automated linting passes |
|
|
| NFR-M-2 | Public interfaces SHALL be documented | All public APIs have docstrings |
|
|
| NFR-M-3 | Code SHALL have automated test coverage | ≥ 80% coverage on core modules |
|
|
| NFR-M-4 | Architecture SHALL support adding new instruments without modifying existing code | Open/closed principle demonstrated |
|
|
| NFR-M-5 | Architecture SHALL support adding new DUT models without modifying physics engine | Open/closed principle demonstrated |
|
|
|
|
### 7.4 Portability
|
|
|
|
| ID | Requirement | Metric |
|
|
|----|-------------|--------|
|
|
| NFR-PT-1 | System SHALL run on Windows 10+ | Tested and documented |
|
|
| NFR-PT-2 | System SHALL run on Linux | Tested and documented |
|
|
| NFR-PT-3 | System SHALL require only standard package manager installation | pip install sufficient |
|
|
|
|
### 7.5 Usability
|
|
|
|
| ID | Requirement | Metric |
|
|
|----|-------------|--------|
|
|
| NFR-U-1 | System SHALL start with a single command | Documented quick-start |
|
|
| NFR-U-2 | Error messages SHALL clearly indicate the problem and suggested resolution | Actionable error messages |
|
|
| NFR-U-3 | Configuration SHALL use human-readable format | YAML or similar |
|
|
|
|
---
|
|
|
|
## 8. Constraints
|
|
|
|
### 8.1 Technical Constraints
|
|
|
|
| ID | Constraint | Rationale |
|
|
|----|------------|-----------|
|
|
| C-T-1 | Implementation SHALL be 100% Python | Target role alignment; industry standard for test automation |
|
|
| C-T-2 | System SHALL not require external service dependencies (database servers, message brokers) | Simplify deployment; portfolio reviewability |
|
|
| C-T-3 | All dependencies SHALL be open-source | Avoid licensing issues |
|
|
| C-T-4 | System SHALL run without requiring physical instruments | Core purpose of the project |
|
|
|
|
### 8.2 Project Constraints
|
|
|
|
| ID | Constraint | Rationale |
|
|
|----|------------|-----------|
|
|
| C-P-1 | Single developer | Portfolio project |
|
|
| C-P-2 | No budget for commercial tools or services | Personal project |
|
|
|
|
---
|
|
|
|
## 9. Assumptions
|
|
|
|
| ID | Assumption | Impact if Invalid |
|
|
|----|------------|-------------------|
|
|
| A-1 | Users have Python 3.11+ installed | Must document installation requirements |
|
|
| A-2 | Users have basic familiarity with ATE concepts | May need to add tutorial documentation |
|
|
| A-3 | Localhost network performance is sufficient | May need to optimise for slower systems |
|
|
| A-4 | Single-user operation is acceptable for MVP | Multi-user would require significant redesign |
|
|
| A-5 | Simplified physics models are acceptable for algorithm validation | May need to increase model fidelity |
|
|
|
|
---
|
|
|
|
## 10. Success Criteria
|
|
|
|
### 10.1 Minimum Viable Product (MVP)
|
|
|
|
The project is successful if:
|
|
|
|
| ID | Criterion | Verification Method |
|
|
|----|-----------|---------------------|
|
|
| SC-1 | Can execute a complete Temperature Coefficient characterisation test against simulated instruments | End-to-end test demonstration |
|
|
| SC-2 | Physics coupling is evident: DUT self-heating affects measurements | Comparison of low-power vs high-power test results |
|
|
| SC-3 | Same test code runs against simulated and real instruments via configuration change | Demonstrate with PyVISA backend (if hardware available) or mock |
|
|
| SC-4 | Test results are persisted and retrievable | Query historical results |
|
|
| SC-5 | Code follows SOLID principles with clear module boundaries | Architecture review |
|
|
| SC-6 | Core modules have ≥ 80% test coverage | Coverage report |
|
|
|
|
### 10.2 Full Project Success
|
|
|
|
| ID | Criterion | Verification Method |
|
|
|----|-----------|---------------------|
|
|
| SC-7 | Streamlit dashboard provides real-time instrument visualisation | Dashboard demonstration |
|
|
| SC-8 | System deployable with single command | Docker Compose demonstration |
|
|
| SC-9 | Complete documentation (README, architecture, API) | Documentation review |
|
|
| SC-10 | Demonstrates portfolio-quality engineering | External code review |
|
|
|
|
---
|
|
|
|
## 11. Risks
|
|
|
|
| ID | Risk | Probability | Impact | Mitigation |
|
|
|----|------|-------------|--------|------------|
|
|
| R-1 | Physics model too simplistic for realistic behaviour | Medium | High | Research real component datasheets; validate against published specifications |
|
|
| R-2 | Scope creep delays completion | High | Medium | Strict MVP definition; defer features to future phases |
|
|
| R-3 | SCPI implementation incompatible with real instruments | Low | Medium | Reference IVI Foundation standards |
|
|
| R-4 | Over-engineering delays delivery | Medium | Medium | Focus on working software over architectural perfection |
|
|
| R-5 | UI development consumes excessive time | Medium | High | CLI-first approach; Streamlit for rapid iteration |
|
|
|
|
---
|
|
|
|
## 12. Glossary
|
|
|
|
| Term | Definition |
|
|
|------|------------|
|
|
| **ATE** | Automated Test Equipment - systems for testing electronic devices |
|
|
| **Characterisation** | Process of measuring device parameters across operating conditions |
|
|
| **DUT** | Device Under Test - the component being characterised |
|
|
| **DVT** | Design Validation Test - testing to verify design meets specifications |
|
|
| **HAL** | Hardware Abstraction Layer - interface isolating code from hardware specifics |
|
|
| **LDO** | Low Dropout Regulator - type of linear voltage regulator |
|
|
| **NPLC** | Number of Power Line Cycles - integration time unit for DMMs |
|
|
| **SCPI** | Standard Commands for Programmable Instruments - IEEE 488.2 command syntax |
|
|
| **TempCo** | Temperature Coefficient - rate of parameter change with temperature (ppm/°C) |
|
|
| **Thermal Coupling** | Physical interaction between thermal and electrical domains |
|
|
| **θ (theta)** | Thermal resistance, measured in °C/W |
|
|
|
|
---
|
|
|
|
**End of Business Requirements Document**
|