85 lines
4.3 KiB
C
85 lines
4.3 KiB
C
/*
|
|
* DTU demonstration measurement model: source inputs, transformer conversion,
|
|
* reporting calibration, and explicit absolute-unit threshold helpers.
|
|
* No manufacturer FA/deadband/zero-drift convention is implied by this model.
|
|
*/
|
|
#ifndef IEC104_DTU_MEASUREMENT_H
|
|
#define IEC104_DTU_MEASUREMENT_H
|
|
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
|
|
struct DtuSettings;
|
|
|
|
#define DTU_MEASUREMENT_FIRST_SOURCE 0x9601U
|
|
#define DTU_MEASUREMENT_LAST_SOURCE 0x962CU
|
|
#define DTU_MEASUREMENT_SOURCE_COUNT 44U
|
|
|
|
typedef struct DtuMeasurementInput {
|
|
/* Normally primary engineering units. secondary_mask marks explicit
|
|
* secondary-unit overrides, the recommended external injection form.
|
|
* Slots 0x961C..0x961E are reserved and are never processed. */
|
|
double source[DTU_MEASUREMENT_SOURCE_COUNT];
|
|
uint64_t override_mask;
|
|
uint64_t secondary_mask;
|
|
} DtuMeasurementInput;
|
|
|
|
typedef struct DtuMeasurementFrame {
|
|
/* Protection inputs before primary ratios and reporting multipliers.
|
|
* Absolute zero suppression is applied here, in secondary units. */
|
|
double secondary[DTU_MEASUREMENT_SOURCE_COUNT];
|
|
/* Reported primary engineering quantities after source multiplier,
|
|
* transformer ratio, power factor 0x8054, and P/Q polarity 0x8056. */
|
|
double primary[DTU_MEASUREMENT_SOURCE_COUNT];
|
|
} DtuMeasurementFrame;
|
|
|
|
/* Unknown/reserved sources return false; Index returns COUNT if invalid. */
|
|
bool Dtu_Measurement_Source_Valid(uint32_t source_addr);
|
|
size_t Dtu_Measurement_Index(uint32_t source_addr);
|
|
void Dtu_Measurement_Init(DtuMeasurementInput *input);
|
|
|
|
/* Both setters reject nonfinite values and preserve input on failure.
|
|
* Secondary overrides survive changes to transformer rated values.
|
|
* Clearing an override lets the next Sample regenerate that source. */
|
|
bool Dtu_Measurement_Override(DtuMeasurementInput *input, uint32_t source_addr, double value);
|
|
bool Dtu_Measurement_Override_Secondary(DtuMeasurementInput *input, uint32_t source_addr, double value);
|
|
bool Dtu_Measurement_Clear_Override(DtuMeasurementInput *input, uint32_t source_addr);
|
|
|
|
/* Fill all 41 active sources; preserve overrides. Normal/fault phase is
|
|
* 0.4/1.3 per-unit current at [0,5)/[5,15)/[15,30) seconds. Open breaker
|
|
* removes phase current and P/Q/S, preserving bus voltages and residuals.
|
|
* Returns false without mutation for NULL/invalid rated settings. */
|
|
bool Dtu_Measurement_Sample(const struct DtuSettings *settings, uint64_t elapsed_ms,
|
|
bool breaker_closed, DtuMeasurementInput *input);
|
|
|
|
/* Demonstration conversion contract, not a vendor specification:
|
|
* secondary = primary_input / primary_rating * secondary_rating;
|
|
* report = secondary * explicit_ratio * source_multiplier.
|
|
* For P/Q/S use PT*phase-CT products, then 0x8054; 0x8056 negates P/Q.
|
|
* PT primary rating 0x8024 is kV; all other source voltages are V.
|
|
* Source multiplier is at source_addr + 0xCC0 and affects reporting only.
|
|
* Invalid settings/input/overflow fail atomically; reserved outputs are zero. */
|
|
bool Dtu_Measurement_Process(const struct DtuSettings *settings,
|
|
const DtuMeasurementInput *input, DtuMeasurementFrame *frame);
|
|
|
|
/* Explicit demo convention: |secondary| <= zero_abs => 0; outside the band
|
|
* remains unchanged. These XML values have no vendor-defined unit, so the
|
|
* caller must describe their use here as absolute secondary engineering units.
|
|
* Deadband is an absolute reported engineering difference, not a percentage.
|
|
* Unclassified sources get zero threshold; invalid inputs return NaN. */
|
|
double Dtu_Measurement_Zero_Absolute(const struct DtuSettings *settings, uint32_t source_addr);
|
|
double Dtu_Measurement_Deadband(const struct DtuSettings *settings, uint32_t source_addr);
|
|
double Dtu_Measurement_Energy_Factor(const struct DtuSettings *settings);
|
|
|
|
/* Does not change baseline: caller updates last_submitted only after a
|
|
* publication has been accepted. Equality to a positive threshold counts;
|
|
* threshold zero still requires an actual change. Invalid values => false. */
|
|
bool Dtu_Measurement_Changed(double value, double last_submitted, double absolute_deadband);
|
|
|
|
/* Round nearest, ties away from zero; saturate before the integer cast.
|
|
* overflow is true on saturation/nonfinite inputs/invalid scale. NaN => 0. */
|
|
int16_t Dtu_Measurement_To_Scaled(double value, double scale, bool *overflow);
|
|
|
|
#endif
|