chat.h File Reference

#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>

Go to the source code of this file.

Data Structures
struct	modem_chat_match
	Modem chat match. More...
struct	modem_chat_script_chat
	Modem chat script chat. More...
struct	modem_chat_script
	Modem chat script. More...
struct	modem_chat
	Chat instance internal context. More...
struct	modem_chat_config
	Chat configuration. More...

Macros
#define	MODEM_CHAT_MATCH(_match, _separators, _callback)
#define	MODEM_CHAT_MATCH_WILDCARD(_match, _separators, _callback)
#define	MODEM_CHAT_MATCH_INITIALIZER(_match, _separators, _callback, _wildcards, _partial)
#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_MATCHES_DEFINE(_sym, ...)    const static struct modem_chat_match _sym[] = {__VA_ARGS__}
#define	MODEM_CHAT_SCRIPT_CMD_RESP(_request, _response_match)
#define	MODEM_CHAT_SCRIPT_CMD_RESP_MULT(_request, _response_matches)
#define	MODEM_CHAT_SCRIPT_CMD_RESP_NONE(_request, _timeout_ms)
#define	MODEM_CHAT_SCRIPT_CMDS_DEFINE(_sym, ...)    const struct modem_chat_script_chat _sym[] = {__VA_ARGS__}
#define	MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, _abort_matches, _callback, _timeout_s)
#define	MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, _script_chats, _callback, _timeout_s)
#define	MODEM_CHAT_SCRIPT_EMPTY_DEFINE(_sym)    MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, modem_chat_empty_script_chats, NULL, 0)

Typedefs
typedef void(*	modem_chat_match_callback) (struct modem_chat *chat, char **argv, uint16_t argc, void *user_data)
	Callback called when matching chat is received.
typedef void(*	modem_chat_script_callback) (struct modem_chat *chat, enum modem_chat_script_result result, void *user_data)
	Callback called when script chat is received.

Enumerations
enum	modem_chat_script_result { MODEM_CHAT_SCRIPT_RESULT_SUCCESS , MODEM_CHAT_SCRIPT_RESULT_ABORT , MODEM_CHAT_SCRIPT_RESULT_TIMEOUT }
enum	modem_chat_script_send_state { MODEM_CHAT_SCRIPT_SEND_STATE_IDLE , MODEM_CHAT_SCRIPT_SEND_STATE_REQUEST , MODEM_CHAT_SCRIPT_SEND_STATE_DELIMITER }

Functions
int	modem_chat_init (struct modem_chat *chat, const struct modem_chat_config *config)
	Initialize modem pipe chat instance.
int	modem_chat_attach (struct modem_chat *chat, struct modem_pipe *pipe)
	Attach modem chat instance to pipe.
int	modem_chat_run_script_async (struct modem_chat *chat, const struct modem_chat_script *script)
	Run script asynchronously.
int	modem_chat_run_script (struct modem_chat *chat, const struct modem_chat_script *script)
	Run script.
static int	modem_chat_script_run (struct modem_chat *chat, const struct modem_chat_script *script)
	Run script asynchronously.
void	modem_chat_script_abort (struct modem_chat *chat)
	Abort script.
void	modem_chat_release (struct modem_chat *chat)
	Release pipe from chat instance.
void	modem_chat_match_init (struct modem_chat_match *chat_match)
	Initialize modem chat match.
int	modem_chat_match_set_match (struct modem_chat_match *chat_match, const char *match)
	Set match of modem chat match instance.
int	modem_chat_match_set_separators (struct modem_chat_match *chat_match, const char *separators)
	Set separators of modem chat match instance.
void	modem_chat_match_set_callback (struct modem_chat_match *chat_match, modem_chat_match_callback callback)
	Set modem chat match callback.
void	modem_chat_match_set_partial (struct modem_chat_match *chat_match, bool partial)
	Set modem chat match partial flag.
void	modem_chat_match_enable_wildcards (struct modem_chat_match *chat_match, bool enable)
	Set modem chat match wildcards flag.
void	modem_chat_script_chat_init (struct modem_chat_script_chat *script_chat)
	Initialize modem chat script chat.
int	modem_chat_script_chat_set_request (struct modem_chat_script_chat *script_chat, const char *request)
	Set request of modem chat script chat instance.
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)
	Set modem chat script chat matches.
void	modem_chat_script_chat_set_timeout (struct modem_chat_script_chat *script_chat, uint16_t timeout_ms)
	Set modem chat script chat timeout.
void	modem_chat_script_init (struct modem_chat_script *script)
	Initialize modem chat script.
void	modem_chat_script_set_name (struct modem_chat_script *script, const char *name)
	Set modem chat script 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)
	Set modem chat script chats.
int	modem_chat_script_set_abort_matches (struct modem_chat_script *script, const struct modem_chat_match *abort_matches, uint16_t abort_matches_size)
	Set modem chat script abort matches.
void	modem_chat_script_set_callback (struct modem_chat_script *script, modem_chat_script_callback callback)
	Set modem chat script callback.
void	modem_chat_script_set_timeout (struct modem_chat_script *script, uint32_t timeout_s)
	Set modem chat script timeout.

Variables
const struct modem_chat_match	modem_chat_any_match
const struct modem_chat_match	modem_chat_empty_matches [0]
const struct modem_chat_script_chat	modem_chat_empty_script_chats [0]

Macro Definition Documentation

MODEM_CHAT_MATCH

#define MODEM_CHAT_MATCH	(		_match,
			_separators,
			_callback
	)

Value:

        {                                                                                          \
                .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,                                                             \
        }

MODEM_CHAT_MATCH_DEFINE

#define MODEM_CHAT_MATCH_DEFINE	(		_sym,
			_match,
			_separators,
			_callback
	)		const static struct modem_chat_match _sym = MODEM_CHAT_MATCH(_match, _separators, _callback)

MODEM_CHAT_MATCH_INITIALIZER

#define MODEM_CHAT_MATCH_INITIALIZER	(		_match,
			_separators,
			_callback,
			_wildcards,
			_partial
	)

Value:

        {                                                                                          \
                .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,                                                             \
        }

MODEM_CHAT_MATCH_WILDCARD

#define MODEM_CHAT_MATCH_WILDCARD	(		_match,
			_separators,
			_callback
	)

Value:

        {                                                                                          \
                .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,                                                             \
        }

MODEM_CHAT_MATCHES_DEFINE

#define MODEM_CHAT_MATCHES_DEFINE	(		_sym,
			...
	)		const static struct modem_chat_match _sym[] = {__VA_ARGS__}

MODEM_CHAT_SCRIPT_CMD_RESP

#define MODEM_CHAT_SCRIPT_CMD_RESP	(		_request,
			_response_match
	)

Value:

        {                                                                                          \
                .request = (uint8_t *)(_request),                                                  \
                .request_size = (uint16_t)(sizeof(_request) - 1),                                  \
                .response_matches = &_response_match,                                              \
                .response_matches_size = 1,                                                        \
                .timeout = 0,                                                                      \
        }

MODEM_CHAT_SCRIPT_CMD_RESP_MULT

#define MODEM_CHAT_SCRIPT_CMD_RESP_MULT	(		_request,
			_response_matches
	)

Value:

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

MODEM_CHAT_SCRIPT_CMD_RESP_NONE

#define MODEM_CHAT_SCRIPT_CMD_RESP_NONE	(		_request,
			_timeout_ms
	)

Value:

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

MODEM_CHAT_SCRIPT_CMDS_DEFINE

#define MODEM_CHAT_SCRIPT_CMDS_DEFINE	(		_sym,
			...
	)		const struct modem_chat_script_chat _sym[] = {__VA_ARGS__}

MODEM_CHAT_SCRIPT_DEFINE

#define MODEM_CHAT_SCRIPT_DEFINE	(		_sym,
			_script_chats,
			_abort_matches,
			_callback,
			_timeout_s
	)

Value:

        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,                                                             \
        }

MODEM_CHAT_SCRIPT_EMPTY_DEFINE

#define MODEM_CHAT_SCRIPT_EMPTY_DEFINE

(

_sym

)

MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, modem_chat_empty_script_chats, NULL, 0)

MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE

#define MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE	(		_sym,
			_script_chats,
			_callback,
			_timeout_s
	)

Value:

        MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, modem_chat_empty_matches,                    \
                                 _callback, _timeout_s)

Typedef Documentation

modem_chat_match_callback

typedef void(* modem_chat_match_callback) (struct modem_chat *chat, char **argv, uint16_t argc, void *user_data)

Callback called when matching chat is received.

Parameters

chat	Pointer to chat instance instance
argv	Pointer to array of parsed arguments
argc	Number of parsed arguments, arg 0 holds the exact match
user_data	Free to use user data set during modem_chat_init()

modem_chat_script_callback

typedef void(* modem_chat_script_callback) (struct modem_chat *chat, enum modem_chat_script_result result, void *user_data)

Callback called when script chat is received.

Parameters

chat	Pointer to chat instance instance
result	Result of script execution
user_data	Free to use user data set during modem_chat_init()

Enumeration Type Documentation

modem_chat_script_result

enum modem_chat_script_result

Enumerator
MODEM_CHAT_SCRIPT_RESULT_SUCCESS
MODEM_CHAT_SCRIPT_RESULT_ABORT
MODEM_CHAT_SCRIPT_RESULT_TIMEOUT

modem_chat_script_send_state

enum modem_chat_script_send_state

Enumerator
MODEM_CHAT_SCRIPT_SEND_STATE_IDLE
MODEM_CHAT_SCRIPT_SEND_STATE_REQUEST
MODEM_CHAT_SCRIPT_SEND_STATE_DELIMITER

Function Documentation

modem_chat_attach()

int modem_chat_attach	(	struct modem_chat *	chat,
		struct modem_pipe *	pipe
	)

Attach modem chat instance to pipe.

Parameters

chat	Chat instance
pipe	Pipe instance to attach Chat instance to

Returns

0 if successful

negative errno code if failure

Note

Chat instance is enabled if successful

modem_chat_init()

int modem_chat_init	(	struct modem_chat *	chat,
		const struct modem_chat_config *	config
	)

Initialize modem pipe chat instance.

Parameters

chat	Chat instance
config	Configuration which shall be applied to Chat instance

Note

Chat instance must be attached to pipe

modem_chat_match_enable_wildcards()

void modem_chat_match_enable_wildcards	(	struct modem_chat_match *	chat_match,
		bool	enable
	)

Set modem chat match wildcards flag.

Parameters

chat_match	Modem chat match instance
enable	Enable/disable Wildcards

modem_chat_match_init()

void modem_chat_match_init

(

struct modem_chat_match *

chat_match

)

Initialize modem chat match.

Parameters

chat_match

Modem chat match instance

modem_chat_match_set_callback()

void modem_chat_match_set_callback	(	struct modem_chat_match *	chat_match,
		modem_chat_match_callback	callback
	)

Set modem chat match callback.

Parameters

chat_match	Modem chat match instance
callback	Callback to set

modem_chat_match_set_match()

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

Set match of modem chat match instance.

Parameters

chat_match	Modem chat match instance
match	Match to set

Note

The lifetime of match must match or exceed the lifetime of chat_match

Warning

Always call this API after match is modified

Return values

0	if successful, negative errno code otherwise

modem_chat_match_set_partial()

void modem_chat_match_set_partial	(	struct modem_chat_match *	chat_match,
		bool	partial
	)

Set modem chat match partial flag.

Parameters

chat_match	Modem chat match instance
partial	Partial flag to set

modem_chat_match_set_separators()

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

Set separators of modem chat match instance.

Parameters

chat_match	Modem chat match instance
separators	Separators to set

Note

The lifetime of separators must match or exceed the lifetime of chat_match

Warning

Always call this API after separators are modified

Return values

0	if successful, negative errno code otherwise

modem_chat_release()

void modem_chat_release

(

struct modem_chat *

chat

)

Release pipe from chat instance.

Parameters

chat	Chat instance

modem_chat_run_script()

int modem_chat_run_script	(	struct modem_chat *	chat,
		const struct modem_chat_script *	script
	)

Run script.

Parameters

chat	Chat instance
script	Script to run

Returns

0 if successful

-EBUSY if a script is currently running

-EPERM if modem pipe is not attached

-EINVAL if arguments or script is invalid

Note

Script runs until complete or aborted.

modem_chat_run_script_async()

int modem_chat_run_script_async	(	struct modem_chat *	chat,
		const struct modem_chat_script *	script
	)

Run script asynchronously.

Parameters

chat	Chat instance
script	Script to run

Returns

0 if script successfully started

-EBUSY if a script is currently running

-EPERM if modem pipe is not attached

-EINVAL if arguments or script is invalid

Note

Script runs asynchronously until complete or aborted.

modem_chat_script_abort()

void modem_chat_script_abort

(

struct modem_chat *

chat

)

Abort script.

Parameters

chat	Chat instance

modem_chat_script_chat_init()

void modem_chat_script_chat_init

(

struct modem_chat_script_chat *

script_chat

)

Initialize modem chat script chat.

Parameters

script_chat

Modem chat script chat instance

modem_chat_script_chat_set_request()

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

Set request of modem chat script chat instance.

Parameters

script_chat	Modem chat script chat instance
request	Request to set

Note

The lifetime of request must match or exceed the lifetime of script_chat

Warning

Always call this API after request is modified

Return values

0	if successful, negative errno code otherwise

modem_chat_script_chat_set_response_matches()

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
	)

Set modem chat script chat matches.

Parameters

script_chat	Modem chat script chat instance
response_matches	Response match array to set
response_matches_size	Size of response match array

Note

The lifetime of response_matches must match or exceed the lifetime of script_chat

Return values

0	if successful, negative errno code otherwise

modem_chat_script_chat_set_timeout()

void modem_chat_script_chat_set_timeout	(	struct modem_chat_script_chat *	script_chat,
		uint16_t	timeout_ms
	)

Set modem chat script chat timeout.

Parameters

script_chat	Modem chat script chat instance
timeout_ms	Timeout in milliseconds

modem_chat_script_init()

void modem_chat_script_init

(

struct modem_chat_script *

script

)

Initialize modem chat script.

Parameters

script

Modem chat script instance

modem_chat_script_run()

static int modem_chat_script_run ( struct modem_chat *  chat, const struct modem_chat_script *  script  )

inlinestatic

Run script asynchronously.

Note

Function exists for backwards compatibility and should be deprecated

Parameters

chat	Chat instance
script	Script to run

Returns

0 if script successfully started

-EBUSY if a script is currently running

-EPERM if modem pipe is not attached

-EINVAL if arguments or script is invalid

modem_chat_script_set_abort_matches()

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

Set modem chat script abort matches.

Parameters

script	Modem chat script instance
abort_matches	Abort match array to set
abort_matches_size	Size of abort match array

Note

The lifetime of abort_matches must match or exceed the lifetime of script

Return values

0	if successful, negative errno code otherwise

modem_chat_script_set_callback()

void modem_chat_script_set_callback	(	struct modem_chat_script *	script,
		modem_chat_script_callback	callback
	)

Set modem chat script callback.

Parameters

script	Modem chat script instance
callback	Callback to set

modem_chat_script_set_name()

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

Set modem chat script name.

Parameters

script	Modem chat script instance
name	Name to set

Note

The lifetime of name must match or exceed the lifetime of script

modem_chat_script_set_script_chats()

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
	)

Set modem chat script chats.

Parameters

script	Modem chat script instance
script_chats	Chat script array to set
script_chats_size	Size of chat script array

Note

The lifetime of script_chats must match or exceed the lifetime of script

Return values

0	if successful, negative errno code otherwise

modem_chat_script_set_timeout()

void modem_chat_script_set_timeout	(	struct modem_chat_script *	script,
		uint32_t	timeout_s
	)

Set modem chat script timeout.

Parameters

script	Modem chat script instance
timeout_s	Timeout in seconds

Variable Documentation

modem_chat_any_match

const struct modem_chat_match modem_chat_any_match

extern

modem_chat_empty_matches

const struct modem_chat_match modem_chat_empty_matches[0]

extern

modem_chat_empty_script_chats

const struct modem_chat_script_chat modem_chat_empty_script_chats[0]

extern