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#ifndef VSF_ESPIDF_CFG_USE_LITTLEFS
108# define VSF_ESPIDF_CFG_USE_LITTLEFS DISABLED
109#endif
110#ifndef VSF_ESPIDF_CFG_LITTLEFS_MAX_INSTANCES
111# define VSF_ESPIDF_CFG_LITTLEFS_MAX_INSTANCES 4
112#endif
113#ifndef VSF_ESPIDF_CFG_USE_FATFS
114# define VSF_ESPIDF_CFG_USE_FATFS DISABLED
115#endif
116#ifndef VSF_ESPIDF_CFG_FATFS_MAX_INSTANCES
117# define VSF_ESPIDF_CFG_FATFS_MAX_INSTANCES 2
118#endif
119
120// Network
121#ifndef VSF_ESPIDF_CFG_USE_NETIF
122# define VSF_ESPIDF_CFG_USE_NETIF DISABLED
123#endif
124#ifndef VSF_ESPIDF_CFG_USE_HTTP_CLIENT
125# define VSF_ESPIDF_CFG_USE_HTTP_CLIENT DISABLED
126#endif
127
128// --------------------------------------------------------------------------
129// esp_http_client feature profile + atomic switches.
130//
131// The 5 atomic switches below toggle optional pieces of the esp_http_client
132// compatibility shim. They are grouped behind a single PROFILE knob so that
133// most users pick one of 3 presets and only the advanced users need to
134// override individual switches.
135//
136// MINIMAL - smallest footprint; HTTP/HTTPS basic GET/POST only.
137// No redirect following, no Digest auth, no bundled CA store,
138// no cooperative cancel, no async mode. Basic auth is ALWAYS
139// compiled in (cost < 50 LOC, not worth a flag).
140// STANDARD - default. MINIMAL + HTTP 3xx redirect follow + 401 challenge
141// retry loop. +~40 LOC vs MINIMAL.
142// FULL - STANDARD + Digest auth + esp_crt_bundle_attach + cooperative
143// cancel. +~120 LOC + CA bundle payload (~10..500KB) vs STANDARD.
144// Does NOT enable async mode (that flag stays opt-in, see below).
145//
146// Any atomic switch a user predefines before this header is included wins
147// over the profile default, regardless of PROFILE value.
148// --------------------------------------------------------------------------
149#define VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_MINIMAL 0
150#define VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_STANDARD 1
151#define VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_FULL 2
152#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE
153# define VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_STANDARD
154#endif
155
156// 3xx redirect following + 401 "WWW-Authenticate: Basic" challenge retry.
157// Cost: ~40 LOC + one extra header-parse pass per hop.
158#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_REDIRECT
159# if VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE >= VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_STANDARD
160# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_REDIRECT ENABLED
161# else
162# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_REDIRECT DISABLED
163# endif
164#endif
165
166// HTTP Digest (RFC 7616) authentication parser + response hashing.
167// Cost: ~50 LOC + pulls MD5 + realm/nonce/qop state. HTTP Basic auth
168// remains unconditionally available in all profiles.
169#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_DIGEST_AUTH
170# if VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE >= VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_FULL
171# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_DIGEST_AUTH ENABLED
172# else
173# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_DIGEST_AUTH DISABLED
174# endif
175#endif
176
177// esp_crt_bundle_attach(): verify server cert against a compiled-in CA store.
178// Cost: ~40 LOC wiring + CA bundle blob (~10..500KB depending on which bundle).
179// When DISABLED, callers must pass cert_pem explicitly; otherwise TLS will
180// run with MBEDTLS_SSL_VERIFY_NONE-equivalent semantics (see TLS layer).
181#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CRT_BUNDLE
182# if VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE >= VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_FULL
183# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CRT_BUNDLE ENABLED
184# else
185# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CRT_BUNDLE DISABLED
186# endif
187#endif
188
189// Cooperative cancellation: esp_http_client_cancel_request() sets a flag
190// that the perform loop checks between chunks. Does NOT preempt a blocked
191// recv() -- use esp_http_client_set_timeout_ms() to bound that.
192// Cost: ~30 LOC + one bool field per client.
193#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CANCEL
194# if VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE >= VSF_ESPIDF_HTTP_CLIENT_CFG_PROFILE_FULL
195# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CANCEL ENABLED
196# else
197# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_CANCEL DISABLED
198# endif
199#endif
200
201// Async mode: esp_http_client_perform() returns ESP_ERR_HTTP_EAGAIN instead
202// of blocking; caller polls until completion. Requires a non-blocking
203// transport port. Cost: ~1500+ LOC (full state machine replicating IDF's
204// dispatch loop). Because of the size, this stays opt-in even when
205// PROFILE == FULL -- users enabling async must predefine it explicitly.
206#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_USE_ASYNC
207# define VSF_ESPIDF_HTTP_CLIENT_CFG_USE_ASYNC DISABLED
208#endif
209
210// Working buffer size used by the shim when the caller does not provide
211// their own via esp_http_client_config_t::buffer_size. Must be >= the
212// largest expected header line (ESP-IDF default is 512).
213#ifndef VSF_ESPIDF_HTTP_CLIENT_CFG_BUFFER_SIZE
214# define VSF_ESPIDF_HTTP_CLIENT_CFG_BUFFER_SIZE 512
215#endif
216
217#ifndef VSF_ESPIDF_CFG_USE_HTTP_SERVER
218# define VSF_ESPIDF_CFG_USE_HTTP_SERVER DISABLED
219#endif
220#ifndef VSF_ESPIDF_CFG_USE_WIFI
221# define VSF_ESPIDF_CFG_USE_WIFI DISABLED
222#endif
223
224// Peripheral drivers (bridged to vsf_template_*)
225#ifndef VSF_ESPIDF_CFG_USE_DRIVER_GPIO
226# define VSF_ESPIDF_CFG_USE_DRIVER_GPIO DISABLED
227#endif
228#ifndef VSF_ESPIDF_CFG_USE_DRIVER_UART
229# define VSF_ESPIDF_CFG_USE_DRIVER_UART DISABLED
230#endif
231#ifndef VSF_ESPIDF_CFG_USE_DRIVER_I2C
232# define VSF_ESPIDF_CFG_USE_DRIVER_I2C DISABLED
233#endif
234#ifndef VSF_ESPIDF_CFG_USE_DRIVER_SPI_MASTER
235# define VSF_ESPIDF_CFG_USE_DRIVER_SPI_MASTER DISABLED
236#endif
237#ifndef VSF_ESPIDF_CFG_USE_DRIVER_LEDC
238# define VSF_ESPIDF_CFG_USE_DRIVER_LEDC DISABLED
239#endif
240#ifndef VSF_ESPIDF_CFG_USE_DRIVER_GPTIMER
241# define VSF_ESPIDF_CFG_USE_DRIVER_GPTIMER DISABLED
242#endif
243#ifndef VSF_ESPIDF_CFG_USE_DRIVER_ADC
244# define VSF_ESPIDF_CFG_USE_DRIVER_ADC DISABLED
245#endif
246
247#endif // __VSF_ESPIDF_CFG_H__
vsf_shell_wrapper.h
Generated from commit: vsfteam/vsf@015f4d1