PmSNMP - Driver for communication by the SNMP protocol

The driver is used for communication with devices using the SNMP protocol - see Communication by the SNMP protocol.
Before using this driver in the PROMOTIC application it is highly recommended to read the chapter: Communication using the PROMOTIC drivers.
Basic properties of the driver:
- Usage of this driver requires purchase of the PmSNMP licence. With the freeware version PmFree, or when developing the application (with development environment for tersting purposes), this component is always functional.
- The communication is done for Ethernet (PROMOTIC application is client). Communication by the UDP/IP protocol with target port 161.
- The PROMOTIC application is the MASTER (i.e. it initiates the data transfer) from this communication point of view.
- The driver supports:
- SNMP version 1 (SNMPv1).
- SNMP version 3 (SNMPv3) including the level of security with authorization and with encryption. The authorization is done by MD5 algorithm and the ecryption is done by DES.
- The driver so far does not support SNMP TRAP.
- The driver is incorporated into the PROMOTIC system by means of the PmaComm object.
- The driver supports usage of the PmaCommGroup object (for read and write the variables from/into SNMP agent / server / PLC device ...).
- The PmaCommMsg object is used only for special auxiliary messages that detect the variable names that can be read from device (see further). This kind of message is so far supported only for SNMP version 1.
- For easy integration of this driver into the application it is handy to use: Preconfigurations in group "SNMP communication protocol".
- The driver is not using MIB database. The MIB database can be read by external programs and this way obtain the addresses (OID) of desired parameters.
Supported data types:
- Integer: 4-byte integer (from -2 147 483 648 to +2 147 483 647) (for read and write).
- Unsigned32: 4-byte integer (from 0 to +4 294 967 295) (for read and write).
- Counter: 4-byte integer (from 0 to +4 294 967 295) (for read and write).
- OctetString: The text formatted as "HexaString" (binary data in the form of hexadecimal values stored as text string) (for read and write).

This is an universal type allowing to carry multiple other unspecified types. For example text string, date and time, physical address (MAC), array, etc. Unfortunately the data of this type do not carry the information regarding the type of contained data. In order to decypher the content it is necessary to know the MIB database.

Tip: In the Pm.TransformValue method, the support for "HexaString" is implemented.

In the driver, the content can be specified by additional information added (see the ItemId description). There are the following subtypes (in SNMP these are called "Composed syntax"):

- DisplayString = in this type the OctetString a text string is stored
- DateTime = in this type the OctetString date and time is stored

- ObjectIdentifier: Text string containing OID (read only).
- TimeTicks: The number of seconds since device power on (read only).
- IpAddress: Text string in the format of IPv4 address (read only).

Recommended parameters values of the PmaComm object:

Recommended values for the Ethernet-client parameters:
TCP/UDP port number161 (standard port number for the SNMP protocol)
Ethernet transfer typeUDP
Description and recommended values for the Protocol parameters:
SNMP Agent Receive Buffer SizeMaximum length of requested message (in bytes) that can be sent by the driver into the SNMP agent. Based on this value, the variables from one PmaCommGroup object are separated into the communication messages.

The default value is 512.

VersionSNMP protocol version number.

For access in the script this entry is identified as: "snmpVer".

SNMP v1 - Basic version of the SNMP protocol. This is not secured against "tapping".
SNMP v3 - SNMP protocol version with authorization and encryption.
Protocol parameters for SNMP version 1:
ReadOnly community nameCommunity string is a text parameter that defines so-called SNMP community where both the sender and receiver are members. This is used for implementing a simple security mechanism based on communities.

For "ReadOnly" access the "public" community string is often used.

For access in the script this entry is identified as: "commRO".

ReadWrite community nameSee previous description of "ReadOnly community name".

For "ReadWrite" access the "private" community string is often used.

For access in the script this entry is identified as: "commRW".

Protocol parameters for SNMP version 3:
Security level
With authorization, no encryption
With authorization, with encryption
User nameDefined in SNMP agent. This name specifies the access level to the system.

For access in the script this entry is identified as: "usrName".

PasswordText string used for authorization with the SNMP server. Minimum length is 8 characters.

For access in the script this entry is identified as: "psw".

Privacy keyText string to be used for encryption of transmitted data. Minimum length is 8 characters.

This configurator is visible only if the security level with encryption is set.

For access in the script this entry is identified as: "privKey". If not set, then it is SNMP without encryption.

Changing SNMP protocol parameters:

Protocol parameters can be modified and read in the script during runtime by methods: PmaComm.SetProtParam("ProtType") and PmaComm.GetProtParam("ProtType").

Entries are in KeyVal format, for example:
- for SNMP version 1: "snmpVer:1;commRO:public;commRW:private;"
- for SNMP version 3: "snmpVer:3;usrName:user1;psw:auth1;privKey:priv1;"

The communication description by means of the PmaCommGroup object

The PmaCommGroup objects can be used for this driver.

The variables in the PmaCommGroup object (or even better the variables in the PmaData object with ExtComm data extension) can be of arbitrary number, type and order. The driver uses optimalised internal communication messages for reading the data from the device.

All variables are read (if the "Data refresh enabled" configurator is checked). When writing to the variable, only the single value is sent (if the "Auto send when writing to item" configurator is checked).

Description of the "ItemID" configurator:

ItemId is the text identifier of the item that is used for addressing the value in the device. The ItemID configurator tells the driver how to receive or send the item value.

The text can be written manually, or it can be assembled in the window opened by the button to the right of the configurator.

Macro expression can be used for input (it is evaluated after starting the application).

The identifier is often represented just by the OID address. These addresses can be found either in MIB database or by using the SNMP Walk type message - see further. It is possible to enter only the OID addresses that represent values with supported data types.

Optionally it is possible to use the "semicolon" character and then the subtype - this is used only for the OctetString type parameter - see Supported data types.

Examples: = The address for the parameter that contains the value of device descriptor. This value is saved in the OctetString type. The received value then contains quite unreadable text in the form of HexaString. The real text can be obtained by processing this value by using the TransformValue(241) method, or more simply define also the subtype in the ItemId:;DisplayString = The value of device descriptor with transfomation of HexaString to decoded text. = The temperature value (type Integer) of the Papouch company thermometer.
Description of the "PmaCommGroup > Parameters > Special Parameters" configurator:
Definite part of OIDThe starting address of OID, that will be repeatedly used in multiple ItemId of the variables. If this starting address is defined, then only the second portion of the address can be entered in the ItemId of these variables.

The communication description by means of the PmaCommMsg object

The PmaCommMsg object can be used for special communications, that cannot be executed by the PmaCommGroup object. The following messages has been implemented into this driver:
- SNMP Get: Returns a value of the parameter together with its data type.
- There are following variables on the "Data-sent" tab::
OID (String) = OID parameter address
- There are following variables on the "Data-received" tab::
ErrCode (Byte) = Error number. See List of SNMP error codes.
DType (String) = Name of parameter data type.
Value (Variant) = Parameter value.
- SNMP GetNext: The same as the previous message "SNMP Get", plus also returns the OID address of the following parameter.
- There are following variables on the "Data-sent" tab::
OID (String) = OID parameter address
- There are following variables on the "Data-received" tab::
ErrCode (Byte) = Error number. See List of SNMP error codes.
NextOID (String) = OID address of the folowing parameter.
DType (String) = Name of parameter data type.
Value (Variant) = Parameter value.
- SNMP Walk: This message cyclicaly transmits the "SNMP GetNext" type messages. Each read "NextOID" value of current reading is used as OID for the following reading. This is done until error message is received. "SNMP Walk" uses this procedure to go through the whole parameter tree.
- There are following variables on the "Data-sent" tab::
OID (String) = Address of the strating parameter. It is OK to enter the value
- There are following variables on the "Data-received" tab::
Content (String) = The text usualy contains large number of rows. Each row contains the information concerning one parameter (OID address, data type, value).

List of SNMP error codes

The value of error code can be read from variable ErrCode on the "Data-received" tab of the PmaCommMsg object.
Value Description
0 = NoError No error occurred.
1 = TooBig The size of the response would be too large to transport.
2 = NoSuchName The name of a requested object was not found.
3 = BadValue The requested SNMP operation tried to change a variable but it specified either a syntax or value error.
4 = ReadOnly The requested SNMP operation tried to change a variable that was not allowed to change, according to the community profile of the variable.
5 = GenErr An error other than one of those listed here occurred during the requested SNMP operation.
6 = NoAccess The specified SNMP variable is not accessible.
7 = WrongType Value is of type that is inconsistent with the type required for the variable.
8 = WrongLength Value has a length that is inconsistent with the length required for the variable.
9 = WrongEncoding Value contains an Abstract Syntax Notation One (ASN.1) encoding that is inconsistent with the ASN.1 tag of the field.
10 = WrongValue Value cannot be assigned to the variable.
11 = NoCreation Variable doesn't exist, and the agent cannot create it.
12 = InconsistentValue Value is inconsistent with values of other managed objects.
13 = ResourceUnavailable Assigning the value to the variable requires allocation of resources that are currently unavailable.
14 = CommitFailed An attempt to set a particular variable failed.
15 = UndoFailed An attempt to set a particular variable as part of a group of variables failed, and the attempt to then undo the setting of other variables was not successful.
16 = AuthorizationError An authorization error occurred.
17 = NotWritable The variable cannot be written or created.
18 = InconsistentName variable doesn't exist. The agent cannot create it because the named object instance is inconsistent with the values of other managed objects.

Pm8.03.23: Fixed bug: In the OID address larger number than 8 388 607 did not work (number to 3 bytes).
Pm8.03.17: Generalization for SNMP version 3 (authorization and encryption).
Pm8.03.15: Fixed bug: message of the SNMP Walk type was sometimes terminated early if some item had StatusError.
Pm8.03.12: Fixed bug: While transferring some message types memory loss accured (PmSNMP, PmMBus, PmIEC8705, PmElgas2).
Pm8.03.05: Fixed bug: It was not possible to receive variables of the Unsigned32 type (bug since Pm8.3.4 version).
Pm8.03.04: Fixed bug: Bugfixes of problems with high volumes of data (sende nad receive).
Pm8.03.01: Fixed bug: Request identifier used wrong format in transmitted data. Only the first 128 messages were trasmitted.
Pm8.02.08: Created
PROMOTIC 9.0.14 SCADA system documentation - MICROSYS, spol. s r.o.

Send page remarkContact responsible person
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice