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.

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

PreparedTune

Everything prepare resolves before a tune’s long-running polling phase can start: the already-validated/defaulted TuneArgs, 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.

Enums

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

TuneOutcome

The final disposition of a tune/simulate run – drives the printed summary (see [print_summary]) and, via crate::tune_outcome_exit_code in lib.rs, the process’s exit code.

Constants

MV_ACTUATION_CONFIRMATION_SECS

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

Functions

drive

Runs an already-prepared tune to completion – the print-free counterpart to [run_with_ctrl_c], for a caller with no terminal to print a summary to and no stdin to prompt on (bhtune-server’s background tune task, tokio::spawned after its POST /api/runs handler has already returned prepared.run_id() to the HTTP client).

pid_parameters_for_result

Converts a persisted result into the exact PID values that may be written to a controller.

prepare

The fast setup phase shared by [run_with_ctrl_c] (the CLI’s entry point) and drive (the entry point for a caller – bhtune-server – that needs to start a run and return control to its own caller before the run finishes). See PreparedTune’s doc comment for why this split exists.

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.

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.

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 (safety-writeback-rollback`, finding 6 of the live-plant safety review).