Promotic

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 watch "PROMOTIC video tutorial 4 - Communication drivers".

Basic properties of the driver:
- Usage of this driver requires purchase of the PmSNMP licence. When developing the application in the freeware mode PmFree, or with development environment and while testing it in runtime, this component is always functional.
- The communication is done for Ethernet (PROMOTIC application is client). Communication is by the UDP/IP protocol on port 161.
- The PROMOTIC application is the Master (it means that 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 the device (see further). This 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".
- 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 in the HexaString format (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 seconds since device power on (read only).
- IpAddress: Text string in the format of IPv4 address (read only).


Recommended values of the PmaComm object parameters:

Recommended values for the Ethernet-client parameters:
TCP/UDP remote port number161 (standard port number for the SNMP protocol)
 
See: Wikipedia: A list of TCP and UDP port numbers used by protocols to run network applications.
Ethernet transfer typeUDP
Description and recommended values for the Protocol parameters:
SNMP Agent Receive Buffer SizeThe maximum length of requested message (in bytes) that can be sent by the driver into the SNMP agent. According to 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 has identifier: "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 has identifier: "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 has identifier: "commRW".
Protocol parameters for SNMP version 3:
Security level
With authorization, no encryption
With authorization, with encryption
User nameDefined in SNMP agent. The name specifies the access level to the system.
For access in the script this entry has identifier: "usrName".
PasswordText string used for authorization with the SNMP server. Minimum length is 8 characters.
For access in the script this entry has identifier: "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 has identifier: "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 the 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 into the variable, only the single variable is sent into the device (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 item 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 the application is launched).
The identifier is usually 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:
1.3.6.1.2.1.1.1.0 = The address for the parameter that contains the value of the device descriptor. This value is saved in the OctetString type. The received value then will contain 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:
1.3.6.1.2.1.1.1.0;DisplayString = The value of the device descriptor with transfomation of HexaString to decoded text.
1.3.6.1.4.1.18248.20.1.2.1.1.2.1 = 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 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 the 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 the parameter data type.
Value (Variant) = Parameter value.


- SNMP Walk: This message periodically transmits the "SNMP GetNext" type messages. Each read the "NextOID" value of current reading is used as OID for the following reading. This is done until error response 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 1.3.6.1.2.1.1.1.
- There are following variables on the "Data-received" tab::
Content (String) = The text usually 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 for transmission.
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.
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 into the variable.
11 = NoCreation Variable does not exist, and the agent cannot create it.
12 = InconsistentValue Value is inconsistent with values of other managed objects.
13 = ResourceUnavailable Assignment of the value into 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 does not exist. The agent cannot create it because the named object instance is inconsistent with the values of other managed objects.

History:
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.27 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
© MICROSYS, spol. s r.o.