Ардуино-библиотека UIPEthernet.h (Ethernet.h).

Справочный материал к уроку 64.

 

Класс Ethernet инициализирует библиотеку и настройки для работы с сетью Ethernet.
begin() subnetMask() dnsServerIP()
localIP() gatewayIP() maintain()

 

Класс Ethernet инициализирует библиотеку и настройки для работы с сетью Ethernet.
 IPAddress()

 

Класс Server – применяется для создания и работы с серверами.
Server available() print()
EthernetServer() write() println()
begin()

 

Класс Client – используется для создания и работы с клиентами.
Client write() read()
EthernetClient() print() peek()
if (EthernetClient) println() flush()
connected() available() stop()
 connect()

 

Класс EthernetUDP – поддерживает UDP протокол.
begin() beginPacket() stop()
read() endPacket() remoteIP()
peek() parsePacket() remotePort()
write() vailable() flush()

 

Класс Ethernet инициализирует библиотеку и настройки для работы с сетью Ethernet.

begin()

int begin(const uint8_t* mac);
void begin(const uint8_t* mac, IPAddress ip);
void begin(const uint8_t* mac, IPAddress ip, IPAddress dns);
void begin(const uint8_t* mac, IPAddress ip, IPAddress dns, IPAddress gateway);
void begin(const uint8_t* mac, IPAddress ip, IPAddress dns, IPAddress gateway, IPAddress subnet);

Инициализирует библиотеку UIPEthernet, задает основные настройки. Имеет форматы:

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 байт). Может быть указан на наклейке модуля или задан программно.
  • ip: IP-адрес сетевого устройства (массив из 4 байт).
  • dns: IP-адрес DNS-сервера (массив из 4 байт). Параметр необязательный. При отсутствии аргумента, в качестве адреса DNS-сервера будет установлен IP-адрес модуля, в котором последний октет равен 1.
  • gateway: IP-адрес сетевого шлюза (массив из 4 байт). Параметр необязательный. При отсутствии аргумента, в качестве адреса шлюза будет установлен IP-адрес модуля, в котором последний октет равен 1.
  • subnet: маска подсети (массив из 4 байт). Параметр необязательный. По умолчанию задается 255.255.255.0.

Подробная информация обо всех этих параметрах есть в уроке 62.

Если функция используется в формате с единственным аргументом Ethernet.begin(mac), назначение IP-адреса модуля происходит автоматически, по протоколу DHCP. В этом случае, при неудачном DHCP-соединении функция возвращает 0, при успешном – 1. Остальные форматы функции begin() не возвращают никаких значений.

if (Ethernet.begin(mac) == 0) {
  // ошибка получения IP-адреса
}

Типичное использование функции выглядит так:

#include <SPI.h>
#include <UIPEthernet.h>

// определяем конфигурацию сети
byte mac[] = {0xAE, 0xB2, 0x26, 0xE4, 0x4A, 0x5C};  // MAC-адрес
byte ip[] = {192, 168, 1, 10};  // IP-адрес
byte myDns[] = {192, 168, 1, 1};  // адрес DNS-сервера
byte gateway[] = {192, 168, 1, 1};  // адрес сетевого шлюза
byte subnet[] = {255, 255, 255, 0};  // маска подсети

void setup() {
  Ethernet.begin(mac, ip, myDns, gateway, subnet);  // инициализация контроллера
  server.begin(); // включаем ожидание входящих соединений
}

 

localIP()

IPAddress localIP();

Функция возвращает IP-адрес Ethernet-модуля. Используется для того, чтобы узнать IP-адрес модуля, назначенный автоматически по DHCP-протоколу.

IPAddress ip = Ethernet.localIP();  // чтение IP-адреса

 

subnetMask()

IPAddress subnetMask();

Функция возвращает маску подсети.

 

gatewayIP()

IPAddress gatewayIP();

Функция возвращает IP-адрес шлюза.

 

dnsServerIP()

IPAddress dnsServerIP();

Функция возвращает IP-адрес DNS-сервера.

 

maintain()

int maintain();

Инициирует обновление IP-адреса по протоколу DHCP. В результате может быть получен, как новый, так и прежний адрес. Как решит DHCP-сервер.

Возвращает значение типа byte:

  • 0 – ничего не произошло;
  • 1 – обновить аренду адреса не удалось;
  • 2 – обновление аренды адреса прошло успешно;
  • 3 – IP-адрес обновить не удалось;
  • 4 – обновление IP-адреса прошло успешно.

 

Класс IPAddress – используется для работы с IP адресами.

IPAddress()

IPAddress();
IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet);
IPAddress(uint32_t address);
IPAddress(const uint8_t *address);

Функция задает IP-адрес.

IPAddress(address);

  • address – IP-адрес (массив 4 байта).

IPAddress ip(192,168,1,15);  // устанавливаем IP-адрес

Действие функции равнозначно:

byte ip[] = {192, 168, 1, 15};  // IP-адрес

 

Класс Server – применяется для создания серверов и работы с ними.

Server

Базовый класс, непосредственно не вызывается. Используется при вызове его функций.

 

EthernetServer()

void EthernetServer (uint16_t);

Создает сервер, ожидающий соединения через заданный порт.

EthernetServer(port);

  • port – номер порта.

EthernetServer server(1000);  // создаем сервер, порт 1000

 

begin()

void begin();

Инициирует сервер начать ожидание входящих соединений.

server.begin();

Аргументов и возвращаемых значений нет.

EthernetServer server(1000);  // создаем сервер, порт 1000

void setup() {
  Ethernet.begin(mac, ip);  // инициализация контроллера
  server.begin(); // включаем ожидание входящих соединений
}

 

available()

EthernetClient available();

При наличии клиента, подключенного к серверу и имеющего непрочитанные данные, возвращает описывающий клиента объект Client.

server.available();

Если отсутствуют клиенты с непрочитанными данными, то функция возвращает false.

client = server.available(); // ожидаем объект клиент
if (client) {
  // есть данные от клиента
}

 

write()

size_t write(uint8_t);
size_t write(const uint8_t *buf, size_t size);

Отправляет данные всем клиентам, подключенным к серверу. Можно отправить один байт или последовательность байтов.

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

  • val - байт, который необходимо передать;
  • buf - массив данных, который необходимо отправить;
  • len - длина массива.

Возвращает количество отправленных байтов.

server.write(0x23);  // отправляем байт

 

print()

size_t print(const __FlashStringHelper *);
size_t print(const String &);
size_t print(const char[]);
size_t print(char);
size_t print(unsigned char, int = DEC);
size_t print(int, int = DEC);
size_t print(unsigned int, int = DEC);
size_t print(long, int = DEC);
size_t print(unsigned long, int = DEC);
size_t print(double, int = 2);
size_t print(const Printable&);

Отправляет данные всем клиентам, подключенным к серверу. Данные передаются в текстовом виде (ASCII символы). Формат функции аналогичен одноименной функции класса Serial.

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

  • data - данные, которые необходимо передать (char, byte, int, long или string);
  • BASE - система счисления, в которой необходимо выводить числа. Параметр не обязательный.
    • BIN – двоичная система исчисление;
    • DEC – десятичная:
    • OCT – восьмеричная;
    • HEX – шестнадцатеричная.

Функция возвращает количество отправленных байтов.

server.print(“Error”);

 

println()

size_t println(const __FlashStringHelper *);
size_t println(const String &s);
size_t println(const char[]);
size_t println(char);
size_t println(unsigned char, int = DEC);
size_t println(int, int = DEC);
size_t println(unsigned int, int = DEC);
size_t println(long, int = DEC);
size_t println(unsigned long, int = DEC);
size_t println(double, int = 2);
size_t println(const Printable&);
size_t println(void);

Аналогично функции print() отправляет данные всем подключенным клиентам в текстовом виде. В отличие от print() добавляет символы переноса строки (\r, код 13) и (\n, код 10).

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

  • data - данные, которые необходимо передать (char, byte, int, long или string);
  • BASE - система счисления, в которой необходимо выводить числа. Параметр не обязательный.
    • BIN – двоичная система исчисление;
    • DEC – десятичная:
    • OCT – восьмеричная;
    • HEX – шестнадцатеричная.

Функция возвращает количество отправленных байтов.

 

Класс Client – используется для создания клиентов и работы с ними.

Client

Базовый класс, непосредственно не вызывается. Используется при вызове его функций.

 

EthernetClient()

void EthernetClient();

Функция создает клиента. Параметров и возвращаемых значений нет.

EthernetClient client;  // создаем клиента

 

if (EthernetClient)

bool operator==(const EthernetClient&);

Показывает готов ли указанный клиент к работе.

if(client)

Если указанный клиент готов, возвращает true.

while(!client) {
  ; // ожидаем подключения клиента
}

 

connected()

uint8_t connected();

Функция показывает, подключен ли клиент к серверу. При наличии непрочитанных данных клиент считается подключенным к серверу, даже если соединение уже закрыто.

client.connected();

Если клиент подключен, функция возвращает true.

if (client.connected()) {
  // подключен
}
else {
  // соединение разорвано
}

 

connect()

int connect(IPAddress ip, uint16_t port);
int connect(const char *host, uint16_t port);

Функция устанавливает соединение с сервером через заданный порт. В качестве аргумента может использоваться как IP-адрес, так и доменное имя.

client.connect(ip, port);
client.connect(URL, port);

  • ip - IP-адрес сервера, с которым необходимо установить соединение (массив из 4 байт);
  • URL - доменное имя сервера, с которым необходимо установить соединение (строка, например "google.com");
  • port - порт, через который необходимо установить соединение.

При успешном подключении функция возвращает true.

// устанавливаем соединение с сервером
if (client.connect(ipServ, 500)) {
  // успешно
}
else {
  // ошибка
}

 

write()

size_t write(uint8_t);
size_t write(const uint8_t *buf, size_t size);

Отправляет данные серверу, с которым было установлено соединение. Можно отправлять один байт или последовательность байтов.

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

  • val - байт, который необходимо отправить;
  • buf - массив данных, который необходимо отправить в виде последовательности байт;
  • len - длина буфера (массива).

Функция возвращает количество отправленных байтов.

 

print()

size_t print(const __FlashStringHelper *);
size_t print(const String &);
size_t print(const char[]);
size_t print(char);
size_t print(unsigned char, int = DEC);
size_t print(int, int = DEC);
size_t print(unsigned int, int = DEC);
size_t print(long, int = DEC);
size_t print(unsigned long, int = DEC);
size_t print(double, int = 2);
size_t print(const Printable&);

Отправляет данные от клиента серверу. Данные передаются в текстовом виде (ASCII символы). Формат функции аналогичен одноименной функции класса Serial.

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

  • data - данные, которые необходимо передать (char, byte, int, long или string);
  • BASE - система счисления, в которой необходимо выводить числа. Параметр не обязательный.
    • BIN – двоичная система исчисление;
    • DEC – десятичная:
    • OCT – восьмеричная;
    • HEX – шестнадцатеричная.

Функция возвращает количество отправленных байтов.

 

println()

size_t println(const __FlashStringHelper *);
size_t println(const String &s);
size_t println(const char[]);
size_t println(char);
size_t println(unsigned char, int = DEC);
size_t println(int, int = DEC);
size_t println(unsigned int, int = DEC);
size_t println(long, int = DEC);
size_t println(unsigned long, int = DEC);
size_t println(double, int = 2);
size_t println(const Printable&);
size_t println(void);

Аналогично функции print() отправляет данные серверу в текстовом виде. В отличии от print() добавляет символы переноса строки (\r, код 13) и (\n, код 10).

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

  • data - данные, которые необходимо передать (char, byte, int, long или string);
  • BASE - система счисления, в которой необходимо выводить числа. Параметр не обязательный.
    • BIN – двоичная система исчисление;
    • DEC – десятичная:
    • OCT – восьмеричная;
    • HEX – шестнадцатеричная.

Функция возвращает количество отправленных байтов.

 

available()

int available();

Возвращает количество непрочитанных байтов, принятых клиентом от сервера.

client.available();

Возвращает количество непрочитанных байтов.

// все, что приходит с сервера, печатаем в UART
if (client.available()) {
  char chr = client.read();
  Serial.print(chr);
}

 

read()

int read();
int read(uint8_t *buf, size_t size);

Считывает очередной байт из потока данных, принятых клиентом от сервера.

client.read();
client.read(buf,len);

  • buf - массив данных, в который необходимо считать данные;
  • len - длина массива.

Возвращает значение очередного байта, либо -1, если буфер пуст.

char chr = client.read();

 

peek()

int peek();

Возвращает очередной принятый от сервера байт, не удаляя его из буфера.

client.peek();

 

flush()

void flush();

Удаляет из буфера все непрочитанные данные, полученные от сервера.

client.flush();

Параметров и возвращаемого значения нет.

 

stop()

void stop();

Разрывает соединение с сервером.

client.stop();

Параметров и возвращаемого значения нет.

 

 

Класс EthernetUDP – поддерживает UDP протокол.

 

begin()

uint8_t   begin(uint16_t);

Инициализирует UDP библиотеку, запускает прослушивание на указанном порту.

EthernetUDP.begin(port);

  • port – номер порта для прослушивания.

Возвращает 1 при успешной операции.

 

read()

int read(void);
int read(unsigned char* buffer, size_t len);
int read(char* buffer, size_t len);

Считывает данные в заданный буфер. Если аргументы функции не заданы, то возвращает очередной принятый символ.

Функцию можно использовать только после вызова parsePacket().

UDP.read();
UDP.read(buf, size);

  • buf - массив для чтения;
  • size -  длина данных.

Возвращает значение очередного байта, либо -1, если буфер пуст. В случае приема пакета, возвращает количество байтов, записанных в массив.

 

peek()

int peek();

Возвращает очередной принятый от сервера байт, не удаляя его из буфера.

UDP.peek();

 

write()

size_t    write(uint8_t);
size_t    write(const uint8_t *buffer, size_t size);

Посылает данные по протоколу UDP. Метод должен вызываться между вызовами функций beginPacket() и endPacket().beginPacket() инициализирует пакет данных, но не отправляет его до вызова endPacket().

UDP.write(val);
UDP.write(buf,len);

  • val - байт, который необходимо отправить;
  • buf - массив данных, который необходимо отправить в виде последовательности байтов;
  • len - длина буфера (массива).

Функция возвращает количество отправленных байтов.

 

beginPacket()

int beginPacket(IPAddress ip, uint16_t port);
int beginPacket(const char *host, uint16_t port);

Устанавливает соединение с устройством для отправки данных по протоколу UDP.

UDP.beginPacket(remoteIP, remotePort);

  • remoteIP - IP-адрес удаленного устройства (4 байта);
  • remotePort - номер порта на удаленном устройстве.

Возвращает 1, если операция прошла успешно, 0 - если возникли неразрешимые проблемы с адресом или портом.

 

endPacket()

int endPacket(void);

Данный метод вызывается после подготовки UDP-данных для отправки.

UDP.endPacket();

Возвращает 1, если пакет был послан успешно, 0 - если произошла ошибка.

 

parsePacket()

int parsePacket(void);

Функция проверяет наличие принятого UDP-пакета и возвращает его размер. Должна вызываться перед считыванием буфера методом UDP.read().

UDP.parsePacket();

Функция возвращает размер принятого UDP-пакета.

 

available()

int available(void);

Функция возвращает количество принятых байтов, доступных для считывания из буфера. Ее можно вызывать только после вызова UDP.parsePacket().

UDP.available();

Возвращает количество байтов, доступных для считывания.

 

stop()

void stop(void);

Разрывает соединение с сервером.

EtheretUDP.stop();

Параметров не имеет, значение не возвращает.

 

remoteIP()

IPAddress remoteIP(void);

Функция возвращает IP-адрес удаленного устройства. Можно вызывать только после вызова UDP.parsePacket().

UDP.remoteIP();

Возвращает IP-адрес удаленного устройства (4 байта).

 

remotePort()

uint16_t  remotePort(void);

Функция возвращает номер порта удаленного устройства. Можно вызывать только после вызова UDP.parsePacket().

UDP.remotePort();

Функция возвращает номер порта UDP-соединения на удаленном устройстве

 

flush()

void flush();

Удаляет из буфера все непрочитанные данные.

UDP.flush();

Параметров и возвращаемого значения нет.