Overview: S-UPS library

TwinCAT PLC Library: SUPS

Overview

The library TcSUPS.Lib contains functions and function blocks which are needed in order to use the Seconds UPS. See sample project Sample_S_UPS.pro.

Function Blocks

Name | Description
FB_S_UPS | Function block to use the Seconds UPS from the PLC.
FB_NT_QuickShutdown | Internal function block for the QuickShutdown, used by the FB_S_UPS.

Functions

Name | Description
F_GetVersionTcSUPS | The function returns library version info.

Requirements

Component | Version
TwinCAT on the development PC, on the target system | TwinCAT 2.11 Build 2016 or higher (R2)


Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


FUNCTION_BLOCK FB_NT_QuickShutdown

The function block FB_NT_QuickShutdown is used to immediately reboot the PC without stopping TwinCAT or the operating system Windows.

Attention:
The function block FB_NT_QuickShutdown is used internally from FB_S_UPS and is not intended to be used elsewhere!

FUNCTION_BLOCK FB_NT_QuickShutdown

VAR_INPUT

VAR_INPUT
    NETID :T_AmsNetId;
    START :BOOL;
    TMOUT :TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

NETID : AmsNetID of the PC.

START : rising edge leads to an immediate reboot of the PC.

TMOUT : Timeout time.

VAR_OUTPUT

VAR_OUTPUT
    BUSY  :BOOL;
    ERR   :BOOL;
    ERRID :UDINT;
END_VAR

BUSY : The QuickShutdown is being executed.

ERR : Is TRUE, if an error occurs.

ERRID : Delivers the error number in case that ERR is TRUE.

Development environment | Target plattform | Hardware | PLC Libraries to include
TwinCAT v2.11.0 Build 2016 or higher (R2) | PC (i386) | Second-UPS | TcSUPS.Lib


FUNCTION_BLOCK FB_S_UPS

The function block FB_S_Ups can be used on PCs with Seconds UPS, to communicate from the PLC with the UPS. The FB_S_Ups can be used to save persistent data and to QuickShutdown the PC in case of a power failure. The INPUTs of the FB_S_UPS should be used with the default values.

Attention 		Data loss
The Seconds UPS is only capable of holding the voltage for a few seconds. This is just enough time to save the persistent data. The used persistent saving mode must be "SPDM_2PASS", even though if this could causes realtime problems. The router memory must be big enough in order to save the persistent data!

Mode eSUPS_WrPersistData_Shutdown (default setting): The persistenten data are written and a QuickShutdown is automatically performed.

Mode eSUPS_WrPersistData_NoShutdown: Only the persistenten data are written, a QuickShutdown will not be performed.

Mode eSUPS_ImmediateShutdown: a QuickShutdown is immediatelly performed.

Mode eSUPS_CheckPowerStatus: only the powerfailure will be detected, no action is performed. In case of the powerfailure the FB waits until the tRecoverTime (10s) has expired before it goes back to the PowerOK state.

The UPS will switch off the main board after the capacitors have been discharged, independent of the mode and therefore independent of the writing of the persistent data and of the QuickShutdown, even if the power supply is restored.

The capacity of the UPS is to small to hold the system alive during longer power outages. The saving of the persistent data has to be done to the Compact Flash, since a hard disk cannot be operated if the UPS supplies the voltage. After the saving of the persistent data a QuickShutdown will be executed.

Attention 		Attention if files are modified:
If other applications or the PLC are keeping files open or write to files during a power failure, then these files can get corrupted, since the QuickShutdown immediately reboots the PC.

Attention 		Attention if using Windows XP embedded:
The EWF (Enhanced Write Filter) or the FBWF (File Based Write Filter) has to be activated in order to ensure the validity of the Windows XP embedded files on systems with a Seconds UPS.

In case of the EWF the TwinCAT\Boot folder needs to be located on a not protected partition (see in the registry: HKEY_LOCAL_MACHINE\SOFTWARE\Beckhoff\TwinCAT\System\BootPrjPath).

In case of the FBWF the TwinCAT\Boot folder needs to be excluded from the protection (see Beckhoff FBWF Manager, Exclusion Settings).

FUNCTION_BLOCK FB_S_UPS

VAR_INPUT

