processing.cpp

Go to the documentation of this file.

 
#include <Arduino.h>
 
#include "config.h"
#include "calibration.h"
#include "dualtariff.h"
#include "processing.h"
#include "utils_pins.h"
#include "shared_var.h"
 
// Define operating limits for the LP filters which identify DC offset in the voltage
// sample streams. By limiting the output range, these filters always should start up
// correctly.
constexpr int32_t l_DCoffset_V_min{ (512L - 100L) * 256L }; 
constexpr int32_t l_DCoffset_V_max{ (512L + 100L) * 256L }; 
constexpr int16_t i_DCoffset_I_nom{ 512L };                 
 
int32_t l_DCoffset_V[NO_OF_PHASES]{}; 

constexpr float f_capacityOfEnergyBucket_main{ static_cast< float >(WORKING_ZONE_IN_JOULES * SUPPLY_FREQUENCY) };
constexpr float f_midPointOfEnergyBucket_main{ f_capacityOfEnergyBucket_main * 0.5F };
constexpr float f_offsetOfEnergyThresholdsInAFmode{ 0.1F };
 
constexpr OutputModes outputMode{ OutputModes::NORMAL }; 
 
bool b_diversionStarted{ false }; 

constexpr auto initThreshold(const bool lower)
{
  return lower
           ? f_capacityOfEnergyBucket_main * (0.5F - ((OutputModes::ANTI_FLICKER == outputMode) ? f_offsetOfEnergyThresholdsInAFmode : 0.0F))
           : f_capacityOfEnergyBucket_main * (0.5F + ((OutputModes::ANTI_FLICKER == outputMode) ? f_offsetOfEnergyThresholdsInAFmode : 0.0F));
}
 
constexpr float f_lowerThreshold_default{ initThreshold(true) };  
constexpr float f_upperThreshold_default{ initThreshold(false) }; 
 
float f_energyInBucket_main{ 0.0F };  
float f_lowerEnergyThreshold{ 0.0F }; 
float f_upperEnergyThreshold{ 0.0F }; 
 
// for improved control of multiple loads
bool b_recentTransition{ false };                 
uint8_t postTransitionCount{ 0 };                 
constexpr uint8_t POST_TRANSITION_MAX_COUNT{ 3 }; 
// constexpr uint8_t POST_TRANSITION_MAX_COUNT{50}; /**< for testing only */
uint8_t activeLoad{ NO_OF_DUMPLOADS }; 
 
int32_t l_sumP[NO_OF_PHASES]{};                
int32_t l_sampleVminusDC[NO_OF_PHASES]{};      
int32_t l_cumVdeltasThisCycle[NO_OF_PHASES]{}; 
int32_t l_sumP_atSupplyPoint[NO_OF_PHASES]{};  
int32_t l_sum_Vsquared[NO_OF_PHASES]{};        
 
uint8_t n_samplesDuringThisMainsCycle[NO_OF_PHASES]{}; 
uint16_t i_sampleSetsDuringThisDatalogPeriod{ 0 };     
 
remove_cv< remove_reference< decltype(DATALOG_PERIOD_IN_MAINS_CYCLES) >::type >::type n_cycleCountForDatalogging{ 0 }; 
 
uint8_t n_lowestNoOfSampleSetsPerMainsCycle{ 0 }; 
 
// For an enhanced polarity detection mechanism, which includes a persistence check
Polarities polarityOfMostRecentSampleV[NO_OF_PHASES]{};    
Polarities polarityConfirmed[NO_OF_PHASES]{};              
Polarities polarityConfirmedOfLastSampleV[NO_OF_PHASES]{}; 
 
LoadStates physicalLoadState[NO_OF_DUMPLOADS]{}; 
uint16_t countLoadON[NO_OF_DUMPLOADS]{};         
 
uint32_t absenceOfDivertedEnergyCountInMC{ 0 }; 
 
uint8_t perSecondCounter{ 0 }; 
 
bool beyondStartUpPeriod{ false }; 

template< size_t N >
constexpr void initializeArray(int32_t (&array)[N], int32_t value)
{
  for (size_t i = 0; i < N; ++i)
  {
    array[i] = value;
  }
}

