os.version()

Возвращает сведения о версии прошивки.

Аргументы: нет

Возвращает четыре значения: название системы, версию, время создания прошивки в формате Unix time и идентификатор ревизии. Эти данные удобны для диагностики и обращения в техническую поддержку.

local name, version, built_at, revision = os.version()
print(name, version, built_at, revision)

os.flashEUI()

Получить идентификатор встроенного SPI FLASH.

Аргументы: нет

Возвращает: идентификатор или ничего.

/ > os.flashEUI()
cb6254185b430e2e

os.uptime([mode])

Выводит время работы после загрузки или возвращает его в заданном формате.

Аргументы:

• mode = 0 или аргумент не задан: печатает строку в консоль и ничего не возвращает.
• mode = 1: возвращает таблицу.
• mode = 2: возвращает время после загрузки в миллисекундах. Это не Unix timestamp. Пока значение помещается в lua_Integer, возвращается число; более широкое значение возвращается точной десятичной строкой.

При mode = 1 таблица содержит:

• current: строку времени в формате %H:%M;
• days: количество полных дней;
• hours: часы;
• mins: минуты;
• secs: секунды.

/ > os.uptime()
23:26 up  0:19:05

local up = os.uptime(1)
print("days:", up.days, "hours:", up.hours, "mins:", up.mins, "secs:", up.secs)

os.time([date])

Без аргументов возвращает текущее время в формате Unix time. Аргумент date — таблица с полями year, month, day, а также необязательными hour, min, sec и isdst; функция преобразует её в Unix time.

Поля таблицы трактуются в часовом поясе, заданном os.tz(): установленное смещение вычитается при преобразовании, поэтому os.time(table) является обратной операцией для локальной формы os.date("*t", timestamp).

Подробнее о формате таблицы см. в документации Lua.

/ > os.time()
1552405265

os.timestamp([resolution], [endian], [as_string], [uptime])

Возвращает системное время или время работы устройства с заданной точностью.

Аргументы:

• resolution: "s", "ms" или "us"; по умолчанию "s";
• endian: порядок байтов "le" или "be"; используется при as_string = true, по умолчанию "le";
• as_string: вернуть бинарную строку вместо числа; по умолчанию false;
• uptime: использовать время после загрузки вместо системного времени; по умолчанию false.

Для секунд бинарная строка занимает 4 байта, для миллисекунд и микросекунд — 8 байт. Если as_string = false, результат возвращается числом, пока он помещается в lua_Integer, и точной десятичной строкой для более широких значений. В стандартном 32-битном профиле текущие Unix timestamp в миллисекундах и микросекундах поэтому являются строками. Для фиксированного бинарного формата используйте as_string = true.

Примеры:

-- Unix time в секундах
local ts = os.timestamp()

-- Unix time в миллисекундах
local ts_ms = os.timestamp("ms")

-- Unix time в микросекундах
local ts_us = os.timestamp("us")

-- Четыре байта, младший байт первым
local bytes_le = os.timestamp("s", "le", true)

-- Восемь байтов, старший байт первым
local bytes_be = os.timestamp("ms", "be", true)

-- Время после загрузки в миллисекундах
local uptime_ms = os.timestamp("ms", "le", false, true)

timezone = os.tz([timezone])

Получает или задаёт смещение часового пояса в часах.

Аргументы:

• timezone (необязательно): целое смещение относительно UTC в часах от -24 до 24.

Возвращает:

• без аргумента — текущее смещение;
• с аргументом — ничего.

os.date([format, [timestamp]])

Преобразует Unix time в строку по шаблону format или в таблицу при format = "*t". Если timestamp не указан, используется текущее время.

К локальным форматам применяется смещение os.tz(). Начальный символ ! выбирает UTC и всегда игнорирует это смещение, например os.date("!%Y-%m-%dT%H:%M:%SZ", timestamp).

Подробнее о форматах см. в документации Lua.

/ > table = os.date("*t", 906000490)

/ > os.date("today is %A, in %B")
today is Tuesday, in March

/ > os.date()
Tue Mar 12 15:35:36 2019

os.settime(…)

Устанавливает системное время. Поддерживаются две формы вызова:

• os.settime(hours, minutes, seconds, month, day, year [, isdst]);
• os.settime{year=..., month=..., day=..., hour=..., min=..., sec=...}.

Возвращает установленное время в формате Unix time. Обычно следует передавать время UTC.

/ > os.settime{year=1970, month=1, day=1, hour=0, min=0, sec=0}
0
/ > os.settime{year=1970, month=1, day=1, hour=0, min=1, sec=0}
60

os.factoryreset()

Отменяет установленные OTA-обновления и перезагружает устройство с заводской прошивкой. Функция доступна только на устройствах с заводским разделом прошивки.

