Unit

Namespace

ZApplication

Extends

ZCore.Object

ZCore.ManagedObject

Unit

Inherited Properties

BootingHints

ExecutionHints

Booted

Busy

Done

Error

Inherited Methods

FB_init

Name

NotifyChild

Reject

SetName

TraceErrorStack

Abort

AbortErrorId

Accept

Assert

AssertCondition

ErrorId

ErrorMessage

ErrorSource

SetBusy

SetIdle

Implements

IUnit

IManagedObject

IObject

IError

IBootable

FUNCTION_BLOCK ABSTRACT Unit EXTENDS ZCore.ManagedObject IMPLEMENTS ZApplication.IUnit, ZCore.IManagedObject, ZCore.IObject, ZCore.IError, ZCore.IBootable

Outputs

Diagnostics DiagnosticMessage

Constructor

FB_init

METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL,
 parent : ZCore.IManagedObject) : BOOL

Inputs

bInitRetains BOOL

if TRUE, the retain variables are initialized (warm start / cold start)

bInCopyCode BOOL

if TRUE, the instance afterwards gets moved into the copy code (online change)

parent IManagedObject

Returns

BOOL

Properties

LockedByAsString

PROPERTY LockedByAsString : ZCore.ZString

Property Value

ZString

StateAsString

PROPERTY StateAsString : ZCore.ZString

Property Value

ZString

Methods

AbortErrorId

This method should be called in an actual implementation of a framework object if an error occcured during executing a sequence and was caused by itself. Compared to method Abort here it is possible to set a specific ErrorId for an error to differentiate between different error causes inside an application or sequence without the need of evaluating the error-strings.

The method changes the state of the object to Error or BootingError depending on the previous state of the object Busy or Booting, respectively.

Additionally, it sets a message to indicate the problem. The error source of the issue is set to THIS^ object and the error code is set to 0. Preexisting errors are not overwritten by calling this method twice or more.

Calling this method also resets a stored execution token from a former "Async" call as the token is not relevant any more.

A unit also appends an alarm and writes the error message to the diagnostics if it is aborted

METHOD PROTECTED AbortErrorId (
 errorId : UDINT,
 message : ZCore.ZString)

Inputs

errorId UDINT

(optional) error code of the issue

message ZString

Assert

This method should be called in an actual implementation of a framework object if an error occcured during executing a sequence and was caused by itself. Compared to method Abort here it is possible to set a specific ErrorId for an error to differentiate between different error causes inside an application or sequence without the need of evaluating the error-strings.

The method changes the state of the object to Error or BootingError depending on the previous state of the object Busy or Booting, respectively.

Additionally, it sets a message to indicate the problem. The error source of the issue is set to THIS^ object and the error code is set to 0. Preexisting errors are not overwritten by calling this method twice or more.

Calling this method also resets a stored execution token from a former "Async" call as the token is not relevant any more.

A unit also appends an alarm and writes the error stack to the diagnostics if the assertion fails

METHOD PROTECTED Assert (
 obj : ZCore.IError) : BOOL

Inputs

obj IError

Returns

BOOL

Cyclic

METHOD Cyclic ()

HaltAsync

Calling this method will trigger the halting mechanism of the currently active sequence. Calling this method also propagates the halt to all objects that are under control of the unit. To trigger a complete halt of a machine that is made of a unit hierarchy, where one unit controls all other units, it is enough to halt the topmost unit. Calling this method on a specific subunit is usually not required.

Caution

Please be aware that you can change the behavior of the running sequences with a halt and this behavior may not correspond to the expectations of a former caller. Since the task remains the same, a former requester (IStartToken of a previous method call) is not informed!

METHOD HaltAsync (
 startToken : ZCore.IStartToken,
 unit : REFERENCE TO Unit)

Inputs

startToken IStartToken

(optional) object to check if the method was executed successfully, if the unit is already controlled by a different unit the startToken may indicate an error

unit REFERENCE TO Unit

unit that wants to take control of the object

HomingAsync

METHOD HomingAsync (
 startToken : ZCore.IStartToken,
 unit : REFERENCE TO Unit)

Inputs

startToken IStartToken

(optional) object to check if the method was executed successfully - may be 0

unit REFERENCE TO Unit

unit that wants to take control of the object

IsLocked

METHOD IsLocked () : BOOL

Returns

BOOL

IsLockedBy

METHOD IsLockedBy (
 unit : REFERENCE TO Unit) : BOOL

Inputs

unit REFERENCE TO Unit

Returns

BOOL

ObserveDigital

This method checks for a falling edge on an input (IDigital) and starts the parameterized sequence of the selected newState.

Here are some standardized newStates for example:

• UnitStateMachineState.GoHome
• UnitStateMachineState.Stop
• UnitStateMachineState.Automatic

UnitStateMachineState.Halt has special behavior. If newState=UnitStateMachineState.Halt a halt is issued to the currently active sequence, but only when the unit is currently busy.

METHOD PROTECTED ObserveDigital (
 input : ZEquipment.IDigital,
 newState : INT) : BOOL

Inputs

input IDigital

digital input

newState INT

event to trigger if request is observed

Returns

BOOL

ObserveRequest

This method checks if a bool is active.

• For FALSE nothing is done
• For TRUE the bool is deactivated and the unit is switched into the desired state, that is provided by newState.

