Types, values and functions for a smart home project. More...

#include "weBatt.h"
#include "weStateM.h"
#include "sweetHome.h"
#include "weGPIOd.h"
#include "mqttHome.h"
#include "we1wire.h"
#include <errno.h>
#include "weModbus.h"

Macros
#define	BATu
	Battery unload (hi active via open drain; gr/gr-ws)

#define	BEFORE_RISE
	Before sunrise timer offset. More...

#define	CHS_CP_OFFSET
	CP signal PWM correction offset. More...

#define	CONcarLd
	Contactor (relay) power to car is ON (low active)

#define	CONcarRq
	Car (CP resistor 2k7) connected / ready (low active)

#define	HYPr
	Bat. to /ref Hippogreiff (dto. ws/gn)

#define	INVu
	two relays switching unused inverter input plugs +&-

#define	isOnPPSrel()
	Check if the phase power switch control relay is on.

#define	LED9
	life LED hi active

#define	LEDx
	other LED hi active (currently unused, always on)

#define	offPort(N)
	Switch port N off. More...

#define	offRel(N)
	Switch relay N off. More...

#define	onPort(N)
	Switch port N on. More...

#define	onRel(N)
	Switch relay N on. More...

#define	PCK_POWER_IND_MAX
	phase packet control limit 200%

#define	PCK_POWER_LIM_DEF
	phase packet default limit 3,6kW

#define	PCK_POWER_LIM_MAX
	phase packet max. limit

#define	PCK_POWER_REL
	phase packet switch control relay

#define	PDEL_BALEND
	Minimal delivery power to leave ballast loading SFC. More...

#define	PDEL_BALINC
	Maximal delivery power not to add ballast. More...

#define	PDEL_BALRED
	Minimal delivery power to reduce ballast. More...

#define	PDEL_SGCONS
	Minimal delivery power (W) to signal consumer. More...

#define	PDEL_SGGIVE
	Maximal delivery power to signal give away. More...

#define	PH_P_SSR1
	Phase packet switch SSR1 (heater element 1)

#define	PH_P_SSR2
	Phase packet switch SSR2 (heater element 2)

#define	POWH
	Power module voltage control (li/br-ws). More...

#define	PWMcarLd
	PWM to control max. car load current (per phase)

#define	SENS0PATH
	Temperature of water tank (top level). More...

#define	SENS1PATH
	Temperature of hot water pipe (from tank top).since 12 23: 28-6fb4d443009b. More...

#define	SENS2PATH
	Temperature of water tank (bottom level). More...

#define	switchPPSrel(V)
	Actuate phase power switch control relay. More...

#define	switchRel(N, V)
	Switch relay N on or off. More...

Functions
void	changeBatLoadPWM (int pwmChg)
	Change battery loader module PWM. More...

void	logBatteryState ()
	Log battery state on outLog as line with time stamp. More...

uint8_t	pckSwPec (float power)
	Set and get package switch percentage by power. More...

void	setBatLoadPWM (int pwm)
	Set battery loader module PWM. More...

uint8_t	setPckSwPerc (uint8_t perc)
	Set package switch percentage. More...

float	setPhPckLimit (float powerLimit)
	Set and get package switch power limit. More...

void	switchBatToStepUp (uint8_t on)
	Switch battery to step up converter. More...

void	switchHotWpump (uint8_t const on)
	Hot water comfort pump turn on/off. More...

Variables
state_t	batCntBalSeq
	Battery controlled load as ballast.

state_t	batCntLodSeq
	Battery loading and keeping.

state_t	batKeepInh
	Inhibit battery keep alive loading. More...

int	batLoadAllowed
	Battery loading allowed. More...

volatile uint8_t	batLodTst
	Battery loader test modus. More...

volatile int	batModPWM
	The actual battery load module's PWM input. More...

int	batUnloadAllowed
	Battery unload allowed. More...

state_t	batUnloadSeq
	Battery controlled unload via inverter.

uint8_t	batVoltValid
	The measured battery voltage is valid. More...

state_t	befRiseTimer
	Before sunrise timer. More...

