Promotic
WikipediaLinkedInYoutubeTwitterFacebook

PmChar - Driver for communication by user defined ASCII/BIN 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 PmChar license. 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-client or for serial link (COM1, COM2 ...) (for Ethernet-server the the PmCharServer communication driver is used).
- The driver is incorporated into the PROMOTIC system by means of the PmaComm object.

The driver supports to usage of the PmaCommMsg object. The PmaCommGroup object cannot be used.

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

 
The driver is simple but powerful tool for communication by user configured protocol. It is determined first of all for the communication where using a special communication protocol doesn't pay in the end.

Usage of this driver is especialy handy for:

- communications by simple protocols.
- both text and binary oriented communications.
- testing purposes.
 
The driver allows using both message of the Master type and of the Slave type.
Slave messages for Ethernet:
- Working only for setup "Ethernet transfer type = TCP".
- Even in such case the driver establishes connection (i.e. it is a client). Slave start to wait for receipt after the connection with the server is established.
 
By means of the PmChar driver it is possible to communicate with the total range of devices and PLC's whose protocol is simple and its description is known, for example:
- Data loggers of the OMEGA, ESC, .. company
- Landis&Gyr PRV1 and PRV2 types
- ABB CS31
- and many others
 
The PmChar driver is not determined for the emulation of more complex protocols (that require for example precise keeping the timing on the communication line, ongoing non-standard control of modem signals, etc.). We'll be glad to help you with the decision if the given protocol can be implemented by the PmChar driver; don't hesitate to contact us! (sw-support@microsys.cz).
 

Recommended parameters values:

Description and recommended values for the Protocol parameters:
Response receipt timeoutOnly for serial link. It is meaningful only for messages of the Master type. The time (in milliseconds) the driver is waiting for the response on sending the message. If no response comes during this time, then the transfer of the message is terminated (the onEndOfTransfer event is triggered with error 24 or 66).
Received data will always be in only one packetOnly for Ethernet.

If checked, then it is assumed that the entire contents of the received message will always fit into a single IP packet.

This setting affects the optimization of the reception rate if ETX can not be used:

Once the packet is received the reception is terminated and the system does not wait for timeout (defined in the "Timeout of one packet transfer [ms]" configurator).

The packet size is predefined by current network. It can be e.g. 521 bytes, 1024 bytes etc.

Use STXSpecifies whether the protocol uses a special char for starting the transmission. If the usage of the char for starting the transmission is enabled, then it is put automatically before the user data prepared for the transmission. On the other hand the fact if the char for starting the transmission finds itself at the beginning, is tested for each data receipt. If it does not, the communication message is terminated with an error.
STX valueSpecifies the ASCII value of the char for starting the transmission (it has usually the value of 2).
Use ETXSpecifies whether the protocol uses a special char for ending the transmission. If the usage of the char for ending the transmission is enabled, then it is put automatically after the user data prepared for the transmission. On the other hand the fact if the char for ending the transmission finds itself at the end, is tested for each data receipt. If it does not, the communication message is terminated with an error. The usage of the ETX signal optimizes the speed rate of the receipt when a message with a variable length is received (into the value of the String type). Immediately after receiving the ETX signal, the system regards the message as completed (eventually it expects only check sum chars) and it ends the receipt instead of waiting for the timeout between receiving two chars.
ETX valueSpecifies the ASCII values of the char for ending the transmission (it has usually the value of 3).
Check sumSpecifies the method of the check sum calculation:
- none: communication without the check sum.
- XOR 1 byte: The checksum of the XOR type is used (it goes about so-called vertical parity). It has the size of 1 byte and mathematically it is the XOR of all bytes that are included into the check sum.
- SUM 1 byte: The checksum of the sum type is used. It has the size of 1 byte and mathematically it is the arithmetic sum of all bytes that are included into the check sum (cut to 1 byte).
- SUM 2 byte: the same as "SUM 1 byte" but it has the size of 2 bytes (cut to 2 bytes).
- CRC 2 byte CCITT [polynom 0x1021 = x16+x12+x5+1, use SBUS]: (Cyclical Redundancy Check) - Special checksum, that is used for example in PmSBUS communication.
- CRC 2 byte IBM [polynom 0xA001 = x16+x15+x2+1, use Modbus]: (Cyclical Redundancy Check) - Special checksum, that is used for example in Modbus protocol.
- CRC 2 byte IBM [polynom 0x8005 = x16+x15+x2+1, use DF1]: (Cyclical Redundancy Check) - Special checksum, that is used for example in PmABradleyDF1 communication.
 
