VSF Documented
vsf_espidf_cfg.h
Go to the documentation of this file.
1/*****************************************************************************
2 * Copyright(C)2009-2026 by VSF Team *
3 * *
4 * Licensed under the Apache License, Version 2.0 (the "License"); *
5 * you may not use this file except in compliance with the License. *
6 * You may obtain a copy of the License at *
7 * *
8 * http://www.apache.org/licenses/LICENSE-2.0 *
9 * *
10 * Unless required by applicable law or agreed to in writing, software *
11 * distributed under the License is distributed on an "AS IS" BASIS, *
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
13 * See the License for the specific language governing permissions and *
14 * limitations under the License. *
15 * *
16 ****************************************************************************/
17
18/*============================ INCLUDES ======================================*/
19
21#include "../../../vsf_cfg.h"
22
23#ifndef __VSF_ESPIDF_CFG_H__
24#define __VSF_ESPIDF_CFG_H__
25
26#include "shell/vsf_shell_wrapper.h"
27
28/*============================ MACROS ========================================*/
29
30// Master switch. User enables this in vsf_usr_cfg.h / board cfg.
31#ifndef VSF_USE_ESPIDF
32# define VSF_USE_ESPIDF DISABLED
33#endif
34
35#ifndef VSF_ESPIDF_ASSERT
36# define VSF_ESPIDF_ASSERT VSF_ASSERT
37#endif
38
39#define VSF_ESPIDF_WRAPPER(__api) VSF_SHELL_WRAPPER(vsf_espidf, __api)
40
41// ---------------------------------------------------------------------------
42// ESP-IDF API baseline version this sub-system targets.
43// Align with a specific IDF release so that header shapes are deterministic.
44// Default baseline: v5.x LTS. Adjust when a new baseline is chosen.
45// ---------------------------------------------------------------------------
46#ifndef VSF_ESPIDF_CFG_VERSION_MAJOR
47# define VSF_ESPIDF_CFG_VERSION_MAJOR 5
48#endif
49#ifndef VSF_ESPIDF_CFG_VERSION_MINOR
50# define VSF_ESPIDF_CFG_VERSION_MINOR 1
51#endif
52#ifndef VSF_ESPIDF_CFG_VERSION_PATCH
53# define VSF_ESPIDF_CFG_VERSION_PATCH 0
54#endif
55
56// ---------------------------------------------------------------------------
57// Per-component enable switches. All OFF by default; opt-in as each module
58// is implemented.
59// ---------------------------------------------------------------------------
60
61// Core infrastructure
62#ifndef VSF_ESPIDF_CFG_USE_LOG
63# define VSF_ESPIDF_CFG_USE_LOG ENABLED
64#endif
65#ifndef VSF_ESPIDF_CFG_USE_ERR
66# define VSF_ESPIDF_CFG_USE_ERR ENABLED
67#endif
68#ifndef VSF_ESPIDF_CFG_USE_EVENT
69# define VSF_ESPIDF_CFG_USE_EVENT ENABLED
70#endif
71#ifndef VSF_ESPIDF_CFG_USE_TIMER
72# define VSF_ESPIDF_CFG_USE_TIMER ENABLED
73#endif
74#ifndef VSF_ESPIDF_CFG_USE_SYSTEM
75# define VSF_ESPIDF_CFG_USE_SYSTEM ENABLED
76#endif
77#ifndef VSF_ESPIDF_CFG_USE_RINGBUF
78# define VSF_ESPIDF_CFG_USE_RINGBUF ENABLED
79#endif
80#ifndef VSF_ESPIDF_CFG_USE_HEAP_CAPS
81# define VSF_ESPIDF_CFG_USE_HEAP_CAPS ENABLED
82#endif
83
84// Storage
85#ifndef VSF_ESPIDF_CFG_USE_PARTITION
86# define VSF_ESPIDF_CFG_USE_PARTITION DISABLED
87#endif
88// Runtime esp_partition_register_external() / _deregister_external() slot
89// pool. Set to 0 to compile the entry points out entirely (callers receive
90// ESP_ERR_INVALID_STATE). Compile-time entries from vsf_espidf_cfg_t are
91// always available regardless of this switch.
92#ifndef VSF_ESPIDF_CFG_PARTITION_DYNAMIC
93# define VSF_ESPIDF_CFG_PARTITION_DYNAMIC ENABLED
94#endif
95#ifndef VSF_ESPIDF_CFG_PARTITION_MAX_DYNAMIC
96# define VSF_ESPIDF_CFG_PARTITION_MAX_DYNAMIC 8
97#endif
98#ifndef VSF_ESPIDF_CFG_USE_NVS
99# define VSF_ESPIDF_CFG_USE_NVS DISABLED
100#endif
101#ifndef VSF_ESPIDF_CFG_USE_ESP_FLASH
102# define VSF_ESPIDF_CFG_USE_ESP_FLASH DISABLED
103#endif
104#ifndef VSF_ESPIDF_CFG_USE_VFS
105# define VSF_ESPIDF_CFG_USE_VFS DISABLED
106#endif
107// Maximum number of concurrently registered VFS entries (base paths).
108#ifndef VSF_ESPIDF_CFG_VFS_MAX_REGISTERED
109# define VSF_ESPIDF_CFG_VFS_MAX_REGISTERED 8
110#endif
111// Maximum open file descriptors per VFS entry (for fd translation).
112#ifndef VSF_ESPIDF_CFG_VFS_MAX_FDS
113# define VSF_ESPIDF_CFG_VFS_MAX_FDS 16
114#endif
115// ESP-IDF CONFIG_VFS_SUPPORT_DIR equivalent. Controls whether directory
116// related ops (stat, link, opendir, readdir, mkdir, ...) are compiled.
117#ifndef VSF_ESPIDF_CFG_VFS_SUPPORT_DIR
118# define VSF_ESPIDF_CFG_VFS_SUPPORT_DIR ENABLED
119#endif
120// ESP-IDF CONFIG_VFS_SUPPORT_SELECT equivalent.
121#ifndef VSF_ESPIDF_CFG_VFS_SUPPORT_SELECT
122# define VSF_ESPIDF_CFG_VFS_SUPPORT_SELECT DISABLED
123#endif
124// ESP-IDF CONFIG_VFS_SUPPORT_TERMIOS equivalent.
125#ifndef VSF_ESPIDF_CFG_VFS_SUPPORT_TERMIOS
126# define VSF_ESPIDF_CFG_VFS_SUPPORT_TERMIOS DISABLED
127#endif
128#ifndef VSF_ESPIDF_CFG_USE_LITTLEFS
129# define VSF_ESPIDF_CFG_USE_LITTLEFS DISABLED
130#endif
131#ifndef VSF_ESPIDF_CFG_LITTLEFS_MAX_INSTANCES
132# define VSF_ESPIDF_CFG_LITTLEFS_MAX_INSTANCES 4
133#endif
134#ifndef VSF_ESPIDF_CFG_USE_FATFS
135# define VSF_ESPIDF_CFG_USE_FATFS DISABLED
136#endif
137#ifndef VSF_ESPIDF_CFG_FATFS_MAX_INSTANCES
138# define VSF_ESPIDF_CFG_FATFS_MAX_INSTANCES 2
139#endif
140
141// Network
142#ifndef VSF_ESPIDF_CFG_USE_NETIF
143# define VSF_ESPIDF_CFG_USE_NETIF DISABLED
144#endif
145#ifndef VSF_ESPIDF_CFG_USE_HTTP_CLIENT
146# define VSF_ESPIDF_CFG_USE_HTTP_CLIENT DISABLED
147#endif
148
149// --------------------------------------------------------------------------
150// esp_http_client feature profile + atomic switches.
151//
152// The 5 atomic switches below toggle optional pieces of the esp_http_client
153// compatibility shim. They are grouped behind a single PROFILE knob so that
154// most users pick one of 3 presets and only the advanced users need to
155// override individual switches.
156//
157// MINIMAL - smallest footprint; HTTP/HTTPS basic GET/POST only.
158// No redirect following, no Digest auth, no bundled CA store,
159// no cooperative cancel, no async mode. Basic auth is ALWAYS
160// compiled in (cost < 50 LOC, not worth a flag).
161// STANDARD - default. MINIMAL + HTTP 3xx redirect follow + 401 challenge
162// retry loop. +~40 LOC vs MINIMAL.
163// FULL - STANDARD + Digest auth + esp_crt_bundle_attach + cooperative
164// cancel. +~120 LOC + CA bundle payload (~10..500KB) vs STANDARD.
165// Does NOT enable async mode (that flag stays opt-in, see below).
166//
167// Any atomic switch a user predefines before this header is included wins
168// over the profile default, regardless of PROFILE value.
169// --------------------------------------------------------------------------
170#define VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_MINIMAL 0
171#define VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_STANDARD 1
172#define VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_FULL 2
173#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE
174# define VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_STANDARD
175#endif
176
177// 3xx redirect following + 401 "WWW-Authenticate: Basic" challenge retry.
178// Cost: ~40 LOC + one extra header-parse pass per hop.
179#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_REDIRECT
180# if VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE >= VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_STANDARD
181# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_REDIRECT ENABLED
182# else
183# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_REDIRECT DISABLED
184# endif
185#endif
186
187// HTTP Digest (RFC 7616) authentication parser + response hashing.
188// Cost: ~50 LOC + pulls MD5 + realm/nonce/qop state. HTTP Basic auth
189// remains unconditionally available in all profiles.
190#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_DIGEST_AUTH
191# if VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE >= VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_FULL
192# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_DIGEST_AUTH ENABLED
193# else
194# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_DIGEST_AUTH DISABLED
195# endif
196#endif
197
198// esp_crt_bundle_attach(): verify server cert against a compiled-in CA store.
199// Cost: ~40 LOC wiring + CA bundle blob (~10..500KB depending on which bundle).
200// When DISABLED, callers must pass cert_pem explicitly; otherwise TLS will
201// run with MBEDTLS_SSL_VERIFY_NONE-equivalent semantics (see TLS layer).
202#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CRT_BUNDLE
203# if VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE >= VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_FULL
204# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CRT_BUNDLE ENABLED
205# else
206# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CRT_BUNDLE DISABLED
207# endif
208#endif
209
210// Cooperative cancellation: esp_http_client_cancel_request() sets a flag
211// that the perform loop checks between chunks. Does NOT preempt a blocked
212// recv() -- use esp_http_client_set_timeout_ms() to bound that.
213// Cost: ~30 LOC + one bool field per client.
214#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CANCEL
215# if VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE >= VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_FULL
216# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CANCEL ENABLED
217# else
218# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CANCEL DISABLED
219# endif
220#endif
221
222// Async mode: esp_http_client_perform() returns ESP_ERR_HTTP_EAGAIN instead
223// of blocking; caller polls until completion. Requires a non-blocking
224// transport port. Cost: ~1500+ LOC (full state machine replicating IDF's
225// dispatch loop). Because of the size, this stays opt-in even when
226// PROFILE == FULL -- users enabling async must predefine it explicitly.
227#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_ASYNC
228# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_ASYNC DISABLED
229#endif
230
231// Working buffer size used by the shim when the caller does not provide
232// their own via esp_http_client_config_t::buffer_size. Must be >= the
233// largest expected header line (ESP-IDF default is 512).
234#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_BUFFER_SIZE
235# define VSF_ESPIDF_HTTP_CLIENT_CFG_BUFFER_SIZE 512
236#endif
237
238#ifndef VSF_ESPIDF_CFG_USE_HTTP_SERVER
239# define VSF_ESPIDF_CFG_USE_HTTP_SERVER DISABLED
240#endif
241#ifndef VSF_ESPIDF_CFG_USE_WIFI
242# define VSF_ESPIDF_CFG_USE_WIFI DISABLED
243#endif
244
245// Peripheral drivers (bridged to vsf_template_*)
246#ifndef VSF_ESPIDF_CFG_USE_DRIVER_GPIO
247# define VSF_ESPIDF_CFG_USE_DRIVER_GPIO DISABLED
248#endif
249#ifndef VSF_ESPIDF_CFG_USE_DRIVER_UART
250# define VSF_ESPIDF_CFG_USE_DRIVER_UART DISABLED
251#endif
252#ifndef VSF_ESPIDF_CFG_USE_DRIVER_I2C
253# define VSF_ESPIDF_CFG_USE_DRIVER_I2C DISABLED
254#endif
255#ifndef VSF_ESPIDF_CFG_USE_DRIVER_SPI_MASTER
256# define VSF_ESPIDF_CFG_USE_DRIVER_SPI_MASTER DISABLED
257#endif
258#ifndef VSF_ESPIDF_CFG_USE_DRIVER_LEDC
259# define VSF_ESPIDF_CFG_USE_DRIVER_LEDC DISABLED
260#endif
261#ifndef VSF_ESPIDF_CFG_USE_DRIVER_GPTIMER
262# define VSF_ESPIDF_CFG_USE_DRIVER_GPTIMER DISABLED
263#endif
264#ifndef VSF_ESPIDF_CFG_USE_DRIVER_ADC
265# define VSF_ESPIDF_CFG_USE_DRIVER_ADC DISABLED
266#endif
267
268// USB Host (bridged to vsf_usbh)
269#ifndef VSF_ESPIDF_CFG_USE_USB_HOST
270# define VSF_ESPIDF_CFG_USE_USB_HOST DISABLED
271#endif
272
273// USB Device (bridged to vsf_usbd)
274#ifndef VSF_ESPIDF_CFG_USE_USB_DEVICE
275# define VSF_ESPIDF_CFG_USE_USB_DEVICE DISABLED
276#endif
277
278// LCD panel (IO + vendor panels bridged to vsf_disp_t)
279#ifndef VSF_ESPIDF_CFG_USE_LCD
280# define VSF_ESPIDF_CFG_USE_LCD DISABLED
281#endif
282// Ringbuf QueueSet integration (xRingbufferAddToQueueSetRead / ...).
283// Requires VSF_USE_FREERTOS and VSF_FREERTOS_CFG_USE_QUEUESET.
284#ifndef VSF_ESPIDF_CFG_RINGBUF_USE_FREERTOS_QUEUESET
285# define VSF_ESPIDF_CFG_RINGBUF_USE_FREERTOS_QUEUESET DISABLED
286#endif
287
288// Application tracing (esp_apptrace_* API).
289// Virtual transport: up-channel -> stdout, down-channel <- stdin.
290#ifndef VSF_ESPIDF_CFG_USE_APP_TRACE
291# define VSF_ESPIDF_CFG_USE_APP_TRACE DISABLED
292#endif
293
294// Console (REPL + command registration + argtable3 + linenoise).
295#ifndef VSF_ESPIDF_CFG_USE_CONSOLE
296# define VSF_ESPIDF_CFG_USE_CONSOLE DISABLED
297#endif
298
299#endif // __VSF_ESPIDF_CFG_H__
vsf_shell_wrapper.h
Generated from commit: vsfteam/vsf@c3767bf