Skip to main content

Using API Calls to Control Alarms Programmatically

Note

0_Sample_Project Example: AlarmManager

Alarms of observation type Alarm (API) are triggered programmatically in the application code using the functionality of the AlarmManager library and the IAlarmHandler9 interface. Alarms can be activated (ActivateAlarm)) or deactivated (DeactivateAlarm) via the interface. The state transitions can be set as desired. These kinds of alarms are defined either directly in an alarm group or as an alarm instance in an alarm group template.

Unlike observation via events (Event (API), alarms can be used for all alarm classes with all acknowledgement methods.

Important

Depending on the alarm class and its acknowledgement methods, it may be necessary for the visualization user to acknowledge the alarm at runtime.

Alarming via API

Defining an alarm with Alarm (API) type

  1. In Alarm Configuration, set an alarm group.

  2. In an alarm group, define an alarm of the observation type Alarm (API).

  3. In the Class column, select for example the alarm class Warning Orange and specify the desired alarm message under Message.

The alarm ID_20, which is triggered via API, is defined.

_visu_img_define_alarmconfig_ag_alarmapi.png

You can define such an alarm with any alarm class. Details are not required, which means that an alarm condition is not given. The alarm is triggered via an API call.

Implementing an API call

Procedure. Step by step

  1. Set the cursor at the program position where the API call should take place.

  2. Insert the API call.

    Tip

    Let the Input Assistant (F2) help you with this.

    Implementation

    This code activates the alarm ID_20 in the alarm group Alarms1Line.

    // Activate by API Call
Alarmmanager.AlarmGlobals.g_AlarmHandler.ActivateAlarm(1,Alm_Alarms1Line_Alarm_IDs.ID_20);

    This code deactivates the alarm ID_20 in the alarm group Alarms1Line.

    // Deactivate by API Call  
Alarmmanager.AlarmGlobals.g_AlarmHandler.DeactivateAlarm(1,Alm_Alarms1Line_Alarm_IDs.ID_20);

Alarming with alarm (API) via alarm instance

This is particularly relevant for library developers. Furthermore, alarm states can be explicitly set programmatically via the provided API methods.

Defining an alarm with Alarm (API) type

  1. In Alarm Configuration, set an alarm group template.

  2. In an alarm group, define an alarm of the observation type Alarm (API).

  3. In the Class column, select for example the alarm class Warning and specify the desired alarm message under Message.

The alarm ID_0, which is triggered via API, is defined.

Tip

You can also define an API alarm in an alarm group.

Implementing a function block and an API call

Procedure. Step by step

  1. Add a function block to your application to set the alarm states of the newly defined alarm in the IEC code.

    1. Select the application node and click the Add Object → POU command.

    2. Configure the POU as follows: name MyAlarmFB, type Function block, implementation language ST.

      Declaration

      FUNCTION_BLOCK MyAlarmFB
VAR_INPUT
END_VAR
VAR_OUTPUT
END_VAR
VAR
END_VAR

    3. Select the POU and add the ActivateAlarm and DeactrivateAlarm methods.

    4. Open the ST editor of the ActivateAlarm method and program the library call.

      Tip

      Let the Input Assistant (F2) help you with this.

      This code activates the alarm ID_0 from the alarm group template.

      METHOD ActivateAlarm : BOOL
VAR_INPUT
END_VAR
      // Activate Alarm Instance Alarm by API Call
Alarmmanager.AlarmGlobals.g_AlarmHandler.ActivateAlarmInstance(THIS, Alm_AlarmGroupTemplate_Alarm_IDs.ID_0);

    5. Open the ST editor of the DesctivateAlarm method and program the library call.

      This code deactivates the alarm ID_0 from the alarm group template AGT.

      METHOD DeactivateAlarm : BOOL
VAR_INPUT
END_VAR
      // Deactivate Alarm Instance Alarm by API Call
Alarmmanager.AlarmGlobals.g_AlarmHandler.DeactivateAlarmInstance(THIS,Alm_AlarmGroupTemplate_Alarm_IDs.ID_0);

      Object navigator

      _visu_img_alarmapi_agt_objects.png

  2. Instantiate the function block in the alarm group template.

    1. Open the editor of AlarmGroupTemplate and click the vertical ellipsis button in the Type for alarm definition row.

      The Input Assistant opens.

    2. Under Application, select the MyAlarmFB function block.

    The alarm definition is instantiated.

    _visu_img_define_alarmapi_in_agt.png

  3. Implement the API call in IEC code and add the alarm calls at the desired locations.

    Declaration

    PROGRAM PLC_PRG
VAR
    alarmTemplateInstance : MyAlarmFB;
END_VAR

    Implementation

        // Deactivate by API Call  
    alarmTemplateInstance.DeactivateAlarm();

        // Activate by API Call
    alarmTemplateInstance.ActivateAlarm();

  4. Create the alarm instances.

    1. Open the Alarm Configuration editor and click the Alarm Instances tab.

    2. Click the Create or update alarm instances button.

    The alarm instances within the Alarm Configuration are recognized and updated.

    _visu_img_alarmconfiguration_alarminstances.png
In this section: