NDI Serial Methods

Functions
NDIFileHandle	ndiSerialOpen (const char *device)
void	ndiSerialClose (NDIFileHandle serial_port)
int	ndiSerialCheckDSR (NDIFileHandle serial_port)
int	ndiSerialBreak (NDIFileHandle serial_port)
int	ndiSerialFlush (NDIFileHandle serial_port, int flushtype)
int	ndiSerialComm (NDIFileHandle serial_port, int baud, const char *mode, int handshake)
int	ndiSerialTimeout (NDIFileHandle serial_port, int milliseconds)
int	ndiSerialWrite (NDIFileHandle serial_port, const char *text, int n)
int	ndiSerialRead (NDIFileHandle serial_port, char *reply, int n)
int	ndiSerialSleep (NDIFileHandle serial_port, int milliseconds)

Detailed Description

These are low-level methods that provide a platform-independent interface to the serial port.

Function Documentation

int ndiSerialBreak

(

NDIFileHandle

serial_port

)

Send a 300ms break to the serial port to reset the NDICAPI. After you call this function, you must also call ndiSerialComm(file, 9600, "8N1", 0) to reset the serial port back to the default NDICAPI communication parameters. The NDICAPI will beep and send the text "RESETBE6F\r", which must be read with ndiSerialRead().

The return value of this function will be if the call was successful. A negative return value means that an IO error occurred.

int ndiSerialCheckDSR

(

NDIFileHandle

serial_port

)

Check whether the DSR signel is set. If the return value is zero, then the DSR is not set which means that either the device has been unplugged from the serial port or has been turned off.

void ndiSerialClose

(

NDIFileHandle

serial_port

)

Close the serial port. It is wise to send a "COMM 00000\r" command to the NDICAPI before you close the port, otherwise the next time the serial port is opened you will have to reset the NDICAPI before you can resume communication with it.

int ndiSerialComm	(	NDIFileHandle	serial_port,
		int	baud,
		const char *	mode,
		int	handshake
	)

Change the baud rate and other comm parameters.

The baud rate should be one of 9600, 14400, 19200, 38400, 57600, 115200.

The mode string should be one of "8N1", "7O2" etc. The first character is the number of data bits (7 or 8), the second character is the parity (N, O or E for none, odd or even), and the the third character is the number of stop bits (1 or 2).

The handshake value should be 0 or 1 depending on whether hardware handshaking is desired.

The default setting for the NDICAPI (i.e. after a power-on or a reset) is (9600, "8N1", 0). A commonly used setting is (115200, "8N1", 1).

Before this function is called you should send a COMM command to the ndicapi and read the "OKAY" reply.

The return value will be 0 if the call was successful. A negative return value means that an IO error occurred, or that the specified parameters are not available for this serial port.

int ndiSerialFlush	(	NDIFileHandle	serial_port,
		int	flushtype
	)

Flush out the serial I/O buffers. The following options are available:

• NDI_IFLUSH: discard the contents of the input buffer
• NDI_OFLUSH: discard the contents of the output buffer
• NDI_IOFLUSH: discard the contents of both buffers.

The return value of this function will be if the call was successful. A negative return value means that an IO error occurred.

NDIFileHandle ndiSerialOpen

(

const char *

device

)

Open the specified serial port device. A return value of NDI_INVALID_HANDLE means that an error occurred. The serial port will be set to 9600 baud, 8N1, no handshake.

The macros NDI_DEVICE0 through NDI_DEVICE3 will expand to valid device names for the first four serial ports, e.g. "/dev/ttyS0" on linux.

The type of the handle is platform-specific.

int ndiSerialRead	(	NDIFileHandle	serial_port,
		char *	reply,
		int	n
	)

Read characters from the serial port until a carriage return is received. A maximum of 'n' characters will be read. The number of characters actually read is returned. The resulting string will not be null-terminated.

If the return value is negative, then an IO error occurred. If the return value is zero, then a timeout error occurred. If the return value is equal to 'n' and the final character is not a carriage return (i.e. reply[n-1] != ''), then the read was incomplete and there are more characters waiting to be read.

int ndiSerialSleep	(	NDIFileHandle	serial_port,
		int	milliseconds
	)

Sleep for the specified number of milliseconds. The actual sleep time is likely to last for 10ms longer than the specifed time due to task scheduling overhead. The return value is always zero.

int ndiSerialTimeout	(	NDIFileHandle	serial_port,
		int	milliseconds
	)

Change the timeout for the serial port in milliseconds. The default is 5 seconds, but this might be too long for certain applications.

The return value will be 0 if the call was successful. A negative return value signals failure.

int ndiSerialWrite	(	NDIFileHandle	serial_port,
		const char *	text,
		int	n
	)

Write a stream of 'n' characters from the string 'text' to the serial port. The number of characters actually written is returned. The NDICAPI expects all commands to end with a carriage return.

The serial port input buffers are flushed before the information is written, because leftover bytes in the input buffer are likely due to an error on a previous communication.

If the return value is negative, then an IO error occurred. If the return value is less than 'n', then a timeout error occurred.