PmSNMP - Driver for communication via the SNMP protocol

The driver is used for communication with devices using the SNMP protocol - see Communication by SNMP protocol.
Before using this driver in the PROMOTIC application it is highly recommended to read the chapter: Communicaton using the PROMOTIC drivers.
Basic properties of the driver:
- Using this driver is bound to purchase the license: PmSNMP. 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 via Ethernet.
- The PROMOTIC application is the MASTER (i.e. it initiates the data transfer) from this communication point of view.
- The driver is incorporated into the PROMOTIC system by means of the PmComm object.

The driver supports usage of PmCommData object (for read and write the variables from/into the PLC). The PmCommMsg object is used only for special auxiliary messages that detect the variable names that can be read from device (see further).

For easy integration of this driver into the application it is handy to use: Preconfigurations in group "SNMP protocol"

- The driver supports SNMP version 1.
- The drive is not using MIB database. The MIB database can be read by external programs and this way obtain the addresses (OID) of desired parameters.
- The river does not support SNMP TRAP.
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: Text string 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 (for read only).
- TimeTicks: Number of seconds since device power on (for read only).
- IpAddress: Text string in the format of IPv4 address (for read only).

Recommended parameters values:

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

The preset value is 512.

ReadOnly community name Community 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.

This parameter can be modified and read in runtime by the methods: SetProtParam("CommunityRO") and GetProtParam("CommunityRO").

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

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

This parameter can be modified and read in runtime by the methods: SetProtParam("CommunityRW") and GetProtParam("CommunityRW").

The communication description by the PmCommData objects

The PmCommData objects can be used for this driver.

The variables in the PmCommData object (or even better the variables in the PmData 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 enabled). When writing to the variable, only the single value is sent (if the Auto write when writing to item configurator is enabled).

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 while the application is launching).

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: = Address of 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 then 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 PmCommData > 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 used in the ItemId of these variables.

The communication description by the PmCommMsg objects

The PmCommMsg obejcts can be used for special communications, that cannot be executed by the PmCommData object. The following messages has been implemented into this driver:
- SNMP Get: Returns the value of the parameter together with its data type.
- There are following variables on the Data-sent page::
OID (String) = OID parameter address
- There are following variables on the Data-received page::
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 page::
OID (String) = OID parameter address
- There are following variables on the Data-received page::
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 page::
OID (String) = Address of the strating parameter. It is OK to enter the value
- There are following variables on the Data-received page::
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 page of the PmCommMsg object.
Value Description
0 = NoError No errors 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 The value specifies a type that is inconsistent with the type required for the variable.
8 = WrongLength The value specifies a length that is inconsistent with the length required for the variable.
9 = WrongEncoding The value contains an Abstract Syntax Notation One (ASN.1) encoding that is inconsistent with the ASN.1 tag of the field.
10 = WrongValue The value cannot be assigned to the variable.
11 = NoCreation The variable does not exist, and the agent cannot create it.
12 = InconsistentValue The 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 The variable does not exist; the agent cannot create it because the named object instance is inconsistent with the values of other managed objects.
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice