Перейти к содержанию
Материалы раздела

net и osc: Ethernet, TCP, UDP, HTTP и время

Модули net и osc контроллера С3: Ethernet, ping, SNTP, HTTP-клиент, UDP, TCP, TCP-сервер и Open Sound Control. Ограничения и примеры на Lua.

Модуль net даёт программе доступ к сети Ethernet: проверить подключение, отправить HTTP-запрос, обменяться данными по TCP и UDP, запустить свой TCP-сервер и синхронизировать часы. Модуль osc собирает и разбирает сообщения Open Sound Control для управления световым и звуковым оборудованием.

local net = require("net")
local task = require("zephyr.task")

task.spawn(function()
  local code, chunks = net.http.get("192.168.1.10", "/status", "application/json",
                                    nil, false, 8080)
  print(code, chunks and table.concat(chunks))
end)

-- Эта задача продолжает мигать, пока идёт запрос.
for i = 1, 10 do
  odkit.led_set(odkit.LED0, i % 2 == 0)
  task.sleep(100)
end

Общие правила

  • Только IPv4-адреса. Имена хостов не поддерживаются: вместо example.com укажите адрес, иначе функция вызовет ошибку «IPv4 address expected».
  • Без TLS. Аргумент ssl = true возвращает ENOTSUP, поэтому HTTPS и другие протоколы с шифрованием напрямую недоступны. Для обмена с облаком используйте шлюз в локальной сети.
  • Ожидание не останавливает программу. Внутри задачи сетевой вызов отдаёт управление другим задачам и продолжается сам. Вне задачи, например в lua eval из USB-консоли, он ждёт до своего тайм-аута.
  • Ошибки. Сбой сети, файла или тайм-аут возвращают nil, errno, сообщение, ошибки аргументов вызывают исключение.
  • Соединений немного. Около восьми сетевых соединений приходится на весь контроллер: веб-интерфейс, DHCP, SNTP, Modbus TCP и сокеты программы. Закрывайте сокеты явно: закрытое TCP-соединение освобождается примерно через 1,5 с.

Сетевые операции расходуют память программы. HTTP-запрос на время выполнения занимает около 1,6 КБ плюс тело ответа, TCP- или UDP-сокет — меньше 0,1 КБ. Большие ответы сохраняйте в файл через net.http.download().

Адрес и настройки сети

При включении Ethernet получает адрес по DHCP или использует статический адрес из настроек. Настройки сети, NTP-сервер и часовой пояс задаются в веб-интерфейсе: «Настройки» → «Сеть» и «Настройки» → «Время», а также командой net_config в USB-консоли. Они действуют после перезапуска контроллера, до старта программы.

Вызовы net.en.setup() и net.en.start() из программы меняют адрес только до перезагрузки и не сохраняются.

net: интерфейсы

ФункцияРезультат
net.connected()true, если у интерфейса есть IPv4-адрес
net.stat([true])без аргумента печатает интерфейсы, с true возвращает массив таблиц
net.en.stat([true])то же только для Ethernet
net.packip(a, b, c, d), net.packip("a.b.c.d" [, quiet])адрес одним числом
net.unpackip(ip, "*n"), net.unpackip(ip, "*s")четыре числа или строка
net.isnetmask("255.255.255.0")true, если это корректная маска

Таблица интерфейса: interface ("en"), ip, netmask, gw, mac, link — кабель подключён и интерфейс поднят, connected — есть адрес, dhcp — адрес получен по DHCP. Массив net.stat(true) начинается с 1.

Число из packip при последнем октете больше 127 отрицательное, unpackip его принимает. С неверной строкой и quiet = true packip возвращает nil вместо ошибки.

print(net.unpackip(net.packip(192, 168, 1, 200), "*s"))  --> 192.168.1.200
for _, i in ipairs(net.stat(true)) do
  print(i.interface, i.connected, i.dhcp)
end

net.en: Ethernet

ФункцияДействие
net.en.setup()следующий start() включит DHCP
net.en.setup(ip, mask [, gw])следующий start() задаст статический адрес
net.en.start([async])применить настройки; с false ждать адреса до 30 с
net.en.stop()остановить DHCP и отключить интерфейс

Адреса передаются числами из net.packip. Если новый статический адрес совпадает с текущим, открытые соединения сохраняются.

