Module tune 

bhtune tune/bhtune simulate: runs a full MRFT test end-to-end — resolving a template, deriving tags, transitioning the loop to Manual, polling the driver and driving a real [bhtune_core::MrftEngine], persisting every tick and the final calculated results, then restoring the loop and optionally writing back the chosen PID constants.

The separate bhtune check preflight validates the same request inputs and reads controller state without preparing or persisting a run. It uses a read-only database connection and ReadOnlyDriver so it cannot mutate the database or controller.

Mirrors the legacy MRFTstart/ReadInitialOPCvalues/ChangeControllerModeToMan/ ResetOPC sequence from OPCClass.cs. The mode-transition and write-back steps automatically no-op for the simulator driver, since its [bhtune_core::LoopTags] has no setpoint/mode/mode-attribute/PID-constant tags at all (see build_loop_tags below) — no separate “is this the simulator?” branching is needed in that logic.

Structs

PidWritePreview

Presentation of one raw result’s controller target, including precision failures that do not change the recorded calculation status.

PreflightCheck

One named preflight check and its operator-facing detail.

PreflightReport

Read-only results for a tune request.

PreflightTagRead

The value, quality, and validation result for one derived OPC tag.

PreparedTune

Everything prepare resolves before a tune’s long-running polling phase can start: the already-validated ValidatedTuneRequest, the resolved template and derived tags, a connected driver, the built [LoopConfig], the run’s start time, and the response level (if any) to write back at the end – plus the tune_runs row’s assigned id.

RecoveryStepReport

RestoreLoopReport

RestoreLoopRequest

StartupOrphanSweepReport

TuneRequest

Transport-neutral inputs for a tune run.

TuneRequestValidationError

A common tune-request field failed runtime validation.

TuneRunReport

UnsupportedDriverKind

ValidatedTuneRequest

A transport-neutral tune request that has passed common input validation.

Enums

AbortReason

DriverKind

PidWriteOutcome

The result of write_pid_values – deliberately simpler than WriteBackOutcome below, which layers CLI-only concerns (a Skipped variant covering unconfigured tags, no recorded results, or an interactive skip) on top of this. write_pid_values only ever runs once a specific, available target has already been chosen, so there is nothing left to “skip” by the time it’s called. Named distinctly from bhtune_driver::WriteOutcome (that one describes a single raw tag write’s own outcome; this one describes the full pre-read/write/verify/rollback/audit sequence across all three PID constants).

PreflightCheckStatus

Severity assigned to an individual preflight result.

RecoveryStepStatus

RunOutcome

TuneOutcome

WriteBackOutcome

WriteBackSelection

WriteBackSkipReason

Constants

DEFAULT_SIM_DEAD_TIME

Default simulator dead time in seconds.

DEFAULT_SIM_GAIN

Default simulator process gain used by every tune-request adapter.

DEFAULT_SIM_INITIAL_VALUE

Default simulator initial PV and MV.

DEFAULT_SIM_NOISE

Default simulator measurement-noise amplitude.

DEFAULT_SIM_SEED

Default simulator random-number-generator seed.

DEFAULT_SIM_TAU

Default simulator process time constant in seconds.

MV_ACTUATION_CONFIRMATION_SECS

Maximum interval from an accepted OPC DA MV write to its mandatory confirmation check.

Traits

WriteBackHandler

Optional adapter hook for response-level selection and progress reporting.

Functions

controller_pid_for_result

The shared new-write validity/precision gate. Restore and revert paths deliberately do not call this: their recorded targets must retain their original precision.

drive

Runs an already-prepared tune without an interactive selector and returns its coarse outcome. An unrequested write-back is skipped.

drive_report

Runs an already-prepared tune and returns the detailed runtime outcome for adapters that report it to a user. An optional handler may select an interactive PID response level and observe write-back progress; it never replaces runtime validation or safety checks.

pid_parameters_for_result

Validates a persisted result’s raw, full-precision PID parameters.

pid_write_preview

preflight

Checks a request without invoking tune preparation, the polling loop, or any database mutation. An existing database is queried only through a read-only pool; when it is absent, the current built-in and configured catalog templates provide the lookup data.

prepare

Validates a tune request and prepares the driver and persisted run record.

prepare_owned

Prepare a simulator tune and bind its history to a demo session before the background execution is started. Live OPC DA preparation is intentionally rejected by this helper.

recover_startup_orphans

Full-mode startup records every affected row before retiring a dead live owner. Holding the process-shared database lock distinguishes a killed process from a paused one whose heartbeat may be stale but whose controller operation is still live.

restore_loop

Restores an interrupted live run only after its original database/resource owner is atomically replaced and a durable evidence export exists.

sample_quality_from_driver

Maps the driver’s live bhtune_driver::Quality to the database’s persisted SampleQuality – two separate enums (rather than one shared type) because bhtune-driver and bhtune-db are sibling crates that each depend only on bhtune-core, not on each other; only a crate depending on both needs this mapping, so it lives here rather than forcing a new cross-dependency onto either crate. pub (not just used by [run_polling_loop] below) because bhtune-server’s routes::opc reuses it verbatim for GET /api/opc/read’s quality field, rather than a second copy of the same three-arm match.

tune_outcome_for_run

validate_finite_f32

Rejects a non-finite f32 request value and identifies its field.

validate_positive_u32

Rejects a zero u32 value where the request requires a positive count.

validate_restore_timeout_secs

Validates the restore budget shared by CLI and HTTP-started tunes.

write_pid_values

Pre-reads the existing Proportional/Integral/Derivative values, writes and verifies target (Proportional then Integral then Derivative, stopping at the first failure), rolls back to the pre-read values on partial failure (only for kind = WriteKind::Write -- [WriteKind::Revert] never does, so a revert can't chase its own failure with a nested rollback; see [WriteKind]'s own doc comment), and records exactly one [TuneWriteRow`] audit row for the attempt, success or not.

write_pid_values_with_owner

Performs an already-owned PID write sequence. driver must be the AuditedDriver for the same guard so each write intent is persisted before I/O.