描述

初始化以太网库和网络设置。

在1.0版本中，库支持DHCP。使用Ethernet.begin(mac)并进行适当的网络设置，以太网扩展板将自动获取IP地址。这会显著增加草图大小。为了确保在需要时正确续租DHCP租约，请务必定期调用Ethernet.maintain()。

语法

Ethernet.begin(mac);
Ethernet.begin(mac, ip);
Ethernet.begin(mac, ip, dns);
Ethernet.begin(mac, ip, dns, gateway);
Ethernet.begin(mac, ip, dns, gateway, subnet);

参数

• mac: 设备的MAC（媒体访问控制）地址（6字节数组）。这是扩展板的以太网硬件地址。较新的Arduino以太网扩展板包含有设备MAC地址的标签。对于较旧的扩展板，请自行选择。
• ip: 设备的IP地址（4字节数组）
• dns: DNS服务器的IP地址（4字节数组）。可选：默认为设备IP地址，最后一个八位字节设置为1
• gateway: 网络网关的IP地址（4字节数组）。可选：默认为设备IP地址，最后一个八位字节设置为1
• subnet: 网络的子网掩码（4字节数组）。可选：默认为255.255.255.0

返回值

• 该函数的DHCP版本，Ethernet.begin(mac)，返回一个int：成功的DHCP连接返回1，失败返回0。
• 其他版本不返回任何值。

示例

#include <SPI.h>
#include <Ethernet.h>

// 扩展板的媒体访问控制（以太网硬件）地址：
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };  
// 扩展板的IP地址：
byte ip[] = { 10, 0, 0, 177 };  

void setup()
{
  Ethernet.begin(mac, ip);
}

void loop () {}

描述

返回设备的DNS服务器IP地址。

语法

Ethernet.dnsServerIP()

参数

无

返回值

设备的DNS服务器IP地址（IPAddress）。

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串口连接。仅对原生USB端口需要
  }

  Ethernet.begin(mac, ip);

  Serial.print("DNS服务器的IP地址是: ");
  Serial.println(Ethernet.dnsServerIP());
}

void loop () {}

描述
返回设备的网关IP地址。

语法
Ethernet.gatewayIP()

参数
无

返回值
设备的网关IP地址（IPAddress）。

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串口连接，仅对原生USB端口有效
  }

  Ethernet.begin(mac, ip);

  Serial.print("网关IP地址是: ");
  Serial.println(Ethernet.gatewayIP());
}

void loop () {}

描述

Ethernet.hardwareStatus() 告诉你在 Ethernet.begin() 过程中检测到的 WIZnet 以太网控制器芯片（如果有的话）。这可以用于故障排除。如果未检测到以太网控制器，则可能存在硬件问题。

语法

Ethernet.hardwareStatus()

参数
无

返回值

• 在 Ethernet.begin() 过程中检测到的 WIZnet 以太网控制器芯片（EthernetHardwareStatus）：

EthernetNoHardware
EthernetW5100
EthernetW5200
EthernetW5500

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  // 打开串口通信并等待端口打开：
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串口连接，仅对原生USB端口有效
  }

  Ethernet.begin(mac, ip);

  if (Ethernet.hardwareStatus() == EthernetNoHardware) {
    Serial.println("未找到以太网扩展板。");
  } else if (Ethernet.hardwareStatus() == EthernetW5100) {
    Serial.println("检测到 W5100 以太网控制器。");
  } else if (Ethernet.hardwareStatus() == EthernetW5200) {
    Serial.println("检测到 W5200 以太网控制器。");
  } else if (Ethernet.hardwareStatus() == EthernetW5500) {
    Serial.println("检测到 W5500 以太网控制器。");
  }
}

void loop () {}

描述

用于配置以太网控制器芯片的 CS（片选）引脚。以太网库有一个默认的 CS 引脚，通常是正确的，但对于某些非标准的以太网硬件，你可能需要使用不同的 CS 引脚。

语法

Ethernet.init(sspin)

参数

• sspin: 用于 CS 的引脚号（byte）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Ethernet.init(53);  // 使用引脚 53 作为以太网的 CS
  Ethernet.begin(mac, ip);
}