state_t	consumeGiveHyst
	Give away hysteresis. More...

state_t	consumeGiveSFC
	Give away state machine / SFC. More...

state_t	dawnTimer
	Dawn timer. More...

state_t	duskTimer
	Dusk timer. More...

uint8_t	heaterAllowed
	phase packet load enabled (always)

int	hippoSwitchMode
	Hippogreiff on/off times. More...

state_t	load250Wcont
	Controlled load SFC.

volatile int	nologBatCap
	Control logging inhibit charging battery due to capacity limit. More...

volatile uint8_t	phPckCnt
	current switch state duration counter

volatile uint8_t	phPckOff
	current phase packet switch OFF duration

volatile uint8_t	phPckOn
	current phase packet switch ON duration

volatile uint8_t	phPckRelOffDelay
	PPS relay off delay.

volatile uint8_t	phPckS2
	heater 2 pps switch state: 0 off; 1 on

volatile uint8_t	phPckSw
	phase packet switch state: 0 off; 1 on

volatile uint8_t	phPckSwIndex
	Actual index (0..200%) determining power. More...

volatile uint8_t	phPpow2
	heater 2 power * 50% (0:0% .. 2:100%)

oneWireDevice_t	sensors [3]
	The 1-wire sensors used.

state_t	solarPowerHyst
	Solar power producer hysteresis. More...

state_t	sunriseTimer
	Sunrise timer. More...

state_t	sunsetTimer
	Sunset timer. More...

state_t	wouldGive250WHyst
	Would give away 250W hysteresis. More...

state_t	wouldGiveAwayHyst
	Would give away hysteresis. More...

Detailed Description

Types, values and functions for a smart home project.

Copyright (c)  2018 - 2025  Albrecht Weinert
weinert-automation.de       a-weinert.de
 
    /         /      /\
   /         /___   /  \      |
   \        /____\ /____\ |  _|__
    \  /\  / \    /      \|   |
     \/  \/   \__/        \__/|_                                 

Revision history

Rev. 94 2.10.2025
Rev.  99 29.01.2018 : load module voltage handling added
Rev. 148 16.06.2018 : battery ballast handling improved, Hippogreiff relay
Rev. 170 24.07.2018 : temperature sensors documentation
Rev. 190 12.02.2019 : remove 4 status relay output as (minimal) preparation
                      for VDE-AR-N 4105 evaluation and inverter cut off
Rev. 218 07.09.2019 : MQTT excerpted to mqttHome.h
Rev. 241 12.08.2021 : battery values updated (200Ah ++)
Rev. 252 17.08.2023 : ECar loading ++
Rev. 255 17.03.2024 : flexible /ref Hippogreiff switching times
Rev. 256 19.06.2024 : max. (lead acid) battery load voltages reduced
Rev. 259 04.08.2024 : battery changed to ECO-WORTHY 12.8V 100Ah LiFePO4
Rev.  79 21.03.2025 : meterPi and Hager contactor to M2=L3
Rev.  85 14.06.2025 : miniJoule inverter replaced - cleanup
Rev.  87 03.07.2025 : solarPowerHyst values and discharge limit
Rev.  89 28.07.2025 : minor comment improvement
Rev.  90 06.08.2025 : battery SOC/% <-> Ubat; loader test prep.
Rev.  92 15.08.2025 : load unload values and SFCs (Rev. 92..94, 02.09.)

This file is the addendum to sweetHome.h and sweetHome.c. It contains process IO related issues. These are not necessary for programs related to pure HMI, logging and the like. For those programs sweetHome.h and sweetHome.c will be sufficient.

In the smart home under control, there's one smart meter for the whole house's public electricity supply and one for solar generators and battery storage. The (two, cf. ANZmodSLAVES) meters are connected by Modbus. Additionally and also via Modbus, a Growatt inverter offers power and other values. Those are made available via an extra Pi acting as Modbus to MQTT bridge.

GPIO usage

See also file /forDSocu/Raspi3ioPinsMeterPi.ods

GPIO pins are used to control relays, LEDs and one button in the Pi's immediate neighbourhood. Three open drain (module) outputs control slightly remote (10m) periphery via shielded cable.

