Promotic

PmChar - Driver for communication by user defined ASCII/BIN 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 PmChar 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) 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 the 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.
The usage of the 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 setting "Ethernet transfer type = TCP".
- Even in such case the driver establishes connection (i.e. it is a client). Slave messages 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 values of the PmaComm object parameters:

Description and recommended values for the Protocol parameters:
Response receipt timeoutOnly for serial link. It has sense 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 transmission 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 content 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 character for starting the transmission. If the usage of the character 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 character 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 character for starting the transmission (character has usually the value of 2).
Use ETXSpecifies whether the protocol uses a special character 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 character 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 if a message with a variable length is received (to 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 characters) and it ends the receipt instead of waiting for the timeout between receiving two chars.
ETX valueSpecifies the ASCII values of the character for ending the transmission (character 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:
- to the end of the 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 checksum
- All data before the checksum except the first character (except STX)
- All data before the checksum except the last character (except ETX)
- All data before the checksum except the first and the last character (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 PmBuffer.CalcCheckSum method.
Enable character replacement in received datacan be enabled if we want to replace the really accepted character with another one in the received data. It is used most often when we want to save the received data to the value of the String type but in the received data the character 00hex (binary zero) can appear. In this case it is necessary to replace the character 00hex by another one because the character 00hex is regarded as the end of the text. See the description further.
The character value is entered in decimal, see The ASCII table.

The communication description by means of the PmaCommMsg object

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" tab. 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 (in hexadecimal), 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" tab.
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 (whether to 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. The designer then configures only the sections marked as "user data" on the Data-sent and Data-received tabs.

The PmaCommMsg object can be set for messages of the Master or Slave type (see the "PmaCommMsg > Parameters > Message type" configurator). The transfer procedure for these message types is following:
- Master type:
- The object transmission 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 (more PmaCommMsg objects 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" tab (but not necessarily if already set).
- The data on the "Data-sent" tab page is processed (e.g. the conversion from HexaString to binary form, the STX, ETX characters 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" tab, then the transmission is terminated (the onEndOfTransfer event is triggered). This is used if the other side does not send any response.
- If there are variables defined on the "Data-received" tab, then the object waits for message receive from the other side.
- After the message is received, the data is checked and processed (the STX, ETX, and checksum is verified. If set, then the conversion into HexaString is done), the processed data is then saved into the "Data-received" tab 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 object of the Slave type, then the data is transferred there, otherwise the procedure goes as follows:
The received message length is compared to requested messages (defined on the "Data-received" tab). The received message is assigned to the object that requested message of equal length (as the received message). If there are two objects requesting the same message length, then it is assigned to the first object - this object is then moved to the end and the next message (of the same length) is assigned to the second object, etc.
- After the received messages are saved into the "Data-received" tab of corresponding object, the onDataReceive event is triggered. The designer can then set the data for transfer on the "Data-sent" tab.
- If there are no variables on the "Data-sent" tab, then the transmission is terminated (the onEndOfTransfer event is triggered). This is used if the PRMOTIC is not requested to send a response to the other side.
- If there are variables defined on the "Data-sent" tab, then the object modifies the data from this tab (e.g. the conversion from HexaString to binary form, the STX, ETX characters 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" tab, then the message length can me modified dynamically (text of fluctuating length can be assigned to 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 length. 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 PmFormat object can be used (e.g. in the onBeginOfTransfer event).
- If you place an item of the String type into the "Data-received" tab, then it is possible to receive messages of fluctuating length.
- 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" tab, it is necessary to define the length (in order to let the driver know what length is expected to be received). This can be done:
- either directly on the tab 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 the PmaCommMsg.ReadVars method before the transmission of the message.

If the item of the String type is the last item on the tab, then the variable number of characters is received up to the text string length set by the above mentioned method.
If the item of the String type isn't the last item on the tab, then the number of characters 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 to 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 are 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 dynamically transfer binary data by text. See the description above.
- or do not use variables of the String type on the tabs Data-sent or Data-received, but use directly the Byte, Integer, etc. variables instead. This way disables receiving and sending the data of dynamically fluctuating length.
- or to use the "Enable character replacement in received data" configurator and to set there that the received character 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 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 "#" character (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 parameters by the "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 to the value of the HexaString type (it is a String containing binary data - for example 3 bytes with values (in hexadecimal) A1, 00, 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
PROMOTIC 9.0.27 SCADA system documentation MICROSYS, spol. s r.o.

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