void loop () {}

描述

告诉你链路是否激活。LinkOFF 可能表示以太网电缆已拔出或有缺陷。此功能仅在使用 W5200 和 W5500 以太网控制器芯片时可用。

语法

Ethernet.linkStatus()

参数
无

返回值

• 链路状态（EthernetLinkStatus）：

  • Unknown
  • LinkON
  • LinkOFF

示例

#include <SPI.h>
#include <Ethernet.h>

void setup() {
  // 打开串口通信并等待端口打开：
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串口连接，仅对原生USB端口有效
  }
}

void loop() {
  if (Ethernet.linkStatus() == Unknown) {
    Serial.println("链路状态未知。链路状态检测仅在 W5200 和 W5500 可用。");
  } else if (Ethernet.linkStatus() == LinkON) {
    Serial.println("链路状态：开");
  } else if (Ethernet.linkStatus() == LinkOFF) {
    Serial.println("链路状态：关");
  }
}

描述

获取以太网扩展板的 IP 地址。当地址是通过 DHCP 自动分配时非常有用。

语法

Ethernet.localIP();

参数
无

返回值

• IP 地址

示例

#include <SPI.h>
#include <Ethernet.h>

// 为你的控制器输入一个 MAC 地址。
// 较新的以太网扩展板上有一个 MAC 地址贴纸
byte mac[] = {  
  0x00, 0xAA, 0xBB, 0xCC, 0xDE, 0x02 };

// 初始化以太网客户端库
// 使用你想要连接的服务器的 IP 地址和端口
// 端口 80 是 HTTP 的默认端口：
EthernetClient client;

void setup() {
  // 启动串口库：
  Serial.begin(9600);
  // 启动以太网连接：
  if (Ethernet.begin(mac) == 0) {
    Serial.println("通过 DHCP 配置以太网失败");
    // 无法继续，进入无限循环：
    for (;;)
      ;
  }
  // 打印你的本地 IP 地址：
  Serial.println(Ethernet.localIP());

}

void loop() {

}

描述

将设备的 MAC 地址填充到提供的缓冲区中。

语法

Ethernet.MACAddress(mac_address)

参数

• mac_address: 接收 MAC 地址的缓冲区（6 字节数组）

返回值
无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串口连接，仅对原生USB端口有效
  }

  Ethernet.begin(mac, ip);

  byte macBuffer[6];  // 创建一个缓冲区来保存 MAC 地址
  Ethernet.MACAddress(macBuffer); // 填充缓冲区
  Serial.print("MAC 地址是: ");
  for (byte octet = 0; octet < 6; octet++) {
    Serial.print(macBuffer[octet], HEX);
    if (octet < 5) {
      Serial.print('-');
    }
  }
}

void loop () {}

描述

允许续租 DHCP 租约。当通过 DHCP 分配 IP 地址时，以太网设备会获得一个租约，有效时间内可以占用该地址。使用 Ethernet.maintain()，可以向 DHCP 服务器请求续租。根据服务器的配置，你可能会收到相同的地址、新的地址，或者根本没有地址。

你可以随时调用此函数，它只会在需要时重新请求 DHCP 租约（在其他情况下返回 0）。最简单的方法是每次 loop() 调用时都调用它，但调用频率低一些也没有问题。不调用此函数（或每秒调用次数明显少于一次）将导致无法在 DHCP 协议要求时续租，并继续使用过期的租约（这不会直接断开连接，但如果 DHCP 服务器将相同地址租给其他人，连接可能会中断）。

Ethernet.maintain() 于 Arduino 1.0.1 中添加。

语法

Ethernet.maintain();

参数
无

返回值

byte:

• 0: 没有发生任何事情
• 1: 续租失败
• 2: 续租成功
• 3: 重绑定失败
• 4: 重绑定成功

描述

设置 DNS 服务器的 IP 地址。不适用于 DHCP。

语法

Ethernet.setDnsServerIP(dns_server)

参数

• dns_server: DNS 服务器的 IP 地址（IPAddress）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);
IPAddress myDns(192, 168, 1, 1);

void setup() {
  Ethernet.begin(mac, ip, myDns);
  IPAddress newDns(192, 168, 1, 1);
  Ethernet.setDnsServerIP(newDns);  // 更改 DNS 服务器 IP 地址
}

void loop () {}

描述

设置网络网关的 IP 地址。不适用于 DHCP。

语法

Ethernet.setGatewayIP(gateway)

参数

• gateway: 网络网关的 IP 地址（IPAddress）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);
IPAddress myDns(192, 168, 1, 1);
IPAddress gateway(192, 168, 1, 1);

void setup() {
  Ethernet.begin(mac, ip, myDns, gateway);
  IPAddress newGateway(192, 168, 100, 1);
  Ethernet.setGatewayIP(newGateway);  // 更改网关 IP 地址
}

void loop () {}

描述

设置设备的 IP 地址。不适用于 DHCP。

语法

Ethernet.setLocalIP(local_ip)

参数

• local_ip: 要使用的 IP 地址（IPAddress）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Ethernet.begin(mac, ip);
  IPAddress newIp(10, 0, 0, 178);
  Ethernet.setLocalIP(newIp);  // 更改 IP 地址
}

void loop () {}

描述

设置 MAC 地址。不适用于 DHCP。

语法

Ethernet.setMACAddress(mac)

参数

• mac: 要使用的 MAC 地址（6 字节数组）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Ethernet.begin(mac, ip);
  byte newMac[] = {0x00, 0xAA, 0xBB, 0xCC, 0xDE, 0x02};
  Ethernet.setMACAddress(newMac);  // 更改 MAC 地址
}

void loop () {}

描述

设置以太网控制器在放弃前的传输尝试次数。初始值为8。8次传输尝试乘以200毫秒的默认超时，在通讯失败期间等于1600毫秒的阻塞延迟。如果通信出现问题，你可能希望设置较低的次数以使程序更迅速地响应。尽管名字如此，这实际上设置的是传输尝试的总次数（而不是第一次尝试失败后的重试次数），所以你最少需要设置的值是1。

语法

Ethernet.setRetransmissionCount(number)

参数

• number: 以太网控制器在放弃前应该尝试的传输次数（byte）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Ethernet.begin(mac, ip);
  Ethernet.setRetransmissionCount(1);  // 配置以太网控制器在放弃前只尝试一次传输
}

void loop () {}

描述

设置以太网控制器的超时时间。初始值为200毫秒。200毫秒的超时时间乘以默认的8次尝试，在通讯失败期间等于1600毫秒的阻塞延迟。如果通信出现问题，你可能希望设置较短的超时时间以使程序更迅速地响应。你需要进行一些实验来确定适合你特定应用的值。

语法

Ethernet.setRetransmissionTimeout(milliseconds)

参数

• milliseconds: 超时时间（uint16_t）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Ethernet.begin(mac, ip);
  Ethernet.setRetransmissionTimeout(50);  // 将以太网控制器的超时时间设置为50毫秒
}

void loop () {}

描述

设置网络的子网掩码。不适用于 DHCP。

语法

Ethernet.setSubnetMask(subnet)

参数

• subnet: 网络的子网掩码（IPAddress）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);
IPAddress myDns(192, 168, 1, 1);
IPAddress gateway(192, 168, 1, 1);
IPAddress subnet(255, 255, 0, 0);

void setup() {
  Ethernet.begin(mac, ip, myDns, gateway, subnet);
  IPAddress newSubnet(255, 255, 255, 0);
  Ethernet.setSubnetMask(newSubnet);  // 更改子网掩码
}

void loop () {}

描述

返回设备的子网掩码。

语法

Ethernet.subnetMask()

参数
无

返回值

• 设备的子网掩码（IPAddress）

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

void setup() {
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串口连接，仅对原生USB端口有效
  }

  Ethernet.begin(mac, ip);

  Serial.print("子网掩码是: ");
  Serial.println(Ethernet.subnetMask());
}

void loop () {}

描述

定义一个 IP 地址。它可以用于声明本地和远程地址。

