LiquidCrystal_I2C_Ext - библиотека для создания меню на Ардуино

Я обратил внимание, что тема создания меню на Ардуино и ЖК дисплее весьма популярна. И ей уже посвящена одна из моих публикаций. Но я понимаю, что для новичков адаптация моего скетча может показаться нетривиальной задачей. Поэтому я решил написать библиотеку для создания меню на Ардуино и ЖК дисплее с I2C управлением, которую было бы легко использовать даже начинающему ардуинщику.

В моем распоряжении имеется ЖК дисплей 20x4 с I2C интерфейсом, к сожалению, без поддержки кириллицы. Для работы с ним нужна библиотека, я использую LiquidCrystal_I2C. И, чтобы моя библиотека не была отдельной надстройкой, завязанной на LiquidCrystal_I2C, я решил доработать последнюю, добавив в нее новые функции. И речь не только о создании меню: я добавил в библиотеку различные наработки, накопившиеся у меня за время работы с данным дисплеем.

Как и прежде для навигации по меню необходим инкрементный энкодер с кнопкой, например, KY-040. Код для работы с ним был помещен непосредственно в библиотеку. Необходимо лишь указать к каким выводам Ардуино подключен энкодер.

Получившуюся библиотеку я назвал LiquidCrystal_I2C_Ext, скачать ее можно по ссылке http://clc.la/LiquidCrystal_I2C_Ext . По сравнению с предшественницей в ней появились следующие функции:

• printAt(x, y, text) – вывод текста на дисплей с указанной позиции.
• printf(format, …) – форматированный вывод текста. Лично мне очень не хватало этой функции. Если раньше приходилось делать несколько вызовов print, или выводить текст в промежуточный буфер функцией sprintf, то сейчас достаточно одного вызова printf.
• printfAt(x, y, format, …) – форматированный вывод с указанной позиции.
• attachEncoder(pinA, pinB, pinBtn) – сообщает библиотеке, к каким выводам Ардуино подключен энкодер. Должна быть вызвана перед использованием описанных далее функций.
• getEncoderState() – опрос состояния энкодера. Возвращает значение типа eEncoderState (перечисляемый тип, описан в библиотеке как {eNone, eLeft, eRight, eButton}).
• printMultiline(text) – вывод длинного текста с возможностью вертикальной прокрутки. Возврат из функции осуществляется при нажатии кнопки энкодера.
• inputVal(title, min, max, default, [step]) – ввод значения путем вращения ручки энкодера. title – заголовок; параметры min и max задают диапазон, в котором может изменяться значение; default – начальное значение; step – величина приращения, по умолчанию равна 1. Выход из функции осуществляется при нажатии кнопки энкодера.
• inputValAt(x, y, min, max, default, [step]) – аналогична функции inputVal, но в отличие от нее не очищает дисплей при вызове и ввод значения осуществляется с указанной позиции. Данная функция может использоваться в паре с printf/printfAt, когда требуется вывести не статичный заголовок.
• inputValBitwise(title, value, precision, [scale], [signed]) – в отличие от функции inputVal, которая подходит для ввода значений из небольшого диапазона, inputValBitwise позволяет вводить значения путем редактирования отдельных разрядов числа. Параметр title определяет заголовок; value – ссылка на переменную, в которую будет помещен результат ввода; precision – общее количество разрядов в числе; scale – количество разрядов после запятой, значение по умолчанию 0; signed – разрешает (при значении 1) или запрещает (при значении 0 – по умолчанию) ввод отрицательных чисел. Функция возвращает 1, если пользователь подтвердил ввод, 0, если отказался.
• inputStrVal(title, buffer, length, available_symbols) – аналогично функции inputValBitwise предоставляет возможность поразрядного ввода, но кроме цифр могут быть введены и другие символы. Параметр title определяет заголовок; buffer – ссылка на символьный буфер, в который будет помещен результат ввода; length – количество вводимых символов; параметр available_symbols – это строка символов, доступных для ввода. Функция возвращает 1, если пользователь подтвердил ввод, 0, если отказался.
• selectVal(title, list_of_values, count, selected_index) – позволяет выбрать значение из списка list и возвращает индекс выбранного элемента.  title – отображаемый на дисплее заголовок, list – список значений для выбора, представляет собой массив значений типа char*, String или int; count – количество элементов; selected_index – индекс выбранного по умолчанию элемента.
• showMenu(menu, menu_length, show_title) – отображает меню и возвращает ключ выбранного элемента. menu – массив элементов типа sMenuItem; menu_length – длина меню; show_title – признак необходимости отображения заголовка.

Я приведу несколько примеров с данными функциями, чтобы не осталось вопросов по их использованию.

