/*
 * 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 */
/** @} */