local p = net.packip
net.en.setup(p(192, 168, 1, 50), p(255, 255, 255, 0), p(192, 168, 1, 1))
assert(net.en.start(false))

net.callback: события подключения

net.callback(function(event)
  print(event.interface, event.type)  -- "en", "up" или "down"
end)
net.callback(nil)                     -- отменить

up приходит, когда интерфейс получил IPv4-адрес, down — когда адрес пропал или интерфейс отключён. Обработчик выполняется как задача и может вызывать task.sleep(). После перезапуска программы подписку нужно задать снова.

net.ping и net.mping

net.ping(host [, count, interval, size, timeout]) печатает результат в консоль. По умолчанию — 10 пакетов по 32 байта, интервал и тайм-аут 1 с; 0 означает значение по умолчанию.

net.mping(host) выполняет одну проверку и возвращает время ответа в миллисекундах или 0, если ответа нет. Одновременно выполняется одна проверка: второй вызов вернёт EBUSY.

if net.mping("192.168.1.1") == 0 then
  print("шлюз не отвечает")
end

net.service.sntp: точное время

ФункцияРезультат
start(server1 [, server2, server3])запустить синхронизацию; адреса только IPv4
stop(), running()остановить, проверить работу
synced()true, если время установлено с момента включения
status(){running, synced, time, server, error}
wait([timeout_ms])ждать синхронизации, по умолчанию 10 000 мс
server([index])адрес сервера 0–2 или nil

Клиент устанавливает часы os.time(), повторяет синхронизацию раз в час и перебирает серверы по очереди. Он продолжает работать и при перезапуске программы. Проще всего задать NTP-сервер в «Настройки» → «Время»: тогда часы синхронизируются ещё до запуска main.lua.

local sntp = net.service.sntp
sntp.start("162.159.200.1", "216.239.35.0")  -- time.cloudflare.com, time.google.com
if sntp.wait(15000) then print(os.date()) end

Часовой пояс из настроек влияет на os.date() и os.time(t); os.date("!...") и сами часы остаются в UTC.

net.http: HTTP-клиент

code, chunks = net.http.get(host, resource, content_type, [headers], [ssl], [port],
                            [timeout_ms], [connect_timeout_s], [ca_cert], [total_timeout_ms])
code, chunks = net.http.post(host, resource, content_type, [headers], [body], [ssl], [port],
                             [timeout_ms], [connect_timeout_s], [ca_cert], [total_timeout_ms])
code = net.http.download(host, resource, content_type, headers, filename, [overwrite], [ssl],
                         [port], [timeout_ms], [connect_timeout_s], [ca_cert], [total_timeout_ms])
  • code — код ответа HTTP. chunks — таблица строк по 1024 байта; она есть только при коде 200 и непустом теле.
  • Тело ответа в памяти — до 8 КБ. Больший ответ даёт EFBIG: скачайте его в файл через download.
  • content_type у get и download — ожидаемый тип ответа с кодом 2xx, сравнивается до ;; nil отключает проверку. У post это тип тела запроса.
  • headers — строка заголовков через "\r\n", без пустой строки внутри.
  • download пишет во временный файл и заменяет filename только после полного непустого ответа 200. Без overwrite существующий файл вызывает ошибку.
  • Тайм-ауты по умолчанию: без прогресса — 3000 мс, подключение — 7 с для get и 5 с для остальных, общий — 60 с или 15 минут для download.
  • Каждый запрос открывает новое соединение и закрывает его после ответа. ca_cert не используется.
local body = '{"door":"open","ts":' .. os.time() .. '}'
local code = net.http.post("192.168.1.10", "/api/events", "application/json",
                           nil, body, false, 8080)
if code ~= 200 then print("сервер ответил", code) end

net.udp

ФункцияРезультат
net.udp.sendto(host, port, data)отправить одну датаграмму: true
conn = net.udp.bind(port)сокет на всех адресах; port = 0 — любой свободный
conn:sendto(host, port, data)true или false
ip, port, data = conn:readfrom([maxlen])следующая датаграмма или ничего, если очередь пуста
conn:close()закрыть; повторный вызов безопасен

readfrom() не ждёт: опрашивайте его в цикле с task.sleep(). Датаграмма — до 1472 байт; maxlen по умолчанию 1024, более длинная датаграмма обрезается.

