ra8_modem_at.c

Go to the documentation of this file.

 
#include "ra8_modem_at.h"
 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_modem_at_internal.h"

#define RA8_MODEM_AT_TAG "MODEM_AT"

typedef enum : uint16_t {
  k_ra8_modem_at_min_line_buf_bytes = 16U, 
} ra8_modem_at_internal_const_t;

typedef enum : uint8_t {
  k_ra8_modem_at_state_idle       = 0U, 
  k_ra8_modem_at_state_await_echo = 1U, 
  k_ra8_modem_at_state_await_resp = 2U, 
  k_ra8_modem_at_state_done       = 3U, 
} ra8_modem_at_state_t;

typedef struct {
  uint8_t               used;                                  
  uint8_t               prefix[k_ra8_modem_at_max_prefix_len]; 
  ra8_modem_at_urc_fn_t fn;                                    
  void*                 ctx;                                   
} ra8_modem_at_urc_slot_t;

typedef struct {
  uint8_t              initialized; 
  ra8_modem_at_cfg_t   cfg;         
  uint16_t             line_len;    
  ra8_modem_at_state_t state;       
  ra8_modem_at_urc_slot_t urcs[k_ra8_modem_at_max_unsolicited];
} ra8_modem_at_module_t;

static ra8_modem_at_module_t s_mod;
 
/* ------------------------------------------------------------------------- */
/* Internal helpers */
/* ------------------------------------------------------------------------- */

uint16_t priv_modem_str_len(const char* s)
{
  uint16_t i = 0U;
  while ((i < UINT16_MAX) && (s[i] != '\0')) {
    ++i;
  }
  return i;
}

uint8_t priv_modem_starts_with(const char* hay, const char* needle)
{
  uint16_t i = 0U;
  while (needle[i] != '\0') {
    if (hay[i] != needle[i]) {
      return 0U;
    }
    ++i;
  }
  return 1U;
}

uint8_t priv_modem_str_eq(const char* a, const char* b)
{
  uint16_t i = 0U;
  while ((a[i] != '\0') && (b[i] != '\0')) {
    if (a[i] != b[i]) {
      return 0U;
    }
    ++i;
  }
  return (uint8_t)((a[i] == '\0') && (b[i] == '\0'));
}

RA8_INTERNAL
static void internal_append_ch(char* out, size_t out_len, size_t* used, char ch)
{
  if ((*used + 1U) < out_len) {
    out[*used] = ch;
    ++(*used);
    out[*used] = '\0';
  }
}

uint8_t priv_modem_reset_line_should_clear(const void* line_buf, uint16_t line_buf_len)
{
  if ((line_buf != nullptr) && (line_buf_len > 0U)) {
    return 1U;
  }
  return 0U;
}

uint8_t priv_modem_payload_prefix_matches(const char* line, const char* expected_response)
{
  if ((expected_response != nullptr) && (expected_response[0] != '\0') &&
      (priv_modem_starts_with(line, expected_response) != 0U)) {
    return 1U;
  }
  return 0U;
}

uint8_t priv_modem_capture_should_clear(const void* capture, size_t capture_len)
{
  if ((capture != nullptr) && (capture_len > 0U)) {
    return 1U;
  }
  return 0U;
}

RA8_INTERNAL
static void internal_reset_line(void)
{
  s_mod.line_len = 0U;
  if (priv_modem_reset_line_should_clear(s_mod.cfg.line_buf, s_mod.cfg.line_buf_len) != 0U) {
    s_mod.cfg.line_buf[0] = (uint8_t)'\0';
  }
}