constexpr uint16_t getOutputPins()
{
  uint16_t output_pins{ 0 };
 
  for (const auto &loadPin : physicalLoadPin)
  {
    if (bit_read(output_pins, loadPin))
      return 0;
 
    bit_set(output_pins, loadPin);
  }
 
  if constexpr (WATCHDOG_PIN_PRESENT)
  {
    if (bit_read(output_pins, watchDogPin))
      return 0;
 
    bit_set(output_pins, watchDogPin);
  }
 
  if constexpr (RELAY_DIVERSION)
  {
    for (uint8_t idx = 0; idx < relays.size(); ++idx)
    {
      const auto relayPin = relays.get_relay(idx).get_pin();
 
      if (bit_read(output_pins, relayPin))
        return 0;
 
      bit_set(output_pins, relayPin);
    }
  }
 
  return output_pins;
}

constexpr uint16_t getInputPins()
{
  uint16_t input_pins{ 0 };
 
  if constexpr (DUAL_TARIFF)
  {
    if (bit_read(input_pins, dualTariffPin))
      return 0;
 
    bit_set(input_pins, dualTariffPin);
  }
 
  if constexpr (DIVERSION_PIN_PRESENT)
  {
    if (bit_read(input_pins, diversionPin))
      return 0;
 
    bit_set(input_pins, diversionPin);
  }
 
  if constexpr (PRIORITY_ROTATION == RotationModes::PIN)
  {
    if (bit_read(input_pins, rotationPin))
      return 0;
 
    bit_set(input_pins, rotationPin);
  }
 
  if constexpr (OVERRIDE_PIN_PRESENT)
  {
    // Add all configured override pins
    for (uint8_t i = 0; i < overridePins.size(); ++i)
    {
      const uint8_t pin = overridePins.getPin(i);
      if (bit_read(input_pins, pin))
        return 0;
 
      bit_set(input_pins, pin);
    }
  }
 
  return input_pins;
}

void initializeProcessing()
{
  initializeArray(l_DCoffset_V, 512L * 256L);  // nominal mid-point value of ADC @ x256 scale
 
  setPinsAsOutput(getOutputPins());      // set the output pins as OUTPUT
  setPinsAsInputPullup(getInputPins());  // set the input pins as INPUT_PULLUP
 
  uint8_t i{ NO_OF_DUMPLOADS };
  do
  {
    --i;
    loadPrioritiesAndState[i] = loadPrioritiesAtStartup[i];
    loadPrioritiesAndState[i] &= loadStateMask;
  } while (i);
 
  // First stop the ADC
  bit_clear(ADCSRA, ADEN);
 
  // Activate free-running mode
  ADCSRB = 0x00;
 
  // Set up the ADC to be free-running
  bit_set(ADCSRA, ADPS0);  // Set the ADC's clock to system clock / 128
  bit_set(ADCSRA, ADPS1);
  bit_set(ADCSRA, ADPS2);
 
  bit_set(ADCSRA, ADATE);  // set the Auto Trigger Enable bit in the ADCSRA register. Because
  // bits ADTS0-2 have not been set (i.e. they are all zero), the
  // ADC's trigger source is set to "free running mode".
 
  bit_set(ADCSRA, ADIE);  // set the ADC interrupt enable bit. When this bit is written
  // to one and the I-bit in SREG is set, the
  // ADC Conversion Complete Interrupt is activated.
 
  bit_set(ADCSRA, ADEN);  // Enable the ADC
 
  bit_set(ADCSRA, ADSC);  // start ADC manually first time
 
  sei();  // Enable Global Interrupts
}

void updatePortsStates()
{
  uint16_t pinsON{ 0 };
  uint16_t pinsOFF{ 0 };
 
  uint8_t i{ NO_OF_DUMPLOADS };
 
  do
  {
    --i;
    // update the local load's state.
    if (LoadStates::LOAD_OFF == physicalLoadState[i])
    {
      // setPinOFF(physicalLoadPin[i]);
      pinsOFF |= bit(physicalLoadPin[i]);
    }
    else
    {
      ++countLoadON[i];
      // setPinON(physicalLoadPin[i]);
      pinsON |= bit(physicalLoadPin[i]);
    }
  } while (i);
 
  // Apply override bitmask directly to pinsON
  pinsON |= Shared::overrideBitmask;
 
  setPinsOFF(pinsOFF);
  setPinsON(pinsON);
}

