Table of Contents

DateTimeUM

Namespace
ZAux
Implements

Time-related operations in PLCs are uniquely implemented from every PLC-manufacturer. In IT it is standard to use the Unix time format beginning with 1.1.1970 and based on this, this class is giving this same time handling to Automation Engineers independently of its platform.

This function block should be used in every PLC-Runtime context where no Zeugwerk Framework is used. For usage inside this standardized framework one can use the DateTime class where running of the object is done by the framework automatically. Both classes are based on the DateTimeImpl class and offer various time-related operations, some of which are.

  • Synchronisation of PLC time with the Operation System (e.g. Windows). Desynchronisation of these two clocks occurs because the windows RTC is cyclically synced with internet time servers and the plc clock gets only updated (incremented) with the CPU time, which is not that precise. This task is performed cyclically with a parameterizeable period. Therefore, even though clocks are synchronized there may be a slight offset between calling UnixTimestamp and TimestampLocalPlc between a synchronization cycle. If the runtime would cyclically sync the PLC-Runtime-clock with the operating system clock this could cause problems in the realtime context.
  • Converting the timestamp value in one that is compatible to the standard unix timestamp. (e.g. for Beckhoff Twincat systems their timestamp starts on 1.1.1602)
  • Timezone correction
Note

Usually there is only one DateTime or DateTimeUM instance needed per PLC-Runtime-Instance.

For time measurement during one PLC-Cycle it is better to use the StopWatch Class in ZPlatform library which has a precision down to 100ns (CPU cycle tick)

To use this DateTimeUM just create an instance in a function block or program and make sure to call the Cyclic method in every PLC-cycle.

PROGRAM MAIN
VAR
  DateTime : ZAux.DateTimeUM;
  UnixTimestamp : ULINT;
  DateTimeString : ZCore.ZString;
END_VAR
-------------------
DateTime.Cyclic();
DateTimeString := ZAux.TimestampToString(DateTime.UnixTimestamp());
UnixTimestamp := DateTime.UnixTimestamp() + DateTime.UtcOffset;

FUNCTION_BLOCK DateTimeUM IMPLEMENTS ZCore.IDateTime, ZCore.IUnmanagedObject

Properties

Bias

This property returns the bias of the localtime to UTC in ms once DateTime is done with its booting process and thus, DateTime is in its Idle state. The bias is between localtime to UTC is defined as UTC = localtime + bias

Note

This property only returns valid information if the booting process of the object is finished, which can be checked with the State method.

PROPERTY Bias : LINT

Property Value

LINT

State

When starting the PLC, the DateTime object initializes its regional settings and syncs to the operating-system time. During this period, the object is in its booting state, only when initialization is finished, the object will obtain ObjectState.Idle. Everytime time object does a (re-)sync of the systemclock if the PLC clock, the object enters ObjectState.Busy.

IF _datetime.State() = ZCore.ObjectState.Idle OR_ELSE _datetime.State() = ZCore.ObjectState.Busy
THEN
 ; // _datetime object is ready to use
END_IF

PROPERTY State : ZCore.ObjectState

Property Value

ObjectState

SynchronizationPeriod

Controls the period (in seconds) in which the current time is synchronized with reported by the operating system.

Here, the operation system of the target is considered. Synchronization period defaults to 10 seconds and if the property is set to 0, synchronization is disabled.

PROPERTY SynchronizationPeriod : LREAL

Property Value

LREAL

Synchronized

This property returns TRUE if the object has a valid connection to a time syncing service, and the sync process has been successfully completed at least once. This usually occurs in the booting process and/or automatically after a period of time.

PROPERTY Synchronized : BOOL

Property Value

BOOL

UtcOffset

Returns the actual Utc Offset which gets retrieved from the local OS Timezone information

Note

This property only returns valid information if the booting process of the object is finished, which can be checked with the State method.

PROPERTY UtcOffset : LINT

Property Value

