FB_LocalSystemTime

In some applications the local Windows system time is synchronized via the SNTP time server or a radio clock. The local Windows system time (the local Windows system time is displayed in the task bar) often has to be used in the PLC (e.g. for time stamp log messages to the HMI). For such applications the FB_LocalSystemTime function block can be useful.

This function block internally combines the functions of the following function blocks: RTC_EX2, NT_GetTime, FB_GetTimeZoneInformation and NT_SetTimeToRTCTime. The RTC_EX2 block can be used for generating time stamps for log outputs, for example. However, this block has the disadvantage that its time is not synchronised with the local Windows system time and must be resynchronised cyclically via the NT_GetTime function block (see RTC block examples in the documentation). Cyclic synchronisation 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 (daylight-saving/standard 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 synchronisations to be calculated.

	Imprecise system clock 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 block is only suitable to a limited extent for measuring tasks requiring higher precision, although it tends to be adequate for building automation applications, 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
...

VAR_INPUT

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

sNetID: A string containing the network address of the TwinCAT computer whose time is to be used for the synchronization can be given here. If it is to be run on the local computer, an empty string can be entered.

bEnable: 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 must set this input to TRUE once.

dwCycle: 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: Additional option parameters. The following parameters are currently available:

Bit 0: If this is set, the Windows system time is additionally synchronized cyclically with the hardware clock (RTC) (corresponds to the function NT_SetTimeToRTCTime). Default: Activated.
This option is irrelevant for a Windows CE system.

tTimeout: States the length of the timeout that may not be exceeded by execution of the internal ADS command.

VAR_OUTPUT

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

bValid: The time at the systemTime output is invalid if this output is FALSE. The time is valid if TRUE (i.e. it was synchronised with the local Windows time at least once).

systemTime: Local Windows system time.

tzID: Time zone information (daylight-saving/standard time).

Example in ST:

In the example the FB_LocalSystemTime function block is activated on program startup (rising edge at bEnable input). Once the time has been synchronised (bValid = TRUE), the PLC writes a message to the TwinCAT System Logview every 500 ms. The internal synchronisation 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

The written messages can be viewed in the TwinCAT System Manager Logview.

FB_LocalSystemTime 3:

Further time, time zone functions and function blocks:

FB_TzSpecificLocalTimeToSystemTime, FB_TzSpecificLocalTimeToFileTime, FB_SystemTimeToTzSpecificLocalTime, FB_FileTimeTimeToTzSpecificLocalTime, FB_GetTimeZoneInformation, FB_SetTimeZoneInformation, NT_SetLocalTime, NT_GetTime, NT_SetTimeToRTCTime, F_TranslateFileTimeBias, FB_LocalSystemTime

Requirements

Development Environment	Target System	PLC libraries to include
TwinCAT v2.10.0 Build > 1328	PC or CX (x86) CX (ARM)	TcUtilities.Lib