clser.h File Reference

Basler ClSer Framegrabber API. More...

Go to the source code of this file.

Macros
#define	CL_BAUDRATE_115200   16
#define	CL_BAUDRATE_19200   2
#define	CL_BAUDRATE_230400   32
#define	CL_BAUDRATE_38400   4
#define	CL_BAUDRATE_460800   64
#define	CL_BAUDRATE_57600   8
#define	CL_BAUDRATE_921600   128
#define	CL_BAUDRATE_9600   1
#define	CL_DLL_VERSION_1_0   2
#define	CL_DLL_VERSION_1_1   3
#define	CL_DLL_VERSION_NO_VERSION   1
#define	CL_ERR_BAUD_RATE_NOT_SUPPORTED   -10008
#define	CL_ERR_BUFFER_TOO_SMALL   -10001
#define	CL_ERR_ERROR_NOT_FOUND   -10007
#define	CL_ERR_FUNCTION_NOT_FOUND   -10099
#define	CL_ERR_INVALID_ARG   -10097
#define	CL_ERR_INVALID_INDEX   -10005
#define	CL_ERR_INVALID_REFERENCE   -10006
#define	CL_ERR_MANU_DOES_NOT_EXIST   -10002
#define	CL_ERR_NO_ERR   0
#define	CL_ERR_OUT_OF_MEMORY   -10009
#define	CL_ERR_PORT_IN_USE   -10003
#define	CL_ERR_TIMEOUT   -10004
#define	CL_ERR_UNABLE_TO_LOAD_DLL   -10098
#define	CL_OK   0
#define	SISO_CL_EXT_PORT_CONFIG_INVERT_RX   0x0002
#define	SISO_CL_EXT_PORT_CONFIG_INVERT_TX   0x0001
#define	SISO_CL_EXT_PORT_CONFIG_LOOPBACK_MODE   0x0008
#define	SISO_CL_EXT_PORT_CONFIG_PARITY_ON   0x0004
#define	SISO_CL_EXT_PORT_CONFIG_SAMPLE_RX_FALLING_EDGE   0x0020
#define	SISO_CL_EXT_PORT_CONFIG_SETUP_TX_RISING_EDGE   0x0010
#define	SISO_CL_EXT_PORT_FEATURE_CONFIG   1
#define	SISO_CL_EXT_PORT_FEATURE_FIFO_DEPTH   2

Functions
int	clFlushPort (void *serialRef)
	This function discards any bytes that are available in the input buffer. .
int	clGetErrorText (int errorCode, char *errorText, unsigned int *errorTextSize)
	This function converts an error code to error text for display in a dialog box or in a standard I/O window. .
int	clGetManufacturerInfo (char *manufacturerName, unsigned int *bufferSize, unsigned int *version)
	This function returns the name of the frame grabber manufacturer who created the DLL and the version of the Camera Link specifications with which the DLL complies. .
int	clGetNumBytesAvail (void *serialRef, unsigned int *numBytes)
	This function outputs the number of bytes that are received at the port specified by serialRef but are not yet read out. .
int	clGetNumSerialPorts (unsigned int *numSerialPorts)
	This function returns the number of serial ports in your system from a specific manufacturer. .
int	clGetSerialPortIdentifier (unsigned int serialIndex, char *portID, unsigned int *bufferSize)
	This function returns a manufacturer-specific identifier for each serial port in your system. .
int	clGetSupportedBaudRates (void *serialRef, unsigned int *baudRates)
	This function returns the valid baud rates of the current interface. .
void	clSerialClose (void *serialRef)
	This function closes the serial device and cleans up the resources associated with serialRef. .
int	clSerialInit (unsigned int serialIndex, void **serialRefPtr)
	This function initializes the device referred to by serialIndex and returns a pointer to an internal serial reference structure. .
int	clSerialRead (void *serialRef, char *buffer, unsigned int *numBytes, unsigned int serialTimeout)
	This function reads numBytes from the serial device referred to by serialRef. .
int	clSerialWrite (void *serialRef, char *buffer, unsigned int *bufferSize, unsigned int serialTimeout)
	This function writes the data in the buffer to the serial device referenced by serialRef. .
