Tsctl

tsctl

Files
Latest tsctl sources

Overview

Tsctl was created as a way to ease software development, allow programs developed for one board to be easily re-used on other boards, and provide a way to control boards from any language and operating system that supports TCP/IP. You can also write your program to talk directly to the hardware via libtsctl. Tsctl has a consistent client API across all access methods. Currently it supports programming in C, Python, shell, Javascript, and Java, as well as any other language in which you can write code to talk to a TCP socket. tsctl is object oriented, and currently defines classes for AIO (Analog I/O, i.e. DAC and ADC), Bus (useful for direct register access), CAN, DIO, EDIO (Extended DIO for PWM, Quadrature counting and more), Pin, Time (timekeeping), TWI, and SPI hardware as well as a System class. Tsctl server runs as a single (user-space) multi-threaded server instance on the board to provide access to board features over TCP/IP.

The older canctl, dioctl, and spictl servers are implemented as libtsctl applications to provide the ability to run those applications on any hardware supported by tsctl.

Support

The following boards are currently supported by tsctl:

TS-Socket CPU
TS-4200
TS-4500
TS-4700
TS-4800
TS-Socket Baseboards
TS-8100
TS-8160
TS-8200
TS-8390
TS-8820
TS-8900
TS Single Board Computers
TS-7552
TS-7553
TS-7558
PC-104 Peripheral Boards
TS-RELAY8
TS-DIO24

Design Philosophy

Technologic System develops and manufactures single-board computers. Newly designed boards have features and configuration intended to meet newly emerging needs in the marketplace, as well as to respond to customer feedback concerning what is useful to them. However, over time many boards developed by Technologic Systems share in common certain features such as Ethernet, serial ports, CAN, and so forth. Some of these features are well supported by the Linux operating system which our boards ship with. However some are not, and in other cases the interface to accessing a particular feature has changed over time, sometimes dramatically.

Technologic System products are targeted towards the embedded market. The software development model in this space is often quite different from the rest of the software industry. Embedded devices typically go through a development cycle which terminates in a "frozen" state for all software on the board. Unlike other parts of the industry, upgrades or change of any kind in the state of the software as shipped is undesirable as it represents a high degrees of risk, risk that assumptions other software relies on will no longer be valid resulting in "breakage" of previously working software. As such, it is important that Technologic System provide software for the features on its board which reaches a frozen state quickly, allowing developers using our products to confidently freeze their own software in a timely manner.

At the same time, there are other important, but sometimes conflicting goals. These are:

1. To bring new products to market quickly.
2. To provide software for all the features on the board.
3. To have a uniform interface to each feature allowing code developed for one board to work on another.

To meet these goals, tsctl does the following:

• defines object classes, which encapsulates a specific piece of TS hardware behind a standard, uniform API across all supported TS products.
• provides easy extensibility to add new objects and new API calls on existing objects without breaking any existing code.
• provides a single, centralized, self-contained, backward compatible binary for each platform containing all TS functionality (which conforms to the tsctl spec)
• utilizes pthreads, which allows for high performance locking of individual resources
• provides a consistent interface across C, text and binary protocols, and various languages facilitates backward compatibility at the command line and protocol level with canctl, dioctl, and spictl
• optimizes individual objects for maximum performance where applicable, i.e. CAN which can transmit and receive close to wire speed at 1Mbps via the high performance canctl protocol.
• provides the new tsctl network protocol which allows all objects to be used through a single port, providing sequentiality and simultaneous access to multiple objects through the same protocol and connection.

Concepts

Objects

Tsctl uses objects to perform most important functionality. These objects are divided into classes which correspond to various resources available on the board: AIO, Bus, CAN, DIORaw, DIO, EDIO, Pin, System, Time, TWI, and SPI. These objects are implement in C using a structure which contains a pointer to the API for the class. To use an object, it is first necessary to call its initialization function to get a pointer to the object. Objects are referenced by initialization by number. Some numbers for a given class are standard across all hardware, while others are specified to a given board.

API Reference

Systems

The system object provides access to control functions implemented by the server itself. For a given architecture, there is a singleton System object for the entire board. The system object provides information about the server, as well as allowing for control functionality.

ClassCount

Typically used for debugging, this function obtain the number of classes defined by the server. The value returned is one greater than the maximum value allowed to be passed as the class parameter in any tsctl protocol request to the server.

API Call

Name	Return Value	Arguments
ClassCount	32-bit integer	Initialized "System" object

System *sys = SystemInit(0);
printf("There are %d classes defined by the system.\n",sys->ClassCount(sys));

This call is also available over the TCP interface on port 5001.

TCP Request Packet Offset Bytes Field Value 0 2 Class 0x0000 2 1 Instance Instance 3 1 Command 0x00

TCP Reply Packet Offset Bytes Field Value 0 2 class 0x0000 2 1 Command 0x00 3 1 Tag 0x13 4 4 ClassCount ClassCount 8 1 tag 0x80

InstanceCount

Typically used for debugging, this function obtains the number of instances of the specified class which are available on the server for clients to make requests for through the tsctl protocol. The value returned is one greater than the maximum value allowed to be passed as the instance parameter in any tsctl protocol request to the specified class; if a value equal or greater is passed, the server will signal an exception by closing the connection to the client.

API Call

Name	Return Value	Arguments
InstanceCount	32-bit integer	Initialized "System" object

This call is also available over the TCP interface on port 5001.

TCP Request Packet Offset Bytes Field Value 0 2 class 0x0000 2 1 instance instance

TCP Reply Packet Offset Bytes Field Value

Template

API Call

Name	Return Value	Arguments
		Initialized "System" object

This call is also available over the TCP interface on port 5001.

TCP Request Packet Offset Bytes Field Value

TCP Reply Packet Offset Bytes Field Value

Advanced

Locking

libtsctl is design to make it possible to share resources. It does this by allowing resources to be locked. A lock can be a shared lock, such as might be appropriate for reading a value, or it can be an exclusive lock, which would be appropriate for changing a value.

All resources that provide an interface to lock and unlock them must be locked before use and unlocked after use. This is because in some cases the locking mechanism, in addition to acquiring shared or exclusive access to the resource, also performs per access initialization. For instance, multi-function pins are automatically set to the correct function during locking.

From the perspective of a client there are object locks, which in the server ultimately result in one or more system locks being held, under control of the object being locked and any sub-objects it contains. All tsctl objects which provide a Lock function offer the client to hold an object lock on that object. Each class defines the circumstances under which the client must hold an object lock. A client should not hold an object lock any longer than necessary.