General Steps

[中文]

Note

This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.

This document summarizes the general implementation process of the HTTP protocol in ESP-IDF, covering the basic explanation of the protocol and the method of configuring the structure.

By mastering the content of this document, developers can quickly understand the key logic of the protocol and provide a unified reference for subsequent example learning.

HTTP/HTTPS Protocol

HTTP (Hypertext Transfer Protocol) is an application layer protocol used for the transmission of hypertext and other resources between clients (such as browsers or mobile applications) and servers. It is the core communication mechanism of the World Wide Web. HTTPS (HTTP Secure) is a secure version of HTTP that implements data encryption and identity authentication through TLS/SSL (Transport Layer Security/Secure Sockets Layer).

Protocol Model

HTTP/HTTPS is based on the request-response model. In a complete communication process:

• The client sends a request, which consists of several parts:

  • Request method: Represents the type of operation, for example, GET is used to obtain resources, POST is used to submit data.

  • URL: Uniform Resource Identifier, used to identify a resource on the Internet, such as a web page address.

  • Request header: Contains additional information, such as data type, authentication information, etc.

  • Request body: An optional part, used to carry data to be passed to the server, such as form content or JSON data.

• After processing the request, the server returns a response, which includes:

  • Status code: A three-digit number representing the processing result, for example, 200 means success, 404 means resource not found, 500 means server error.

  • Response header: Contains the attribute information of the response, such as data length or data format.

  • Response body: The actual returned resource content, such as web page HTML text or API returned JSON data.

Protocol Features

The HTTP protocol is stateless. This means that the server does not automatically save the client’s request history, and each request is considered an independent event. To implement the “remember user” function, it is necessary to use methods such as Cookies (a small data file stored on the client), Session (a session management mechanism based on the server side), or Token (a token used to identify and verify user identity).

HTTPS introduces TLS/SSL encryption on this basis. Through encrypted communication, even if the data between the client and the server is intercepted by a third party, it cannot be easily parsed. At the same time, TLS/SSL also provides identity authentication, ensuring that the communication object is a trusted server and integrity check, ensuring that the data has not been tampered with, thereby significantly improving security.

Common Application Scenarios

HTTP/HTTPS is widely used in:

• Web browsing: The browser requests a web page, and the server returns resources such as HTML, CSS, images, etc.

• API calls: Client applications call RESTful APIs to exchange JSON or XML data with the server.

• File transfer: Upload forms, download images or firmware files.

HTTP/S Client Execution Process

When using the HTTP/S client on ESP32, the standard execution process can be summarized as the following steps:

1. Configure the structure: For detailed explanation, refer to Structure Configuration.

2. Apply structure configuration:

• Call esp_http_client_init() to create an HTTP/S client instance and apply the configuration structure to the client object. For usage and parameter explanation, refer to ESP HTTP Client API.

3. Request operation: For detailed explanation, refer to Request Operation Instructions.

4. Obtaining response: It is necessary to obtain the HTTP/S status code and response body length to accurately determine the execution result and data range of the request. The acquisition of the response body content can be flexibly selected according to application requirements, and can be implemented through event callbacks, stream reading, or one-time complete reading.

• Call esp_http_client_get_status_code() to get the HTTP/S status code. If it returns 200, it means the request is successful. For related usage and parameter description, please refer to ESP HTTP Client API.

• Call esp_http_client_get_content_length() to get the response body length. For related usage and parameter description, please refer to ESP HTTP Client API.

• Call esp_http_client_read_response() to get the response body. For related usage and parameter description, please refer to ESP HTTP Client API.

5. Releasing resources:

• Call esp_http_client_cleanup() to release the resources occupied by the HTTP/S client to avoid memory leaks. After calling, the client handle is no longer available. For related usage and parameter description, please refer to ESP HTTP Client API.

Structure Configuration