int	clSetBaudRate (void *serialRef, unsigned int baudRate)
	This function sets the baud rate for the serial port of the selected device. .
int	clSetFlowControlMode (void *serialRef, void *secondRef, unsigned int flowControl)
	This function allows to enable asymmetric RTS/CTS hardware flow control. .
int	clSetParity (void *serialRef, unsigned int parityOn)
	This function sets the parity for the serial port of the selected device. .
int	clSetPortFeature (void *serialRef, unsigned int feature, unsigned int value)
	This function allows to activate different enhanced settings. .

Detailed Description

Basler ClSer Framegrabber API.

clser.h

Copyright (c) 2021 Basler AG, All Rights Reserved.

Author

Basler AG

Macro Definition Documentation

CL_BAUDRATE_115200

#define CL_BAUDRATE_115200   16

CL_BAUDRATE_19200

#define CL_BAUDRATE_19200   2

CL_BAUDRATE_230400

#define CL_BAUDRATE_230400   32

CL_BAUDRATE_38400

#define CL_BAUDRATE_38400   4

CL_BAUDRATE_460800

#define CL_BAUDRATE_460800   64

CL_BAUDRATE_57600

#define CL_BAUDRATE_57600   8

CL_BAUDRATE_921600

#define CL_BAUDRATE_921600   128

CL_BAUDRATE_9600

#define CL_BAUDRATE_9600   1

CL_DLL_VERSION_1_0

#define CL_DLL_VERSION_1_0   2

This Camera Link library conforms to the October 2000 version of the Camera Link Specifications

CL_DLL_VERSION_1_1

#define CL_DLL_VERSION_1_1   3

This Camera Link library conforms to the November 2002 version of the Camera Link Specifications

CL_DLL_VERSION_NO_VERSION

#define CL_DLL_VERSION_NO_VERSION   1

This library is not a valid Camera Link library

CL_ERR_BAUD_RATE_NOT_SUPPORTED

#define CL_ERR_BAUD_RATE_NOT_SUPPORTED   -10008

Requested baud rate not supported by this interface.

CL_ERR_BUFFER_TOO_SMALL

#define CL_ERR_BUFFER_TOO_SMALL   -10001

User buffer not large enough to hold data.

CL_ERR_ERROR_NOT_FOUND

#define CL_ERR_ERROR_NOT_FOUND   -10007

Could not find the error description for this error code.

CL_ERR_FUNCTION_NOT_FOUND

#define CL_ERR_FUNCTION_NOT_FOUND   -10099

Function does not exist in the manufacturer's library.

CL_ERR_INVALID_ARG

#define CL_ERR_INVALID_ARG   -10097

The function was called by using an invalid argument.

CL_ERR_INVALID_INDEX

#define CL_ERR_INVALID_INDEX   -10005

Not a valid index.

CL_ERR_INVALID_REFERENCE

#define CL_ERR_INVALID_REFERENCE   -10006

The serial reference is not valid.

CL_ERR_MANU_DOES_NOT_EXIST

#define CL_ERR_MANU_DOES_NOT_EXIST   -10002

The requested manufacturer's DLL does not exist on your system.

CL_ERR_NO_ERR

#define CL_ERR_NO_ERR   0

Function returned successfully.

CL_ERR_OUT_OF_MEMORY

#define CL_ERR_OUT_OF_MEMORY   -10009

System is out of memory and could not perform required actions.

CL_ERR_PORT_IN_USE

#define CL_ERR_PORT_IN_USE   -10003

Port is valid but cannot be opened because it is in use.

CL_ERR_TIMEOUT

#define CL_ERR_TIMEOUT   -10004

Operation not completed within specified timeout period.

CL_ERR_UNABLE_TO_LOAD_DLL

#define CL_ERR_UNABLE_TO_LOAD_DLL   -10098

The DLL was unable to load due to a lack of memory or because it does not export all required functions.

CL_OK

#define CL_OK   0

SISO_CL_EXT_PORT_CONFIG_INVERT_RX

#define SISO_CL_EXT_PORT_CONFIG_INVERT_RX   0x0002

Invert the received signal

SISO_CL_EXT_PORT_CONFIG_INVERT_TX

#define SISO_CL_EXT_PORT_CONFIG_INVERT_TX   0x0001

Invert the transmitted signal

SISO_CL_EXT_PORT_CONFIG_LOOPBACK_MODE

#define SISO_CL_EXT_PORT_CONFIG_LOOPBACK_MODE   0x0008

Enable loopback mode

SISO_CL_EXT_PORT_CONFIG_PARITY_ON

#define SISO_CL_EXT_PORT_CONFIG_PARITY_ON   0x0004

Set parity on. If you set the parity with clSetParity, you don't need to include this flag.

SISO_CL_EXT_PORT_CONFIG_SAMPLE_RX_FALLING_EDGE

#define SISO_CL_EXT_PORT_CONFIG_SAMPLE_RX_FALLING_EDGE   0x0020

Sample received signal with the falling edge of the clock (USART mode)

SISO_CL_EXT_PORT_CONFIG_SETUP_TX_RISING_EDGE

#define SISO_CL_EXT_PORT_CONFIG_SETUP_TX_RISING_EDGE   0x0010

Setup transmitted signal with the rising edge of the clock (USART mode)

SISO_CL_EXT_PORT_FEATURE_CONFIG

#define SISO_CL_EXT_PORT_FEATURE_CONFIG   1

Set port configuration. The value is a combination of ORed SISO_CL_EXT_PORT_CONFIG_ flags

SISO_CL_EXT_PORT_FEATURE_FIFO_DEPTH

#define SISO_CL_EXT_PORT_FEATURE_FIFO_DEPTH   2

Set the serial port FIFO depth in characters (default 0)

Function Documentation

clFlushPort()

int clFlushPort

(

void *

serialRef

)

This function discards any bytes that are available in the input buffer. .

Parameters

serialRef

The value obtained by the clSerialInit() function that describes the port to be flushed.

clGetErrorText()

int clGetErrorText	(	int	errorCode,
		char *	errorText,
		unsigned int *	errorTextSize )

This function converts an error code to error text for display in a dialog box or in a standard I/O window. .

Parameters

errorCode	The error code used to find the appropriate error text. An error code is returned by every function in this library.
errorText	A caller-allocated buffer which contains the NULL-terminated error text on function return.
errorTextSize	On success, contains the number of bytes written into the buffer, including the NULL-termination character. This value should be the size in bytes of the error text buffer passed in. On CL_ERR_BUFFER_TOO_SMALL, contains the size of the buffer needed to write the error text.

Return values

CL_ERR_NO_ERR	the error text has been written into errorText
CL_ERR_BUFFER_TOO_SMALL	errorText is too small to contain the error message, it needs to be scaled to the value written into errorTextSize
CL_ERR_ERROR_NOT_FOUND

clGetManufacturerInfo()

int clGetManufacturerInfo	(	char *	manufacturerName,
		unsigned int *	bufferSize,
		unsigned int *	version )

This function returns the name of the frame grabber manufacturer who created the DLL and the version of the Camera Link specifications with which the DLL complies. .

Parameters

manufacturerName	A pointer to a user-allocated buffer into which the function copies the manufacturer name. The returned name is NULL-terminated.
bufferSize	As an input, this value should be the size of the buffer that is passed. On successful return, this parameter contains the number of bytes written into the buffer, including the NULL termination character. On CL_ERR_BUFFER_TOO_SMALL, this parameter contains the size of the buffer needed to write the data text.
version	A constant stating the version of the Camera Link specifications with which this DLL complies.

Return values

CL_ERR_BUFFER_TOO_SMALL	manufacturerName is too small to contain the manufacturer name, it needs to be scaled to the value written into bufferSize.
CL_ERR_NO_ERR

clGetNumBytesAvail()

int clGetNumBytesAvail	(	void *	serialRef,
		unsigned int *	numBytes )

This function outputs the number of bytes that are received at the port specified by serialRef but are not yet read out. .

Parameters

serialRef	The value obtained by the clSerialInit() function.
numBytes	The number of bytes currently available to be read from the port.