VAR_INPUT
    sNetID          : T_AmsNetId := '';               (* '' = local netid *)
    iPLCPort        : UINT := AMSPORT_R0_PLC_RTS1;    (* PLC Runtime System for writing persistent data *)
    iUPSPort        : UINT := 16#4A8;                 (* Port for reading Power State of UPS, dafault 16#4A8 *)
    tTimeout        : TIME := DEFAULT_ADS_TIMEOUT;    (* ADS Timeout *)
    eUpsMode        : E_S_UPS_Mode := eSUPS_WrPersistData_Shutdown; (* UPS mode (w/wo writing persistent data, w/wo shutdown) *)
    ePersistentMode : E_PersistentMode := SPDM_2PASS; (* mode for writing persistent data *)
    tRecoverTime    : TIME := T#10s;                  (* ON time to recover from short power failure in mode eSUPS_WrPersistData_NoShutdown/eSUPS_CheckPowerStatus *)
END_VAR

sNetID : AmsNetID of the PC.

iPLCPort : Port number of the PLC runtime system (AMSPORT_R0_PLC_RTS1 = 801, AMSPORT_R0_PLC_RTS2 = 811, AMSPORT_R0_PLC_RTS3 = 821, AMSPORT_R0_PLC_RTS4 = 831).

iUPSPort : Port number for reading the UPS-State (default value is 16#4A8).

tTimeout : Timeout for the execution of the QuickShutdown.

eUpsMode : eUpsMode defines, if persistent data need to be written and if a QuickShutdown needs to be executed.
The default value is eSUPS_WrPersistData_Shutdown, means with writing of the persistent data and then a QuickShutdown. See E_S_UPS_Mode.

ePersistentMode : Mode for the writing of the persistent data. Default value is SPDM_2PASS.

tRecoverTime : Time which will be waited after a power failure (in case of UPS modes without shutdown) to go back to the status PowerOK.
The tRecoverTime needs to be a little bit bigger than the maximum holding time of the UPS, since the UPS will shut off even if the power supply is restored.

VAR_OUTPUT

VAR_OUTPUT
    bPowerFailDetect	: BOOL;            (* TRUE while powerfailure is detected *)
    eState 		: E_S_UPS_State;   (* current ups state *)
END_VAR

bPowerFailDetect : TRUE if a power failure is detected; FALSE if the power supply is sufficiant.

eState : internal state of the function block, for the values see E_S_UPS_State.

VAR_GLOBAL

VAR_GLOBAL
    eGlobalSUpsState : E_S_UPS_State;    (* current ups state *)
END_VAR

eGlobalUpsState : internal state of the function block as a global copy of eState, for the values see E_S_UPS_State.

Development environment | Target plattform | Hardware | PLC Libraries to include


FUNCTION F_GetVersionTcSUPS

The function returns library version info.

FUNCTION F_GetVersionTcSUPS : UINT

VAR_INPUT
    nVersionElement : INT;
END_VAR

nVersionElement : Version element:

  • 1 : major number;
  • 2 : minor number;
  • 3 : revision number;
Development environment | Target plattform | Hardware | PLC Libraries to include


TYPE E_S_UPS_Mode

eSUPS_WrPersistData_Shutdown: Writing of persistent data and then a QuickShutdown

eSUPS_WrPersistData_NoShutdown: Only writing of the persistent data (no QuickShutdown)

eSUPS_ImmediateShutdown: Only QuickShutdown (no writing of persistent data)

eSUPS_CheckPowerStatus: Only check status (neither writing of persistent data nor a QuickShutdown)

Development environment | Target plattform | Hardware | PLC Libraries to include


TYPE E_S_UPS_State

eSUPS_PowerOK:
    in all modes: Power supply is OK

eSUPS_PowerFailure:
    in all modes: Power supply is faulty (only shown for one PLC cycle)

eSUPS_WritePersistentData:
    in Mode eSUPS_WrPersistData_Shutdown: Writing of persistent data is active
    in Mode eSUPS_WrPersistData_NoShutdown: Writing of persistent data is active

eSUPS_QuickShutdown:
    in Mode eSUPS_WrPersistData_Shutdown: QuickShutdown is active
    in Mode eSUPS_ImmediateShutdown: QuickShutdown is active

eSUPS_WaitForRecover:
    in Mode eSUPS_WrPersistData_NoShutdown: Wait for the reestablishment of the power supply
    in Mode eSUPS_CheckPowerStatus: Wait for the reestablishment of the power supply

eSUPS_WaitForPowerOFF:
    in Mode eSUPS_WrPersistData_Shutdown: Wait for switching off of the PC by the UPS
    in Mode eSUPS_ImmediateShutdown: Wait for switching off of the PC by the UPS

Development environment | Target plattform | Hardware | PLC Libraries to include