In ESP-IDF, the HTTP client is configured through the esp_http_client_config_t structure, which is used to define the client’s target address, request behavior, security authentication, and extended functions. The structure provides a complete configuration from basic HTTP/S requests to advanced security, performance optimization, and extended capabilities. In actual applications, various parameters should be selected reasonably according to the request target, communication security, data volume, and network environment to achieve stable, efficient, and secure HTTP communication. For specific structure members, please refer to ESP HTTP Client API.

Target Server Configuration

Used to specify the target address and access method of the HTTP/HTTPS request:

URL Configuration

• The client can be configured through a complete URL. The priority of the URL is the highest, which will override other related fields, suitable for scenarios with fixed request addresses.

• It can also be configured by field to dynamically splice paths or query parameters, suitable for scenarios that need to generate requests based on runtime conditions.

  • query: In HTTP/S requests, the query parameter is a string appended to the URL path, used to pass additional information or request conditions to the server, usually following the path, connected with ?.

    • Query parameters are commonly used in GET requests to pass conditions, keywords, pagination information or other additional data, telling the server the data range, specific resources or processing methods that the client wants to obtain; it can also be used to specify resource identifiers, because some interfaces locate specific resources through query parameters, rather than putting them in the path; it can also carry control information, such as user status, filter conditions or other custom parameters, to help the server return more accurate results.

    • In POST, PUT, DELETE and other requests, query parameters can also be used to pass auxiliary information or locate resources, but the main data is usually placed in the request body.

    • When using the host + path configuration method, if the interface requires query parameters, they must be set through query; when using the full URL configuration, the query parameters can be directly included in the URL, without separate setting.

    • When the query parameter contains spaces, special symbols or non-ASCII characters, it must be URL encoded to ensure that the request is legal and the server can correctly parse it.

Address type: Supports IPv4/IPv6/domain names, etc., which can be specified by addr_type.

Authentication and Security Configuration

Supports HTTP layer authentication and TLS/SSL security mechanisms, including username/password authentication, server certificate verification, client certificate and private key configuration, TLS protocol version selection, and optional hardware security extensions, such as ECDSA peripherals and security components. When accessing services with authentication enabled, the relevant information must be correctly configured.

In HTTPS scenarios, server certificate verification is a necessary measure to ensure communication security; client certificates are used for two-way authentication; hardware security configuration is suitable for high-security applications, which can enhance the security of key management and encryption operations.

Root Certificate (Root CA Certificate) is a digital certificate issued by a trusted certificate authority (CA), used to establish the trust chain in TLS/SSL secure communication. In HTTPS or other protocols based on TLS/SSL, the server provides its certificate, and the client (such as ESP32) verifies the server’s identity through the root certificate to ensure the legality of the communication object and prevent data from being tampered with or forged.

The main functions of the root certificate include:

1. Server identity verification: Confirm the validity and trustworthy source of the server certificate.

2. Foundation for secure communication: Establish an encrypted channel after verification to ensure that data is not eavesdropped on during transmission.

3. Prevent man-in-the-middle attacks: Prevent malicious nodes from impersonating servers to intercept or tamper with data.

Server certificate verification is used to ensure that the identity of the HTTPS server accessed by the client is trustworthy. The client verifies whether the certificate provided by the server matches the trusted root certificate, confirming that the server is indeed the expected target, rather than a man-in-the-middle attack or a forged server. This verification not only guarantees the authenticity of the communication object, but also ensures that the data transmitted through TLS/SSL encryption has not been tampered with during transmission, thereby protecting the confidentiality and integrity of the data. The root certificate can be configured in the following two ways:

• cert_pem is used to specify a single or a small number of root certificates in PEM format. It is flexible but requires a lot of management, suitable for scenarios targeting specific servers or self-signed certificates. Developers need to manually provide the certificate content. This method must be used if accessing a private server or needing to trust a specific certificate.

• crt_bundle_attach:

  • A pre-compiled certificate bundle, containing multiple common root certificates. The client can verify various common HTTPS server certificates at the same time, without having to provide each certificate separately.

  • Suitable for general scenarios or applications that need to access multiple HTTPS servers, reducing the workload of manually managing certificates. If accessing public HTTPS services, this method can usually be used directly.

  • It can usually be obtained by calling esp_crt_bundle_attach. For usage instructions, refer to ESP Certificate Package.