void updatePhysicalLoadStates()
{
  if constexpr (NO_OF_DUMPLOADS == 0)
  {
    return;
  }
 
  if constexpr (PRIORITY_ROTATION != RotationModes::OFF)
  {
    if (Shared::b_reOrderLoads)
    {
      uint8_t i{ static_cast< uint8_t >(NO_OF_DUMPLOADS - 1) };
      const auto temp{ loadPrioritiesAndState[i] };
      do
      {
        loadPrioritiesAndState[i] = loadPrioritiesAndState[i - 1];
        --i;
      } while (i);
      loadPrioritiesAndState[0] = temp;
 
      Shared::b_reOrderLoads = false;
    }
  }
 
  const bool bDiversionEnabled{ Shared::b_diversionEnabled };
  uint8_t idx{ NO_OF_DUMPLOADS };
  do
  {
    --idx;
    const auto iLoad{ loadPrioritiesAndState[idx] & loadStateMask };
    const bool bOverrideActive = Shared::overrideBitmask & (1U << physicalLoadPin[iLoad]);
    physicalLoadState[iLoad] = bDiversionEnabled && (bOverrideActive || (loadPrioritiesAndState[idx] & loadStateOnBit)) ? LoadStates::LOAD_ON : LoadStates::LOAD_OFF;
  } while (idx);
}

void processPolarity(const uint8_t phase, const int16_t rawSample)
{
  // remove DC offset from each raw voltage sample by subtracting the accurate value
  // as determined by its associated LP filter.
  l_sampleVminusDC[phase] = (static_cast< int32_t >(rawSample) << 8) - l_DCoffset_V[phase];
  polarityOfMostRecentSampleV[phase] = (l_sampleVminusDC[phase] > 0) ? Polarities::POSITIVE : Polarities::NEGATIVE;
}

void processCurrentRawSample(const uint8_t phase, const int16_t rawSample)
{
  // extra items for an LPF to improve the processing of data samples from CT1
  static int32_t lpf_long[NO_OF_PHASES]{};  // new LPF, for offsetting the behaviour of CTx as a HPF
 
  // remove most of the DC offset from the current sample (the precise value does not matter)
  int32_t sampleIminusDC = (static_cast< int32_t >(rawSample - i_DCoffset_I_nom)) << 8;
 
  // extra filtering to offset the HPF effect of CTx
  const int32_t last_lpf_long{ lpf_long[phase] };
  lpf_long[phase] += alpha * (sampleIminusDC - last_lpf_long);
  sampleIminusDC += (lpf_gain * lpf_long[phase]);
 
  // calculate the "real power" in this sample pair and add to the accumulated sum
  const int32_t filtV_div4 = l_sampleVminusDC[phase] >> 2;  // reduce to 16-bits (now x64, or 2^6)
  const int32_t filtI_div4 = sampleIminusDC >> 2;           // reduce to 16-bits (now x64, or 2^6)
  int32_t instP = filtV_div4 * filtI_div4;                  // 32-bits (now x4096, or 2^12)
  instP >>= 12;                                             // scaling is now x1, as for Mk2 (V_ADC x I_ADC)
 
  l_sumP[phase] += instP;                // cumulative power, scaling as for Mk2 (V_ADC x I_ADC)
  l_sumP_atSupplyPoint[phase] += instP;  // cumulative power, scaling as for Mk2 (V_ADC x I_ADC)
}

void confirmPolarity(const uint8_t phase)
{
  static uint8_t count[NO_OF_PHASES]{};
 
  if (polarityOfMostRecentSampleV[phase] == polarityConfirmedOfLastSampleV[phase])
  {
    count[phase] = 0;
    return;
  }
 
  if (++count[phase] > PERSISTENCE_FOR_POLARITY_CHANGE)
  {
    count[phase] = 0;
    polarityConfirmed[phase] = polarityOfMostRecentSampleV[phase];
  }
}

