nodemcu-firmware/docs/modules/eth.md

Eth Module

Since	Origin / Contributor	Maintainer	Source
2019-06-25	Arnim Laeuger	Arnim Laeuger	eth.c

The eth module provides access to the ethernet PHY chip configuration.

Your board must contain one of the PHY chips that are supported by ESP-IDF:

• IP101
• RTL8201
• LAN8720 (possibly others in the LAN87xx family)
• DP83848
• KSZ8001 / KSZ8021 / KSZ8031 / KSZ8041 / KSZ8051 / KSZ8061 / KSZ8081 / KSZ8091

eth.get_mac()

Get MAC address.

Syntax

local mac = eth.get_mac()

Parameters

None

Returns

MAC address as string "aa:bb:cc:dd:ee:dd".

eth.get_speed()

Get Ethernet connection speed.

Syntax

local speed = eth.get_speed()

Parameters

None

Returns

Connection speed in Mbit/s, or error if not connected.

• 10
• 100

eth.init()

Initialize the internal ethernet interface by configuring the MAC and PHY and starting the interface.

Note that while the PHY model and some GPIO pins are configured at runtime, the clock configuration has been moved into the menuconfig and is no longer available at runtime. Please refer to the settings available under Component config -> Ethernet -> Support ESP32 internal EMAC controller.

Syntax

eth.init(cfg)

Parameters

• cfg table containing configuration data. Unless otherwise noted, the entries are mandatory:
  • addr PHY address, 0 to 31, optional (default will attempt auto-detect)
  • mdc MDC pin number
  • mdio MDIO pin number
  • phy PHY chip model, one of
    • PHY_DP83848
    • PHY_IP101
    • PHY_KSZ80XX
    • PHY_KSZ8041 (deprecated, use PHY_KSZ80XX instead)
    • PHY_KSZ8081 (deprecated, use PHY_KSZ80XX instead)
    • PHY_LAN87XX
    • PHY_LAN8720 (deprecated, use PHY_LAN87XX instead)
    • PHY_RTL8201
  • power power enable pin, optional

Returns

nil

An error is thrown in case of invalid parameters, MAC/PHY setup errors, or if the ethernet interface has already been successfully configured.

Example

-- Initialize ESP32-GATEWAY
eth.init({phy  = eth.PHY_LAN8720,
          addr = 0,
          power = 5,
          mdc   = 23,
          mdio  = 18})

-- Initialize wESP32
eth.init({phy  = eth.PHY_LAN8720,
          addr = 0,
          mdc   = 16,
          mdio  = 17})


-- Initialise wt32-eth01
eth.init({ phy = eth.PHY_LAN8720, addr = 1, mdc = 23, mdio = 18, power = 16 })

eth.on()

Register or unregister callback functions for Ethernet events.

Syntax

eth.on(event, callback)

Parameters

• event Ethernet event to register the callback for:
  • "start"
  • "stop"
  • "connected"
  • "disconnected"
  • "got_ip"
• callback callback function(event, info) to perform when event occurs, or nil to unregister the callback for the event. The info argument given to the callback is a table containing additional information about the event.

Event information provided for each event is as follows:

• start: no additional info
• stop: no additional info
• connected: no additional info
• disconnected: no additional info
• got_ip: IP network information:
  • ip: the IP address assigned
  • netmask: the IP netmask
  • gw: the gateway ("0.0.0.0" if no gateway)

Example

function ev(event, info)
    print("event", event)
    if event == "got_ip" then
        print("ip:"..info.ip..", nm:"..info.netmask..", gw:"..info.gw)
    elseif event == "connected" then
        print("speed:", eth.get_speed())
        print("mac:", eth.get_mac())
    end
end

eth.on("connected", ev)
eth.on("disconnected", ev)
eth.on("start", ev)
eth.on("stop", ev)
eth.on("got_ip", ev)

eth.set_mac()

Set MAC address.

Syntax

eth.set_mac(mac)

Parameters

• mac MAC address as string "aa:bb:cc:dd:ee:ff"

Returns

nil

An error is thrown in case of invalid parameters or if the ethernet driver failed.

eth.set_ip()

Configures a static IPv4 address on the ethernet interface.

Calling this function does three things:

• disables the DHCP client for the ethernet interface
• sets the IP address, netmask and gateway
• set the DNS server to use

Note that these settings are not persisted to flash.

Syntax

eth.set_ip(cfg_opts)

Parameters

• cfg_opts - table with the following fields:
  • ip static IPv4 address to set
  • netmask the network netmask
  • gateway default gateway to use
  • dns DNS server

Returns

nil

An error is thrown in case of invalid parameters or if any of the options can not be set.

Example

eth.set_ip({
  ip = "192.168.0.12",
  netmask = "255.255.255.0",
  gateway = "192.168.0.1",
  dns = "8.8.8.8"
})

eth.set_hostname()

Configures the interface specific hostname for the ethernet interface. The ethernet interface must be initialized before the hostname can be configured.

By default the system hostname is used, as configured in the menu config.

Syntax

eth.set_hostname(hostname)

Parameters

• hostname the hostname to use on the ethernet interface

Returns

nil

An error is thrown in case the hostname cannot be set.