Library for TFT-displays

Version: 2014-06-11
Status: beta
SeeAlso:AdvaBoard RPi1 documentation, TFT datasheets
Author: Advamation, Roland Koebler (support@advamation.de)
Copyright: (c) Advamation (info@advamation.de)
License:open-source / MIT
RCS:am_rpi_tft.c,v 1.30 2014/06/11 13:01:15 rk Exp

1   library configuration

1.1   init library

Initialize the library.

Does nothing (except incrementing the init-counter) if already called. am_rpi_tft_init() and am_rpi_tft_exit() must always be called pairwise.

Usage:AM_ERROR am_rpi_tft_init(void)
Returns:0 on success, <0 on error

1.2   exit library

De-initialize the library, close files and reset log-level.

Usage:void am_rpi_tft_exit(void)

1.3   logging

Configure logging.

All messages up to "level" are printed and/or stored in the logfile. DEBUG/INFO are printed to stdout, MESSAGE/WARNING/CRITICAL/ERROR to stderr.

The available levels are:
  • AM_LOG_LEVEL_DEBUG
  • AM_LOG_LEVEL_INFO
  • AM_LOG_LEVEL_MESSAGE
  • AM_LOG_LEVEL_WARNING
  • AM_LOG_LEVEL_CRITICAL
  • AM_LOG_LEVEL_ERROR
Usage:

AM_ERROR am_rpi_tft_logging(enum am_log_level level, char const *logfile, enum am_log_level logfile_level)
Parameters:
  • level: log-level for "print"
  • logfile: filename of the logfile (NULL: no logfile)
  • logfile_level: log-level for the logfile
Returns:

0 on success, <0 on error (AM_ERROR_INVALID_ARGUMENT, AM_ERROR_FILE_OPEN (see errno for details))
SeeAlso:

am_logging

2   display open / close / locking / on / off / configuration

2.1   open TFT-display

Open TFT-display.

Usage:

AM_ERROR am_rpi_tft_open(enum am_rpi_tft_type type, enum am_rpi_tft_interface interface, struct am_rpi_tft **tft)
Parameters:
  • type: display-type (TFT_32, TFT_43, TFT_50, TFT_70)
  • interface: display-interface (ADVABOARD_RPi1, ESPI)
  • tft: output, pointer to the display
Returns:

0 on success, < 0 on error (AM_ERROR_INVALID_ARGUMENT, AM_ERROR_DEVICE_NOT_SUPPORTED, AM_ERROR_NOT_IMPLEMENTED)
Note:
  • ADVABOARD_RPi1: The AdvaBoard RPi1 must be initialized before.

2.2   close TFT-display

Close display + cleanup. (+cleanup)

Usage:

void am_rpi_tft_close(struct am_rpi_tft **tft, bool off)
Parameters:
  • tft: the display
  • off: if true, also turn display and power off

2.3   manually lock TFT-display

Manually lock the TFT-display for several subsequent communications.

Note that you additionally have to use a mutex, if you're accessing the display-interface (SPI) from several threads in the same program.

Usage:

AM_ERROR am_rpi_tft_lock(struct am_rpi_tft *tft, int32_t timeout_ms)
Parameters:
  • tft: the display to lock
  • timeout_ms: timeout in ms, 0=non-blocking, -1=use auto-locking-timeout
Returns:

0 on success, <0 on error (e.g. AM_ERROR_BUSY after timeout)
SeeAlso:

am_rpi_advaboard_spi_lock()

2.4   manually unlock TFT-display

Unlock the TFT-display again after am_rpi_advaboard_tft_lock(). This has to be used for every successful call to am_rpi_advaboard_tft_lock().

Usage:void am_rpi_tft_unlock(struct am_rpi_tft *UNUSED0)

2.5   set auto-locking-timeout

Set timeout, after which display-communication-functions return AM_ERROR_BUSY if they cannot lock the TFT-display.

Usage:

void am_rpi_tft_locking_timeout(uint16_t timeout_ms)
Parameters:
  • timeout_ms: timeout in ms (default: 1000ms)

2.6   power-on/off

Turn display-power (and pins) on/off.

Usage:

AM_ERROR am_rpi_tft_power(struct am_rpi_tft *tft, bool poweron)
Parameters:
  • tft: the display
  • poweron: TRUE=on, FALSE=off
Returns:

0 on success, <0 on error

2.7   check display-power

Check if the display is currently powered-on. (And update internal power-on/off-status.)

Usage:

int am_rpi_tft_power_read(struct am_rpi_tft *tft)
Parameters:
  • tft: the display
Returns:

1 if powered-on, 0 if powered-off, <0 on error

2.8   reset TFT