RA8_INTERNAL
static uint8_t internal_classify_final(const char* line, uint8_t* is_error)
{
  *is_error = 0U;
  if (priv_modem_str_eq(line, "OK") != 0U) {
    return 1U;
  }
  if (priv_modem_str_eq(line, "ERROR") != 0U) {
    *is_error = 1U;
    return 1U;
  }
  if (priv_modem_starts_with(line, "+CME ERROR") != 0U) {
    *is_error = 1U;
    return 1U;
  }
  if (priv_modem_starts_with(line, "+CMS ERROR") != 0U) {
    *is_error = 1U;
    return 1U;
  }
  if (priv_modem_str_eq(line, "BUSY") != 0U) {
    *is_error = 1U;
    return 1U;
  }
  if (priv_modem_str_eq(line, "NO CARRIER") != 0U) {
    *is_error = 1U;
    return 1U;
  }
  return 0U;
}

RA8_INTERNAL
static uint8_t internal_dispatch_urc(const char* line)
{
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_modem_at_max_unsolicited; ++i) {
    if (s_mod.urcs[i].used == 0U) {
      continue;
    }
    if (priv_modem_starts_with(line, (const char*)s_mod.urcs[i].prefix) != 0U) {
      s_mod.urcs[i].fn(line, s_mod.urcs[i].ctx);
      return 1U;
    }
  }
  return 0U;
}
 
/* ra8_modem_line_kind_t is defined in ra8_modem_at_internal.h so tests
 * can read the return value of priv_modem_classify(). */

ra8_modem_line_kind_t
priv_modem_classify(const char* line, const char* cmd_echo, const char* expected_response)
{
  if (line[0] == '\0') {
    return k_ra8_modem_line_kind_empty;
  }
  if ((cmd_echo != nullptr) && (priv_modem_str_eq(line, cmd_echo) != 0U)) {
    return k_ra8_modem_line_kind_echo;
  }
  uint8_t is_err = 0U;
  if (internal_classify_final(line, &is_err) != 0U) {
    return (is_err != 0U) ? k_ra8_modem_line_kind_final_err : k_ra8_modem_line_kind_final_ok;
  }
  /* If the caller didn't ask for a specific prefix, allow URC dispatch. */
  if ((expected_response == nullptr) || (expected_response[0] == '\0') ||
      (priv_modem_starts_with(line, expected_response) == 0U)) {
    if (internal_dispatch_urc(line) != 0U) {
      return k_ra8_modem_line_kind_urc;
    }
  }
  return k_ra8_modem_line_kind_payload;
}

RA8_INTERNAL
static void internal_accumulate(uint8_t byte, const char** line_out)
{
  *line_out = nullptr;
  if ((byte == (uint8_t)'\r') || (byte == (uint8_t)'\n')) {
    if (s_mod.line_len > 0U) {
      s_mod.cfg.line_buf[s_mod.line_len] = (uint8_t)'\0';
      *line_out                          = (const char*)s_mod.cfg.line_buf;
      s_mod.line_len                     = 0U;
    }
    return;
  }
  if ((s_mod.line_len + 1U) >= s_mod.cfg.line_buf_len) {
    /* Overflow: terminate, emit what we have, drop the new byte. */
    s_mod.cfg.line_buf[s_mod.line_len] = (uint8_t)'\0';
    *line_out                          = (const char*)s_mod.cfg.line_buf;
    s_mod.line_len                     = 0U;
    return;
  }
  s_mod.cfg.line_buf[s_mod.line_len] = byte;
  ++s_mod.line_len;
}

RA8_INTERNAL
static ra8_err_t internal_tx_command(const char* s)
{
  uint16_t i = 0U;
  while (s[i] != '\0') {
    const ra8_err_t err = s_mod.cfg.io.tx_byte(s_mod.cfg.io.ctx, (uint8_t)s[i]);
    if (err != k_ra8_ok) {
      return err;
    }
    ++i;
  }
  return s_mod.cfg.io.tx_byte(s_mod.cfg.io.ctx, (uint8_t)'\r');
}

RA8_INTERNAL
static uint16_t internal_effective_timeout(uint16_t timeout_ms)
{
  if (timeout_ms != 0U) {
    return timeout_ms;
  }
  if (s_mod.cfg.default_timeout_ms != 0U) {
    return s_mod.cfg.default_timeout_ms;
  }
  return (uint16_t)k_ra8_modem_at_default_timeout_ms;
}