Аргументы: нет.

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

os.factoryreset()

os.history([enable])

Включает или отключает запись истории команд, введённых в консоли. История доступна по клавишам «вверх» и «вниз». Для сохранения истории нужен смонтированный раздел SD или RAMFS, например fs.mount("/rfs", "ramfs").

Аргументы:

• enable (необязательно): true для включения, false для отключения. Если аргумент не указан, функция возвращает текущее состояние.

Возвращает текущее состояние, если аргумент не указан; иначе ничего.

-- Включить историю
os.history(true)

os.logcons([enable])

Включение или отключение логирования. Если оно включено, сообщения журнала отображаются в консоли и записываются в файл /log/messages.log, если подключена SD-карта. Если оно отключено, сообщения журнала записываются в файл /log/messages.log, если подключена SD-карта.

Аргументы:

• enable (необязательно): true для включения вывода, false для отключения. Если аргумент не указан, функция возвращает текущее состояние.

Возвращает текущее состояние, если аргумент не указан; иначе ничего.

-- Не выводить журнал в консоль
os.logcons(false)

os.loglevel([level])

Устанавливает уровень логирования. Уровень логирования контролирует объем информации журнала, который Lua RTOS отображает на консоли и записывает в файл /log/messages.log (если подключена SD-карта).

Аргументы:

• level (необязательно): уровень логирования, может быть os.LOG_ALL, os.LOG_INFO, os.LOG_EMERG, os.LOG_ALERT, os.LOG_CRIT, os.LOG_ERR, os.LOG_WARNING, os.LOG_NOTICE, os.LOG_DEBUG. Если этот аргумент не предоставлен, функция возвращает текущую настройку loglevel.

Возвращает: ничего или текущую настройку loglevel, если аргумент enable не предоставлен.

-- Show only error logs
os.loglevel(os.LOG_ERR)

os.syslog(message[, level])

Записывает сообщение в системный журнал (syslog).

Аргументы:

message: сообщение для записи в системный журнал

• level (необязательно): уровень логирования, может быть os.LOG_ALL, os.LOG_INFO, os.LOG_EMERG, os.LOG_ALERT, os.LOG_CRIT, os.LOG_ERR, os.LOG_WARNING, os.LOG_NOTICE, os.LOG_DEBUG. Если этот аргумент не предоставлен, функция возвращает текущую настройку loglevel.

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

-- Log an informative message
os.syslog("foo", os.LOG_INFO)

os.rsyslog([server])

Включает или отключает логирование на удаленный сервер rsyslog.

Аргументы:

• server (необязательно): имя или IP-адрес удаленного сервера syslog. Пустая строка или 0.0.0.0 для отключения.

Возвращает: текущий установленный сервер rsyslog.

-- Retrieve the currently set rsyslog server
/ > os.rsyslog()
0.0.0.0
-- Set a new rsyslog server
/ > os.rsyslog("10.0.0.1")
10.0.0.1
-- Retrieve the currently set rsyslog server
/ > os.rsyslog()
10.0.0.1
-- Disable logging to a remote syslog server
/ > os.rsyslog("0.0.0.0")
0.0.0.0

os.shell([enable])

Включить или отключить оболочку Lua RTOS.

/ > ls
f	     370		abp.lua
d	       -		examples
d	       -		sys
f	     468		system.lua
f	     388		wifi.lua
f	      40		autorun.lua
/ > cd examples
/examples > ls
d	       -		blocks
d	       -		lua
d	       -		a
f	       0		system.lua
/examples >

Аргументы:

• enable (необязательно): true для включения / false для отключения. Если этот аргумент не предоставлен, функция возвращает текущую настройку оболочки.

Возвращает: ничего или текущую настройку оболочки (true/false), если аргумент enable не предоставлен.

os.exists(path)

Проверяет, существует ли файл или директория по указанному пути.

Аргументы:

• path: путь к файлу или директории.

Возвращает: true если файл или директория существует, false в противном случае.

/ > os.exists("/system.lua")
true
/ > os.exists("/nonexistent.lua")
false

os.isfile(path)

Проверяет, является ли указанный путь файлом.

Аргументы:

• path: путь для проверки.

Возвращает: true если путь существует и является файлом, false в противном случае.

/ > os.isfile("/system.lua")
true
/ > os.isfile("/examples")
false

os.isdir(path)

Проверяет, является ли указанный путь директорией.

Аргументы:

• path: путь для проверки.

Возвращает: true если путь существует и является директорией, false в противном случае.

/ > os.isdir("/examples")
true
/ > os.isdir("/system.lua")
false

os.clock()

Возвращает процессорное время в секундах, использованное данным процессом.

