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 an 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:

1. include "lcd.h"

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 (LCD_ON) or off (LCD_OFF). 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

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 is defined by 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.

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.

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.

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.

Input Functions

lcd_handle *lcd_inputcreate(char *selection, char *initiail, 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.", and initial contains the initial result which is to be edited (or NULL) if the result is to be initialised as blank 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.

Clock Functions

lcd_handle *clockcreate()

This function creates a clock screen.

void lcd_clockupdate(lcd_handle *handle, char *str, struct tm *now, struct tm *alarm, slcd_e_status alarmon)

This function sets the title, updates the time and alarm (alarmon=SLCD_ON) in the clock buffer. If the alarm time is NULL, or alarmon status is off (SLCD_OFF), the alarm is not shown. 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() 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 (200ms suggested). Note that the function should not be called before lcd_init() has been performed, and should not be performed after lcd_exit() has been called.