<commit_before>/*
The OpenTRV project licenses this file to you
under the Apache Licence, Version 2.0 (the "Licence");
you may not use this file except in compliance
with the Licence. You may obtain a copy of the Licence at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the Licence is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the Licence for the
specific language governing permissions and limitations
under the Licence.

Author(s) / Copyright (s): <NAME> 2016
*/

/*
 * OpenTRV radiator valve basic parameters.
 */

#ifndef ARDUINO_LIB_OTRADVALVE_PARAMETERS_H
#define ARDUINO_LIB_OTRADVALVE_PARAMETERS_H


#include <stddef.h>
#include <stdint.h>
#include <OTV0p2Base.h>


// Use namespaces to help avoid collisions.
namespace OTRadValve
    {


    // Minimum and maximum bounds target temperatures; degrees C/Celsius/centigrade, strictly positive.
    // Minimum is some way above 0C to avoid freezing pipework even with small measurement errors and non-uniform temperatures.
    // Maximum is set a little below boiling/100C for DHW applications for safety.
    // Setbacks and uplifts cannot move temperature targets outside this range for safety.
    static constexpr uint8_t MIN_TARGET_C = 5; // Minimum temperature setting allowed (to avoid freezing, allowing for offsets at temperature sensor, etc).
    static constexpr uint8_t MAX_TARGET_C = 95; // Maximum temperature setting allowed (eg for DHW).

    // 18C is a safe room temperature even for the slightly infirm according to NHS England 2014:
    //    http://www.nhs.uk/Livewell/winterhealth/Pages/KeepWarmKeepWell.aspx
    // Small babies have relatively poor thermoregulation so a device with setbacks may not be suitable for them, else ~18C is good:
    //    http://www.nhs.uk/conditions/pregnancy-and-baby/pages/reducing-risk-cot-death.aspx
    // so could possibly be marked explicitly on the control.
    // 21C is recommended living temperature in retirement housing:
    //     http://ipc.brookes.ac.uk/publications/pdf/Identifying_the_health_gain_from_retirement_housing.pdf
    static constexpr uint8_t SAFE_ROOM_TEMPERATURE = 18; // Safe for most purposes.

    // Templated set of constant parameters derived together from common arguments.
    // Can be tweaked to parameterise different products,
    // or to make a bigger shift such as to DHW control.
    //   * ecoMin  basic target frost-protection temperature (C).
    //   * comMin  minimum temperature in comfort mode at any time, even for frost protection (C).
    //   * ecoWarm  'warm' in ECO mode.
    //   * comWarm  'warm' in comfort mode.
    template<uint8_t ecoMinC, uint8_t comMinC, uint8_t ecoWarmC, uint8_t comWarmC,
             uint8_t bakeLiftC = 10>
    class ValveControlParameters
        {
        public:
            // Basic frost protection threshold.
            // Must be in range [MIN_TARGET_C,MAX_TARGET_C[.
            static constexpr uint8_t FROST = OTV0P2BASE::fnmin(OTV0P2BASE::fnmax(ecoMinC, MIN_TARGET_C), MAX_TARGET_C);
            // Frost protection threshold temperature in eco-friendly / ECO-bias mode.
            // Must be in range [MIN_TARGET_C,FROST_COM[.
            static constexpr uint8_t FROST_ECO = FROST;
            // Frost protection threshold temperature in comfort mode, eg to be safer for someone infirm.
            // Must be in range ]FROST_ECO,MAX_TARGET_C].
            static constexpr uint8_t FROST_COM = OTV0P2BASE::fnmax(OTV0P2BASE::fnmin(comMinC, MAX_TARGET_C), FROST_ECO);

            // Warm temperatures.
            // Warm temperature in eco-friendly / ECO-bias mode.
            // Must be in range [FROST_ECO+1,MAX_TARGET_C].
            static constexpr uint8_t WARM_ECO = OTV0P2BASE::fnmax(OTV0P2BASE::fnmin(ecoWarmC, MAX_TARGET_C), (uint8_t)(FROST_ECO+1));
            // Warm temperature in comfort mode.
            // Must be in range [FROST_COM+1,MAX_TARGET_C].
            static constexpr uint8_t WARM_COM = OTV0P2BASE::fnmax(OTV0P2BASE::fnmin(comWarmC, MAX_TARGET_C), (uint8_t)(FROST_COM+1));
            // Default 'warm' at a 'safe' temperature.
            static constexpr uint8_t WARM = OTV0P2BASE::fnmax(WARM_ECO, SAFE_ROOM_TEMPERATURE);

            // Typical markings for a temperature scale.
            // Scale can run from eco warm -1 to comfort warm + 1, eg: * 16 17 18 >19< 20 21 22 BOOST
            // Bottom of range for adjustable-base-temperature systems.
            static constexpr uint8_t TEMP_SCALE_MIN = (WARM_ECO-1);
            // Middle of range for adjustable-base-temperature systems; should be 'eco' baised.
            static constexpr uint8_t TEMP_SCALE_MID = ((WARM_ECO + WARM_COM + 1)/2);
            // Top of range for adjustable-base-temperature systems.
            static constexpr uint8_t TEMP_SCALE_MAX = (WARM_COM+1);

            // Raise target by this many degrees in 'BAKE' mode (strictly positive).
            // DHD20160927 TODO-980 raised from 5 to 10 to ensure very rarely fails to trigger in in shoulder season.
            static constexpr uint8_t BAKE_UPLIFT = bakeLiftC;

            // Initial minor setback degrees C (strictly positive).  Note that 1C heating setback may result in ~8% saving in the UK.
            // This may be the maximum setback applied with a comfort bias for example.
            static constexpr uint8_t SETBACK_DEFAULT = 1;
            // Enhanced setback, eg in eco mode, for extra energy savings.  Not more than SETBACK_FULL.
            static constexpr uint8_t SETBACK_ECO = 1+SETBACK_DEFAULT;
            // Full setback degrees C (strictly positive and significantly, ie several degrees, greater than SETBACK_DEFAULT, less than MIN_TARGET_C).
            // Deeper setbacks increase energy savings at the cost of longer times to return to target temperatures.
            // See also (recommending 13F/7C setback to 55F/12C): https://www.mge.com/images/pdf/brochures/residential/setbackthermostat.pdf
            // See also (suggesting for an 8hr setback, 1F set-back = 1% energy savings): http://joneakes.com/jons-fixit-database/1270-How-far-back-should-a-set-back-thermostat-be-set
            // See comments on savings, comfort and condensation with setbacks > ~4C: https://www.cmhc-schl.gc.ca/en/co/grho/grho_002.cfm
            // This must set back to no more than than MIN_TARGET_C to avoid problems with unsigned arithmetic.
            static constexpr uint8_t SETBACK_FULL = 4;
        };

    // Mechanism to make ValveControlParameters available at run-time.
    class ValveControlParametersRTBase
      {
      public:
        const uint8_t BAKE_UPLIFT;
        const uint8_t SETBACK_DEFAULT;<commit_msg>improved comments and ties to external doc<commit_after>/*
The OpenTRV project licenses this file to you
under the Apache Licence, Version 2.0 (the "Licence");
you may not use this file except in compliance
with the Licence. You may obtain a copy of the Licence at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the Licence is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the Licence for the
specific language governing permissions and limitations
under the Licence.

Author(s) / Copyright (s): <NAME> 2016
*/

/*
 * OpenTRV radiator valve basic parameters.
 */

#ifndef ARDUINO_LIB_OTRADVALVE_PARAMETERS_H
#define ARDUINO_LIB_OTRADVALVE_PARAMETERS_H


#include <stddef.h>
#include <stdint.h>
#include <OTV0p2Base.h>


// Use namespaces to help avoid collisions.
namespace OTRadValve
    {


    // Minimum and maximum bounds target temperatures; degrees C/Celsius/centigrade, strictly positive.
    // Minimum is some way above 0C to avoid freezing pipework even with small measurement errors and non-uniform temperatures.
    // Maximum is set a little below boiling/100C for DHW applications for safety.
    // Setbacks and uplifts cannot move temperature targets outside this range for safety.
    static constexpr uint8_t MIN_TARGET_C = 5; // Minimum temperature setting allowed (to avoid freezing, allowing for offsets at temperature sensor, etc).
    static constexpr uint8_t MAX_TARGET_C = 95; // Maximum temperature setting allowed (eg for DHW).

    // 18C is a safe room temperature even for the slightly infirm according to NHS England 2014:
    //    http://www.nhs.uk/Livewell/winterhealth/Pages/KeepWarmKeepWell.aspx
    // Small babies have relatively poor thermoregulation so a device with setbacks may not be suitable for them, else ~18C is good:
    //    http://www.nhs.uk/conditions/pregnancy-and-baby/pages/reducing-risk-cot-death.aspx
    // so could possibly be marked explicitly on the control.
    // 21C is recommended living temperature in retirement housing:
    //     http://ipc.brookes.ac.uk/publications/pdf/Identifying_the_health_gain_from_retirement_housing.pdf
    static constexpr uint8_t SAFE_ROOM_TEMPERATURE = 18; // Safe for most purposes.

    // Templated set of constant parameters derived together from common arguments.
    // Can be tweaked to parameterise different products,
    // or to make a bigger shift such as to DHW control.
    //   * ecoMin  basic target frost-protection temperature (C).
    //   * comMin  minimum temperature in comfort mode at any time, even for frost protection (C).
    //   * ecoWarm  'warm' in ECO mode.
    //   * comWarm  'warm' in comfort mode.
    template<uint8_t ecoMinC, uint8_t comMinC, uint8_t ecoWarmC, uint8_t comWarmC,
             uint8_t bakeLiftC = 10>
    class ValveControlParameters
        {
        public:
            // Basic frost protection threshold.
            // Must be in range [MIN_TARGET_C,MAX_TARGET_C[.
            static constexpr uint8_t FROST = OTV0P2BASE::fnmin(OTV0P2BASE::fnmax(ecoMinC, MIN_TARGET_C), MAX_TARGET_C);
            // Frost protection threshold temperature in eco-friendly / ECO-bias mode.
            // Must be in range [MIN_TARGET_C,FROST_COM[.
            static constexpr uint8_t FROST_ECO = FROST;
            // Frost protection threshold temperature in comfort mode, eg to be safer for someone infirm.
            // Must be in range ]FROST_ECO,MAX_TARGET_C].
            static constexpr uint8_t FROST_COM = OTV0P2BASE::fnmax(OTV0P2BASE::fnmin(comMinC, MAX_TARGET_C), FROST_ECO);

            // Warm temperatures.
            // Warm temperature in eco-friendly / ECO-bias mode.
            // Must be in range [FROST_ECO+1,MAX_TARGET_C].
            static constexpr uint8_t WARM_ECO = OTV0P2BASE::fnmax(OTV0P2BASE::fnmin(ecoWarmC, MAX_TARGET_C), (uint8_t)(FROST_ECO+1));
            // Warm temperature in comfort mode.
            // Must be in range [FROST_COM+1,MAX_TARGET_C].
            static constexpr uint8_t WARM_COM = OTV0P2BASE::fnmax(OTV0P2BASE::fnmin(comWarmC, MAX_TARGET_C), (uint8_t)(FROST_COM+1));
            // Default 'warm' at a 'safe' temperature.
            static constexpr uint8_t WARM = OTV0P2BASE::fnmax(WARM_ECO, SAFE_ROOM_TEMPERATURE);

            // Typical markings for a temperature scale.
            // Scale can run from eco warm -1 to comfort warm + 1, eg: * 16 17 18 >19< 20 21 22 BOOST
            // Bottom of range for adjustable-base-temperature systems.
            static constexpr uint8_t TEMP_SCALE_MIN = (WARM_ECO-1);
            // Middle of range for adjustable-base-temperature systems; should be 'eco' baised.
            static constexpr uint8_t TEMP_SCALE_MID = ((WARM_ECO + WARM_COM + 1)/2);
            // Top of range for adjustable-base-temperature systems.
            static constexpr uint8_t TEMP_SCALE_MAX = (WARM_COM+1);

            // Raise target by this many degrees in 'BAKE' mode (strictly positive).
            // DHD20160927 TODO-980 raised from 5 to 10 to ensure very rarely fails to trigger in in shoulder season.
            static constexpr uint8_t BAKE_UPLIFT = bakeLiftC;

            // Initial minor setback degrees C (strictly positive).  Note that 1C heating setback may result in ~8% saving in the UK.
            // This may be the maximum setback applied with a comfort bias for example.
            static constexpr uint8_t SETBACK_DEFAULT = 1;
            // Enhanced setback, eg in eco mode, for extra energy savings.  Not more than SETBACK_FULL.
            static constexpr uint8_t SETBACK_ECO = 1+SETBACK_DEFAULT;
            // Full setback degrees C (strictly positive and significantly, ie several degrees, greater than SETBACK_DEFAULT, less than MIN_TARGET_C).
            // Deeper setbacks increase energy savings at the cost of longer times to return to target temperatures.
            // See also (recommending 13F/7C setback to 55F/12C): https://www.mge.com/images/pdf/brochures/residential/setbackthermostat.pdf
            // See also (suggesting for an 8hr setback, 1F set-back = 1% energy savings): http://joneakes.com/jons-fixit-database/1270-How-far-back-should-a-set-back-thermostat-be-set
            // See comments on savings, comfort and condensation with setbacks > ~4C (eg ~15% saving for 6C setback overnight): https://www.cmhc-schl.gc.ca/en/co/grho/grho_002.cfm
            // This must set back to no more than than MIN_TARGET_C to avoid problems with unsigned arithmetic.
            static constexpr uint8_t SETBACK_FULL = 4;
        };

    // Mechanism to make ValveControlParameters available at run-time.
    class ValveControlParametersRTBase
      {
      public:
        const uint8_t BAKE_UPLIFT;
        const uint8_t SETBACK_DEFAULT;
{'fraction_non_alphanumeric': 0.07431293514107731, 'fraction_numerical': 0.02000732869182851, 'mean_word_length': 2.8723041997729855, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 17, 'https://': 4, 'lorem ipsum': 0, 'www.': 10, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2553970', 'n_tokens_mistral': 4263, 'n_tokens_neox': 3926, 'n_words': 1418}