Auxiliary Display (auxdisplay)

Overview

Auxiliary Displays are text-based displays that have simple interfaces for displaying textual, numeric or alphanumeric data, as opposed to the Display Interface, auxiliary displays do not support custom graphical output to displays (and most often monochrome), the most advanced custom feature supported is generation of custom characters. These inexpensive displays are commonly found with various configurations and sizes, a common display size is 16 characters by 2 lines.

This API is unstable and subject to change.

Configuration Options

Related configuration options:

API Reference

Related code samples

Auxiliary display

Output "Hello World" to an auxiliary display.

group auxdisplay_interface

Auxiliary (Text) Display Interface.

Since

3.4

Version

0.1.0

Defines

AUXDISPLAY_LIGHT_NOT_SUPPORTED

Used for minimum and maximum brightness/backlight values if not supported.

Typedefs

typedef uint32_t auxdisplay_mode_t

Used to describe the mode of an auxiliary (text) display.

Enums

enum auxdisplay_position

Used for moving the cursor or display position.

Values:

enumerator AUXDISPLAY_POSITION_ABSOLUTE = 0

Moves to specified X,Y position.

enumerator AUXDISPLAY_POSITION_RELATIVE

Shifts current position by +/- X,Y position, does not take display direction into consideration.

enumerator AUXDISPLAY_POSITION_RELATIVE_DIRECTION

Shifts current position by +/- X,Y position, takes display direction into consideration.

enumerator AUXDISPLAY_POSITION_COUNT
enum auxdisplay_direction

Used for setting character append position.

Values:

enumerator AUXDISPLAY_DIRECTION_RIGHT = 0

Each character will be placed to the right of existing characters.

enumerator AUXDISPLAY_DIRECTION_LEFT

Each character will be placed to the left of existing characters.

enumerator AUXDISPLAY_DIRECTION_COUNT

Functions

int auxdisplay_display_on(const struct device *dev)

Turn display on.

Parameters:

  • dev – Auxiliary display device instance

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -errno – Negative errno code on other failure.

int auxdisplay_display_off(const struct device *dev)

Turn display off.

Parameters:

  • dev – Auxiliary display device instance

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -errno – Negative errno code on other failure.

int auxdisplay_cursor_set_enabled(const struct device *dev, bool enabled)

Set cursor enabled status on an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • enabled – True to enable cursor, false to disable

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -errno – Negative errno code on other failure.

int auxdisplay_position_blinking_set_enabled(const struct device *dev, bool enabled)

Set cursor blinking status on an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • enabled – Set to true to enable blinking position, false to disable

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -errno – Negative errno code on other failure.

int auxdisplay_cursor_shift_set(const struct device *dev, uint8_t direction, bool display_shift)

Set cursor shift after character write and display shift.

Parameters:

  • dev – Auxiliary display device instance

  • direction – Sets the direction of the display when characters are written

  • display_shift – If true, will shift the display when characters are written (which makes it look like the display is moving, not the cursor)

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_cursor_position_set(const struct device *dev, enum auxdisplay_position type, int16_t x, int16_t y)

Set cursor (and write position) on an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • type – Type of move, absolute or offset

  • x – Exact or offset X position

  • y – Exact or offset Y position

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_cursor_position_get(const struct device *dev, int16_t *x, int16_t *y)

Get current cursor on an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • x – Will be updated with the exact X position

  • y – Will be updated with the exact Y position

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_display_position_set(const struct device *dev, enum auxdisplay_position type, int16_t x, int16_t y)

Set display position on an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • type – Type of move, absolute or offset

  • x – Exact or offset X position

  • y – Exact or offset Y position

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_display_position_get(const struct device *dev, int16_t *x, int16_t *y)

Get current display position on an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • x – Will be updated with the exact X position

  • y – Will be updated with the exact Y position

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_capabilities_get(const struct device *dev, struct auxdisplay_capabilities *capabilities)

Fetch capabilities (and details) of auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • capabilities – Will be updated with the details of the auxiliary display

Return values:

  • 0 – on success.

  • -errno – Negative errno code on other failure.

int auxdisplay_clear(const struct device *dev)

Clear display of auxiliary display and return to home position (note that this does not reset the display configuration, e.g.

custom characters and display mode will persist).

Parameters:

  • dev – Auxiliary display device instance

