How khoih-prog/asynchttprequest_generic works
Project Type & Purpose
• This is an Arduino-style client library (“AsyncHTTPRequest_Generic”) that provides a non-blocking, callback-driven HTTP layer for embedded C++ applications on ESP8266, ESP32 and STM32 boards. It wraps board-specific asynchronous TCP stacks to let user sketches issue GET/POST/PUT/etc. requests without blocking the MCU.
File-Structure Analysis
• Top-level
• library.json & library.properties – metadata for Arduino and PlatformIO.
• README.md – full documentation.
• LICENSE, CONTRIBUTING.md, .github/ – governance and CI.
• src/
• AsyncHTTPRequest_Generic.h/.hpp/.cpp – public C++ API and template implementation.
• AsyncHTTPRequest_Impl_Generic.h – conditional‐compile transport adapter.
• xbuf buffer classes inside.
• examples/
• One sketch per board/type demonstrating usage (ESP32, ESP8266, STM32, ENC28J60, W5500, etc.).
• multiFileProject shows best practice for avoiding multiple‐definition errors.
• Packages_Patches/
• Board-core override files for STM32, Arduino SAMD, Seeeduino, etc. to support LAN8720, Serial1, etc.
• platformio/
• platformio.ini demonstrating auto-install of dependencies.
• utils/
• Formatting scripts (astyle, restyle).
Key Insights from README
• Architecture: layered HTTP-on-TCP abstraction mirroring XMLHttpRequest’s ready-state model.
• Dependencies: ESPAsyncTCP (ESP8266), AsyncTCP (ESP32), STM32AsyncTCP or STM32Ethernet+LwIP for STM32.
• Principles: non-blocking callbacks (onReadyStateChange, onData), small-segment chained buffer (xbuf).
• Extensibility: pluggable transport via AsyncHTTPRequest_Impl_Generic.h; examples cover WiFiManager, SPIFFS/LittleFS.
Components & Interactions (
a. Main Components
1. Application Sketch (Arduino .ino)
2. AsyncHTTPRequest_Generic Library
3. Transport Adapter Layer
‑ ESPAsyncTCP adapter (ESP8266)
‑ AsyncTCP adapter (ESP32)
‑ STM32AsyncTCP / STM32Ethernet+LwIP adapter (STM32)
4. Network Interface
‑ Wi-Fi PHY / Ethernet PHY (LAN8720, LAN8742A, W5500, ENC28J60, W6100)
5. Board MCU
‑ ESP8266 / ESP32 / STM32
6. External HTTP Server (cloud/service)
7. Optional FileSystem (SPIFFS, LittleFS) for credential-store in WiFiManager examples
8. Packages_Patches Mechanism (override board core files)
b. Relationships & Data Flow
• Sketch calls AsyncHTTPRequest API →
• Library builds HTTP request, enqueues into xbuf →
• Calls Transport Adapter to open TCP connection →
• Adapter uses AsyncTCP (board-specific) →
• AsyncTCP schedules non-blocking send/receive through hardware PHY →
• Packet flows over network to External HTTP server →
• Response events flow back upward through the same chain, invoke onData/onReadyStateChange →
• Sketch processes callbacks.
• If using examples with WiFiManager: Sketch ↔ FileSystem for storing/retrieving credentials before HTTP.
• Packages_Patches interact at build time, not at runtime.
c. Architectural Patterns & Principles
• Layered Abstraction – clear separation Sketch / HTTP library / TCP stack / PHY / MCU.
• Pluggable Adapters – single “Generic” API, concrete transport bound at compile time.
• Event-Driven, Non-Blocking – callbacks for state progression, data reception.
• Chain-of-Responsibility for buffer management (xbuf segments).
• Conditional Compilation – #if defined(ESP32) / ESP8266 / STM32 in impl header.
d. Key Technologies & Frameworks
• C++ headers + template implementation (.h/.hpp) to avoid linker errors.
• AsyncTCP / ESPAsyncTCP / STM32AsyncTCP / STM32Ethernet + LwIP
• Arduino Core for ESP8266, ESP32, STM32
• SPIFFS / LittleFS (in examples)
• PlatformIO builds & dependency manager