Defining a Custom SNMP Device

Scenario: You want to configure Desigo CC to monitor an SNMP device that is not included among the predefined ones provided with the installation (UPS, Printer, Scalance Switch, Analog Value, Multi-State Value, Binary Value, String Value, Time Value). This requires creating an SNMP library for the custom device, into which you import and configure its SNMP data model.

 

Reference: For background information, see SNMP Library.

 

Workflow diagram:

 

 

Prerequisites:

  • You are trained and authorized to work with system libraries.
  • System Manager is in Engineering mode.
  • System Browser is in Management View.

 

Steps:

1 – Prepare a CSV Data Model File for the Custom SNMP Device
  • You obtained the Management Information Base (MIB) file for the SNMP device. This is generally supplied by the manufacturer.
  • You obtained the SNMP Data Model CSV file template.
  1. Use a MIB browser to analyze the MIB file and obtain the Object ID (OID) and Data Type information of the SNMP device. Each OID identifies a property that can be read or written using SNMP.
  1. Open the CSV file and edit the SNMP data model to define the data point types (DPTs) and data point elements (DPEs, or properties) for the custom device. See SNMP Data Model and SNMP Data Types Relationship as reference.

 

2 – Create an SNMP Library for the Custom Device

NOTE: This procedure covers how to create an SNMP library for the custom device by cloning the structure of the L1-Headquarter SNMP library. If you want to manually create the structure of the library, see Manually Creating a New Library.

 

  • You are authorized to handle libraries for the specific customization level (L4-Project, L3-Country, or L2-Region) where you want to create the customized SNMP library.
  1. In System Browser, select Project > System Settings > Libraries > L1-Headquarter > Global > SNMP.
  • The Library Configurator tab displays.
  1. Click Customize the entire library to a lower level .
  • A confirmation message displays.
  1. Click OK.
  • The structure of the selected library is cloned under the allowed customization level (for example, L4-Project > Global > SNMP).
  • Version indicates the version of your SNMP library.
    The major version identifies the independent library versions related to the same device. For example, if the SNMP device will change in future thus requiring modification of the SNMP library (new DPTs or new DPEs added to an existing DPT), you can create a new major library version that will be used for those new SNMP devices only. The minor version is used instead to identify any library upgrade or maintenance activities (such as, new symbols, update of text groups, and so on).
  • Dependencies indicate the libraries from which the SNMP library depends. If you modify the dependencies by adding libraries to this list, the SNMP library cannot be imported in the project if the libraries in the list are not installed.

 

3 – Import the CSV Data Model File into the Customized Library

Importing a CSV Data Model file will add to the library all the object models (DPTs, with their corresponding DPEs) for the custom SNMP device defined in that file.

 

Information

The import of a CSV Data Model file differs from a library import, which instead brings into the project the SNMP library with all the data (object models, text groups, symbols, icons, and so on) needed to use the SNMP device.

 

  1. In System Browser, select Project > System Settings > Libraries > [L4-Project, L3-Country or L2-Region] > Global > SNMP > Object Model.
  1. Select the Import tab.
  1. Click Browse.
  • The Open dialog box displays. It contains all the configuration files available in the chosen directory.
  1. Select the CSV file you want to use (for example, SNMP Data Model Ver. 2.0).
  1. Click OK.
  • The complete path of the selected file displays. The Source Items preview lists all the available items.
  1. Select the DPTs to import by transferring the desired items from the Source Items list to the Items to Import list and click .
  1. Click Import.
  • A confirmation message displays.
  1. Click Yes.
  • The import starts. The Import tab refreshes to display the Import in progress page where you can check the import state. When the import completes successfully, the Import dialog box displays its outcome.
  1. Click OK to close the dialog box.
  • The DPTs that you selected to import are added to System Browser under the SNMP Object Model folder.

 

4 – Define the Main Settings of the SNMP Object Models

Repeat this procedure for each DPT object model that was added to the Object Model folder of the SNMP library.

  1. In System Browser select Project > System Settings > Libraries > [L4-Project] or [L3-Country] or [L2-Region] > Global > SNMP > Object Model > [SNMP object model].
  1. Select the Models & Functions tab.
  1. Open the Main expander. Here you must define the basic settings of the SNMP Object Model.
  1. Select the Default property.
    This parameter is the property that appears in the Value column of the Textual Viewer (System Manager in Operating mode).
  1. Select the Managed type.
    This parameter indicates the application that is loaded when selecting the data point instance.
    NOTE: Always use SNMP Object for the SNMP points.
  1. Leave Generic create and Generic delete unselected.
    These options enable the possibility to add or delete the point instance (point added in the configuration under the SNMP network) from the Object Configurator tab.
    NOTE: Do not use these options for the SNMP devices. Setting these options may result in an unwanted behavior when deleting these objects.
  1. (Optional) Select the Limit number of children option.
    This option limits the number of objects that can be added under the data point instance to the value set as Max. children.
  1. (Optional) Enter the Default name.
    If configured, it indicates the name and description used in the New Object dialog box when adding an SNMP device under the SNMP network.
  1. Specify Parents: GMS_SNMPNetwork.
    This setting indicates the parent DPT of the SNMP device. If configured, the SNMP device can be added to the project under the configured parent node only. In the above example, MySNMP_Device can be added only under the SNMP network.
    NOTE: When configuring SNMP, always set GMS_SNMPNetwork as parent. This allows adding the SNMP device under the SNMP network. If you do not configure the parent properly, it will not be possible to add the SNMP device to the project configuration.
  1. In the Presets section, specify Discipline, Subdiscipline, Type, and Subtype values for the SNMP DPT.
    These settings can be used, for example, in scopes or operating procedure configurations.
  1. Click Save .

 