void processVoltage(const uint8_t phase)
{
  // for the Vrms calculation (for datalogging only)
  const int32_t filtV_div4{ l_sampleVminusDC[phase] >> 2 };  // reduce to 16-bits (now x64, or 2^6)
  int32_t inst_Vsquared{ filtV_div4 * filtV_div4 };          // 32-bits (now x4096, or 2^12)
 
  if constexpr (DATALOG_PERIOD_IN_SECONDS > 10)
  {
    inst_Vsquared >>= 16;  // scaling is now x1/16 (V_ADC x I_ADC)
  }
  else
  {
    inst_Vsquared >>= 12;  // scaling is now x1 (V_ADC x I_ADC)
  }
 
  l_sum_Vsquared[phase] += inst_Vsquared;  // cumulative V^2 (V_ADC x I_ADC)
  //
  // store items for use during next loop
  l_cumVdeltasThisCycle[phase] += l_sampleVminusDC[phase];           // for use with LP filter
  polarityConfirmedOfLastSampleV[phase] = polarityConfirmed[phase];  // for identification of half cycle boundaries
  ++n_samplesDuringThisMainsCycle[phase];                            // for real power calculations
}

void processStartUp(const uint8_t phase)
{
  // wait until the DC-blocking filters have had time to settle
  if (millis() <= (initialDelay + startUpPeriod))
  {
    return;  // still settling, do nothing
  }
 
  // the DC-blocking filters have had time to settle
  beyondStartUpPeriod = true;
  l_sumP[phase] = 0;
  l_sumP_atSupplyPoint[phase] = 0;
  n_samplesDuringThisMainsCycle[phase] = 0;
  i_sampleSetsDuringThisDatalogPeriod = 0;
 
  n_lowestNoOfSampleSetsPerMainsCycle = UINT8_MAX;
  // can't say "Go!" here 'cos we're in an ISR!
}

void proceedHighEnergyLevel()
{
  bool bOK_toAddLoad{ true };
  const auto tempLoad{ nextLogicalLoadToBeAdded() };
 
  if (tempLoad == NO_OF_DUMPLOADS)
  {
    return;
  }
 
  // a load which is now OFF has been identified for potentially being switched ON
  if (b_recentTransition)
  {
    // During the post-transition period, any increase in the energy level is noted.
    f_upperEnergyThreshold = f_energyInBucket_main;
 
    // the energy thresholds must remain within range
    if (f_upperEnergyThreshold > f_capacityOfEnergyBucket_main)
    {
      f_upperEnergyThreshold = f_capacityOfEnergyBucket_main;
    }
 
    // Only the active load may be switched during this period. All other loads must
    // wait until the recent transition has had sufficient opportunity to take effect.
    bOK_toAddLoad = (tempLoad == activeLoad);
  }
 
  if (bOK_toAddLoad)
  {
    loadPrioritiesAndState[tempLoad] |= loadStateOnBit;
    activeLoad = tempLoad;
    postTransitionCount = 0;
    b_recentTransition = true;
  }
}

void proceedLowEnergyLevel()
{
  bool bOK_toRemoveLoad{ true };
  const auto tempLoad{ nextLogicalLoadToBeRemoved() };
 
  if (tempLoad == NO_OF_DUMPLOADS)
  {
    return;
  }
 
  // a load which is now ON has been identified for potentially being switched OFF
  if (b_recentTransition)
  {
    // During the post-transition period, any decrease in the energy level is noted.
    f_lowerEnergyThreshold = f_energyInBucket_main;
 
    // the energy thresholds must remain within range
    if (f_lowerEnergyThreshold < 0)
    {
      f_lowerEnergyThreshold = 0;
    }
 
    // Only the active load may be switched during this period. All other loads must
    // wait until the recent transition has had sufficient opportunity to take effect.
    bOK_toRemoveLoad = (tempLoad == activeLoad);
  }
 
  if (bOK_toRemoveLoad)
  {
    loadPrioritiesAndState[tempLoad] &= loadStateMask;
    activeLoad = tempLoad;
    postTransitionCount = 0;
    b_recentTransition = true;
  }
}

