Lua для контроллера С3
Справочник встроенных Lua-модулей модульного контроллера С3: задачи, входы и выходы, модули расширения, RS485, Modbus, сеть, файлы, FlashDB и адресные ленты.
В модульном контроллере С3 программа на Lua 5.4 управляет входами и выходами, модулями расширения, линией RS485 и сетью. Здесь описаны встроенные модули и правила их вызова. Подключение контроллера, веб-редактор и запуск программы описаны в руководстве устройства:
- Программирование С3 на Lua — как устроена программа, задачи, память и восстановление после ошибок;
- Примеры программ для С3 — готовые сценарии, которые можно взять за основу.
Чем Lua в С3 отличается от Lua в ODNFC и LuaTerm
В С3 используется собственная среда исполнения, а не Lua RTOS из ODNFC и
LuaTerm. Имена части модулей совпадают (net, modbus, neopixel, osc,
flashdb),
но аргументы, результаты и обработка ошибок могут отличаться. Не переносите
программы между устройствами без проверки по этому справочнику.
| Что нужно | ODNFC и LuaTerm (Lua RTOS) | С3 |
|---|---|---|
| Версия языка | Lua 5.3 | Lua 5.4 |
| Пауза и параллельные задачи | thread.sleepms, thread.start | zephyr.task.sleep, zephyr.task.spawn |
| Входы и выходы | pio | odkit.io |
| Файл программы | usercode.lua | /lfs/main.lua |
Числа
Целые числа и числа с плавающей точкой в С3 32-битные:
- целые — от −2 147 483 648 до 2 147 483 647 (
math.maxinteger); - дробные — около 7 значащих цифр.
Длинные идентификаторы, например UID карты или 64-битный серийный номер,
храните строкой. Для 32-битных значений из регистров используйте
string.pack и string.unpack. Беззнаковое 32-битное значение больше
2 147 483 647 становится отрицательным; разность двух таких отсчётов
(b - a) всё равно правильная, если интервал меньше половины диапазона.
Подключение модулей
Базовые функции, package и string доступны сразу. Таблицы coroutine,
table, io, os, math, utf8, debug и odkit создаются при первом
обращении: программа тратит память только на то, что использует. Остальные
модули загружаются через require:
local task = require("zephyr.task")
local io = require("odkit.io")
local led = assert(io.open(5))
assert(led:configure("output_low"))
Собственные модули загрузите в раздел «Файлы» веб-интерфейса, в каталог
/lfs/lua. require("имя") ищет файлы /lfs/lua/имя.lua и
/lfs/lua/имя/init.lua.
Как модули сообщают об ошибках
Большинство функций С3 следуют одному правилу:
- ошибка в аргументах — неверный тип, номер вне диапазона, неизвестная опция — вызывает исключение Lua;
- ошибка устройства, сети или файла возвращается тремя значениями:
nil, положительный кодerrnoи текстовое сообщение; - команда без собственного результата при успехе возвращает
true.
Поэтому результат удобно проверять через assert или явно:
local uart = require("zephyr.uart")
local port, errno, message = uart.open("rs485")
if not port then
print("RS485 недоступен:", errno, message)
return
end
Исключения из правила указаны на страницах модулей. Например, flashdb
возвращает nil, сообщение, код, а функции модулей расширения в odkit
сообщают об аппаратной ошибке исключением.
Дескрипторы устройств, файлов и баз закрываются методом close(),
конструкцией Lua 5.4 local x <close> = ... или сборщиком мусора. Повторное
закрытие безопасно, а вызов метода у закрытого дескриптора возвращает EBADF.
Перезапуск программы закрывает все дескрипторы и освобождает выводы.
Обычно тайм-ауты задаются в миллисекундах, для обращений к устройствам — не
больше 60 000 мс, а 0 означает «не ждать». Исключения указаны на
страницах модулей: например, в net.tcp тайм-аут задаётся в секундах, а 0
снимает ограничение.
Частые коды errno
| Код | Имя | Обычная причина |
|---|---|---|
| 2 | ENOENT | нет файла, ключа или задачи |
| 5 | EIO | ошибка линии или ввода-вывода |
| 9 | EBADF | дескриптор уже закрыт |
| 11 | EAGAIN | данных пока нет или операция не завершилась сразу |
| 13 | EACCES | операция не разрешена в текущем режиме, например запись во вход |
| 16 | EBUSY | ресурс уже занят другим дескриптором |
| 19 | ENODEV | устройства нет в этом исполнении |
| 23 | ENFILE | открыто слишком много дескрипторов |
| 28 | ENOSPC | нет места: в таблице задач, на диске или в очереди |
| 71 | EPROTO | ответ не соответствует протоколу |
| 77 | EBADMSG | неверная контрольная сумма |
| 105 | ENOBUFS | принятые данные не успели прочитать |
| 116 | ETIMEDOUT | истёк тайм-аут |
| 134 | ENOTSUP | функция не поддерживается |
Модули
| Модуль | Назначение |
|---|---|
zephyr.task, zephyr.timer, zephyr.channel, zephyr.event | параллельные задачи, паузы, таймеры и обмен между задачами |
zephyr.sys, zephyr.log, zephyr.settings, zephyr.random, zephyr.watchdog | сведения о системе, журнал, постоянные настройки, сторожевой таймер |
odkit.unit | модули расширения по виду: выходы, реле, кнопки, АЦП |
odkit | светодиоды платы, регистры модулей расширения, дисплей |
odkit.io, zephyr.gpio, zephyr.input | дискретные входы и выходы IO1–IO8, кнопка платы |
zephyr.uart | обмен байтами по RS485 |
modbus | Modbus RTU и Modbus TCP, master и slave |
net, osc | Ethernet, TCP, UDP, HTTP-клиент, время по SNTP, Open Sound Control |
zephyr.fs, zephyr.sd | файлы во встроенной памяти и на карте microSD |
flashdb | база «ключ — значение» и журнал записей с временем |
neopixel | адресные светодиодные ленты WS2811 и WS2812 |
odrfid | библиотека опроса считывателей ODRFID-RS485 по Modbus |
Номера клемм IO, доступных в вашем исполнении, возвращает
require("odkit.io").list().
Нужен модуль расширения, которого нет в списке модулей, например Wi-Fi или CAN? Опишите задачу инженеру.