This program uses eight relays (one 10A change over contact each) in an eight relays module. The relays are energised by an active low "Din" (n:1..8) signal.

Eight 10A relays module connected via RS485 converter/shield pin connectors

module  : Gnd  Di1  Di2  Di3  Di4  Di5  Di6  Di7  Di8  3V3     Gnd  5V
colour  : brn  blk  wht  gry  vio  blu  grn  yel  ora  red     brn  red
RS conv.: Gnd   P0   P1   P2   P3   P4   P5   P6   P7  3.3V    Gnd  5V
Pi Pin  : 6&c   11   12   13   15   16   18   22    3  1 &c    6&c  2&3
GPIO Pi3:       17   18   27   22   23   24   25    2
IO name :     REL1 REL2 REL3 REL4 REL5 REL6 REL7 REL8

Other process IO see project file /forDocu/Raspi3ioPinsMeterPi.ods .

Notes on process IO functions

  REL1 :  defect XX   (ex PPS-SSR pre-relay)
  REL2 :  off miniJoule's Ferraris meter on battery unload (out of use 6'23)
  REL3 :  not used (ex VDE-AR-N 4105)
  REL4 :  phase packet switch (PPS-SSR) pre-relay for heater contactor
  REL5 :  would give away more than 250 W          (prolonged 2h)
  REL6 :  not used (ex VDE-AR-N 4105)
  REL7 :  not used (ex VDE-AR-N 4105)
  REL8 :  hot water circulation pump  (comfort function)
  Note :  When searching relay usages search for macros onRel(N), offRel(N)
          and switchRel(N, V).
 
  LED9 :  red LED; Modbus slave indicator;  on: Modbus slave index > 0
  LEDx :  green LED; no function at the moment, always on
 
  HWPB :  start hot water pump (button to GND)
  POWH :  Battery load power module voltage control (via open drain)
          PWM for adjustable 11..14V 10A power module
          lo or off: for lowest voltage
  BATu :  Battery unload (hi active);  battery to step up
          when battery surveyor signal is OK
  CONb :  Step up to miniJoule inverter (32V) | not used miniJoule out 1.6.25
  INVu :  two relays switching unused inverter input plugs +&-: ex CONb
  HYPr :  Battery to Hippogreiff
 
PH_P_SSR1: Phase packet switch SSR1 (heater element 1) 0..100%
PH_P_SSR2: Phase packet switch SSR2 (heater element 2) 0, 50, 100%
PWMcarLd : PWM to control max. car load current (per phase)
CONcarLd : Contactor (relay) "power to car" is set ON  (low active OC in)
CONcarRq : Car (i.e. CP resistor 2k7) is connected (low active OC in)

MQTT usage

The MQTT protocol is used for remote process IO within "sweet home's" private (W)LAN:
a) battery surveillance and voltage measurement by specialised ESP8266
b) For Sonoff S20 plug switches modified to be MQTT clients (Tasmota).