typedef enum : uint8_t {
  k_ra8_modem_line_action_continue = 0U, 
  k_ra8_modem_line_action_done_ok  = 1U, 
  k_ra8_modem_line_action_done_err = 2U, 
} ra8_modem_line_action_t;

void priv_modem_capture_line(const char* line, char* capture, size_t capture_len, size_t* used)
{
  if ((capture == nullptr) || (capture_len == 0U)) {
    return;
  }
  if (*used > 0U) {
    internal_append_ch(capture, capture_len, used, '\n');
  }
  uint16_t k = 0U;
  while (line[k] != '\0') {
    internal_append_ch(capture, capture_len, used, line[k]);
    ++k;
  }
}

RA8_INTERNAL
static ra8_modem_line_action_t internal_handle_line(const char*           line,
                                                    ra8_modem_line_kind_t kind,
                                                    const char*           expected_response,
                                                    uint8_t*              seen_exp,
                                                    char*                 capture,
                                                    size_t                capture_len,
                                                    size_t*               used)
{
  switch (kind) {
    case k_ra8_modem_line_kind_empty:
    case k_ra8_modem_line_kind_urc:
      return k_ra8_modem_line_action_continue;
    case k_ra8_modem_line_kind_echo:
      s_mod.state = k_ra8_modem_at_state_await_resp;
      return k_ra8_modem_line_action_continue;
    case k_ra8_modem_line_kind_final_ok:
      s_mod.state = k_ra8_modem_at_state_done;
      if (*seen_exp == 0U) {
        ra8_log_error(RA8_MODEM_AT_TAG, "OK without expected prefix");
        return k_ra8_modem_line_action_done_err;
      }
      return k_ra8_modem_line_action_done_ok;
    case k_ra8_modem_line_kind_final_err:
      s_mod.state = k_ra8_modem_at_state_done;
      return k_ra8_modem_line_action_done_err;
    case k_ra8_modem_line_kind_payload:
    default:
      if (priv_modem_payload_prefix_matches(line, expected_response) != 0U) {
        *seen_exp = 1U;
      }
      priv_modem_capture_line(line, capture, capture_len, used);
      if (s_mod.state == k_ra8_modem_at_state_await_echo) {
        s_mod.state = k_ra8_modem_at_state_await_resp;
      }
      return k_ra8_modem_line_action_continue;
  }
}

typedef struct {
  const char* cmd;               
  const char* expected_response; 
  char*       capture;           
  size_t      capture_len;       
  size_t*     used;              
  uint8_t*    seen_exp;          
} ra8_modem_wait_ctx_t;

RA8_INTERNAL
static ra8_modem_line_action_t internal_pump_one(const ra8_modem_wait_ctx_t* wc)
{
  uint8_t         byte   = 0U;
  const ra8_err_t rx_err = s_mod.cfg.io.rx_byte(s_mod.cfg.io.ctx, &byte);
  if (rx_err != k_ra8_ok) {
    return k_ra8_modem_line_action_continue;
  }
  const char* line = nullptr;
  internal_accumulate(byte, &line);
  if (line == nullptr) {
    return k_ra8_modem_line_action_continue;
  }
  const ra8_modem_line_kind_t kind = priv_modem_classify(line, wc->cmd, wc->expected_response);
  return internal_handle_line(line,
                              kind,
                              wc->expected_response,
                              wc->seen_exp,
                              wc->capture,
                              wc->capture_len,
                              wc->used);
}