语法

IPAddress(address);

参数

• address: 逗号分隔的地址列表（4 字节，例如 192, 168, 1, 1）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

// 网络配置。dns 服务器、网关和子网是可选的。

// 扩展板的媒体访问控制（以太网硬件）地址：
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };

// dns 服务器 IP
IPAddress dnServer(192, 168, 0, 1);
// 路由器的网关地址：
IPAddress gateway(192, 168, 0, 1);
// 子网：
IPAddress subnet(255, 255, 255, 0);

// IP 地址取决于你的网络
IPAddress ip(192, 168, 0, 2);

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

  // 初始化以太网设备
  Ethernet.begin(mac, ip, dnServer, gateway, subnet);
  // 打印出 IP 地址
  Serial.print("IP = ");
  Serial.println(Ethernet.localIP());
}

void loop() {
}

描述

Server 是所有基于以太网服务器调用的基类。它不会被直接调用，而是在你使用依赖于它的函数时被调用。

描述

创建一个在指定端口上监听传入连接的服务器。

语法

Server(port);

参数

• port: 监听的端口（int）

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

// 网络配置。网关和子网是可选的。

// 扩展板的媒体访问控制（以太网硬件）地址：
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };  
// 扩展板的 IP 地址：
byte ip[] = { 10, 0, 0, 177 };  
// 路由器的网关地址：
byte gateway[] = { 10, 0, 0, 1 };
// 子网：
byte subnet[] = { 255, 255, 0, 0 };

// telnet 默认使用端口 23
EthernetServer server = EthernetServer(23);

void setup() {
  // 初始化以太网设备
  Ethernet.begin(mac, ip, gateway, subnet);

  // 开始监听客户端
  server.begin();
}

void loop() {
  // 如果一个传入的客户端连接，有可读的字节：
  EthernetClient client = server.available();
  if (client == true) {
    // 从传入的客户端读取字节并将其写回给
    // 任何连接到服务器的客户端：
    server.write(client.read());
  }
}

描述

通知服务器开始监听传入的连接。

语法

server.begin()

参数

无

返回值

无

示例

#include <SPI.h>
#include <Ethernet.h>

// 以太网硬件地址（MAC地址）:
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };  
// 以太网上的IP地址:
byte ip[] = { 10, 0, 0, 177 };  
// 路由器的网关地址:
byte gateway[] = { 10, 0, 0, 1 };
// 子网掩码:
byte subnet[] = { 255, 255, 0, 0 };

// telnet 默认为 23 端口
EthernetServer server = EthernetServer(23);

void setup()
{
  // 初始化以太网设备
  Ethernet.begin(mac, ip, gateway, subnet);

  // 开始监听客户端连接
  server.begin();
}

void loop()
{
  // 如果有客户端连接进来，会有可读取的字节:
  EthernetClient client = server.available();
  if (client == true) {
    // 读取来自连接客户端的字节，并将其写回到任意连接到服务器的客户端:
    server.write(client.read());
  }
}

描述

传统的 server.available() 函数仅会在客户端发送数据后通知你有新连接，这使得某些协议（如 FTP）无法正确实现。

设计目的是程序要么使用 available()，要么使用 accept()，但不能同时使用。使用 available() 时，客户端连接继续由 EthernetServer 管理。你不需要保持一个客户端对象，因为调用 available() 会返回任何已发送数据的客户端。可以使用很少的代码编写简单的服务器。

使用 accept() 时，EthernetServer 只会给你一次客户端对象，不论它是否发送了任何数据。你必须跟踪连接的客户端。这需要更多代码，但你会获得更多控制。

语法

server.accept()

参数

无

返回值

• 一个 Client 对象。如果没有客户端有可读取的数据，该对象在 if 语句中将判断为 false。（EthernetClient）

示例

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(192, 168, 69, 104);

// telnet 默认为 23 端口
EthernetServer server(23);

EthernetClient clients[8];

void setup() {
  Ethernet.begin(mac, ip);

  // 打开串行通信并等待端口打开:
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串行端口连接。仅对原生 USB 端口需要
  }

  // 开始监听客户端
  server.begin();
}

