Serial communication e.g. for 6B Modules

The »Serial Toolkit« from the production range »RealTime Suite« provides an easy and comfortable opportunity to carry sending and receiving jobs for serial interfaces. You can choose between different modes for every individual application. The main difference is the signalization of the ending of a data transfer.

In the majority of cases the easy 'wait-mode' on receiving of data is enough if it has to wait for a particular number or character.

The sending of data could happen with the 'event mode' as a background activity which means the normal running of programs can be continued.

The following example shows, how to control a 6B module from analog devices by »Serial Toolkit« in the measurement engineering. For the purposes of this tutorial, we will not do an error analysis here, but it is advisable to do this!

Firstly you always have to open the particular COM interface. Choose driver implementation: For the "normal" application implementation, the flag KSF_USER_EXEC is used but with KSF_KERNEL_EXEC you choose the kernel implementation which is only available in »Serial Toolkit Plus«. This one has got the advantage to realize serial communication in real-time and it provides some more opportunities, e.g. the login of byte handler. In both cases, a handle for the identifying of the interface will be returned.

Handle hComm;
err = KS_openSerialPort( &hComm, "COM1", "19200,n,8,1", KSF_KERNEL_EXEC );

If the opening was successful, are the following properties of the COM1 interfaces initialized: transmission rate, parity, data and stop bits.

From now the driver of the Toolkit monitors the interface in the background and saves all incoming characters in its own buffer. Receiving orders which have started later can be buffered, analyzed and deleted. Before the measurement data is received( e.g. 6B analogical input modul), the request command is sent. You can do this easily in the background. The parameter is the address of the sending string.

Char* pXmitCmd = "#01\r"; // 01 ist die 6B-Modul-Nr.
err = KS_xmitPort( hComm, NULL, pXmitCmd, 0, NULL, KSF_DONT_WAIT );

The 'post-mode' will be configured by the NULL handle as signalization information and flag KSF_DONT_WAIT. It is not necessary to enter the number of sending characters – if it is connected with zero bytes, the driver will automatically detect the length of string.

The functions, which triggers the sending process, will be immediately returned to the post-mode. This is why the program can work on the next orders, while the Toolkit carries out the sending in the background.

Next, the only characters with requested measurement data will be received. The easiest method is to use ‘wait-mode’. The functions return to the start of the receiving order, if all characters are completely received (or if an error occured).

For the delivery of characters it is necessary to have a sufficient buffer. Additionally, the number of received characters has to be entered - here we have 9, because the format of 6B modul data were configured as "percent of full scale".

Char pRecvBuf[ 10 ]; // Empfangspuffer
err = KS_recvPort( hComm, NULL, pRecvBuf, 9, NULL, 0 );

Something to explain: the second parameter determines, how the user gets informed about the sending or receiving order. This could be an event or a Callback-handle or a NULL handle, what means that the function is blocked by its own until the order is concluded. Unless if in addition to the NULL handle the flag KSF_DONT_WAIT is entered: In this case, the function will be immediately returned and there is no signalization.

After successful receiving, all character are in the format ">+DDD.DD\r" in the receiving buffer. Every "D" is a number and "+"is the algebraic sign.

Refinements

Essentially, thats all! Now we want to go in the refinements.

For the last shown receiving function call, all characters were considered, which were internal buffered from the driver before. So you don’t have do worry about a few missing characters.

The characters which have been buffered can be erased with the function KSF_CLEAR_BUFFER.

Furthermore, the pointer of an integer variable can be delivered. If there was an error, you can use it to see how many characters were already received (the last character may be missing, it is not so important).

Let’s get back to the sending: We don’t get something to know about the end of data transfer in the above shown example. But if you want to get informed about the successful send of a sending order, you could, for example, create an event, which will be waited for - the best would be in its own thread. At first, we create an event object and get a handle for it:

Handle hXmitEvent;
err = KS_createEvent( &hXmitEvent, "MyTransmitEvent", 0 );

Than a thread has to be blocked by waiting for this event. Thereby you can enter a timeout value. If you want to have it endless, you have to enter ‘timeOut’ 0:

UInteger timeOut = 200*ms;        // maximal waiting time
err = KS_waitForEvent( hXmitEvent, 0, timeOut );

The thread will be blocked in the 'event mode' until the data transfer - here sending - is completed, an error occurs or the timeout time has expired.

After the end of a data transfer via a serial interface, you have to close it:

err = KS_closePort( hComm );

Thus this COM-interface is also available for other application.

Besides the described mechanisms, the »Serial Toolkit« provides even more transfer modes. On this basis is it possible to fulfill complex requests.

E.g. 'callback-mode', a customized callback routine will be called, if the entered number equals the transferred number. You can combine this mode with the 'Unending-mode': The content of entered sending puffer will be sent at start. The callback routine will be called after every sending circle. This could refresh, for example, a data part of a big circular sending telegram.

Additionally, different special handlers can be logged in, which will be called for determined events. These can be set up for each sent or received byte, transfer or timeout error, for the change of handshake lines (LSR/MSR) or for every hardware interrupt. Thereby, for example, you can give every incoming databyte a "timestamp" or a special character (e.g. a "token"). Immediate reaction by the sending of a suitable answer with call to a special adaptation function or an abortion of receipt. In this way, you can realize complex transferring protocols.

Conclusion

The described scenarios are typically orders of serial communication in the industry, which can be easily solved with the help of a »Serial Toolkits«. In nearly every case it is possible to apply an appropriate transfer mode of the Toolkit with the additional functions for state monitoring and controlling to solve such problems in a fast and easy way with a few function calls.