chat.h

Go to the documentation of this file.

/*
 * Copyright (c) 2022 Trackunit Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/device.h>
#include <zephyr/sys/ring_buffer.h>
 
#include <zephyr/modem/pipe.h>
#include <zephyr/modem/stats.h>
 
#ifndef ZEPHYR_MODEM_CHAT_
#define ZEPHYR_MODEM_CHAT_
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct modem_chat;
 
typedef void (*modem_chat_match_callback)(struct modem_chat *chat, char **argv, uint16_t argc,
 void *user_data);
 
struct modem_chat_match {
 const uint8_t *match;
 uint8_t match_size;
 const uint8_t *separators;
 uint8_t separators_size;
 uint8_t wildcards : 1;
 uint8_t partial : 1;
 modem_chat_match_callback callback;
};
 
#define MODEM_CHAT_MATCH(_match, _separators, _callback) \
 { \
 .match = (uint8_t *)(_match), .match_size = (uint8_t)(sizeof(_match) - 1), \
 .separators = (uint8_t *)(_separators), \
 .separators_size = (uint8_t)(sizeof(_separators) - 1), .wildcards = false, \
 .callback = _callback, \
 }
 
#define MODEM_CHAT_MATCH_WILDCARD(_match, _separators, _callback) \
 { \
 .match = (uint8_t *)(_match), .match_size = (uint8_t)(sizeof(_match) - 1), \
 .separators = (uint8_t *)(_separators), \
 .separators_size = (uint8_t)(sizeof(_separators) - 1), .wildcards = true, \
 .callback = _callback, \
 }
 
#define MODEM_CHAT_MATCH_INITIALIZER(_match, _separators, _callback, _wildcards, _partial) \
 { \
 .match = (uint8_t *)(_match), \
 .match_size = (uint8_t)(sizeof(_match) - 1), \
 .separators = (uint8_t *)(_separators), \
 .separators_size = (uint8_t)(sizeof(_separators) - 1), \
 .wildcards = _wildcards, \
 .partial = _partial, \
 .callback = _callback, \
 }
 
#define MODEM_CHAT_MATCH_DEFINE(_sym, _match, _separators, _callback) \
 const static struct modem_chat_match _sym = MODEM_CHAT_MATCH(_match, _separators, _callback)
 
/* Helper struct to match any response without callback. */
extern const struct modem_chat_match modem_chat_any_match;
 
#define MODEM_CHAT_MATCHES_DEFINE(_sym, ...) \
 const static struct modem_chat_match _sym[] = {__VA_ARGS__}
 
/* Helper struct to match nothing. */
extern const struct modem_chat_match modem_chat_empty_matches[0];
 
struct modem_chat_script_chat {
 const uint8_t *request;
 uint16_t request_size;
 const struct modem_chat_match *response_matches;
 uint16_t response_matches_size;
 uint16_t timeout;
};
 
#define MODEM_CHAT_SCRIPT_CMD_RESP(_request, _response_match) \
 { \
 .request = (uint8_t *)(_request), \
 .request_size = (uint16_t)(sizeof(_request) - 1), \
 .response_matches = &_response_match, \
 .response_matches_size = 1, \
 .timeout = 0, \
 }
 
#define MODEM_CHAT_SCRIPT_CMD_RESP_MULT(_request, _response_matches) \
 { \
 .request = (uint8_t *)(_request), \
 .request_size = (uint16_t)(sizeof(_request) - 1), \
 .response_matches = _response_matches, \
 .response_matches_size = ARRAY_SIZE(_response_matches), \
 .timeout = 0, \
 }
 
#define MODEM_CHAT_SCRIPT_CMD_RESP_NONE(_request, _timeout_ms) \
 { \
 .request = (uint8_t *)(_request), \
 .request_size = (uint16_t)(sizeof(_request) - 1), \
 .response_matches = NULL, \
 .response_matches_size = 0, \
 .timeout = _timeout_ms, \
 }
 
#define MODEM_CHAT_SCRIPT_CMDS_DEFINE(_sym, ...) \
 const struct modem_chat_script_chat _sym[] = {__VA_ARGS__}
 
/* Helper struct to have no chat script command. */
extern const struct modem_chat_script_chat modem_chat_empty_script_chats[0];
 
enum modem_chat_script_result {
 MODEM_CHAT_SCRIPT_RESULT_SUCCESS,
 MODEM_CHAT_SCRIPT_RESULT_ABORT,
 MODEM_CHAT_SCRIPT_RESULT_TIMEOUT
};
 
typedef void (*modem_chat_script_callback)(struct modem_chat *chat,
 enum modem_chat_script_result result, void *user_data);
 
