kschappell/py-dvt-ate
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Initial project setup with documentation

Browse Source 
- Add project requirements document (01_requirements.md)
- Add technical specification (02_technical_specification.md)
- Add architecture decisions (03_architecture_decisions.md)
- Add README with project overview
- Add .gitignore for Python projects
This commit is contained in:
Kai Chappell
2025-01-15 10:17:15 +00:00
commit 5d85275396
5 changed files with 2336 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
docs/01_requirements.md Normal file
View File

@@ -0,0 +1,362 @@
# Business Requirements Document
## ThermalATE: 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 ThermalATE 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
ThermalATE 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**