void processStartNewCycle()
{
  // Restrictions apply for the period immediately after a load has been switched.
  // Here the b_recentTransition flag is checked and updated as necessary.
  // if (b_recentTransition)
  //   b_recentTransition = (++postTransitionCount < POST_TRANSITION_MAX_COUNT);
  // for optimization, the next line is equivalent to the two lines above
  b_recentTransition &= (++postTransitionCount < POST_TRANSITION_MAX_COUNT);
 
  if (f_energyInBucket_main > f_midPointOfEnergyBucket_main)
  {
    // the energy state is in the upper half of the working range
    f_lowerEnergyThreshold = f_lowerThreshold_default;  // reset the "opposite" threshold
    if (f_energyInBucket_main > f_upperEnergyThreshold)
    {
      // Because the energy level is high, some action may be required
      proceedHighEnergyLevel();
    }
  }
  else
  {
    // the energy state is in the lower half of the working range
    f_upperEnergyThreshold = f_upperThreshold_default;  // reset the "opposite" threshold
    if (f_energyInBucket_main < f_lowerEnergyThreshold)
    {
      // Because the energy level is low, some action may be required
      proceedLowEnergyLevel();
    }
  }
 
  updatePhysicalLoadStates();  // allows the logical-to-physical mapping to be changed
 
  updatePortsStates();  // update the control ports for each of the physical loads
 
  if (loadPrioritiesAndState[0] & loadStateOnBit)
  {
    absenceOfDivertedEnergyCountInMC = 0;
  }
  else
  {
    ++absenceOfDivertedEnergyCountInMC;
  }
 
  // Now that the energy-related decisions have been taken, min and max limits can now
  // be applied  to the level of the energy bucket. This is to ensure correct operation
  // when conditions change, i.e. when import changes to export, and vice versa.
  //
  if (f_energyInBucket_main > f_capacityOfEnergyBucket_main)
  {
    f_energyInBucket_main = f_capacityOfEnergyBucket_main;
  }
  else if (f_energyInBucket_main < 0)
  {
    f_energyInBucket_main = 0;
  }
}

void processMinusHalfCycle(const uint8_t phase)
{
  // This is a convenient point to update the Low Pass Filter for removing the DC
  // component from the phase that is being processed.
  // The portion which is fed back into the integrator is approximately one percent
  // of the average offset of all the SampleVs in the previous mains cycle.
  //
  l_DCoffset_V[phase] += (l_cumVdeltasThisCycle[phase] >> 12);
  l_cumVdeltasThisCycle[phase] = 0;
 
  // To ensure that this LP filter will always start up correctly when 240V AC is
  // available, its output value needs to be prevented from drifting beyond the likely range
  // of the voltage signal.
  //
  if (l_DCoffset_V[phase] < l_DCoffset_V_min)
  {
    l_DCoffset_V[phase] = l_DCoffset_V_min;
  }
  else if (l_DCoffset_V[phase] > l_DCoffset_V_max)
  {
    l_DCoffset_V[phase] = l_DCoffset_V_max;
  }
}

uint8_t nextLogicalLoadToBeAdded()
{
  for (uint8_t index = 0; index < NO_OF_DUMPLOADS; ++index)
  {
    if (0x00 == (loadPrioritiesAndState[index] & loadStateOnBit))
    {
      return (index);
    }
  }
 
  return (NO_OF_DUMPLOADS);
}

uint8_t nextLogicalLoadToBeRemoved()
{
  uint8_t index{ NO_OF_DUMPLOADS };
  do
  {
    if (loadPrioritiesAndState[--index] & loadStateOnBit)
    {
      return (index);
    }
  } while (index);
 
  return (NO_OF_DUMPLOADS);
}

