ESP32 WiFi Library – WiFi.setHostname

Home / References / ESP32 Library / WiFi API / Station

Description

The setHostname() method sets the hostname of the ESP32 device, which serves as its unique identifier on the network. This hostname is used by the system and network services to recognize the device.

The hostname should be set before establishing a Wi-Fi connection. It persists across reboots and network connections until explicitly changed.


Syntax and Usage

The method is part of the WiFi class and uses the following syntax:

setHostname(const char* hostname);

This method sets the device’s hostname and returns a boolean indicating success.


Argument(const char*)

  • hostname (const char*) – The desired hostname for the device. Must conform to DNS naming conventions:
    • 63 characters maximum length
    • Allowed characters: letters (a-z), digits (0-9), hyphen (-)
    • Cannot start or end with hyphen
    • Cannot contain consecutive hyphens

Return Value

The method returns a bool value:

  • true – Hostname set successfully
  • false – Failed to set hostname (invalid format)

Common failure reasons include invalid hostname format or attempting to change hostname while connected to a Wi-Fi network.


Example Codes

Example Setting a Custom Hostname

Note: This example demonstrates setting a valid hostname before connecting to a Wi-Fi network. The hostname persists after connection and can be verified using WiFi.getHostname().

/*
 * Author: Avant Maker
 * Date (MM-DD-YY): 02-06-25
 * Version: 1.0
 * Description: This example code demostrates how to use setHostname 
 * method to set a valid hostname before connecting to a Wi-Fi network. 
 * The hostname persists after connection and can be verified using 
 * WiFi.getHostname().
 *
 * 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>

void setup() {
  Serial.begin(115200);
  
  // Set custom hostname
  if (WiFi.setHostname("my_esp32_device")) {
    Serial.println("Hostname set successfully");
  } else {
    Serial.println("Failed to set hostname");
  }

  // Connect to Wi-Fi
  WiFi.begin("your_SSID", "your_PASSWORD");
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connecting to WiFi...");
  }

  // Verify hostname
  Serial.print("Hostname: ");
  Serial.println(WiFi.getHostname());
}

void loop() {
}

AvantMaker Tutorial Suggestion

If you want to learn more about the ESP32’s WiFi capabilities, we’ve created a beginner-friendly guide that explains them in detail. Just click the link below, and you’ll be teleported to that page. It will clear up any confusion you may have while connecting your ESP32 to WiFi or setting it up as a WiFi access point (AP).

ESP32 Essential Guide – Network Section – WiFi Chapter

ESP32 Library Index

ESP32 Arduino Core Library


FAQ

Ready to experiment and explore more about ESP32? Visit our website’s All About ESP32 Resources Hub, packed with tutorials, guides, and tools to inspire your maker journey. Experiment, explore, and elevate your skills with everything you need to master this powerful microcontroller platform!

error: Content is protected !!