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)
ExampleHeating (FB) ¶ FUNCTION_BLOCK ExampleHeating Example heating circuit This example function block implements a simple outside temperature dependent water heating circuit to demonstrate how to: implement a plant / an aggregate in CFC using CODESYS Building Automation library function blocks SequenceControl can be used for one sequence as well use DailyMeanTemperature to enable / disable heating circuit in “atomatic”-mode use HeatingCharacteristicCurve to compute supply temperature setpoint This example involves: heating circuit operation enabled / disabled in “auto”-mode using DailyMeanTemperature or outdoor temperature computation of supply temperature setpoint using HeatingCharacteristicCurve night time setpoint reduction vs. switching off heating circuit operation economy mode - switching off circulation pump and mixing valve if supply temperature to low to provide sufficient energy optional anti-freeze Watch out for comments in the implementation where those aspects are covered. outdoor air temperature sensor indoor air temperature sensor supply temperature sensor circulation pump mixing valve Heating circuit operation ¶ Heating circuit operation could be enabled / disabled manually setting eOnOff accordingly. Heating circuit operation could be determined automatically setting eOnOff to Auto. In “auto”-mode the operation is enabled if either the daily mean temperature or the outdoor temperature (xUseOdaTemp = TRUE) is below rTempLimitEnable. Night time setpoint reduction vs. switching off heating circuit operation ¶ ExampleHeating allows to use either a reduced supply temperature setpoint (rSupplyTempSetpt) at night, or to switch off operation at all. Economy mode ¶ Economy mode is switching off circulation pump and mixing valve if rSupplyTempSetpt is to low to provide sufficient energy. It differentiates low / high temperature heating systems by HeatingCharacteristicCurve gradient. Gradient < 1.0 assumes a low temperature heating system (for example floor heating). Gradient <= 1.0 - low temperature heating system: rSupplyTempSetpt < rIdaTempSetpt => switch off rSupplyTempSetpt > rIdaTempSetpt + 2.0K => switch on Gradient > 1.0 - high temperature heating system: rSupplyTempSetpt < rIdaTempSetpt + 5.0K => switch off rSupplyTempSetpt > rIdaTempSetpt + 7.0K => switch on Optional anti-freeze ¶ If anti-freeze is activated, there are three separate measures activated: low outdoor temperature (rOdaTemp < rAntiFreezeOdaTempLimit) cause the circulation pump to be enabled low supply temperature (rSupplyTemp < rAntiFreezeSupplyTempLimit) cause the heating circuit operation to be enabled anyway low indoor air temperature (rIdaTemp < rAntiFreezeIdaTempLimit) cause the heating circuit operation to be enabled anyway 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_heatingCharacteristicCurve, m_circulationPump, m_sequenceControl, m_mixingValve, etc. is not or not completely exposed on the ExampleHeating VAR_INPUT section) sensors missing (circulation pump service / error indication, …) input consistency checks (implausible measurement values, …) day / night operation does often fullfill more complex needs scheduling (for example via BACnet scheduler) might set setpoint instead of day / night ramping up/down the setpoint instead of switching over between day / night setpoint xError / eErrorID not computed at all, see ExampleAirConditioning2 how to do this sensor / actuator process I/O not mapped (FB sensor inputs, m_circulationPump, m_mixingValve) InOut: Scope Name Type Initial Comment Input eOnOff AutoOnOff AutoOnOff.Auto Operation mode preset rSupplyTemp REAL Supply temperature rOdaTemp REAL Outdoor temperature rIdaTemp REAL 21.0 Indoor air temperature rIdaTempSetpt REAL 21.0 Indoor air temperature setpoint rTempLimitAutoEnable REAL 16.0 Temperature limit to enable operation in “auto”-mode xUseOdaTemp BOOL FALSE Decides whether to use daily mean temperature or outdoor temperature to enable operation in “auto”-mode. xUseOdaTemp := FALSE => use daily mean temperature. xUseOdaTemp := TRUE => use outdoor temperature. xDayNight BOOL TRUE Decides whether to use day / night operation rGradient REAL 1.2 HeatingCharacteristicCurve gradient. rShift REAL 0.0 HeatingCharacteristicCurve parallel shift rMinimumSupplyTemp REAL 20.0 Supply temperature minimum rMaximumSupplyTemp REAL 80.0 Supply temperature maximum xNightSetptReductionEnable BOOL TRUE Decides whether to use night time setpoint reduction vs. switching off heating circuit operation rNightSetptReduction REAL -12.0 Night time setpoint reduction xEconomyEnable BOOL TRUE Enables economy mode xAntiFreezeEnable BOOL TRUE Enables anti-freeze rAntiFreezeOdaTempLimit REAL 4.0 Anti-freeze outdoor temperature limit rAntiFreezeSupplyTempLimit REAL 10 Anti-freeze supply temperature limit rAntiFreezeIdaTempLimit REAL 14.0 Anti-freeze indoor air temperature limit 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 xOn BOOL Heating circuit is activated / enabled xHeat BOOL Heating circuit in operation rSupplyTempSetpt REAL Supply temperature setpoint xEconomy BOOL Economy mode active xFrostAlarm BOOL Frost alarm indication xCircPump BOOL Circulation pump running rValve REAL Mixing valve
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.