ESP32 WiFiClient Library – readBytes

Home / References / ESP32 Library / WiFiClientSecure

Description

The readBytes method in the WiFiClient library enables you to read a defined number of bytes from a connected network stream into a buffer. Unlike the read method, which may return fewer bytes than requested, readBytes keeps reading until it retrieves the exact number of bytes specified or times out. This makes it perfect for applications where you need to ensure a complete data chunk is received, such as parsing structured responses from a server.

Syntax and Usage

The readBytes method has a single, consistent syntax that requires arguments. Here’s how to use it, illustrated with a code snippet:

• Read a specified number of bytes into a buffer: This method reads the requested number of bytes from the stream into a provided buffer, blocking until the data is fully received or a timeout occurs. It’s ideal for scenarios requiring precise data lengths.

For practical applications and examples of this method, please consult the “Example Code” section on this page. This section provides comprehensive guidance to help you better understand and apply the method effectively.

Argument(s)

The readBytes method requires the following arguments:

• buffer (uint8_t* or char*): A pointer to an array where the read bytes will be stored. This must be a pre-allocated buffer large enough to hold the requested number of bytes.
• length (size_t): The exact number of bytes to read from the network stream. The method will attempt to read this many bytes, blocking until complete or timing out.

Return Value

The readBytes method returns an size_t value:

• Return Value: The number of bytes actually read into the buffer. This will equal the requested length if successful. If fewer bytes are available before a timeout or disconnection occurs, it returns the number of bytes read, which may be less than length. Returns 0 if no data is read (e.g., due to timeout or no connection).

Example Codes

Below is a practical example demonstrating the use of the readBytes method. This example connects to www.httpbin.org, a simple HTTP testing service, to show how to read a fixed number of bytes from a server response.

Example: Reading a Fixed Number of Bytes

This example connects to www.httpbin.org and uses readBytes to read exactly 64 bytes of the server’s response into a buffer. It then prints the data to the Serial Monitor. This is useful for applications where you need a specific amount of data, such as headers or payloads.

/*
 * Author: Avant Maker
 * Date: February 24, 2025
 * Version: 1.0
 * Description: This example demonstrates how to use 
 * ESP32 WiFiClient Library's available method to
 * read exactly 64 bytes of the server’s response into a buffer.
 *
 * License: MIT 
 * 
 * Code Source: This example code is sourced from the Comprehensive 
 * Guide to the ESP32 Arduino Core Library, accessible on 
 * AvantMaker.com. For additional code examples and in-depth 
 * documentation related to the ESP32 Arduino Core Library, 
 * please visit:
 *
 * https://avantmaker.com/references/esp32-arduino-core-index/
 *
 * AvantMaker.com, your premier destination for all things 
 * DIY, AI, IoT, Smart Home, and STEM projects. We are dedicated 
 * to empowering makers, learners, and enthusiasts with the resources
 * they need to bring their innovative ideas to life.
 */

#include <WiFi.h>

const char* ssid = "your-SSID";         // Replace with your WiFi SSID
const char* password = "your-PASSWORD"; // Replace with your WiFi password
const char* host = "www.httpbin.org";
const int port = 80;

WiFiClient client;

void setup() {
    Serial.begin(115200);
    WiFi.begin(ssid, password);
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }
    Serial.println("\nConnected to WiFi");

    if (client.connect(host, port)) {
        Serial.println("Connected to server");
        client.println("GET /get HTTP/1.1");
        client.println("Host: www.httpbin.org");
        client.println("Connection: close");
        client.println();
    }
}

void loop() {
    if (client.available()) {
        char buffer[64];                  // Buffer to store 64 bytes
        size_t bytesRead = client.readBytes(buffer, 64); // Read exactly 64 bytes
        if (bytesRead > 0) {
            Serial.print("Read ");
            Serial.print(bytesRead);
            Serial.println(" bytes:");
            Serial.write(buffer, bytesRead); // Print the buffer content
            Serial.println();
        } else {
            Serial.println("No data read or timeout occurred.");
        }
    }
    if (!client.connected()) {
        Serial.println("Disconnected from server");
        client.stop();
        while (true); // Stop after disconnect
    }
}