DOCSEARCHbyAlgolia
Submit Docs

WakeOnLan

repository·main·Indexed 42 days ago

https://github.com/a7md0/wakeonlan

A lightweight C++ library for ESP8266 and ESP32 that enables devices to send Wake-on-LAN (WOL) magic packets. It supports custom ports, SecureOn passwords, and both manual and automatic broadcast address configuration via the WakeOnLan class.

Tokens
2.2K
Snippets
12
Records
12
Agent score
3%

What's inside WakeOnLan

  1. Install the WakeOnLan library

    main

    Arduino IDE

    1. Navigate to Tools -> Library Manager.
    2. Search for WakeOnLan and install.

    Alternatively, download the repository as a ZIP file and use Sketch -> Include Library -> Add .ZIP Library.

    PlatformIO

    Add the following to your platformio.ini file:

    lib_deps = WakeOnLan

    Or use the git URL:

    lib_deps = https://github.com/a7md0/WakeOnLan.git
    lib_deps = WakeOnLan

  2. Initialize the WakeOnLan class

    main

    The WakeOnLan class requires an instance of WiFiUDP to function. This library is designed for environments where IPAddress, WiFiUDP, and delay classes are available (e.g., ESP8266 or ESP32).

    1. Include WiFiUdp.h and initialize a WiFiUDP object.
    2. Include WakeOnLan.h and pass the WiFiUDP object to the WakeOnLan constructor.
    #include <WiFiUdp.h>
#include <WakeOnLan.h>

WiFiUDP UDP;
WakeOnLan WOL(UDP);

  3. Configure WakeOnLan broadcast and repetition

    main

    You can optionally configure how the magic packet is sent and where it is broadcasted.

    Repeat packets

    Use setRepeat(count, delay_ms) to send the packet multiple times to increase reliability.

    Set broadcast address

    After connecting to WiFi, you can either calculate the broadcast address automatically using the local IP and subnet mask, or set it manually.

    • calculateBroadcastAddress(localIP, subnetMask): Automatically determines the broadcast address.
    • setBroadcastAddress("IP_ADDRESS"): Manually sets the broadcast address as a string.
    WOL.setRepeat(3, 100); // Repeat 3 times with 100ms delay

// Automatic calculation
WOL.calculateBroadcastAddress(WiFi.localIP(), WiFi.subnetMask());

// Manual setting
WOL.setBroadcastAddress("192.168.1.255");

  4. Send WOL using a byte array MAC address

    main

    To send a Wake-on-LAN packet using a raw byte array (uint8_t) representation of the MAC address:

    • sendMagicPacket(MAC, size): Sends a standard magic packet.
    • sendMagicPacket(MAC, size, port): Sends a magic packet on a specific port.
    • sendSecureMagicPacket(MAC, size, SECURE_ON, secureOn_size): Sends a secure packet.
    • sendSecureMagicPacket(MAC, size, SECURE_ON, secureOn_size, port): Sends a secure packet on a specific port.
    uint8_t MAC[6] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xAB};
uint8_t SECURE_ON[6] = {0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54};

WOL.sendMagicPacket(MAC, sizeof(MAC));
WOL.sendMagicPacket(MAC, sizeof(MAC), 7);
WOL.sendSecureMagicPacket(MAC, sizeof(MAC), SECURE_ON, sizeof(SECURE_ON));
WOL.sendSecureMagicPacket(MAC, sizeof(MAC), SECURE_ON, sizeof(SECURE_ON), 7);

  5. Send WOL using a char array MAC address

    main

    To send a Wake-on-LAN packet using a string (char array) representation of the MAC address:

    • sendMagicPacket(MACAddress): Sends a standard magic packet using the default port (9).
    • sendMagicPacket(MACAddress, port): Sends a magic packet using a specific port.
    • sendSecureMagicPacket(MACAddress, secureOn): Sends a packet including the "SecureOn" password (default port 9).
    • sendSecureMagicPacket(MACAddress, secureOn, port): Sends a secure packet using a specific port.
    const char *MACAddress = "01:23:45:67:89:AB";
const char *secureOn = "FE:DC:BA:98:76:54";