Аргументы: нет

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

/ > os.clock()
0.123456

os.difftime(t1, t2)

Возвращает разницу между двумя временными метками.

Аргументы:

• t1: первая временная метка
• t2: вторая временная метка

Возвращает: число (разница в секундах между t1 и t2).

/ > start = os.time()
/ > -- ... some operations ...
/ > elapsed = os.difftime(os.time(), start)

os.remove(path)

Удаляет файл или директорию. Поддерживает wildcard (*) для удаления нескольких файлов. Путь, который не помещается в системный PATH_MAX, отклоняется с ошибкой и никогда не используется в усечённом виде.

Аргументы:

• path: путь к файлу, директории или шаблон с wildcard (*)

Возвращает: true в случае успеха, false и сообщение об ошибке в случае неудачи.

-- Удаление одного файла
/ > os.remove("/tmp/test.txt")
true

-- Удаление директории
/ > os.remove("/tmp/mydir")
true

-- Удаление по шаблону
/ > os.remove("/tmp/*.tmp")
true

os.rename(oldname, newname)

Переименовывает файл или директорию.

Аргументы:

• oldname: текущее имя файла или директории
• newname: новое имя файла или директории

Возвращает: true в случае успеха, false и сообщение об ошибке в случае неудачи.

/ > os.rename("/old.txt", "/new.txt")
true

os.tmpname()

Генерирует уникальное имя временного файла.

Аргументы: нет

Возвращает: строку с путем к временному файлу.

/ > tmp = os.tmpname()
/ > print(tmp)
/tmp/lua_a1B2c3

os.exit([code [, close]])

Завершает выполнение программы.

Аргументы:

• code (опционально): код завершения (число или boolean). true = EXIT_SUCCESS, false = EXIT_FAILURE. По умолчанию EXIT_SUCCESS.
• close (опционально): если true, закрывает состояние Lua перед выходом.

Возвращает: ничего (программа завершается).

Примечание: На ESP32 при code = true выполняется перезагрузка системы через esp_restart().

-- Успешное завершение
/ > os.exit()

-- Завершение с кодом ошибки
/ > os.exit(false)

-- Завершение с закрытием состояния Lua
/ > os.exit(0, true)

os.get_partition()

Возвращает метку текущего запущенного раздела.

Аргументы: нет

Возвращает: строку с меткой раздела.

/ > os.get_partition()
lua_rtos

os.change_partition()

Переключается на следующий OTA-раздел и перезагружает систему.

Аргументы: нет

Возвращает: ничего (система перезагружается).

os.partitions()

Выводит список всех разделов flash-памяти.

Аргументы: нет

Возвращает: ничего (выводит информацию в консоль).

Type, SubType, Address, Size, Encrypted, Label
--------------------------------------------------
0x01, 0x00, 0x10000, 0x100000, 0, factory
0x01, 0x10, 0x110000, 0x100000, 0, ota_0

os.passwd()

Интерактивная смена системного пароля.

Аргументы: нет

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

/ > os.passwd()
Changing password for user 'admin'
Old password: ********
New password: ********
Retype new password: ********
Password changed

os.autopasswd(password)

Автоматическая установка пароля без подтверждения.

Аргументы:

• password: новый пароль

Возвращает: true в случае успеха, false в случае неудачи.

/ > os.autopasswd("newpassword123")
true

os.now()

Возвращает время в миллисекундах с момента загрузки системы.

Аргументы: нет

Возвращает: миллисекунды числом, пока значение помещается в lua_Integer, иначе точной десятичной строкой. Счётчик основан на 64-битном монотонном таймере и не обнуляется при переполнении 32-битного системного тика.

/ > os.now()
12345678

os.stdout([path])

Перенаправляет stdout в файл или возвращает вывод в консоль.

Аргументы:

• path (опционально): путь к файлу для перенаправления вывода. Если nil или не указано, сбрасывает перенаправление.

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

-- Перенаправить вывод в файл
/ > os.stdout("/tmp/output.txt")
/ > print("This goes to file")
/ > os.stdout()  -- сброс

os.clear()

Очищает экран консоли.

Аргументы: нет

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

/ > os.clear()

os.ls([path [, to_table]])

Выводит список файлов в директории. Поддерживает wildcard (*).

Аргументы:

• path (опционально): путь к директории или шаблон. По умолчанию текущая директория.
• to_table (опционально): если 1, возвращает таблицу вместо вывода в консоль.

Возвращает: ничего или массив строк с именами файлов (если to_table = 1).

-- Вывод списка файлов
/ > os.ls()
f	     370		abp.lua
d	       -		examples
...

-- С wildcard
/ > os.ls("*.lua")

