CMRI library API documentation.

Defined values:

For your convience, the following values have been pre-defined within
the CMRI library:

Error codes:

Error				Value

NO_ERROR			0
UNSPECIFIED_ERROR		1
INVALID_NODE_DESCRIPTOR		10
INVALID_NODE_NUMBER		11
INVALID_NUMBER_OUTPORT		12
INVALID_NUMBER_INPORT		13
ILLEGAL_SIGNAL_VALUE		14
SIGNAL_NUMBER_MISMATCH		15
TOO_MANY_CARDS			16
NOT_ENOUGH_CARDS		17
INVALID_CARD_VALUE		18
INVALID_PORT_NUMBER		19
INVALID_SERIAL_PORT		30
INVALID_BAUD_RATE		31
UNABLE_TO_OPEN_PORT		32
SERIAL_WRITE_ERROR		33
SERIAL_READ_TIMEOUT		34
SERIAL_READ_FRAME_ERROR		35
SERIAL_PORT_NOT_OPEN		36

Baud rates:

Define:		Value	Baud rate
CMRI_B9600	0	9600
CMRI_B19200	1	19200
CMRI_B57600	2	56600
CMRI_B115200	3	115200

Serial port definitions:

For people used to DOS nomenclature:

Define:		Value  Port
CMRI_COM1	0      COM1 (ttyS0)
CMRI_COM2	1      COM2 (ttyS1)
CMRI_COM3	2      COM3 (ttyS2)
CMRI_COM4	3      COM4 (ttyS3)

Serial port definitions for the benefit of Unix users

Define		Value	Port
CMRI_TTYS0	0	ttyS0
CMRI_TTYS1	1	ttyS1
CMRI_TTYS2	2	ttyS2
CMRI_TTYS3	3	ttyS3

Serial port definitions for usb to rs232 converters.
Note, these will only really work if your computer supports usb-rs232
converters through modules such as usbserial.o

Define		Value	   Port
CMRI_USB0	10	   ttyUSB0
CMRI_USB1	11	   ttyUSB1
CMRI_USB2	12	   ttyUSB2



Functions:

int cmri_open_serial_port(int port, int baud)

This function takes the given port and baud information and
initializes the serial port for use by the C/MRI. If this function is
not called first, the other functions will return a
SERIAL_PORT_NOT_OPEN error. The function will return NO_ERROR on
sucess

Valid inputs are:
For port, any serial port define (CMRI_COM1-CMRI_COM4,
CMRI_TTYS0-CMRI_TTYS3 or CMRI_USB0-CMRI_USB2).

For baud rate only CMRI_B9600, CMRI_B19200, CMRI_B57600, CMRI_155200
are alowed. Note your hardware must support the speed used.



int cmri_make_initialize (char cardtype, int nn, unsigned int dl, int
ni, int no, int ns, int *ct)

This function sets up one SMINI or SUSIC/USIC preparing it for use. On
success it returns NO_ERROR. An error value is returned on failure.

Valid inputs are:
For card type (char cardtype), a single ASCII character (N,X,M)
N for USIC cards,
X for SUSIC cards, and
M for SMINI cards.  Any other value returns INVALID_NODE_DESCRIPTOR.

For card node number (int nn), valid values are 0 to 127. Invalid
values return INVALID_NODE_NUMBER.

The delay constant (unsigned int dl) is any valid 16 bit integer
number.

Number of input ports (int ni). Valid values depend on type of card. 
For SMINI cards, this will always be 3.
For SUSIC cards, this will be the number of input cards * 4.
For USIC cards, this will be the number of input cards * 3. 
The routine returns INVALID_NUMBER_INPUT for invalid values.

Number of output ports (int no) again vary by card.
For SMINI cards, this will always be 6.
For SUSIC cards, this will be the number of output cards * 4.
For USIC cards, this will be the number of output cards * 3. 
INVALID_NUMBER_OUTPUT is returned for non valid values.

Number of signals (int ns) is the number of target signals hooked up
to an SMINI or number of card sets of 4 for SUSIC/USIC cards. This value is
checked for validity. Again see the C/MRI User's handbook for more
information on this topic. ILLEGAL_SIGNAL_VALUE is returned on error.