void loop() {
  // 检查是否有新客户端连接，并在任何传入数据前打招呼
  EthernetClient newClient = server.accept();
  if (newClient) {
    for (byte i = 0; i < 8; i++) {
      if (!clients[i]) {
        newClient.print("Hello, client number: ");
        newClient.println(i);
        // 一旦我们 "accept"，客户端不再由 EthernetServer 跟踪
        // 因此必须将其存储到我们的客户端列表中
        clients[i] = newClient;
        break;
      }
    }
  }

  // 检查所有客户端的传入数据
  for (byte i = 0; i < 8; i++) {
    while (clients[i] && clients[i].available() > 0) {
      // 读取客户端的传入数据
      Serial.write(clients[i].read());
    }
  }

  // 停止任何断开的客户端
  for (byte i = 0; i < 8; i++) {
    if (clients[i] && !clients[i].connected()) {
      clients[i].stop();
    }
  }
}

描述

获取一个已连接到服务器并有可读取数据的客户端。当返回的客户端对象超出其作用域时，连接仍然持续；你可以通过调用 client.stop() 来关闭它。

语法

server.available()

参数

无

返回值

• 一个客户端对象；如果没有客户端有可读取的数据，该对象在 if 语句中将判断为 false（见下面的示例）

示例

#include <Ethernet.h>
#include <SPI.h>

// 以太网硬件地址（MAC 地址）:
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };  
// 以太网上的 IP 地址:
byte ip[] = { 10, 0, 0, 177 };  
// 路由器的网关地址:
byte gateway[] = { 10, 0, 0, 1 };
// 子网掩码:
byte subnet[] = { 255, 255, 0, 0 };

// telnet 默认为 23 端口
EthernetServer server = EthernetServer(23);

void setup()
{
  // 初始化以太网设备
  Ethernet.begin(mac, ip, gateway, subnet);

  // 开始监听客户端
  server.begin();
}

void loop()
{
  // 如果有客户端连接进来，会有可读取的字节:
  EthernetClient client = server.available();
  if (client) {
    // 读取来自连接客户端的字节，并将其写回到任意连接到服务器的客户端:
    server.write(client.read());
  }
}

描述

表示服务器是否正在监听新客户端。你可以用这个来检测server.begin()是否成功。它还可以告诉你当没有更多的套接字可用于监听更多客户端时的情况，因为已经连接了最大数量的客户端。

语法

if(server)

参数

无

返回值

• 服务器是否正在监听新客户端(布尔值)。

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

// telnet默认使用23端口
EthernetServer server = EthernetServer(23);

void setup() {
  // 打开串行通信并等待端口打开：
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串行端口连接。仅对本机USB端口需要
  }

  // 初始化以太网设备
  Ethernet.begin(mac, ip);

  // 开始监听客户端
  server.begin();
}

void loop() {
  if (server) {
    Serial.println("服务器正在监听");
  }
  else {
    Serial.println("服务器没有在监听");
  }
}

描述

向连接到服务器的所有客户端写入数据。这些数据以单个字节或一系列字节的形式发送。

语法

server.write(val)
server.write(buf, len)

参数

• val: 作为单个字节发送的值（byte或char类型）
• buf: 作为一系列字节发送的数组（byte或char类型）
• len: 缓冲区的长度

返回值

• byte类型
• write()返回已写入的字节数。通常不需要读取这个返回值。

示例

#include <SPI.h>
#include <Ethernet.h>

// 网络配置。网关和子网掩码是可选的。

 // 屏蔽的媒体访问控制（以太网硬件）地址：
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };  
// 屏蔽的IP地址：
byte ip[] = { 10, 0, 0, 177 };  
// 路由器的网关地址：
byte gateway[] = { 10, 0, 0, 1 };
// 子网掩码：
byte subnet[] = { 255, 255, 0, 0 };

// telnet默认使用23端口
EthernetServer server = EthernetServer(23);

void setup()
{
  // 初始化以太网设备
  Ethernet.begin(mac, ip, gateway, subnet);

  // 开始监听客户端
  server.begin();
}