printAt, printf, printfAt

#include <Wire.h>
#include <LiquidCrystal_I2C_Ext.h>
LiquidCrystal_I2C_Ext lcd(0x27, 20, 4);

void setup() {
  char hello[] = "Hello, world!";
  String s = "String example";
  lcd.begin();
  lcd.printf("millis=%lu", millis());
  lcd.printAt(3, 1, hello);
  lcd.printAt(0, 2, s);
  lcd.printfAt(0, 3, "%s", s.c_str());
}

void loop() {

}

Функция printAt поддерживает те же типы данных, что и print: вы можете выводить на дисплей целые и дробные числа, текстовые строки (будь то массив символов или переменная типа String). А при работе с функциями форматированного вывода не забывайте, что они не поддерживают тип String и передавать им нужно указатель на строку в стиле Си. Для этого достаточно вызвать функцию c_str() класса String, в примере выше это показано.

Говоря о форматированном выводе, хочу отметить еще один момент. Реализация функций семейства printf на Ардуино поддерживает не все команды форматирования. Это было сделано с целью уменьшить размер библиотеки. Лично я столкнулся с невозможностью указать в формате printf значения width и precision через переменную (т.е. через символ *).

attachEncoder, getEncoderState

#include <Wire.h>
#include <LiquidCrystal_I2C_Ext.h>
LiquidCrystal_I2C_Ext lcd(0x27, 20, 4);

// Пины для энкодера
#define pinCLK 2
#define pinDT  3
#define pinSW  4

int x = 0; // Счетчик

void setup() {
  lcd.begin();
  lcd.attachEncoder(pinDT, pinCLK, pinSW);
  lcd.printfAt(0, 0, "%d ", x);
}

void loop() {
  // Опрашиваем состояние энкодера
  eEncoderState EncoderState = lcd.getEncoderState();
  switch (EncoderState) {
    case eLeft: // При вращении влево уменьшаем счетчик
      x--;
      break;
    case eRight: // При вращении вправо увеличиваем счетчик
      x++;
      break;
    case eButton: // При нажатии обнуляем
      x = 0;
      break;
    case eNone: // Состояние энкодера не изменилось. Выходим из функции
      return;
  }
  lcd.printfAt(0, 0, "%d ", x); // Выводим значение счетчика на дисплей
}

В данном примере выполняется подключение энкодера и опрос его состояния в цикле. При вращении энкодера изменяется значение переменной x и выводится на дисплей. Нажатие на кнопку приводит к обнулению переменной.

printMultiline

#include <avr/pgmspace.h>
#include <Wire.h>
#include <LiquidCrystal_I2C_Ext.h>
LiquidCrystal_I2C_Ext lcd(0x27, 20, 4);

// Пины для энкодера
#define pinCLK 2
#define pinDT  3
#define pinSW  4

const char text_1[] PROGMEM = "Using PROGMEM example";
const char text_2[] PROGMEM = "This text is stored in FLASH";

const char* const text[] PROGMEM = {text_1, text_2};

void setup() {
  lcd.begin();
  lcd.attachEncoder(pinDT, pinCLK, pinSW);
}

void loop() {
  char *buffer;
  lcd.printMultiline("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua");
  buffer = (char*) malloc(30); // Выделяем память для чтения строки из памяти программ
  strcpy_P(buffer, (char*)pgm_read_word(&(text[0]))); // Считываем строку из памяти программ
  lcd.printMultiline(buffer); // Выводим содержимое буфера на экран
  strcpy_P(buffer, (char*)pgm_read_word(&(text[1])));
  lcd.printMultiline(buffer);
  free(buffer); // И освобождаем буфер
  lcd.printMultiline(F("Using F() macro example. Press button to continue."));
}

На функции printMultiline нужно остановиться поподробнее. Она позволяет выводить на дисплей длинные строки с возможностью прокрутки. Но, объявив несколько таких строк в своем скетче, при компиляции вы можете заметить, как быстро они "съедают" память данных. Например, в Ардуино Уно для хранения данных доступно всего 2кб, тогда как для кода программы отведено 32кб. Поэтому при наличии в программе большого объема текстовых данных целесообразно разместить их в памяти программ. Для этого используется ключевое слово PROGMEM. 

PROGMEM – это модификатор переменных, он сообщает компилятору, что указанная переменная должна быть размещена не в памяти данных, а в памяти программ. Работает этот модификатор только с типами данных, объявленными в файле pgmspace.h, частью которой он является. Чтобы впоследствии процессор мог что-то сделать с этими данными, они должны быть скопированы из flash в SRAM. Для этого в примере выше выделяется буфер, в который происходит считывание строк. После того как данные выведены на дисплей буфер может быть освобожден.

