03_software_req.sdoc

[DOCUMENT]
TITLE: Safe Kiln Controller, Software Requirements
UID: SAFEKILN-SWR
VERSION: 0.1 (draft)
DATE: 2026-10-08
OPTIONS:
  MARKUP: Markdown
  VIEW_STYLE: Table
  NODE_IN_TOC: True
METADATA:
  SPDX-FileCopyrightText: 2026 Bitcrush Testing
  SPDX-License-Identifier: GPL-3.0-or-later
  Status: For review
  Project: Safe Kiln Controller, PID kiln controller

[GRAMMAR]
ELEMENTS:
- TAG: TEXT
  FIELDS:
  - TITLE: STATEMENT
    TYPE: String
    REQUIRED: True
- TAG: SECTION
  PROPERTIES:
    IS_COMPOSITE: True
  FIELDS:
  - TITLE: UID
    TYPE: String
    REQUIRED: False
  - TITLE: TITLE
    TYPE: String
    REQUIRED: True
- TAG: REQUIREMENT
  FIELDS:
  - TITLE: UID
    TYPE: String
    REQUIRED: True
  - TITLE: STATEMENT
    TYPE: String
    REQUIRED: True
  - TITLE: RATIONALE
    TYPE: String
    REQUIRED: False
  - TITLE: PRIORITY
    TYPE: SingleChoice(M, S, C, W)
    REQUIRED: False
  - TITLE: VERIFICATION
    TYPE: MultipleChoice(T, A, I, D)
    REQUIRED: False
  - TITLE: STATUS
    TYPE: SingleChoice(Active, Withdrawn, Superseded, Reversed, Resolved)
    REQUIRED: False
  RELATIONS:
  - TYPE: Parent
- TAG: CONSTRAINT
  FIELDS:
  - TITLE: UID
    TYPE: String
    REQUIRED: True
  - TITLE: STATEMENT
    TYPE: String
    REQUIRED: True
  - TITLE: STATUS
    TYPE: SingleChoice(Active, Withdrawn, Superseded, Reversed, Resolved)
    REQUIRED: False
- TAG: ASSUMPTION
  FIELDS:
  - TITLE: UID
    TYPE: String
    REQUIRED: True
  - TITLE: STATEMENT
    TYPE: String
    REQUIRED: True
  - TITLE: STATUS
    TYPE: SingleChoice(Active, Withdrawn, Superseded, Reversed, Resolved)
    REQUIRED: False
- TAG: QUESTION
  FIELDS:
  - TITLE: UID
    TYPE: String
    REQUIRED: True
  - TITLE: STATEMENT
    TYPE: String
    REQUIRED: True
  - TITLE: STATUS
    TYPE: SingleChoice(Active, Withdrawn, Superseded, Reversed, Resolved)
    REQUIRED: False

[TEXT]
STATEMENT: >>>
Level 3 of the V-model (see [`v-model-process.md`](v-model-process.md)): what the
**software** must do, as allocated from the system requirements of
[`02_system_req.sdoc`](02_system_req.sdoc). Refined by the software architecture
of [`04_software_arch.sdoc`](04_software_arch.sdoc) and verified by integration
tests.

The sub-prefix after `SWR-` is the functional area and is a deliberate deviation
from the flat `SWR-nnn` numbering the process document's examples show. With 169
functional requirements, `SWR-CTL-07` says where it belongs and `SWR-112` does
not, and the areas were already the document's structure. The process document
records the deviation.

`SWR-SAF-` are the 27 safety requirements that are software behaviour; the four
that hardware discharges are in `02_system_req.sdoc`. `SWR-NFR-` are the
non-functional requirements, all of which turned out to be software-level.
`SWR-TST-` are the testability requirements, which constrain the software so that
it can be verified at all.
<<<

[[SECTION]]
UID: SECT-1
TITLE: 1. Introduction

[[SECTION]]
UID: SECT-1-1
TITLE: 1.1 Purpose

[TEXT]
STATEMENT: >>>
This document specifies the requirements for **Safe Kiln Controller**, an open-source
temperature controller for electric ceramic / glass kilns. It is the reference
for implementation, verification and review. The software architecture derived
from this document is [`architecture.md`](architecture.md).
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-1-2
TITLE: 1.2 Scope

[TEXT]
STATEMENT: >>>
Safe Kiln Controller replaces the mechanical or simple on/off controller of an electric
kiln with a closed-loop PID controller that follows a user-defined
**firing curve** (a time/temperature program). The operator interacts with the
device through a small local display and, over WiFi, through a built-in web
interface that also visualises logged temperature data.

In scope:

- Temperature acquisition from a type-K thermocouple in the kiln chamber, plus a
  second thermocouple for enclosure/electronics temperature.
- Time-proportional PID control of a solid-state relay switching the heating
  elements, with an independent safety contactor.
- Measurement of heater current with a current transformer (Stromwandler), for
  direct electrical detection of a failed relay, contactor or heating element.
- Automatic PID tuning against the real kiln.
- Storage and execution of multi-segment firing programs.
- Local display of current and target temperature plus program state.
- A self-hosted web interface for program editing, live monitoring, historical
  temperature charts and configuration.
- On-device logging of every firing run without an SD card or external database.
- Safety supervision: thermal runaway, sensor failure, relay failure,
  over-temperature.

Out of scope: see §12 ([LINK: SECT-12]).
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-1-3
TITLE: 1.3 Definitions and abbreviations

[TEXT]
STATEMENT: >>>
| Term | Meaning |
|---|---|
| **Firing program** | Ordered list of segments describing a complete firing. Also "curve", "profile", "schedule". |
| **Segment** | One element of a program: ramp to a target temperature at a given rate, then dwell (hold) for a given time. |
| **Setpoint (SP)** | The instantaneous temperature the controller is aiming for. Produced by the setpoint generator from the active program; it is *not* the segment target except at the end of a ramp. |
| **Process value (PV)** | The measured kiln temperature. |
| **Control output (CV)** | PID output, 0–100 % heating duty. |
| **Dwell / soak** | Holding the temperature constant for a defined time. |
| **Ramp rate** | Rate of change of the setpoint, in °C/h. |
| **Hold-back** | Suspension of setpoint advance while PV lags SP beyond a threshold, so a slow kiln cannot silently fall behind its curve. |
| **SSR** | Solid-state relay. Modulates heater power. |
| **Contactor / EMR** | Electromechanical relay or contactor in series with the SSR. Provides a galvanic break independent of the SSR. |
| **TC** | Thermocouple. |
| **CJC** | Cold-junction compensation. |
| **Stromwandler / CT** | Current transformer. A split-core clip-on transformer around one heater conductor giving a galvanically isolated signal proportional to heater current. |
| **Burden** | The resistor across a CT secondary that turns its output current into a voltage. A current-output CT whose burden is removed while primary current flows develops dangerous open-circuit voltages. |
| **RMS** | Root mean square: the heating-equivalent value of an alternating waveform. |
| **Fail-on / fail-off** | A switching device stuck conducting (fail-on) or stuck open (fail-off). A shorted SSR and a welded contactor are both fail-on faults. |
| **Weld discrimination** | Determining whether unexpected current is due to a shorted SSR or a welded contactor, by dropping the contactor and re-measuring. |
| **Time-proportional control** | Converting a 0–100 % duty into on/off intervals within a fixed window, since an SSR cannot be driven at an analogue level. |
| **Relay autotune** | Åström–Hägglund method: force a bounded limit cycle with on/off control, measure its amplitude and period, derive PID gains. |
| **HAL** | Hardware abstraction layer. |
| **HIL** | Hardware in the loop. |
| **SUT** | System under test. |
| **NVS** | ESP-IDF Non-Volatile Storage (key/value store in flash). |
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-1-4
TITLE: 1.4 Requirement conventions

[TEXT]
STATEMENT: >>>
Each requirement has a stable identifier, a **shall** statement, and a
verification method:

| Code | Method | Meaning |
|---|---|---|
| **T** | Test | Automated test (host unit test, target test, or HIL test). |
| **A** | Analysis | Calculation, model, static analysis or code metric. |
| **I** | Inspection | Review of code, schematic or document. |
| **D** | Demonstration | Operating the system and observing behaviour. |

Priority: **M** = mandatory for v1.0, **S** = should have, **C** = could have
(deferred without blocking release).

Identifier prefixes:

| Prefix | Area |
|---|---|
| `ASM` | Assumption |
| `CON` | Constraint |
| `FR-ACQ` | Temperature acquisition |
| `FR-CTL` | Control loop |
| `FR-TUN` | Automatic PID tuning |
| `FR-PRG` | Firing programs |
| `FR-RUN` | Run control and state machine |
| `FR-HMI` | Local display and input |
| `FR-WEB` | Web interface |
| `FR-LOG` | Data logging |
| `FR-CFG` | Configuration |
| `FR-NET` | Connectivity and time |
| `FR-UPD` | Firmware update |
| `SR` | Safety requirement |
| `NFR` | Non-functional requirement |
| `HR` | Hardware interface requirement |
| `TR` | Testability requirement |
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-1-5
TITLE: 1.5 References