Authentication Mechanism Configuration is used to specify how the client authenticates at the HTTP layer, mainly involving the selection of authentication types (such as Basic Authentication、Digest Authentication) and the number of retries after authentication failure. The explanations of the related structure members are as follows:

• auth_type is used to explicitly specify the authentication method adopted by the client (such as Basic or Digest), suitable for scenarios that need to fix the authentication method or avoid unnecessary negotiation.

• max_authorization_retries is used to control the maximum number of retries after authentication failure, suitable for scenarios that need to limit or close automatic retries. If this parameter is not specified, the client will use the default retry count (usually set by the library internally); if specified as -1, automatic retries are disabled, and the client will not send requests with authentication information again after receiving a 401 response, requiring developers to manually handle subsequent authentication requests.

Request Behavior Configuration

Controls request methods, network timeout, buffer size, automatic redirection, authorization retry, and asynchronous mode, etc.

Buffer needs to match the expected data volume to prevent data truncation;

Asynchronous mode can be used for applications that do not block the main task, for further explanation, refer to Asynchronous Request.

• is_async is used to specify whether the client enables asynchronous mode. The default is synchronous mode, i.e., not enabled, set to true to enable.

• timeout_ms is used to set the timeout of the request (in milliseconds), indicating the maximum time the client waits for the server response, preventing long waits from causing task blocking or resource occupation. If the request is still not completed after this time, esp_http_client_perform() will return a timeout error.

Custom Transport Options can meet special network requirements, such as proxy or encrypted channels.

Session and Connection Maintenance Configuration

Used to optimize connection performance, including keep-alive and TLS session reuse.

• Enabling keep-alive can reduce the overhead of repeated connections, but it requires server support;

• TLS session reuse can reduce handshake consumption and improve HTTPS communication efficiency.

Parameter selection should be combined with connection frequency and system resource conditions.

Event and Context Configuration

Provides event callbacks and user-defined context, used to handle data and status information during the request process.

• Event callback is used to implement necessary processing logic, the user data pointer must remain valid during the request to ensure data safety and consistency.

This type of configuration is suitable for real-time data processing, OTA upgrades, and debugging logs, etc.

Network and Extension Configuration

Supports multiple network interfaces, HTTP/2 protocol, and custom transport:

• The request path can be controlled by specifying the network interface;

• The ALPN protocol is used to implement HTTP/2 negotiation;

• Special network requirements can be met through custom transport.

When configuring, ensure compatibility with the server and client interfaces to avoid handshake or transmission abnormalities.

Request Operation Instructions

HTTP request operations refer to different types of requests initiated by the client to the server, each corresponding to different actions and server processing logic. In the ESP-IDF HTTP client, these request operations are essentially specified by the method parameter in the esp_http_client_config_t structure. All request operations supported in ESP-IDF can be referred to the members of the esp_http_client_method_t structure here. The following only selects some for explanation.

Request Operations

Request Operation	Function	Typical Use Cases
GET	Requests to obtain resources, the server returns resource content	Reading web pages, obtaining JSON data, downloading files
POST	Submits data to the server, usually triggers the server’s creation or update operation	Form submission, data upload, API call
PUT	Updates resources on the server (sometimes also creates)	Modifying existing data or files
DELETE	Deletes resources on the server	Deleting database records, files, etc.
HEAD	Similar to GET, but the server only returns the response header, not the body	Checking if a resource exists, obtaining metadata
PATCH	Modifies part of the server resources	Modifying data of some fields, not covering the entire resource

In ESP-IDF, all HTTP request operations have the same core execution flow in client code, but there are some differences in details:

1. Setting the method：

• Call esp_http_client_set_method() to set the request method. For usage and parameter description, refer to ESP HTTP Client API.

• GET is the default request method, so if this API is not explicitly called, the client will use the GET method to send the request.