RA8_INTERNAL
static ra8_err_t internal_wait_response(const char* cmd,
                                        const char* expected_response,
                                        uint16_t    timeout_ms,
                                        char*       capture,
                                        size_t      capture_len)
{
  const uint32_t start = s_mod.cfg.io.now_ms(s_mod.cfg.io.ctx);
  size_t         used  = 0U;
  uint8_t seen_exp = (uint8_t)((expected_response == nullptr) || (expected_response[0] == '\0'));
 
  if (priv_modem_capture_should_clear(capture, capture_len) != 0U) {
    capture[0] = '\0';
  }
 
  s_mod.state = k_ra8_modem_at_state_await_echo;
 
  const ra8_modem_wait_ctx_t wc = {
    .cmd               = cmd,
    .expected_response = expected_response,
    .capture           = capture,
    .capture_len       = capture_len,
    .used              = &used,
    .seen_exp          = &seen_exp,
  };
 
  while (1) {
    const ra8_modem_line_action_t action = internal_pump_one(&wc);
    if (action == k_ra8_modem_line_action_done_ok) {
      internal_reset_line();
      return k_ra8_ok;
    }
    if (action == k_ra8_modem_line_action_done_err) {
      internal_reset_line();
      return k_ra8_err_hw_error;
    }
    const uint32_t elapsed = s_mod.cfg.io.now_ms(s_mod.cfg.io.ctx) - start;
    if (elapsed >= (uint32_t)timeout_ms) {
      s_mod.state = k_ra8_modem_at_state_idle;
      internal_reset_line();
      return k_ra8_err_hw_timeout;
    }
  }
}
 
/* ------------------------------------------------------------------------- */
/* Public API */
/* ------------------------------------------------------------------------- */

RA8_INTERNAL
static void internal_clear_urc_table(void)
{
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_modem_at_max_unsolicited; ++i) {
    s_mod.urcs[i].used = 0U;
    s_mod.urcs[i].fn   = nullptr;
    s_mod.urcs[i].ctx  = nullptr;
  }
}

RA8_INTERNAL
static ra8_err_t internal_validate_init_cfg(const ra8_modem_at_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, RA8_MODEM_AT_TAG, "cfg");
  RA8_CHECK_NULL_PTR(cfg->line_buf, RA8_MODEM_AT_TAG, "cfg->line_buf");
  RA8_CHECK_NULL_PTR((void*)cfg->io.tx_byte, RA8_MODEM_AT_TAG, "cfg->io.tx_byte");
  RA8_CHECK_NULL_PTR((void*)cfg->io.rx_byte, RA8_MODEM_AT_TAG, "cfg->io.rx_byte");
  RA8_CHECK_NULL_PTR((void*)cfg->io.now_ms, RA8_MODEM_AT_TAG, "cfg->io.now_ms");
  if (cfg->line_buf_len < (uint16_t)k_ra8_modem_at_min_line_buf_bytes) {
    ra8_log_error(RA8_MODEM_AT_TAG, "line_buf too small");
    return k_ra8_err_invalid_size;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_modem_at_init(const ra8_modem_at_cfg_t* cfg)
{
  const ra8_err_t verr = internal_validate_init_cfg(cfg);
  if (verr != k_ra8_ok) {
    return verr;
  }
  s_mod.cfg         = *cfg;
  s_mod.line_len    = 0U;
  s_mod.state       = k_ra8_modem_at_state_idle;
  s_mod.initialized = 1U;
  internal_clear_urc_table();
  internal_reset_line();
  return k_ra8_ok;
}
 
ra8_err_t ra8_modem_at_send_cmd(const char* cmd, const char* expected_response, uint16_t timeout_ms)
{
  if (s_mod.initialized == 0U) {
    return k_ra8_err_not_initialized;
  }
  RA8_CHECK_NULL_PTR(cmd, RA8_MODEM_AT_TAG, "cmd");
 
  internal_reset_line();
  const ra8_err_t tx_err = internal_tx_command(cmd);
  if (tx_err != k_ra8_ok) {
    return tx_err;
  }
  return internal_wait_response(cmd,
                                expected_response,
                                internal_effective_timeout(timeout_ms),
                                nullptr,
                                0U);
}
 
ra8_err_t
ra8_modem_at_send_cmd_capture(const char* cmd, char* out_buf, size_t buf_len, uint16_t timeout_ms)
{
  if (s_mod.initialized == 0U) {
    return k_ra8_err_not_initialized;
  }
  RA8_CHECK_NULL_PTR(cmd, RA8_MODEM_AT_TAG, "cmd");
  RA8_CHECK_NULL_PTR(out_buf, RA8_MODEM_AT_TAG, "out_buf");
  if (buf_len == 0U) {
    return k_ra8_err_invalid_size;
  }
 
  out_buf[0] = '\0';
  internal_reset_line();
  const ra8_err_t tx_err = internal_tx_command(cmd);
  if (tx_err != k_ra8_ok) {
    return tx_err;
  }
  return internal_wait_response(cmd,
                                nullptr,
                                internal_effective_timeout(timeout_ms),
                                out_buf,
                                buf_len);
}

RA8_INTERNAL
static uint8_t internal_urc_replace(const char* prefix, ra8_modem_at_urc_fn_t fn, void* ctx)
{
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_modem_at_max_unsolicited; ++i) {
    if (s_mod.urcs[i].used == 0U) {
      continue;
    }
    if (priv_modem_str_eq((const char*)s_mod.urcs[i].prefix, prefix) != 0U) {
      s_mod.urcs[i].fn  = fn;
      s_mod.urcs[i].ctx = ctx;
      return 1U;
    }
  }
  return 0U;
}