[TEXT]
STATEMENT: >>>
| Ref | Document |
|---|---|
| [R1] | [PIDKiln](https://github.com/Saur0o0n/PIDKiln) by Adrian Siemieniak, ESP32 kiln controller, the functional inspiration for this project (GPL-3.0). |
| [R2] | Espressif, *ESP-IDF Programming Guide*, v5.x. |
| [R3] | Analog Devices, *MAX31856 Precision Thermocouple to Digital Converter with Linearization*, datasheet. |
| [R4] | IEC 60584-1, *Thermocouples, Part 1: EMF specifications and tolerances*. |
| [R5] | K. J. Åström, T. Hägglund, *PID Controllers: Theory, Design and Tuning*, 2nd ed., 1995. |
| [R6] | IEC 60519-1, *Safety in installations for electroheating and electromagnetic processing*. |
| [R7] | GNU General Public License version 3, [`../LICENSE`](../LICENSE). |
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-1-6
TITLE: 1.6 Relationship to PIDKiln

[TEXT]
STATEMENT: >>>
PIDKiln [R1] demonstrates that a ~40 USD ESP32 board can run a real kiln, and
this project adopts its proven ideas: a segment-based program model
(`target / ramp / dwell`), dual display and web control, on-device storage with
no external services, a redundant SSR + contactor output stage, and safety
supervision covering runaway, probe failure, SSR failure and insulation
degradation.

Safe Kiln Controller deliberately diverges in the following respects, and these
divergences drive many requirements below:

| Aspect | PIDKiln | Safe Kiln Controller | Driver |
|---|---|---|---|
| Framework | Arduino-ESP32 | ESP-IDF v5.x ([LINK: UR-CON-01]) | Explicit requirement; better test tooling, partition/OTA control, watchdogs |
| MCU | ESP32-WROVER | ESP32-S3 ([LINK: SYS-HW-01]) | Explicit requirement |
| TC front-end | MAX31855 (K only, ≤1350 °C) | MAX31856 (K/N/S/R/B/E/J/T, richer fault detection) | Diagnosability, [LINK: SWR-SAF-04] |
| PID gains | Manually tuned, documented by experiment | Automatic tuning on-device (FR-TUN ([LINK: SECT-3-3])) | Explicit requirement |
| Storage | SPIFFS on internal flash, microSD board recommended | Dedicated raw partitions, fixed slots for programs and run records and a circular ring for the log, no SD card and no filesystem ([LINK: UR-CON-03]) | Explicit requirement |
| Heater current | Optional 30 A/1 V power meter, not used for protection | **Mandatory** current transformer driving relay fail-on / fail-off detection and weld discrimination (FR-CUR ([LINK: SECT-3-12]), [LINK: SWR-SAF-25]–[LINK: SWR-SAF-30]) | Explicit requirement; resolves [LINK: OQ-02] |
| Architecture | Arduino sketch, hardware access throughout | Layered, HAL-isolated, host-testable core (TR ([LINK: SECT-7])) | Explicit requirement: design for testability |

No PIDKiln source code is copied. Safe Kiln Controller is licensed GPL-3.0-or-later, the
same licence as PIDKiln, so derivation remains possible in either direction.
<<<

[[/SECTION]]

[[/SECTION]]

[[SECTION]]
UID: SECT-2
TITLE: 2. System overview

[[SECTION]]
UID: SECT-2-1
TITLE: 2.1 Context

[TEXT]
STATEMENT: >>>
```mermaid
flowchart LR
    OP(["Operator"])
    subgraph KC["Safe Kiln Controller device"]
        MCU["ESP32-S3<br/>controller"]
        OLED["128x64 OLED"]
        ENC["Encoder<br/>+ button"]
        BUZ["Buzzer"]
    end
    subgraph KILN["Kiln"]
        TC1["Chamber<br/>thermocouple"]
        ELEM["Heating<br/>elements"]
    end
    SSR["SSR"]
    CONT["Safety<br/>contactor"]
    CT["Current<br/>transformer"]
    TC2["Enclosure<br/>thermocouple"]
    BROWSER(["Browser on<br/>phone / PC"])
    MAINS(["Mains supply"])

    OP -->|turn / press| ENC
    OLED -->|temperatures, state| OP
    BUZ -->|alarm| OP
    TC1 -->|mV| MCU
    TC2 -->|mV| MCU
    MCU -->|duty| SSR
    MCU -->|heat enable| CONT
    MAINS --> CONT --> SSR --> CT --> ELEM
    CT -->|heater current| MCU
    ELEM -.->|heat| TC1
    MCU <-->|WiFi / HTTP| BROWSER
```
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-2-2
TITLE: 2.2 Operating modes

[TEXT]
STATEMENT: >>>
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> RunningProgram: start program
    Idle --> Manual: set fixed target
    Idle --> Autotune: start tuning
    RunningProgram --> Paused: pause
    Paused --> RunningProgram: resume
    RunningProgram --> Complete: last segment done
    Manual --> Idle: stop
    Autotune --> Idle: finished / aborted
    Complete --> Idle: acknowledge
    RunningProgram --> Fault: safety trip
    Manual --> Fault: safety trip
    Autotune --> Fault: safety trip
    Paused --> Fault: safety trip
    Fault --> Idle: acknowledge (heat off, cooled)
```

| Mode | Description |
|---|---|
| **Idle** | Heating disabled, temperature monitored and displayed. |
| **Running** | Executing a firing program under PID control. |
| **Paused** | Program suspended, heating off, elapsed time frozen; resumable. |
| **Manual** | PID holds a single operator-entered target temperature indefinitely. |
| **Autotune** | Automatic PID tuning procedure in progress. |
| **Complete** | Program finished normally; cooling, awaiting acknowledgement. |
| **Fault** | A safety condition tripped. Heating de-energised and latched off. |
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-2-3
TITLE: 2.3 Primary use cases

[TEXT]
STATEMENT: >>>
| UC | Actor | Description |
|---|---|---|
| UC-1 | Operator | Load a stored firing program, review it, start it, and walk away. |
| UC-2 | Operator | Watch current vs. target temperature on the local display. |
| UC-3 | Operator | Open the web interface on a phone to see live status and the curve traced so far. |
| UC-4 | Operator | Create or edit a firing program in the browser and save it on the device. |
| UC-5 | Operator | Change the target temperature or ramp of a *running* program. |
| UC-6 | Operator | Abort a running firing from either the device or the browser. |
| UC-7 | Operator | Run automatic PID tuning after installing the controller on a new kiln. |
| UC-8 | Operator | Review the logged temperature trace of a previous firing and export it. |
| UC-9 | System | Detect a failed element, shorted SSR, welded contactor or broken thermocouple, de-energise the kiln and alarm. |
| UC-12 | Operator | Fit a clip-on current transformer to a heater conductor and calibrate it against a reference meter. |
| UC-13 | Operator | See that this firing is drawing less current than usual and conclude an element is failing, before it ruins a load. |
| UC-10 | Installer | Provision WiFi credentials and configure kiln limits on first power-up. |
| UC-11 | Maintainer | Update firmware over WiFi. |
<<<

[[/SECTION]]

[[/SECTION]]

[[SECTION]]
UID: SECT-3
TITLE: 3. Functional requirements

[[SECTION]]
UID: SECT-3-1
TITLE: 3.1 Temperature acquisition (FR-ACQ)

[REQUIREMENT]
UID: SWR-ACQ-01
STATEMENT: >>>
Chamber temperature shall be measured with a MAX31856 thermocouple front end over SPI **by the independent supervisor**, and reported to the controller over the link of [LINK: SYS-HW-27] at not less than 4 Hz. The **enclosure** channel's MAX31856 remains the controller's own, on the controller's bus.

**Amended 2026-10-10 with the supervisor (SWA-22).** This said "the system shall measure", which was accurate when one microcontroller read both front ends. It no longer is, and the difference matters to every requirement downstream: the controller does not own the chamber front end, cannot configure it ([LINK: SWR-ACQ-02]), and has no access to it other than a frame arriving on a serial line.

What that makes the controller's obligation here:

- **A report is a sample.** The link's rate is the controller's sample rate; there is nothing behind it to poll faster.
- **Silence is a sensor fault, not a comms problem.** A link that has gone quiet, or that is repeating a sequence number, presents to the controller exactly as a front end that has stopped answering, and is handled by [LINK: SWR-SAF-04]'s grace and latch rather than retried. That is tested end to end: the kiln is heating, the link stops, the fault latches and the contactor opens.
- **A reading is not trusted further than its source.** The supervisor's own fault bits and its trip reason come up the same link and are displayed, never acted on as permission.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-02
STATEMENT: >>>
The **chamber** thermocouple shall be type **K**, and its type shall not be configurable.

The chamber front end is read by the independent safety supervisor, which applies a hard-coded temperature backstop ([LINK: SWR-SAF-23]). The MAX31856 linearises according to a type register, so whoever sets that register determines what the supervisor's temperature *means*: with the supervisor expecting type K and a type S couple fitted, the reading at 1300 °C is roughly a quarter of type K's output and the backstop would never fire. Tripping on raw thermovoltage does not escape this, because a threshold set for the least sensitive type never fires for the most sensitive and one set for the most sensitive fires at a few hundred degrees for the rest.

The other types are therefore a documented limitation of the supervised product rather than a silent hazard. The **enclosure** channel's type remains configurable, that channel not being in the supervisor's remit.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-03
STATEMENT: >>>
The system shall acquire chamber temperature at a rate of at least **4 Hz**, and the acquisition period shall be constant to within ±10 %.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-04
STATEMENT: >>>
The system shall apply cold-junction compensation using the MAX31856 internal cold-junction sensor.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-05
STATEMENT: >>>
The system shall report chamber temperature with a resolution of **0.1 °C** or finer and a usable range of **−20 °C to 1350 °C** for type K.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-06
STATEMENT: >>>
The system shall configure the front-end's line-frequency notch filter to **50 Hz or 60 Hz** according to configuration, defaulting to 50 Hz.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-07
STATEMENT: >>>
The system shall apply a configurable first-order low-pass filter to the measurement used for control, with a time constant of 0–30 s (default 2 s), and shall log the *unfiltered* value alongside it.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-08
STATEMENT: >>>
The system shall apply a configurable calibration offset of −50.0 … +50.0 °C and a gain factor of 0.90 … 1.10 to the chamber reading.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-09
STATEMENT: >>>
The system shall measure enclosure/electronics temperature with a second, independently configurable thermocouple channel.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-10
STATEMENT: >>>
The system shall read and expose the front-end fault register on every conversion, distinguishing at minimum: open circuit, short to VCC, short to GND, cold-junction out of range, thermocouple out of range, over/under-voltage.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-11
STATEMENT: >>>
The system shall compute the rate of temperature change (°C/h) from a regression over a configurable window of 10–300 s (default 60 s).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-ACQ-12
STATEMENT: >>>
On a transient acquisition error the system shall retain the last valid reading for a configurable grace period of 1–30 s (default 5 s) before declaring a sensor fault ([LINK: SWR-SAF-04]).
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-2
TITLE: 3.2 Control loop (FR-CTL)

[REQUIREMENT]
UID: SWR-CTL-01
STATEMENT: >>>
The system shall implement a PID controller producing a heating duty in the range 0–100 %.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-02
STATEMENT: >>>
The controller shall execute at a fixed, configurable period of 0.25–5 s (default 1 s), independent of the acquisition rate.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-03
STATEMENT: >>>
The controller shall use configurable gains Kp, Ki, Kd with the ranges and units defined in [LINK: SWR-CFG-02].
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-04
STATEMENT: >>>
The controller shall compute the derivative term from the *measurement*, not the error, so that a setpoint step does not produce a derivative kick.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-05
STATEMENT: >>>
The controller shall clamp its integral term and shall suspend integration while the output is saturated (conditional-integration anti-windup).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-06
STATEMENT: >>>
On entering or leaving manual/automatic control the controller shall transfer bumplessly: the output shall not step by more than 1 % as a direct result of the mode change.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-07
STATEMENT: >>>
The system shall convert duty to heater switching by **time-proportional control** over a configurable window of 0.5–30 s (default 2 s).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-08
STATEMENT: >>>
The system shall enforce a configurable minimum on-time and minimum off-time (0–2000 ms, default 100 ms) and shall round a duty that cannot satisfy them to fully off or fully on.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-09
STATEMENT: >>>
The system shall generate the setpoint from the active program by linear interpolation in time, so that the setpoint advances at the segment's ramp rate rather than stepping to the segment target.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-10
STATEMENT: >>>
The system shall support a ramp rate of 1–9999 °C/h, where a configured rate of **0 means "as fast as the kiln allows"** (setpoint follows the segment target directly).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-11
STATEMENT: >>>
The system shall implement **hold-back**: when |SP − PV| exceeds a configurable band (0–200 °C, default 0 disables), the setpoint shall stop advancing and the segment timer shall pause until PV re-enters the band.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-12
STATEMENT: >>>
The system shall treat a dwell segment as complete only after the dwell time has elapsed *and* PV has been within a configurable tolerance band of the target (0.5–50 °C, default 5 °C) for that duration, subject to [LINK: SWR-CTL-11].
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-13
STATEMENT: >>>
The system shall never command heating during a cooling segment; a segment whose target is below the current temperature shall be executed as a passive cooling ramp with the setpoint tracked only as an upper bound.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-14
STATEMENT: >>>
The system shall support a manual mode in which the PID holds a single operator-supplied target temperature.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-15
STATEMENT: >>>
The system shall expose PID internals (P, I, D contributions, error, duty, saturation flag) for diagnostics and logging.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CTL-16
STATEMENT: >>>
The system shall limit the commanded duty to a configurable maximum of 10–100 % (default 100 %), to allow derating an over-powered kiln.
<<<
PRIORITY: C
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-3
TITLE: 3.3 Automatic PID tuning (FR-TUN)

[REQUIREMENT]
UID: SWR-TUN-01
STATEMENT: >>>
The system shall provide an automatic PID tuning procedure that determines Kp, Ki and Kd without operator calculation.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-02
STATEMENT: >>>
Tuning shall use the **relay (Åström–Hägglund) method** [R5]: the controller drives a bounded on/off limit cycle about a tuning setpoint and measures the ultimate gain *Ku* and ultimate period *Tu* from the resulting oscillation.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-03
STATEMENT: >>>
The operator shall specify the tuning setpoint; the system shall reject a setpoint above the configured maximum temperature or below ambient + 50 °C.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-04
STATEMENT: >>>
The relay output shall be bounded by a configurable output amplitude *d* (10–100 % duty, default 50 %) and a configurable hysteresis (0.1–20 °C, default 1 °C).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-05
STATEMENT: >>>
The system shall discard the first oscillation cycle and shall require at least **3** further cycles whose successive periods agree within 15 % and whose amplitudes agree within 20 % before accepting a result.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-06
STATEMENT: >>>
The system shall derive gains using selectable rules, **Ziegler–Nichols** (classic, aggressive) and **Tyreus–Luyben** (conservative, default), and shall present both candidate gain sets to the operator.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-07
STATEMENT: >>>
The system shall abort tuning and enter Fault if any safety requirement in §5 ([LINK: SECT-5]) trips, if no valid oscillation is identified within a configurable timeout (10–480 min, default 120 min), or if the operator cancels.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-08
STATEMENT: >>>
Aborted tuning shall leave the previously stored gains unchanged.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-09
STATEMENT: >>>
The system shall not store tuning results automatically; the operator shall explicitly accept a result before it replaces the active gains.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-TUN-10
STATEMENT: >>>
The system shall report live tuning progress (phase, cycles captured, measured Ku/Tu, elapsed time) and shall record the tuning oscillation in the data log like any other run.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-11
STATEMENT: >>>
The system shall store the provenance of the active gains: manual, or tuned (with rule, Ku, Tu, tuning setpoint and timestamp).
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TUN-12
STATEMENT: >>>
The system shall warn the operator that the kiln must be loaded representatively and the lid closed before tuning, because the identified model includes the load.
<<<
PRIORITY: S
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TUN-13
STATEMENT: >>>
The system shall support storing up to **4** named gain sets (e.g. per firing range) and selecting one per program.
<<<
PRIORITY: C
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-4
TITLE: 3.4 Firing programs (FR-PRG)

[REQUIREMENT]
UID: SWR-PRG-01
STATEMENT: >>>
A firing program shall consist of a name, an optional description, and an ordered list of **1–32 segments**.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-02
STATEMENT: >>>
Each segment shall comprise: target temperature (0–1350 °C), ramp rate (0–9999 °C/h, 0 = maximum), and dwell time (0–5999 min).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-03
STATEMENT: >>>
Each segment shall optionally carry a flag requiring **operator acknowledgement** before the program advances past it (e.g. to crack the lid for venting).
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-04
STATEMENT: >>>
**Withdrawn 2026-10-10.** This required at least 20 programs in non-volatile storage, persisting across power loss and firmware update.

It was the last requirement standing on the authoring path that [LINK: SWR-PRG-07], [LINK: SWR-PRG-08] and [LINK: SWR-PRG-10] were withdrawn with. With nothing on the device able to create or edit a program, the storage held a copy of the three examples that arrive in the image ([LINK: SWR-PRG-09]) and nothing else: persistence of something already persistent, in a medium that wears out, behind a seeding path that could fail on a first boot and a store that could fail to mount.

So the programs are read from the firmware. What that *removes* is worth stating, because this is a deletion that makes the device better rather than smaller:

- A device whose flash will not mount now still has its programs. It used to serve `503` for the list of programs it was carrying in its own image.
- A factory reset ([LINK: SWR-CFG-09]) no longer costs the operator their programs. The partition holds run history, and losing history is what a factory reset is for.
- The first boot has nothing to get wrong. Seeding was idempotent and tested, and it was still a write to flash on every power-on of a brand-new device.

"Persisting across a firmware update" is now trivially true in the only sense left: the programs are part of what the update installs. A user who wants a different curve edits `kiln_core/profile` and builds, which is the cost [LINK: SWR-PRG-09] states plainly.

The 20-slot figure is gone with the requirement. `kiln_core/fileslots` still carries 64 regions and the run index still uses 20 of them ([LINK: SWR-LOG-09]), so the partition is now a third used rather than two thirds. That is recorded in architecture 10.6 and deliberately not acted on: shrinking the partition is a flash-layout change that breaks every device already flashed, to recover space nothing needs.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-05
STATEMENT: >>>
The system shall validate a program on start, rejecting it with a specific reason if: no segments; any target above the configured maximum temperature; any field out of range; total predicted duration above 168 h.

**Still required after [LINK: SWR-PRG-04]'s withdrawal, and the reason is the configured maximum.** The programs are compiled in and therefore trusted as *data*, but `safety.max_temp_c` is set by the operator and can be lowered below a program's peak; validation on start is what refuses that firing rather than running it into a ceiling. A test asserts that every compiled-in example validates against the default maximum, because an example that cannot start is one an operator discovers by selecting it.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-06
STATEMENT: >>>
The system shall compute and present the predicted total duration and the predicted end time of a program before it is started.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-07
STATEMENT: >>>
**Withdrawn 2026-10-09: programs are pre-compiled and are not edited anywhere.** This required creating, reading, updating, renaming, duplicating and deleting programs through the web interface.

Half of it was already gone: [LINK: SWR-WEB-26] made the interface read-only, so nothing over the network could create or change a program. The rest goes with the decision that the set of firing profiles is **fixed at build time** ([LINK: SWR-PRG-09]), which answers `OQ-09` by removing the question rather than by choosing one of the editors it offered.

What that buys, and it is the reason to prefer it: there is no authoring path to secure, no file format to validate, no import to get wrong, and no editor to build on a rotary encoder. What it costs is stated plainly in [LINK: SWR-PRG-09]: a user who wants a curve of their own builds one into the firmware.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-08
STATEMENT: >>>
**Withdrawn 2026-10-09 with [LINK: SWR-PRG-07].** This required exporting and importing a program as a documented JSON file.

Import is authoring by another name, and the set of profiles is fixed at build time. Export has no purpose on its own: what a user would export is already in the source, under version control, readable.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-09
STATEMENT: >>>
The system shall ship with at least **3** example programs (e.g. bisque cone 06, glaze cone 6, glass fusing), compiled into the firmware and read-only.

**These are the only firing programs the device has**, as of the 2026-10-09 decision that withdrew [LINK: SWR-PRG-07], [LINK: SWR-PRG-08] and [LINK: SWR-PRG-10]. A user who wants a different curve adds it here and builds, which is a real cost and is the honest consequence of having no authoring path at all: it puts a compiler between a potter and a firing schedule.

The trade was taken deliberately. Every authoring route costs something this design is not willing to spend: over the network reopens a write path that [LINK: SWR-WEB-26] closed, at the display means editing five segments of target, rate and dwell on a rotary encoder, and an import file is a parser accepting operator-supplied data on the component that commands a heater.
<<<
PRIORITY: S
VERIFICATION: I

[REQUIREMENT]
UID: SWR-PRG-10
STATEMENT: >>>
**Withdrawn 2026-10-09 with [LINK: SWR-PRG-07].** This required editing the remaining segments of a running program while rejecting edits to the current or completed ones.

It was the most delicate requirement in this section, because it asks the run controller to accept a change to the thing it is executing, and it is now moot: there is no editor and no segment to change. [LINK: SWR-RUN-07]'s abort remains the way to stop a firing that is doing the wrong thing.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PRG-11
STATEMENT: >>>
The system shall record, for each run, the program content as executed, so that a later program edit does not invalidate the historical record.
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-5
TITLE: 3.5 Run control (FR-RUN)

[REQUIREMENT]
UID: SWR-RUN-01
STATEMENT: >>>
The system shall implement the state machine of §2.2 ([LINK: SECT-2-2]), and every state transition shall be logged with a timestamp and cause.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-RUN-02
STATEMENT: >>>
The system shall start a program only from Idle, and only after validation ([LINK: SWR-PRG-05]) and a self-check of sensor and output health has passed.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-RUN-03
STATEMENT: >>>
The system shall support pause and resume; on pause, heating shall be disabled and all program timers frozen.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-RUN-04
STATEMENT: >>>
The operator shall be able to abort a run at any time from the local display **and** from the web interface; abort shall de-energise heating within **1 s**.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-RUN-05
STATEMENT: >>>
The system shall expose, while running: state, segment index and count, setpoint, process value, duty, rate of change, elapsed time, time remaining in segment, predicted end time, and hold-back status.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-RUN-06
STATEMENT: >>>
On program completion the system shall disable heating, sound the alarm for a configurable duration (0–600 s, default 4 s), and enter Complete.

**Amended 2026-10-09.** The default was 30 s, which with the completion pattern of [LINK: SWR-SAF-20] is fifteen repetitions of it. A firing that has just finished correctly is good news, and a notification is what it wants rather than half a minute of chirping, so the default is now one burst's worth. The range is unchanged: an operator who wants the kiln to keep saying so until somebody comes can still set it, and 0 silences the completion annunciation without touching the fault one.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-RUN-07
STATEMENT: >>>
The system shall record a **run record** for every run (program executed, gains used, start and end time, end reason, log extent, and the reference heater current established for the run, [LINK: SWR-CUR-08]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-RUN-08
STATEMENT: >>>
On restart after an unexpected power loss during a run, the system shall apply the configured recovery policy: **abort** (default), or **resume** if the outage was shorter than a configurable limit (1–120 min, default 15 min) *and* PV is within a configurable band (5–200 °C, default 50 °C) of the setpoint at the time of interruption.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-RUN-09
STATEMENT: >>>
The system shall persist enough run state at least every **10 s** to support [LINK: SWR-RUN-08], without exceeding the flash endurance budget of [LINK: SWR-NFR-14].
<<<
PRIORITY: M
VERIFICATION: A, T

[REQUIREMENT]
UID: SWR-RUN-10
STATEMENT: >>>
The system shall refuse to start a run while a fault is latched, while autotune is active, or while the enclosure temperature exceeds its limit.
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-6
TITLE: 3.6 Local display and input (FR-HMI)

[REQUIREMENT]
UID: SWR-HMI-01
STATEMENT: >>>
The system shall drive a 128×64 monochrome OLED (SSD1306/SH1106 class) over I²C.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-HMI-02
STATEMENT: >>>
The default screen shall show, simultaneously and unambiguously, the **current chamber temperature** and the **target temperature**.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-HMI-03
STATEMENT: >>>
The current temperature shall be rendered in the largest font on the screen, legible at 2 m.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-HMI-04
STATEMENT: >>>
The default screen shall additionally show: operating state, segment index/count when running, rate of change, elapsed or remaining time, and a progress indication.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-HMI-05
STATEMENT: >>>
The display shall refresh at least **twice per second**, and displayed values shall be no more than **1 s** stale.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-HMI-06
STATEMENT: >>>
The system shall present a fault screen showing the fault code and a human-readable cause, which shall take precedence over all other screens and shall not be dismissible while the fault condition persists.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-HMI-07
STATEMENT: >>>
The system shall display WiFi connection state and the address at which the web interface is reachable (hostname and IP).
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-HMI-08
STATEMENT: >>>
The system shall provide additional screens for: enclosure temperature and PID diagnostics; network details; program selection; and device information (version, uptime, gains).
<<<
PRIORITY: S
VERIFICATION: D

[REQUIREMENT]
UID: SWR-HMI-09
STATEMENT: >>>
The system shall accept input from a rotary encoder with push button, distinguishing rotate, short press and long press (≥400 ms), with debouncing such that no physical detent produces more than one logical event.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-HMI-10
STATEMENT: >>>
The operator shall be able to, from the local input alone: select and start a stored program, pause/resume, abort a run, acknowledge a fault, and read the WiFi address.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-HMI-11
STATEMENT: >>>
Starting a program and aborting a run from the local input shall require a confirmation step.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-HMI-12
STATEMENT: >>>
The system shall support a configurable display dim/blank timeout (0 = never, 10–3600 s) which shall be suspended while a fault is active.
<<<
PRIORITY: C
VERIFICATION: T

[REQUIREMENT]
UID: SWR-HMI-15
STATEMENT: >>>
The local display shall render operator text in the language of `hmi.language` ([LINK: SWR-NFR-23]). Short labels shall fit the display in every language provided; a translation that does not fit is a defect in the translation, not a reason to truncate at runtime.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-HMI-13
STATEMENT: >>>
Temperature shall be displayed in °C or °F according to configuration; all internal computation, storage and API values shall remain in °C.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-HMI-14
STATEMENT: >>>
If the display fails to initialise or stops acknowledging on I²C, the system shall log the fault and continue controlling the kiln.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-HMI-16
STATEMENT: >>>
**The update screen.** When a newer release has been found ([LINK: SWR-UPD-09]), the display shall show that one is available, its version, and whether it is a security release, without displacing a firing screen. Confirming it shall take a deliberate act rather than a single click of the encoder, and the screen shall state plainly that the kiln will restart. While an update is downloading the display shall show progress and shall allow it to be abandoned; afterwards it shall show the result, success or failure with a reason, until acknowledged ([LINK: SWR-UPD-07], [LINK: SWR-UPD-12]).

This screen is the **only** place a firmware update can be authorised ([LINK: SWR-UPD-08]), which makes it part of the security design and not only of the interface.
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-7
TITLE: 3.7 Web interface (FR-WEB)

[REQUIREMENT]
UID: SWR-WEB-01
STATEMENT: >>>
The system shall serve a web interface from an HTTP server on the device itself.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-02
STATEMENT: >>>
All web assets shall be served from the device with **no runtime dependency on any external host** (no CDN, no external fonts, no telemetry).
<<<
PRIORITY: M
VERIFICATION: I, T

[REQUIREMENT]
UID: SWR-WEB-03
STATEMENT: >>>
The interface shall be usable on a 360 px-wide phone screen and on a desktop browser, without horizontal scrolling of the page body.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-WEB-04
STATEMENT: >>>
The interface shall present a live dashboard: state, current temperature, target temperature, duty, rate of change, segment progress, elapsed and remaining time, and active warnings.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-WEB-05
STATEMENT: >>>
Live values shall update at least once per second without a page reload, via a push mechanism (Server-Sent Events or WebSocket) rather than polling.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-06
STATEMENT: >>>
The interface shall plot **logged temperature data** as a time series chart showing at minimum the measured chamber temperature and the setpoint on a common time axis.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-WEB-07
STATEMENT: >>>
The chart shall additionally offer heating duty, heater current and enclosure temperature as toggleable series, on a secondary axis where units differ.
<<<
PRIORITY: S
VERIFICATION: D

[REQUIREMENT]
UID: SWR-WEB-08
STATEMENT: >>>
For a run in progress, the chart shall show the trace so far together with the **planned remainder** of the curve, so that actual and intended firing can be compared at a glance.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-WEB-09
STATEMENT: >>>
The interface shall list completed runs and shall plot the logged data of any selected past run.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-WEB-10
STATEMENT: >>>
The chart shall support zoom and pan over the time axis and shall read out the values at the cursor position.
<<<
PRIORITY: S
VERIFICATION: D

[REQUIREMENT]
UID: SWR-WEB-11
STATEMENT: >>>
The interface shall render a chart of a **24 h run at 10 s resolution (≈8600 points)** within 2 s on a mid-range phone, decimating server-side as needed.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-12
STATEMENT: >>>
The interface shall **display** a stored program as a graph and a segment table, and shall not edit one. Authoring is a local function ([LINK: SWR-WEB-26]); until a local editor exists, programs are the seeded examples of [LINK: SWR-PRG-09]. See [LINK: OQ-09].
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-13
STATEMENT: >>>
~~Client-side validation with server re-validation on save.~~ **Withdrawn 2026-10-06**: there is no save. Program validation remains in `kiln_core/profile` and runs wherever a program is stored.
<<<
PRIORITY: M
VERIFICATION: I
STATUS: Withdrawn

[REQUIREMENT]
UID: SWR-WEB-14
STATEMENT: >>>
The interface shall **not** provide any means of starting, pausing, resuming or aborting a run. Run control is available only at the kiln ([LINK: SWR-WEB-26]). Run *state* shall remain fully readable.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-15
STATEMENT: >>>
The interface shall **not** provide manual heating, nor adjustment of the remaining segments of a running program. Both are available only at the kiln ([LINK: SWR-WEB-26]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-16
STATEMENT: >>>
The interface shall allow **monitoring** an automatic PID tuning run. It shall not start, cancel or accept one: a tuning run drives the kiln through relay oscillation and is a firing by another name ([LINK: SWR-WEB-26]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-17
STATEMENT: >>>
The interface shall **display** all configuration items of [LINK: SWR-CFG-01] with their units, ranges and defaults, and shall not write any of them. The configured maximum temperature and the safety thresholds live here ([LINK: SWR-WEB-26]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-18
STATEMENT: >>>
The interface shall allow downloading a run's log as **CSV** and as **JSON**.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-19
STATEMENT: >>>
The system shall expose a documented JSON/REST API; the web UI shall use only that API, adding no privileged back channel.
<<<
PRIORITY: M
VERIFICATION: I, T

[REQUIREMENT]
UID: SWR-WEB-20
STATEMENT: >>>
The API shall return errors as a JSON object with a machine-readable code and a human-readable message, using conventional HTTP status codes.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-21
STATEMENT: >>>
The system shall serve at least **4** concurrent HTTP clients without the control loop missing a period ([LINK: SWR-NFR-02]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-22
STATEMENT: >>>
Web assets shall be pre-compressed and served with `Content-Encoding: gzip`, and static assets shall carry cache headers keyed to the firmware version.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-23
STATEMENT: >>>
~~Optional password protection of state-changing endpoints.~~ **Withdrawn 2026-10-06.** With the interface read-only there is no state-changing endpoint to protect, and the password could not be set from anywhere in any case: [LINK: SWR-WEB-26] had removed configuration writes and the local interface has no text entry. An authentication gate that can never be armed is worse than none, because it reads as protection.
<<<
PRIORITY: M
VERIFICATION: I
STATUS: Withdrawn

[REQUIREMENT]
UID: SWR-WEB-24
STATEMENT: >>>
The interface shall display a clear, persistent banner whenever a fault is latched or a warning is active.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-WEB-26
STATEMENT: >>>
**The web interface shall be read-only.** No endpoint reachable over the network shall change any device state: not the run, not manual heating, not tuning, not configuration, not a latched fault, not the current-transformer calibration, and not the stored programs. Every request other than `GET` shall return `403` with the code `read_only` and shall name where the control actually is. Everything the interface can do, it can do by reading.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-25
STATEMENT: >>>
The interface shall remain functional with a lost connection, showing stale-data and reconnection state rather than silently displaying old values as current.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-WEB-27
STATEMENT: >>>
The interface shall be operable in light and dark colour schemes following the browser preference.
<<<
PRIORITY: C
VERIFICATION: D

[[/SECTION]]

[[SECTION]]
UID: SECT-3-8
TITLE: 3.8 Data logging (FR-LOG)

[REQUIREMENT]
UID: SWR-LOG-01
STATEMENT: >>>
The system shall log a temperature sample record during every run and during autotune.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-02
STATEMENT: >>>
A sample record shall contain at minimum: timestamp, chamber temperature (raw and filtered), setpoint, heating duty, **heater current**, enclosure temperature, segment index, state, and a flags field.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-03
STATEMENT: >>>
The sample interval shall be configurable from **1 s to 300 s**, default **10 s**.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-04
STATEMENT: >>>
The system shall additionally log an out-of-band record on every state transition, fault, warning, configuration change and operator action.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-05
STATEMENT: >>>
Logs shall be stored **on the device's internal flash**. The system shall not require an SD card and shall not require any external database or network service ([LINK: UR-CON-03]).
<<<
PRIORITY: M
VERIFICATION: I, T

[REQUIREMENT]
UID: SWR-LOG-06
STATEMENT: >>>
Sample logs shall be stored in a fixed-size **circular** store; when full, the oldest data shall be overwritten, and the system shall never fail a run because the log is full.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-07
STATEMENT: >>>
The log store shall retain at least **150 h** of samples at the default 10 s interval.
<<<
PRIORITY: M
VERIFICATION: A, T

[REQUIREMENT]
UID: SWR-LOG-08
STATEMENT: >>>
The log store shall be append-structured so that a power loss can corrupt at most the record being written, and the reader shall detect and skip a torn record.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-09
STATEMENT: >>>
The system shall retain the run records ([LINK: SWR-RUN-07]) of at least the **20** most recent runs, including those whose samples have been overwritten, and shall mark such runs as having truncated data.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-10
STATEMENT: >>>
The system shall expose logged data through the API with selection by run and time range, and with server-side decimation to a caller-specified maximum point count.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-11
STATEMENT: >>>
Decimation shall preserve visible extrema (min/max per bucket), so that a short temperature excursion is not hidden by downsampling.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-12
STATEMENT: >>>
Every record shall carry a monotonic device timestamp; where wall-clock time is known ([LINK: SWR-NET-06]) records shall additionally carry UTC, and records logged before time sync shall be marked as such.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-13
STATEMENT: >>>
The operator shall be able to erase all logs, and shall be warned that the action is irreversible.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-14
STATEMENT: >>>
Logging shall never block the control loop; if the log store is unavailable the system shall continue controlling and raise a warning.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-15
STATEMENT: >>>
The system shall report log store health: used and free capacity, oldest and newest record time, and write error count.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-LOG-16
STATEMENT: >>>
**Security-relevant events shall be recorded, and the recording shall be disableable.** The event log shall record, timestamped and distinguishable from process events:

- a firmware update offered, confirmed, installed, abandoned or refused, with the version and the reason for a refusal ([LINK: SWR-UPD-09], [LINK: SWR-UPD-12]);
- a manifest or an image that failed verification, which is the signature of somebody trying ([LINK: SWR-UPD-11]);
- a rollback, whether the new image failed to confirm itself or was reverted deliberately ([LINK: SWR-UPD-15]);
- every change to configuration, and which interface made it;
- the provisioning access point starting, and a client associating with it;
- a reset whose cause was abnormal ([LINK: SWR-NFR-15]).

The log shall be readable by the operator, shall survive a restart, and the recording of these events shall be **disableable by the owner**: [LINK: UR-REG-004] asks for the opt-out as explicitly as it asks for the log, and a device that logs access to itself regardless of its owner's wishes is a surveillance feature rather than a security one.

It shall contain nothing that the device does not already show: no credential, no key material, no request body. A log that records what an attacker wanted is useful; one that records the WiFi password is a second copy of [LINK: SRR-05].

**Partly implemented 2026-10-10, and the division is deliberate.** Three event codes are added to the persisted log (appended, so the codes every existing log uses keep their meaning), and `log.security_events` is the owner's opt-out, default on because the default has to be the one that helps an owner who has not thought about it. The opt-out is applied in the one place every event passes through, so no emitter can forget it, and it removes **only** the security events: a fault, a state change and the periodic sample are the evidence of what a kiln did, which is a safety record rather than a record of access to the device, and no configuration item switches those off.

What is recorded now: an **abnormal reset cause** (anything but a power-on, a requested restart, an external reset or a wake from sleep -- a cause the adapter could not identify counts as abnormal, because a reset nobody can account for is exactly what a log should carry); a **factory reset** ([LINK: SWR-CFG-09]), logged last so that it is the first entry of the new owner's log and explains why the rest is missing; a **network join commanded at the display**, without the SSID, since a log that records which network a kiln joined is a record of where it lives; and **every configuration change**, which the log already carried.

What is **not** recorded, and why it waits: the update-path events this requirement lists -- an offer, a confirmation, an install, a refusal with its version and reason, a failed signature check, a rollback -- need a version string and a reason, and neither fits a 20 byte record ([LINK: SWA-18]). They arrive with the update path itself (tasklist H2), which will need either a second record type or its own channel. Adding codes now that could carry no detail would have looked like progress and recorded nothing.

Two items this exposed are fixed with it. "Which interface made it" has one answer today, the display, because [LINK: SWR-WEB-26] left no other writer; when that stops being true the field has to be carried rather than assumed. And a record appended **outside a run** used to be lost: it went into a sector with no header, which `iterate` skips and the next run erases, so the first security event of this kind would have been written, stored, counted and never read. The ring now claims a sector lazily, tagged run 0 for "not part of a run".
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-9
TITLE: 3.9 Configuration (FR-CFG)

[REQUIREMENT]
UID: SWR-CFG-01
STATEMENT: >>>
The system shall hold all tunable parameters in a single versioned configuration structure in non-volatile storage, each item having a type, unit, range and default.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CFG-02
STATEMENT: >>>
The configuration shall include at minimum: **safety**: maximum chamber temperature, maximum enclosure temperature, runaway detection parameters, power-loss recovery policy; **control**: Kp, Ki, Kd, loop period, PWM window, minimum on/off time, maximum duty, hold-back band, dwell tolerance; **sensing**: the *enclosure* TC type, line filter frequency, filter time constant, calibration offset and gain for both channels (there is no chamber TC type: [LINK: SWR-ACQ-02] fixes it at K and schema 2 removed the item, because a setting that is offered and ignored is worse than one that is absent); **tuning**: amplitude, hysteresis, rule, timeout; **current**: CT ratio and output type, nominal heater current, mains voltage, fail-on and fail-off thresholds and settle times, deviation bands, over-current limit, relay life limits, monitoring enable; **logging**: sample interval; **HMI**: units, dim timeout, alarm duration; **network**: WiFi credentials, hostname, NTP server, timezone, there being no mode to choose and no access point since [LINK: SWR-NET-11]; **security**: none, since [LINK: SWR-WEB-26] left nothing reachable over the network to authenticate.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-CFG-03
STATEMENT: >>>
The system shall validate every configuration write against its declared range and shall reject the whole write atomically if any item is invalid.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CFG-04
STATEMENT: >>>
The system shall apply a configuration change without a reboot wherever physically possible, and shall clearly mark items that require a reboot.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CFG-05
STATEMENT: >>>
On reading a configuration written by an older firmware version, the system shall migrate it, filling new items with defaults; on reading an unreadable or corrupt configuration it shall fall back to defaults and raise a warning.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CFG-06
STATEMENT: >>>
The system shall support restoring all configuration to defaults, and shall support exporting and importing configuration as JSON (excluding secrets).
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CFG-07
STATEMENT: >>>
The system shall never return stored passwords or passphrases through the API; it shall return only whether a secret is set.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CFG-08
STATEMENT: >>>
The system shall reject changes to safety-relevant configuration while a run is in progress.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CFG-09
STATEMENT: >>>
**The owner shall be able to erase everything, from the device itself.** A factory reset reachable from the local display shall permanently remove the configuration, the WiFi and access point credentials, the stored programs, the run records, the sample log and the wear counters. It shall leave the production data block of [LINK: SWR-PROD-01] and the firmware alone: those identify the unit for its whole life and are not the owner's data.

It shall require a deliberate confirmation of the same kind as a firmware install ([LINK: SWR-HMI-16]), shall be refused while a run or an autotune is in progress, and shall report what it erased rather than only that it finished.

**Erasure means gone, not unreferenced.** A flash region holding a credential shall be erased or overwritten, not merely delisted, and the test for this requirement shall read the raw partition back and look for the secret rather than asking the API whether it is still configured.

This is the requirement that turns [LINK: SRR-05]'s disposal obligation from a line in a manual into a function of the product, which is how [LINK: UR-REG-004]'s requirement to permanently remove all data and settings is met. Until it exists, the only honest instruction is "erase the flash with a cable before you sell it", and most owners will not.

**Implemented 2026-10-10.** `kiln_app_factory_reset` is reachable from the last entry of the display's menu, behind the same confirmation an abort uses and defaulting to "no". It erases the configuration and the WiFi credentials inside it, the latched fault, every run record, the sample log and the wear counters; it restarts the run numbering, because a kiln whose first firing is number 94 tells its new owner something false; and it leaves the production data block and the firmware alone. Refused while running, paused or autotuning. It reports counts rather than only success, and does as much as it can rather than stopping at the first failure, because a reset that gave up half way would leave an owner with some of their data erased and no idea which.

**What the test had to establish, and how.** The credential is overwritten with zeros and committed *before* the key is erased, since an NVS erase delists an entry and leaves its bytes in the page until a garbage collection that may never come. Proving that needed the host key/value fake to stop being kinder than the medium: it used to clear a whole entry on erase and to reuse the delisted slot on the next write, either of which made "the secret is gone" pass with no implementation behind it. It now delists and keeps the bytes, as NVS does, with collection available only when a test asks for it. With the overwrite removed from the implementation, the test fails; with it restored, it passes. That experiment is the evidence this requirement asked for.
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-10
TITLE: 3.10 Connectivity and time (FR-NET)

[REQUIREMENT]
UID: SWR-NET-01
STATEMENT: >>>
The system shall connect to a WiFi network as a station using stored credentials.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-02
STATEMENT: >>>
**Withdrawn 2026-10-09. The system shall raise no access point.** This required a provisioning AP and a page served on it whenever no credentials were stored or the station failed to join for a configurable period.

It is replaced by [LINK: SWR-NET-11] and [LINK: SWR-NET-12], which put network setup on the local display. The reasoning is the same one behind [LINK: SWR-WEB-26]: an access point is a second radio anybody within range can reach, with a second passphrase to get wrong, serving a page whose entire purpose is to accept credentials. The display and the encoder are already fitted, the operator is already standing at them, and what can be done there cannot be done by a passer-by at all.

The device therefore has exactly one radio role, station, and a kiln whose network has changed is told the new one at the kiln. It keeps firing meanwhile, which [LINK: SWR-NET-07] requires regardless.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-NET-03
STATEMENT: >>>
The system shall retry the station connection with exponential backoff indefinitely, without interfering with control or safety functions.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-04
STATEMENT: >>>
The system shall advertise itself over mDNS under a configurable hostname (default `kiln`), so the interface is reachable as `kiln.local`.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-05
STATEMENT: >>>
**Withdrawn 2026-10-09 with [LINK: SWR-NET-02].** This required the access point's passphrase to be at least 8 characters with a device-unique default derived from the MAC.

There is no access point, so there is no second passphrase: `net.ap_ssid` and `net.ap_pass` are removed from the configuration schema. The eight-character rule survives where it still applies, as the minimum this device will accept when **joining** a WPA network ([LINK: SWR-NET-12]), which is the standard's own bound rather than this project's.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-NET-06
STATEMENT: >>>
The system shall synchronise wall-clock time by SNTP when a route to the internet exists, and shall apply a configurable timezone with daylight-saving rules.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-07
STATEMENT: >>>
Loss of WiFi, of the internet, or of time sync shall not interrupt, pause or otherwise alter a running firing.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-08
STATEMENT: >>>
The system shall maintain a monotonic time base for all control, safety and log timing that is unaffected by wall-clock adjustments.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-09
STATEMENT: >>>
The system shall expose WiFi diagnostics: mode, SSID, IP, RSSI, uptime, disconnect count, and last disconnect reason.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-10
STATEMENT: >>>
The system shall support optional remote logging of events to a syslog server over UDP.
<<<
PRIORITY: C
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-11
STATEMENT: >>>
**The device shall scan for networks and show what it found on the local display.** The scan shall be startable from the network screen, shall not block the display while it runs, and shall report the networks strongest first with, for each: the SSID, and whether it is secured.

Three properties that are requirements rather than implementation detail:

- **"Scanning" and "none found" shall be distinguishable.** They are different instructions to the operator, and a scan takes seconds.
- **A scan shall be allowed while a firing runs.** It is receive-only and changes nothing; [LINK: SWR-NET-07] already forbids the network from altering a run, and an operator whose WiFi dropped mid-firing should not have to abort to fix it.
- **An SSID too long for the line shall be shown as truncated** rather than silently cut, because picking the wrong one of two similar names is the failure this screen exists to avoid.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NET-12
STATEMENT: >>>
**The operator shall be able to join a network entirely from the local display**, selecting it from the scan of [LINK: SWR-NET-11] and entering its passphrase on the rotary encoder. This is the **only** way the device is given network credentials: no access point, and no route over the network itself ([LINK: SWR-WEB-26]).

What the entry has to provide, each because its absence makes a network unjoinable:

- **Every printable ASCII character**, since a passphrase this cannot type is a network this kiln cannot join and there is no fallback to correct it from.
- **Deletion**, and deleting past the start shall not underflow.
- **Abandoning entry shall discard what was typed**, rather than leaving half a passphrase for the next attempt.
- **A passphrase shorter than 8 characters shall not be offered to the radio.** WPA-PSK cannot be shorter, and spending a join attempt to discover that costs the operator thirty seconds and tells them nothing.
- **An open network shall not ask for a passphrase at all.**

The credentials shall be **persisted before the join is attempted**, so that a device which joins successfully and then loses power comes back to the same network rather than to a display nobody is standing at.

**Added 2026-10-09.** The display shall also show **the outcome of the last attempt**, distinguishing a join in progress from one the radio refused, and shall show the refusal's reason code. "Not connected" is not an answer an operator can act on, and since this screen is the only route in, acting on it is the whole job: a mistyped passphrase, an SSID out of range and a radio that never came up are three different remedies and were previously one message. The reason code is shown as the number the driver reports, to be read out to somebody who can look it up, rather than translated into a sentence that guesses which of them it was.

A knob is a poor keyboard, so entry shall **resume at the character the previous press selected** rather than returning to the start of the set.
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-11
TITLE: 3.11 Firmware update (FR-UPD)

[REQUIREMENT]
UID: SWR-UPD-01
STATEMENT: >>>
The system shall **not** accept a firmware image pushed to it over the network ([LINK: SWR-WEB-26]): an inbound update route is total and persistent control of the heater, and the web interface is an observation surface. Instead the system shall **fetch** images itself from the manufacturer's update service ([LINK: SWR-UPD-09]) and shall install one only after a confirmation given at the local display ([LINK: SWR-UPD-12]).

The **direction** is the whole design, and it is what [LINK: OQ-08] resolved: nothing on the network can offer this device an image, and nothing on the network can make it take one. The web interface stays read-only ([LINK: SWR-WEB-26]) with no exception carved into it, and the device gains a field update path without gaining an inbound one.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-UPD-02
STATEMENT: >>>
The system shall use dual OTA application partitions and shall fall back to the previous firmware if the new image fails to confirm itself as bootable.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-03
STATEMENT: >>>
The system shall verify the integrity of an uploaded image before marking it bootable, and shall reject an image that is not a valid application for this target.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-04
STATEMENT: >>>
The system shall refuse a firmware update while a run or autotune is in progress.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-05
STATEMENT: >>>
A firmware update shall preserve configuration, stored programs and run records; loss of sample log data across an update is acceptable if the log partition layout changes, and shall be stated in release notes.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-06
STATEMENT: >>>
The system shall report the running firmware version, build time, git revision and target in the interface and via the API. The version shall follow **semantic versioning** and shall be derived by the build from the release tag rather than maintained by hand, so that it cannot disagree with the tag it was built from. A build that is not on a release tag shall remain a valid semantic version and shall say so, by carrying the commit count and revision as build metadata.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-07
STATEMENT: >>>
The system shall report update progress and a clear success or failure result.
<<<
PRIORITY: S
VERIFICATION: D

[REQUIREMENT]
UID: SWR-UPD-08
STATEMENT: >>>
No client on the network, authenticated or otherwise, shall be able to initiate, offer, authorise, postpone or cancel a firmware update ([LINK: SWR-UPD-01], [LINK: SWR-WEB-26]). The device initiates its own check ([LINK: SWR-UPD-09]) and the operator standing at the display authorises the install ([LINK: SWR-UPD-12]). There shall be no route to either over HTTP, and in particular no `POST /api/ota`.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-09
STATEMENT: >>>
**The update check.** The system shall look for a newer release by fetching a **static manifest** over HTTPS from the manufacturer's update service, whose default host is `update.bitcrushtesting.com`. The check shall:

- run at most once per 24 hours, at a random offset within the day, and not before the network and the wall clock are available;
- be enabled by default, disableable from the local display (`update.check_enabled`), and point at a configurable URL (`update.url`) so that a site may mirror the service rather than reach it directly;
- never block, delay or fault anything. A failed check is a **diagnostic**, not an error: a device on a network with no route to the internet shall remain fully functional and shall say that its last check failed, not that it has a fault.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-10
STATEMENT: >>>
**The check shall reveal nothing about the device.** It shall carry no serial number, no installed version, no configuration, no usage data, no identifier of any kind and no query parameters. The manifest shall be a static file, byte-identical for every device, and the comparison against the running version shall happen **on the device**. What the request discloses is what any HTTPS GET discloses: an address and a time ([LINK: SWR-NFR-21]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-11
STATEMENT: >>>
**Authenticity, and what it does not rest on.** The manifest shall carry a signature made with an **offline** key, verified on the device against a public key compiled into the image. A manifest whose signature does not verify shall be discarded without being parsed further and without being shown to the operator. The image a valid manifest names shall be verified against the digest in that manifest **and** against its own appended image signature before it is marked bootable ([LINK: SWR-UPD-03]), on a secure-boot unit and equally on one that was never provisioned.

Transport security shall be HTTPS with certificate validation, and shall deliberately **not** be the thing the design depends on: an attacker who defeats TLS, spoofs DNS or takes over the service still cannot produce a manifest or an image that verifies, and the worst they achieve is silence.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-12
STATEMENT: >>>
**Local confirmation, and no automatic install.** An available update shall be announced on the local display ([LINK: SWR-HMI-16]) and shall be installed **only** after an explicit confirmation given at the device. The system shall never install an update by itself, on any schedule, for any severity.

The announcement shall not displace a firing screen; the confirmation shall be refused while a run or an autotune is in progress ([LINK: SWR-UPD-04]); and the restart that puts the new image into service shall be a separate act, equally local. The reason this is not the automatic default-on installation that a general consumer product would be expected to provide is safety rather than preference: this device switches kilowatts into a kiln, and an unattended reboot into untried firmware while a load is inside it is not an acceptable trade for promptness.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-13
STATEMENT: >>>
**No downgrade from the service.** The system shall refuse an image whose version is not strictly greater than the running version, and shall refuse one whose target is not this target. A deliberate downgrade shall remain possible over the local path of [LINK: SWR-UPD-14] and shall not be reachable through the update service, so that a replayed or rolled-back manifest cannot return a unit to a version whose vulnerability is known.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-14
STATEMENT: >>>
**The local path stays, as the recovery path.** A firmware update over USB shall remain available for a device whose update service is unreachable, whose new image will not confirm itself, or which has to be downgraded deliberately. It shall require physical access, shall preserve the `nvs`, `kilnfs`, `kilnlog` and `prod` partitions, and shall be a documented procedure carried out by a tool rather than hand-typed commands, because the mistake it invites, erasing the production data block, is not recoverable in the field.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-UPD-15
STATEMENT: >>>
**A new image shall earn its rollback cancellation.** An image booted for the first time shall cancel the rollback of [LINK: SWR-UPD-02] only after it has demonstrated, in the running system, that the supervisor link is delivering valid frames, that both chamber thermocouples read plausibly ([LINK: SWR-SAF-37]), that the configuration and the stored programs are readable, and that the display is alive. Until then it shall remain pending-verify, so that any reset returns the previous image to service. Cancelling the rollback during start-up, before any of this is known, shall be treated as a defect and not as an implementation choice.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-UPD-16
STATEMENT: >>>
**Security releases, separately.** A security fix shall be released separately from functional change where that is technically feasible, shall be marked as a security release in the manifest, and shall be accompanied by an advisory that says what it fixes. The **support period** over which such releases are provided shall be declared in the documentation and shall be at least five years from placing on the market ([LINK: UR-REG-004]), the expected service life of a kiln controller being considerably longer than that floor.
<<<
PRIORITY: M
VERIFICATION: I

[[/SECTION]]

[[SECTION]]
UID: SECT-3-12
TITLE: 3.12 Heater current measurement (FR-CUR)

[TEXT]
STATEMENT: >>>
> Measuring the current actually flowing in the heating elements turns three
> safety detections from slow thermal *inferences* into fast electrical *facts*.
> [LINK: SWR-SAF-07] needs 15 minutes of missing temperature
> rise to conclude the elements are not heating; a current measurement says so in
> one switching window.
<<<

[REQUIREMENT]
UID: SWR-CUR-01
STATEMENT: >>>
The system shall measure the current in the heater circuit using a current transformer (Stromwandler) fitted around one heater conductor, downstream of both the safety contactor and the SSR, so that the measurement reflects current actually reaching the elements.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-02
STATEMENT: >>>
The system shall measure true RMS current over a configurable nominal range of **0–60 A**, with a resolution of **0.1 A** and an accuracy of **±3 % of reading or ±0.3 A, whichever is greater**, after calibration.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-03
STATEMENT: >>>
RMS shall be computed from samples taken at **≥ 1 kHz** over a whole number of mains cycles, so that the result is independent of sampling phase.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-04
STATEMENT: >>>
Measurement shall be **gated to the commanded output state**: the system shall measure conduction current only within a commanded-on interval and leakage current only within a commanded-off interval, in each case after a configurable settle delay (0–200 ms, default 20 ms) that allows for zero-cross turn-on and CT settling.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-05
STATEMENT: >>>
The system shall not attempt a conduction measurement when the commanded on-interval is shorter than the settle delay plus one full mains cycle; such windows shall be skipped rather than reported as zero current.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-06
STATEMENT: >>>
The system shall apply a configurable CT ratio, a gain calibration of 0.50–2.00 and a zero offset, and shall support a one-point calibration against a known load or reference meter.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-07
STATEMENT: >>>
The system shall derive and expose apparent power and cumulative energy per run from the measured current and a configured mains voltage, stating that a resistive load is assumed.

**Apparent power, and it stays apparent. Closed 2026-10-10 (tasklist I3).** Real power would need a voltage channel: a mains-referenced measurement with its own isolation, its own calibration and its own creepage distances on a board that currently touches mains in exactly one place. The design does not have one and should not grow one for this.

What the assumption costs is small and worth stating rather than leaving implied. A kiln element is very nearly a pure resistance ([LINK: SYS-ASM-09]), so the power factor is within a percent or two of unity and apparent power is real power to better than the accuracy of the configured mains voltage, which an installer types in and which varies by more than that over a day. The number is for an operator asking "what does a firing cost" and for [LINK: SWR-SAF-12]'s energy comparison between firings, and both are served by a figure whose *relative* accuracy between runs is what matters.

Where it would be wrong is a load this controller is not for: phase-angle control, which [LINK: SYS-ASM-03] excludes in favour of zero-cross switching, or an inductive load, which an element is not. Both are out of scope rather than unhandled.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-08
STATEMENT: >>>
On each run the system shall establish a **reference current**: the median conduction current measured while the elements are cold and fully on, recorded in the run record ([LINK: SWR-RUN-07]) and used as the baseline for [LINK: SWR-SAF-28].
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-09
STATEMENT: >>>
The system shall log heater current in every sample record ([LINK: SWR-LOG-02]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-10
STATEMENT: >>>
The system shall present heater current live in the web interface, as a chart series, and on a local diagnostics screen.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-CUR-11
STATEMENT: >>>
The system shall detect an absent, disconnected or shorted current transformer, distinguishing it from a genuine zero-current reading by the absence of any signal at all including noise floor.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-12
STATEMENT: >>>
The system shall refuse to start a run when current monitoring is unavailable, **unless** current monitoring has been explicitly disabled in configuration; while it is disabled the system shall raise a persistent warning and shall rely solely on the thermal detections of [LINK: SWR-SAF-07] and [LINK: SWR-SAF-08].
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-13
STATEMENT: >>>
The system shall count and persist the number of switching operations of the contactor and of each SSR, for the wear warning of [LINK: SWR-SAF-30].
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-CUR-14
STATEMENT: >>>
Current measurement shall not delay or block the control or safety cycles ([LINK: SWR-NFR-02]).
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-3-13
TITLE: 3.13 Device identity (FR-PROD)

[TEXT]
STATEMENT: >>>
> Two kinds of identity, kept apart on purpose.
>
> The **firmware** version answers "what is running on this unit", changes with
> every release, and is derived from the release tag by the build so that no
> human has to remember to update it.
>
> The **unit** identity answers "which unit is this", is written once at
> manufacture and never again, and must survive everything the firmware is
> allowed to do to its own storage, including the configuration erase that
> [LINK: SWR-CFG-05] permits on an NVS format change.
>
> A support conversation needs both, which is why they are reported together.
<<<

[REQUIREMENT]
UID: SWR-PROD-01
STATEMENT: >>>
The device shall carry a **production data block** in non-volatile storage containing the manufacturer, the device model, the board revision, the serial number and the production date. It shall be held in a storage partition separate from the one holding operator configuration, so that erasing or reformatting configuration storage cannot destroy it.
<<<
PRIORITY: M
VERIFICATION: T, I

[REQUIREMENT]
UID: SWR-PROD-02
STATEMENT: >>>
The firmware shall read the production data block **read-only**. No firmware function, local or remote, shall write, modify or erase it; the only writer shall be a production tool acting over a programming interface at manufacture.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-PROD-03
STATEMENT: >>>
The production data block shall be reported in the device information API alongside the firmware version of [LINK: SWR-UPD-06], and shown in the web interface.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PROD-04
STATEMENT: >>>
A device whose production data block is absent or incomplete shall boot and operate normally, and shall report its identity as **unprogrammed** rather than reporting partial or invented values. Incompleteness shall be treated as absence: a block missing any required field shall not be reported as programmed.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-PROD-05
STATEMENT: >>>
A tool shall be provided that creates the production data block and writes it to a device, validating every field before writing, and taking the target storage offset from the firmware's own partition table rather than from a separately maintained constant.
<<<
PRIORITY: M
VERIFICATION: T, D

[[/SECTION]]

[[/SECTION]]

[[SECTION]]
UID: SECT-4
TITLE: 4. Non-functional requirements

[REQUIREMENT]
UID: SWR-NFR-01
STATEMENT: >>>
The temperature control loop shall execute at its configured period with a jitter not exceeding **±5 %** of the period, under all supported load conditions including active web clients, OTA-idle, and WiFi reconnection.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-02
STATEMENT: >>>
No non-safety activity (HTTP serving, log writing, display update, WiFi management) shall be able to delay a control or safety cycle by more than **50 ms**.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-03
STATEMENT: >>>
The safety supervisor shall evaluate its conditions at least **4 times per second**.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-04
STATEMENT: >>>
Heating shall be de-energised within **500 ms** of a safety condition being detectable, and the contactor shall open within **1 s**.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-05
STATEMENT: >>>
The system shall control temperature to within **±5 °C** of setpoint during a dwell, on a kiln whose PID has been tuned by the procedure of FR-TUN ([LINK: SECT-3-3]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-06
STATEMENT: >>>
The system shall follow a ramp within **±15 °C** of the commanded setpoint, given a ramp rate the kiln is physically capable of.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-07
STATEMENT: >>>
Steady-state offset during dwell shall be less than **2 °C** after settling.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-08
STATEMENT: >>>
Temperature overshoot after a ramp-to-dwell transition shall not exceed **10 °C** with Tyreus–Luyben gains.
<<<
PRIORITY: S
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-09
STATEMENT: >>>
The firmware shall boot to a state where temperature is measured and heating is safely off within **3 s** of reset.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-10
STATEMENT: >>>
The system shall operate unattended for a **168 h** continuous run without restart, memory exhaustion, or degradation of loop timing.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-11
STATEMENT: >>>
The system shall show no net growth in free heap over a 24 h soak with an active web client, beyond a documented allocator noise band.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-12
STATEMENT: >>>
Static RAM plus peak dynamic allocation shall leave at least **48 kB** of free internal heap at all times.
<<<
PRIORITY: M
VERIFICATION: A, T

[REQUIREMENT]
UID: SWR-NFR-13
STATEMENT: >>>
The application image shall fit an OTA partition of **2 MB**; the design shall target ≤ **8 MB** total flash and shall not require PSRAM.
<<<
PRIORITY: M
VERIFICATION: A

[REQUIREMENT]
UID: SWR-NFR-14
STATEMENT: >>>
Flash write patterns shall keep every erase block below **50 000** erase cycles over a 10-year life at the default configuration, assuming 100 000-cycle endurance.
<<<
PRIORITY: M
VERIFICATION: A

[REQUIREMENT]
UID: SWR-NFR-15
STATEMENT: >>>
A watchdog reset, brownout or panic shall leave heating de-energised and shall be recorded in non-volatile storage with the reset cause.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-16
STATEMENT: >>>
The system shall recover from any unexpected reset into a defined state within [LINK: SWR-NFR-09], applying the recovery policy of [LINK: SWR-RUN-08].
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-17
STATEMENT: >>>
Every error path shall be handled explicitly; an unchecked failing call in control, safety or storage code shall be treated as a defect.
<<<
PRIORITY: M
VERIFICATION: A, I

[REQUIREMENT]
UID: SWR-NFR-18
STATEMENT: >>>
All source files shall carry an SPDX licence identifier of `GPL-3.0-or-later`, and the distribution shall include the full licence text and third-party notices.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-NFR-19
STATEMENT: >>>
The HTTP server shall treat every request body and parameter as untrusted: bounded lengths, no unbounded allocation, no format-string or path-traversal exposure. Authentication shall use a constant-time comparison and shall rate-limit failed attempts.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-20
STATEMENT: >>>
The device is designed for a **trusted local network**. It shall accept **no inbound connection** from outside that network, it shall not be exposed directly to the internet, and the documentation shall state this. The one connection it originates outwards is the update check of [LINK: SWR-UPD-09], which carries no information about the device ([LINK: SWR-UPD-10]), which can be turned off at the display, and whose absence costs nothing but the check itself.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-NFR-21
STATEMENT: >>>
The system shall not transmit any data to any third party. The update check of [LINK: SWR-UPD-09] is to the **manufacturer's own** service, carries no information about the device ([LINK: SWR-UPD-10]) and is disableable; beyond the three exceptions named below, no outbound connection shall exist, and there shall be no telemetry and no analytics on any route.

Three exceptions, named here rather than discovered later:

1. The **update check** of [LINK: SWR-UPD-09], to the manufacturer's own service, carrying nothing about the device.
2. The **SNTP client** behind `port_clock`, which contacts a time server and therefore a third party. It transmits nothing about the device but does reveal that the device exists. Its server shall be configurable and its default shall be stated in the documentation.
3. The **syslog destination** of [LINK: SWR-NET-10], which is off unless the owner sets it and then points at the owner's own server. It is the owner's data going to the owner's host, which is not a third party in any sense that matters, but it crosses the network in cleartext over UDP and the documentation shall say so.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-NFR-22
STATEMENT: >>>
The system shall have no hardcoded credentials, no default-enabled remote access other than the documented local interface, and no undocumented service ports.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-NFR-23
STATEMENT: >>>
Operator-facing text shall be held in a **single resource location**, indexed by language, with no text embedded at its point of use. **English and German** shall both be provided, selected by the `hmi.language` configuration item and offered on the local display and in the web interface. A language with no entry for a string shall fall back to English rather than showing nothing. Diagnostic output, the event log and requirement identifiers shall remain English regardless of the setting, so that a fault quoted in a report reads the same whoever filed it.

**Clarified 2026-10-09, after "no text embedded at its point of use" was found to be half true.** Faults and warnings were in a table from the start; the display's own frame -- screen titles, the menu, the two answers to a confirmation, the footers that say what the knob does -- was string literals at their draw sites, so a device set to German announced its faults in German inside an English frame. There are now two tables, `kiln_core/faults` for what has gone wrong and `kiln_hmi/strings` for the display's own words, and no operator-facing literal remains at a draw site.

Two constraints on the German, both from the panel rather than from the language, and both asserted rather than reviewed:

- **The 5x7 font carries the 95 printable ASCII glyphs and nothing else**, so German text is transliterated (AE, OE, UE, SS). A byte outside 0x20 to 0x7E reaches the panel as a blank, which nobody would see until the device was in a workshop.
- **21 characters is the display's width** at scale 1, past which the framebuffer clips silently. German runs about 15 per cent longer than English, so this is the bound the translation is written against rather than something to discover on hardware.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-24
STATEMENT: >>>
The system shall log internally at selectable verbosity, and production builds shall not emit debug output on the pins used by any peripheral.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-NFR-25
STATEMENT: >>>
Code shall build warning-free with `-Wall -Wextra -Werror` and shall pass the project's static analysis configuration.
<<<
PRIORITY: M
VERIFICATION: A

[REQUIREMENT]
UID: SWR-NFR-26
STATEMENT: >>>
Documentation shall cover: assembly and wiring, mains safety, commissioning, autotuning, program authoring, the REST API, the log record format, and current-transformer fitting and calibration.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-NFR-27
STATEMENT: >>>
Uncommanded heater current ([LINK: SWR-SAF-25]) shall de-energise heating within **1 s** of the offending measurement window, and the weld discrimination of [LINK: SWR-SAF-27] shall reach its verdict within a further **3 s**.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-NFR-28
STATEMENT: >>>
**The build shall emit a machine-readable bill of materials.** A release build shall produce an SBOM in **CycloneDX 1.6 JSON**, and shall be able to produce the same inventory as **SPDX 2.3 JSON**, naming at least the top-level dependencies with their versions and licences: ESP-IDF and every component actually linked, mbedTLS by its own version, the toolchain, the browser assets, and this project itself. It shall be **generated by the build** rather than maintained by hand, because a hand-written inventory of dependencies is wrong within one release of being written and wrong by omission, and it shall be published with the release artefacts and kept for the whole support period ([LINK: SWR-UPD-16]).

Three properties the generator shall have, each of which is a way this requirement is otherwise met in name only:

- **The component list comes from the build**, specifically from the artefact the build writes naming what it linked, and not from a list maintained in the generator.
- **A licence is scanned from the component's own sources**, from the `SPDX-License-Identifier` tags the vendor put there, and a component that carries none shall be reported as `NOASSERTION` rather than given a plausible default. A scan is evidence, not a legal conclusion, and the difference shall survive into the document.
- **The same build shall produce the same bytes.** Components sorted, the serial number derived from the inventory rather than generated randomly, and the timestamp overridable, so that a diff between two SBOMs shows the product changing rather than the clock.

Two things worth recording because they are **not** what a reader expects. The browser assets are **first-party**: there is no vendored third-party JavaScript, which resolves `OQ-04`, and the SBOM states that with file digests rather than by saying nothing. And the independent safety supervisor links no third-party source at all, its register definitions being generated from ST's own SVD ([LINK: SWA-22]).

This exists because [LINK: UR-REG-004] requires it, and because the question it answers, "is this unit affected by the advisory published this morning", cannot be answered after the fact by a project that did not record what it shipped.
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-5
TITLE: 5. Safety requirements

[TEXT]
STATEMENT: >>>
> A kiln is a multi-kilowatt mains-powered heater that reaches temperatures at
> which its own wiring, the enclosure and the building are at risk. The
> requirements in this section are the reason this project exists in the form it
> does, and take precedence over every functional requirement. They are all
> mandatory.
<<<

[[SECTION]]
UID: SECT-5-1
TITLE: 5.1 Safety principles

[[/SECTION]]

[[SECTION]]
UID: SECT-5-2
TITLE: 5.2 Detection requirements

[TEXT]
STATEMENT: >>>
> **Defence in depth.** The current-based rules ([LINK: SWR-SAF-25]–[LINK: SWR-SAF-30])
> are the *primary* detection of a failed relay, contactor or element, because
> they are fast and unambiguous. The thermal rules ([LINK: SWR-SAF-07],
> [LINK: SWR-SAF-08]) are **retained unchanged** as an
> independent backstop: they use a different sensor and a different physical
> principle, so they still cover the case where the current transformer itself
> has failed or been left unfitted ([LINK: SWR-CUR-12]).
> Neither may be removed on the grounds that the other exists.
<<<

[REQUIREMENT]
UID: SWR-SAF-04
STATEMENT: >>>
**Thermocouple failure.** The system shall detect open circuit, short circuit, out-of-range reading, cold-junction fault, and front-end communication failure. A fault persisting beyond the grace period of [LINK: SWR-ACQ-12] shall de-energise heating and latch a fault.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-05
STATEMENT: >>>
**Reversed thermocouple.** The system shall detect a thermocouple connected with reversed polarity, indicated by the reading falling while heating is commanded at high duty, and shall latch a fault.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-06
STATEMENT: >>>
**Stuck sensor.** The system shall detect a reading that does not change by more than a configurable threshold (default 2 °C) while heating is commanded above a configurable duty (default 50 %) for a configurable period (default 10 min), and shall latch a fault.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-07
STATEMENT: >>>
**Thermal runaway / heating failure.** The system shall latch a fault if heating is commanded above a configurable duty (default 80 %) for longer than a configurable period (default 15 min) while the measured rate of rise remains below a configurable threshold (default 10 °C/h). This covers a failed element, an open contactor, an open safety chain and an open kiln lid.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-08
STATEMENT: >>>
**Shorted SSR / uncommanded heating.** The system shall latch a fault, open the contactor and alarm if the temperature rises by more than a configurable threshold (default 5 °C) over a configurable period (default 3 min) while commanded duty is zero.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-09
STATEMENT: >>>
**Over-temperature.** The system shall de-energise heating whenever the chamber temperature exceeds the configured maximum chamber temperature, and shall latch a fault if it exceeds it by a configurable margin (default 10 °C).
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-10
STATEMENT: >>>
**Setpoint excursion.** The system shall latch a fault if PV exceeds SP by more than a configurable band (default 50 °C) for longer than a configurable period (default 2 min).
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-11
STATEMENT: >>>
**Enclosure over-temperature.** The system shall latch a fault if the enclosure/electronics temperature exceeds the configured maximum (default 70 °C), protecting the controller and its wiring.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-12
STATEMENT: >>>
**Insulation degradation.** The system shall record, per firing, the heating energy (duty × time) required to reach reference temperatures, and shall raise a warning when it exceeds the established baseline by a configurable factor (default 1.3), indicating failing insulation or ageing elements.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-13
STATEMENT: >>>
**Loss of control.** The system shall latch a fault if the control loop fails to complete a cycle within twice its configured period, or if the safety supervisor fails to run within its deadline.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-14
STATEMENT: >>>
**Watchdog.** The system shall enable the hardware watchdog and a per-task watchdog covering the control and safety tasks; a watchdog expiry shall de-energise heating through the mechanism of [LINK: SYS-SAF-02] and reset the device.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-15
STATEMENT: >>>
**Brownout.** The system shall enable brownout detection, and a brownout reset shall leave heating de-energised.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-25
STATEMENT: >>>
**Relay fail-on (uncommanded current).** The system shall latch a fault when measured heater current exceeds a configurable threshold (default 0.5 A) during a commanded-off interval, after the settle delay of [LINK: SWR-CUR-04], for a configurable number of consecutive measurement windows (default 2). This is the direct electrical counterpart of [LINK: SWR-SAF-08] and shall act on it rather than waiting for a temperature rise.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-26
STATEMENT: >>>
**Relay or element fail-off (no current when commanded).** The system shall latch a fault when measured conduction current remains below a configurable threshold (default 20 % of the reference current) during commanded-on intervals for a configurable period (default 30 s). This covers a failed SSR, an open contactor, an open safety chain, a blown heater fuse and fully open elements, and shall act long before the thermal detection of [LINK: SWR-SAF-07].
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-27
STATEMENT: >>>
**Weld discrimination.** On detecting uncommanded current ([LINK: SWR-SAF-25]) the system shall de-assert heat enable so the contactor opens, wait a configurable interval (contactor drop-out time plus margin, default 2 s), and re-measure. If current has ceased it shall latch **SSR shorted**; if current persists it shall latch **contactor welded**, which is the more severe fault and whose operator instruction shall be to isolate the kiln at its supply, because the controller has no remaining means of interrupting the current.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-28
STATEMENT: >>>
**Partial element failure / current deviation.** The system shall compare conduction current against the reference current of [LINK: SWR-CUR-08], corrected for the known positive temperature coefficient of the elements where configured, and shall raise a warning at a configurable deviation (default 10 %) and latch a fault at a configurable deviation (default 25 %). Losing one of several element groups is a step change of a known fraction and shall be detected as such.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-29
STATEMENT: >>>
**Over-current.** The system shall latch a fault when measured current exceeds a configurable maximum (default 120 % of nominal), indicating a shorted element, incorrect wiring or a failed SSR passing excessive current.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-30
STATEMENT: >>>
**Relay wear / incipient failure.** The system shall raise a warning when the switching-operation count of the contactor or an SSR reaches a configurable life limit, and shall additionally raise a warning when current mismatches of the kind described in [LINK: SWR-SAF-25] or [LINK: SWR-SAF-26] occur intermittently and self-clear, an early indication that a relay is becoming defective before it fails outright.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-31
STATEMENT: >>>
**Door / lid interlock.** Where a door interlock switch is fitted, the system shall de-energise heating and open the contactor **immediately**: within one safety cycle, with no confirmation delay, whenever the switch indicates the door is open, and shall latch a fault if it remains open for a configurable confirmation period (0–0.5 s, default 0.2 s) while a heating state is active. The switch shall be **normally closed**, so that an open circuit, a disconnected plug or a failed switch all read as "door open". Where no interlock is fitted the rule shall stand down and a warning shall be raised; it shall not be possible for an unread input to be interpreted as a closed door.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-32
STATEMENT: >>>
**Clearing the supervisor's own trip.** The independent safety supervisor of [LINK: SWA-22] shall latch its trip and shall clear it only on a **local, deliberate human act**: a button wired to the supervisor, which shall be **edge triggered and held**. The input shall be seen released before it can clear anything, and shall then be held for a configurable-at-compile-time period (default 0.5 s), so that a button shorted to ground, or one stuck down, can never clear the latch. A failed start-up self-test shall not be clearable by this or any other means.

There shall be no path to this function from the link, because the supervisor has no receiver ([LINK: SWA-22]).
<<<
RATIONALE: >>>
Written because the behaviour was implemented and tested before it was specified, which `safety-supervisor.md` section 12 item 4 recorded as outstanding. Six host tests exercised it against a tasklist item rather than a requirement, and a tested behaviour with nothing behind it is the gap a certification assessment finds first.

The deliberate difference from [LINK: SWR-SAF-17] is worth stating rather than leaving as an apparent contradiction: that requirement makes the **ESP32's** latched fault survive power loss, whereas the supervisor's latch does not. The supervisor comes up refusing heat regardless, because its permit is conjunctive and no conversion has yet been seen, so a latch that survived the power cycle would add nothing and would need a second clearing path to recover from.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-33
STATEMENT: >>>
**Working memory integrity.** The independent safety supervisor shall test its working memory with a pattern test that drives every bit of every tested word to both states, and shall additionally apply an **address-dependent** pattern, so that two words which are physically the same storage are detected. The test shall run over the whole of working memory before heat is first permitted, and shall thereafter run continuously, a block at a time, such that the whole is covered repeatedly while the supervisor runs. A failure shall be treated as a failed self-test ([LINK: SWR-SAF-36]).
<<<
RATIONALE: >>>
An address-dependent pattern is required and not optional. Two words that alias because an address line is stuck pass every uniform pattern, because both hold the same value and both read back what was written; they fail only when asked to hold two different values at once.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-34
STATEMENT: >>>
**Stack overflow detection.** The supervisor shall reserve a guard region below its stack, fill it at start-up with a pattern that is neither all zeros nor all ones, and check **every word** of it each cycle. A guard word that no longer holds the pattern shall be treated as a failed self-test ([LINK: SWR-SAF-36]).
<<<
RATIONALE: >>>
The pattern excludes all-zeros and all-ones because those are what uninitialised and erased storage read as: a guard whose pattern matches the state it is looking for would read as intact on a board where it had never been filled. Every word is checked rather than a sample, because the stack arrives at the top of the region and a sampled check would miss a shallow overflow, which is the one that is still recoverable.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-35
STATEMENT: >>>
**Program sequence monitoring.** Each stage of the supervisor's cycle shall announce itself, and at the end of each cycle the supervisor shall verify that every stage ran **exactly once and in order**. A cycle whose sequence is incomplete, out of order or repeated shall be treated as a failed self-test ([LINK: SWR-SAF-36]). Each cycle shall be judged on its own; a broken cycle shall not condemn the next one, because latching is the trip logic's responsibility and not the monitor's.
<<<
RATIONALE: >>>
This detects what a watchdog cannot. A watchdog notices a cycle that stopped; it cannot notice a cycle that finished on time having skipped the stage that drives the permit line, or one that a corrupted branch entered halfway through. Both produce a cycle of the right duration doing the wrong work.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-36
STATEMENT: >>>
**A failed diagnostic is not clearable.** A failure of any self-diagnostic, whether at start-up or while running, shall de-energise heating, shall latch, and shall **not** be clearable by the local button of [LINK: SWR-SAF-32] or by any other operator action. Recovery shall require a power cycle, and a diagnostic that fails again shall latch again.
<<<
RATIONALE: >>>
The clear button exists so an operator can acknowledge a condition they can see and have dealt with: an open thermocouple, an over-temperature. A supervisor whose memory, stack, clock, program image or program sequence has failed is not in that category. It is a supervisor that cannot be trusted to evaluate its own conditions, and a button that returned it to service would be a button that overrides the diagnostic rather than the fault.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-37
STATEMENT: >>>
**Two chamber thermocouples, compared.** The independent safety supervisor shall read **two** chamber thermocouples, each through its **own front end on its own SPI bus**, and shall:

- act on the **higher** of the two valid readings, never on an average and never on a fixed preference;
- latch a fault when both readings are valid and differ by more than a compiled-in band (50 °C) for a compiled-in confirmation period (10 s);
- continue to protect using whichever couple remains valid if the other becomes unusable, and report that it is doing so;
- refuse to start up at all if either front end fails to configure.

The installation shall place the two couples so that the comparison is a statement about the sensors rather than about the kiln: in the same thermowell, or close enough that chamber gradients stay inside the band.
<<<
RATIONALE: >>>
This is the requirement that answers [LINK: HZ-03] by **comparison** rather than only by interrogation, and it reverses the decision recorded in section 9 of `safety-supervisor.md`, which declined a second couple on installation grounds. Those grounds were about product convenience; this is about the only hazard the design previously admitted defeated both channels.

Acting on the higher reading is the half that does the safety work. A couple reading low is the dangerous failure, because it lets a hot kiln look cool. An average would let a couple reading 200 °C low pull the pair 100 °C low, which is the failure dressed as redundancy.

Two SPI buses rather than two chip selects on one: a shared bus makes both readings depend on the same shift register, clock divider and chip-select logic, and a common-cause failure there takes both at once. Three pins buys independence of everything between the core and the two front ends.

The band is wide, and the limitation has to be stated rather than implied: it catches a **grossly** wrong couple, which is the [LINK: HZ-03] failure, and not a couple reading five degrees low. A band tight enough for that would stop healthy firings, and [LINK: HZ-10] is about where that leads.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-38
STATEMENT: >>>
**Permit readback.** The supervisor shall sense the state of the coil drive it commands, and shall latch a fault when the permit has been withdrawn and the drive is still sensed energised after a compiled-in settle period (2 s). This fault shall **replace** the reason of any existing trip other than a failed self-test, because a supervisor that cannot interrupt the heater supersedes whatever it was interrupting it for.

A permit that is commanded and **not** sensed shall not be a fault: that is heat not being delivered, which the lid interlock and the front ends' fault outputs do deliberately.

Where no readback is fitted the diagnostic shall report as **absent** rather than as passing or failing.
<<<
RATIONALE: >>>
Without it the output stage is the one part of the chain with no diagnostic at all: the supervisor could command the coil open for an hour against a shorted drive transistor and report everything healthy.

The escalation is the same reasoning [LINK: SWR-SAF-27] uses to make a welded contactor the more severe of its pair. An operator shown "over-temperature" presses the clear button; one shown "permit stuck" is told to isolate at the supply, which is the only thing that helps. A failed self-test is the exception, because a supervisor that has failed its own diagnostics cannot be trusted to have concluded correctly that the coil is stuck.

This places a requirement on the hardware that the board does not yet carry: a divider from the coil drive node to the supervisor's sense input, scaled to 3V3 and referenced to its ground.
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-5-3
TITLE: 5.3 Reaction and recovery requirements

[REQUIREMENT]
UID: SWR-SAF-16
STATEMENT: >>>
On any fault the system shall, in this order: command zero duty, de-assert heat enable so the contactor opens, assert the alarm output, latch the fault with its code and a snapshot of relevant values, log it, and enter Fault state.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-17
STATEMENT: >>>
A latched fault shall persist across power loss, and shall require an explicit operator acknowledgement to clear. The system shall not silently self-recover.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-18
STATEMENT: >>>
The system shall refuse to clear a fault while its triggering condition is still present.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-19
STATEMENT: >>>
Each fault shall have a unique, stable numeric code and a human-readable cause, presented on both the display and the web interface, and documented.
<<<
VERIFICATION: I, T

[REQUIREMENT]
UID: SWR-SAF-20
STATEMENT: >>>
The on-board buzzer ([LINK: SYS-HW-09]) shall sound on any fault and on program completion, and the two shall be audibly distinguishable by their pattern.

**Amended 2026-10-09 to say what the two patterns are**, because "distinguishable" was left to the implementation and the implementation was in a timer callback no test could reach:

- **Completion** is three 90 ms chirps, then five seconds of silence. Brief and unmistakably a notification.
- **A fault** is six 60 ms chirps at twice that rate, a 400 ms gap, and again without end until the fault is acknowledged. Twice the chirp rate, a third of the cycle sounding against a twentieth, and a cycle five times shorter: the two differ in rhythm, in rate and in duty, so neither a noisy workshop nor a closed door collapses one into the other.

The patterns are a table in `kiln_core/alarmptn`, and the distinguishability is asserted as a comparison between them rather than described, which is why the verification method changes from Demonstration to Test. A buzzer that cannot be commanded, including a pattern value that is not one of the three, is silent: the failure direction is off, because an operator's only remedy for a buzzer stuck on is the mains switch.
<<<
VERIFICATION: T

[REQUIREMENT]
UID: SWR-SAF-21
STATEMENT: >>>
Heating outputs shall be de-energised during reset, boot, firmware update and any transition through an undefined software state.
<<<
VERIFICATION: I, T

[REQUIREMENT]
UID: SWR-SAF-22
STATEMENT: >>>
Every safety detection threshold shall be configurable within a bounded range, and no range shall permit disabling a detection entirely except where explicitly stated ([LINK: SWR-SAF-12] warning only).
<<<
VERIFICATION: I, T

[REQUIREMENT]
UID: SWR-SAF-23
STATEMENT: >>>
The maximum chamber temperature shall be configurable only up to an absolute compile-time ceiling of **1300 °C**, and every temperature setpoint, program target and tuning setpoint shall be clamped to the configured maximum.

The independent safety supervisor's hard-coded backstop shall be **1350 °C**, above this ceiling, so that the configurable limit is always reachable and the backstop is always beyond it. The two values shall be stated together wherever either appears; limits that can be edited apart eventually cross. The 1300 °C ceiling is above cone 10 (about 1285 °C), and 1350 °C is the top of type K's usable range ([LINK: SWR-ACQ-05]), which is why the ceiling moved down rather than the backstop up.
<<<
VERIFICATION: T

[[/SECTION]]

[[/SECTION]]

[[SECTION]]
UID: SECT-7
TITLE: 7. Testability requirements

[TEXT]
STATEMENT: >>>
> "Designed for testability" is a stated goal of this project, so it is specified
> as requirements rather than left to implementation taste. The architecture in
> [`architecture.md`](architecture.md) is structured to satisfy this section.
<<<

[[SECTION]]
UID: SECT-7-1
TITLE: 7.1 Design for test

[REQUIREMENT]
UID: SWR-TST-01
STATEMENT: >>>
The control, safety, setpoint-generation, autotune, program, and log-encoding logic shall be implemented in components that contain **no reference to any hardware peripheral, ESP-IDF driver, or RTOS primitive**, and shall be compilable and runnable on a development host.
<<<
PRIORITY: M
VERIFICATION: A, I

[REQUIREMENT]
UID: SWR-TST-02
STATEMENT: >>>
All hardware access shall be reached through explicit HAL interfaces that can be substituted at link or construction time by a test double.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-03
STATEMENT: >>>
No logic component shall read a clock directly; time shall be supplied through an injected time source, so that a 24 h firing can be simulated in milliseconds.
<<<
PRIORITY: M
VERIFICATION: A, I

[REQUIREMENT]
UID: SWR-TST-04
STATEMENT: >>>
Logic components shall be free of global mutable state: each shall operate on an explicit context passed by the caller, so that multiple independent instances can coexist in one test process.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-05
STATEMENT: >>>
Logic components shall perform no dynamic allocation after initialisation, and their memory footprint shall be statically determinable.
<<<
PRIORITY: S
VERIFICATION: A

[REQUIREMENT]
UID: SWR-TST-06
STATEMENT: >>>
Every component shall have a declared, minimal public interface; no test shall need access to a private symbol to verify required behaviour.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-07
STATEMENT: >>>
Component dependencies shall be acyclic and shall respect the layering of [`architecture.md`](architecture.md); a violation shall fail the build.
<<<
PRIORITY: M
VERIFICATION: A

[REQUIREMENT]
UID: SWR-TST-08
STATEMENT: >>>
The state of the run controller and the safety supervisor shall be fully observable through a query interface, so that tests assert on state rather than on side effects.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-09
STATEMENT: >>>
Every fault condition of §5.2 ([LINK: SECT-5-2]) shall be reachable in a test through a documented stimulus, without physical hardware.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TST-10
STATEMENT: >>>
Test-only interfaces (fault injection, state forcing, time warping) shall be compiled out of production builds, verified by a build-time check.
<<<
PRIORITY: M
VERIFICATION: A

[[/SECTION]]

[[SECTION]]
UID: SECT-7-2
TITLE: 7.2 Test infrastructure

[REQUIREMENT]
UID: SWR-TST-11
STATEMENT: >>>
The project shall provide a **kiln plant simulator**: a first-order-plus-dead-time thermal model with configurable gain, time constant, dead time, ambient temperature and noise, capable of injected faults (open element, shorted SSR, open TC, drifting TC, lid opened).
<<<
PRIORITY: M
VERIFICATION: I, T

[REQUIREMENT]
UID: SWR-TST-12
STATEMENT: >>>
The simulator shall be deterministic and reproducible from a seed, so that a failing test can be replayed exactly.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TST-13
STATEMENT: >>>
The project shall provide host-executed unit tests for every logic component, runnable with a single command and without hardware.
<<<
PRIORITY: M
VERIFICATION: D

[REQUIREMENT]
UID: SWR-TST-14
STATEMENT: >>>
The project shall provide closed-loop integration tests that run the real control, setpoint, safety and autotune code against the simulator, verifying the performance requirements [LINK: SWR-NFR-05] to [LINK: SWR-NFR-08] and the safety reactions of §5 ([LINK: SECT-5]).
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TST-15
STATEMENT: >>>
The project shall provide on-target tests for the HAL drivers, run on real hardware or an emulator, covering front-end configuration and fault decoding, display output, encoder decoding, storage and the time-proportional output.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TST-16
STATEMENT: >>>
The project shall provide API-level tests that exercise the HTTP interface end-to-end against a firmware instance, including malformed and hostile input.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TST-17
STATEMENT: >>>
The project shall provide a documented HIL procedure using a low-power resistive load and a thermocouple simulator, for the tests that cannot be virtualised.
<<<
PRIORITY: S
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-18
STATEMENT: >>>
Timing requirements [LINK: SWR-NFR-01] to [LINK: SWR-NFR-04] shall be verified on target by instrumented measurement of cycle period, jitter and worst-case latency, reported as numbers rather than asserted by inspection.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TST-19
STATEMENT: >>>
The project shall measure line and branch coverage of host tests and shall achieve at least **90 % line coverage** of the control, safety, setpoint, program and autotune components, and **100 % of safety decision branches**.
<<<
PRIORITY: M
VERIFICATION: A

[REQUIREMENT]
UID: SWR-TST-20
STATEMENT: >>>
The build shall support address and undefined-behaviour sanitisers for host test runs.
<<<
PRIORITY: S
VERIFICATION: A

[REQUIREMENT]
UID: SWR-TST-21
STATEMENT: >>>
Long-duration behaviour ([LINK: SWR-NFR-10], [LINK: SWR-NFR-11]) shall be verifiable both by accelerated simulation and by an automated soak test on target.
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[SECTION]]
UID: SECT-7-3
TITLE: 7.3 Process

[REQUIREMENT]
UID: SWR-TST-22
STATEMENT: >>>
Every requirement in this document shall be traceable to at least one verification artefact, and the traceability shall be maintained as a machine-checkable file in the repository.
<<<
PRIORITY: M
VERIFICATION: A

[REQUIREMENT]
UID: SWR-TST-23
STATEMENT: >>>
Every requirement in §5 ([LINK: SECT-5]) shall be covered by at least one **automated** test; inspection alone shall not be sufficient.
<<<
PRIORITY: M
VERIFICATION: A

[REQUIREMENT]
UID: SWR-TST-24
STATEMENT: >>>
Continuous integration shall, on every push and pull request: build the firmware, run all host unit and integration tests with coverage, run static analysis, run the emulated target and API tests, and lint the web assets. A failure in any of these shall block merge.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-25
STATEMENT: >>>
A defect fix shall be accompanied by a regression test that fails before the fix and passes after it.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-26
STATEMENT: >>>
Test names shall reference the requirement identifiers they verify.
<<<
PRIORITY: S
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-27
STATEMENT: >>>
The kiln plant simulator ([LINK: SWR-TST-11]) shall model heater current as well as temperature, and shall inject the electrical faults that [LINK: SWR-SAF-25]–[LINK: SWR-SAF-30] detect: relay fail-on, relay fail-off, welded contactor (current persisting after the contactor is commanded open), partial element failure, over-current, and a disconnected current transformer.
<<<
PRIORITY: M
VERIFICATION: T

[REQUIREMENT]
UID: SWR-TST-28
STATEMENT: >>>
The HIL jig ([LINK: SWR-TST-17]) shall be able to present a known current to the transformer and to emulate a welded contactor, so that the discrimination sequence of [LINK: SWR-SAF-27] is verified against real hardware and not only in simulation.
<<<
PRIORITY: M
VERIFICATION: I

[REQUIREMENT]
UID: SWR-TST-29
STATEMENT: >>>
The independent safety supervisor's trip logic and the link's wire format shall achieve at least **80 % modified condition/decision coverage (MC/DC)** in host tests, measured and enforced automatically.

Line and branch coverage are insufficient for this component, and the reason is specific rather than general. Its permit decision is a five-term conjunction, and a single test with every term true plus one with every term false gives 100 % line and 100 % branch coverage of that decision while demonstrating none of what matters: that a missing reading alone withholds heat, that a reported fault alone withholds heat, and so on for each term independently. MC/DC is the criterion that requires each condition to be shown to change the outcome on its own.

This applies to the supervisor and not to the rest of the firmware. It is about 120 lines of logic, it is the only component in which failing to evaluate a condition means heat that should have stopped, and it is the component whose entire justification is that it can be read and verified in full ([LINK: SWA-22]).
<<<
PRIORITY: M
VERIFICATION: T

[[/SECTION]]

[[/SECTION]]

[[SECTION]]
UID: SECT-10
TITLE: 10. Verification strategy summary

[TEXT]
STATEMENT: >>>
| Level | What it covers | Where it runs |
|---|---|---|
| **Unit** | Individual logic components: PID maths, setpoint generator, program validation, autotune identification, safety rules, log codec, config validation. | Host |
| **Integration (simulated)** | Closed-loop behaviour of the real firmware logic against the kiln simulator ([LINK: SWR-TST-11]): control performance, full program execution, every fault scenario, autotune convergence, power-loss recovery. | Host |
| **Driver / on-target** | HAL against real silicon: MAX31856 configuration and fault decode, OLED, encoder, flash log store, time-proportional output timing. | Target / emulator |
| **API** | HTTP endpoints, authentication, input validation, push updates, decimation correctness, hostile input. | Target / emulator |
| **Timing** | Loop period, jitter, safety latency, boot time, under load. | Target, instrumented |
| **Soak** | 168 h run, heap stability, log wraparound, WiFi reconnection. | Target |
| **Current / relay fault** | Every rule of [LINK: SWR-SAF-25]–[LINK: SWR-SAF-30] against the simulator's electrical fault injections, including the full weld-discrimination sequence. | Host |
| **HIL** | Output stage, contactor watchdog release, real thermocouple, real SSR with resistive load, real CT with a known current, emulated welded contactor. | Bench jig |
| **Commissioning** | Autotune and a full firing on a real kiln. | Real kiln |
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-11
TITLE: 11. Open questions

[QUESTION]
UID: OQ-01
STATEMENT: >>>
Should cone-based targets (Orton cone numbers with heatwork/rate correction) be offered in addition to plain temperature targets?
<<<

[QUESTION]
UID: OQ-02
STATEMENT: >>>
**Resolved 2026-09-28: yes.** The current transformer is mandatory ([LINK: SYS-HW-11]) and drives FR-CUR ([LINK: SECT-3-12]) and [LINK: SWR-SAF-25]–[LINK: SWR-SAF-30]. The thermal detections are retained as an independent backstop.
<<<
STATUS: Resolved

[QUESTION]
UID: OQ-06
STATEMENT: >>>
**Resolved 2026-10-06: single phase only.** Three-phase kilns are out of scope (§12 ([LINK: SECT-12])). A three-phase kiln monitored on one phase is worse than one not supported at all: a fault on an unmonitored phase would be caught only by the thermal rules, slowly, and the power and energy figures would cover a third of the load while looking like a whole-kiln number. This reverses the resolution of 2026-10-05 and reinstates [LINK: SYS-ASM-10] in a narrower form.
<<<
STATUS: Resolved

[QUESTION]
UID: OQ-08
STATEMENT: >>>
**Resolved 2026-10-09: the device fetches, the operator at the display confirms, and the web interface stays read-only.** What replaces the removed over-the-web firmware update ([LINK: SWR-UPD-01]) is a **pull** path, not a staged push: a daily check of a signed static manifest at `update.bitcrushtesting.com` ([LINK: SWR-UPD-09]) that reveals nothing about the device ([LINK: SWR-UPD-10]), an announcement on the local display, and an install that happens only on a deliberate confirmation there ([LINK: SWR-UPD-12], [LINK: SWR-HMI-16]). USB remains as the recovery and downgrade path ([LINK: SWR-UPD-14]).

Choosing pull over the staged push this question also offered has one decisive consequence: **no inbound route is created at all**, so [LINK: SWR-WEB-26] and `SEC-00` keep their absolute form instead of being narrowed to "read-only except for firmware". What the answer costs is a new outbound connection and a dependency on the manufacturer's service, both carried in `security.md` section 6.2. `SRR-11` stays open until this is built rather than merely specified.
<<<
STATUS: Resolved

[QUESTION]
UID: OQ-09
STATEMENT: >>>
**Resolved 2026-10-09: nowhere. The profiles are pre-compiled and nothing edits them.** The question was where firing programs are authored now that [LINK: SWR-WEB-26] has made the web interface read-only, with a local editor, a file import, or shipping only the examples as the candidates.

The answer is the third, taken as a decision rather than as a default. [LINK: SWR-PRG-09]'s examples are the device's whole repertoire; [LINK: SWR-PRG-07], [LINK: SWR-PRG-08] and [LINK: SWR-PRG-10] are withdrawn.

**The gap this leaves is real and is not being minimised**: a potter who wants a curve of their own needs a toolchain and a flash, which for most of them means somebody else does it. That is a genuine cost of the read-only decision and it should be stated in the user documentation rather than discovered.

What it buys is that there is no authoring path at all: nothing over the network to secure, no file format to validate, no parser accepting operator data on the processor that commands a heater, and no editor to design for a rotary encoder. If the cost proves too high in use, the cheapest reversal is the file import of [LINK: SWR-PRG-08] at service time, which needs physical access and so leaves the security argument intact.
<<<

[QUESTION]
UID: OQ-07
STATEMENT: >>>
Should the element positive temperature coefficient used to correct the [LINK: SWR-SAF-28] baseline be measured automatically during the first firing, or entered by the installer from the element datasheet?
<<<

[QUESTION]
UID: OQ-03
STATEMENT: >>>
Should the log store be sized for whole-life retention of run summaries in a separate, non-circular area?
<<<

[QUESTION]
UID: OQ-04
STATEMENT: >>>
Which small charting approach for [LINK: SWR-WEB-06], a vendored MIT-licensed micro-library, or hand-written canvas rendering? Decided in the architecture, revisit if asset budget is exceeded.
<<<

[QUESTION]
UID: OQ-05
STATEMENT: >>>
Is a 3-zone variant ([LINK: SYS-ASM-02]) a v1.1 goal? It affects whether the control component is written for one zone or N from the start.
<<<

[[/SECTION]]

[[SECTION]]
UID: SECT-APPENDIX-A-FAULT-CODE-ALLOCATION
TITLE: Appendix A, Fault code allocation

[TEXT]
STATEMENT: >>>
Codes are stable and shall not be reused. Detail in §5.2 ([LINK: SECT-5-2]).

| Code | Fault | Requirement |
|---|---|---|
| 1 | Chamber thermocouple open circuit | SWR-SAF-04 |
| 2 | Chamber thermocouple short circuit | SWR-SAF-04 |
| 3 | Chamber reading out of range | SWR-SAF-04 |
| 4 | Cold-junction fault | SWR-SAF-04 |
| 5 | Front-end communication failure | SWR-SAF-04 |
| 6 | Chamber thermocouple reversed | SWR-SAF-05 |
| 7 | Chamber sensor stuck | SWR-SAF-06 |
| 8 | Thermal runaway / heating failure | SWR-SAF-07 |
| 9 | Uncommanded heating (SSR shorted) | SWR-SAF-08 |
| 10 | Over-temperature | SWR-SAF-09 |
| 11 | Setpoint excursion | SWR-SAF-10 |
| 12 | Enclosure over-temperature | SWR-SAF-11 |
| 13 | Control loop deadline missed | SWR-SAF-13 |
| 14 | Safety supervisor deadline missed | SWR-SAF-13 |
| 15 | Watchdog reset during run | SWR-SAF-14 |
| 16 | Enclosure thermocouple fault | SWR-SAF-04, SWR-SAF-11 |
| 17 | Operator abort | SWR-RUN-04 |
| 18 | Autotune failed to converge | SWR-TUN-07 |
| 19 | Power-loss recovery refused | SWR-RUN-08 |
| 20 | Configuration invalid / storage failure | SWR-CFG-05 |
| 21 | Uncommanded heater current (relay fail-on) | SWR-SAF-25 |
| 22 | Contactor welded, isolate at the supply | SWR-SAF-27 |
| 23 | No heater current when commanded (relay/element fail-off) | SWR-SAF-26 |
| 24 | Heater current deviation (partial element failure) | SWR-SAF-28 |
| 25 | Heater over-current | SWR-SAF-29 |
| 26 | Current transformer fault or disconnected | SWR-CUR-11 |
| 27 | Door opened during a firing | SWR-SAF-31 |

Warnings (non-latching, do not stop a firing):

| Code | Warning | Requirement |
|---|---|---|
| 101 | Insulation degradation suspected | SWR-SAF-12 |
| 102 | Hold-back active, firing behind schedule | SWR-CTL-11 |
| 103 | Log store unavailable | SWR-LOG-14 |
| 104 | Display unavailable | SWR-HMI-14 |
| 105 | Time not synchronised | SWR-LOG-12 |
| 106 | WiFi disconnected | SWR-NET-07 |
| 107 | Duty saturated for extended period | SWR-CTL-15 |
| 108 | Gains are untuned defaults | SWR-TUN-11 |
| 109 | Relay switching-operation life limit reached | SWR-SAF-30 |
| 110 | Intermittent current mismatch, a relay may be failing | SWR-SAF-30 |
| 111 | Current monitoring disabled | SWR-CUR-12 |
| 112 | Heater current deviating from the run reference | SWR-SAF-28 |
| 113 | No door interlock fitted | SWR-SAF-31 |
<<<

[[/SECTION]]