Return values:

  • 0 – on success.

  • -errno – Negative errno code on other failure.

int auxdisplay_brightness_get(const struct device *dev, uint8_t *brightness)

Get the current brightness level of an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • brightness – Will be updated with the current brightness

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -errno – Negative errno code on other failure.

int auxdisplay_brightness_set(const struct device *dev, uint8_t brightness)

Update the brightness level of an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • brightness – The brightness level to set

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_backlight_get(const struct device *dev, uint8_t *backlight)

Get the backlight level details of an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • backlight – Will be updated with the current backlight level

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -errno – Negative errno code on other failure.

int auxdisplay_backlight_set(const struct device *dev, uint8_t backlight)

Update the backlight level of an auxiliary display.

Parameters:

  • dev – Auxiliary display device instance

  • backlight – The backlight level to set

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_is_busy(const struct device *dev)

Check if an auxiliary display driver is busy.

Parameters:

  • dev – Auxiliary display device instance

Return values:

  • 1 – on success and display busy.

  • 0 – on success and display not busy.

  • -ENOSYS – if not supported/implemented.

  • -errno – Negative errno code on other failure.

int auxdisplay_custom_character_set(const struct device *dev, struct auxdisplay_character *character)

Sets a custom character in the display, the custom character struct must contain the pixel data for the custom character to add and valid custom character index, if successful then the character_code variable in the struct will be set to the character code that can be used with the auxdisplay_write() function to show it.

A character must be valid for a display consisting of a uint8 array of size character width by character height, values should be 0x00 for pixel off or 0xff for pixel on, if a display supports shades then values between 0x00 and 0xff may be used (display driver dependent).

Parameters:

  • dev – Auxiliary display device instance

  • character – Pointer to custom character structure

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_write(const struct device *dev, const uint8_t *data, uint16_t len)

Write data to auxiliary display screen at current position.

Parameters:

  • dev – Auxiliary display device instance

  • data – Text data to write

  • len – Length of text data to write

Return values:

  • 0 – on success.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

int auxdisplay_custom_command(const struct device *dev, struct auxdisplay_custom_data *data)

Send a custom command to the display (if supported by driver)

Parameters:

  • dev – Auxiliary display device instance

  • data – Custom command structure (this may be extended by specific drivers)

Return values:

  • 0 – on success.

  • -ENOSYS – if not supported/implemented.

  • -EINVAL – if provided argument is invalid.

  • -errno – Negative errno code on other failure.

struct auxdisplay_light
#include <auxdisplay.h>

Light levels for brightness and/or backlight.

If not supported by a display/driver, both minimum and maximum will be AUXDISPLAY_LIGHT_NOT_SUPPORTED.

Public Members

uint8_t minimum

Minimum light level supported.

uint8_t maximum

Maximum light level supported.

struct auxdisplay_capabilities
#include <auxdisplay.h>

Structure holding display capabilities.

Public Members

uint16_t columns

Number of character columns.

uint16_t rows

Number of character rows.

auxdisplay_mode_t mode

Display-specific data (e.g.

4-bit or 8-bit mode for HD44780-based displays)

struct auxdisplay_light brightness

Brightness details for display (if supported)

struct auxdisplay_light backlight

Backlight details for display (if supported)

uint8_t custom_characters

Number of custom characters supported by display (0 if unsupported)

uint8_t custom_character_width

Width (in pixels) of a custom character, supplied custom characters should match.

uint8_t custom_character_height

Height (in pixels) of a custom character, supplied custom characters should match.

struct auxdisplay_custom_data
#include <auxdisplay.h>

Structure for a custom command.

This may be extended by specific drivers.

Public Members

uint8_t *data

Raw command data to be sent.

uint16_t len

Length of supplied data.

uint32_t options

Display-driver specific options for command.

struct auxdisplay_character
#include <auxdisplay.h>

Structure for a custom character.

Public Members

uint8_t index

Custom character index on the display.

uint8_t *data

Custom character pixel data, a character must be valid for a display consisting of a uint8 array of size character width by character height, values should be 0x00 for pixel off or 0xff for pixel on, if a display supports shades then values between 0x00 and 0xff may be used (display driver dependent).

uint8_t character_code

Will be updated with custom character index to use in the display write function to disaplay this custom character.