5 – Define the Properties Settings of the SNMP Object Models

Repeat this procedure for each DPT object model that was added to the Object Model folder of the SNMP library.

  1. In System Browser, select Project > System Settings > Libraries > L4-Project or L3-Country or L2-Region > Global > SNMP > Object Model > [SNMP object model].
  1. Select the Models & Functions tab.
  1. Open the Properties expander. Here you must specify the attributes for each individual DPE (property) belonging to this DPT (object).
  1. For each property in the list, use the check boxes and drop-down list to enter its settings. Refer to the tables below for an explanation of each setting.
  1. Click Save .

 

 

The properties of a DPT are grouped as follows.

 

Description

1

CommonStatus

Mandatory properties required for Desigo CC SNMP components to work correctly. They are the result of the import of the line *;CommonStatus;Ref;_GmsSNMP_CommonStatus; defined in the CSV file.

2

CommonSettings

Mandatory properties required for Desigo CC SNMP components to work correctly. They are the result of the import of the line *;CommonSettings;Ref;_GmsSNMP_CommonSettings; defined in the CSV file.

3

SNMP Properties

Properties explicitly defined for the SNMP points to read from the SNMP device. Each property represents an SNMP point and the corresponding variable type.

 

Information

The configuration of the properties attributes, especially for the mandatory DPEs, presented in the previous figure, is optimal for each SNMP device to integrate. When configuring a new object model, we suggest copying the settings from the SNMP object model provided for the Global library in the L1-Headquarter library level (make a screenshot and copy from the image).
Even though you can freely define the SNMP properties attributes, the configuration presented in the previous figure can be considered consistent and working with the majority of the SNMP object models.

 

Setting

Description

FS

Indicates that the property has a Field System alarm configured.

A Field System alarm is an event arriving from the field. This means that it is generated by a supported control unit or field device where the driver is in charge of generating this kind of alarms generally based on specific alarm tables.

MS

Indicates that the property has a Management Station alarm configured.

A Management Station alarm is an event internally triggered by the management station (and not generated by a driver that has an alarm table associated). SNMP uses Management Station alarm types.

VL

Indicates that the property is logged in the Value Log (Event) of the History Database.

The Value Log is the database that collects any information relevant to value changes for trending (for example, temperature value for an Analog Input Temperature Sensor).

AL

Indicates that the property is logged in the Activity Log of the History Database.

The Activity Log is the database that collects any information relevant to the operators' activity or system activity (for example, alarm handling, acknowledged alarms, and so on).

DL0

If set, the property is visible in configuration mode (System Manager in Engineering mode).

DL1

If set, the property is visible in the Status and Commands window available for graphic objects.

DL2

If set, the property is visible in the Operation tab (in the Contextual pane).

DL3

If set, the property is visible in the Extended Operation tab (in the Contextual pane).

DL4

if set, the property is exposed to the OPC server interface and other northbound interfaces in future that will make use of this setting.

Stat

If set, it enables the configuration of the Status option: you can define whether the specific property is only visible when it is different from the (configured) normal status. If associated to DL1, it displays the property in a bubble widget.

Persist

If set, the value of the property is saved in case Desigo CC is stopped and restarted. Basically, this option is set for the configuration of properties when they must be already valorized at system start-up (for example, the IP address of a control unit to connect).

NOTE: Typically, the properties required for SNMP must be updated during system operation; therefore this option must not be set.

Property Group

Used to assign a property to a specific group for which you can configure different access levels and visibility in the Security configuration.

6 – Define the Details, Alarm, and Command Configuration for each Property in an SNMP Object Model