Еще один вариант размещения строки в памяти программ – это использование макроса F() непосредственно в функции printMultiline. В примере это также показано.

inputVal, inputValAt

#include <Wire.h>
#include <LiquidCrystal_I2C_Ext.h>
LiquidCrystal_I2C_Ext lcd(0x27, 20, 4);

// Пины для энкодера
#define pinCLK 2
#define pinDT  3
#define pinSW  4

void setup() {
  lcd.begin();
  lcd.attachEncoder(pinDT, pinCLK, pinSW);
}

void loop() {
  // Запрашиваем длину массива:
  uint8_t len = lcd.inputVal("Input array len", 5, 10, 8);
  uint8_t A[len];
  uint8_t t;
  
  // Запрашиваем элементы массива:
  for (uint8_t i = 0; i < len; i++) {
    lcd.printfAt(0, 0, "Input A[%d]: ", i);
    A[i] = lcd.inputValAt(12, 0, 0, 9, 5);
  }
  
  // Сортируем массив:
  for (uint8_t i = 0; i < len - 1; i++) {
    for (uint8_t j = i + 1; j < len; j++) {
      if(A[i] > A[j]){
        t = A[i];
        A[i] = A[j];
        A[j] = t;
      }
    }
  }
  
  // Выводим отсортированный массив на дисплей:
  lcd.clear();
  lcd.print("Sorted array:");
  lcd.setCursor(0, 1);
  for (uint8_t i = 0; i < len; i++)
    lcd.printf("%d ", A[i]);
  
  // Для продолжения ждем нажатия кнопки:
  lcd.printAt(0, 2, "Press button");
  lcd.printAt(0, 3, "to continue");
  while (lcd.getEncoderState() != eButton);
}

Для демонстрации использования функций inputVal и inputValAt в данном примере предлагается ввести длину массива, а затем элементы массива. Введенный массив сортируется и выводится на дисплей. Отличие этих двух функций состоит в том, что inputValAt при вызове не очищает дисплей и позволяет предварительно вывести на дисплей заголовок, используя printf. В скетче выше это используется для отображения индекса вводимого элемента массива.

inputValBitwise

#include <Wire.h>
#include <LiquidCrystal_I2C_Ext.h>
LiquidCrystal_I2C_Ext lcd(0x27, 20, 4);

// Пины для энкодера
#define pinCLK 2
#define pinDT  3
#define pinSW  4

long v = 0;

void setup() {
  lcd.begin();
  lcd.attachEncoder(pinDT, pinCLK, pinSW);
}

void loop() {
  if (lcd.inputValBitwise("Input value", v, 5))
    lcd.printf("You entered %ld", v);
  else
    lcd.print("Input canceled");
  lcd.printAt(0, 2, "Press button");
  lcd.printAt(0, 3, "to continue");
  while (lcd.getEncoderState() != eButton); // Для продолжения ждем нажатия кнопки
}

В данном скетче для ввода значения используется функция inputValBitwise. В параметрах функции присутствует заголовок, переменная, в которую будет помещено введенное значение, и количество разрядов для ввода. При подтверждении ввода на дисплей выводится соответствующее сообщение.

inputStrVal

#include <Wire.h>
#include <LiquidCrystal_I2C_Ext.h>
LiquidCrystal_I2C_Ext lcd(0x27, 20, 4);

// Пины для энкодера
#define pinCLK 2
#define pinDT  3
#define pinSW  4

char ip[] = "192.168.001.001";

void setup() {
  lcd.begin();
  lcd.attachEncoder(pinDT, pinCLK, pinSW);
}

void loop() {
  if (lcd.inputStrVal("Input IP", ip, 15, "0123456789")){
    lcd.print("You entered:");
    lcd.printAt(0, 1, ip);
  }
  else
    lcd.print("Input canceled");
  press_button_to_continue();
}

void press_button_to_continue(){
  lcd.printAt(0, 2, "Press button");
  lcd.printAt(0, 3, "to continue");
  while (lcd.getEncoderState() != eButton);
}

Здесь функция inputStrVal используется для ввода IP адреса. При вызове функции содержимое переданного буфера рассматривается как значение по умолчанию и выводится на дисплей. Последний параметр функции определяет разрешенные для ввода символы, в данном случае только цифры. Если буфер содержит символы, которые не могут быть введены, то их не удастся изменить. Таким образом можно реализовать маскированный ввод.

selectVal

#include <Wire.h>
#include <LiquidCrystal_I2C_Ext.h>
LiquidCrystal_I2C_Ext lcd(0x27, 20, 4);

// Пины для энкодера
#define pinCLK 2
#define pinDT  3
#define pinSW  4