void processLatestContribution(const uint8_t phase)
{
  // for efficiency, the energy scale is Joules * SUPPLY_FREQUENCY
  // add the latest energy contribution to the main energy accumulator
  f_energyInBucket_main += (l_sumP[phase] / n_samplesDuringThisMainsCycle[phase]) * f_powerCal[phase];
 
  // apply any adjustment that is required.
  if (0 == phase)
  {
    // If diversion hasn't started yet, use start threshold, otherwise use regular offset
    if (!b_diversionStarted)
    {
      f_energyInBucket_main -= DIVERSION_START_THRESHOLD_WATTS;
 
      // Check if we've exceeded the threshold to start diversion
      if (f_energyInBucket_main > f_upperThreshold_default)
      {
        b_diversionStarted = true;
        // Once started, we divert all surplus according to the configured fixed offset
      }
    }
    else
    {
      // When diversion is already started, apply normal export offset if configured
      // Comment or remove this if you want to divert ALL surplus once started
      f_energyInBucket_main -= REQUIRED_EXPORT_IN_WATTS;
    }
 
    if (++perSecondCounter == SUPPLY_FREQUENCY)
    {
      perSecondCounter = 0;
 
      if (absenceOfDivertedEnergyCountInMC > SUPPLY_FREQUENCY)
      {
        ++Shared::absenceOfDivertedEnergyCountInSeconds;
        // Reset diversion state if we've had no diversion for a full second
        b_diversionStarted = false;
      }
      else
        Shared::absenceOfDivertedEnergyCountInSeconds = 0;
    }
 
    Shared::b_newMainsCycle = true;  //  a 50 Hz 'tick' for use by the main code
  }
  // Applying max and min limits to the main accumulator's level
  // is deferred until after the energy related decisions have been taken
  //
}

void processDataLogging()
{
  if (++n_cycleCountForDatalogging < DATALOG_PERIOD_IN_MAINS_CYCLES)
  {
    return;  // data logging period not yet reached
  }
 
  n_cycleCountForDatalogging = 0;
 
  uint8_t phase{ NO_OF_PHASES };
  do
  {
    --phase;
    Shared::copyOf_sumP_atSupplyPoint[phase] = l_sumP_atSupplyPoint[phase];
    l_sumP_atSupplyPoint[phase] = 0;
 
    Shared::copyOf_sum_Vsquared[phase] = l_sum_Vsquared[phase];
    l_sum_Vsquared[phase] = 0;
  } while (phase);
 
  uint8_t i{ NO_OF_DUMPLOADS };
  do
  {
    --i;
    Shared::copyOf_countLoadON[i] = countLoadON[i];
    countLoadON[i] = 0;
  } while (i);
 
  Shared::copyOf_sampleSetsDuringThisDatalogPeriod = i_sampleSetsDuringThisDatalogPeriod;  // (for diags only)
  Shared::copyOf_lowestNoOfSampleSetsPerMainsCycle = n_lowestNoOfSampleSetsPerMainsCycle;  // (for diags only)
  Shared::copyOf_energyInBucket_main = f_energyInBucket_main;                              // (for diags only)
 
  n_lowestNoOfSampleSetsPerMainsCycle = UINT8_MAX;
  i_sampleSetsDuringThisDatalogPeriod = 0;
 
  // signal the main processor that logging data are available
  // we skip the period from start to running stable
  Shared::b_datalogEventPending = beyondStartUpPeriod;
}

void processPlusHalfCycle(const uint8_t phase)
{
  processLatestContribution(phase);  // runs at 6.6 ms intervals
 
  // A performance check to monitor and display the minimum number of sets of
  // ADC samples per mains cycle, the expected number being 20ms / (104us * 6) = 32.05
  //
  if (0 == phase)
  {
    if (n_samplesDuringThisMainsCycle[phase] < n_lowestNoOfSampleSetsPerMainsCycle)
    {
      n_lowestNoOfSampleSetsPerMainsCycle = n_samplesDuringThisMainsCycle[phase];
    }
 
    processDataLogging();
  }
 
  l_sumP[phase] = 0;
  n_samplesDuringThisMainsCycle[phase] = 0;
}