local conn = assert(net.udp.bind(9000))
task.spawn(function()
  while true do
    local ip, port, data = conn:readfrom()
    if ip then conn:sendto(ip, port, "ack:" .. data) else task.sleep(20) end
  end
end)

net.tcp

ФункцияРезультат
conn = net.tcp.connect(host, port, [timeout_s])соединение
net.tcp.sendto(host, port, data, [timeout_s])подключиться, отправить, закрыть: true или false
conn:send(data)отправить всё: true или false
data = conn:read([size])от 1 до size байт из уже пришедших
line = conn:readline([size])строка вместе с "\n" или size байт без него
conn:close()закрыть

timeout_s по умолчанию — 10 с. Он ограничивает подключение и каждое ожидание без прогресса в send, read и readline; 0 — ждать, пока соединение не разорвётся. size по умолчанию 1024, не больше 4096. Последняя строка без "\n" перед закрытием соединения тоже возвращается.

Ошибка подключения возвращает nil, errno, сообщение. read и readline при тайм-ауте возвращают nil, ETIMEDOUT, после закрытия соединения другой стороной — nil, ENOTCONN.

local conn = assert(net.tcp.connect("192.168.1.10", 8000, 3))
conn:send("GET /status HTTP/1.0\r\n\r\n")
print(conn:readline())  --> HTTP/1.0 200 OK
conn:close()

net.tcpserv: TCP-сервер

Один TCP-сервер с несколькими клиентами.

ФункцияДействие
net.tcpserv.start([port], fn, [autoclose], [redirectio])запустить; повторный вызов перезапускает с новыми параметрами
net.tcpserv.stop(), net.tcpserv.running()остановить, проверить
net.tcpserv.send(data, [timeout_ms], [flush])в обработчике: отправить клиенту; число байтов или false
net.tcpserv.print(...)в обработчике: отправить строки как есть, без разделителей
net.tcpserv.flush()в обработчике: отправлять без задержки, true
  • port по умолчанию 5555. fn(ip, data) вызывается на каждую порцию данных до 1024 байт. Обработчики одного клиента выполняются по очереди и могут вызывать task.sleep().
  • autoclose — секунды простоя до закрытия соединения, по умолчанию 60; 0 — не закрывать.
  • redirectio = true отправляет клиенту вывод print() из обработчика.
  • send без timeout_ms отправляет то, что сокет принимает сразу; с тайм-аутом дожидается отправки остатка, уступая управление другим задачам.
  • Одновременно обслуживаются 2 клиента, следующий получает отказ.
  • Ошибка в обработчике записывается в журнал, сервер продолжает работать.
  • Сервер останавливается вместе с программой, которая его запустила.
-- Текстовые команды по TCP: "on", "off".
net.tcpserv.start(5555, function(ip, data)
  local cmd = data:match("^%s*(%a+)")
  if cmd == "on" then odkit.led_set(odkit.LED0, true)
  elseif cmd == "off" then odkit.led_set(odkit.LED0, false) end
  net.tcpserv.print("ok ", cmd or "?", "\n")
end, 300)

Сервер не проверяет, кто к нему подключился. Если порт доступен из чужой сети, добавьте в протокол собственную проверку или ограничьте доступ на сетевом оборудовании.

osc: Open Sound Control

local osc = require("osc")
local msg = osc.make("/mixer/fader", "if", 3, 0.75)
local address, format, channel, level = osc.parse(msg)
osc.print(msg)  --> [28 bytes] /mixer/fader if 3 0.75

net.udp.sendto("192.168.1.20", 8000, osc.make("/c3/button", "i", 1))
ФункцияРезультат
osc.make(address, types, ...)двоичное сообщение строкой
osc.parse(message)адрес, строка типов и значения аргументов
osc.print(message)вывести сообщение в консоль

Типы аргументов: i, f, s, b (blob — строка Lua), m (MIDI — 4 байта строкой или таблицей), T, F, N, I. Сообщение — до 1024 байт. Типы d, h и t не поддерживаются из-за 32-битных чисел, бандлы — тоже. Сообщения передаются через net.udp.

Доступ к веб-интерфейсу

Пароль веб-интерфейса настраивается в разделе «Настройки», см. «Первый запуск и веб-интерфейс».