The state transition will only occur if is allowed. If the transition is not allowed, an error is logged and the unit will not change its state. UnitStateMachineState.Halt has special behavior. If newState=UnitStateMachineState.Halt a halt is issued to the currently active sequence, but only when the unit is currently busy.

METHOD PROTECTED ObserveRequest (
 request : REFERENCE TO BOOL,
 newState : INT) : BOOL

Inputs

request REFERENCE TO BOOL

request to observe

newState INT

event to trigger if request is observed

Returns

BOOL

PostCyclic

Cyclically called method that should be used for monitoring inputs, axes (...). The method is internally called after any sequences of the unit are called. This method can be implemented (overridden) by every object that is extending from Unit

METHOD PROTECTED PostCyclic ()

PreCyclic

Cyclically called method that should be used for monitoring inputs, axes (...). The method is internally called before any sequences of the unit are called. This method can be implemented (overridden) by every object that is extending from Unit

METHOD PROTECTED PreCyclic ()

RunAutomaticAsync

METHOD RunAutomaticAsync (
 startToken : ZCore.IStartToken,
 unit : REFERENCE TO Unit)

Inputs

startToken IStartToken

(optional) object to check if the method was executed successfully - may be 0

unit REFERENCE TO Unit

unit that wants to take control of the object

RunSequenceAsync

METHOD PROTECTED RunSequenceAsync (
 startToken : ZCore.IStartToken,
 unit : REFERENCE TO Unit,
 newState : INT)

Inputs

startToken IStartToken

(optional) object to check if the method was executed successfully - may be 0

unit REFERENCE TO Unit

unit that wants to take control of the object

newState INT

event to trigger if request is observed

SetBusy

This method should be called whenever an object starts an active action or when the object finished executing an action. The method will perform the following state transitions

busy Parameter	State before	State after
TRUE	Idle	Busy
TRUE	Error	Busy
TRUE	BootingError	Booting
FALSE	Busy	Idle

Other states are not effected by calling this method. The state table shows, that this method should/can only be used if an object is in its normal operation mode, after it has finished its initial Booting phase. To get from the Booting phase into the normal operation mode, use SetIdle.

Calling this method also resets a stored execution token from a former "Async" call if the object changes from Busy to Idle as the token is not relevant any more.

Calling this method with on=TRUE if the object is in an inactive state (Idle, Error, BootingError) resets diagnostics

METHOD PROTECTED SetBusy (
 busy : BOOL)

Inputs

busy BOOL

SetStateMachine

Assigns the statemachine to an interface, which is used for processing. This method also passes the listener processor to the statemachine

METHOD SetStateMachine (
 statemachine : IUnitStateMachine)

Inputs

statemachine IUnitStateMachine

StopAsync

Stops the unit abruptly. Calling this method takes the unit to its Stop Sequence, performing is a hard stop: If the unit is currently in an active sequence (i.e. Automatic) it will execute this sequence one more time so it is possible to react to the stop with OnStop. However, in the same cycle the unit is also switched to the stop sequence.

Stopping is allowed from any state, besides FaultReaction, Fault, Stop, Init, Boot and stopping ignores the locker of the unit. For instance, if unit1 controls subUnit1, unit2 may still stop SubUnit1. However, there is a subtle difference.

• For subUnit1.StopAsync(startToken:=startToken, unit:=unit1), subUnit1 will end up in the Stopped state and will be done (subunit1.Done=TRUE), since it is a normal command from the controlling unit to the controlled unit.
• For subUnit1.StopAsync(startToken:=startToken, unit:=unit2), subUnit1 will end up in the Stopped state but will report an error (subunit1.Error=TRUE), since it is a forced command from a non-controlling unit. The reported error is "Forcefully stopped by unit2".

The parameter unit of this method is only used for making forced stops easier to trace in the logger.

Note

Even if the unit is in an inactive state, calling this method will trigger the Stop Sequence and subsequently put the unit in its Stopped state. The behavior is implemented like this, because the Stop Sequence, while not always the case, can change the physical state of the machine (move axes, switch off power, ...)

METHOD StopAsync (
 startToken : ZCore.IStartToken,
 unit : REFERENCE TO Unit)

Inputs

startToken IStartToken

(optional) object to check if the method was executed successfully - may be 0

unit REFERENCE TO Unit

unit that requests the stop, if not locked by another unit, the passed unit will be the new locker of this object

TryLock

METHOD TryLock (
 unit : REFERENCE TO Unit) : BOOL

Inputs

unit REFERENCE TO Unit

unit that wants to take control of the object

Returns

BOOL

Unlock

This method releases the internal mutex of the Unit such that it may be locked and controlled by a different Unit (including itself).

The method will succeed (return TRUE) if the unit has been actually locked by the unit that is passed as parameter. If the object is still Busy (i.e. it is still executing an active Sequence like Automatic, Stop, FaultReaction, ...) the lock is passed the the object itself such that it can not be locked by a different Unit.

The method will fail (return FALSE) for the following coditions

• unit does not actually own this object.
• the object is locked by itself (unit = THIS), but is still Busy.

Note

The unlock mechanism ensures that a Unit that is Busy is always locked - at least by itself.

METHOD Unlock (
 unit : REFERENCE TO Unit) : BOOL

Inputs

unit REFERENCE TO Unit

unit that wants to take control of the object

Returns

BOOL