Help - Generic Clients

Overview

"Generic clients" are external add-on modules which can be used to implement additional functionality. The main purpose for having generic clients is to make it easier to write serial (RS-232) client interfaces. However, generic clients can also be used for Ethernet communications, file or database access, or any other application where it is desired to add custom functionality.

Generic clients are experimental at this stage, and the interface is subject to change. If you intend to make use of this feature at this stage in its development, be prepared to make minor modifications to your custom generic clients in future versions.

Generic Client Server Interface

Generic clients associate with the main system by communicating with it via the "generic client" server interface. This uses a remote procedure call mechanism called "Perspective Broker" which is part of the Twisted communications framework.

A generic client runs as a seperate program that communicates with the main system through the generic server interface. The generic server interface must be configured and running before any generic clients may work with the main system.

Generic Client Names

Each instance of a generic client must be given a unique name. That means that even when running two or more copies of the same type of client, each copy must have its own name. The name of the client does not necessarily mean the name of the file containing the client. Two or more clients may use the same code from the same file, but be given different names. The name is simply a parameter passed to the client which it uses to identify itself to the server when it starts up.

For example, the system may need to interface with two identical weigh scales. The same client program file can be used for both, but they must be given different names when they are started so the correct parameters can be passed to them.

Generic Client Parameters

The parameters for each generic client instance are defined in the client communications configuration file ("mbclient.config") just like all other client configurations. These parameters follow a similar format to those used with TCP clients. In addition, each client can have custom parameters which are not "understood" by the server, but are simply passed on to the client for its own use. This allows the standard configuration system to load and parse the parameters while allowing each type of client to have whatever parameters are appropriate to the application.

Details of the configuration parameters can be found in the section on communications configuration.

Generic Client Start and Stop Sequence

When the system starts up, it reads and parses the communications configuration file
If any generic clients are found, it attempts to start them.
Each generic client contacts the generic client interface server and requests its parameter set by name.
The generic server interface server sends the parameter set to the client.
The client validates its parameters, and sends any error messages back to the server.
The generic client runs on a regular scan cycle, performing its own tasks and exchanging data and status information with the server.
When the main system wishes to shut down, it sends a "stop" command to each generic client, requesting that they stop executing and exit.
The system then waits for a fixed time. When this time delay has passed, the system will forcibly terminate any generic clients which may still be running.
The system then completes its own shutdown and exits.

File Locations

Generic clients are located in a directory called "genclient". The system will automatically look in that directory for any specified files.

Protocols and Message Transports

Generic clients are primarily intended to allow the addition of protocols and custom interfaces. These typically include serial protocols, but can also include protocols that use HTTP and low level socket access. Since the generic client runs independently from the main system, it will not block or interrupt the operation of the main system. However, the client should not block (stop) execution of the main client loop for long periods of time as the main system may interpret that behaviour as indicating the client has faulted ("locked-up").

Some available libraries for implementing client protcols are:

socket - This is a standard Python library that offers direct TCP, UDP, and unix socket access.
urllib2 - This is a standard Python library that offers simple HTTP protocol access.
pyserial - This is a third party library that offers access to the serial port.

Help Topics

Topic Details for Communications