LINT

Methods

CalendarInfo

Returns an interface to a Calendar info data object represented by IDateTimeCalendarInfo based on the actual date shifted by a given utc-offset.

METHOD CalendarInfo (
 offset : LINT) : ZCore.IDateTimeCalendarInfo

Inputs

offset LINT

Returns

IDateTimeCalendarInfo

Cyclic

This method is executing all neccessary actions of the DateTimeImpl class to do its syncing and delta calulating stuff described here If used in Zeugwerk Framework context, this method is usually hidden and there is no further action needed (using DateTime class. If not used in Framework context, this method has to be called manually somewhere in the PLC-Application. It is a good approach to do this in the MAIN programm somewhere on top.

_dateTime.Cyclic()

its as simple as that

METHOD Cyclic ()

DeltaSecondsOs

Returns the time difference now - unixTimestamp in seconds. The parameter unixTimestamp is usually previously stored from a call to UnixTimestamp. This method should be prefered to calls to DeltaSecondsPlc that uses FILETIME timestamps in the local PLC context in contrast to this method.

Note

This method only returns valid information if the booting process of the object is finished, which can be checked with the State method.

METHOD DeltaSecondsOs (
 unixTimestamp : ULINT) : LREAL

Inputs

unixTimestamp ULINT

unix timestamp

Returns

LREAL

DeltaSecondsPlc

see DeltaSecondsOs

Note

This method only returns valid information if the booting process of the object is finished, which can be checked with the State method.

METHOD DeltaSecondsPlc (
 filetime : ULINT) : LREAL

Inputs

filetime ULINT

unix timestamp

Returns

LREAL

Now 

METHOD Now (
 offset : LINT) : REFERENCE TO ZCore.DateTimeRecord

Inputs

offset LINT

Returns

REFERENCE TO DateTimeRecord

SetTarget

Targetsystem where time information is retrieved from. If an empty string is used, the local target is used. For machines that are using several PLCs that are running on multiple computers, it is recommended to use the same DateTime target for all of them, because it facilitates in some cases, e.g. timestamp information in different logfiles are more precisely comparable to each other.

This method automatically causes DateTime to start (re-)initalization, which fill in turn fetch localization informations from the (new) target. During (re-)initalization the methods of the object should not be used. The current state of DateTime can be externally retrieved by the State method.

For Beckhoff Twincat specific PLC-Runtimes this should be given as a AMS-Net-Id string (e.g. 200.200.210.4.1.1).

METHOD SetTarget (
 netid : ZCore.ZString)

Inputs

netid ZString

AMS-Net-Id, e.g. 200.200.210.4.1.1

SetTimeout

Set timeout for unresponsive targets. This is usually only relevant if the target is not the local PLC.

METHOD FINAL SetTimeout (
 timeout : LREAL)

Inputs

timeout LREAL

in seconds (defaults to 3s)

TimestampLocalPlc

Returns the current timestamp in the filetime format with 100ns resolution. This time may differ vastly from the time information that the operation system shows, because over time PLC time and OS time may drift appart. If the actual time information is more important that tick counts, the method UnixTimestamp should be used that is returning timestamps that are synchronized to OS time.

Note

This method only returns valid information if the booting process of the object is finished, which can be checked with the State method.

METHOD TimestampLocalPlc () : ULINT

Returns

ULINT

UnixTimestamp

Returns the actual timestamp in unix time format (beginning on 1.1.1970) cyclically corrected with the generated time lag between OS-time (which gets cyclically synced with the internet time) and the plc-runtime-time which gets just incremented over the CPU-Tick-Counter. The returned timestamp has a resolution of 1ms.

If the UnixTimestamp needs to be corrected via UTC-Offset, just add the value of UtcOffset to the return of this method.

Note

This method only returns valid information if the booting process of the object is finished, which can be checked with the State method.

METHOD UnixTimestamp () : ULINT

Returns

ULINT