RA8_INTERNAL
static uint8_t
internal_urc_insert(const char* prefix, uint16_t plen, ra8_modem_at_urc_fn_t fn, void* ctx)
{
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_modem_at_max_unsolicited; ++i) {
    if (s_mod.urcs[i].used != 0U) {
      continue;
    }
    uint16_t k = 0U;
    while (k < plen) {
      s_mod.urcs[i].prefix[k] = (uint8_t)prefix[k];
      ++k;
    }
    s_mod.urcs[i].prefix[plen] = (uint8_t)'\0';
    s_mod.urcs[i].fn           = fn;
    s_mod.urcs[i].ctx          = ctx;
    s_mod.urcs[i].used         = 1U;
    return 1U;
  }
  return 0U;
}
 
ra8_err_t
ra8_modem_at_register_unsolicited_handler(const char* prefix, ra8_modem_at_urc_fn_t fn, void* ctx)
{
  if (s_mod.initialized == 0U) {
    return k_ra8_err_not_initialized;
  }
  RA8_CHECK_NULL_PTR(prefix, RA8_MODEM_AT_TAG, "prefix");
  RA8_CHECK_NULL_PTR((void*)fn, RA8_MODEM_AT_TAG, "fn");
 
  const uint16_t plen = priv_modem_str_len(prefix);
  if ((plen == 0U) || (plen >= (uint16_t)k_ra8_modem_at_max_prefix_len)) {
    return k_ra8_err_invalid_size;
  }
 
  if (internal_urc_replace(prefix, fn, ctx) != 0U) {
    return k_ra8_ok;
  }
  if (internal_urc_insert(prefix, plen, fn, ctx) != 0U) {
    return k_ra8_ok;
  }
  return k_ra8_err_no_mem;
}
 
ra8_err_t ra8_modem_at_poll(void)
{
  if (s_mod.initialized == 0U) {
    return k_ra8_err_not_initialized;
  }
  while (1) {
    uint8_t         byte = 0U;
    const ra8_err_t err  = s_mod.cfg.io.rx_byte(s_mod.cfg.io.ctx, &byte);
    if (err != k_ra8_ok) {
      break;
    }
    const char* line = nullptr;
    internal_accumulate(byte, &line);
    if (line != nullptr) {
      const ra8_modem_line_kind_t kind = priv_modem_classify(line, nullptr, nullptr);
      (void)kind;
    }
  }
  return k_ra8_ok;
}