Reset TFT. Note that you have to turn it on again afterwards, before accessing it.

Usage:AM_ERROR am_rpi_tft_reset(struct am_rpi_tft *tft)
Returns:0 on success, <0 on error

2.9   configure display-interface-clock

For ADVABOARD_RPi1, the SPI-clock is set to 250MHz/speed, speed=4/6/8/10/../65536, default: 4.

Usage:

AM_ERROR am_rpi_tft_clk(struct am_rpi_tft *tft, int clk)
Parameters:
  • tft: the display
  • clk: interface-clock/clock-divider
Returns:

0 on success, <0 on error
Note:
  • If the TFT-display is currently not locked by this program, configuring SPI-clock is delayed until the next lock.

2.10   on

Switch display-power on, initialize display and turn the backlight on.

This is necessary before the display can be accessed/configured.

Usage:

AM_ERROR am_rpi_tft_on(struct am_rpi_tft *tft, uint8_t brightness)
Parameters:
  • tft: the display
  • brightness: initial backlight-brightness
Returns:

0 on success, <0 on error

2.11   off

Turn display off and switch display-power and backlight-power off.

If you only want a temporary blank/black display, better use am_rpi_tft_sleep() or turn the backlight off.

Usage:

AM_ERROR am_rpi_tft_off(struct am_rpi_tft *tft, bool poweroff)
Parameters:
  • tft: the display
  • poweroff: TRUE, if the display-power should be turned off, too
Returns:

0 on success, <0 on error
Note:

poweroff=FALSE is e.g. useful if the display should be turned off, but the touchpanel should still be accessible.

2.12   sleep

Sleep mode. Can be used to temporarily disable the display to save power. The backlight is also turned off/on.

Usage:AM_ERROR am_rpi_tft_sleep(struct am_rpi_tft *tft, bool sleep)
Returns:0 on success, <0 on error

3   TFT low level functions

3.1   write to TFT

Usage:

AM_ERROR am_rpi_tft_write(struct am_rpi_tft *tft, bool isdata, uint16_t value)
Parameters:
  • tft: the display
  • isdata: D/C register selection, 0=command, 1=data
  • value: data to write
Returns:

0 on success, <0 if tft==NULL or locking the interface fails

3.2   write to TFT (raw version)

Usage:

AM_ERROR am_rpi_tft_write_raw(struct am_rpi_tft *tft, int isdata, unsigned int len, char const *data, bool finish)
Parameters:
  • tft: the display
  • isdata: D/C register selection, 0=command, 1=data, <0=don't change
  • len: number of bytes to write
  • data: "len" bytes of data
  • finish: finish the communication after sending the bytes?
Returns:

0 on success, <0 if tft==NULL or locking the interface fails

3.3   write tft-register (16-bit version)

Usage:

AM_ERROR am_rpi_tft_write_reg(struct am_rpi_tft *tft, uint8_t addr, uint16_t value)
Parameters:
  • tft: the display
  • addr: register-address
  • value: value to write to the register
Returns:

0 on success, <0 if tft==NULL, tft is off or locking the interface fails

3.4   write tft-register (raw version)

Usage:

AM_ERROR am_rpi_tft_write_reg_raw(struct am_rpi_tft *tft, uint8_t addr, unsigned int len, char const *data)
Parameters:
  • tft: the display
  • addr: register-address
  • len: number of bytes to write
  • data: "len" bytes of data
Returns:

0 on success, <0 if tft==NULL, tft is off or locking the interface fails

4   TFT high level functions

4.1   set rotation

Set display-rotation. 0 is the default direction, positive angles rotate the image to the right. Only multiples of 90 are valid.

Usage:

AM_ERROR am_rpi_tft_rotation(struct am_rpi_tft *tft, int angle)
Parameters:
  • tft: the display
  • angle: absolute rotation-angle (..., 0, 90, 180, 270, ...)
Returns:

0 on success, <0 on error

4.2   set window

Set drawing-window on the display.

Usage:

AM_ERROR am_rpi_tft_window(struct am_rpi_tft *tft, uint16_t x0, uint16_t y0, uint16_t w, uint16_t h, bool pos)
Parameters:
  • tft: the display
  • x0/y0: position of the window (top-left corner, 0..size-1)
  • w: width of the window, 0 = max.
  • h: height of the window, 0 = max.
  • pos: set drawing-position to top-left-corner?
Returns:

0 on success, <0 on error (AM_ERROR_INVALID_DEVICE, AM_ERROR_DEVICE_NOT_INITIALIZED, AM_ERROR_INVALID_ARGUMENT, ...)

4.3   set position in current window

Set drawing-position on the display, relative to current window.

Usage:

AM_ERROR am_rpi_tft_position(struct am_rpi_tft *tft, uint16_t x, uint16_t y)
Parameters:
  • tft: the display
  • x/y: position in the current window (0..size-1)
Returns:

0 on success, <0 on error (AM_ERROR_INVALID_DEVICE, AM_ERROR_DEVICE_NOT_INITIALIZED, AM_ERROR_INVALID_ARGUMENT, ...)

4.4   write pixel: start

Start/init writing pixels at the current position.

Usage:AM_ERROR am_rpi_tft_pixel_start(struct am_rpi_tft *tft)
Returns:0 on success, <0 on error
SeeAlso:am_rpi_tft_pixel, am_rpi_tft_pixel_stop

4.5   write pixel value

Write a single pixel.

Usage:

void am_rpi_tft_pixel(struct am_rpi_tft *tft, uint8_t r, uint8_t g, uint8_t b)
Parameters:
  • tft: the display
  • r: red (0..255)
  • g: green (0..255)
  • b: blue (0..255)
SeeAlso:

am_rpi_tft_pixel_start, am_rpi_tft_pixel_stop

4.6   write pixel value N times

Write a pixel N times.

Usage:

void am_rpi_tft_pixel_N(struct am_rpi_tft *tft, unsigned int N, uint8_t r, uint8_t g, uint8_t b)
Parameters:
  • tft: the display
  • N: number of pixels
  • r: red (0..255)
  • g: green (0..255)
  • b: blue (0..255)
SeeAlso:

am_rpi_tft_pixel_start, am_rpi_tft_pixel_stop

4.7   write pixel: stop

Stop writing pixels.

Usage:void am_rpi_tft_pixel_stop(struct am_rpi_tft *tft)
SeeAlso:am_rpi_tft_pixel_start, am_rpi_tft_pixel

4.8   write pixels

Write pixels to the display (incl. start/stop) in raw display-pixel-format.

Usage:

AM_ERROR am_rpi_tft_pixels_raw(struct am_rpi_tft *tft, unsigned int len, char const *data)
Parameters:
  • tft: the display
  • len: number of bytes to write
  • data: pixel-data
Returns:

0 on success, <0 on error

4.9   write pixels in window

Write pixels to a window on the display (incl. init/start/stop) in raw display-pixel-format.

Usage:

AM_ERROR am_rpi_tft_pixels_window(struct am_rpi_tft *tft, uint16_t x0, uint16_t y0, uint16_t w, uint16_t h, unsigned int len, char const *data)
Parameters:
  • tft: the display
  • x0/y0: position of the window (top-left corner)
  • w: width of the window
  • h: height of the window
  • len: number of bytes to write (usually w*h*2)
  • data: pixel-data
Returns:

0 on success, <0 on error (AM_ERROR_INVALID_DEVICE, AM_ERROR_DEVICE_NOT_INITIALIZED, AM_ERROR_INVALID_ARGUMENT, ...)

4.10   update pixels from a framebuffer

Copy a window of pixels from the framebuffer to the display. (incl. init/start/stop)

Usage:AM_ERROR am_rpi_tft_fb_update(struct am_rpi_tft *tft, uint16_t x0, uint16_t y0, uint16_t w, uint16_t h, char const *fb)
Note:The byte-order of every pixel is reversed, since the framebuffer uses a different byte-order than the display.

5   TFT drawing functions

5.1   fill

Fill display completely with some color.

Usage:

AM_ERROR am_rpi_tft_fill(struct am_rpi_tft *tft, uint8_t r, uint8_t g, uint8_t b)
Parameters:
  • tft: the display
  • r: red (0..255)
  • g: green (0..255)
  • b: blue (0..255)
Returns:

0 on success, <0 on error

6   backlight

Set backlight-brightness and turn backlight on/off.

Usage:

AM_ERROR am_rpi_tft_backlight(struct am_rpi_tft *tft, bool on, int brightness)
Parameters:
  • on: 0=on, 1=off
  • brightness: 0..255=brightness, -1=don't change
Returns:

0 on success, <0 on error

7   touchpanel functions

The TFT-displays usually contain a touchpanel. It shares its power with the display, so the display-power must be on, when the touchpanel is used. (But the display itself may be off.)

7.1   read touch

Read if / wait until the touchpanel is touched.

Usage:

AM_ERROR am_rpi_tft_tp_touched(struct am_rpi_tft *tft, int timeout_ms)
Parameters:
  • tft: the display of the touchpanel
  • timeout_ms: timeout in ms, or 0=non-blocking, -1=blocking
Returns:

0 if not touched, 1 if touched, <0 on error

7.2   read position

Read the current calibrated touch-position. If the touchsceen is not calibrated, raw values are returned.

Usage:

AM_ERROR am_rpi_tft_tp_pos(struct am_rpi_tft *tft, int *x, int *y)
Parameters:
  • tft: the display of the touchpanel
  • x/y: output, x-/y-coordinate in pixels
Returns:

0 if not touched, 1 if touched, <0 on error
Note:

The values of x and y may be outside of the display (<0 or >width/height), since the touchpanels are usually a bit larger than the display-area.

7.3   wait until touch and read position

Usage:

AM_ERROR am_rpi_tft_tp_next(struct am_rpi_tft *tft, int timeout_ms, int *x, int *y)
Parameters:
  • tft: the display of the touchpanel
  • timeout_ms: timeout in ms, or 0=non-blocking, -1=blocking
  • x/y: output, x-/y-coordinate in pixels
Returns:

0 if not touched, 1 if touched, <0 on error

7.4   read raw position

Read current raw, uncalibrated touch-position-values. Note that this probably returns 0 or a large value if the touchpanel is currently not touched.

Usage:

AM_ERROR am_rpi_tft_tp_posraw(struct am_rpi_tft *tft, uint16_t *xraw, uint16_t *yraw, double *rtouch)
Parameters:
  • tft: the display of the touchpanel
  • xraw/yraw: output, x-/y-coordinate, 0..4096
  • rtouch: output, touch-resistance (may be NULL)
Returns:

0 on success, <0 on error

7.5   set touchpanel-rotation

Set touchpanel-rotation. This configures the rotation for the pixel-coordinates returned by am_rpi_tft_tp_pos()/_next().

The touchpanel-rotation should usually be the same as the display-rotation. 0 is the default direction, positive angles rotate the image to the right. Only multiples of 90 are valid.

Usage:

AM_ERROR am_rpi_tft_tp_rotation(struct am_rpi_tft *tft, int angle)
Parameters:
  • tft: the display
  • angle: absolute rotation-angle (..., 0, 90, 180, 270, ...)
Returns:

0 on success, <0 on error

7.6   calibrate touchpanel

Calibrate the touchpanel:

  • blank screen
  • display crosshair and get touch-positions for 3 points
  • calculate touchpanel-calibration-values
  • use these values from now on or/and return them
Usage:

AM_ERROR am_rpi_tft_tp_calibrate(struct am_rpi_tft *tft, bool use, double *result)
Parameters:
  • tft: the display
  • use: TRUE=use the calibration for am_rpi_tft_tp_pos()/_next()
  • result: output, result (double[8])
Returns:

0 on success, <0 on error

7.7   set calibration

Set the calibration for am_rpi_tft_tp_pos()/_next().

Usage:

AM_ERROR am_rpi_tft_tp_calib_set(struct am_rpi_tft *tft, double *values)
Parameters:
  • tft: the display
  • values: the calibration-values, double[8]
Returns:

0 on success, AM_ERROR_INVALID_DEVICE if tft==NULL, AM_ERROR_INVALID_ARGUMENT if values==NULL

7.8   load calibration from a file

Load the calibration for am_rpi_tft_tp_pos()/_next() from a file.

Usage:AM_ERROR am_rpi_tft_tp_calib_load(struct am_rpi_tft *tft, char const *filename)
Returns:0 on success, <0 on error

7.9   store current calibration in a file

Store the current calibration to a file.

Usage:AM_ERROR am_rpi_tft_tp_calib_store(struct am_rpi_tft *tft, char const *filename)
Returns:0 on success, <0 on error

7.10   manually lock touchpanel

Manually lock the touchpanel for several subsequent communications.

Note that you additionally have to use a mutex, if you're accessing the disply-interface (SPI) from several threads in the same program.

Usage:

AM_ERROR am_rpi_tft_tp_lock(struct am_rpi_tft *tft, int32_t timeout_ms)
Parameters:
  • tft: the display of the touchpanel to lock
  • timeout_ms: timeout in ms, 0=non-blocking, -1=use auto-locking-timeout
Returns:

0 on success, <0 on error (e.g. AM_ERROR_BUSY after timeout)
SeeAlso:

am_rpi_advaboard_spi_lock()

7.11   manually unlock touchpanel

Unlock the touchpanel again after am_rpi_advaboard_tp_lock(). This has to be used for every successful call to am_rpi_advaboard_tp_lock().

Usage:void am_rpi_tft_tp_unlock(struct am_rpi_tft *UNUSED0)

7.12   set auto-locking-timeout

Set timeout, after which touchpanel-communication-functions return AM_ERROR_BUSY if they cannot lock the touchpanel.

Usage:

void am_rpi_tft_tp_locking_timeout(uint16_t timeout_ms)
Parameters:
  • timeout_ms: timeout in ms (default: 1000ms)