中文文档

A lightweight Arduino library for sending Wake-on-LAN (WOL) and Wake-on-Wireless LAN (WoWLAN) magic packets to wake up network devices (PCs, NAS, servers, etc.) over a local network.

The library is hardware-agnostic — it relies on the standard Arduino UDP interface, making it compatible with a wide range of platforms:

• ESP32 (WiFiUDP)
• Arduino UNO R4 WiFi (WiFiS3 + WiFiUDP)
• Arduino UNO R4 Minima (with Ethernet shield, EthernetUDP)
• Raspberry Pi Pico W (RP2040, arduino-pico core WiFiUDP)
• Raspberry Pi Pico 2 W (RP2350, arduino-pico core WiFiUDP)
• Any other Arduino-compatible board that provides a standard UDP implementation

• Pass MAC address as a string ("00:11:22:33:44:55" or "00-11-22-33-44-55") or a byte array (uint8_t[6]).
• Hardware-agnostic: works with any initialized UDP object (WiFiUDP, EthernetUDP, etc.).
• Customizable broadcast IP address and UDP port (defaults: 255.255.255.255, port 9).

1. Download this repository as a ZIP file.
2. In Arduino IDE, go to Sketch → Include Library → Add .ZIP Library…
3. Select the downloaded ZIP file.

Add the following to your platformio.ini:

lib_deps =
    https://github.com/yourusername/ArduinoWOL.git

#include <Arduino.h>
#include <ArduinoWOL.h>

// Include the appropriate WiFi library for your board
#if defined(ESP32)
  #include <WiFi.h>
  #include <WiFiUdp.h>
#elif defined(ARDUINO_UNOWIFIR4)
  #include <WiFiS3.h>
  #include <WiFiUdp.h>
#elif defined(ARDUINO_ARCH_RP2040)
  // Raspberry Pi Pico W / Pico 2 W
  #include <WiFi.h>
  #include <WiFiUdp.h>
#endif

const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
const char* targetMacAddress = "00:11:22:33:44:55";

WiFiUDP udp;

void setup() {
  Serial.begin(115200);

  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("\nWiFi connected!");

  udp.begin(9);

  if (ArduinoWOL::sendMagicPacket(udp, targetMacAddress)) {
    Serial.println("Magic Packet sent successfully!");
  } else {
    Serial.println("Failed to send Magic Packet.");
  }
}

void loop() {}

static bool ArduinoWOL::sendMagicPacket(
    UDP& udp,
    const char* macAddress,
    IPAddress broadcastIP = IPAddress(255, 255, 255, 255),
    uint16_t port = 9
);

Send a WOL magic packet using a MAC address string.

Returns: true on success, false on failure.

static bool ArduinoWOL::sendMagicPacket(
    UDP& udp,
    const uint8_t* macAddress,
    IPAddress broadcastIP = IPAddress(255, 255, 255, 255),
    uint16_t port = 9
);

Send a WOL magic packet using a 6-byte MAC address array. Parameters are the same as above, except macAddress is a uint8_t[6].

A WOL magic packet is a 102-byte UDP broadcast frame consisting of:

1. 6 bytes of 0xFF (the synchronization stream).
2. 16 repetitions of the target device's 6-byte MAC address.

The target device's network adapter listens for this specific pattern even while the system is in a low-power state, and triggers a wake-up when detected. This works over both wired Ethernet (WOL) and wireless connections (WoWLAN), as long as the target device's BIOS/firmware and OS are configured to support it.

• Verify that Wake-on-LAN is enabled in the target device's BIOS/UEFI and operating system.
• For wired WOL, make sure the network adapter supports WOL and is allowed to wake the system from sleep or shutdown.
• For WoWLAN, confirm that the WiFi chipset, driver, and operating system all support wireless wake-up. Many devices do not fully support it.

• Check that the UDP object has been initialized with udp.begin(...) before calling sendMagicPacket.
• Confirm that the MAC address format is valid, for example 00:11:22:33:44:55 or 00-11-22-33-44-55.
• Make sure the MAC address values are valid hexadecimal bytes in the range 00 to FF.
• Some routers block 255.255.255.255. If that happens, use your subnet broadcast address such as 192.168.1.255.

• Ensure the sender and target are on the same local network or that your network is explicitly configured to forward WOL traffic.
• Check whether your router, access point, or firewall is filtering UDP broadcasts on port 9.
• Try another common WOL port such as 7 or a device-specific port if your environment requires it.
• Use a packet capture tool such as Wireshark on the local network to confirm that the magic packet is actually being broadcast.

MIT