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.
- 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.
:
-
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:
Description and recommended values for the Protocol parameters:
| SNMP Agent Receive Buffer Size | The 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. |
|---|
| Version | SNMP 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 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.
For access in the script this entry has identifier: "commRO". |
|---|
| ReadWrite community name | See 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 name | Defined in SNMP agent. The name specifies the access level to the system.
For access in the script this entry has identifier: "usrName". |
|---|
| Password | Text string used for authorization with the SNMP server. Minimum length is 8 characters.
For access in the script this entry has identifier: "psw". |
|---|
| Privacy key | Text 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. |
|---|
:
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 starting the application).
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 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:
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.
| Definite part of OID | The 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::
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::
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
"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. |