-- Вернуть таблицей
/ > files = os.ls("/", 1)
/ > for _, name in ipairs(files) do print(name) end

os.cd([path])

Изменяет текущую директорию.

Аргументы:

• path (опционально): путь к новой директории. По умолчанию “/”.

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

/ > os.cd("/examples")
/examples >

os.pwd()

Возвращает текущую директорию.

Аргументы: нет

Возвращает: строку с путем текущей директории.

/examples > os.pwd()
/examples

os.mkdir(path)

Создает директорию.

Аргументы:

• path: путь к создаваемой директории

Возвращает: true в случае успеха, false в случае неудачи.

/ > os.mkdir("/tmp/newdir")
true

os.stats([what])

Выполняет полную сборку мусора и возвращает или печатает сведения о памяти системы.

Аргументы:

• what = "mem": вернуть объём свободной памяти;
• what = "table": вернуть таблицу с полями free и min;
• без аргумента: напечатать текущий и минимальный объём свободной памяти и ничего не возвращать.

Возвращает: число для "mem", таблицу для "table" или ничего без аргумента.

-- Напечатать текущую и минимальную свободную память
/ > os.stats()
Free mem: 45632
Free mem min: 40128

-- Получить свободную память числом
/ > free = os.stats("mem")

-- Детальная информация
/ > s = os.stats("table")
/ > print(s.free, s.min)

os.format(path)

Форматирует файловую систему.

Аргументы:

• path: путь к монтированной файловой системе

Возвращает: ничего. Требует подтверждение пользователя.

/ > os.format("/sd")
This will erase all data in /sd. Are you sure? (y/n): y
Format complete

os.cat(path)

Выводит содержимое файла на консоль.

Аргументы:

• path: путь к файлу

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

/ > os.cat("/system.lua")
-- contents of file...

os.more(path)

Выводит содержимое файла на консоль с постраничным просмотром.

Аргументы:

• path: путь к файлу

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

/ > os.more("/largefile.txt")
-- shows content page by page --
Press any key to continue...

os.dmesg()

Выводит содержимое системного журнала (kernel log).

Аргументы: нет

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

/ > os.dmesg()
[    0.000] boot: ESP-IDF v4.4.1-dirty 2nd stage bootloader
...

os.run([code])

Выполняет Lua код. Если код не указан, принимает ввод с UART.

Аргументы:

• code (опционально): строка с Lua кодом для выполнения

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

-- Выполнить код из строки
/ > os.run("print('Hello from run')")
Hello from run

-- Ввести код интерактивно
/ > os.run()
> local x = 10
> print(x * 2)
> -- Ctrl+D для завершения
20

os.lua_running()

Проверяет, запущен ли Lua.

Аргументы: нет

Возвращает: true если Lua запущен, false в противном случае.

/ > os.lua_running()
true

os.lua_interpreter()

Проверяет, активен ли Lua интерпретатор.

Аргументы: нет

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

/ > os.lua_interpreter()
true

os.bootcount()

Возвращает счетчик загрузок системы.

Аргументы: нет

Возвращает: число (количество загрузок).

/ > os.bootcount()
42

os.edit(path)

Запускает текстовый редактор для редактирования файла.

Аргументы:

• path: путь к файлу для редактирования

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

/ > os.edit("/system.lua")
-- открывается редактор --

os.df([path [, console]])

Возвращает информацию о свободном месте на диске (disk free).

Аргументы:

• path (опционально): путь к файловой системе. По умолчанию “/”.
• console (опционально): если true, выводит информацию в консоль.

Возвращает: свободное место и общий размер либо ничего (если console = true). Каждое значение возвращается числом, пока помещается в lua_Integer, иначе точной десятичной строкой. Поэтому том размером 2 ГиБ в стандартном 32-битном Lua-профиле возвращает строку "2147483648", а не отрицательное число.

-- Вывод в консоль
/ > os.df("/sd", true)
Free: 1024 MB, Total: 2048 MB

-- Получить значения
/ > free, total = os.df("/sd")
/ > print(free, type(total), total)
1073741824 string 2147483648

os.locks()

Выводит список заблокированных драйверов).

Аргументы: нет

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

/ > os.locks()
Driver       Owner
------------------------
GPIO         task1
UART         task2

os.cp(src, dst)

Копирует файл через временный файл в каталоге назначения. Готовый временный файл заменяет dst атомарным rename(): при нехватке памяти, ошибке чтения или записи прежний файл назначения остаётся неизменным, а незавершённый временный файл удаляется.

Аргументы:

• src: путь к исходному файлу
• dst: путь к целевому файлу

Возвращает: true в случае успеха, false в случае неудачи.

/ > os.cp("/system.lua", "/backup/system.lua")
true