void loop()
{
  // 如果有新的客户端连接，将有可读取的字节：
  EthernetClient client = server.available();
  if (client == true) {
    // 从传入的客户端读取字节，并将它们写回
    // 到连接到服务器的任何客户端：
    server.write(client.read());
  }
}

描述

向连接到服务器的所有客户端打印数据。将数字作为一系列数字打印，每个数字都是一个ASCII字符（例如，数字123被发送为三个字符'1'、'2'、'3'）。

语法

server.print(data)
server.print(data, BASE)

参数

• data: 要打印的数据（char、byte、int、long或string类型）
• BASE（可选）：打印数字的进制：BIN表示二进制（基数2），DEC表示十进制（基数10），OCT表示八进制（基数8），HEX表示十六进制（基数16）。

返回值

• byte类型
• print()将返回已写入的字节数，但读取这个数字是可选的

描述

向连接到服务器的所有客户端打印数据，然后跟随一个换行符。将数字作为一系列数字打印，每个数字都是一个ASCII字符（例如，数字123被发送为三个字符'1'、'2'、'3'）。

语法

server.println()
server.println(data)
server.println(data, BASE)

参数

• data（可选）：要打印的数据（char、byte、int、long或string类型）
• BASE（可选）：打印数字的进制：BIN表示二进制（基数2），DEC表示十进制（基数10），OCT表示八进制（基数8），HEX表示十六进制（基数16）。

返回值

• byte类型
• println()将返回已写入的字节数，但读取这个数字是可选的

描述

Client是所有基于以太网客户端调用的基类。它不会被直接调用，而是在你使用依赖于它的函数时被调用。

描述

创建一个可以连接到指定互联网IP地址和端口（在client.connect()函数中定义）的客户端。

语法

EthernetClient()

参数

无

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google

EthernetClient client;

void setup()
{
  Ethernet.begin(mac, ip);
  Serial.begin(9600);

  delay(1000);

  Serial.println("正在连接...");

  if (client.connect(server, 80)) {
    Serial.println("已连接");
    client.println("GET /search?q=arduino HTTP/1.0");
    client.println();
  } else {
    Serial.println("连接失败");
  }
}

void loop()
{
  if (client.available()) {
    char c = client.read();
    Serial.print(c);
  }

  if (!client.connected()) {
    Serial.println();
    Serial.println("正在断开连接。");
    client.stop();
    for(;;)
      ;
  }
}

描述

指示指定的以太网客户端是否就绪。

语法

if (client)

参数

无

返回值

• 布尔值：如果指定的客户端可用，则返回true。

示例

#include <Ethernet.h>
#include <SPI.h>


byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google

EthernetClient client;

void setup()
{
  Ethernet.begin(mac, ip);
  Serial.begin(9600);

  delay(1000);

  Serial.println("正在连接...");
  while(!client){
    ; // 等待直到有客户端连接才继续
  }
  if (client.connect(server, 80)) {
    Serial.println("已连接");
    client.println("GET /search?q=arduino HTTP/1.0");
    client.println();
  } else {
    Serial.println("连接失败");
  }
}

void loop()
{
  if (client.available()) {
    char c = client.read();
    Serial.print(c);
  }

  if (!client.connected()) {
    Serial.println();
    Serial.println("正在断开连接。");
    client.stop();
    for(;;)
      ;
  }
}

描述

客户端是否已连接。注意，如果连接已关闭但仍有未读数据，客户端也被视为已连接。

语法

client.connected()

参数

无

返回值

• 如果客户端已连接，返回true；否则返回false。

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google

EthernetClient client;

void setup()
{
  Ethernet.begin(mac, ip);
  Serial.begin(9600);
  client.connect(server, 80);
  delay(1000);

  Serial.println("正在连接...");

  if (client.connected()) {
    Serial.println("已连接");
    client.println("GET /search?q=arduino HTTP/1.0");
    client.println();
  } else {
    Serial.println("连接失败");
  }
}

