Zephyr API Documentation 4.0.0-rc2
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
22struct modem_chat;
23
32typedef void (*modem_chat_match_callback)(struct modem_chat *chat, char **argv, uint16_t argc,
33 void *user_data);
34
54
55#define MODEM_CHAT_MATCH(_match, _separators, _callback) \
56 { \
57 .match = (uint8_t *)(_match), .match_size = (uint8_t)(sizeof(_match) - 1), \
58 .separators = (uint8_t *)(_separators), \
59 .separators_size = (uint8_t)(sizeof(_separators) - 1), .wildcards = false, \
60 .callback = _callback, \
61 }
62
63#define MODEM_CHAT_MATCH_WILDCARD(_match, _separators, _callback) \
64 { \
65 .match = (uint8_t *)(_match), .match_size = (uint8_t)(sizeof(_match) - 1), \
66 .separators = (uint8_t *)(_separators), \
67 .separators_size = (uint8_t)(sizeof(_separators) - 1), .wildcards = true, \
68 .callback = _callback, \
69 }
70
71#define MODEM_CHAT_MATCH_INITIALIZER(_match, _separators, _callback, _wildcards, _partial) \
72 { \
73 .match = (uint8_t *)(_match), \
74 .match_size = (uint8_t)(sizeof(_match) - 1), \
75 .separators = (uint8_t *)(_separators), \
76 .separators_size = (uint8_t)(sizeof(_separators) - 1), \
77 .wildcards = _wildcards, \
78 .partial = _partial, \
79 .callback = _callback, \
80 }
81
82#define MODEM_CHAT_MATCH_DEFINE(_sym, _match, _separators, _callback) \
83 const static struct modem_chat_match _sym = MODEM_CHAT_MATCH(_match, _separators, _callback)
84
85/* Helper struct to match any response without callback. */
86extern const struct modem_chat_match modem_chat_any_match;
87
88#define MODEM_CHAT_MATCHES_DEFINE(_sym, ...) \
89 const static struct modem_chat_match _sym[] = {__VA_ARGS__}
90
91/* Helper struct to match nothing. */
92extern const struct modem_chat_match modem_chat_empty_matches[0];
93
109
110#define MODEM_CHAT_SCRIPT_CMD_RESP(_request, _response_match) \
111 { \
112 .request = (uint8_t *)(_request), \
113 .request_size = (uint16_t)(sizeof(_request) - 1), \
114 .response_matches = &_response_match, \
115 .response_matches_size = 1, \
116 .timeout = 0, \
117 }
118
119#define MODEM_CHAT_SCRIPT_CMD_RESP_MULT(_request, _response_matches) \
120 { \
121 .request = (uint8_t *)(_request), \
122 .request_size = (uint16_t)(sizeof(_request) - 1), \
123 .response_matches = _response_matches, \
124 .response_matches_size = ARRAY_SIZE(_response_matches), \
125 .timeout = 0, \
126 }
127
128#define MODEM_CHAT_SCRIPT_CMD_RESP_NONE(_request, _timeout_ms) \
129 { \
130 .request = (uint8_t *)(_request), \
131 .request_size = (uint16_t)(sizeof(_request) - 1), \
132 .response_matches = NULL, \
133 .response_matches_size = 0, \
134 .timeout = _timeout_ms, \
135 }
136
137#define MODEM_CHAT_SCRIPT_CMDS_DEFINE(_sym, ...) \
138 const struct modem_chat_script_chat _sym[] = {__VA_ARGS__}
139
140/* Helper struct to have no chat script command. */
142
148
156typedef void (*modem_chat_script_callback)(struct modem_chat *chat,
157 enum modem_chat_script_result result, void *user_data);
158
178
179#define MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, _abort_matches, _callback, _timeout_s) \
180 const static struct modem_chat_script _sym = { \
181 .name = #_sym, \
182 .script_chats = _script_chats, \
183 .script_chats_size = ARRAY_SIZE(_script_chats), \
184 .abort_matches = _abort_matches, \
185 .abort_matches_size = ARRAY_SIZE(_abort_matches), \
186 .callback = _callback, \
187 .timeout = _timeout_s, \
188 }
189
190#define MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, _script_chats, _callback, _timeout_s) \
191 MODEM_CHAT_SCRIPT_DEFINE(_sym, _script_chats, modem_chat_empty_matches, \
192 _callback, _timeout_s)
193
194#define MODEM_CHAT_SCRIPT_EMPTY_DEFINE(_sym) \
195 MODEM_CHAT_SCRIPT_NO_ABORT_DEFINE(_sym, modem_chat_empty_script_chats, NULL, 0)
196
205
211 /* Pipe used to send and receive data */
212 struct modem_pipe *pipe;
213
214 /* User data passed with match callbacks */
216
217 /* Receive buffer */
221
222 /* Work buffer */
225
226 /* Chat delimiter */
230
231 /* Array of bytes which are discarded out by parser */
234
235 /* Parsed arguments */
239
240 /* Matches
241 * Index 0 -> Response matches
242 * Index 1 -> Abort matches
243 * Index 2 -> Unsolicited matches
244 */
245 const struct modem_chat_match *matches[3];
247
248 /* Script execution */
257 struct k_sem script_stopped_sem;
258
259 /* Script sending */
264
265 /* Match parsing */
270
271 /* Process received data */
273
274 /* Statistics */
275#if CONFIG_MODEM_STATS
276 struct modem_stats_buffer receive_buf_stats;
277 struct modem_stats_buffer work_buf_stats;
278#endif
279};
280
308
315int modem_chat_init(struct modem_chat *chat, const struct modem_chat_config *config);
316
325int modem_chat_attach(struct modem_chat *chat, struct modem_pipe *pipe);
326
337int modem_chat_run_script_async(struct modem_chat *chat, const struct modem_chat_script *script);
338
349int modem_chat_run_script(struct modem_chat *chat, const struct modem_chat_script *script);
350
361static inline int modem_chat_script_run(struct modem_chat *chat,
362 const struct modem_chat_script *script)
363{
364 return modem_chat_run_script_async(chat, script);
365}
366
372
378
384
394int modem_chat_match_set_match(struct modem_chat_match *chat_match, const char *match);
395
406
414
421
427void modem_chat_match_enable_wildcards(struct modem_chat_match *chat_match, bool enable);
428
434
445 const char *request);
446
457 const struct modem_chat_match *response_matches,
458 uint16_t response_matches_size);
459
466 uint16_t timeout_ms);
467
473
480void modem_chat_script_set_name(struct modem_chat_script *script, const char *name);
481
492 const struct modem_chat_script_chat *script_chats,
493 uint16_t script_chats_size);
494
505 const struct modem_chat_match *abort_matches,
506 uint16_t abort_matches_size);
507
515
522
523#ifdef __cplusplus
524}
525#endif
526
527#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:143
@ MODEM_CHAT_SCRIPT_RESULT_TIMEOUT
Definition chat.h:146
@ MODEM_CHAT_SCRIPT_RESULT_SUCCESS
Definition chat.h:144
@ MODEM_CHAT_SCRIPT_RESULT_ABORT
Definition chat.h:145
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:156
modem_chat_script_send_state
Definition chat.h:197
@ MODEM_CHAT_SCRIPT_SEND_STATE_REQUEST
Definition chat.h:201
@ MODEM_CHAT_SCRIPT_SEND_STATE_IDLE
Definition chat.h:199
@ MODEM_CHAT_SCRIPT_SEND_STATE_DELIMITER
Definition chat.h:203
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:361
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:32
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.
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
A structure used to submit work after a delay.
Definition kernel.h:3985
A structure used to submit work.
Definition kernel.h:3957
Chat configuration.
Definition chat.h:284
uint8_t * receive_buf
Receive buffer used to store parsed arguments.
Definition chat.h:288
uint16_t argv_size
Elements in array of pointers.
Definition chat.h:302
const struct modem_chat_match * unsol_matches
Array of unsolicited matches.
Definition chat.h:304
uint16_t receive_buf_size
Size of receive buffer should be longest line + longest match.
Definition chat.h:290
uint8_t delimiter_size
Size of delimiter.
Definition chat.h:294
uint8_t * delimiter
Delimiter.
Definition chat.h:292
void * user_data
Free to use user data passed with modem match callbacks.
Definition chat.h:286
uint16_t unsol_matches_size
Elements in array of unsolicited matches.
Definition chat.h:306
uint8_t ** argv
Array of pointers used to point to parsed arguments.
Definition chat.h:300
uint8_t * filter
Bytes which are discarded by parser.
Definition chat.h:296
uint8_t filter_size
Size of filter.
Definition chat.h:298
Modem chat match.
Definition chat.h:38
modem_chat_match_callback callback
Type of modem chat instance.
Definition chat.h:52
uint8_t separators_size
Size of separators array.
Definition chat.h:46
const uint8_t * separators
Separators array.
Definition chat.h:44
bool partial
Set if script shall not continue to next step in case of match.
Definition chat.h:50
const uint8_t * match
Match array.
Definition chat.h:40
bool wildcards
Set if modem chat instance shall use wildcards when matching.
Definition chat.h:48
uint8_t match_size
Size of match.
Definition chat.h:42
Modem chat script chat.
Definition chat.h:97
uint16_t timeout
Timeout before chat script may continue to next step in milliseconds.
Definition chat.h:107
const struct modem_chat_match * response_matches
Expected responses to request.
Definition chat.h:103
const uint8_t * request
Request to send to modem.
Definition chat.h:99
uint16_t request_size
Size of request.
Definition chat.h:101
uint16_t response_matches_size
Number of elements in expected responses.
Definition chat.h:105
Modem chat script.
Definition chat.h:162
uint32_t timeout
Timeout in seconds within which the script execution must terminate.
Definition chat.h:176
const struct modem_chat_match * abort_matches
Array of abort matches.
Definition chat.h:170
uint16_t script_chats_size
Elements in array of script chats.
Definition chat.h:168
const struct modem_chat_script_chat * script_chats
Array of script chats.
Definition chat.h:166
modem_chat_script_callback callback
Callback called when script execution terminates.
Definition chat.h:174
uint16_t abort_matches_size
Number of elements in array of abort matches.
Definition chat.h:172
const char * name
Name of script.
Definition chat.h:164
Chat instance internal context.
Definition chat.h:210
uint16_t delimiter_size
Definition chat.h:228
uint16_t filter_size
Definition chat.h:233
uint16_t matches_size[3]
Definition chat.h:246
void * user_data
Definition chat.h:215
uint16_t parse_arg_len
Definition chat.h:268
uint16_t script_send_pos
Definition chat.h:261
struct k_work_delayable script_send_timeout_work
Definition chat.h:263
const struct modem_chat_match * parse_match
Definition chat.h:266
struct k_work script_run_work
Definition chat.h:251
struct k_work receive_work
Definition chat.h:272
struct k_work script_send_work
Definition chat.h:262
uint8_t work_buf[32]
Definition chat.h:223
const struct modem_chat_script * script
Definition chat.h:249
enum modem_chat_script_result script_result
Definition chat.h:256
uint16_t receive_buf_size
Definition chat.h:219
uint16_t work_buf_len
Definition chat.h:224
struct modem_pipe * pipe
Definition chat.h:212
enum modem_chat_script_send_state script_send_state
Definition chat.h:260
uint16_t script_chat_it
Definition chat.h:254
struct k_sem script_stopped_sem
Definition chat.h:257
uint8_t * delimiter
Definition chat.h:227
const struct modem_chat_script * pending_script
Definition chat.h:250
const struct modem_chat_match * matches[3]
Definition chat.h:245
uint16_t argv_size
Definition chat.h:237
uint16_t argc
Definition chat.h:238
struct k_work_delayable script_timeout_work
Definition chat.h:252
uint8_t * filter
Definition chat.h:232
uint16_t parse_match_len
Definition chat.h:267
uint16_t receive_buf_len
Definition chat.h:220
uint16_t parse_match_type
Definition chat.h:269
uint16_t delimiter_match_len
Definition chat.h:229
uint8_t ** argv
Definition chat.h:236
struct k_work script_abort_work
Definition chat.h:253
uint8_t * receive_buf
Definition chat.h:218
atomic_t script_state
Definition chat.h:255