feat: add HalDisplay and HalGPIO (#522)

## Summary

Extracted some changes from
https://github.com/crosspoint-reader/crosspoint-reader/pull/500 to make
reviewing easier

This PR adds HAL (Hardware Abstraction Layer) for display and GPIO
components, making it easier to write a stub or an emulated
implementation of the hardware.

SD card HAL will be added via another PR, because it's a bit more
tricky.

---

### AI Usage

While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.

Did you use AI tools to help write this code? **NO**

lib/hal/HalDisplay.cpp

@@ -0,0 +1,51 @@
+#include <HalDisplay.h>
+#include <HalGPIO.h>
+
+#define SD_SPI_MISO 7
+
+HalDisplay::HalDisplay() : einkDisplay(EPD_SCLK, EPD_MOSI, EPD_CS, EPD_DC, EPD_RST, EPD_BUSY) {}
+
+HalDisplay::~HalDisplay() {}
+
+void HalDisplay::begin() { einkDisplay.begin(); }
+
+void HalDisplay::clearScreen(uint8_t color) const { einkDisplay.clearScreen(color); }
+
+void HalDisplay::drawImage(const uint8_t* imageData, uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+                           bool fromProgmem) const {
+  einkDisplay.drawImage(imageData, x, y, w, h, fromProgmem);
+}
+
+EInkDisplay::RefreshMode convertRefreshMode(HalDisplay::RefreshMode mode) {
+  switch (mode) {
+    case HalDisplay::FULL_REFRESH:
+      return EInkDisplay::FULL_REFRESH;
+    case HalDisplay::HALF_REFRESH:
+      return EInkDisplay::HALF_REFRESH;
+    case HalDisplay::FAST_REFRESH:
+    default:
+      return EInkDisplay::FAST_REFRESH;
+  }
+}
+
+void HalDisplay::displayBuffer(HalDisplay::RefreshMode mode) { einkDisplay.displayBuffer(convertRefreshMode(mode)); }
+
+void HalDisplay::refreshDisplay(HalDisplay::RefreshMode mode, bool turnOffScreen) {
+  einkDisplay.refreshDisplay(convertRefreshMode(mode), turnOffScreen);
+}
+
+void HalDisplay::deepSleep() { einkDisplay.deepSleep(); }
+
+uint8_t* HalDisplay::getFrameBuffer() const { return einkDisplay.getFrameBuffer(); }
+
+void HalDisplay::copyGrayscaleBuffers(const uint8_t* lsbBuffer, const uint8_t* msbBuffer) {
+  einkDisplay.copyGrayscaleBuffers(lsbBuffer, msbBuffer);
+}
+
+void HalDisplay::copyGrayscaleLsbBuffers(const uint8_t* lsbBuffer) { einkDisplay.copyGrayscaleLsbBuffers(lsbBuffer); }
+
+void HalDisplay::copyGrayscaleMsbBuffers(const uint8_t* msbBuffer) { einkDisplay.copyGrayscaleMsbBuffers(msbBuffer); }
+
+void HalDisplay::cleanupGrayscaleBuffers(const uint8_t* bwBuffer) { einkDisplay.cleanupGrayscaleBuffers(bwBuffer); }
+
+void HalDisplay::displayGrayBuffer() { einkDisplay.displayGrayBuffer(); }

lib/hal/HalDisplay.h

@@ -0,0 +1,52 @@
+#pragma once
+#include <Arduino.h>
+#include <EInkDisplay.h>
+
+class HalDisplay {
+ public:
+  // Constructor with pin configuration
+  HalDisplay();
+
+  // Destructor
+  ~HalDisplay();
+
+  // Refresh modes
+  enum RefreshMode {
+    FULL_REFRESH,  // Full refresh with complete waveform
+    HALF_REFRESH,  // Half refresh (1720ms) - balanced quality and speed
+    FAST_REFRESH   // Fast refresh using custom LUT
+  };
+
+  // Initialize the display hardware and driver
+  void begin();
+
+  // Display dimensions
+  static constexpr uint16_t DISPLAY_WIDTH = EInkDisplay::DISPLAY_WIDTH;
+  static constexpr uint16_t DISPLAY_HEIGHT = EInkDisplay::DISPLAY_HEIGHT;
+  static constexpr uint16_t DISPLAY_WIDTH_BYTES = DISPLAY_WIDTH / 8;
+  static constexpr uint32_t BUFFER_SIZE = DISPLAY_WIDTH_BYTES * DISPLAY_HEIGHT;
+
+  // Frame buffer operations
+  void clearScreen(uint8_t color = 0xFF) const;
+  void drawImage(const uint8_t* imageData, uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+                 bool fromProgmem = false) const;
+
+  void displayBuffer(RefreshMode mode = RefreshMode::FAST_REFRESH);
+  void refreshDisplay(RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
+
+  // Power management
+  void deepSleep();
+
+  // Access to frame buffer
+  uint8_t* getFrameBuffer() const;
+
+  void copyGrayscaleBuffers(const uint8_t* lsbBuffer, const uint8_t* msbBuffer);
+  void copyGrayscaleLsbBuffers(const uint8_t* lsbBuffer);
+  void copyGrayscaleMsbBuffers(const uint8_t* msbBuffer);
+  void cleanupGrayscaleBuffers(const uint8_t* bwBuffer);
+
+  void displayGrayBuffer();
+
+ private:
+  EInkDisplay einkDisplay;
+};

lib/hal/HalGPIO.cpp

@@ -0,0 +1,55 @@
+#include <HalGPIO.h>
+#include <SPI.h>
+#include <esp_sleep.h>
+
+void HalGPIO::begin() {
+  inputMgr.begin();
+  SPI.begin(EPD_SCLK, SPI_MISO, EPD_MOSI, EPD_CS);
+  pinMode(BAT_GPIO0, INPUT);
+  pinMode(UART0_RXD, INPUT);
+}
+
+void HalGPIO::update() { inputMgr.update(); }
+
+bool HalGPIO::isPressed(uint8_t buttonIndex) const { return inputMgr.isPressed(buttonIndex); }
+
+bool HalGPIO::wasPressed(uint8_t buttonIndex) const { return inputMgr.wasPressed(buttonIndex); }
+
+bool HalGPIO::wasAnyPressed() const { return inputMgr.wasAnyPressed(); }
+
+bool HalGPIO::wasReleased(uint8_t buttonIndex) const { return inputMgr.wasReleased(buttonIndex); }
+
+bool HalGPIO::wasAnyReleased() const { return inputMgr.wasAnyReleased(); }
+
+unsigned long HalGPIO::getHeldTime() const { return inputMgr.getHeldTime(); }
+
+void HalGPIO::startDeepSleep() {
+  esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
+  // Ensure that the power button has been released to avoid immediately turning back on if you're holding it
+  while (inputMgr.isPressed(BTN_POWER)) {
+    delay(50);
+    inputMgr.update();
+  }
+  // Enter Deep Sleep
+  esp_deep_sleep_start();
+}
+
+int HalGPIO::getBatteryPercentage() const {
+  static const BatteryMonitor battery = BatteryMonitor(BAT_GPIO0);
+  return battery.readPercentage();
+}
+
+bool HalGPIO::isUsbConnected() const {
+  // U0RXD/GPIO20 reads HIGH when USB is connected
+  return digitalRead(UART0_RXD) == HIGH;
+}
+
+bool HalGPIO::isWakeupByPowerButton() const {
+  const auto wakeupCause = esp_sleep_get_wakeup_cause();
+  const auto resetReason = esp_reset_reason();
+  if (isUsbConnected()) {
+    return wakeupCause == ESP_SLEEP_WAKEUP_GPIO;
+  } else {
+    return (wakeupCause == ESP_SLEEP_WAKEUP_UNDEFINED) && (resetReason == ESP_RST_POWERON);
+  }
+}

lib/hal/HalGPIO.h

@@ -0,0 +1,61 @@
+#pragma once
+
+#include <Arduino.h>
+#include <BatteryMonitor.h>
+#include <InputManager.h>
+
+// Display SPI pins (custom pins for XteinkX4, not hardware SPI defaults)
+#define EPD_SCLK 8   // SPI Clock
+#define EPD_MOSI 10  // SPI MOSI (Master Out Slave In)
+#define EPD_CS 21    // Chip Select
+#define EPD_DC 4     // Data/Command
+#define EPD_RST 5    // Reset
+#define EPD_BUSY 6   // Busy
+
+#define SPI_MISO 7  // SPI MISO, shared between SD card and display (Master In Slave Out)
+
+#define BAT_GPIO0 0  // Battery voltage
+
+#define UART0_RXD 20  // Used for USB connection detection
+
+class HalGPIO {
+#if CROSSPOINT_EMULATED == 0
+  InputManager inputMgr;
+#endif
+
+ public:
+  HalGPIO() = default;
+
+  // Start button GPIO and setup SPI for screen and SD card
+  void begin();
+
+  // Button input methods
+  void update();
+  bool isPressed(uint8_t buttonIndex) const;
+  bool wasPressed(uint8_t buttonIndex) const;
+  bool wasAnyPressed() const;
+  bool wasReleased(uint8_t buttonIndex) const;
+  bool wasAnyReleased() const;
+  unsigned long getHeldTime() const;
+
+  // Setup wake up GPIO and enter deep sleep
+  void startDeepSleep();
+
+  // Get battery percentage (range 0-100)
+  int getBatteryPercentage() const;
+
+  // Check if USB is connected
+  bool isUsbConnected() const;
+
+  // Check if wakeup was caused by power button press
+  bool isWakeupByPowerButton() const;
+
+  // Button indices
+  static constexpr uint8_t BTN_BACK = 0;
+  static constexpr uint8_t BTN_CONFIRM = 1;
+  static constexpr uint8_t BTN_LEFT = 2;
+  static constexpr uint8_t BTN_RIGHT = 3;
+  static constexpr uint8_t BTN_UP = 4;
+  static constexpr uint8_t BTN_DOWN = 5;
+  static constexpr uint8_t BTN_POWER = 6;
+};