Card conifguration (int *ct) is a pointer to an array of
integers. Contains the configuration of target signals for SMINI cards
or card configuration for SUSIC/USIC cards. The length of the array
should be as long as the number of output cards for SMINI and the
total number of card sets for SUSIC/USIC cards. See the C/MRI User's
handbook for more on configuring signals and cards. 



int cmri_make_transmit(int nn, int no, int *ct)

This routine takes an array of integers and sends it to the selected
node. This is the primary user output routine for the library. The
function will return error messages from the transmit routine if there
is a transmission error or NO_ERROR on success.

Valid inputs are:
Node number (int nn) the integer value of node address.

Number of data elements (int no) then number of elements in the array
of data.

Data (int *ct) pointer to an array of integers containing the data to
be sent.



int cmri_make_poll(int nn)

This routine sends a poll request to the specified node. Note: it does
not collect the data, merely requests the poll. The function will
return the error message from the transmit routines or NO_ERROR on
success.

Valid inputs are:
Node number (int nn) integer value of node address.



int cmri_createsendstring (char *in, int lin, char *out, int *lout)

This routine takes the given string, adds the start, framing and DLE
bytes to it in preparation for transmission. The routine returns
NO_ERROR. The output string is stored at *out and lout contains the
length of the output string. Note, ensure there is enought space set
aside for *out, this routine does not check for this. Generally the
user shouldn't need to use this to create output strings. To
initialize, poll or send data use cmri_make_initialize,
cmri_make_transmit and cmri_make_poll instead.

Valid inputs:
String to be processed is pointed to by char *in.
Length of string to be processed is in int lin.
Output string is pointed to by char *out.
Length of output string is pointed to by int *lout.



int cmri_rxdata(char *s, int *slen, int tout)

This is the main receive data routine. Once the user calles the
cmri_make_poll routine, this routine should be called to receive the
data from the node. The routine performs the post-processing on the
data, removing the sync, framing and DLE characters from the string,
returning only the data. The first byte of the string is the number of
the port that the string was received from. The routine returns
NO_ERROR on success with the processed string in *s and the length in
*slen and the appropriate receive error on failure. Note: ensure that
enough memory is set aside for the receive buffer *s.

Valid inputs:
Received data string pointed to by char *s.
Length of received data pointed to by int *slen.
Receive timeout is in int tout. This value is in milliseconds and
should be long enough to allow the sending node to transmit bytes.


int cmri_txdata(char *s, int slen)

This routine sends the string given to the open serial port. Generally
speaking, this routine will not be used by the end user directly, but
will be used through the cmri_make_* routines. The routine returns
NO_ERROR on success and the appropriate serial transmission error on
failure.

Valid inputs:
String to be sent pointed to by char *s.
Length of string in int slen.



int cmri_printstring (char *s, int slen)

This is a debugging routine and should not be needed by the end
user. It is used to print out the integer value of the string elements
in *s. The routine displays the values to stderr and returns 0.

Valid inputs:
String to be displayed pointed to by char *s.
Length of string in int slen.



int cmri_countsigs(char c)

This routine counts the number of two lead signals in a given
byte. This is an error checking routine used by cmri_make_initialize
and should not be used by the end user directly. It returns the number
of signals.


int cmri_countports(char c)

This routine counts the number of ports in the byte given. This is an
error checking routine used by cmri_make_initialize and should not be
used by the end user directly. It returns the number of ports.



int cmri_getbyte(char *c, int tout)

This routine reads a byte from the serial port. The end user shouldn't
use this routine, use cmri_rxdata instead. The routine returns
NO_ERROR on success, relevant serial error message on failure.

Valid input:
Pointer to received character char *c.
Timeout value in milliseconds in tout.



void cmri_sighandler(int sig)

This routine is used by the receive byte routines to trap a timeout
situation. The end user should not access this routine.

Valid inputs:
The signal trapped will be in int sig.





int cmri_filltime(struct itimerval *timevalue, int val_sec, int
val_usec, int int_sec, int int_usec)

This routine is used by the receive byte routines to set the timeout
value. The end user should not access this routine.

Valid inputs:
The structure to fill pointed to by *timevalue.
The various times in val_* and int_*.