void processRawSamples(const uint8_t phase)
{
  // The raw V and I samples are processed in "phase pairs"
  const auto &lastPolarity{ polarityConfirmedOfLastSampleV[phase] };
 
  if (Polarities::POSITIVE == polarityConfirmed[phase])
  {
    // the polarity of this sample is positive
    if (Polarities::POSITIVE != lastPolarity)
    {
      // This is the start of a new +ve half cycle, for this phase, just after the zero-crossing point.
      if (beyondStartUpPeriod)
      {
        processPlusHalfCycle(phase);
      }
      else
      {
        processStartUp(phase);
      }
    }
 
    // still processing samples where the voltage is POSITIVE ...
    // check to see whether the trigger device can now be reliably armed
    if ((0 == phase) && beyondStartUpPeriod && (2 == n_samplesDuringThisMainsCycle[0]))  // lower value for larger sample set
    {
      // This code is executed once per 20mS, shortly after the start of each new mains cycle on phase 0.
      processStartNewCycle();
    }
  }
  else
  {
    // the polarity of this sample is negative
    if (Polarities::NEGATIVE != lastPolarity)
    {
      // This is the start of a new -ve half cycle (just after the zero-crossing point)
      processMinusHalfCycle(phase);
    }
  }
}

void processVoltageRawSample(const uint8_t phase, const int16_t rawSample)
{
  processPolarity(phase, rawSample);
  confirmPolarity(phase);
 
  processRawSamples(phase);  // deals with aspects that only occur at particular stages of each mains cycle
 
  processVoltage(phase);
 
  if (phase == 0)
  {
    ++i_sampleSetsDuringThisDatalogPeriod;
  }
}

void printParamsForSelectedOutputMode()
{
  // display relevant settings for selected output mode
  DBUG(F("Output mode:    "));
  if (OutputModes::NORMAL == outputMode)
  {
    DBUGLN(F("normal"));
  }
  else
  {
    DBUGLN(F("anti-flicker"));
    DBUG(F("\toffsetOfEnergyThresholds  = "));
    DBUGLN(f_offsetOfEnergyThresholdsInAFmode);
  }
  DBUG(F("\tf_capacityOfEnergyBucket_main = "));
  DBUGLN(f_capacityOfEnergyBucket_main);
  DBUG(F("\tf_lowerEnergyThreshold   = "));
  DBUGLN(f_lowerThreshold_default);
  DBUG(F("\tf_upperEnergyThreshold   = "));
  DBUGLN(f_upperThreshold_default);
}

ISR(ADC_vect)
{
  static uint8_t sample_index{ 0 };
  int16_t rawSample;
 
  switch (sample_index)
  {
    case 0:
      rawSample = ADC;                  // store the ADC value (this one is for Voltage L1)
      ADMUX = bit(REFS0) + sensorV[1];  // the conversion for I1 is already under way
      ++sample_index;                   // increment the control flag
      //
      processVoltageRawSample(0, rawSample);
      break;
    case 1:
      rawSample = ADC;                  // store the ADC value (this one is for Current L1)
      ADMUX = bit(REFS0) + sensorI[1];  // the conversion for V2 is already under way
      ++sample_index;                   // increment the control flag
      //
      processCurrentRawSample(0, rawSample);
      break;
    case 2:
      rawSample = ADC;                  // store the ADC value (this one is for Voltage L2)
      ADMUX = bit(REFS0) + sensorV[2];  // the conversion for I2 is already under way
      ++sample_index;                   // increment the control flag
      //
      processVoltageRawSample(1, rawSample);
      break;
    case 3:
      rawSample = ADC;                  // store the ADC value (this one is for Current L2)
      ADMUX = bit(REFS0) + sensorI[2];  // the conversion for V3 is already under way
      ++sample_index;                   // increment the control flag
      //
      processCurrentRawSample(1, rawSample);
      break;
    case 4:
      rawSample = ADC;                  // store the ADC value (this one is for Voltage L3)
      ADMUX = bit(REFS0) + sensorV[0];  // the conversion for I3 is already under way
      ++sample_index;                   // increment the control flag
      //
      processVoltageRawSample(2, rawSample);
      break;
    case 5:
      rawSample = ADC;                  // store the ADC value (this one is for Current L3)
      ADMUX = bit(REFS0) + sensorI[0];  // the conversion for V1 is already under way
      sample_index = 0;                 // reset the control flag
      //
      processCurrentRawSample(2, rawSample);
      break;
    default:
      sample_index = 0;  // to prevent lockup (should never get here)
  }
}  // end of ISR