It is possible to enter where the checksum will be placed:
- at the end of message (after ETX)
- before ETX
 
It is possible to enter which data of the message have to be included into the check sum:
- All data before the check sum
- All data before the check sum except the first char (except STX)
- All data before the check sum except the last char (except ETX)
- All data before the check sum except the first and the last char (except STX and ETX)
 
If the checksum is used, then it is automatically transmitted. On the other hand on each data receipt it is checked if the correct checksum is placed at the end. If it does not, the communication message is terminated with an error.

Checksum calculation can also be done by the Pm.ArrayOper method.

Enable character replacement in received datacan be enabled if we want to replace the really accepted char with another one in the received data. It is used most often when we want to save the received data into the value of the String type but in the received data the char 00hex (binary zero) can appear. In this case it is necessary to replace the char 00hex by another one because the char 00hex is regarded as the end of the text. See the description further.

The character value is entered decimaly, see The ASCII table.

The communication description by the PmaCommMsg objects

Message parameters:
There is HexaString only in 'Data-sent'If checked, then it is presumed that there is only a single variable of the String type on the "Data-sent" page. The content of this variable is so-called HexaString that can be used in order to transfer binary values in the String type as folows:

For example if you are to send 4 bytes with binary values of 01 A0 00 B3 (hexadecimaly), then it is necessary to put into the variable of the String type the value of "01A000B3" - i.e. the text of 2*4=8 characters. This way you can easily transfer data containing binary zeroes, that are forbidden in the value of the String type.

The Pm.TransformValue(240) method can be used for preparation of the transferred data.

There is HexaString only in 'Data-received'The sane as the previous configurator, only for the Data-received page.

The Pm.TransformValue(241) method can be used for processing the received data.

This message will use next parameters (replace protocol parameters)(only for messages of the Master type) If checked, then the same configurators are displayed as for protocol parameters, (whetherto use the STX, ETX characters, the checksum). These parameters overrule the protocol parameters during the message transfer.
 
Thus really received/transmitted data has for example the following format:
[STX] "user data" [ETX] [checksum]

Note: Fields in the brackets can be modified by the above mentioned parameters. Then the designer configures only the sections marked as "user data" on the Data-sent and Data-received pages.

 
The PmaCommMsg object can be set for messages of the Master or Slave type (see "PmaCommMsg > Parameters > Message type" configurator). The transfer procedure for these message types is following:
- Master type:
- The object trasfer is started automatically (according to the "AutoRun transfer enabled" configurator) or by the Run method.
- The object is placed into the inner queue of waiting Master objects (multiple PmaCommMsg object may be waiting for data transfer simultaneously).
- When the object get its turn, the onBeginOfTransfer event is triggered. The designer can then set the data for example on the "Data-sent" page (but not necessarily if already set).
- The data from the Data-sent page is processed (e.g. the transformation from HexaString to binary form, the STX, ETX or checksum are added).
- The processed data is then sent via Ethernet or via the computer's serial port.
- If there are no variables on the "Data-received" page, then the transfer is terminated (the onEndOfTransfer event is triggered). This is used if the other side does not send any reply.
- If there are variables defined on the "Data-received" page, then the object waits for data receive from the other side.
- After the message is received, the data is checked and processed (the STX, ETX, and checksum is verified. If requested, then the transformation into HexaString is done), the processed data is then saved into the "Data-received" page and the onDataReceive event is triggered.
- the onEndOfTransfer event is triggered.
- Slave type:
- The object waits for receiving the data from other side. When the Master messages are being transferred the Slave message receive is blocked, i.e. Master messages are preferred.
- After the message is received from the other side it is decided which Slave object this message belongs to. If there is only a single Slave type object, then the data is transferred there, otherwise the procedure goes as follows:

The received message lenght is compared to requested messages defined on Data-received pages. The received message is assigned to the object that requested message of equal lenght (as the received message). If there are two objects requesting the same message lenght, then it is assigned to the first object - this object is then moved to the end and the next message (of the same lenght)is assigned to the second object, etc.

