ra8_touch.c

Go to the documentation of this file.

 
#include "ra8_touch.h"
 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_i2c_bus_ops.h"
#include "ra8_icu.h"
#include "ra8_log.h"
#include "ra8_touch_gt911_regs.h"

static const char* s_tag = "TOUCH";

typedef enum : uint32_t {
  k_ra8_touch_product_id_byte0 = (uint32_t)'9', 
  k_ra8_touch_irq_pin_count    = 32U,           
  k_ra8_touch_byte_mask        = 0xFFU,         
  k_ra8_touch_byte_shift       = 8U,            
} ra8_touch_internal_t;

typedef struct {
  ra8_touch_event_fn_t cb;         
  void*                ctx;        
  ra8_i2c_bus_ops_t    bus;        
  uint8_t              target_7b;  
  uint8_t              max_points; 
  uint8_t              irq_pin;    
  bool                 opened;     
} ra8_touch_state_t;

static ra8_touch_state_t s_state;
 
/* ===========================================================================
 * Helpers -- decoding + I2C transport
 * ===========================================================================
 */

RA8_INTERNAL
RA8_INTERNAL static inline void internal_pack_reg(uint16_t reg, uint8_t* out_buf)
{
  out_buf[0] = (uint8_t)(((uint32_t)reg >> k_ra8_touch_byte_shift) & k_ra8_touch_byte_mask);
  out_buf[1] = (uint8_t)((uint32_t)reg & k_ra8_touch_byte_mask);
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_gt911_read(uint16_t reg, uint8_t* buf, uint32_t len)
{
  uint8_t reg_bytes[k_ra8_touch_gt911_reg_ptr_bytes];
  internal_pack_reg(reg, reg_bytes);
  return s_state.bus.transfer(s_state.bus.ctx,
                              s_state.target_7b,
                              reg_bytes,
                              (uint32_t)k_ra8_touch_gt911_reg_ptr_bytes,
                              buf,
                              len);
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_gt911_write_byte(uint16_t reg, uint8_t value)
{
  enum : uint8_t {
    k_payload_len = k_ra8_touch_gt911_reg_ptr_bytes + 1U, 
  };
  uint8_t payload[k_payload_len];
  internal_pack_reg(reg, payload);
  payload[k_ra8_touch_gt911_reg_ptr_bytes] = value;
  return s_state.bus.write(s_state.bus.ctx,
                           s_state.target_7b,
                           payload,
                           (uint32_t)k_payload_len,
                           /*send_stop=*/true);
}

RA8_INTERNAL
RA8_INTERNAL static void internal_decode_one(const uint8_t* raw, ra8_touch_point_t* out)
{
  out->track_id = raw[k_ra8_touch_gt911_point_off_track];
  out->x = (uint16_t)((uint32_t)raw[k_ra8_touch_gt911_point_off_x_lsb] |
                      ((uint32_t)raw[k_ra8_touch_gt911_point_off_x_msb] << k_ra8_touch_byte_shift));
  out->y = (uint16_t)((uint32_t)raw[k_ra8_touch_gt911_point_off_y_lsb] |
                      ((uint32_t)raw[k_ra8_touch_gt911_point_off_y_msb] << k_ra8_touch_byte_shift));
  /* Pressure is the low byte of the 16-bit "size" field; the high byte
   * is rarely populated and is dropped here so the public type stays
   * one byte. */
  out->pressure = raw[k_ra8_touch_gt911_point_off_size_lsb];
}

RA8_INTERNAL
RA8_INTERNAL static void internal_decode_block(const uint8_t*     raw,
                                               uint8_t            n_points,
                                               ra8_touch_point_t* out,
                                               uint8_t            max_count,
                                               uint8_t*           got_count)
{
  uint8_t emit = n_points;
  if (emit > max_count) {
    emit = max_count;
  }
  if (emit > k_ra8_touch_gt911_max_points) {
    emit = k_ra8_touch_gt911_max_points;
  }
  for (uint8_t i = 0U; i < emit; i++) {
    const size_t off = (size_t)i * (size_t)k_ra8_touch_gt911_point_bytes;
    internal_decode_one(&raw[off], &out[i]);
  }
  *got_count = emit;
}
 
/* ===========================================================================
 * Lifecycle
 * ===========================================================================
 */

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_validate_cfg(const ra8_touch_cfg_t* cfg)
{
  if ((cfg->bus.write == nullptr) || (cfg->bus.transfer == nullptr)) {
    return k_ra8_err_invalid_arg;
  }
  if ((cfg->target_7b != k_ra8_touch_gt911_addr_low) &&
      (cfg->target_7b != k_ra8_touch_gt911_addr_high)) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_attach_irq_pin(uint8_t irq_pin)
{
  if ((uint32_t)irq_pin >= k_ra8_touch_irq_pin_count) {
    /* Either the sentinel value or any other "no pin" marker. */
    return k_ra8_ok;
  }
  const ra8_icu_irq_cfg_t cfg = {
    .sense      = k_ra8_icu_irqmd_falling,
    .filter_div = k_ra8_icu_fclksel_pclkb,
    .filter_en  = false,
  };
  return ra8_icu_configure_irq_pin(irq_pin, &cfg);
}

RA8_INTERNAL
RA8_INTERNAL static void internal_stash_state(const ra8_touch_cfg_t* cfg)
{
  s_state.bus        = cfg->bus;
  s_state.target_7b  = cfg->target_7b;
  s_state.irq_pin    = cfg->irq_pin;
  s_state.max_points = cfg->max_points;
  if ((s_state.max_points == 0U) || (s_state.max_points > k_ra8_touch_max_points)) {
    s_state.max_points = k_ra8_touch_max_points;
  }
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_check_product_id(void)
{
  uint8_t         product[k_ra8_touch_gt911_id_bytes] = {};
  const ra8_err_t pid_err =
    internal_gt911_read(k_ra8_touch_gt911_reg_product, product, sizeof(product));
  if (pid_err != k_ra8_ok) {
    return k_ra8_err_hw_init_failed;
  }
  if ((uint32_t)product[0] != k_ra8_touch_product_id_byte0) {
    return k_ra8_err_hw_init_failed;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_open_finalise(const ra8_touch_cfg_t* cfg)
{
  const ra8_err_t pid_err = internal_check_product_id();
  if (pid_err != k_ra8_ok) {
    return pid_err;
  }
  (void)internal_gt911_write_byte(k_ra8_touch_gt911_reg_status, k_ra8_touch_gt911_cmd_clear_status);
  return internal_attach_irq_pin(cfg->irq_pin);
}
 
[[nodiscard]] ra8_err_t ra8_touch_open(const ra8_touch_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "ra8_touch_open: cfg");
  if (s_state.opened) {
    return k_ra8_err_invalid_state;
  }
  const ra8_err_t cfg_err = internal_validate_cfg(cfg);
  RA8_RETURN_ON_ERROR(cfg_err, s_tag, "ra8_touch_open: cfg validation");
 
  internal_stash_state(cfg);
 
  const ra8_err_t fin_err = internal_open_finalise(cfg);
  RA8_RETURN_ON_ERROR(fin_err, s_tag, "ra8_touch_open: finalise");
 
  s_state.cb     = nullptr;
  s_state.ctx    = nullptr;
  s_state.opened = true;
  ra8_log_info(s_tag, "ra8_touch_open");
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_touch_close(void)
{
  if (!s_state.opened) {
    return k_ra8_err_not_initialized;
  }
  s_state.cb     = nullptr;
  s_state.ctx    = nullptr;
  s_state.opened = false;
  return k_ra8_ok;
}
 
/* ===========================================================================
 * Event handler attach / dispatch
 * ===========================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_touch_attach_handler(ra8_touch_event_fn_t fn, void* ctx)
{
  if (!s_state.opened) {
    return k_ra8_err_not_initialized;
  }
  s_state.cb  = fn;
  s_state.ctx = ctx;
  return k_ra8_ok;
}
 
void ra8_touch_dispatch_irq(void)
{
  const ra8_touch_event_fn_t fn  = s_state.cb;
  void* const                ctx = s_state.ctx;
  if (fn != nullptr) {
    fn(ctx);
  }
}
 
/* ===========================================================================
 * Touch-point read
 * ===========================================================================
 */

RA8_INTERNAL
RA8_INTERNAL static uint8_t internal_clamp_emit(uint8_t status_byte, uint8_t max_count)
{
  uint8_t emit = status_byte & k_ra8_touch_gt911_status_count_mask;
  if (emit > max_count) {
    emit = max_count;
  }
  if (emit > s_state.max_points) {
    emit = s_state.max_points;
  }
  return emit;
}

RA8_INTERNAL
RA8_INTERNAL static void internal_ack_frame(void)
{
  (void)internal_gt911_write_byte(k_ra8_touch_gt911_reg_status, k_ra8_touch_gt911_cmd_clear_status);
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t
internal_read_inner(ra8_touch_point_t* out_points, uint8_t max_count, uint8_t* got_count)
{
  /* Step 1: read the status byte. */
  uint8_t         status     = 0U;
  const ra8_err_t status_err = internal_gt911_read(k_ra8_touch_gt911_reg_status, &status, 1U);
  if (status_err != k_ra8_ok) {
    *got_count = 0U;
    return k_ra8_err_hw_error;
  }
 
  /* Step 2: bit7 must be set, otherwise no frame is ready. */
  if ((status & k_ra8_touch_gt911_status_ready_mask) == 0U) {
    *got_count = 0U;
    return k_ra8_ok;
  }
 
  /* Step 3 + 4: clamp, pull the per-point block, decode. */
  const uint8_t emit = internal_clamp_emit(status, max_count);
  if (emit > 0U) {
    uint8_t raw[(size_t)k_ra8_touch_gt911_max_points * (size_t)k_ra8_touch_gt911_point_bytes] = {};
    const uint32_t  bytes   = (uint32_t)emit * (uint32_t)k_ra8_touch_gt911_point_bytes;
    const ra8_err_t blk_err = internal_gt911_read(k_ra8_touch_gt911_reg_point0, raw, bytes);
    if (blk_err != k_ra8_ok) {
      *got_count = 0U;
      internal_ack_frame();
      return k_ra8_err_hw_error;
    }
    internal_decode_block(raw, emit, out_points, max_count, got_count);
  } else {
    /* Frame-ready with zero contacts: a full-release frame. Nothing to
     * decode -- fall through to the ack so the IC latches the next one. */
    *got_count = 0U;
  }
 
  /* Step 5: ack the frame so the IC latches the next one. */
  internal_ack_frame();
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t
ra8_touch_read(ra8_touch_point_t* out_points, uint8_t max_count, uint8_t* got_count)
{
  RA8_CHECK_NULL_PTR(out_points, s_tag, "ra8_touch_read: out_points");
  RA8_CHECK_NULL_PTR(got_count, s_tag, "ra8_touch_read: got_count");
  if (max_count == 0U) {
    *got_count = 0U;
    return k_ra8_err_invalid_arg;
  }
  if (!s_state.opened) {
    *got_count = 0U;
    return k_ra8_err_not_initialized;
  }
  return internal_read_inner(out_points, max_count, got_count);
}
 
[[nodiscard]] ra8_err_t ra8_touch_calibrate(void)
{
  /* GT911 is factory-calibrated. Nothing to do. */
  return k_ra8_ok;
}
 
#ifdef UNIT_TEST
[[nodiscard]] ra8_err_t ra8_touch_test_decode(const uint8_t*     raw,
                                              uint8_t            n_points,
                                              ra8_touch_point_t* out_points,
                                              uint8_t            max_count,
                                              uint8_t*           got_count)
{
  RA8_CHECK_NULL_PTR(raw, s_tag, "test_decode: raw");
  RA8_CHECK_NULL_PTR(out_points, s_tag, "test_decode: out_points");
  RA8_CHECK_NULL_PTR(got_count, s_tag, "test_decode: got_count");
  if (max_count == 0U) {
    *got_count = 0U;
    return k_ra8_err_invalid_arg;
  }
  internal_decode_block(raw, n_points, out_points, max_count, got_count);
  return k_ra8_ok;
}
#endif /* UNIT_TEST */