void loop()
{
  if (client.available()) {
    char c = client.read();
    Serial.print(c);
  }

  if (!client.connected()) {
    Serial.println();
    Serial.println("正在断开连接。");
    client.stop();
    for(;;)
      ;
  }
}

描述

连接到指定的IP地址和端口。返回值表示连接成功或失败。在使用域名时也支持DNS查找。

语法

client.connect(ip, port)
client.connect(servername, port)

参数

• ip: 客户端将连接到的IP地址（4字节数组）
• servername: 客户端将连接到的域名（字符串，例如："arduino.cc"）
• port: 客户端将连接到的端口（整数）

返回值

• 如果连接成功返回true，否则返回false。

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google

EthernetClient client;

void setup()
{
  Ethernet.begin(mac, ip);
  Serial.begin(9600);

  delay(1000);

  Serial.println("正在连接...");

  if (client.connect(server, 80)) {
    Serial.println("已连接");
    client.println("GET /search?q=arduino HTTP/1.0");
    client.println();
  } else {
    Serial.println("连接失败");
  }
}

void loop()
{
  if (client.available()) {
    char c = client.read();
    Serial.print(c);
  }

  if (!client.connected()) {
    Serial.println();
    Serial.println("正在断开连接。");
    client.stop();
    for(;;)
      ;
  }
}

描述

返回客户端连接的本地端口号。

语法

client.localPort

参数

无

返回值

• 客户端连接的本地端口号（uint16_t类型）。

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

// telnet默认使用23端口
EthernetServer server = EthernetServer(23);

void setup() {
  // 打开串行通信并等待端口打开：
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串行端口连接。仅适用于本机USB端口
  }

  // 初始化以太网设备
  Ethernet.begin(mac, ip);

  // 开始监听客户端
  server.begin();
}

void loop() {
  // 如果有新的客户端连接，将有可读取的字节：
  EthernetClient client = server.available();
  if (client) {
    Serial.print("客户端连接的端口是：");
    Serial.println(client.localPort());
    client.stop();
  }
}

描述

返回客户端的IP地址。

语法

client.remoteIP()

参数

无

返回值

• 客户端的IP地址（IPAddress类型）。

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

// telnet默认使用23端口
EthernetServer server = EthernetServer(23);

void setup() {
  // 打开串行通信并等待端口打开：
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串行端口连接。仅适用于本机USB端口
  }

  // 初始化以太网设备
  Ethernet.begin(mac, ip);

  // 开始监听客户端
  server.begin();
}

void loop() {
  // 如果有新的客户端连接，将有可读取的字节：
  EthernetClient client = server.available();
  if (client) {
    Serial.print("远程IP地址：");
    Serial.println(client.remoteIP());
    client.stop();
  }
}

描述

返回发送当前传入数据包的主机的端口。

语法

client.remotePort()

参数

无

返回值

• 发送当前传入数据包的主机的端口（uint16_t类型）。

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

// telnet默认使用23端口
EthernetServer server = EthernetServer(23);

void setup() {
  // 打开串行通信并等待端口打开：
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串行端口连接。仅适用于本机USB端口
  }

  // 初始化以太网设备
  Ethernet.begin(mac, ip);

  // 开始监听客户端
  server.begin();
}

void loop() {
  // 如果有新的客户端连接，将有可读取的字节：
  EthernetClient client = server.available();
  if (client) {
    Serial.print("远程端口：");
    Serial.println(client.remotePort());
    client.stop();
  }
}

描述

设置client.connect()和client.stop()的超时时间。初始值为1000毫秒。你可能更倾向于设置一个较低的超时值，以便在出现问题时使你的程序反应更迅速。

语法

client.setConnectionTimeout(milliseconds)

参数

• milliseconds：client.connect()和client.stop()的超时时长（uint16_t类型）

返回值

无

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};
IPAddress ip(10, 0, 0, 177);

// telnet默认使用23端口
EthernetServer server = EthernetServer(23);

void setup() {
  // 打开串行通信并等待端口打开：
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串行端口连接。仅适用于本机USB端口
  }

  // 初始化以太网设备
  Ethernet.begin(mac, ip);

  // 开始监听客户端
  server.begin();
}