PLG1 "would give 250 W" = parallel to REL5
PLG2 sunset to sunrise  (since 03.03.2018; as Hippogreiff)
PLG3 just controlled by web interface (since August 2019 used
     for outside air monitor's supply, to enable remote reset)
PLG4 "actually giving away" (neg. supply) warning

Macro Definition Documentation

◆ SENS0PATH

#define SENS0PATH

Temperature of water tank (top level).

This is the address of the 1-wire sensor's value file provided by the 1-wire-temp kernel module.

◆ SENS1PATH

#define SENS1PATH

Temperature of hot water pipe (from tank top).since 12 23: 28-6fb4d443009b.

◆ SENS2PATH

#define SENS2PATH

Temperature of water tank (bottom level).

◆ PDEL_BALEND

#define PDEL_BALEND

Minimal delivery power to leave ballast loading SFC.

Value: 410.2 W

◆ PDEL_BALRED

#define PDEL_BALRED

Minimal delivery power to reduce ballast.

Value: 61.02 W

◆ PDEL_BALINC

#define PDEL_BALINC

Maximal delivery power not to add ballast.

Value: 1.02 W

◆ PDEL_SGCONS

#define PDEL_SGCONS

Minimal delivery power (W) to signal consumer.

See consumeGiveHyst.

Value: 45.4 W

◆ PDEL_SGGIVE

#define PDEL_SGGIVE

Maximal delivery power to signal give away.

See consumeGiveHyst.

Value: 14.3 W

◆ CHS_CP_OFFSET

#define CHS_CP_OFFSET

CP signal PWM correction offset.

The CP signal's duty cycle to E-car (+/-12V) might deviate from the ��C's control signal (TTL); explanation see at DEF_CP_OFFSET.

-27 is the correct value for the (modified) Analog EVSE. Due to asymmetries caused by the optocoupler input the change to Hi state is propagated faster than the one to Lo.

◆ POWH

#define POWH

Power module voltage control (li/br-ws).

See loadModUlookup

◆ switchPPSrel

#define switchPPSrel ( V )

Actuate phase power switch control relay.

For safety reasons there is a contactor (Hager 4 * 40A) in front of the electronic zero crossing switches (solid state relays SSR) for the two heater elements.

The PPS relay (4) actuates this contactor. The Hager contactor consumes about 9W, when actuated. The meterPi and Hager contactor were move from M3=L3 to M2=L3 as not to spoil the ballast load sum.

Parameters

V	0: off; else: on

◆ onPort

#define onPort ( N )

Switch port N on.

Parameters

N	port name (LEDx, BATu, INVu; CONb and miniJoule out 1.6.25 ..)

◆ offPort

#define offPort ( N )

Switch port N off.

Parameters

N	port name (LEDx, BATu, INVu; CONb and miniJoule out 1.6.25 ..)

◆ switchRel

#define switchRel	(	N,
		V
	)

Switch relay N on or off.

Parameters

N	relay number 1..8
V	0: off; else: on

◆ onRel

#define onRel ( N )

Switch relay N on.

Parameters

N	relay number 1..8

◆ offRel

#define offRel ( N )

Switch relay N off.

A module with 8 relays controlled directly by Pi output pins.

Parameters

N	relay number 1..8

◆ BEFORE_RISE

#define BEFORE_RISE

Before sunrise timer offset.

See also: befRiseTimer value: 248 minutes (since 12.08.2021; 188 before)

Function Documentation

◆ logBatteryState()

void logBatteryState ( )

Log battery state on outLog as line with time stamp.

Logs the battery voltage in the format

/0123456789x123456789v123456789t123456789q123456789c123456789s123456789S1234567
/ 2019-05-01 11:58:16.600 # battery 1?.05 V, pwmL 000: 13.08V;  1234.6W       .
/linefeed  

◆ pckSwPec()

uint8_t pckSwPec ( float power )

Set and get package switch percentage by power.

Besides determining an returning the percentage(power), this function sets the process control values via setPckSwPerc() returns its value.

Parameters

power in W

Returns: the phase packet percentage 0..100

◆ setPhPckLimit()

float setPhPckLimit ( float powerLimit )

Set and get package switch power limit.

This function sets the PPS power limit in the range 0.0 ... PCK_POWER_LIM_MAX.

Parameters

powerLimit PPS power limit in W

Returns: the (new) power limit

◆ setPckSwPerc()

uint8_t setPckSwPerc ( uint8_t perc )

Set package switch percentage.

This function sets phPckSwIndex by the parameter value in the range 0..200; respectively PCK_POWER_IND_MAX. Additionally it adjusts the current phPckCnt should its value be higher than by the new setting.

On transitions from respectively to 0 the control relay (PCK_POWER_REL) is actuated before respectively after actuating the electronic switch.

This function also sets .phPckpower in valFilVal according to the values in table (array) phPckSwPow.

Parameters

perc	0..200; values above PCK_POWER_IND_MAX will have no effect and return the current setting un-altered

Returns: the actual (new) phase packet percentage 0..200

◆ switchHotWpump()

void switchHotWpump ( uint8_t const on )

Hot water comfort pump turn on/off.

It turns the hot water comfort circulation pump on respectively off.

Parameters

