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.
Доступ к веб-интерфейсу
Пароль веб-интерфейса настраивается в разделе «Настройки», см. «Первый запуск и веб-интерфейс».