FB_BA_GetTime

The function block FB_BA_GetTime can be used to implement an internal clock (Real Time Clock RTC) in the TwinCAT PLC. When the function block is enabled via bEn, the RTC clock is initialized with the current NT system time. One system cycle of the CPU is used to calculate the current RTC time. The function block must be called once per PLC cycle in order for the current time to be calculated. Internally, an instance of the function blocks NT_GetTime, FB_GetTimeZoneInformation and RTC_EX2 is called in the function block. The time is output at the outputs tSysTi for the read system time and tUtcTi for the Coordinated Universal Time (UTC). This is determined internally from the system time and the time zone. If the system time and/or the time zone was entered incorrectly, the UTC time will also be wrong.

The system time is read cyclically via the timer to be set (nUpdRTC [sec]); it is used to synchronize the internal RTC clock. The time information (time zone, time shift relative to UTC, summer/winter time) is read in the same cycle. The output nRemTiUpd indicates the seconds remaining to the next read cycle. The time structures that are output, dtSysTi and dtUtc, can be resolved with the aid of the function block FB_BA_ExtTiSt into the components day, month, hour, minute etc.

	Information on the read/wait cycle During the read cycle, the outputs bRdySysTi and bRdyTiZoInfo change to FALSE, and the enumerator eTiZId shows 0 = eTimeZoneID_Unknown. If the read operation was successful, the outputs switch back to TRUE or show the respective information for summer or winter time, if available. If the read operation was unsuccessful - internally the system waits for a response for 5 seconds - the outputs remain at FALSE or 0, and another wait cycle is started before the next read cycle. Although the internal RTC clock is not synchronized in the event of an error and may still show the right time, the time information may be wrong, and therefore also the UTC time. Errors during the read cycle will, any case, show up in bErr and sErrDescr. The countdown output nRemTiUpd is not restarted until the wait cycle starts.

Inputs

VAR_INPUT
  bEn            : BOOL;
  tNetId         : T_AmsNetId;;
  nUpdRtc        : UDINT;
  bUpdRtc        : BOOL;
END_VAR

Name	Type	Description
bEn	BOOL	Enables the function block. If bEn = TRUE, then the RTC clock is initialized with the NT system time.
tNetId	T_AmsNetId	This parameter can be used to specify the AmsNetID of the TwinCAT computer, whose NT system time is to be read as timebase. If it is to be run on the local computer, an empty string can be entered.
nUpdRtc	UDINT	Time specification [s] with which the RTC clock is regularly synchronized with the NT system time. Internally this value is limited to a minimum of 5 seconds, in order to ensure correct processing of the internal function blocks.
bUpdRtc	BOOL	In parallel with the time nUpdRtc, the RTC clock can be synchronized via a positive edge at this input

Outputs

VAR_OUTPUT
  bRdySysTi         : BOOL;
  bRdyTiZoInfo      : BOOL;
  bRdyRTC           : BOOL;
  nRemTiUpd         : UDINT;
  tSysTi            : TIMESTRUCT;
  tUTC              : TIMESTRUCT;
  dtSysTi           : DT;
  dtUTC             : DT;
  nCurrentTime_ms   : UDINT
  eTiZId            : E_TimeZoneID;
  bErr              : BOOL;
  sErrDescr         : T_MAXSTRING;
END_VAR

Name	Type	Description
bRdySysTi	BOOL	The system time was read successfully from the target system
bRdyTiZoInfo	BOOL	The additional time information (time zone, time shift relative to UTC and summer/winter time) was read successfully.
bRdyRTC	BOOL	This output is set if the function block has been initialized at least once. If this output is set, then the values for date, time and milliseconds at the outputs are valid.
nRemTiUpd	UDINT	Countdown to next synchronization/update of the time information.
tSysTi	TIMESTRUCT	System time of the read target system. The time structure can be resolved with the aid of the function block FB_BA_ExtTiSt into its components: day, month, hour, minute etc. Info: If the function block is not enabled (bEn = FALSE), the output stSysTi and its subelements (day month, etc.) show 0.
tUTC	TIMESTRUCT	Coordinated Universal Time. This is determined internally from the system time and the time information read from the target system. The time structure can be resolved with the aid of the function block FB_BA_ExtTiSt into its components: day, month, hour, minute etc. Info: If the function block is not enabled (bEn=FALSE), the output tUTC and its subelements (day month, etc.) show 0.
dtSysTi / dtUTC	DT	Same as stSysTi/ stUTC, but in DATE-AND-TIME format: year-month-day-hour-minute-seconds. Info: If the function block is not enabled (bEn = FALSE), the outputs dtSysTi and dtUTC each display DT#1970-01-01-00:00, since this is the lower limit and it corresponds to the zeros in the structure representation of dtSysTi / dtUTC.
nCurrentTime	UDINT	Current time of day [ms].
eTiZId	E_TimeZoneID	Enumerator for summer/winter time information.
bErr	BOOL	This output is switched to TRUE if the parameters entered are erroneous.
sErrDescr	T_MAXSTRING	Contains the error description.

Error description
01: Warning: ADS error when reading the time (NT_GetTime). The ADS error number is stated.
02: Warning: ADS error when reading the time zone information (FB_GetTimeZoneInformation). The ADS error number is stated.

Requirements

Development environment	Required PLC library
TwinCAT from v3.1.4024.22	Tc3_BA2 from v5.2.5.0