Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
chat.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2022 Trackunit Corporation
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7#include <zephyr/kernel.h>
8#include <zephyr/types.h>
9#include <zephyr/device.h>
11
12#include <zephyr/modem/pipe.h>
13#include <zephyr/modem/stats.h>
14
15#ifndef ZEPHYR_MODEM_CHAT_
16#define ZEPHYR_MODEM_CHAT_
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
30
31struct modem_chat;
32
41typedef void (*modem_chat_match_callback)(struct modem_chat *chat, char **argv, uint16_t argc,
42 void *user_data);
43
63
64#define MODEM_CHAT_MATCH(_match, _separators, _callback) \
65 { \
66 .match = (uint8_t *)(_match), .match_size = (uint8_t)(sizeof(_match) - 1), \
67 .separators = (uint8_t *)(_separators), \
68 .separators_size = (uint8_t)(sizeof(_separators) - 1), .wildcards = false, \
69 .callback = _callback, \
70 }
71
72#define MODEM_CHAT_MATCH_WILDCARD(_match, _separators, _callback) \
73 { \
74 .match = (uint8_t *)(_match), .match_size = (uint8_t)(sizeof(_match) - 1), \
75 .separators = (uint8_t *)(_separators), \
76 .separators_size = (uint8_t)(sizeof(_separators) - 1), .wildcards = true, \
77 .callback = _callback, \
78 }
79
80#define MODEM_CHAT_MATCH_INITIALIZER(_match, _separators, _callback, _wildcards, _partial) \
81 { \
82 .match = (uint8_t *)(_match), \
83 .match_size = (uint8_t)(sizeof(_match) - 1), \
84 .separators = (uint8_t *)(_separators), \
85 .separators_size = (uint8_t)(sizeof(_separators) - 1), \
86 .wildcards = _wildcards, \
87 .partial = _partial, \
88 .callback = _callback, \
89 }
90
91#define MODEM_CHAT_MATCH_DEFINE(_sym, _match, _separators, _callback) \
92 const static struct modem_chat_match _sym = MODEM_CHAT_MATCH(_match, _separators, _callback)
93
94/* Helper struct to match any response without callback. */
95extern const struct modem_chat_match modem_chat_any_match;
96
97#define MODEM_CHAT_MATCHES_DEFINE(_sym, ...) \
98 const static struct modem_chat_match _sym[] = {__VA_ARGS__}
99
100/* Helper struct to match nothing. */
101extern const struct modem_chat_match modem_chat_empty_matches[0];
102
118
119#define MODEM_CHAT_SCRIPT_CMD_RESP(_request, _response_match) \
120 { \
121 .request = (uint8_t *)(_request), \
122 .request_size = (uint16_t)(sizeof(_request) - 1), \
123 .response_matches = &_response_match, \
124 .response_matches_size = 1, \
125 .timeout = 0, \
126 }
127
128#define MODEM_CHAT_SCRIPT_CMD_RESP_MULT(_request, _response_matches) \
129 { \
130 .request = (uint8_t *)(_request), \
131 .request_size = (uint16_t)(sizeof(_request) - 1), \
132 .response_matches = _response_matches, \
133 .response_matches_size = ARRAY_SIZE(_response_matches), \
134 .timeout = 0, \
135 }
136
137#define MODEM_CHAT_SCRIPT_CMD_RESP_NONE(_request, _timeout_ms) \
138 { \
139 .request = (uint8_t *)(_request), \
140 .request_size = (uint16_t)(sizeof(_request) - 1), \
141 .response_matches = NULL, \
142 .response_matches_size = 0, \
143 .timeout = _timeout_ms, \
144 }
145
146#define MODEM_CHAT_SCRIPT_CMDS_DEFINE(_sym, ...) \
147 const static struct modem_chat_script_chat _sym[] = {__VA_ARGS__}
148
149/* Helper struct to have no chat script command. */
151
157
165typedef void (*modem_chat_script_callback)(struct modem_chat *chat,
166 enum modem_chat_script_result result, void *user_data);
167
187
188#define MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, _abort_matches, _callback, _timeout_s) \
189 const static struct modem_chat_script _sym = { \
190 .name = #_sym, \
191 .script_chats = _script_chats, \
192 .script_chats_size = ARRAY_SIZE(_script_chats), \
193 .abort_matches = _abort_matches, \
194 .abort_matches_size = ARRAY_SIZE(_abort_matches), \
195 .callback = _callback, \
196 .timeout = _timeout_s, \
197 }
198
199#define MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, _script_chats, _callback, _timeout_s) \
200 MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, modem_chat_empty_matches, \
201 _callback, _timeout_s)
202
203#define MODEM_CHAT_SCRIPT_EMPTY_DEFINE(_sym) \
204 MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, modem_chat_empty_script_chats, NULL, 0)
205
214
220 /* Pipe used to send and receive data */
221 struct modem_pipe *pipe;
222
223 /* User data passed with match callbacks */
225
226 /* Receive buffer */
230
231 /* Work buffer */
234
235 /* Chat delimiter */
239
240 /* Array of bytes which are discarded out by parser */
243
244 /* Parsed arguments */
248
249 /* Matches
250 * Index 0 -> Response matches
251 * Index 1 -> Abort matches
252 * Index 2 -> Unsolicited matches
253 */
254 const struct modem_chat_match *matches[3];
256
257 /* Script execution */
267
268 /* Script sending */
273
274 /* Match parsing */
279
280 /* Process received data */
282
283 /* Statistics */
284#if CONFIG_MODEM_STATS
285 struct modem_stats_buffer receive_buf_stats;
286 struct modem_stats_buffer work_buf_stats;
287#endif
288};
289
317
324int modem_chat_init(struct modem_chat *chat, const struct modem_chat_config *config);
325
334int modem_chat_attach(struct modem_chat *chat, struct modem_pipe *pipe);
335
346int modem_chat_run_script_async(struct modem_chat *chat, const struct modem_chat_script *script);
347
358int modem_chat_run_script(struct modem_chat *chat, const struct modem_chat_script *script);
359
370static inline int modem_chat_script_run(struct modem_chat *chat,
371 const struct modem_chat_script *script)
372{
373 return modem_chat_run_script_async(chat, script);
374}
375
381
387
393
403int modem_chat_match_set_match(struct modem_chat_match *chat_match, const char *match);
404
415
423
430
436void modem_chat_match_enable_wildcards(struct modem_chat_match *chat_match, bool enable);
437
443
454 const char *request);
455
466 const struct modem_chat_match *response_matches,
467 uint16_t response_matches_size);
468
475 uint16_t timeout_ms);
476
482
489void modem_chat_script_set_name(struct modem_chat_script *script, const char *name);
490
501 const struct modem_chat_script_chat *script_chats,
502 uint16_t script_chats_size);
503
514 const struct modem_chat_match *abort_matches,
515 uint16_t abort_matches_size);
516
524
531
535
536#ifdef __cplusplus
537}
538#endif
539
540#endif /* ZEPHYR_MODEM_CHAT_ */
long atomic_t
Definition atomic_types.h:15
const struct modem_chat_script_chat modem_chat_empty_script_chats[0]
void modem_chat_match_init(struct modem_chat_match *chat_match)
Initialize modem chat match.
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_match_enable_wildcards(struct modem_chat_match *chat_match, bool enable)
Set modem chat match wildcards flag.
int modem_chat_match_set_separators(struct modem_chat_match *chat_match, const char *separators)
Set separators of modem chat match instance.
int modem_chat_run_script_async(struct modem_chat *chat, const struct modem_chat_script *script)
Run script asynchronously.
modem_chat_script_result
Definition chat.h:152
void modem_chat_script_set_callback(struct modem_chat_script *script, modem_chat_script_callback callback)
Set modem chat script callback.
void modem_chat_match_set_partial(struct modem_chat_match *chat_match, bool partial)
Set modem chat match partial flag.
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_script_callback)(struct modem_chat *chat, enum modem_chat_script_result result, void *user_data)
Callback called when script chat is received.
Definition chat.h:165
modem_chat_script_send_state
Definition chat.h:206
void modem_chat_script_set_timeout(struct modem_chat_script *script, uint32_t timeout_s)
Set modem chat script timeout.
void modem_chat_script_set_name(struct modem_chat_script *script, const char *name)
Set modem chat script name.
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.
static int modem_chat_script_run(struct modem_chat *chat, const struct modem_chat_script *script)
Run script asynchronously.
Definition chat.h:370
const struct modem_chat_match modem_chat_empty_matches[0]
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_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.
const struct modem_chat_match modem_chat_any_match
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.
void modem_chat_script_chat_set_timeout(struct modem_chat_script_chat *script_chat, uint16_t timeout_ms)
Set modem chat script chat timeout.
int modem_chat_run_script(struct modem_chat *chat, const struct modem_chat_script *script)
Run script.
void(* modem_chat_match_callback)(struct modem_chat *chat, char **argv, uint16_t argc, void *user_data)
Callback called when matching chat is received.
Definition chat.h:41
void modem_chat_script_chat_init(struct modem_chat_script_chat *script_chat)
Initialize modem chat script chat.
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.
void modem_chat_script_init(struct modem_chat_script *script)
Initialize modem chat script.
void modem_chat_match_set_callback(struct modem_chat_match *chat_match, modem_chat_match_callback callback)
Set modem chat match callback.
@ MODEM_CHAT_SCRIPT_RESULT_TIMEOUT
Definition chat.h:155
@ MODEM_CHAT_SCRIPT_RESULT_SUCCESS
Definition chat.h:153
@ MODEM_CHAT_SCRIPT_RESULT_ABORT
Definition chat.h:154
@ MODEM_CHAT_SCRIPT_SEND_STATE_REQUEST
Definition chat.h:210
@ MODEM_CHAT_SCRIPT_SEND_STATE_IDLE
Definition chat.h:208
@ MODEM_CHAT_SCRIPT_SEND_STATE_DELIMITER
Definition chat.h:212
Public kernel APIs.
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
Semaphore structure.
Definition kernel.h:3275
A structure used to submit work after a delay.
Definition kernel.h:4192
A structure used to submit work.
Definition kernel.h:4164
Chat configuration.
Definition chat.h:293
uint8_t * receive_buf
Receive buffer used to store parsed arguments.
Definition chat.h:297
uint16_t argv_size
Elements in array of pointers.
Definition chat.h:311
const struct modem_chat_match * unsol_matches
Array of unsolicited matches.
Definition chat.h:313
uint16_t receive_buf_size
Size of receive buffer should be longest line + longest match.
Definition chat.h:299
uint8_t delimiter_size
Size of delimiter.
Definition chat.h:303
uint8_t * delimiter
Delimiter.
Definition chat.h:301
void * user_data
Free to use user data passed with modem match callbacks.
Definition chat.h:295
uint16_t unsol_matches_size
Elements in array of unsolicited matches.
Definition chat.h:315
uint8_t ** argv
Array of pointers used to point to parsed arguments.
Definition chat.h:309
uint8_t * filter
Bytes which are discarded by parser.
Definition chat.h:305
uint8_t filter_size
Size of filter.
Definition chat.h:307
Modem chat match.
Definition chat.h:47
modem_chat_match_callback callback
Type of modem chat instance.
Definition chat.h:61
uint8_t separators_size
Size of separators array.
Definition chat.h:55
const uint8_t * separators
Separators array.
Definition chat.h:53
bool partial
Set if script shall not continue to next step in case of match.
Definition chat.h:59
const uint8_t * match
Match array.
Definition chat.h:49
bool wildcards
Set if modem chat instance shall use wildcards when matching.
Definition chat.h:57
uint8_t match_size
Size of match.
Definition chat.h:51
Modem chat script chat.
Definition chat.h:106
uint16_t timeout
Timeout before chat script may continue to next step in milliseconds.
Definition chat.h:116
const struct modem_chat_match * response_matches
Expected responses to request.
Definition chat.h:112
const uint8_t * request
Request to send to modem.
Definition chat.h:108
uint16_t request_size
Size of request.
Definition chat.h:110
uint16_t response_matches_size
Number of elements in expected responses.
Definition chat.h:114
Modem chat script.
Definition chat.h:171
uint32_t timeout
Timeout in seconds within which the script execution must terminate.
Definition chat.h:185
const struct modem_chat_match * abort_matches
Array of abort matches.
Definition chat.h:179
uint16_t script_chats_size
Elements in array of script chats.
Definition chat.h:177
const struct modem_chat_script_chat * script_chats
Array of script chats.
Definition chat.h:175
modem_chat_script_callback callback
Callback called when script execution terminates.
Definition chat.h:183
uint16_t abort_matches_size
Number of elements in array of abort matches.
Definition chat.h:181
const char * name
Name of script.
Definition chat.h:173
Chat instance internal context.
Definition chat.h:219
uint16_t delimiter_size
Definition chat.h:237
uint16_t filter_size
Definition chat.h:242
uint16_t matches_size[3]
Definition chat.h:255
void * user_data
Definition chat.h:224
uint16_t parse_arg_len
Definition chat.h:277
uint16_t script_send_pos
Definition chat.h:270
struct k_work_delayable script_send_timeout_work
Definition chat.h:272
const struct modem_chat_match * parse_match
Definition chat.h:275
struct k_work script_run_work
Definition chat.h:260
struct k_work receive_work
Definition chat.h:281
struct k_work script_send_work
Definition chat.h:271
uint8_t work_buf[32]
Definition chat.h:232
const struct modem_chat_script * script
Definition chat.h:258
enum modem_chat_script_result script_result
Definition chat.h:265
uint16_t receive_buf_size
Definition chat.h:228
uint16_t work_buf_len
Definition chat.h:233
struct modem_pipe * pipe
Definition chat.h:221
enum modem_chat_script_send_state script_send_state
Definition chat.h:269
uint16_t script_chat_it
Definition chat.h:263
struct k_sem script_stopped_sem
Definition chat.h:266
uint8_t * delimiter
Definition chat.h:236
const struct modem_chat_script * pending_script
Definition chat.h:259
const struct modem_chat_match * matches[3]
Definition chat.h:254
uint16_t argv_size
Definition chat.h:246
uint16_t argc
Definition chat.h:247
struct k_work_delayable script_timeout_work
Definition chat.h:261
uint8_t * filter
Definition chat.h:241
uint16_t parse_match_len
Definition chat.h:276
uint16_t receive_buf_len
Definition chat.h:229
uint16_t parse_match_type
Definition chat.h:278
uint16_t delimiter_match_len
Definition chat.h:238
uint8_t ** argv
Definition chat.h:245
struct k_work script_abort_work
Definition chat.h:262
uint8_t * receive_buf
Definition chat.h:227
atomic_t script_state
Definition chat.h:264