Note: the authoritative source of informations are the headers (*.h) and the example program (test_libticables.c). You can eventually look at the TiLP or GtkTiEmu program.
This documentation describes the libticables library v3.x.x. The v3.x.x version is backwards compatible with the v2.x.x but it is recommended to use the new version which brings about new features and enhancements.
The source code of the v2.x.x has been cleaned up and the v3.x.x includes a better USB support, both under Linux & Windows. Also, lib is now easier to use and configure now.
What in this manual ?
This documentation is for who want
use the library under Linux or Windows.
The documentation is divided into
six chapters:
Chapter 1: Introduction discusses adding the library to your system and provides an overview of handled link cables and available functions.
Chapter 2: Data types tells about the different definition of types which are provided to the user.
Chapter 3: Setting up link cables guides you through the steps to set up link cables on your computer.
Chapter 4: General functions details the software functions that are not specific to link cable.
Chapter 5: Link cable functions details functions that are specific to link cable.
Chapter 6: Appendices include installation
instructions for the libticables library and procedures to add the lib
to your system. In addition the Appendix D explains the procedure for compiling
programs which use this library. For your convenience separate Appendices
cover "Flags for use", a "Code Index" and a list of "Error messages".
I Introduction
Chapter 1 provides an overview of the libticables library. The topics covered are:
functions,
conventions used in this manual.
The library contains routines to handle the different
link cables designed for the TI calculators under different platforms.
It can also manage virtual linking. The library is easy to use: you simply
tells to lib which link cable you want to use on which port and the library
make the work ! It has an I/O management system which determines the best
method to use and some auto-probing routines for detecting Operating System,
I/O ports and link cable type.
The library is independant of the OS and completely
transparent.
The supported platform are: Linux, Windows9x/Me,
WindowsNT4/2000/XP and Mac OS-X. Under Windows NT4/2000/XP, the library
may require a device driver: PortTalk
(DriverLYNX DLPortIO driver is no longer used). This driver is provided
with TiLP so you don't have to worry about it.
If you use a USB link cable, a driver is also required (http://lpg.ticalc.org/prj_usb).
Supported architectures are: x86 (Intel/AMD) processors,
Alpha, Sparc, some kinds of PDA (such as iPAQ).
The supported link cables are:
- the home-made parallel (alias 5$-cable),
- the home-made serial (alias 4$-cable),
- the Black TIGraphLink,
- the Grey/Gray TIGraphLink cable,
- the AVRlink cable (this is the link cable I
have designed: Grey TIGL compatible, 4 times faster),
- experimental support of the TPUlink (Ti/Pc USB
link cable),
- full support of the SilverLink cable (TIGraphLink
USB): a device driver is required.
At last, there is a full support for the TI device kernel module (Linux only).
The library provides also two virtual link cables
for connecting an emulator to a linking software:
- 'Vti' virtual link for communicating with VirtualTI,
a TI emulator,
- 'GtkTiEmu' virtual link: a generic virtual link,
used by GtkTiEmu, another TI emulator.
Remark: it may be necessary to be the super-user ('root') under Linux for using some link cables (serial/parallel/BlackLink). If you do not want this or can do it (due to GTK >1.2.9 for instance), you must use a kernel module (such as 'tipar'/'tiser').
Functions
The libticables is a set of 'C' languages subroutines (but useable with C and C++ languages) designed to handle the different link cables through a same set of functions. This constitute a complete API.
The libticables library (Linux version) was written and tested using gcc under Linux. It was ported under Windows and tested using the Microsoft Visual C++ version 5.0. It seems that others compilers such as Borland C++ 4.0 or DJGPP do not work because they do not support long filenames ! It was also ported under Mac OS-X.
Thomas Wolf <two@chello.at> has written a wrapper for the libticables and the source code is BCC5.x compliant. This wrapper is unsupported. Please mail Thomas Wolf for any questions about BorlandC.
There are also some Delphi projects but they are not maintain any longer.
The functions are supplied both in source form and linked as a DLL. The source code is released under the GPL licence and the libraries under the LGPL license.
Each function is presented with its formal definition, including data types of all input and output variables. A brief description of the purpose of the function is provided along with the legal values for inputs where applicable. All structures and flags used by the libticables library are in Appendix G: "Flags for use".
Functions are written as "C" functions, i.e. they return values except few of them. A non zero value signifies an error.
Conventions used
To help differentiate between different kinds of information, the following text styles are used in the Reference Manual.
Functions look like this (charter font).
Variables look like this (courier font).
Parameter look like this (helmet font).
File names look like this (timmons font,
bold).
FLAGS look like this (timmons font).
II Data types
Chapter 2 details the different data types provided to the user. These types are defined in the cable_defs.h file or in typedefs.h for the basic types.
Basic types:
- byte: a 8-bit unsigned integer,
- word: a 16-bit unsigned integer,
- longword: a 32-bit unsigned integer.
The most important type is a structure and is defined as below:
struct ticable_link
{ // cooked access
int (*init) ();
int (*open) ();
int (*put) (byte data);
int (*get) (byte *data);
int (*probe) ();
int (*close) ();
int (*exit) ();
int (*check) (int *status);
// raw access
int (*set_red_wire) ();
int (*set_white_wire) ();
This structure contains a set of functions. These functions are used to handle a link cable. You will find more explanations on these functions further in the documentation.
The other data type is not used by the libticables but is provided for your convenience.
struct ticable_param
{
int calc_type;
int link_type;
unsigned int io_addr;
char device[16];
int timeout;
int delay;
int baud_rate;
int hfc;
int port;
int method;
};
typedef struct ticable_param TicableLinkParam;
It contains all variables required for setting up a link cable.
At last, the third structure is used by the library for auto-detection operations:
struct port_info_
{
int lpt_count;
int lpt_addr[MAX_LPT_PORTS+1];
int lpt_mode[MAX_LPT_PORTS+1];
char lpt_name[MAX_LPT_PORTS+1][17];
int com_count;
int com_addr[MAX_COM_PORTS+1];
int com_mode[MAX_COM_PORTS+1];
char com_name[MAX_COM_PORTS+1][17];
};
typedef struct port_info_ TicablePortInfo;
III Setting up link cables
Chapter 2 guides you through the steps to set up a link cable on your computer. Detailed operating instructions for the functions are described in Chapter 3.
To set up the libticables library:
1. call the ticable_init function,
2. call the ticable_get_default_param function,
3. fill the timeout and delay variables,
4. fill the port and method variables,
5. eventually set up the device and io_addr variables
if you want override automatic settings,
6. set up the parameters with ticable_set_param
or ticable_set_param2
7. finally, set up the link cable with ticable_set_cable.
The I/O ports
To use some functions, you should know some informations
about the I/O ports. This is not mandatory since the libticables automatically
manages I/O ports.
A parallel link cable use the printer ports based
on 0x3BC, 0x378 or 0x278.
A serial link cable or Black/Grey TIGraphLink
or fastAVRlink cable use the serial ports based on 0x3F8, 0x2F8, 0x3E8,
0x2E8.
These addresses are standard addresses but the
library automatically uses the right one. You can also pass any addresses.
So, you can use your cable with a strange serial board... On the other
hand, you should pay attention whether the address is valid or not.
Global setup function
To implement the global setup functions call:
1. get_cable_version to check the library version
number.
2. call ticable_get_default_param. This will fill
you structure with some default values.
3. fill up your LinkParam structure with the values
you want.
4. use ticable_set_param
5. use ticable_set_cable to set the link_cable
structure according to your cable type.
NOTE: under Windows NT4/2000/XP, the use of the
PortTalk driver is required but this driver is not compulsory under Windows9x/Me.
Anyways the library will list at startup the I/O ressources it can use
and auto-detect if this driver is present. If yes, it will use it else
it will use its own I/O routines. If the driver is not present and if you
are under Windows NT4/2000/XP, you will get an error message in order to
avoid an access violation.
The same mechanism appears with the USB link cable.
Setting up a link cable
To set a link cable, you must follow this sequence:
1. init: this function must be called prior to
any others (usually when the program starts).
2. open: this function must be called before a
transfer if you have not called yet or if you have closed the port with
close.
3. close: this function must be called once you
have finished a transfer.
4. exit: this function must be called whenever
you exits of your program or if you want change of link cable.
IV General functions
Chapter 3 details the software functions that are
not specific to a link cable.
The flags included in each functions are defined
in Appendix ?.
The functions listed below are described in this chapter:
- general functions:
ticable_init
ticable_exit
ticable_get_version
ticable_get_error
ticable_set_param/ticable_set_param2
ticable_get_param
ticable_get_default_param
ticable_set_cable
ticable_get_support
- set/get functions:
ticable_set_timeout
ticable_get_timeout
ticable_set_delay
ticable_get_delay
ticable_set_baudrate
ticable_get_baudrate
ticable_set_hfc
ticable_get_hfc
ticable_set_io_address
ticable_get_io_address
ticable_set_io_device
ticable_get_io_device
ticable_set_port
ticable_get_port
ticable_set_method
ticable_get_method
- probing funtions:
ticable_detect_os
ticable_detect_port
ticable_detect_cable
ticable_detect_all
- display funtions:
DISPLAY
DISPLAY_ERROR
ticable_DISPLAY_settings
Please not that any changes made with the set/get functions will be taken into account to the next ticable_set_cable call.
ticable_get_version
Description: This functions returns the version number of the library as a string. This string as the following format: "major.minor.release" such as "1.0.5".
Syntax: const char *ticable_get_version()
Input parameters: none.
Output Parameters: none.
Return values:
const char pointer, to a string.
ticable_get_error
Description: returns the string corresponding to the error code returned by a link cable function. This function propagate the error code that is to say it returns the passed error code if it can not find the corresponding error message else it returns 0. This mechanism of propagation is useful for the libTIcalc library for instance.
Syntax: int ticable_get_error(int err_num, char *error_msg)
Input parameters: err_num, an error code returned by a link cable function.
Output Parameters: error_msg, a string which contains the corresponding error message.
Return values: int, 0 if the error code has been caught else the error code.
ticable_get_default_param
Description: This functions fills the passed structure with default values.
Syntax: int ticable_get_default_param(TicableLinkParam *lp)
Input parameters: lp, the address of the structure to fill.
Output Parameters: lp, the filled structure.
Return values: int, an error code.
ticable_set_param
Description: This functions set the internal library parameters with your settings.
Syntax: void ticable_set_param(const TicableLinkParam *lp)
Input parameters: lp, a structure to fill up.
Output Parameters: none.
Return values: none.
ticable_set_param2
Description: This functions set the internal library parameters with your settings.
Syntax: void ticable_set_param(TicableLinkParam lp)
Input parameters: lp, a structure to fill up.
Output Parameters: none.
Return values: none.
ticable_get_param
Description: This functions retrieve the internal library settings.
Syntax: int ticable_get_param(TicableLinkParam *lp)
Input parameters: lp, the address of the structure to fill.
Output Parameters: lp, the filled structure.
Return values: int, an error code.
ticable_set_cable
Description: this functions takes as first parameter the link cable type and returns via the second parameter a structure of functions which contains the functions for the suitable link cable.
Syntax: void ticable_set_cable(int type, TicableLinkCable *lc)
Input parameters: type, one of the following flags: LINK_PAR, LINK_SER, LINK_TGL, LINK_AVR, LINK_VTI, LINK_TIE, LINK_TPU which can be combined (| OR) with LINK_DEV for using the 'tidev' kernel module.
Output Parameters: lc, a pointer on a structure which contains the twelve functions used for manipulating transfers on the link cables and one for probing the link cable type.
Return values: int, an error code. This functions returns an error if the library can not determine or find an I/O method to use.
ticable_set_timeout
Description: This functions set up the timeout value which is used by all link cable functions for exiting when the timeout delay is elapsed.
Syntax: int ticable_set_timeout(int timeout_v)
Input parameters: timeout_v, the timeout value in tenth of seconds. Example: 20 represents 2 seconds.
Output Parameters: none.
Return values: none.
ticable_get_timeout
Description: This functions returns the timeout value which is used by all link cable functions for breaking when the timeout delay is elapsed.
Syntax: int ticable_get_timeout()
Input parameters: none.
Output Parameters: none.
Return values: int, the timeout value in tenth of seconds.
ticable_set_delay
Description: This functions set up the delay value which is used by home-made link cable functions for defining the inter-bit delay. The lower, the faster but less stable.
Syntax: int ticable_set_delay(int delay_v)
Input parameters: delay_v, the delay value in micro-seconds.
Output Parameters: none.
Return values: none.
ticable_get_delay
Description: This functions returns the delay value which is used by home-made link cable functions for defining the inter-bit delay.
Syntax: int ticable_get_timeout()
Input parameters: none.
Output Parameters: none.
Return values: int, the delay value in micro-seconds.
ticable_set_baudrate
Description: This functions set up the baud-rate value which is used by fastAVRlink cable functions for defining the transfer rate. The value must be the same as than one defined by the 'fastAVRlink Setup Utility' else the link cable will not work (different baud-rates).
Syntax: void ticable_set_baudrate(int br);
Input parameters: br, the baud-rate value which can be one of the following flags: BR9600, BR19200, BR38400 or BR57600.
Output Parameters: none.
Return values: none.
ticable_get_baudrate
Description: This functions returns the baud-rate value which is used by fastAVRlink link cable functions for defining the transfer rate.
Syntax: int ticable_get_baudrate()
Input parameters: none.
Output Parameters: none.
Return values: int, the baud-rate value such as BR9600 for 9600 bauds.
ticable_set_io_address
Description: This functions set up the I/O port base address which is used by the link cable functions. The value must be a valid value. Moreover, for Linux user, this address must be an authorized address (see the tilp.access file which defines I/O permissions).
Syntax: void ticable_set_io_address(uint io_addr);
Input parameters: io_addr, an unsigned int number which contains the base address of the I/O port to access.
Output Parameters: none.
Return values: none.
ticable_get_io_address
Description: This functions returns the I/O port base address.
Syntax: uint ticable_get_io_address()
Input parameters: none.
Output Parameters: none.
Return values: int, the baud-rate value such as BR9600 for 9600 bauds.
ticable_set_io_device
Description: This functions set up the character device (Linux only) to use by the link cable functions. The value must be an existing character device else the libticables functions will return an error.
Syntax: void ticable_set_io_device(char * device);
Input parameters: device, a string which contains a character device name such as "/dev/ttyS0".
Output Parameters: none.
Return values: none.
ticable_get_io_device
Description: This functions returns the character device name which is used by link cable functions.
Syntax: char *ticable_get_io_device()
Input parameters: none.
Output Parameters: none.
Return values: char *, the character device name.
ticable_set_hfc
Description: This functions enables or disables the hardware flow control (CTS/RTS). This is used only for the (fast)AVRlink cable.
Syntax: void ticable_set_hfc(int action)
Input parameters: action, 0 for disabling the flow control.
Output Parameters: none.
Return values: none.
ticable_get_hfc
Description: This functions returns the hardware flow control status.
Syntax: int ticable_get_hfc(void)
Input parameters: none.
Output Parameters: none.
Return values: int, an error code.
ticable_set_port
Description: This functions set up a port to use.
Syntax: int ticable_set_port(int port)
Input parameters: port, the port to use.
Output Parameters: none.
Return values: none.
ticable_get_port
Description: This functions returns the port which is currently used.
Syntax: int ticable_get_port(void)
Input parameters: none.
Output Parameters: none.
Return values: int, the port.
ticable_set_method
Description: This functions set up the method to use for performing I/O operations.
Syntax: int ticable_set_method(int method)
Input parameters: method, usually, simply pass IOM_AUTO. The library will automatically use the best appropriate method.
Output Parameters: none.
Return values: none.
ticable_get_method
Description: This functions returns the I/O method used by library.
Syntax: int ticable_get_method()
Input parameters: none.
Output Parameters: none.
Return values: int, the method used.
ticable_detect_os
Description: tries to detect the running Operating System.
Syntax: int ticable_detect_os(char **os_type)
Input parameters: none.
Output Parameters: os_type, the address of a pointer for storing the resulting string into. String can be 'Windows9x' for 9x/Me, 'WindowsNT'' for NT4/2000, 'Linux' for any Linux machine or 'unknown'.
Return values: int, an error code.
ticable_detect_port
Description: the function lists in a structure all available ports on the machine.
Syntax: int ticable_detect_port(PortInfo *pi)
Input parameters: none.
Output Parameters: pi, the address of a structure where the function will store the results.
Return values: int, an error code.
ticable_detect_cable
Description: try to detect one or more link cables connected on the listed ports (the ticable_detect_port function must have been called before). Beware, this function can hang up the mouse if you have a serial mouse...
Syntax: int ticable_detect_cable(PortInfo *pi)
Input parameters: pi, a structure previously filled up with the ticable_detect_port function.
Output Parameters: pi, a PortInfo structure which contains both available ports and cables.
Return values: int, an error code.
V Link cables functions
Chapter 4 details the software functions that are specific to link cable.
The functions listed below are described in this
chapter:
- cooked access:
init
open
put
get
probe
close
term
check
- raw access:
set_red_wire
set_white_wire
get_red_wire
get_white_wire
Most of the functions described above returns an
error code which can have different origins. In fact, the first set of
functions always returns an error code whereas the second set does not
return any error code.
The error could be a timeout error, a byte error
on the device, an error during the opening of a device or for obtaining
some I/O permissions. You can get the corresponding error message with
the get_cable_error function.
init
Description: this functions must be called prior to any of the following functions for initializing some internal variables and configuring ports or devices.
Syntax: int init_port(void)
Input parameters: none.
Output Parameters: none.
Return values: an error code which can be turned into a string with the get_cable_error function.
open
Description: this functions must be called prior to any transfers for initializing some things and flushing some buffers.
Syntax: int open_port(void)
Input parameters: none.
Output Parameters: none.
Return values: an error code which can be turned into a string with the get_cable_error function.
put
Description: this functions send a byte (unsigned char) to the link cable.
Syntax: int put(byte data)
Input parameters: data, the byte to transmit on the link cable.
Output Parameters: none.
Return values: an error code which can be turned into a string with the get_cable_error function.
get
Description: this functions waits a byte (unsigned char) from the link cable.
Syntax: int get(byte *data)
Input parameters: none.
Output Parameters: data, the byte received from the link cable.
Return values: an error code which can be turned into a string with the get_cable_error function.
close
Description: this functions closes the transmission.You should call it whenever a transfer is finished.
Syntax: int close_port(void)
Input parameters: none.
Output Parameters: none.
Return values: an error code which can be turned into a string with the get_cable_error function.
term
Description: this functions closes the port and frees some ressources or devices. It must be called if you quit your program or if you have changed the link cable type before using init_port.
Syntax: int term_port(void)
Input parameters: none.
Output Parameters: none.
Return values: an error code which can be turned into a string with the get_cable_error function.
probe
Description: not useable for the moment.
Syntax: int probe_port(void)
Input parameters: none.
Output Parameters: none.
Return values: an error code which can be turned into a string with the get_cable_error function.
check
Description: this functions can be called to check the status of the link cable: check if a byte has been received and so on. This function is useful to check the receiving buffer without calling the 'get' function which is a blocking function.
Syntax: int check_port(int *status)
Input parameters: none.
Output Parameters: status, the status of the link cable. For the moment, this value can take only 3 values which are STATUS_NONE, STATUS_RX when a byte has been received or STATUS_TX if a byte can be sent.
Return values: an error code which can be turned into a string with the get_cable_error function.
set_red_wire
Description: this functions simply sets the 'red' wire to the desired value.
Syntax: int set_red_wire(int b)
Input parameters: b, the value of line that is to say 0 or 1.
Output Parameters: none.
Return values: int, always 0.
set_white_wire
Description: this functions simply sets the 'white' wire to the desired value.
Syntax: int set_white_wire(int b)
Input parameters: b, the value of line that is to say 0 or 1.
Output Parameters: none.
Return values: int, always 0.
get_red_wire
Description: this functions returns the logical value of the 'red' wire.
Syntax: int get_red_wire(void)
Input parameters: none.
Output Parameters: none.
Return values: int, the value of the wire.
get_white_wire
Description: this functions returns the logical value of the 'white' wire.
Syntax: int get_white_wire(void)
Input parameters: none.
Output Parameters: none.
Return values:
int, the value of the wire.
VI Appendices
Appendix A: installation instructions.
Appendix B: compiling programs under Linux and/or
Windows.
Appendix C: flags for use.
Appendix D: software tools library
Appendix E: Code Index.
Appendix F: Error Messages.
Appendix G: Function Index.
Appendix A: installation instructions
This appendix explains the procedure for adding/using libticables library on your system.
At first, install any required device driver:
- Windows NT4/2000/XP: PortTalk or TiglUsb,
- Linux: LibUsb or TiglUsb.
Linux
procedure: retrieve a tarball of the library source code, make a 'tar
xvzf libticables.tar.gz', go into the libticables directory. Type 'configure'
to check your system and create the Makefile. Next, type 'make' to compile
the library and at last, type 'make install' to install it.
By default, the shared object 'libticables.so'
is placed in the '/usr/lib' directory and necessary links are created.
The headers files are placed in the '/usr/include/ti'
directory. For including them, you just have to place a #include <tilp/cabl_int.h>
on the beginning of your program.
Windows procedure: retrieve a ZIP archive of the library source code and uncompress it in the default folder. Next, place the .DLL file in the same directory than your program (local folder) or place it either in the C:\Windows\System32 directory either in the C:\WinNT\System32 directory according to your OS type.
Appendix B: compiling programs under Linux and/or Windows
Linux procedure: I provide the source of the library. Its installation as described above provides the shared object and necessary headers files. You just have to include the right headers files and compile your program during the linking/last stage with the -lti_cable option on the gcc command line.
Windows procedure: I provide a DLL for use
with all versions of Windows and for the Microsoft compiler only. If you
want use it with a Borland compiler, you have to recompile the library
since the calling conventions are not the same (standard call calling convention
("stdcall") for Borland, C calling convention ("cdecl") for Microsoft).
You can also use cygwin or mygwin (GCC ported under Win32). It should work
also with the Linux makefiles. But, you will need the cygwin environment
with Automake/Autoconf and maybe some other stuffs...
To compile Windows program, to link together with
the appropriate DLL, perform the following steps:
1. a .lib file is provided. Include the .lib file
as part of your project.
2. include the "cable_interface.h" header files
at the top of your test program. This header file include three files.
The first, "typedefs.h" contains some type definitions. The second, "cable_defs.h"
contains...
Appendix C: flags for use
Flags are grouped according to the function in which they are used. Some flags are used in more than one function, and they are duplicated in each section for clarity. Most flags are input parameters to the functions they are listed under.
NOTE: Always use flags where provided, rather than the value associated with it, since values may change. For example, use LINK_TGL with set_cable rather than 1.
ticable_set_timeout
| DFLT_TIMEOUT |
|
Default timeout value |
ticable_set_delay
| DFLT_DELAY |
|
default delay value |
ticable_set_baudrate
| BR9600 |
|
9600 bauds |
| BR19200 |
|
19200 bauds |
| BR38400 |
|
38400 bauds |
| BR57600 |
|
75600 bauds |
ticable_set_cable
| LINK_TGL |
|
Grey TIGraphLink, PIClink or AVRlink |
| LINK_SER |
|
Black TIGraphLink or home-made serial link cable |
| LINK_PAR |
|
Home-made parallel link cable |
| LINK_AVR |
|
FastAVRlink link cable |
| LINK_VTL |
|
Virtual linking |
| LINK_TIE |
|
TIEmulator virtual linking |
| LINK_VTI |
|
Vti virtual linking |
| LINK_TPU |
|
TI/PC USB link |
| LINK_UGL |
|
TIGraphLink USB |
ticable_set_port
| PARALLEL_PORT_1 | 0x378 | Parallel port #1 |
| PARALLEL_PORT_2 | 0x278 | Parallel port #2 |
| PARALLEL_PORT_3 | 0x3BC | Parallel port #3 |
| SERIAL_PORT_1 | 0x3F8 | Serial port #1 |
| SERIAL_PORT_2 | 0x2F8 | Serial port #2 |
| SERIAL_PORT_3 | 0x3E8 | Serial port #3 |
| SERIAL_PORT_4 | 0x2E8 | Serial port #4 |
| VIRTUAL_PORT_1 |
1
|
Virtual linking #1 (emulator) |
| VIRTUAL_PORT_2 |
2
|
Virtual linking #2 (linking program) |
| USB_PORT_1 | SilverLink (first) | |
| USB_PORT_2 | SilverLink (second) | |
| USB_PORT_3 | ||
| USB_PORT_4 | ||
| USER_PORT | I/O address and/or device name are overriden/passed |
check_port
| STATUS_NONE |
|
Nothing |
| STATUS_RX |
|
At least 1 byte has been received |
| STATUS_TX |
|
1 byte can be sent (no more) |
Appendix D: software tools library
| Filename | Ext | Description |
|---|---|---|
| par_link | C/H | Manage the home-made parallel link cable |
| ser_link | C/H | Manage the home-made serial link cable |
| tig_link | C/H | Manage the Grey/Gray TI GraphLink cable |
| avr_link | C/H | Manage the fastAVRlink |
| vtl_link | C/H | Manage the 2 virtual link cables |
| probe_cable | C/H | Try to auto-detect the I/O ports and the link cable type |
| ioports | C/H | Win32 only. Used for switching between internal I/O routines or kernel driver I/O routines |
| interface | C | The interface of the library |
| error | C/H | Manage the error codes and error messages |
| errorcodes | H | The list of error codes and error messages |
| cable_defs | H | Structure and macro definitions |
| cable_interface | H | The header which contains the prototype of exported functions |
| extern | H | Thhis header contains extern variables but for internal use |
| win_port | H | Used for making the Windows DLL |
| Typedefs | H | Some importants definitions of type such 'byte', 'word' |
| Macros | H | Some useful macros |
Appendix E: Code Index
The libticables is a set of 'C' language subroutines designed to handle the different link cable types though a unique set of functions. Below is an alphabetical listing of all libticables functions and the name of the C file which contains its programming code.
The functions below are exported functions:
| Driver function | Code filename |
|---|---|
| get_cable_version | interface.c |
| set_timeout | interface.c |
| get_timeout | interface.c |
| set_delay | interface.c |
| get_delay | interface.c |
| set_baudrate | interface.c |
| get_baudrate | interface.c |
| set_io_address | interface.c |
| get_io_address | interface.c |
| set_io_device | interface.c |
| get_io_device | interface.c |
| set_cable | Interface.c |
| get_cable_error | Error.c |
The functions below are internal functions:
| Driver function | Code filename |
|---|---|
| par_init_port, par_open_port, par_put, par_get, par_probe, par_close_port, par_term_port, par_check_port | Par_link.c |
| ser_init_port, ser_open_port, ser_put, ser_get, ser_probe_port, ser_close_port, ser_term_port, ser_check_port | Ser_link.c |
| tig_init_port, tig_open_port, tig_put, tig_get, tig_probe_port, tig_close_port, tig_term_port, tig_check_port | Tig_link.c |
| avr_init_port, avr_open_port, avr_put, avr_get, avr_probe_port, avr_close_port, avr_term_port, avr_check_port | Avr_link.c |
| vtl_init_port, vtl_open_port, vtl_put, vtl_get, vtl_probe_port, vtl_close_port, vtl_term_port, vtl_check_port | Vtl_link.c |
| vti_init_port, vti_open_port, vti_put,
vti_get, vti_probe_port, vti_close_port,
vti_term_port, vti_check_port |
Vti_link.c |
| tie_init_port, tie_open_port, tie_put,
tie_get, tie_probe_port, tie_close_port,
tie_term_port, tie_check_port |
Tie_link.c |
| tpu_init_port, tpu_open_port, tpu_put, tpu_get, tpu_probe_port, tpu_close_port, tpu_term_port, tpu_check_port | Tpu_link.c |
| ugl_init_port, ugl_open_port, ugl_put,
ugl_get, ugl_probe_port, ugl_close_port,
ugl_term_port, ugl_check_port |
Ugl_link.c |
| detect_port | probe_cable.c |
| detect_cable |
Appendix F: Error Messages
All routines in the libticables are written as 'C' functions i.e., thery return values. A non zero value signifies an error. Full error messages may be printed using the get_cable_error function. Below is a list of all error messages, the value of each, and an explanation of the error.
L = Linux
W = Windows9x or Windows NT4
M = Mac OS-X
| Error code | Value |
|
Explanation |
|---|---|---|---|
| ERR_ABORT |
-1
|
|
Operation aborted |
| ERR_ROOT |
1
|
|
Root permissions required |
| ERR_SND_BIT_TIMEOUT |
2
|
|
Send bit timeout |
| ERR_RCV_BIT_TIMEOUT |
3
|
|
Receive bit timeout |
| ERR_OPEN_SER_DEVICE |
32
|
|
Unable to open a serial device (/dev/ttySx) |
| ERR_SND_BYT |
33
|
|
Send byte error |
| ERR_RCV_BYT |
34
|
|
Receive byte error |
| ERR_SND_BYT_TIMEOUT |
36
|
|
Send byte timeout |
| ERR_RCV_BYT_TIMEOUT |
35
|
|
Receive byte timeout |
| ERR_CREATE_FILE |
41
|
|
Unable to open a COM port (COMx) |
| ERR_OPEN_COM_PORT |
42
|
|
Unable to open a COM port (COMx) |
| ERR_READ_FILE |
47
|
|
Error while reading the COM port |
| ERR_OPEN_TIDEV_DEV |
48
|
|
Error while opening a 'tidev' char device |
| ERR_VT0_ALREADY_USED |
49
|
|
Error when the pipe is already used |
| ERR_VT1_ALREADY_USED |
50
|
|
Error when the pipe is already used |
| ERR_OPEN_PIPE |
51
|
|
Unable to open a pipe |
| ERR_PIPE_FCNTL |
52
|
|
Unable to modify the pipe characteristics |
| ERR_OPP_NOT_AVAIL |
53
|
|
No answer |
| ERR_CLOSE_PIPE |
54
|
Unable to close a pipe | |
| ERR_BYTE_LOST |
55
|
|
A byte might have been lost due to check_port |
| ERR_ILLEGAL_OP |
56
|
|
An illegal argument has been used |
Appendix G: Function Index
To do...
---------------------
I hope this documentation to be useful. If you
have comments, suggestions, and so on, feel free to mail me.
If you want additional informations, fire me an
e-mail...
libticables, (c) 1999-2002, Romain Liévin
All code is placed under GPL license and libraries
under the LGPL license.
Lib version 3.1.6.
Doc version 2.0, 17/02/2002.
This doc has been written with StarOffice 5.2
Personnal Edition for Linux (StarOffice = 50 MB of RAM !!!). SGML could
be a better choice but I have not enough time to learn it ...