Ethernet library – библиотека для работы с Ethernet-шилдом

Ethernet-шилд – это дополнительная плата, которая подключается к ардуино и позволяет этой замечательной плате посылать и получать данные через локальную сеть и даже работать с Интернетом.

Работа с протоколами TCP/IP в шилде реализована аппаратно на микросхеме W5100.

Для работы с данным шилдом ничего дополнительно скачивать не нужно, т.к. в составе Arduino IDE уже есть удобная библиотека (\libraries\Ethernet\).

Библиотека содержит три класса: EthernetClass ,Client и Server.

Чтобы начать работать с библиотекой – её нужно сначала подключить; для этого можно написать

#include <Ethernet.h>

или выбрать в меню Arduino IDE:
Sketch – Import Library… — Ethernet
и в Ваш скетч автоматически добавятся строчки:

#include <Client.h>
#include <Ethernet.h>
#include <Server.h>

Библиотека позволяет выступать не только в качестве клиента, но и как сервер и поддерживает до четырёх одновременных подключений (входящих или исходящих).
Рассмотрим функции, которые реализуют этот функционал.

Первым делом необходимо инициализировать работу с библиотекой функцией begin, которая принимает от двух до четырёх параметров:

void begin(uint8_t *, uint8_t *);

Описание:
Инициализирует работу с библиотекой Ethernet и устанавливает сетевые настройки.

Синтаксис:

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

Параметры:
mac — MAC-адрес — физический адрес устройства (массив из 6 байт)
ip — IP-адрес – сетевой адрес Вашего устройства (массив из 4 байт)
gateway – IP-адрес Вашего сетевого шлюза (массив из 4 байт) (по-умолчанию – IP-адрес устройства с 1 в последнем октете)
subnet – маска подсети. (массив из 4 байт) (по-умолчанию 255.255.255.0)

если Вы не помните свои сетевые параметры, то на компьютере под управлением ОС Windows их можно посмотреть через
Пуск – Панель управления – Сетевые подключения
Щёлкнуть правой кнопкой мышки на «Подключение по локальной сети» и выбрать «Свойства»
В появившемся окошке выделить в списке «Протокол Интернета TCP/IP» и нажать кнопку «Свойства»

или же просто набрать в консоли команду

ipconfig /all

Возвращаемое значение:
ничего

Пример:

#include <Ethernet.h>

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

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

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

Рассмотрим серверные функции.

Server(uint16_t);

Описание:
Это конструктор класса Server – при вызове данной функции создаётся объект типа Server, для обработки входящих подключений по указанному порту.

Синтаксис:

Server(port);

Параметры:
port: номер порта сервера (int)

Возвращаемое значение:
ничего

Пример:

#include <Ethernet.h>

// задаём сетевую конфигурацию (шлюз и маска подсети – не обязательно)
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte gateway[] = { 10, 0, 0, 1 };
byte subnet[] = { 255, 255, 0, 0 };

// telnet на стандартном порту 23
Server server = Server(23);

void setup()
{
  // инициализация Ethernet-модуля
  Ethernet.begin(mac, ip, gateway, subnet);

  // запускаем сервер
  server.begin();
}

void loop()
{
  Client client = server.available();
  if (client) {
    server.write(client.read());
  }
}

void begin();

Описание:
Запускает сервер на приём входящих соединений.

Синтаксис:

server.begin();

Параметры:
нет

Возвращаемое значение:
ничего

Пример:

#include <Ethernet.h>

// задаём сетевую конфигурацию (шлюз и маска подсети – не обязательно)
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte gateway[] = { 10, 0, 0, 1 };
byte subnet[] = { 255, 255, 0, 0 };

// telnet на стандартном порту 23
Server server = Server(23);

void setup()
{
  // инициализация Ethernet-модуля
  Ethernet.begin(mac, ip, gateway, subnet);

  // запускаем сервер
  server.begin();
}

Client available();

Описание:
Возвращает объект типа Client, который представляет клиентское подключение к серверу и имеет данные для считывания (запрос). Объект сохраняется при выходе из области видимости; его можно закрыть вызовом client.stop().

Синтаксис:

server.available();

Параметры:
Нет

Возвращаемое значение:
ничего

Пример:

void loop()
{
  Client client = server.available();
  if (client) {
    server.write(client.read());
  }
}

virtual void write(uint8_t);
virtual void write(const char *str);
virtual void write(const uint8_t *buf, size_t size);

Описание:
Запись данных для передачи подключенному клиенту.

Синтаксис:

server.write(data);

Параметры:
data – байт или строка символов

Возвращаемое значение:
ничего

Пример:

void loop()
{
  Client client = server.available();
  if (client) {
    server.write(client.read());
  }
}

Т.к. класс Server наследуется от класса Print возможен так же вызов функций
print()
println()

Печатает данные для всех подключённых клиентов. Числа печатаются, как последовательность цифр, в виде ASCII-символов (например, число 123 будет передано как три символа: '1', '2', '3').
Функции println печатают данные с последующим переводом на новую строчку.

Синтаксис:

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

Параметры:
data – данные для печати (char, byte, int, long или строка)

BASE (опционально): основание представления числа: BIN -двоичное (основание 2), DEC десятичное (основание 10), OCT — восьмеричное (основание 8), HEX — шестнадцатеричное(основание 16).

Теперь рассмотрим клиентские функции.

Client(uint8_t);
Client(uint8_t *, uint16_t);
Описание:
Это конструктор класса Client – при вызове данной функции создаётся объект типа Client, который может подключаться к указанному IP-адресу и порту.

Синтаксис:

Client(ip, port);

Параметры:
ip: IP-адрес к которому клиент должен подключиться (массив из 4 байт)
port: номер порта для поключения (int)

Пример:

#include <Ethernet.h>

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

Client client(server, 80);

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

  delay(1000);

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

  if (client.connect()) {
    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(;;)
      ;
  }
}

uint8_t connected();

Описание:
Определяет есть ли подключение к серверу.
! Клиент считается подключённым, если подключение уже закрыто, но остались несчитанные данные.

Синтаксис:

client.connected();

Параметры:
нет

Возвращаемое значение:
true – если клиент подключен и false в противном случае.

Пример:

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

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

uint8_t connect();

Описание:
Подключается к IP-адресу и порту, заданному через конструктор.

Синтаксис:

client.connect();

Параметры:
нет

Возвращаемое значение:
ничего

Пример:
true – если подключиться удалось и false в противном случае.

Пример:

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

  delay(1000);

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

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

virtual void write(uint8_t);
virtual void write(const char *str);
virtual void write(const uint8_t *buf, size_t size);

Описание:
Запись данных для передачи к подключенному серверу.

Синтаксис:

client.write(data);

Параметры:
data – байт или строка символов

Возвращаемое значение:
ничего

Как и класс Server – класс Client наследуется от класса Print и так же возможен вызов функций
print()
println()

Печатает данные для сервера, к которому подключён клиент. Числа печатаются, как последовательность цифр, в виде ASCII-символов (например, число 123 будет передано как три символа: '1', '2', '3').
Функции println печатают данные с последующим переводом на новую строчку.

Синтаксис:

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

Параметры:
data – данные для печати (char, byte, int, long или строка)

BASE (опционально): основание представления числа: BIN -двоичное (основание 2), DEC десятичное (основание 10), OCT — восьмеричное (основание 8), HEX — шестнадцатеричное(основание 16).

Пример:

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

  delay(1000);

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

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

int available();

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

Синтаксис:

client.available();

Параметры:
нет

Возвращаемое значение:
Количество доступных байт (int).

Пример:

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

int read();

Описание:
Считывает следующий байт, полученный клиентом от сервера (после последнего вызова read())

Синтаксис:

client.read();

Параметры:
нет

Возвращаемое значение:
Байт (или символ) или -1 если данные отсутствуют.

Пример:

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

void flush();

Описание:
Очищает данные, которые были получены клиентом, но еще не были им прочитаны.

Синтаксис:

client.flush();

Параметры:
нет

Возвращаемое значение:
Ничего

void stop();

Описание:
Отключение от сервера.

Синтаксис:

client.stop();

Параметры:
нет

Возвращаемое значение:
ничего

Ссылки:
www.arduino.cc/en/Reference/Ethernet
code.google.com/p/webduino/