WOL.sendMagicPacket(MACAddress); // Default port 9
WOL.sendMagicPacket(MACAddress, 7); // Port 7
WOL.sendSecureMagicPacket(MACAddress, secureOn); // Secure, port 9
WOL.sendSecureMagicPacket(MACAddress, secureOn, 7); // Secure, port 7

  6. Generate a magic packet buffer

    main

    If you need to generate the magic packet bytes without sending them immediately, use generateMagicPacket. You must provide a pre-allocated buffer of sufficient size.

    Buffer Size Calculation

    • Standard Packet: 6 + (6 * 16) bytes (6 bytes of 0xFF + 16 repetitions of the 6-byte MAC).
    • Secure Packet: 6 + (6 * 16) + 6 bytes (Standard packet + 6 bytes for the SecureOn password).
    // Standard generation
size_t magicPacketSize = 6 + (6 * 16);
uint8_t* magicPacket = new uint8_t[magicPacketSize];
uint8_t MAC[6] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xAB};

WOL.generateMagicPacket(magicPacket, magicPacketSize, MAC, sizeof(MAC));

// Secure generation
size_t secureSize = 6 + (6 * 16) + 6;
uint8_t* securePacket = new uint8_t[secureSize];
uint8_t SECURE_ON[6] = {0xFE, 0xDC, 0xBA, 0x98, 0x76, 0x54};

WOL.generateMagicPacket(securePacket, secureSize, MAC, sizeof(MAC), SECURE_ON, sizeof(SECURE_ON));

  7. Calculate the broadcast address from IP and Subnet Mask

    main

    Use calculateBroadcastAddress(IPAddress _ipAddress, IPAddress _subnetMask) to determine the correct broadcast address for a given IP address and subnet mask.

    IPAddress broadcast = wol.calculateBroadcastAddress(IPAddress(192, 168, 1, 50), IPAddress(255, 255, 255, 0));

  8. Configure broadcast address and packet repetition

    main

    You can customize how the magic packets are sent using the following methods:

    • setBroadcastAddress(IPAddress _broadcastAddress): Sets the target broadcast IP address (defaults to 255.255.255.255).
    • setRepeat(uint8_t _repeatPacket, unsigned long _delayPacket): Configures the library to send multiple packets. _repeatPacket is the number of times to repeat the packet, and _delayPacket is the delay in milliseconds between each packet.
    wol.setBroadcastAddress(IPAddress(192, 168, 1, 255));
wol.setRepeat(3, 100); // Send 3 packets with 100ms delay

  9. Initialize the WakeOnLan class

    main

    To use the library, instantiate the WakeOnLan class by passing an existing WiFiUDP instance to its constructor. This instance will be used by the library to send the magic packets over the network.

    WiFiUDP udp;
WakeOnLan wol(udp);

  10. Send a Magic Packet using a byte array MAC address

    main

    If your MAC address is stored in a byte array, use the following method:

    • sendMagicPacket(uint8_t* pMacAddress, size_t sizeOfMacAddress, uint16_t portNum = 9)

    Returns true if the packet was sent successfully.

    uint8_t mac[] = {0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF};
wol.sendMagicPacket(mac, 6);

  11. Send a Secure Magic Packet

    main

    The library supports sending 'Secure Magic Packets' which include an additional security payload. You can provide the security string or byte array to be included.

    Using Strings:

    • sendSecureMagicPacket(String _macString, String _secureOn, uint16_t _portNum = 9)
    • sendSecureMagicPacket(const char* _macAddress, const char* _secureOn, uint16_t _portNum = 9)

    Using Byte Arrays:

    • sendSecureMagicPacket(uint8_t* pMacAddress, size_t sizeOfMacAddress, uint8_t* pSecureOn, size_t sizeOfSecureOn, uint16_t portNum = 9)
    wol.sendSecureMagicPacket("AA:BB:CC:DD:EE:FF", "mySecretKey");

  12. Send a Magic Packet using a MAC address string

    main

    The library provides several overloads to send a standard Magic Packet using a MAC address provided as a String or a const char* (e.g., "AA:BB:CC:DD:EE:FF"). You can optionally specify a _portNum (defaults to 9).

    Methods:

    • sendMagicPacket(String _macString, uint16_t _portNum = 9)
    • sendMagicPacket(const char* _macAddress, uint16_t _portNum = 9)
    wol.sendMagicPacket("AA:BB:CC:DD:EE:FF");
// OR
wol.sendMagicPacket("AA:BB:CC:DD:EE:FF", 7);