boon_metrology.h

#pragma once
 
#include <archive.h>
#include <archive_entry.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include "serialize.h"
 
// for post metrology sample return value key
#define PM_NO_CHANGE 0
#define PM_ERROR 1
#define PM_STATE_CHANGE 2
 
#define MAX_TIMESTAMP_LENGTH 50

struct LoadChange {
  bool m_LoadChangeDetected;    /* any load change in the active power */
  bool m_EVChangeDetected;      /* EV state change detected */
  bool m_BatteryChangeDetected; /* battery state change detected */
  int m_ClusterID;              /* cluster ID associated with the convolve filter pattern */
};

struct FeatureStruct {
  float MinVal; 
  float MaxVal; 
};

struct MetrologySettings {
  struct FeatureStruct VoltageAverage;
  struct FeatureStruct Current;
  struct FeatureStruct LineToLineVoltage;
  struct FeatureStruct ActivePower;
  struct FeatureStruct ReactivePower;
  struct FeatureStruct VoltageTHD;
  struct FeatureStruct CurrentTHD;
};

struct PowerQualitySettings {
  float PercentVariation;       // The Nano model percent variation
  int StreamingWindowSize;      // Typically = 1
  uint32_t NumTrainingSamples;  // This many metrology samples will be consumed prior to switching to monitoring mode
};
 
struct LoadDisaggregationSettings {
  // Nano model settings for load disaggregation
  uint16_t FilterWindowSize;    // Window for load transition checking
  uint16_t PatternWindowSize;   // Window for pattern generation
  float PercentVariation;       // Nano model percent variation for training disaggregation of discrete jumps (loads and generation)
  uint32_t NumTrainingSamples;  // This many metrology samples will be consumed prior to switching to monitoring mode
  float DetectionThreshold;     // The threshold for detecting jumps in Current
};
 
struct PVDisaggregationSettings {
  // PV Model settings
  uint16_t NumTrainingSamples;  // The number of samples to use for disaggregating PV active power transitions from discrete loads
  float ZValueThreshold;        // The statistical z-threshold tolerance to separate PV from discrete jumps
};
 
struct DynamicHostingCapacitySettings {
  uint32_t NumTrainingSamples;  // Number of historical samples to retain for computing DHC estimates
};

struct BoonMetrologyConfiguration {
  struct PowerQualitySettings PQS;
  struct LoadDisaggregationSettings LDS;
  struct PVDisaggregationSettings PVDS;
  struct DynamicHostingCapacitySettings DHS;
};
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct BoonMetrology;

float GetBoonMetrologyVersion();

const char* GetErrorString(struct BoonMetrology* BM);

struct BoonMetrology* ConstructBoonMetrology(uint16_t SamplesPerSecond);

void FreeBoonMetrology(struct BoonMetrology* BM);

void GetBoonMetrologyConfiguration(struct BoonMetrology* BM, struct BoonMetrologyConfiguration* BMC);

bool ConfigureLoadDisaggregation(struct BoonMetrology* BM, struct LoadDisaggregationSettings* LDS);

bool ConfigurePVDisaggregation(struct BoonMetrology* BM, struct PVDisaggregationSettings* PVDS);

bool ConfigurePowerQualityMonitoring(struct BoonMetrology* BM, struct PowerQualitySettings* PQS);

bool ConfigureDynamicHostingCapacity(struct BoonMetrology* BM, struct DynamicHostingCapacitySettings* DHS);

bool IncrementalSerialize(struct BoonMetrology* BM, const char* DirPath, ArchiveWriteCallbackType WriteCallbackFunction,
                          struct IncrementalArchiveFileStatus* AFS, size_t TransferBufferSize, void* UserData);

bool IncrementalDeserialize(struct BoonMetrology* BM, const char* DirPath, ArchiveReadCallbackType ReadCallbackFunction,
                            struct IncrementalArchiveFileStatus* AFS, size_t TransferBufferSize, void* UserData);

bool SerializeBoonMetrology(struct BoonMetrology* BM, uint8_t** Buffer, size_t* BufferLength);

bool DeserializeBoonMetrology(struct BoonMetrology* BM, uint8_t* Buffer, size_t BufferLength);

struct MetrologySample {
  char Time[MAX_TIMESTAMP_LENGTH];  // date    // LD
  float VoltageAverage;             // volts   // DHC, PQM
  float Current;                    // amps    // PQM
  float LineToLineVoltage;          // volts   // PQM
  float ActivePower;                // kW      // DHC, PQM, LD, PVD
  float ReactivePower;              // kVAR    // DHC, PQM, LD
  float VoltageTHD;                 //  %      // PQM, LD
  float CurrentTHD;                 //  %      // PQM, LD
};

bool PostMetrologySample(struct BoonMetrology* BM, const struct MetrologySample* MS, struct LoadChange* LC);

bool GetPVDisaggregationEstimate(struct BoonMetrology* BM, float* PVEstimate);

const char* GetDisaggregation(struct BoonMetrology* BM);

void ResetPVDisaggregationEstimate(struct BoonMetrology* BM);

bool GetPowerQualityScore(struct BoonMetrology* BM, float* QualityScore);

bool GetVoltageEstimatePQ(struct BoonMetrology* BM, float DeltaP, float DeltaQ, float* DeltaVEstimate);

bool GetVoltageEstimateP(struct BoonMetrology* BM, float DeltaP, float* DeltaVEstimate);

const char* GetStatus(struct BoonMetrology* BM);

const char* GetStatusPowerQualityMonitoring(struct BoonMetrology* BM);

const char* GetStatusDynamicHostingCapacity(struct BoonMetrology* BM);

const char* GetStatusPVDisaggregation(struct BoonMetrology* BM);

const char* GetStatusLoadDisaggregation(struct BoonMetrology* BM);

const char* GetDiagnostics(struct BoonMetrology* BM);
 
#define DT_DHC 0x0001
#define DT_PVDisaggregation 0x0002
#define DT_LoadDisaggregation 0x0004
#define DT_PowerQualityMonitoring 0x0008
#define DT_ALL_USE_CASES DT_DHC | DT_PVDisaggregation | DT_LoadDisaggregation | DT_PowerQualityMonitoring
 
#define DT_ExcludeRecentSamples 0x2000
#define DT_ClusterCountOnly 0x4000
#define DT_ExcludeNano 0x8000

const char* GetDiagnosticsByType(struct BoonMetrology* BM, uint16_t ResultsList);
 
#ifdef __cplusplus
}
#endif