void setup() {
  lcd.begin();
  lcd.attachEncoder(pinDT, pinCLK, pinSW);
}

void loop() {
  int index;
  String list[] = {"Off", "On"};
  index = lcd.selectVal("Turn backlight", list, 2, lcd.getBacklight());
  lcd.setBacklight(index);
  lcd.printf("Backlight turned %s", list[index].c_str());
  delay(2000);
}

Функция selectVal очень полезна при выборе значения из списка. Эта задача может быть решена и с использованием меню, но преимущество функции selectVal состоит в том, что она не только позволяет выбрать значение, но еще и показывает текущее выбранное значение. Функция работает с массивами значений типа char*, String или int и возвращает индекс выбранного элемента.

showMenu

#include <Wire.h>
#include <LiquidCrystal_I2C_Ext.h>
LiquidCrystal_I2C_Ext lcd(0x27, 20, 4);

// Пины для энкодера
#define pinCLK 2
#define pinDT  3
#define pinSW  4

// Перечислим значения, используемые в меню для задания связи родитель-потомок
enum {mkBack, mkRoot, mkRun, mkOptions, mkMode, mkSpeed, mkLog, mkSelftest, mkHelp, mkFAQ, mkIndex, mkAbout};

// Опишем меню
sMenuItem menu[] = {
  {mkBack, mkRoot, "Menu demo"},
    {mkRoot, mkRun, "Run"},
    {mkRoot, mkOptions, "Options"},
      {mkOptions, mkMode, "Mode"},
      {mkOptions, mkSpeed, "Speed"},
      {mkOptions, mkLog, "Print log"},
      {mkOptions, mkSelftest, "Selftest"},
      {mkOptions, mkBack, "Back"},
    {mkRoot, mkHelp, "Help"},
      {mkHelp, mkFAQ, "FAQ"},
      {mkHelp, mkIndex, "Index"},
      {mkHelp, mkAbout, "About"},
      {mkHelp, mkBack, "Back"},
    {mkRoot, mkBack, "Exit menu"}
};

// Определим колчество элементов в меню
uint8_t menuLen = sizeof(menu) / sizeof(sMenuItem);

void setup() {
  lcd.begin();
  lcd.attachEncoder(pinDT, pinCLK, pinSW);
}

void loop() {
  uint8_t selectedMenuItem = lcd.showMenu(menu, menuLen, 1);
  if (selectedMenuItem == mkRun)
    lcd.print("Run selected");
  else if (selectedMenuItem == mkMode)
    lcd.print("Mode selected");
  else if (selectedMenuItem == mkSpeed)
    lcd.print("Speed selected");
  else if (selectedMenuItem == mkLog)
    lcd.print("Print log selected");
  else if (selectedMenuItem == mkSelftest)
    lcd.print("Selftest selected");
  else if (selectedMenuItem == mkFAQ)
    lcd.print("FAQ selected");
  else if (selectedMenuItem == mkIndex)
    lcd.print("Index selected");
  else if (selectedMenuItem == mkAbout)
    lcd.print("About selected");
  else if (selectedMenuItem == mkBack)
    lcd.print("Exit selected");
delay(2000);
}

Ну и, наконец, последняя функция – showMenu, которая берет на себя отрисовку меню и навигацию по нему. Работу с ней можно разделить на 3 этапа. Сначала нужно описать меню. Для этого в библиотеке определена структура sMenuItem:

struct sMenuItem {
  uint8_t parent;
  uint8_t key;
  char    *caption;
};

Параметры parent и key служат для задания иерархии, caption – указатель на название элемента меню. В примере показано, как описывается меню в виде массива элементов sMenuItem.

В качестве parent и key могут быть использованы целочисленные значения, начиная с 1. Но гораздо удобнее определить для них символьные имена, т.е. работать с перечислением. Обратите внимание на то, что первым в перечислении определено значение mkBack, ему соответствует значение 0. Данное значение является служебным и используется для пунктов меню, отвечающих за возврат на уровень выше.

Следующий этап – вызов функции showMenu. Ее параметрами являются описанное ранее меню, его длина и признак отвечающий за вывод заголовка.

При выборе пункта меню, не имеющего подменю, функция возвращает соответствующее ему значение key. И остается последний этап – проанализировать вернувшееся значение при помощи if или case и выполнить соответствующее выбранному элементу действие.

По-моему, получилась интересная библиотека.  Есть некоторые вещи, которые хотелось бы доработать (например, в меню нет прокрутки длинных названий),  но я решил их пока отложить, т.к. сейчас занимаюсь другими проектами. В общем скачивайте, пробуйте, оставляйте комментарии.