on	!= 0 : on; else, ==0 : off

◆ switchBatToStepUp()

void switchBatToStepUp ( uint8_t on )

Switch battery to step up converter.

When the parameter is !=0 respectively ON, this function switches the battery to the step up converter.

When the parameter is off, this function switches the battery to the (max. 20 A) battery loader / keep alive module .

Parameters

on	true: switch battery to step up converter; 0, false: switch battery to load modul.

◆ setBatLoadPWM()

void setBatLoadPWM ( int pwm )

Set battery loader module PWM.

This function sets the battery load module power PWM signal and hence its output voltage. 0 is the lowest and 255 the highest possible setting. While this function allows setting to 0, the highest value is limited to BAT_LDMX_PWM.

Parameters

pwm	the pwm ratio 0: 0%; 255: 100%

◆ changeBatLoadPWM()

void changeBatLoadPWM ( int pwmChg )

Change battery loader module PWM.

This function adds the parameter pwmChg's value to the current one limits the result to BAT_NOLD_PWM ... BAT_LDMX_PWM and sets it (see setBatLoadPWM).

Parameters

pwmChg the change of the pwm value

Variable Documentation

◆ batVoltValid

uint8_t batVoltValid

extern

The measured battery voltage is valid.

When not 0 the last MQTT battery voltage measurement respectively message is not older than 2.4s and hence considered the actual valid value.

◆ nologBatCap

volatile int nologBatCap

extern

Control logging inhibit charging battery due to capacity limit.

1: log next time when it occurs and (always) decrement 0: or high value log no more this day. n: inhibit the next 2*n seconds while continually trying

◆ batUnloadAllowed

int batUnloadAllowed

extern

Battery unload allowed.

Bit 0 (1): allow after sunset
Bit 1 (2): allow before sunrise
Bit 3 (4): allow when Pimp > 400W, i.e. allow also at daylight.
Bit 4 (8): default (usually 2 in winter and 3 in summer)
Start value: 8 = default
Note: Must be a standard integer (no uint_8 e.g.) for use in getopt_long.

See also: BAT_UNL_SUMM; BAT_UNL_WINT

◆ batLoadAllowed

int batLoadAllowed

extern

Battery loading allowed.

Bit 0 (1): allow ballast loading
Bit 1 (2): allow automatic / controlled loading
start value: 3 = all allowed
Note: Must be a standard integer (no uint_8 e.g.) for use in getopt_long.

See also: batUnloadAllowed; BAT_LOAD_FORBID

◆ hippoSwitchMode

int hippoSwitchMode

extern

Hippogreiff on/off times.

Bit 0,1 ( 3): switch at sunset resp. sunrise (winter)
Bit 2,3 (12): switch at dusk resp. dawn (summer)
start value: 12 (/ref Hippogreiff summer)

◆ phPckSwIndex

volatile uint8_t phPckSwIndex

extern

Actual index (0..200%) determining power.

This is the control variable for the electric heater elements in the hot water tank. Until June 2023 there was one such element of PCK100PERC_POWER W and this variable had a range of 0..100%. Since July 2023 there are two heater elements of equal power. The range of this control variable was extended to 0..200%. The power distribution between the two heater elements is done by software; see setPckSwPerc(uint8_t const perc) and PCK_POWER_IND_MAX

◆ batLodTst

volatile uint8_t batLodTst

extern

Battery loader test modus.

A value 0 means normal loading, keeping or idle mode.
Other values mean test modus, i.e. have stable PWM values to allow test measurements. These PWM values are usually set manually.

See also BAT_LDTEST_MAX_PWM, BAT_LDTEST_MIN_PWM, BAT_LDTEST_UPS_PWM, BAT_LDTEST_DWN_PWM, setBatLoadPWM

◆ batModPWM

volatile int batModPWM

extern

The actual battery load module's PWM input.

The range of the Pi's pwm output control register 0 for 0 % or permanent off to 255 for 100% respectively permanent on. The eight bit register, hence, is to be fed with an unsigned 8 bit value which was for many years the type of this variable.
A new loader module since August 2025 uses the full range 0..255. This variable was made a standard int to simplify underflow and overflow detection.
Note: Keeping this variable's value in the range 0 .. +255 is essential!

