225 lines
5.3 KiB
Markdown
225 lines
5.3 KiB
Markdown
# Eth Module
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2019-06-25 | [Arnim Laeuger](https://github.com/devsaurus) |[Arnim Laeuger](https://github.com/devsaurus) | [eth.c](../../components/modules/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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
-- 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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
|
|
```lua
|
|
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
|
|
```lua
|
|
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.
|