- After the received messages are saved into the "Data-received" page of corresponding object, the onDataReceive event is triggered. The designer can then set the data for transfer on the "Data-sent" page.
- If there are no variables on the "Data-sent" page, then the transfer is terminated (the onEndOfTransfer event is triggered). This is used if the PRMOTIC is not requested to send a reply to the other side.
- If there are variables defined on the "Data-sent" page, then the object modifies the data from this page (e.g. the transformation from HexaString to binary form, the STX, ETX or checksum is added) and the processed data is then sent to the other side.
- After the transfer is done the onEndOfTransfer event is triggered.
 
Text data transfer:
- If you place an item of the String type into the "Data-sent" page, then the message lenght can me modified dynamically (text of fluctuating lenght can be assigned into the value of the String type).
- If the "There is HexaString only in 'Data-sent'" configurator is set, then the text is transformed to binary data, that will be half as large (in bytes) than the text lenght. This is handy for binary oriented communications. In order to create the HexaString value easily, the Pm.TransformValue(240) method can be used (e.g. in the onBeginOfTransfer event).
- If not set, then the text is set without conversion. This is handy for text oriented communications. In order to create the formatted text easily, the Pm.StringFormat method can be used (e.g. in the onBeginOfTransfer event).
- If you place an item of the String type into the "Data-received" page, then it is possible to receive messages of fluctuating lenght.
- If the "There is HexaString only in 'Data-received'" configurator is set, then the received data is transformed into HexaString (that will have twice as many bytes as the received binary data). This is handy for binary oriented communications. In order to process the HexaString value easily, the Pm.TransformValue(241) method can be used (e.g. in the onEndOfTransfer event).
- If not set, then the received text is saved without conversion. This is handy for text oriented communications. In order to process the text easily, the Pm.StringScan method can be used (e.g. in the onEndOfTransfer event).

For the item of the String type on the "Data-received" page, it is necessary to define the lenght (in order to let the driver know what lenght is expected to be received). This can be done:

- either directly on the page by filling of the "Length" configurator
- or it is possible to leave this field blank and then to set the string of required length into the item of the String type by means of the PmaCommMsg.ReadVars property before the transmission of the message.

If the item of the String type is the last item on the page, then the variable number of chars is received up to the string length set by the above mentioned method.

If the item of the String type isn't the last item on the page, then the number of chars that corresponds exactly to the string length set by the above mentioned method, is received into this item.

 
Binary data transfer:

The common problem is receiving the data including the binary value 0 (further 00hex). Direct receiving of such data into the value of the String type does not work well because the String is always interpreted as a text terminated by the 00hex character. The data is received, but only the characters before the 00hex value are accessible. There are the following ways to solve this problem:

- receive the binary data from HexaString conversions (see the configurators There is HexaString only in 'Data-sent' and There is HexaString only in 'Data-received'). This is the general way how to dynamicaly transfer binary data by text. See the description above.
- or do not use variables of the String type on the pages Data-sent or Data-received, but use directly the Byte, Integer, etc. variables instead. This way disables receiving and sending the data of fluctuating lenght.
- or to use the "Enable character replacement in received data" configurator and to set there that the received char 00hex is to be replaced for example by the "#" character - if you know that the "#" character is not used in the transferred data (the "#" character has the value of 35, see The ASCII table). Then you can receive data only into a single data item of the String type and text there will sometimes contain the "#" cgaracter (instead of 00hex). Such text can then be processed (e.g. in the onEndOfTransfer event), for example, by the Split VBScript function that separates the text according to the separator "#".

History:
Pm9.00.02: Fixed bug: After closing the port the message of the Slave type was not completed correctly.
Pm8.03.27: Fixed bug: For Etnernet TCP the messages of the Slave type did not work.
Pm8.03.24: Fixed bug: Sometimes the driver stopped working when Ethernet connection failed while sending data.
Pm8.03.22: Generalization Ethernet protocol parameter "Received data will always be in only one packet" configurator, that can be used to optimize the speed of reception of short messages.
Pm8.03.13: Generalization for Ethernet Slave messages.
Pm8.01.02: Generalization for the possibility to receive the binary data into the HexaString value type (it is a String containing binary data - for example 3 bytes with hexadecimal values A1, 00 and 4B are saved into a string with 2*3 characters "A1004B"). This way it is possible to easily transmit any binary data.

See new configurators There is HexaString only in 'Data-sent' and There is HexaString only in 'Data-received'.

Pm8.00.02: Fixed bug: checksum was not calculated correctly in some cases
Pm7.01.00: now supports also communication via Ethernet
PROMOTIC 9.0.4 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