◆ batKeepInh

state_t batKeepInh

extern

Inhibit battery keep alive loading.

This timer will be started after battery loading and unloading for a specific time BATkeepInhContLoad, BATkeepInhUnload or BATkeepInhByCmd. This timer is initially OFF and will be stopped in advance by battery keep command via HMI/GUI.
It will be started after battery unload, after battery ballast load and by battery off command via GUI.
When running out it will start battery keep alive with BAT_KEEP_PWM.

Note: The feature seems/is unnecessarily complicated due to its lead acid battery past

◆ sunriseTimer

state_t sunriseTimer

extern

Sunrise timer.

This timer will run out every day at (approximated) sunrise. For the "every day" behaviour, its state change function will — after all due actions — restart this timer for the next 24h to hit (very approximately) the next sunrise. This acceptable guess will be adjusted at day change or at program start.

◆ sunsetTimer

state_t sunsetTimer

extern

Sunset timer.

This timer will run out every day at (approximated) sunset. See also sunriseTimer

◆ dawnTimer

state_t dawnTimer

extern

Dawn timer.

This timer will run out every day at (approximated) dawn, meaning the beginning of civil twilight. See also sunriseTimer and duskTimer

◆ duskTimer

state_t duskTimer

extern

Dusk timer.

This timer will run out every day at (approximated) dusk, meaning the end of civil twilight. About this time street lamps and position lights may be lit. See also sunriseTimer

◆ befRiseTimer

state_t befRiseTimer

extern

Before sunrise timer.

This timer will run out every day at about 180 min before (approximated) sunrise. The offset must be sufficient time to unload the battery before sunrise.
See also: sunriseTimer BEFORE_RISE

◆ solarPowerHyst

state_t solarPowerHyst

extern

Solar power producer hysteresis.

The limits of the power of the biggest (or all) PV panels to recognise the availability / generation of solar power.
Current limits 7.9W (off), 40.0 W (on); since 03.07.2025
Former values 4.8, 12.02

◆ consumeGiveHyst

state_t consumeGiveHyst

extern

Give away hysteresis.

thresholds: PDEL_SGGIVE, PDEL_SGCONS

◆ consumeGiveSFC

state_t consumeGiveSFC

extern

Give away state machine / SFC.

Status ON means consumer: OK.
Status OFF means very low power consumption: Inhibit power delivery.

◆ wouldGiveAwayHyst

state_t wouldGiveAwayHyst

extern

Would give away hysteresis.

thresholds (04.03.18): -/+ 7W

◆ wouldGive250WHyst

state_t wouldGive250WHyst

extern

Would give away 250W hysteresis.

thresholds (04.03.18): -250 / -178W

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SENS0PATH

◆ SENS1PATH

◆ SENS2PATH

◆ PDEL_BALEND

◆ PDEL_BALRED

◆ PDEL_BALINC

◆ PDEL_SGCONS

◆ PDEL_SGGIVE

◆ CHS_CP_OFFSET

◆ POWH

◆ switchPPSrel

◆ onPort

◆ offPort

◆ switchRel

◆ onRel

◆ offRel

◆ BEFORE_RISE

Function Documentation

◆ logBatteryState()

◆ pckSwPec()

◆ setPhPckLimit()

◆ setPckSwPerc()

◆ switchHotWpump()

◆ switchBatToStepUp()

◆ setBatLoadPWM()

◆ changeBatLoadPWM()

Variable Documentation

◆ batVoltValid

◆ nologBatCap

◆ batUnloadAllowed

◆ batLoadAllowed

◆ hippoSwitchMode

◆ phPckSwIndex

◆ batLodTst

◆ batModPWM

◆ batKeepInh

◆ sunriseTimer

◆ sunsetTimer

◆ dawnTimer

◆ duskTimer

◆ befRiseTimer

◆ solarPowerHyst

◆ consumeGiveHyst

◆ consumeGiveSFC

◆ wouldGiveAwayHyst

◆ wouldGive250WHyst