struct modem_chat_script {
 const char *name;
 const struct modem_chat_script_chat *script_chats;
 uint16_t script_chats_size;
 const struct modem_chat_match *abort_matches;
 uint16_t abort_matches_size;
 modem_chat_script_callback callback;
 uint32_t timeout;
};
 
#define MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, _abort_matches, _callback, _timeout_s) \
 const static struct modem_chat_script _sym = { \
 .name = #_sym, \
 .script_chats = _script_chats, \
 .script_chats_size = ARRAY_SIZE(_script_chats), \
 .abort_matches = _abort_matches, \
 .abort_matches_size = ARRAY_SIZE(_abort_matches), \
 .callback = _callback, \
 .timeout = _timeout_s, \
 }
 
#define MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, _script_chats, _callback, _timeout_s) \
 MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, modem_chat_empty_matches, \
 _callback, _timeout_s)
 
#define MODEM_CHAT_SCRIPT_EMPTY_DEFINE(_sym) \
 MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, modem_chat_empty_script_chats, NULL, 0)
 
enum modem_chat_script_send_state {
 /* No data to send */
 MODEM_CHAT_SCRIPT_SEND_STATE_IDLE,
 /* Sending request */
 MODEM_CHAT_SCRIPT_SEND_STATE_REQUEST,
 /* Sending delimiter */
 MODEM_CHAT_SCRIPT_SEND_STATE_DELIMITER,
};
 
struct modem_chat {
 /* Pipe used to send and receive data */
 struct modem_pipe *pipe;
 
 /* User data passed with match callbacks */
 void *user_data;
 
 /* Receive buffer */
 uint8_t *receive_buf;
 uint16_t receive_buf_size;
 uint16_t receive_buf_len;
 
 /* Work buffer */
 uint8_t work_buf[32];
 uint16_t work_buf_len;
 
 /* Chat delimiter */
 uint8_t *delimiter;
 uint16_t delimiter_size;
 uint16_t delimiter_match_len;
 
 /* Array of bytes which are discarded out by parser */
 uint8_t *filter;
 uint16_t filter_size;
 
 /* Parsed arguments */
 uint8_t **argv;
 uint16_t argv_size;
 uint16_t argc;
 
 /* Matches
 * Index 0 -> Response matches
 * Index 1 -> Abort matches
 * Index 2 -> Unsolicited matches
 */
 const struct modem_chat_match *matches[3];
 uint16_t matches_size[3];
 
 /* Script execution */
 const struct modem_chat_script *script;
 const struct modem_chat_script *pending_script;
 struct k_work script_run_work;
 struct k_work_delayable script_timeout_work;
 struct k_work script_abort_work;
 uint16_t script_chat_it;
 atomic_t script_state;
 enum modem_chat_script_result script_result;
 struct k_sem script_stopped_sem;
 
 /* Script sending */
 enum modem_chat_script_send_state script_send_state;
 uint16_t script_send_pos;
 struct k_work script_send_work;
 struct k_work_delayable script_send_timeout_work;
 
 /* Match parsing */
 const struct modem_chat_match *parse_match;
 uint16_t parse_match_len;
 uint16_t parse_arg_len;
 uint16_t parse_match_type;
 
 /* Process received data */
 struct k_work receive_work;
 
 /* Statistics */
#if CONFIG_MODEM_STATS
 struct modem_stats_buffer receive_buf_stats;
 struct modem_stats_buffer work_buf_stats;
#endif
};
 
struct modem_chat_config {
 void *user_data;
 uint8_t *receive_buf;
 uint16_t receive_buf_size;
 uint8_t *delimiter;
 uint8_t delimiter_size;
 uint8_t *filter;
 uint8_t filter_size;
 uint8_t **argv;
 uint16_t argv_size;
 const struct modem_chat_match *unsol_matches;
 uint16_t unsol_matches_size;
};
 
int modem_chat_init(struct modem_chat *chat, const struct modem_chat_config *config);
 
int modem_chat_attach(struct modem_chat *chat, struct modem_pipe *pipe);
 
int modem_chat_run_script_async(struct modem_chat *chat, const struct modem_chat_script *script);
 
int modem_chat_run_script(struct modem_chat *chat, const struct modem_chat_script *script);
 
static inline int modem_chat_script_run(struct modem_chat *chat,
 const struct modem_chat_script *script)
{
 return modem_chat_run_script_async(chat, script);
}
 
void modem_chat_script_abort(struct modem_chat *chat);
 
void modem_chat_release(struct modem_chat *chat);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_MODEM_CHAT_ */