• Although the .method member can be configured during structure initialization, the request method may change multiple times on the same client instance. The initialization structure is not flexible enough to fix the .method, and each modification still needs to call the API. Therefore, in actual applications, the initialization structure usually only configures fixed parameters (URL, callback, timeout, etc.), and the method and dynamic request parameters are set through the API.

2. Configuring data：

• Call esp_http_client_set_post_field() to set the request body, which carries the actual data and is the payload sent by the client to the server. For usage and parameter description, refer to ESP HTTP Client API.

• Call esp_http_client_set_header() to set the request header, which is used to pass metadata, such as authentication, data type, cache control, and interface custom information, to inform the server how to parse the request body or perform authentication. For related usage and parameter description, please refer to ESP HTTP Client API.

• Call esp_http_client_set_user_data() to set user data, which can be accessed in the callback, used to save status information, context data, or custom information related to application logic. For related usage and parameter description, please refer to ESP HTTP Client API.

• Not all requests need to configure the above content, you can configure the corresponding content according to the actual situation:

Request operation	Request body requirements	Request header requirements	Description
GET	Not used	Optional	GET requests are used to obtain resources, no request body is needed, and the request header can be set as needed by the interface, such as Authorization, Accept.
POST	Usually must be used	Must specify data type	POST is used to create resources or submit data; the request body carries data, and the request header specifies the data type and possible authentication information.
PUT	Usually must be used (optional for some interfaces)	If a request body is set, the data type must be specified	PUT is used to fully update resources; if the interface needs to upload data, you need to set the request body and inform the server of the data type through the request header.
DELETE	Optional	Optional	DELETE requests are used to delete resources; generally, no request body is needed, but some interfaces allow additional data, and the request header can be set according to the interface requirements.
HEAD	Not used	Optional	HEAD requests only return the response header; no request body, the request body can be used for authentication or custom information.
PATCH	Must be used	Must specify data type	PATCH is used to partially update resources; the request body must contain the data fields to be modified, and the data format is specified through the request header.

3. Execute the request: In ESP-IDF, the HTTP client supports two types of request execution methods: one-time transmission and streaming transmission.

One-time transmission is the most common method, which completes the entire HTTP request and response process by calling esp_http_client_perform(). In this mode, ESP-IDF internally automatically completes the steps of connection, sending requests, receiving response bodies, and closing connections, and the application only obtains the final result after the request is completed. Its characteristic is simple to use, but it needs to cache the complete response body at one time, and it is only suitable for scenarios where the response content is small. For related usage and parameter descriptions, please refer to ESP HTTP Client API.

Stream transmission allows developers to read the response body in segments, and can read and process data during the data reception process without having to store the complete response body at one time. This method is more flexible and suitable for large file downloads, long connections, and memory-limited scenarios. Its execution process is more complicated than one-time transmission:

• Call esp_http_client_open() to initiate a request and establish a connection. For related usage and parameter descriptions, please refer to ESP HTTP Client API.

• Call esp_http_client_fetch_headers() to get the response header. For related usage and parameter descriptions, please refer to ESP HTTP Client API.

• Call esp_http_client_read() multiple times to read the response body. You need to build a loop yourself, read a part of the data each time, until the complete response body is read. For related usage and parameter descriptions, please refer to ESP HTTP Client API.

• After processing, call esp_http_client_close() to close the connection. For related usage and parameter descriptions, please refer to ESP HTTP Client API.

Chunked Transfer Encoding

Overview

Chunked transfer encoding is a server data transmission mechanism supported by HTTP/1.1. When the server does not declare Content-Length in the response header, and the response length cannot be predetermined when sending, this encoding is usually used to maintain the connection and send data in chunks.

Under this mechanism, the response body is split into a series of chunks and sent sequentially. Each chunk is preceded by its length identifier, and the client parses it by block when receiving it, until it encounters a block with a length of zero, indicating the end of transmission. The main application scenarios include:

• The length of the response content cannot be predetermined when it is generated, such as streaming data, dynamically calculated results, or continuously pushed log information.

