Using the tsctl server from C

Writing a C application to talk to a tsctl server uses much of the same API as a direct access client application. The main difference is that instead of including "libtsctl.h", you will instead include "NetTsctl.h", which is a short-cut to include all of the Net class files. (The file "NetTsctl-export.h" in the net/ directory embeds everything into a single file so you can easily import it into your own project.) Then, instead of calling the class Init functions such as DIOInit, you will first call TsctlClient for each tsctl server you wish to connect to, following by the Net Init function (such as NetDIOInit) for each class on that server. Unlike the direct access counterparts, Net classes can throw exceptions which should be caught as shown in the next section.

When you write code to use the libnettsctl API your code does not need to run on a Technologic Systems board, as the API operates entirely over TCP/IP and does not depend on any direct hardware access.

The TsctlClient function takes two arguments: the host name of the tsctl server (such as "127.0.0.1", or "localhost"), and the tsctl Net Mode. The latter is one of the following:

• NetModeBlocking

In this mode, each call to a tsctl class function will block until the server returns completion.

• NetModeNonBlocking

In this mode, functions which return void and also return no data (i.e. pass no non-const pointers or arrays) will return immediately, without waiting for the server to reply. This can improve client performance by increasing the rate at which commands can be sent, while still invoking the functionality without delay.

• NetModeQueued

In this mode, functions which return void and also return no data (i.e. pass no non-const pointers or arrays) will queue the command for transmission to the server and return immediately. No commands will be sent until either a function is called which does return data, or else the transmission buffer is filled up. The default buffer size is 1436 bytes, but this can be changed by editing Net2.c.

This mode is useful for cases where overhead to the server should be minimized (by not sending each command in a separate TCP packet), or where several commands must be sent to the server all at once. For instance, using NetModeQueued, it is possible to send a command to turn off a relay, wait for the relay to actually physically turn off, and then turn it on again, even if the relay controls the power to the machine issuing the command. In other modes this would not work, because as soon as the command to turn off the relay was sent there would be a race between the board being shut down and the next command being sent, and even if the machine was able to send the delay command, it would never be able to send the command to turn the relay back on.

The tsctl TCP Net classes generate exceptions in case of network errors, such as an unexpectedly closed connection or the server no longer being reachable. Exceptions are implemented using the setjmp/longjmp calls. The tsctl connection struct returned by TsctlClient contains the space to hold the exception variable used by setjmp. A reasonable approach would be to wrap a sequence of calls to tsctl Net classes in a setjmp condition as follows:

   tsctl *conn;
   ...
   conn = TsctlClient(host,mode);
   ...

   if (!setjmp(conn->exception)) {
     // make API calls here
   } else {
     // handle exception here
   }

A couple of sample programs are included which demonstrate how to create an application to talk to the tsctl server. NetTest2 sends several commands to determine the round trip latency for sending commands. NetTest adds the functionality of printing the Model Id, Base Board Id, and then toggling the red LED on the board 100 times. After this, it does a Map test.

For use in your own projects, simply copy net/NetTsctl-export.h into your own project, renaming it to NetTsctl.h. Then, build libnettsctl.a (e.g. "make libnettsctl.a") and import it into your project.