Repeat this procedure for each DPT object model that was added to the Object Model folder of the SNMP library.

  1. In System Browser, select Project > System Settings > Libraries > [L4-Project] or [L3-Country] or [L2-Region] > Global > SNMP > Object Model > [SNMP object model].
  1. Select the Models & Functions tab.
  1. Open the Properties expander and click a property in the Property list.
  • The Details, Alarm Configuration, and Command Configuration expanders for the selected property display on the right.
  1. If the property is one of the following types, configure the expanders as instructed in the relevant linked procedure:
  1. Otherwise, if the property is not one of the above common types, configure the expanders as instructed in the remainder of this procedure.
  1. In the Details expander, define the DPE type, value attributes, and behavior in Desigo CC. Depending on the selected variable type, additional configuration sections may become available.
  • In the General section, select the Type and enter a Description.
    Type indicates the data type Desigo CC uses for the selected DPE. What you can select here strictly depends on the variable defined in the CSV file (for example, if you defined Int, you can choose among the Integer variables available in the configuration).
    Description represents the name that will be assigned to the DPE when created in the configuration.
  • In the Value Attributes section, specify the following:
    - Valid: Set this option to enable the configuration of the options in this section.
    - Min/Max: Enter the minimum and maximum values a DPE can have based on the used variable type.
    - Unit text group (if GmsInt or GmsUint type is used): Define the text group to use for retrieving the measurement unit associated to the value that will be read by SNMP (for example, MHz, W, or Mb). The measurement units are pre-defined in the selected text group.
    - Text group (if GmsEnum type is used): Define the text group to use to associate a specific text to a specific value (read from SNMP) and therefore to have a table for the different SNMP conditions.
    - Unit (available only for Unit Text Group): Select the unit to associate to the DPE from the text group defined in the Unit Text Group.
  • In the Display section, specify the following:
    - Valid: Set this option to enable the configuration of the options in this section.
    - Omit prop. descriptor: Set this option to hide the description of the DPE in all the display levels where the property displays.
    NOTE: This is valid for Default and Event Time Stamp display controls only. It does not work for Priority Array.
    - Display Control: Select how to display the property in all the display levels where the property displays.
    - Icon Library: Select the Icons library to use for the DPE.
    - Default Icon: Select the icon for the DPE. The available icons belong to the selected Icons library.
  • In the Status section, specify the following:
    - Disp. off-normal only: If set, the DPE displays in the Operation tab of the Contextual pane and the Status and Commands window only if its value is different from normal and if the related DL1 and DL2 levels are enabled for this DPE.
    NOTE: You can configure this option only if the Stat property attribute is enabled for the DPE.
    - Normal Value: Enter a value to be considered as normal condition for the previous option. If the property value is different from the defined Normal value, the property will display.
    NOTE: The Normal value can be explicitly defined here (for GmsInt and GmsUint types) or read from a text group (for GmsEnum type).
  1. In the Alarm Configuration expander, define how events are generated in the system based on the property value.
  • Valid: Set this option to enable the configuration of the options in this section.
  • Specify the Alarm Configuration: Define how events are generated based on the values read from a text group (for GmsEnum type), or explicitly defined in the alarm configuration (for GmsInt or GmsUint types).
    IMPORTANT: For SNMP we remind you to always use Management Station alarms. Field System alarms are dedicated to the drivers that support such option.
  • Alarm config. activated: When the events behavior is configured in the Alarm Configuration expander, by setting this option you activate the configuration (the use of the configuration is enabled).
    NOTE: Remember to clear this option if the creation of events in the system must be disabled.
  1. Generally, in the Command Configuration expander it is possible to define the commands (if any) for each DPE and optionally configure from one to three properties from which the commands depends on (Dependency 1, Dependency 2, and/or Dependency 3).
    NOTE: The current version of Desigo CC does not support SNMP commanding.
  1. Repeat steps 4 to 8 above for each property in the list.
  1. Click Save .

 

7 – Configure SNMP Text Groups for the Custom Device

During the configuration of a custom SNMP device you may want to associate the different SNMP values with descriptive texts to help the operators to understand the different conditions in the system.

  1. In System Browser, select Project > System Settings > Libraries > [L4-Project] or [L3-Country] or [L2-Region] > Global > SNMP > Texts.
  • The Text Group Editor tab displays.
  1. Configure the text group entries as follows:
    a. Click Add new row .
    b. In the new row, add a Value and a descriptive text for en-US and any other supported language.
    c. Click OK.
    d. Repeat the previous substeps to add all required texts.
  1. Click Save .
  1. In the Save Object As dialog box, do the following:
    a. Enter the Object name.
    b. In the Name field, enter for example, TxG_MySNMP_Events.
    c. In the Description field, enter for example, MySNMP Events.
    d. Click OK.
    NOTE: It is important to follow specific syntax rules when saving a text group:
    - The Object name and Name must have the following prefix: TxG_.
    - The prefix can be followed by a label to represent the device name or discipline name (for example, MySNMP or SNMP).
    - End the text with a label that indicates the group type (for example, Events).
    - In the Description field, you can enter free text.
  • The new SNMP text group object is added to System Browser.
  1. Exit and launch again the Desigo CC client application. In this way it is possible to view the new text group in the areas where it can be used.
    NOTE: If the syntax of the text group name is incorrect, Desigo CC cannot load the text group where it is referenced (for example, in the DPE Details configuration).

 

Field

Description

Value

Enter the value that the management station reads from the SNMP point. Basically, it indicates the real condition of the SNMP point using a numeric value (the variable is of the Unsigned Integer type).

Color

Select the color to associate to the text when the point reaches the value set. This field is optional.

Icon

Select the icon to associate to the text and to the point status when the SNMP reaches the value set. This field is optional.

en-US

Enter the text in English-US. Unless differently configured, the English language is always present in projects (mostly if an HQ project template is restored).

Other languages
(for example, fr-FR)

Enter the text for the second language. Each project can have a second configurable language (French in the above example).

For more details about text groups, see the relevant reference section.