ls027b7dh01_open :: Quanser C Functions

navigation bar

ls027b7dh01_open

Opens a Sharp LS027B7DH01 LCD display.

Description

The ls027b7dh01_open function opens a Sharp LS027B7DH01 LCD display. The handle to the display returned by this function is used by the other LS027B7DH01 functions in the Devices API to refer to the LCD display. This handle must be closed using the ls027b7dh01_close function when the display is no longer in use.

Prototype

t_error
ls027b7dh01_open(const char* uri, t_lcd_access access, t_ls027b7dh01* display);

Parameters

const char * uri

A string containing the URI identifying the communication protocol and associated parameters to use to communicate with the display. This display is the one used on the Quanser QCar 2.

On the QCar 2, a suitable URI for the Sharp LS027B7DH01 display is spi://localhost:1?word='8',baud='45000000',polarity='on',phase='on',memsize='8192',frame='0'.

t_lcd_access access

The type of access to the LCD display. Access to the LCD can be shared, asynchronous or exclusive:

Access	Description
LCD_ACCESS_SHARED	In shared mode, the LCD may be shared by multiple processes and only holds a global mutex while actually writing to the display. Hence, two processes can write to the display and will not corrupt each other's messages. If one process currently holds the mutex, the other will simply wait for it to finish its operation and then it will grab the mutex and write to the display. The net effect is that the message from the second process may replace the message from the first process.
LCD_ACCESS_ASYNCHRONOUS	In asynchronous mode, the LCD may be shared by multiple processes and only holds a global mutex while actually writing to the display. Hence, two processes can write to the display and will not corrupt each other's messages. However, in this case, if one process currently holds the mutex, the other will simply skip its write operation and not do anything. The net effect is that the message from the second process is not displayed. This mode is typically used in combination with a process in `LCD_ACCESS_EXCLUSIVE` mode so that the process with exclusive access (e.g. a QUARC model) takes priority until it finishes with the LCD. For example, asynchronous mode is used by the QUARC Power Monitor to access the LCD so it takes lower priority than other processes.
LCD_ACCESS_EXCLUSIVE	In exclusive mode, the LCD is not shared by multiple processes. It holds the global mutex for the whole time the LCD is open. If another process tries to open the LCD in exclusive mode it will return `-QERR_BUSY` indicating that the LCD is in use.

t_ls027b7dh01 * display

A handle to the display is returned in the t_ls027b7dh01 variable passed in this parameter. This argument cannot be NULL. Pass the address of a variable of type t_ls027b7dh01.

Return value

The return value is 0 if the display is opened successfully. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_INVALID_ARGUMENT

One of the arguments is invalid.

QERR_OUT_OF_MEMORY

There is not enough memory to complete the operation.

Requirements

Include Files	Libraries
quanser_lcd_display.h	quanser_devices.lib;quanser_communications.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_ls027b7dh01 display;
t_error result = 
    ls027b7dh01_open("spi-cpu://localhost:1?word='8',baud='45000000',polarity='on',phase='on',memsize='8192',frame='0'", LCD_ACCESS_EXCLUSIVE, &display);
if (result == 0) {
    ...
    ls027b7dh01_close(display);
} else {
    TCHAR message[512];
    msg_get_error_message(NULL, result, message, sizeof(message));
    _tprintf(_T("Failed to open LCD display. %s (error %d)\n"), message, -result);
}