• Need to generate and transmit data simultaneously to reduce response latency or improve real-time performance.

• In scenarios of large data transmission, to avoid caching and sending all content at once, improving memory and network utilization efficiency.

The advantage of chunked transfer encoding is its flexibility and support for stream output, without the need for the server to calculate the total length in advance. The client can process the data step by step, suitable for applications with limited memory or requiring immediate processing. The downside is the increased complexity of parsing and protocol overhead, with each chunk needing to carry length information; at the same time, some debugging and verification tools have limited support for chunked responses, making debugging and problem location more complex.

Incremental Reallocation Strategy

When the client processes the response, if it cannot obtain the complete response length in advance, it usually needs to use the incremental reallocation strategy:

• Initially allocate a smaller buffer for receiving data.

• Each time a new data block is received, dynamically expand the buffer size based on the current amount of data received.

• Reallocate memory through realloc() or an equivalent method, and copy the existing data to the new buffer, then append the new data.

• Repeat the above process until the entire response is received.

The incremental reallocation strategy can be applied to all responses of unknown length, not just in chunked encoding scenarios.

Execution Logic

Encoding Judgment: The client calls esp_http_client_is_chunked_response(), and judges whether the current received HTTP response uses chunk encoding through its return value. For related usage and parameter description, please refer to ESP HTTP Client API. Return Value Processing:

• If it returns true, it means that the response data uses chunked encoding, and the client cannot know the total length in advance, and needs to use the incremental reallocation strategy or process the data block by block.

• If it returns false, it means that the client can obtain the total length of the response through Content-Length, and allocate the buffer at one time.

Redirect and Status Code

In the HTTP protocol, redirection is a server instruction used to notify the client that the requested resource has been moved or needs further operation. It is usually implemented by the server returning a 3xx series status code (range 300–399), and attaching the Location field in the response header, indicating the new access address.

For example, when a user requests http://example.com, the server may return a 301 (Moved Permanently) status code, indicating that the requested resource has been permanently moved, and specify https://example.com in the Location field, prompting the client to use the new HTTPS address for access.

Redirect Type

The specific type of redirection depends on the server-side implementation. The server can return a relative path or an absolute path in Location:

Relative Path Redirection

• The value of Location is a relative path, such as /new-path.

• When the client processes it, it will generate a complete new URL based on the hostname and protocol of the current request. If the splicing logic is wrong, it may lead to access failure.

• This type of redirection depends on the original request URL, and the server only needs to give a relative path, which is suitable for resource migration under the same domain name.

Absolute Path Redirection

• The value of Location is a complete absolute URL, such as http://example.com/new-path.

• The client can directly use this URL to initiate a new request, without splicing.

• This type of redirection is independent of the original request, can be redirected to different domain names or protocols, has higher flexibility, but the return message length is longer, occupying more bandwidth.

Redirect Processing

In the ESP-IDF’s HTTP client, when the server returns a 3xx response, it will trigger the HTTP_EVENT_REDIRECT callback event. Developers can perform the following operations in the callback:

• Modify Request Header: Call esp_http_client_set_header() to add or modify request header fields, such as adding user authentication information or specific identifiers. For related usage and parameter descriptions, please refer to ESP HTTP Client API.

• Trigger Redirection: Call esp_http_client_set_redirection() to instruct the client to initiate subsequent requests according to the new URL provided in the response header Location field. For related usage and parameter descriptions, please refer to ESP HTTP Client API.

• Control Automatic Redirection Behavior: Control automatic redirection behavior by configuring some related members in the esp_http_client_config_t structure.

  • disable_auto_redirect is used to determine whether the client automatically follows the new URL specified by the Location field when it receives a 3xx status code.

    • When set to true, the client will not automatically redirect, but will directly hand over the 3xx response to the application layer for processing. At this time, developers can decide whether to follow the redirection, whether to modify the request header, or whether to terminate the request through the HTTP_EVENT_REDIRECT callback.

    • When set to false (default value), the client will automatically redirect according to Location, which is suitable for most general scenarios.

  • max_redirection_count is used to limit the number of times the client automatically follows redirection.

    • In some service configuration errors or malicious scenarios, there may be an infinite redirection loop, causing the request to be unable to end and consuming system resources. This parameter can be used to set the maximum allowable times (such as 5 times). Once this number is exceeded, the client will terminate the request and return an error.

    • This value is a non-negative integer. When the value is 0, the library’s default limit will be used (different versions of the SDK may adjust it) to avoid infinite loops when not explicitly configured.

