Skip to main content

Using API Calls to Trigger Events Programmatically

Note

0_Sample_Project Example: AlarmManager

Events are alarms of observation type Event (API). They are triggered programmatically in the application code using the functionality of the AlarmManager library and the IArarmHandler7 interface.

Events are defined directly in an alarm group or in an alarm group template as an alarm instance.

For more information, see Example: AlarmManager

Alarming with an event

Defining an alarm with Event (API) type

  1. In Alarm Configuration, set an alarm group.

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

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

The alarm ID_0, which is triggered via API on an event, is defined.

You can define such an event with any alarm class. Details are not required and an alarm condition is not given. The event is triggered via an API call.

Tip

You can also define an event in an alarm group template.

Implementing an API call

An event is triggered in the code by the API call of the library FB instance RaiseEvent, with an alarm ID being passed. Each alarm has a unique ID. This can be used as a variable in the code and therefore serves as a transfer variable.

Specifically, the AlarmID variable is an enum following this scheme:

Alm_<name of alarm group>_ IDs.ID_<configured ID>

Procedure. Step by step

  1. Set the cursor at the program position where the function-block call should take place.

  2. Enter "AlarmManager" followed by a period.

  3. Select AlarmGlobals and enter a period.

    A window opens containing a list of all insertable elements ("List components" function).

    _cds_img_autocomplete_alarms.png

  4. In the same way, insert the elements g_AlarmHandler and RaiseEvent.

    You get the following line: Alarmmanager.AlarmGlobals.g_AlarmHandler.RaiseEvent.

  5. Now define the transfer variables AlarmGroup_ID and Alarm_ID. To do this, enter an opening parenthesis.

    A tooltip appears, showing information about the transfer variables

  6. Press the F2 key.

    The Input Assistant opens.

  7. On the Categories tab (_3_r.png), select the category Variables (_4_r.png).

    Input Assistant

    _cds_img_input_assistant_alarms.png

  8. Select the desired alarm group ID variable (_1_r.png).

    The variable is applied into the program line.

  9. Enter a comma and use the Input Assistant to insert the desired alarm ID variable (_2_r.png). Enter a closing parenthesis and a semicolon.

    You get the following program line:

    Alarmmanager.AlarmGlobals.g_AlarmHandler.RaiseEvent(Alm_AlarmConfiguration_Alarmgroup_IDs.ID_AlarmGroup1, Alm_AlarmGroup1_Alarm_IDs.ID_0);

    This code triggers the alarm ID_0 in the alarm group AlarmGroup1.

Triggering an event via an alarm instance

This is particularly relevant for library developers.

Important

If you observe the variable of a custom type (function block of structure) and you want to define an event for this POU, then you should preferably do this in an alarm group template.

It is an advantage that both the POU and the alarm group template can become part of a development library.

Defining an alarm with Event (API) type

  1. Under your application, create the Alarm Group Template named AGT_0.

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

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

The alarm ID_0, which should be triggered via API on an event, is defined.

This kind of alarm can be defined with an alarm class and acknowledgement method specified in the list box. Details are not required.

Implementing an API call

An event of an instance alarm is triggered by the API call of the library FB RaiseEventAlarmInstance or alternatively by RaiseEventAlarmInstanceByName.

Procedure. Step by step

  1. Implement the FB_MyAlarm function block with the METH_RaiseEvent method.

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

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

    3. Declare the function input variables.

      Declaration:

      FUNCTION_BLOCK FB_MyAlarm
VAR_INPUT
    xCondition : BOOL;
END_VAR
VAR_OUTPUT
END_VAR
VAR
END_VAR

    4. Select the POU and add the METH_RaiseEvent method.

    5. Open the ST editor of the METH_RaiseEvent 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 AGT_0.

      METHOD RaiseEvent : BOOL
VAR_INPUT
END_VAR
      Alarmmanager.AlarmGlobals.g_AlarmHandler.RaiseEventAlarmInstance(THIS, Alm_AGT_0_Alarm_IDs.ID_0);

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

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

      The Input Assistant opens.

    2. Under Application, select the FB_MyAlarm function block.

    The alarm definition is instantiated.

  3. Implement the API call in IEC code.

    Declaration

    PROGRAM PLC_PRG
VAR
    // Alarm Instances
    myInst : FB_MyAlarm;
    myInst2 : FB_MyAlarm;
END_VAR

    Implementation

    Alarmmanager.AlarmGlobals.g_AlarmHandler.RaiseEventAlarmInstance(ADR(myInst), Alm_AGT_0_Alarm_IDs.ID_0); 
Alarmmanager.AlarmGlobals.g_AlarmHandler.RaiseEventAlarmInstanceByName(ADR(myInst2), Alm_AGT_0_Alarm_IDs.ID_0, 'AGT_0');
In this section: