LCD display

Overview

The Reciva radios support a range of LCD displays, from 2 line text displays to much larger graphical displays.

Some displays/radios have features such as adjustable brightness and contrast, and settable icons and LEDs, and others do not.

The sharpfin project has provided the Libreciva interface library, which is written in two halves (a low level hardware access library - lcdhw.c/lcdhw.h, and a higher level interface library - lcd.c/lcd.h).

Usage

To use the library, ensure that the following line is placed at the top of your C file:

<syntaxhighlight>#include "lcd.h"</syntaxhighlight>

And when linking, ensure that the libreciva.a file is included.

General Functions

The following functions are provided to access the LCD

int lcd_init()

The initialise function, which must be called at the start of any program which is going to use the display.

void lcd_exit()

The shutdown function, which clears the screen, and releases any internal buffers - note that each 'screens' lcd_delete() function must also be called before the call to lcd_exit() is made.

enum slcd_e_caps lcd_capabilities()

This function returns the capabilities of the LCD. The returned number is a bitmask, and includes the following fields:

• SLCD_HAS_ARROWS - It is possible to use >arrows< to select lines
• SLCD_HAS_GRAPHICS - The display supports graphics modes
• SLCD_HAS_BRIGHTNESS - The display has a brightness control
• SLCD_HAS_CONTRAST - The display has a contrast control
• SLCD_HAS_ICONS - The display has icons
• SLCD_HAS_LEDS - The display has LEDs

void lcd_brightness(int level)

Adjusts the screens brightness (if supported) to the given level (0-100).

void lcd_contrast(int level)

Adjusts the screens contrast (if supported) to the given level (0-100)

int lcd_seticon(enum slcd_e_icons icon, enum slcd_e_status state)

This function turns the identified icon or LED on (SLCD_ON) or off (SLCD_OFF) - if the icons are present on the radio. If the icons are not present, the function will simply set an internal register which can be acquired with the lcd_geticon() function. The icons / LEDs are one of:

• SLCD_ICON_SHIFT
• SLCD_ICON_IRADIO
• SLCD_ICON_MEDIA
• SLCD_ICON_SHUFFLE
• SLCD_ICON_REPEAT
• SLCD_ICON_SLEEP
• SLCD_ICON_MUTE
• SLCD_ICON_ALARM
• SLCD_ICON_SNOOZE
• SLCD_ICON_MENU
• SLCD_ICON_VOLUME

enum slcd_e_status lcd_geticon(enum slcd_e_icons icon)

This function returns SLCD_ON or SLCD_OFF - the current state of the specified icon or LED. Se lcd_seticon() for a list of the available icons.

int lcd_width(), int lcd_height()

These functions simply return the width and height of the display.

Frame Functions

The library provides a group of functions to manage the LCD, using it as a fixed frame. Lines that are too long, are automatically scrolled left/right when the lcd_tick() function is called. The frame height can be found by calling lcd_height().

lcd_handle *lcd_framecreate()

This function creates a frame buffer, which can be updated, before being written to the actual display with the lcd_refresh() function. The function creates a handle, which must be used in all screen operations. If there are memory problems when creating the frame, the function returns NULL.

int lcd_framesetline(lcd_handle *handle, int line, char *str)

This function sets the text on the line to 'str', for the given handle's frame. Note that this does not cause the LCD to update - lcd_refresh() is required. Line must be >= 0 and < lcd_height(). Note that the output is left justified. If the operation succeeded, the function returns true (SLCD_TRUE) and on failure, returns false (SLCD_FALSE).

int lcd_frameprintf(lcd_handle *handle, int line, char *fmt, ...)

This function provides a printf style function, and puts the result (left justified) on the given line. This function returns SLCD_TRUE (true) on success.

enum slcd_e_status lcd_framebar(lcd_handle *handle, int line, int min, int max, int progres, enum slcd_e_bartype bartype)

This function draws a progress bar on the given line of the screen. The bar takes the full screen width, and contains either volume bars (bartype=SLCD_VOLUMEBAR), or small arrows (bartype=SLCD_ARROWBAR). This function returns SLCD_TRUE (true) on success, or false (SLCD_FALSE) on memory allocation errors.

enum slcd_e_status lcd_framestatus(lcd_handle *handle, int line, enum slcd_e_status showicons)

This function sets the given line of the screen to contain a status line. The status line includes the current time of day (which is updated with the tick() function), and optionally (if showicons is SLCD_TRUE) a representation of the Sleep and Alarm icons.

Note that if the radio supports icons, the Sleep and Alarm representations are not displayed.

Menu Functions

The interface supports the management of menus, which scroll up/down. The interface provides functions to add as many menu entries as is desired, and then the interface manages the scrolling and animation.

lcd_handle *lcd_menucreate()

This function creates an empty menu. It returns a handle to the menu, or NULL of there was a problem allocating memory.

slcd_e_status lcd_menuclear(lcd_handle *handle)

This function clears all of the rows from the lcd structure, so that it can be re-used. The function returns true (SLCD_TRUE) on success.

int lcd_menuaddentry(lcd_handle *handle, int idnumber, char *str, enum slcd_e_select selected)

This function adds an entry to the menu. The entry is added to the bottom of the menu list, and includes an idnumber, which can be retrieved when an entry is selected. One menu entry can be selected (selected=SLCD_SELECTED / selected=SLCD_NOTSELECTED) - this selected entry is where the <selection_arrows> begin.

void lcd_menusort(lcd_handle *handle)

This function sorts the menu entries into alphabetical order.

int lcd_menucontrol(lcd_handle *handle, enum slcd_e_menuctl cmd)

This function is used to navigate through the menu - it moves the selection in the buffer, but note that a call to lcd_refresh() is required to update the LCD. The cmd is either SLCD_UP or SLCD_DOWN.

int lcd_menugetselid(lcd_handle *handle)

This function returns the idnumber for the currently selected line.

char *lcd_menugetsels(lcd_handle *handle)

This function returns a pointer to the string represented on the currently selected line.

Input Functions

The LCD libreciva library provides a some functions to manage an input dialog, with a scrolling top line / chooser, and the output is displayed on the second line (row 1) of the display.

lcd_handle *lcd_inputcreate(char *selection, char *result, int maxlen)

This function sets up a screen for text input. selection contains the pallette of letters / numbers / symbols to use in the selector (e.g. "0123456789.", the result must be preset to contain either the starting string for the input, or initialised as an empty string. result is the location where the resulting text will be stored (up to maxlen-1 characters long). This function returns a handle to the screen buffer, or NULL if there was an error.

int lcd_inputcontrol(lcd_handle *handle, enum slcd_e_inputctl cmd)

This function is used to control the actual input activity. The supplied cmd can be one of the following:

• SLCD_LEFT - Move the selection left (usually driven by the left button)
• SLCD_RIGHT - Move the selection right (usually driven by the right button)
• SLCD_ENTER - Select the current selected character (usually driven by the enter button)

Note that this function does not update the display - lcd_refresh() must be called for this to happen.

This function will normally return false (SLCD_FALSE), and will return true (SLCD_TRUE) when END has been selected, and the input activity is complete.

int lcd_inputsetline(lcd_handle *handle, int line, char *str)

This function sets the text on the specified line to str. It works in the same way as the lcd_framesetline() funciton, except that rows 0 and 1 are reserved.

int lcd_inputprintf(lcd_handle *handle, int line, char *fmt, ...)

This function sets the text (with printf) on the specified line to str. It works in the same way as the lcd_frameprintf() funciton, except that rows 0 and 1 are reserved.

YesNo Functions

The yesno functions provide a mechanism to receive the user's input to a simple yes/no/maybe question.

lcd_handle *lcd_yesnocreate(char *yesno, char *title, int defopt)

The lcd_yesnocreate function creates an input screen With a prompt on the top line, and the next line shows "<Yes>/ No ".

yesno contains the text for Yes and No, in the format "Yes/No" The function also supports more options, which are supplied in the format "Abort/Save/Ignore".

The yesno functions do not perform any scrolling of the input line. It should be noted that the selected option is padded (before and after) with angle brackets <>. This function returns a handle, which is used for future screen operations, or NULL in the case of an error.

int lcd_yesnocontrol(lcd_handle *handle, enum slcd_e_inputctl cmd)

lcd_yesnocontrol is used to scroll through the yesno options with the SLCD_LEFT and SLCD_RIGHT commands.

The function returns true (SLCD_TRUE) on success.

int lcd_yesnoresult(lcd_handle *handle)

This function returns the number of the currently selected option (first supplied is 0). e.g. If the input is "Yes/No/Ignore", the possible responses from this function are 0, 1 and 2.

Clock Functions

Some radios have a built-in hardware clock, which displays the time of day in a large font, other radios do not have anything. This function allows a clock screen to be set up, and the libreciva will use the hardware function if it is available, and if not, will display a libreciva generated version of the display (as shown in the following image):

lcd_handle *lcd_clockcreate(char *title)

This function creates a clock screen, and sets the title for the top line.

void lcd_clocksetalarm(lcd_handle *handle, struct tm *alarm, slcd_e_status alarmon)

This function sets the alarm time to be displayed with the clock. If alarmon=SLCD_FALSE, the alarm is not displayed. Note that this updates the buffer, and a call to lcd_refresh() is required to update the actual screen.

Destruction Functions

When a screen buffer is no longer required, its memory must be freed up correctly. Note that the lcd_exit() does not perform this tidy-up.

void lcd_delete(lcd_handle *handle)

This function deletes the given screen, and frees up its memory. It deletes screens that have been created with lcd_framecreate(), lcd_menucreate(), lcd_inputcreate(), lcd_yesnocreate() and lcd_clockcreate().

Screen Update Functions

There are just two functions which will cause the screen to be updated:

void lcd_refresh(lcd_handle *handle)

This function updates the LCD with the contents of the screen identified by handle.

void lcd_tick()

This function performs screen animation (if required), such as scrolling / flipping text. The function should be called at regular intervals (500ms - 1000ms suggested). Note that the function should not be called before lcd_init() has been performed, and should not be called after lcd_exit() has been performed.