The tsctl command line client for remote access

The previous section alluded to being able to specify an @host parameter to tsctl commands. In order for this to work, it is first necessary to run the tsctl server on the board you want to control. The tsctl server listens for connections on various TCP ports, providing the ability to control the board remotely. Client code was be written in C, HTML/Javascript, Python, Javascript, or any other language that can talk to a TCP/IP socket or which can generate an HTTP POST. However, to start with, we will use the tsctl client itself.

First, start the tsctl server on the board you wish to control:

tsctl --server

Note:

If you link against uclibc, the server must be manually backgrounded due to issues with the daemon() call interacting with pthreads in uclibc.

Once the server is started, you can now invoke tsctl functionality remotely, by adding the @host parameter to any tsctl command. If you are running the tsctl client on the same board as the server, communication will still be over TCP/IP by specifying localhost (or 127.0.0.1) as the host. If you do not specify a host and the server is running, localhost will be used automatically. By using the client/server access mechanism rather than direct access you gain the added flexibility of being able to simultaneously control the board from multiple processes or machines, or to control multiple boards from the same client.

Let's look at our previous example of controlling the LEDs, this time done using the client/server approach:

$ tsctl
tsctl> @localhost DIO
tsctl @localhost DIO> SetAsync GREEN_LED LOW
tsctl @localhost DIO> SetAsync GREEN_LED HIGH

The only difference from the previous usage is that we have added the host name before the class. The tsctl program distinguishes between whether the first argument is a host or a class by case. All classes start with an upper-case letter, so if the first argument starts with an upper-case letter it is assumed to be a class. Therefore, you must specify the host using either a numeric IP address or with a host name that starts with a lower-case letter. Host names are usually specified using lower case anyway but since they are case insensitive all host names can be distinguished from class names by tsctl.

When the tsctl sever has started, it listens on two TCP ports: 5002 and 8000. Port 5002 is intended for use by the tsctl and other clients, and defaults to input encoding Command, input base Binary, output encoding Raw, output base 0. Port 8000 is intended for use by HTML/Javascript clients, and defaults to input encoding HTTP, input base Text, output encoding JSON, output base 10.

Internally, tsctl converts all (available) commands to a binary encoding before executing them. This provides for a uniform consistency in execution time between text and binary mode, as all the overhead of parsing the text command occurs before execution starts. It simplifies server design, as a single interpreter of the binary protocol is sufficient in all cases. Likewise the data returned from executing commands is in binary format, which is then rendered in the current output mode. However, since the reply data does not come back all at once in some cases (depending on the command, loading, network latency and other condition), reply data is collected as much as possible at once and then rendered as output before repeating the process until all reply data has been output. This provides for both responsive output even when certain commands (such as Time delays) produce noticable delays before giving output, while providing for maximal uniformity and performance similar to the request.

The separate internal conversion process also provides for the ability to pre-compile tsctl text commands to binary format ahead of time. This makes possible the ease of writing readable text commands with the greater performance of issuing commands in binary format. To this end, these are several command-line options provided for compiling and using pre-compiled commands:

--compile reads all commands provided and then produces a binary output containing two sections. The first contains the binary format the for requests and the second section containing the look-up table. Support is planned for outputting these sections in a format suitable for reading in subsequent invocations of tsctl, or for putting in your own C, Python, Javascript, etc. program.

--binary skips reading commands and instead reads the output of --compile as its input. It then performs the look-up specified in the look-up table, and then directly interprets the binary commands to produce output.

--skip-lookup is only used in conjunction with --binary, and causes the look-up step of that option to not be performed.

--lookup-only is used only in conjunction with --binary. It only performs only the look-up stage, and then outputs the resulting binary protocol for subsequent use.

--raw-output skips the output rendering. The raw binary reply data from the server is output. The result is the same as if raw binary output mode is explicitly specified in the request for the entire duration of the requests.

--raw-untagged disables output tagging. Implies and automatically enables the --raw-output option, as the normal output stages rely on tagging to render output.

Note: UNIMPLEMENTED