RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity
630b14b322
RIOT/drivers/include/aip31068.h
Hendrik van Essen 6778bf4b98 driver/aip31068: add new driver
2020-09-29 14:42:15 +02:00

427 lines
16 KiB
C
Raw Blame History

/*
* Copyright (C) 2020 Freie Universität Berlin
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @defgroup drivers_aip31068 AIP31068 I2C LCD controller
* @ingroup drivers_display
* @brief Device driver for AIP31068
*
* @{
*
* @author Hendrik van Essen <hendrik.ve@fu-berlin.de>
* @file
*/
#ifndef AIP31068_H
#define AIP31068_H
#ifdef __cplusplus
extern "C"
{
#endif
#include "stdbool.h"
#include "periph/i2c.h"
#include "aip31068_regs.h"
/**
* @brief Keys for custom symbols.
*/
typedef enum {
CUSTOM_SYMBOL_1 = 0, /**< 1st custom symbol */
CUSTOM_SYMBOL_2 = 1, /**< 2nd custom symbol */
CUSTOM_SYMBOL_3 = 2, /**< 3rd custom symbol */
CUSTOM_SYMBOL_4 = 3, /**< 4th custom symbol */
CUSTOM_SYMBOL_5 = 4, /**< 5th custom symbol */
CUSTOM_SYMBOL_6 = 5, /**< 6th custom symbol */
CUSTOM_SYMBOL_7 = 6, /**< 7th custom symbol */
CUSTOM_SYMBOL_8 = 7, /**< 8th custom symbol */
} aip31068_custom_symbol_t;
/**
* @brief Defines the direction of the text insertion. Starting from the cursor,
* either increment the column of the cursor position after insertion
* (LEFT_TO_RIGHT), or decrement the current column of the cursor
* position after insertion (RIGHT_TO_LEFT).
*/
typedef enum {
LEFT_TO_RIGHT, /**< Insert text from left to right */
RIGHT_TO_LEFT, /**< Insert text from right to left */
} aip31068_text_insertion_mode_t;
/**
* @brief Size of a character of the display in dots/pixels.
*/
typedef enum {
FONT_SIZE_5x8, /**< Single character has 5x8 pixels */
FONT_SIZE_5x10, /**< Single character has 5x10 pixels */
} aip31068_font_size_t;
/**
* @brief Bit mode for the display.
*/
typedef enum {
BITMODE_4_BIT, /**< Use 4 bit mode */
BITMODE_8_BIT, /**< Use 8 bit mode */
} aip31068_bit_mode_t;
/**
* @brief AIP31068 device initialization parameters
*/
typedef struct {
i2c_t i2c_dev; /**< I2C device */
uint16_t i2c_addr; /**< I2C address of device */
uint8_t row_count; /**< Number of rows */
uint8_t col_count; /**< Number of columns */
aip31068_font_size_t font_size; /**< Font size */
aip31068_bit_mode_t bit_mode; /**< Bit mode */
} aip31068_params_t;
/**
* @brief AIP31068 PWM device data structure type
*/
typedef struct {
aip31068_params_t params; /**< Device initialization parameters */
uint8_t _curr_display_control; /**< Current value of DISPLAY_CONTROL */
uint8_t _curr_entry_mode_set; /**< Current value of ENTRY_MODE_SET */
} aip31068_t;
/**
* @brief Initialization.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] params Parameters for device initialization
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_init(aip31068_t *dev, const aip31068_params_t *params);
/**
* @brief Turn on the display.
*
* @param[in] dev Device descriptor of the AIP31068
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_turn_on(aip31068_t *dev);
/**
* @brief Turn off the display.
*
* @param[in] dev Device descriptor of the AIP31068
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_turn_off(aip31068_t *dev);
/**
* @brief Clear the display and set the cursor to position (0, 0).
*
* @note: Also changes to setTextInsertionMode(LEFT_TO_RIGHT)
*
* @param[in] dev Device descriptor of the AIP31068
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_clear(aip31068_t *dev);
/**
* @brief Reset cursor position to (0, 0) and scroll display to original position.
*
* @param[in] dev Device descriptor of the AIP31068
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_return_home(aip31068_t *dev);
/**
* @brief Enable or disable automated scrolling.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] enabled Enable or disable
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_set_auto_scroll_enabled(aip31068_t *dev, bool enabled);
/**
* @brief Enable or disable cursor blinking.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] enabled Enable or disable
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_set_cursor_blinking_enabled(aip31068_t *dev, bool enabled);
/**
* @brief Show or hide the cursor.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] visible Show or hide
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_set_cursor_visible(aip31068_t *dev, bool visible);
/**
* @brief Move the cursor to a given position.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] row Row of the new cursor position (starting at 0)
* @param[in] col Column of the new cursor position (starting at 0)
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_set_cursor_position(aip31068_t *dev, uint8_t row, uint8_t col);
/**
* @brief Set the direction from which the text is inserted, starting from the cursor.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] mode Insertion mode
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_set_text_insertion_mode(aip31068_t *dev,
aip31068_text_insertion_mode_t mode);
/**
* @brief Move the cursor one unit to the left.
*
* When the cursor passes the 40th character of the first line and a second line
* is available, the cursor will move to the second line.
*
* @param[in] dev Device descriptor of the AIP31068
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_move_cursor_left(aip31068_t *dev);
/**
* @brief Move the cursor one unit to the right.
*
* When the cursor passes the 40th character of the first line and a second line
* is available, the cursor will move to the second line.
*
* @note: The cursor respects the setting for the insertion mode and is set
* to (1, 0) for LEFT_TO_RIGHT and to (1, COL_MAX) for RIGHT_TO_LEFT.
*
* @param[in] dev Device descriptor of the AIP31068
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_move_cursor_right(aip31068_t *dev);
/**
* @brief Scroll the entire display content (all lines) one unit to the left.
*
* @note: The cursor respects the setting for the insertion mode and is set
* to (1, 0) for LEFT_TO_RIGHT and to (1, COL_MAX) for RIGHT_TO_LEFT.
*
* @param[in] dev Device descriptor of the AIP31068
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_scroll_display_left(aip31068_t *dev);
/**
* @brief Scroll the entire display content (all lines) one unit to the right.
*
* @param[in] dev Device descriptor of the AIP31068
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_scroll_display_right(aip31068_t *dev);
/**
* @brief Create a custom symbol.
*
* Useful link: https://maxpromer.github.io/LCD-Character-Creator/
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] customSymbol Key to which a custom symbol should be assigned
* @param[in] charmap Bitmap definition of the custom symbol
*
* @note: The size of charmap depends on how the AIP31068 was initialized.
* 8 bytes for FONT_SIZE_5x8 and 10 bytes for FONT_SIZE_5x10.
*
* This function resets the cursor position. Therefore this function
* should be called before printing any characters to the display.
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_set_custom_symbol(aip31068_t *dev,
aip31068_custom_symbol_t customSymbol,
const uint8_t charmap[]);
/**
* @brief Print a custom symbol by key reference.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] customSymbol Key of the custom symbol to be printed
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_print_custom_symbol(aip31068_t *dev,
aip31068_custom_symbol_t customSymbol);
/**
* @brief Print a string.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] data String to be printed (null-terminated)
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_print(aip31068_t *dev, const char *data);
/**
* @brief Print a single character.
*
* @param[in] dev Device descriptor of the AIP31068
* @param[in] c Character to be printed
*
* @retval 0 on success
* @retval -1 if acquiring of I2C bus fails
* @retval -EIO When slave device doesn't ACK the byte
* @retval -ENXIO When no devices respond on the address sent on the bus
* @retval -ETIMEDOUT When timeout occurs before device's response
* @retval -EINVAL When an invalid argument is given
* @retval -EOPNOTSUPP When MCU driver doesn't support the flag operation
* @retval -EAGAIN When a lost bus arbitration occurs
*/
int aip31068_print_char(aip31068_t *dev, char c);
#ifdef __cplusplus
}
#endif
#endif /* AIP31068_H */
/** @} */
View Git Blame Copy Permalink