void loop() {
  // 如果有新的客户端连接，将有可读取的字节：
  EthernetClient client = server.available();
  if (client) {
    client.setConnectionTimeout(100);  // 设置client.connect()和client.stop()的超时时长
  }
}

描述

向客户端连接的服务器写入数据。这些数据以单个字节或一系列字节的形式发送。

语法

client.write(val)
client.write(buf, len)

参数

• val: 作为单个字节发送的值（byte或char类型）
• buf: 作为一系列字节发送的数组（byte或char类型）
• len: 缓冲区的长度

返回值

byte类型:

• write()返回已写入的字节数。读取这个值并非必要。

描述

将数据打印到客户端连接的服务器。以一系列数字的形式打印数字，每个数字都是一个ASCII字符（例如，数字123被发送为三个字符'1'、'2'、'3'）。

语法

client.print(data)
client.print(data, BASE)

参数

• data: 要打印的数据（字符、字节、整数、长整数或字符串）
• BASE（可选）：打印数字的进制：DEC表示十进制（以10为基数），OCT表示八进制（以8为基数），HEX表示十六进制（以16为基数）。

返回值

• byte: 返回写入的字节数，虽然读取该数字是可选的

描述

将数据打印到客户端连接的服务器，后跟回车符和换行符。以一系列数字的形式打印数字，每个数字都是一个ASCII字符（例如，数字123被发送为三个字符'1'、'2'、'3'）。

语法

client.println()
client.println(data)
client.print(data, BASE)

参数

• data（可选）：要打印的数据（字符、字节、整数、长整数或字符串）
• BASE（可选）：打印数字的进制：DEC表示十进制（以10为基数），OCT表示八进制（以8为基数），HEX表示十六进制（以16为基数）。

返回值

• byte: 返回写入的字节数，虽然读取该数字是可选的

描述

返回可供读取的字节数（即服务器向其连接的客户端写入的数据量）。

available() 继承自 Stream 实用类。

语法

client.available()

参数

无

返回值

• 可用的字节数。

示例

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google

EthernetClient client;

void setup()
{
  Ethernet.begin(mac, ip);
  Serial.begin(9600);

  delay(1000);

  Serial.println("connecting...");

  if (client.connect(server, 80)) {
    Serial.println("connected");
    client.println("GET /search?q=arduino HTTP/1.0");
    client.println();
  } else {
    Serial.println("connection failed");
  }
}

void loop()
{
  if (client.available()) {
    char c = client.read();
    Serial.print(c);
  }

  if (!client.connected()) {
    Serial.println();
    Serial.println("disconnecting.");
    client.stop();
    for(;;)
      ;
  }
}

描述

读取从客户端连接的服务器接收到的下一个字节（在上一次调用 read() 之后）。

read() 继承自 Stream 实用类。

语法

client.read()

参数

无

返回值

• 下一个字节（或字符），如果没有可用字节则返回 -1。

描述

等待直到缓冲区中所有待发送的字符都已被发送。

flush() 继承自 Stream 实用类。

语法

client.flush()

参数

无

返回值

无

描述

断开与服务器的连接。

语法

client.stop()

参数

无

返回值

无

描述
初始化以太网 UDP 库和网络设置。

语法
EthernetUDP.begin(localPort);

参数
localPort: 要监听的本地端口（int 类型）

返回值
如果成功则返回 1，如果没有可用的套接字则返回 0。

示例

#include <SPI.h>      
#include <Ethernet.h>
#include <EthernetUdp.h>

// 在下面为你的控制器输入 MAC 地址和 IP 地址。
// IP 地址将取决于你的本地网络：
byte mac[] = {  
  0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
IPAddress ip(192, 168, 1, 177);

unsigned int localPort = 8888;      // 要监听的本地端口

// 一个 EthernetUDP 实例，让我们能够通过 UDP 发送和接收数据包
EthernetUDP Udp;

void setup() {
  // 启动以太网和 UDP：
  Ethernet.begin(mac,ip);
  Udp.begin(localPort);
}

void loop() {
}