Basic Authentication

Basic authentication is the simplest authentication mechanism in the HTTP protocol, used to confirm user identity between the client and the server. When the client requests protected resources, it sends the username and password to the server in the Authorization field of the HTTP request header after Base64 encoding. Since Base64 encoding is only used for transmission format and does not provide encryption, transmissions without HTTPS encryption are easy to intercept, and the security is relatively low.

The main advantages of basic authentication are its simplicity and good compatibility, making it suitable for quickly implementing user authentication scenarios, especially under controlled networks or HTTPS encrypted communications. It is applicable in the following situations:

1. When you need to quickly implement HTTP layer user identity authentication, and the system environment is controlled with low risk.

2. When you need to interact with trusted servers or server-side interfaces, such as REST APIs, local area network management services.

3. When you want to implement client automatic authentication in a simple way, without the need for complex digest calculations or encryption operations.

Execution Process

The regular full process of basic authentication can be summarized as follows:

1. Client requests protected resources:

• The client sends an HTTP request to the server without providing authentication information.

• The server detects that the sent request requires authentication and returns a 401 Unauthorized response.

2. Server returns authentication challenge

• The response header contains the WWW-Authenticate field, indicating that the authentication type is Basic, and provides a realm value to identify the authentication domain.

3. Client generates authentication response

• The client concatenates the username and password in the format of username:password and encodes it in Base64.

• The encoded result is attached to the Authorization request header and the request is reissued.

4. Server verifies the response

• The server parses the Base64 encoding, obtains the username and password, and compares them with local storage or authentication mechanism.

• If they match, the content of the client’s requested resource is returned; otherwise, 401 is returned and the above process is repeated.

5. Subsequent requests

• For subsequent requests to the same authentication domain, the client can continue to use the same Authorization header without having to regenerate it.

• Automatic retries and authentication processing can be implemented by configuring client parameters (such as auth_type and max_authorization_retries).

Digest Authentication

Digest Authentication is an HTTP protocol layer identity verification mechanism used to securely verify user identity between the client and the server. This authentication generates a digest value (digest) by hashing the username, password, and request information (such as URI, random number nonce, etc.) using common algorithms like MD5 or SHA-256, and sends it to the server, instead of directly transmitting the plaintext password.

Through Digest Authentication, the client does not directly send plaintext passwords on the network, effectively preventing plaintext password leakage and enhancing security. At the same time, the random number (nonce) provided by the server participates in the digest calculation, which can prevent attackers from reusing the request packet for authentication. In addition, this authentication is more secure than Basic Authentication when not using HTTPS, and can further enhance security under HTTPS.

This authentication is applicable to the following scenarios:

1. When it is necessary to verify user identity at the HTTP protocol layer, but plaintext passwords should not be directly transmitted.

2. Suitable for authentication between the client and the controlled server, such as REST API interfaces or management services within a local area network.

3. When higher security than Basic Authentication is required, but it is inconvenient to deploy a complete TLS two-way authentication.

Execution Process

The regular full process of Digest Authentication can be summarized as follows:

1. Client requests protected resources:

• The client sends an HTTP request to the server without providing authentication information.

• The server detects that the sent request requires authentication and returns a 401 Unauthorized response.

2. Server returns authentication challenge

• The response header contains the WWW-Authenticate field, specifying Digest Authentication parameters:

  • realm: Authentication domain, used to distinguish different protection areas.

  • nonce: One-time random number, used to prevent replay attacks.

  • algorithm: Digest algorithm (such as MD5, SHA-256).

  • qop (optional): Quality protection options, such as auth.

  • opaque (optional): Random value generated by the server, used to prevent tampering.

