FB_LocalSystemTime

In some applications the local Windows system time is synchronized via the SNTP time server or a radio clock. In many cases the local Windows system time has to be used in the PLC (e.g. in the form of timestamp log messages to the HMI). The local Windows system time is displayed in the taskbar. For such applications the FB_LocalSystemTime function block can be useful.

This function block internally combines the function of the following function blocks: RTC_EX2, NT_GetTime, FB_GetTimeZoneInformation and NT_SetTimeToRTCTime. The RTC_EX2 function block can be used for generating timestamps for log outputs, for example. However, this function block has the disadvantage that its time is not synchronized with the local Windows system time and has to be resynchronized cyclically via the NT_GetTime function block (see RTC function block examples in the documentation). Cyclic synchronization of the internal time (systemTime output) is already implemented in the function block. The cycle time can be configured via the dwCycle input. The function block also provides time zone information (summer time/winter time).

The FB_LocalSystemTime function block must be called cyclically (e.g. every second or during each PLC cycle). This is necessary to enable the time between synchronizations to be calculated.

	Jitter! The local Windows system time is read with the aid of acyclic services (ADS function blocks). Due to the system characteristics the runtime of the ADS commands cannot be specified/estimated. Differences in command runtimes may lead to time jitter at the systemTime output, depending on the operating system, the synchronization interval and the PLC cycle time. For this reason, the time supplied by the function block is only suitable for more accurate measurement tasks to a limited extent. However, the accuracy is sufficient for applications in the field of building automation, for example.

Switching between daylight-saving time and standard time

The function block cannot be called exactly at the time when the switchover from daylight-saving time to standard time and vice versa takes place. In order to avoid complex calculations, the following implementation was chosen (explained in the example).

In our example the function block synchronises its own time with the local Windows system time (grey) every 60 seconds.
The PLC application needs and reads the time in the function block (e.g. every 30 seconds, blue). In our example the switchover between daylight-saving time and standard time is detected with a delay of 15 seconds. This behaviour should be unproblematic for most applications.

Switching from standard time to daylight-saving time

...
30-03-2008-01:58:10, tzID = standard time
30-03-2008-01:58:15, after internal synchronisation
30-03-2008-01:58:40, tzID = standard time
30-03-2008-01:59:10, tzID = standard time
30-03-2008-01:59:15, after internal synchronisation
30-03-2008-01:59:40, tzID = standard time
30-03-2008-02:00:00, the operating system changes the time from 2 am to 3 am
30-03-2008-02:00:10, tzID = standard time (still!)
30-03-2008-03:00:15, after internal synchronisation, subsequent tzID = daylight-saving time
30-03-2008-03:00:40, tzID = daylight-saving time
30-03-2008-03:01:10, tzID = daylight-saving time
30-03-2008-03:01:15, after internal synchronisation
30-03-2008-03:01:40, tzID = daylight-saving time
...

Switching from daylight-saving time to standard time

...
26-10-2008-02:58:10, tzID = daylight-saving time
26-10-2008-02:58:15, after internal synchronisation
26-10-2008-02:58:40, tzID = daylight-saving time
26-10-2008-02:59:10, tzID = daylight-saving time
26-10-2008-02:59:15, after internal synchronisation
26-10-2008-02:59:40, tzID = daylight-saving time
26-10-2008-03:00:00, the operating system changes the time from 3 am to 2 am
26-10-2008-03:00:10, tzID = daylight-saving time (still!)
26-10-2008-02:00:15, after internal synchronisation, subsequent tzID = standard time
26-10-2008-02:00:40, tzID = standard time
26-10-2008-02:01:10, tzID = standard time
26-10-2008-02:01:15, after internal synchronisation
26-10-2008-02:01:40, tzID = standard time
...

Inputs

VAR_INPUT
    sNetID    : T_AmsNetID := '';
    bEnable   : BOOL;
    dwCycle   : DWORD(1..86400) := 5;
    dwOpt     : DWORD := 1;
    tTimeout  : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

Name	Type	Description
sNetID	T_AmsNetID	A string containing the network address of the TwinCAT computer whose time is to be used for the synchronization can be specified here. For the local computer an empty string may be specified.
bEnable	BOOL	A rising edge at this input triggers immediate synchronization of the internal time with the local Windows system time. The output bValid remains set to FALSE until the synchronization is complete. The first rising edge activates the cyclic synchronization. The subsequent cyclic synchronizations are then executed automatically. In most cases the application only has to set this input to TRUE once.
dwCycle	DWORD	Cycle time (in seconds) during which the function block resynchronizes its own time. Cyclic synchronization is activated after the first rising edge at the bEnable input. Default: Synchronization every 5 seconds.
dwOpt	DWORD	Additional option parameters. The following parameters are currently available:
tTimeout	TIME	States the length of the timeout that may not be exceeded by execution of the ADS command.

Outputs

VAR_OUTPUT
    bValid     : BOOL;
    systemTime : TIMESTRUCT;
    tzID       : E_TimeZoneID := eTimeZoneID_Invalid;
END_VAR

Name	Type	Description
bValid	BOOL	The time at the systemTime output is invalid if this output is FALSE. The time is valid if TRUE (i.e. it was synchronized with the local Windows time at least once).
systemTime	TIMESTRUCT	Local Windows system time.
tzID	E_TimeZoneID	Time zone information (summer time, winter time)

Example:

In the example the FB_LocalSystemTime function block is activated on program startup (rising edge at bEnable input). Once the time has been synchronized (bValid = TRUE), the PLC writes a message to the TwinCAT "Error List" window every 500 ms. The internal synchronization is carried out every second.

PROGRAM MAIN
VAR
    fbTime   : FB_LocalSystemTime := ( bEnable := TRUE, dwCycle := 1 );
    logTimer : TON := ( IN := TRUE, PT := T#500ms );
END_VAR

fbTime();

logTimer( IN := fbTime.bValid );
IF logTimer.Q THEN
    logTimer( IN := FALSE ); logTimer( IN := fbTime.bValid );
    ADSLOGSTR( ADSLOG_MSGTYPE_HINT OR ADSLOG_MSGTYPE_LOG, 'Local System Time:%s', SYSTEMTIME_TO_STRING(fbTime.systemTime));
END_IF

You can see the written messages in the TwinCAT "Error List" window.

Further time and time zone functions and function blocks:

Requirements

Development environment	Target platform	PLC libraries to be integrated (category group)
TwinCAT v3.1.0	PC or CX (WES7/Win7/Win10: TC RT x86/x64, WEC6/7: TC RT x86, WEC7: TC CE7 ARMV7, TC/BSD: TC RT x64, TC OS ARMT2)	Tc2_Utilities (System)