ExampleAirConditioning2 (FB) ¶ FUNCTION_BLOCK ExampleAirConditioning2 Example air conditioning 2 This example function block evolves from ExampleAirConditioning1 and implements a bit more complex air conditioning plant to demonstrate how to: implement a plant / an aggregate in CFC using CODESYS Building Automation library function blocks use SequenceControl and SequenceSwitch do anti-freeze control / anti-freeze shutoff for heater coil compute the xError / eErrorID from xError / eErrorID of function block instances used This example involves following real world application aspects: recirculation air admixing minimum outdoor air ratio sequence control of recirculation air damper / heater coil / cooler coil energy selection (outdoor air vs. extract air) for recirculation air damper energy level air side anti-freeze / water side anti-freeze for heater coil exhaust air damper / outdoor air damper control extract air fan / supply air fan control Watch out for comments in the implementation where those aspects are covered. outdoor air temperatur sensor outdoor air damper recirculation air damper heater coil (water operated) frost monitor heater coil return temperatur sensor cooler coil (water operated) supply air fan extract air fan extract air temperatur sensor exhaust air damper Air types ¶ Air types - terms, abbreviations and colors oriented towards DIN EN 16798-3. Sequence control damper / heater coil / cooler coil ¶ SequenceControl is used to control three sequences - heater coil, RCA damper and cooler coil. RCA damper - 0% (maximum outdoor air) .. 100% (would be: no outdoor air) This is about to utilize mixed air or outdoor air energy as much as possible to heat / cool. In case you want to trade comfort (in this case control deviation and it’s duration) a bit higher to energy consumption, you might want to set mc_rDamperCoilOverlap to a value < 0.0, making the RCA damper sequence and the coil sequences overlap thus forcing the coils to jump in before maximum RCA ratio is reached. Set mc_rDamperCoilOverlap to -1.0 (K) will make the coil open 25% (because rXP = 4.0) if recirculation air damper reached maximum. Recirculation air admixing and energy selection ¶ RCA admixing is done using the RCA damper as primary control sequence thus minimizing heat / cool energy consumption. Please see m_energySelection for the energy selection aspect. Minimum outdoor air ratio ¶ Minimum ODA ratio is achieved by rMax2 := 100% - rMinOdaRatio Remember: RCA damper is controlled by sequence 2. rOut2 = 0% means maximum ODA ratio (100% in this case). Water side anti-freeze for heater coil ¶ Water side anti-freeze for heater coil is done with two separate sub-functionalities a controlled startup procedure continuous anti-freeze during control The startup procedure is done using HVAC_AntiFreezeControlStartup if ODA temperature < startup threshold: preload (the heater coil): ODA / ETA damper closed RCA damper open (maximum recirculation air ratio - 100%) forcing the heater coil to open check heater coil return temperature to reach a threshold after preload - wait for system to become settled (HVAC_AntiFreezeControlStartup.tFollowUp): open ODA / ETA damper to minimum ODA ratio set RCA damper accordingly to minimum ODA ratio take over to normal control actions SequenceControl.xForceEnable and .rForcedValue is used to force the heater coil sequence, thus providing smooth control takeover after sucessfull startup. The continuous anti-freeze during control is done using a CommandVariable setting the heater coil sequence minimum. Air side anti-freeze ¶ Air side anti-freeze is done using a frost monitor HVAC_AntiFreezeControlMonitor . The frost monitor simply does shut-off the whole plant, but keeping the heater coil opened to maximum. Hints ¶ Unused pins of function block instances are hidden, so refer to the function block documentation for more details. Caveats ¶ To keep complexity as low as possible this example omits the following real world application aspects worth mentioning: configuration missing (configuration of m_energyLevelSetpoint, m_sequenceControl, m_antiFreezeControlStartup and m_antiFreezeCont is not exposed on the ExampleAirConditioning1 VAR_INPUT section) ignoring the subtle differences between indoor air control vs. extract air control (assuming extract air temp. = indoor air temp.) no indoor air / supply air cascade control (control quality) no supply air minimum enforced (physiological problems caused by low supply air temperature) ramping up/down the ODA / EHA damper after anti-freeze control preload is done (our impl. does simply switch to rMinOdaRatio or 100%) cooling is not blocked if continuous anti-freeze during control is opening heater coil InOut: Scope Name Type Initial Comment Input xEnable BOOL TRUE Enable eLevel EnergyLevel EnergyLevel.COMFORT Energy level rEtaTemp REAL 22.0 Extract air temperature rSetptHeatComfort REAL 21.0 Heat setpoint comfort level rSetptCoolComfort REAL 23.0 Cool setpoint comfort level rOdaTemp REAL 10.0 Outdoor air temperature rMinOdaRatio REAL 20.0 Minimum outdoor air ratio, 0..100% rHeaterCoilReturnTemp REAL 20.0 Heater coil return temperature xFrost BOOL FALSE Heater coil frost indication xReset BOOL FALSE Reset to proportional control / reset detected input error itfDateTimeProvider Util.IDateTimeProvider Globals.g_dtpDateTimeProvider Source for the current date and time information in milliseconds since 1.1.1970 00:00:00.000 Output eModeOut HeatCoolOperationMode HeatCoolOperationMode.INACTIVE Operation mode. rHeatOut REAL Heat valve signal (0..100%). rCoolOut REAL Cool valve signal (0..100%). rOdaDamperOut REAL Outdoor air damper signal (0..100%). rRcaDamperOut REAL Recirculation air damper signal (0..100%). rEhaDamperOut REAL Exhaust air damper signal (0..100%). xFan BOOL Extract air / supply air fan xAntiFreezeStartup BOOL Anti-freeze control startup indication xAntiFreezeStartupError BOOL Anti-freeze control startup error indication xFrostAlarm BOOL Frost alarm indication xError BOOL Error indication eErrorID Error Error ID
AWS Iot Core Client ¶ Enums QOS (Enum) Function Blocks AWSIoTClient (FunctionBlock) AWSIoTGetDeviceShadow (FunctionBlock) AWSIoTPublish (FunctionBlock) AWSIoTSubscribe (FunctionBlock) AWSIoTSubscribeDeviceShadow (FunctionBlock) AWSIoTUpdateDeviceShadow (FunctionBlock) Visualization ETrigToTemplate (FunctionBlock) GlobalTextList (GlobalTextList) TextListForCombobox_MQTT_QOS (TextList) TextListForCombobox_QOS (TextList)
QOS (ENUM) ¶ TYPE QOS : Quality of Service levels (QoS) Attributes: qualified_only InOut: Name Initial Comment QoS0 0 Send Message 1x, if disconnect from server then send can fail. QoS1 1 Send Message Nx, until Receive is acknowledged.
Function Blocks ¶ AWSIoTClient (FunctionBlock) AWSIoTGetDeviceShadow (FunctionBlock) AWSIoTPublish (FunctionBlock) AWSIoTSubscribe (FunctionBlock) AWSIoTSubscribeDeviceShadow (FunctionBlock) AWSIoTUpdateDeviceShadow (FunctionBlock)
AWSIoTClient (FB) ¶ FUNCTION_BLOCK AWSIoTClient Function block to connect to the AWS IoT Core Service. InOut: Scope Name Type Initial Comment Input xEnable BOOL TRUE: Opens a connection, FALSE: Close connection uiKeepAlive UINT 30 Keep alive interval in seconds (default: 30s) sClientId STRING(255) The clientId (Name of the thing in AWS IoT Core) sHostname STRING(1024) API Endpoint (e.g. xxxxxxyyyyyyy.iot.eu- central-1.amazonaws.com) uiPort UINT 8883 MQTT port (default: 8883) wsWillTopic WSTRING(1024) “” Last will topic (optional) pbWillMessage POINTER TO BYTE 0 Pointer to the ‘Last Will’ message (optional) uiWillMessageSize UINT 0 Size of ‘Last Will’ message (optional) eLastWillQoS QOS Quality of Service of the last will message itfTLSContext NBS.ITLSContext 0 Encapsulates all the data neccecray to handle encrypted tcp connections Static initialization, as shown in the following code snippet. VAR commonName : STRING := 'MyRrasPi' ; ciCertInfo : NBS.CERT_INFO := ( psInfo := ADR ( commonName ), udiSize := LEN ( commonName )); myTLSContext : NBS.TLSContext := ( ePurpose := NBS.PURPOSE.CLIENT_SIDE , sUseCaseName := 'NBSTest' , sTLSVersion := '1.3' , ciCertInfo := ciCertInfo , udiVerificationMode := 2 ); END_VAR itfAsyncProperty NBS.IAsyncProperty 0 Runs the connect process in a own background task. Use this property if the connection setup takes longer than one task cycle (e.g. TLS connections) sCertCNPrefix STRING ‘’ Prefix for the Common Name (CN) of the certificate. The prefix should be used if the ClientId is identical to the host name. This prevents loading of a wrong certificate (e.g. from the WebServer). Example: sCertCNPr := ‘AWSClient’, sClientId := ‘MyHostname’ => The Common Name (CN) of the certificate will be AWSClient @ MyHostname xCleanSession BOOL TRUE TRUE: Creates a new session, FALSE: Uses already existing session if available Output xError BOOL TRUE, if an error occurred xBusy BOOL TRUE, while the function block is active eError MQTT.MQTT_ERROR The error id xConnectedToBroker BOOL FALSE FALSE when there is no Connection to MQTT Broker Server, otherwise TRUE
ExampleHotWater (FB) ¶ FUNCTION_BLOCK ExampleHotWater Example hot water boiler control This example function block implements a simple hot water boiler control to demonstrate how to implement a plant / an aggregate in ST using CODESYS Building Automation library function blocks. All other examples are implemented using CFC, because this way it’s a bit more easy to read / understand. No matter of this ST is also a good choice to implement plants / aggregates. Here we demonstrate, that an implementation using ST is also easy to read / understand if structured nicely and well documented. This example involves: 2 point control of boiler temperature steady control of boiler supply temperature demand-based activation of loading pump legionella prevention optional unload protection using supply temperature sensor Watch out for comments in the implementation where those aspects are covered. supply temperature sensor mixing valve loading pump boiler supply temperature sensor upper boiler temperature sensor lower boiler temperature sensor circulation pump 2 point control of boiler temperature ¶ A boiler load cycle is requested, if boiler temperature is below setpoint. The boiler load cycle is stopped, if boiler temperature exceeds setpoint plus hysteresis. Legionella prevention ¶ Boiler temperature is to be kept above 60°C for at least an hour the day. Circulation pump is enabled during this load cycle. Optional unload protection ¶ In case there is a supply temperature sensor ExampleHotWater checks the supply temperature before / during a load operation. In case the supply temperature is below boiler temperature the boiler will not be loaded. Caveats ¶ To keep complexity as low as possible this example omits - amongst others - the following real world application aspects worth mentioning: configuration missing (configuration of m_legionellaPreventionDone, m_legionellaPreventionTimer, m_loadPump, m_circPump, m_mixingValve etc. is not or not completely exposed on the ExampleHotWater VAR_INPUT section) input consistency checks (rHyst <= 0, implausible measurement values, …) no legionella warning issued, if legionella prevention load cycle is missed due to unload conditions sensors missing (both pumps - service / error indication, …) xError / eErrorID not computed at all, see ExampleAirConditioning2 how to do this sensor / actuator process I/O not mapped (FB sensor inputs, m_loadPump, m_circPump, m_mixingValve, …) InOut: Scope Name Type Initial Comment Input rSetpt REAL 50.0 Hot water temperature setpoint rHyst REAL 5.0 Hot water temperature hysteresis rSupplyTemp REAL Supply temperature xSupplyTempSensor BOOL FALSE Optional supply temperature sensor exists rBoilerSupplyTemp REAL Boiler supply temperature rBoilerTemp1 REAL Upper boiler temperature rBoilerTemp2 REAL Lower boiler temperature xCircPumpRequest BOOL FALSE Request circulation pump tLegionella TIME TIME#1440m0s0ms Time to next legionella prevention boiler load cycle xReset BOOL FALSE Reset itfDateTimeProvider Util.IDateTimeProvider Globals.g_dtpDateTimeProvider Source for the current date and time information in milliseconds since 1.1.1970 00:00:00.000 Output rRequestedBoilerTemp REAL Requested boiler temperature xLegionellaPreventionDone BOOL Legionella prevention has been done in the last 24 hours xLoad BOOL Boiler will be loaded actually. xLoadPump BOOL Loading pump running xCircPump BOOL Circulation pump running rValve REAL Mixing valve tLegionellaRemaining TIME Remaing time to next legionella prevention boiler load cycle
AWSIoTGetDeviceShadow (FB) ¶ FUNCTION_BLOCK AWSIoTGetDeviceShadow EXTENDS CBML.ETrigTo Function block to read the device shadow of the connected device. InOut: Scope Name Type Initial Comment Inherited from Input xExecute BOOL Rising edge: Starts defined operation FALSE : Resets the defined operation after ready condition was reached ETrigTo udiTimeOut UDINT Max. operating time for executing [µs], 0: No operating time limit ETrigTo Output xDone BOOL Ready condition reached ETrigTo xBusy BOOL Operation is running ETrigTo xError BOOL Error condition reached ETrigTo Input pbPayload POINTER TO BYTE Pointer to the receive buffer (device shadow) udiMaxPayloadSize UDINT Maximum size of the receive buffer eQoS QOS Quality of service level (QoS) sClientId REFERENCE TO STRING(255) 0 The name of another thing. The input sClientId can be used to access device shadows of other things. if 0, then the clientId from AWSIoTClient will be used. Inout awsIoTClient AWSIoTClient Reference to AWSIoTClient Output eError MQTT.MQTT_ERROR Error code udiPayloadSize UDINT Length of the device shadow
AWSIoTPublish (FB) ¶ FUNCTION_BLOCK AWSIoTPublish Function block for publishing a message via AWS IoT Core. InOut: Scope Name Type Comment Input xExecute BOOL Rising edge will publish the message |pbPayload| udiTimeOut UDINT Time out in µs, 0: no time out pbPayload POINTER TO BYTE Pointer to the message udiPayloadSize UDINT Size of the message |pbPayload| eQoS QOS Quality of service level (QoS) Inout awsIoTClient AWSIoTClient Reference to AWSIoTClient wsTopic WSTRING(1024) Reference to the topic Output xError BOOL TRUE, if an error occurred xBusy BOOL TRUE, while sending the message xDone BOOL TRUE, if the message was sent successfully eError MQTT.MQTT_ERROR Error code
ExampleRoomAutomation (FB) ¶ FUNCTION_BLOCK ExampleRoomAutomation Example room automation This example function block implements a very simple room temperature control using a fan coil to demonstrate: how to implement a complex control strategy in CFC using CODESYS Building Automation library function blocks how to use certain room automation related function blocks how to use SequenceControl This example involves following real world application aspects: presence controlled energy level room temperature control using a fan coil Fancoil3Stage energy optimization (night cooling, energy lock, summer compensation) fast heat / cool at “pre-comfort” window alarm Watch out for comments in the implementation where those aspects are covered. outdoor air temperatur sensor room control panel including indoor air temperatur sensor, manual control elements (presence, temperature setpoint, fan speed) presence sensor fan coil (4-pipe system) window actuator window contact Air types ¶ Air types - terms, abbreviations and colors oriented towards DIN EN 16798-3 - see ExampleAirConditioning1 . Presence controlled energy level ¶ In this example energy level is selected by local information - presence information from room control panel and presence sensor. More complex scenarios might involve using a “pre-comfort” energy level controlled by building managment system / room occupancy control system. To keep the example simple, xPrecomfort := TRUE does switch the energy level from “economy” to “pre-comfort”, but doesnt effect an active energy level “comfort”. Dealing with “pre-comfort” is a bit more complex in real world applications. Night cooling ¶ Cooling down the room using cooler outdoor air is done using HeatCoolUsingOutdoorAir . Energy lock ¶ The energy lock function prevents energy consumption if window is opened. Nevertheless building protection is taken care for running the sequence controller with the related building protection setpoints. In case control actions are executed and energy is spent xBuildingProtectionActive is signalling this. The energy lock does imply an on-delay, so window needs to be open for tEnergyLockOnDelay before building protection setpoints are used. Also there is a tEnergyLockMaxTime limiting the duration of the energy lock function. Sommer compensation ¶ Sommer compensation is done shifting the setpoints (in “comfort” energy level only) using a CommandVariable to adjust setpoints. Fast heat / cool ¶ Fast heat / cool is about to bring a room the “comfort” conditions during “pre-comfort” mode because a switch to “comfort” is going to happen soon. Common use case - hotel receptionist does a checkin procedure, starting fast heat / cool right away. Window alarm ¶ Window alarm is signalled, if room is not occupied, window contact is signalling open window and night cooling does not open the window. Manual fan control ¶ Manual fan control can be done via room control panel if room is occupied. Hints ¶ Unused pins of function block instances are hidden, so refer to the function block documentation for more details. Caveats ¶ To keep complexity as low as possible this example omits the following real world application aspects worth mentioning: configuration missing (configuration of m_energyLevelSetpoint, m_sequenceControl etc. is not exposed on the ExampleAirConditioning1 VAR_INPUT section) input consistency checks (implausible measurement values, …) simplistic energy level selection - usually their is more complex state machinery in room control panel / building managment system / room occupancy control system “pre-comfort” energy level controlled by building managment system / room occupancy control system xError / eErrorID not computed from xError / eErrorID of function block instances used, see ExampleAirConditioning2 how to do this sensor / actuator process I/O not mapped (FB sensor inputs, m_windowActuator, m_valveHeat, m_valveCool, m_condensatePump, …) InOut: Scope Name Type Initial Comment Input xEnable BOOL TRUE Enable xPresenceSetting BOOL TRUE Presence signalled by room control panel rIdaTemp REAL 22.0 Indoor air temperature signalled by room control panel usiFanStageManual USINT (0..3) 0 Fan speed manual control requested by room control panel - 0 => off, or stage 1 .. 3 xFanStageManual BOOL FALSE Fan speed manual manual control requested by room control panel. xPrecomfort BOOL FALSE Enables the “pre-comfort” energy level. xFastHeatCool BOOL FALSE Enables the fast heat / cool mode. xPresence BOOL TRUE Presence signalled by presence sensor rOdaTemp REAL 10.0 Outdoor air temperature xWindowOpen BOOL FALSE Window contact signalling open window. xNightCooling BOOL FALSE Enable night cooling xEnergyLock BOOL FALSE Enable energy lock tEnergyLockOnDelay TIME TIME#10s0ms Energy lock on-delay tEnergyLockMaxTime TIME TIME#10m0s0ms Energy lock maximum duration xSummerCompensation BOOL FALSE Enable summer compensation xReset BOOL FALSE Reset itfDateTimeProvider Util.IDateTimeProvider Globals.g_dtpDateTimeProvider Source for the current date and time information in milliseconds since 1.1.1970 00:00:00.000 Output eLevel EnergyLevel Energy level eMode HeatCoolOperationMode Operation mode. xWindowAlarm BOOL Window alarm xBuildingProtectionActive BOOL There are control actions / energy consumption to keep indoor air temperature in the building protection setpoint range.