3. Client generates authentication response

• The client uses the username, password, and the realm, nonce and other parameters returned by the server to generate a digest (response).

• The calculation formula is determined by the algorithm, such as MD5 or SHA-256.

• The generated response is attached to the Authorization request header and the request is reissued.

4. Server verifies the response

• The server calculates the expected digest according to the same algorithm and compares it with the response provided by the client.

• If they match, the content of the client’s requested resource is returned; otherwise, 401 is returned and the above process is repeated.

5. Subsequent requests

• The most recent nonce can be reused or refreshed for subsequent requests to the same authentication domain, and Digest Authentication can continue to be used.

Digest Algorithm

In HTTP Digest Authentication, the algorithm determines how the client calculates the digest to respond to the server’s challenge, usually using the following two algorithms:

MD5 (Message Digest 5) is a digest algorithm with an output length of 128 bits (16 bytes). It is fast and has a long history, but it has been proven to have collision vulnerabilities. Therefore, it is not suitable for security-sensitive scenarios, but is applicable for non-security checks, file integrity checks, or historical compatibility requirements.

SHA-256 (Secure Hash Algorithm 256) has an output length of 256 bits (32 bytes). It is more secure and has strong collision resistance. It is currently considered safe and can be used for encryption signatures, password storage, and secure communication in TLS/SSL, etc.

URL Encoding

URL encoding (also known as percent-encoding) is used to convert special characters or non-ASCII characters in URLs into legal ASCII characters to ensure that HTTP requests can be correctly transmitted and parsed.

Some characters in URLs have special meanings or are not allowed to appear directly, such as:

• ? is used to separate paths and queries.

• & is used to separate multiple query parameters.

• # represents a URL anchor.

• Spaces, Chinese or other non-ASCII characters.

If these characters are used directly in URLs, it may lead to request format errors, server parsing failures, and data loss or errors. Therefore, when query parameters contain spaces, special symbols, or non-ASCII characters, URL encoding must be performed.

Execution Process

The general process of URL encoding can be summarized as follows:

1. Determine the characters that need to be encoded.

2. Convert characters into ASCII values.

3. Generate encoding format:

• Use the % symbol plus the hexadecimal value to represent the character.

• For example, space is represented as %20, # is represented as %23, and the Chinese character “中” is represented as %E4%B8%AD (converted by byte after UTF-8 encoding).

4. Replace the original string:

• Replace the characters that need to be encoded in the original string one by one with the %XX format to generate the final encoded string.

5. Append to the URL:

• Append the encoded string as a query parameter after the URL path, separated by ?.

In actual development, you can call the example function example_uri_encode() provided by ESP-IDF to complete URL encoding. This function encapsulates the core steps in the general process, including determining which characters need to be encoded, converting these characters into %XX hexadecimal representations, and generating the encoded string. Developers only need to pass the original query parameters into this function to get a safe, usable encoded string for HTTP GET requests, and then append it to the request, without the need to manually encode each character, thereby simplifying the development process and avoiding encoding errors.

Asynchronous Requests

Asynchronous requests refer to the client initiating an HTTPS request and not blocking to wait for the server’s response, but immediately returning control, allowing the program to continue executing other tasks. Its characteristic is that it can handle other operations during the request process and handle response data through event callbacks or polling methods.

When set to asynchronous requests, calling esp_http_client_perform() may return ESP_ERR_HTTP_EAGAIN, indicating that the request is not yet complete. Therefore, during the execution process, this function needs to be called in a loop until it returns a value other than ESP_ERR_HTTP_EAGAIN.

The advantage of asynchronous requests is that they do not block the main task, improving the system’s response capability, especially suitable for scenarios where multiple HTTPS requests or other tasks are handled simultaneously. In contrast, synchronous requests will block until the request is completed or times out after calling esp_http_client_perform(), although the implementation is simple, it can easily block other tasks in high concurrency or long delay scenarios, affecting execution efficiency.