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_INCLUDE_MODEM_CHAT_H_
#define ZEPHYR_INCLUDE_MODEM_CHAT_H_
 
#ifdef __cplusplus
extern "C" {
#endif

 
struct modem_chat;
struct modem_chat_script;

typedef bool (*modem_chat_run_check)(void *user_data);

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;
        const uint8_t *separators;
        modem_chat_match_callback callback;
        uint8_t match_size;
        uint8_t separators_size;
        bool wildcards;
        bool partial;
};
 
#define MODEM_CHAT_MATCH(_match, _separators, _callback)                                           \
        {                                                                                          \
                .match = (uint8_t *)(_match),                                                      \
                .separators = (uint8_t *)(_separators),                                            \
                .match_size = (uint8_t)(sizeof(_match) - 1),                                       \
                .separators_size = (uint8_t)(sizeof(_separators) - 1),                             \
                .wildcards = false,                                                                \
                .callback = _callback,                                                             \
        }
 
#define MODEM_CHAT_MATCH_WILDCARD(_match, _separators, _callback)                                  \
        {                                                                                          \
                .match = (uint8_t *)(_match),                                                      \
                .separators = (uint8_t *)(_separators),                                            \
                .match_size = (uint8_t)(sizeof(_match) - 1),                                       \
                .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),                                                      \
                .separators = (uint8_t *)(_separators),                                            \
                .match_size = (uint8_t)(sizeof(_match) - 1),                                       \
                .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)
 
#define MODEM_CHAT_MATCH_WILDCARD_DEFINE(_sym, _match, _separators, _callback)                     \
        const static struct modem_chat_match _sym =                                                \
                MODEM_CHAT_MATCH_WILDCARD(_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;
#if defined(CONFIG_MODEM_CHAT_COMMANDS_CONDITIONAL) || defined(__DOXYGEN__)
        modem_chat_run_check run_check;
#endif
};

#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_CMD_RESP_COND(_request, _response_match, _run_check)                     \
        {                                                                                          \
                .request = (uint8_t *)(_request),                                                  \
                .request_size = (uint16_t)(sizeof(_request) - 1),                                  \
                .response_matches = &_response_match,                                              \
                .response_matches_size = 1,                                                        \
                .timeout = 0,                                                                      \
                .run_check = _run_check                                                            \
        }

#define MODEM_CHAT_SCRIPT_CMD_RESP_MULT_COND(_request, _response_matches, _run_check)              \
        {                                                                                          \
                .request = (uint8_t *)(_request),                                                  \
                .request_size = (uint16_t)(sizeof(_request) - 1),                                  \
                .response_matches = _response_matches,                                             \
                .response_matches_size = ARRAY_SIZE(_response_matches),                            \
                .timeout = 0,                                                                      \
                .run_check = _run_check                                                            \
        }

#define MODEM_CHAT_SCRIPT_CMD_RESP_NONE_COND(_request, _timeout_ms, _run_check)                    \
        {                                                                                          \
                .request = (uint8_t *)(_request),                                                  \
                .request_size = (uint16_t)(sizeof(_request) - 1),                                  \
                .response_matches = NULL,                                                          \
                .response_matches_size = 0,                                                        \
                .timeout = _timeout_ms,                                                            \
                .run_check = _run_check                                                            \
        }

#define MODEM_CHAT_SCRIPT_CMDS_DEFINE(_sym, ...)                                                   \
        const static 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
};

struct modem_chat_script_completion_info {
        const struct modem_chat_script *script;
        const struct modem_chat_script_chat *script_chat;
};

typedef void (*modem_chat_script_callback)(struct modem_chat *chat,
                                           enum modem_chat_script_result result,
                                           const struct modem_chat_script_completion_info *info,
                                           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,
};

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[CONFIG_MODEM_CHAT_WORK_BUFFER_SIZE];
        uint16_t work_buf_len;
 
        /* Chat delimiter */
        const uint8_t *delimiter;
        uint16_t delimiter_size;
        uint16_t delimiter_match_len;
 
        /* Array of bytes which are discarded out by parser */
        const 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;
#if defined(CONFIG_MODEM_CHAT_LOG_RAW_RX)
        uint8_t raw_log_separators[CONFIG_MODEM_CHAT_LOG_BUFFER_SIZE];
        uint16_t raw_log_separators_len;
#endif
 
        /* 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;
        const uint8_t *delimiter;
        uint8_t delimiter_size;
        const 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);

bool modem_chat_is_running(struct modem_chat *chat);

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);

void modem_chat_match_init(struct modem_chat_match *chat_match);

int modem_chat_match_set_match(struct modem_chat_match *chat_match, const char *match);

int modem_chat_match_set_separators(struct modem_chat_match *chat_match, const char *separators);

void modem_chat_match_set_callback(struct modem_chat_match *chat_match,
                                   modem_chat_match_callback callback);

void modem_chat_match_set_partial(struct modem_chat_match *chat_match, bool partial);

void modem_chat_match_enable_wildcards(struct modem_chat_match *chat_match, bool enable);

void modem_chat_script_chat_init(struct modem_chat_script_chat *script_chat);

int modem_chat_script_chat_set_request(struct modem_chat_script_chat *script_chat,
                                       const char *request);

int modem_chat_script_chat_set_response_matches(struct modem_chat_script_chat *script_chat,
                                                const struct modem_chat_match *response_matches,
                                                uint16_t response_matches_size);

void modem_chat_script_chat_set_timeout(struct modem_chat_script_chat *script_chat,
                                        uint16_t timeout_ms);

void modem_chat_script_init(struct modem_chat_script *script);

void modem_chat_script_set_name(struct modem_chat_script *script, const char *name);

int modem_chat_script_set_script_chats(struct modem_chat_script *script,
                                       const struct modem_chat_script_chat *script_chats,
                                       uint16_t script_chats_size);

int modem_chat_script_set_abort_matches(struct modem_chat_script *script,
                                        const struct modem_chat_match *abort_matches,
                                        uint16_t abort_matches_size);

void modem_chat_script_set_callback(struct modem_chat_script *script,
                                    modem_chat_script_callback callback);

void modem_chat_script_set_timeout(struct modem_chat_script *script, uint32_t timeout_s);

 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_MODEM_CHAT_H_ */