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

Lua для контроллера С3

Справочник встроенных Lua-модулей модульного контроллера С3: задачи, входы и выходы, модули расширения, RS485, Modbus, сеть, файлы, FlashDB и адресные ленты.

В модульном контроллере С3 программа на Lua 5.4 управляет входами и выходами, модулями расширения, линией RS485 и сетью. Здесь описаны встроенные модули и правила их вызова. Подключение контроллера, веб-редактор и запуск программы описаны в руководстве устройства:

Чем Lua в С3 отличается от Lua в ODNFC и LuaTerm

В С3 используется собственная среда исполнения, а не Lua RTOS из ODNFC и LuaTerm. Имена части модулей совпадают (net, modbus, neopixel, osc, flashdb), но аргументы, результаты и обработка ошибок могут отличаться. Не переносите программы между устройствами без проверки по этому справочнику.

Что нужноODNFC и LuaTerm (Lua RTOS)С3
Версия языкаLua 5.3Lua 5.4
Пауза и параллельные задачиthread.sleepms, thread.startzephyr.task.sleep, zephyr.task.spawn
Входы и выходыpioodkit.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

КодИмяОбычная причина
2ENOENTнет файла, ключа или задачи
5EIOошибка линии или ввода-вывода
9EBADFдескриптор уже закрыт
11EAGAINданных пока нет или операция не завершилась сразу
13EACCESоперация не разрешена в текущем режиме, например запись во вход
16EBUSYресурс уже занят другим дескриптором
19ENODEVустройства нет в этом исполнении
23ENFILEоткрыто слишком много дескрипторов
28ENOSPCнет места: в таблице задач, на диске или в очереди
71EPROTOответ не соответствует протоколу
77EBADMSGневерная контрольная сумма
105ENOBUFSпринятые данные не успели прочитать
116ETIMEDOUTистёк тайм-аут
134ENOTSUPфункция не поддерживается

Модули

МодульНазначение
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
modbusModbus RTU и Modbus TCP, master и slave
net, oscEthernet, 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? Опишите задачу инженеру.