Return values

CL_ERR_NO_ERR
CL_ERR_INVALID_REFERENCE

clGetNumSerialPorts()

int clGetNumSerialPorts

(

unsigned int *

numSerialPorts

)

This function returns the number of serial ports in your system from a specific manufacturer. .

Parameters

numSerialPorts

The number of serial ports in your system that you can access with the current DLL.

Return values

CL_ERR_NO_ERR

clGetSerialPortIdentifier()

int clGetSerialPortIdentifier	(	unsigned int	serialIndex,
		char *	portID,
		unsigned int *	bufferSize )

This function returns a manufacturer-specific identifier for each serial port in your system. .

This returns a string which contains the board and port indexes that are used by Basler Framegrabber SDK (e.g. function Fg_InitEx()).

Parameters

serialIndex	A zero-based index value. The valid range for serialIndex is 0 to (n–1), where n is the value of numSerialPorts, as returned by clGetNumSerialPorts().
portID	Manufacturer-specific identifier for the serial port
bufferSize	As an input, this value should be the size of the buffer that is passed. On successful return, this parameter contains the number of bytes written into the buffer, including the NULL termination character. On CL_ERR_BUFFER_TOO_SMALL, this parameter contains the size of the buffer needed to write the data text.

Return values

CL_ERR_NO_ERR
CL_ERR_INVALID_INDEX
CL_ERR_BUFFER_TOO_SMALL	portID is too small to contain the port identification string, it needs to be scaled to the value written into bufferSize.

Example code to print out the port identifier of port with index "i":

char *buf = NULL;
unsigned int buflen = 0;
if (clGetSerialPortIdentifier(i, buf, &buflen) != CL_ERR_BUFFER_TOO_SMALL)
    return;
buf = malloc(buflen);
if (clGetSerialPortIdentifier(i, buf, &buflen) == CL_ERR_NO_ERR)
    printf("port %i is identified as %s\n", i, buf);
free(buf);

clGetSupportedBaudRates()

int clGetSupportedBaudRates	(	void *	serialRef,
		unsigned int *	baudRates )

This function returns the valid baud rates of the current interface. .

Parameters

serialRef	The value obtained from the clSerialInit() function, which describes the port being queried for baud rates.
baudRates	Bitfield that describes all supported baud rates of the serial port as described by serialRefPtr.

Return values

CL_ERR_NO_ERR
CL_ERR_INVALID_REFERENCE

clSerialClose()

void clSerialClose

(

void *

serialRef

)

This function closes the serial device and cleans up the resources associated with serialRef. .

Upon return, serialRef is no longer usable.

Parameters

serialRef

The value obtained from the clSerialInit() function for clean-up.

clSerialInit()

int clSerialInit	(	unsigned int	serialIndex,
		void **	serialRefPtr )

This function initializes the device referred to by serialIndex and returns a pointer to an internal serial reference structure. .

The serial port will be initialized with the default settings. The baudrate will be set to 9600, no parity and any advanced port features will be set to the hardware defaults. If the serial port supports both UART and USART mode, it will be set to UART mode.

Parameters

serialIndex	A zero-based index value. For n serial devices in the system supported by this library, serialIndex has a range of 0 to (n-1).
serialRefPtr	On a successful call, points to a value that contains a pointer to the vendor-specific reference to the current session.

Return values

CL_ERR_NO_ERR
CL_ERR_PORT_IN_USE
CL_ERR_INVALID_INDEX
CL_ERR_INVALID_REFERENCE

clSerialRead()

int clSerialRead	(	void *	serialRef,
		char *	buffer,
		unsigned int *	numBytes,
		unsigned int	serialTimeout )

This function reads numBytes from the serial device referred to by serialRef. .

clSerialRead() will return when numBytes are available at the serial port or when the serialTimeout period has passed. Upon success, numBytes are copied into buffer. In the case of any error, including CL_ERR_TIMEOUT, no data is copied into buffer.

Parameters

serialRef	The value obtained from the clSerialInit() function.
buffer	Points to a user-allocated buffer. Upon a successful call, buffer contains the data read from the serial device. Upon failure, this buffer is not affected. Caller should ensure that buffer is at least numBytes in size.
numBytes	The number of bytes requested by the caller.
serialTimeout	Indicates the timeout in milliseconds.

Return values

CL_ERR_NO_ERR
CL_ERR_INVALID_REFERENCE
CL_ERR_TIMEOUT

clSerialWrite()

int clSerialWrite	(	void *	serialRef,
		char *	buffer,
		unsigned int *	bufferSize,
		unsigned int	serialTimeout )

This function writes the data in the buffer to the serial device referenced by serialRef. .

Parameters

serialRef	The value obtained from the clSerialInit() function.
buffer	Contains data to write to the serial port (see note below).
bufferSize	Contains the buffer size indicating the maximum number of bytes to be written. Upon a successful call, bufferSize contains the number of bytes written to the serial device.
serialTimeout	Indicates the timeout in milliseconds.

Note

The type of the input buffer is defined to be "char *" by the CameraLink specification. The Basler Framegabber SDK implementation guarantees to never modify this data, in fact it will cast the input pointer to a "const char *" immediately. So it is fine to pass in arbitrary constant data that is casted to "char *" to satisfy this interface.

Return values

CL_ERR_NO_ERR
CL_ERR_INVALID_REFERENCE
CL_ERR_TIMEOUT

clSetBaudRate()

int clSetBaudRate	(	void *	serialRef,
		unsigned int	baudRate )

This function sets the baud rate for the serial port of the selected device. .

Use clGetSupportedBaudRates() to determine supported baud rates. The serial port will be initialized with the default settings. The parity will be disabled and any advanced port features will be set to the hardware defaults.

Parameters

serialRef	The value obtained from the clSerialInit() function.
baudRate	The baud rate you want to use. This parameter expects the values represented by the CL_BAUDRATE constants.

Return values

CL_ERR_NO_ERR
CL_ERR_INVALID_REFERENCE
CL_ERR_BAUD_RATE_NOT_SUPPORTED

clSetFlowControlMode()

int clSetFlowControlMode	(	void *	serialRef,
		void *	secondRef,
		unsigned int	flowControl )

This function allows to enable asymmetric RTS/CTS hardware flow control. .

Some serial ports support standard asymmetric RTS/CTS hardware flow control. Since RTS and CTS signals require additional connections, two UART modules have to be combined. The primary port is used for communication, while the secondary port will be disabled when hardware flow control is used. Please see device documentation for support of hardware flow control, and details which UART modules must be combined.

Parameters

serialRef	Primary port handle obtained from the clSerialInit() function.
secondRef	Secondary port handle obtained from the clSerialInit() function.
flowControl	0: turn flow control off, 0x01 use hardware flow control

Return values

CL_ERR_NO_ERR	successful function call
CL_ERR_INVALID_REFERENCE	invalid serial handle
CL_ERR_FUNCTION_NOT_FOUND	primary port does not support USART mode
CL_ERR_INVALID_INDEX	secondary port does not match primary port

clSetParity()

int clSetParity	(	void *	serialRef,
		unsigned int	parityOn )

This function sets the parity for the serial port of the selected device. .

Any advanced port settings will be reset to the hardware defaults.

Parameters

serialRef	The value obtained from the clSerialInit() function.
parityOn	The parity that shall be used ( 0: parity off, 1: even parity)

Return values

CL_ERR_NO_ERR
CL_ERR_INVALID_REFERENCE

clSetPortFeature()

int clSetPortFeature	(	void *	serialRef,
		unsigned int	feature,
		unsigned int	value )

This function allows to activate different enhanced settings. .

The features are specific to certain hardware and frame grabber types. The function is reserved for future releases of Basler hardware. Each bit at the bit mask represents a certain switch.

Parameters

serialRef	The value obtained from the clSerialInit() function.
feature	identifier for a certain feature
value	value to be set for the feature

Return values

CL_ERR_NO_ERR	successful function call
CL_ERR_INVALID_REFERENCE	invalid serial handle
CL_ERR_FUNCTION_NOT_FOUND	invalid port feature or feature not supported
CL_ERR_INVALID_ARG	invalid value for port feature