doc: add docs for sdcard, wifi & transforms (closes #107) (#112)

keira: rename imageTransform to transforms, construct transform with transforms.new()
keira: fix FTP app crashing when WiFi is down
keira: lua: add gpio.INPUT_PULLDOWN
keira: fix Lua sample scripts

docs/keira/lua/reference/index.rst

@@ -8,11 +8,14 @@ Lua API
 
     lilka
     display
+    transform
     controller
     resources
     math
     geometry
     gpio
     util
     buzzer
+    sdcard
     state
+    wifi

docs/keira/lua/reference/sdcard.rst

@@ -0,0 +1,16 @@
+``sdcard`` - Робота з SD-картою
+-------------------------------
+
+Функції для роботи читання/запису файлів на SD-карті.
+
+Приклад:
+
+.. code-block:: lua
+    :linenos:
+
+    local file = sdcard.open("file.txt", "w")
+    file:write("Hello, world!")
+
+.. lua:autoclass:: sdcard
+
+.. lua:autoclass:: File

docs/keira/lua/reference/transform.rst

@@ -0,0 +1,18 @@
+``transform`` - Перетворення зображень
+--------------------------------------
+
+Функції для обертання та масштабування зображень.
+
+Приклад:
+
+.. code-block:: lua
+
+    local image = resource.load_image("face.bmp", display.color565(0, 0, 0))
+    local transform = transforms.new()
+    transform = transform:scale(1.5, 0.5)
+    transform = transform:rotate(45)
+    display.draw_image(image, 50, 80, transform) -- малює зображення в точці (50, 80) з перетвореннями
+
+.. lua:autoclass:: transforms
+
+.. lua:autoclass:: Transform

docs/keira/lua/reference/wifi.rst

@@ -0,0 +1,18 @@
+``wifi`` - Робота з WiFi-мережами
+---------------------------------
+
+Функції для роботи з WiFi-мережами.
+
+Приклад:
+
+.. code-block:: lua
+    :linenos:
+
+    local networks = wifi.scan()
+    for i = 0, #networks do
+        print(networks[i])
+        print('Сила сигналу: ', wifi.get_rssi(i))
+        print('Тип шифрування: ', wifi.get_encryption_type(i))
+    end
+
+.. lua:autoclass:: wifi

firmware/keira/sdcard/sdcard_test.lua

@@ -1,19 +1,15 @@
 local file_dir = sdcard.ls("/")
 
 print(#file_dir)
-
-for i = 0, #file_dir do 
-    print(file_dir[i])
+for i = 0, #file_dir do
+    print('*', file_dir[i])
 end
 
-file = file("/test.txt", "a+") 
-
-file:write("HELLOWORLD") 
+local file = sdcard.open("/test.txt", "a+")
+file:write("HELLOWORLD")
 
-text = file:read(5) 
+local text = file:read(5)
+print(text)
 
-print(text) 
-
-size = file:size()
+local size = file:size()
 print(size)
-

firmware/keira/sdcard/test_draw_image.lua

@@ -30,7 +30,7 @@ for i = 10, 1, -1 do
     local scaleX = math.min({ math.random(), 0.1 })
     local scaleY = math.min({ math.random(), 0.1 })
 
-    local transform = imageTransform()
+    local transform = transforms.new()
 
     transform = transform:rotate(rot)
 

firmware/keira/sdcard/wifi_test.lua

@@ -1,18 +1,16 @@
-status = wifi.get_status()
+local status = wifi.get_status()
 print(status)
 
 wifi.disconnect()
 
 status = wifi.get_status()
 print(status)
 
-scan = wifi.scan()
+local scan = wifi.scan()
 
 print(#scan)
 for i = 1, #scan do -- This will cycle through and print each element of the array
-    print(scan[i])
-    rssi = wifi.get_rssi(i)
-    print(rssi)
-    rssi = wifi.get_encryption_type(i)
-    print(rssi)
+    local rssi = wifi.get_rssi(i)
+    local enc_type = wifi.get_encryption_type(i)
+    print(scan[i], rssi, enc_type)
 end

firmware/keira/src/apps/ftp/ftp_server.cpp

@@ -3,6 +3,8 @@
 #include <FtpServer.h>
 
 #include "ftp_server.h"
+#include "servicemanager.h"
+#include "services/network.h"
 
 FTPServerApp::FTPServerApp() : App("FTP Server") {
 }
@@ -15,6 +17,29 @@ void FTPServerApp::run() {
 
     lilka::fileutils.initSD();
 
+    NetworkService* networkService = ServiceManager::getInstance()->getService<NetworkService>("network");
+
+    if (networkService->getNetworkState() != NETWORK_STATE_ONLINE) {
+        canvas->fillScreen(0);
+        canvas->setCursor(16, 16);
+        canvas->setTextBound(16, 16, canvas->width() - 32, canvas->height() - 32);
+        canvas->printf("WiFi не підключено\n"
+                       "\n"
+                       "Підключіться до мережі\n"
+                       "та спробуйте ще раз\n"
+                       "\n"
+                       "Натисніть [A] для виходу");
+        queueDraw();
+
+        while (true) {
+            lilka::State state = lilka::controller.getState();
+            if (state.a.justPressed) {
+                return;
+            }
+            taskYIELD();
+        }
+    }
+
     FtpServer ftpSrv;
     ftpSrv.begin("lilka", password.c_str());
 

firmware/keira/src/apps/lua/lualilka_display.cpp

@@ -257,7 +257,7 @@ int lualilka_display_drawImage(lua_State* L) {
 };
 
 int lualilka_display_drawImageTransformed(lua_State* L) {
-    // Args are image table, X & Y, imageTransform object
+    // Args are image table, X & Y, Transform object
     // First argument is table that contains image width, height and pointer. We only need the pointer.
     lua_getfield(L, 1, "pointer");
 

firmware/keira/src/apps/lua/lualilka_gpio.cpp

@@ -50,6 +50,8 @@ int lualilka_gpio_register(lua_State* L) {
     lua_setfield(L, -2, "OUTPUT");
     lua_pushinteger(L, INPUT_PULLUP);
     lua_setfield(L, -2, "INPUT_PULLUP");
+    lua_pushinteger(L, INPUT_PULLDOWN);
+    lua_setfield(L, -2, "INPUT_PULLDOWN");
     lua_setglobal(L, "gpio");
     return 0;
 }

firmware/keira/src/apps/lua/lualilka_imageTransform.cpp

@@ -99,8 +99,15 @@ static int lualilka_imageTransform_set_matrix(lua_State* L) {
     return 0;
 }
 
+static const luaL_Reg lualilka_transforms[] = {
+    {"new", lualilka_create_object_imageTransform},
+    {nullptr, nullptr},
+};
+
 int lualilka_imageTransform_register(lua_State* L) {
-    lua_register(L, IMAGE_TRANSFORM, lualilka_create_object_imageTransform);
+    luaL_newlib(L, lualilka_transforms);
+    lua_setglobal(L, "transforms");
+
     luaL_newmetatable(L, IMAGE_TRANSFORM);
     lua_pushcfunction(L, lualilka_delete_object_imageTransform);
     lua_setfield(L, -2, "__gc");
@@ -124,5 +131,6 @@ int lualilka_imageTransform_register(lua_State* L) {
     lua_setfield(L, -2, "vtransform");
 
     lua_pop(L, 1);
+
     return 0;
 }

firmware/keira/src/apps/lua/lualilka_imageTransform.h

@@ -3,6 +3,6 @@
 #include <lilka.h>
 #include <lua.hpp>
 
-#define IMAGE_TRANSFORM "imageTransform"
+#define IMAGE_TRANSFORM "Transform"
 
 int lualilka_imageTransform_register(lua_State* L);

firmware/keira/src/apps/lua/lualilka_sdcard.cpp

@@ -160,11 +160,14 @@ static const luaL_Reg lualilka_sdcard[] = {
     {"ls", lualilka_sdcard_list_dir},
     {"remove", lualilka_sdcard_remove},
     {"rename", lualilka_sdcard_rename},
+    {"open", lualilka_create_object_file},
     {NULL, NULL},
 };
 
 int lualilka_sdcard_register(lua_State* L) {
-    lua_register(L, FILE_OBJECT, lualilka_create_object_file);
+    luaL_newlib(L, lualilka_sdcard);
+    lua_setglobal(L, "sdcard");
+
     luaL_newmetatable(L, FILE_OBJECT);
     lua_pushcfunction(L, lualilka_delete_object_file);
     lua_setfield(L, -2, "__gc");
@@ -182,8 +185,5 @@ int lualilka_sdcard_register(lua_State* L) {
 
     lua_pop(L, 1);
 
-    luaL_newlib(L, lualilka_sdcard);
-    lua_setglobal(L, "sdcard");
-
     return 0;
 }

firmware/keira/src/apps/lua/lualilka_sdcard.h

@@ -3,6 +3,6 @@
 #include <lua.hpp>
 #include <Arduino.h>
 #include <SD.h>
-#define FILE_OBJECT "file"
+#define FILE_OBJECT "File"
 
 int lualilka_sdcard_register(lua_State* L);

sdk/addons/lualilka/library/display.lua

@@ -186,10 +186,10 @@ function display.draw_image(image, x, y) end
 ---@param image table ідентифікатор зображення
 ---@param x integer координата x лівого верхнього кута зображення
 ---@param y integer координата y лівого верхнього кута зображення
----@param transform userdata перетворення (TODO: додати опис модуля imageTransform)
+---@param transform Transform перетворення
 ---@usage
 --- local image = resource.load_image("face.bmp", display.color565(0, 0, 0))
---- local transform = imageTransform()
+--- local transform = transforms.new()
 --  transform = transform:scale(1.5, 0.5)
 --- transform = transform:rotate(45)
 --- display.draw_image(image, 50, 80, transform) -- малює зображення в точці (50, 80) з перетвореннями

sdk/addons/lualilka/library/gpio.lua

@@ -6,11 +6,12 @@
 ---@field INPUT integer режим введення
 ---@field OUTPUT integer режим виведення
 ---@field INPUT_PULLUP integer режим введення з підтяжкою вгору
+---@field INPUT_PULLDOWN integer режим введення з підтяжкою вниз
 gpio = {}
 
 ---Налаштовує режим GPIO-піна.
 ---@param pin integer номер піна
----@param mode integer режим піна, може бути ``gpio.INPUT``, ``gpio.OUTPUT`` або ``gpio.INPUT_PULLUP``
+---@param mode integer режим піна, може бути ``gpio.INPUT``, ``gpio.OUTPUT``, ``gpio.INPUT_PULLUP`` або ``gpio.INPUT_PULLDOWN``
 function gpio.set_mode(pin, mode) end
 
 ---Записує цифрове зрачення в GPIO-пін.

sdk/addons/lualilka/library/sdcard.lua

@@ -0,0 +1,72 @@
+---@meta
+
+---@class sdcard
+sdcard = {}
+
+---Повернути таблицю зі списком файлів та директорій за вказаним шляхом.
+---
+---@param path string шлях до директорії (відносно кореня SD-картки)
+---@return table
+---@usage
+--- local entries = sdcard.ls("/folder")
+--- for i = 0, #entries do
+---     print(entries[i])
+--- end
+function sdcard.ls(path) end
+
+---Видалити файл або директорію за вказаним шляхом.
+---
+---@param path string шлях до файлу або директорії (відносно кореня SD-картки)
+---@usage
+--- sdcard.remove("/folder/file.txt")
+function sdcard.remove(path) end
+
+---Перейменувати файл або директорію.
+---
+---@param old_path string старий шлях до файлу або директорії (відносно кореня SD-картки)
+---@param new_path string новий шлях до файлу або директорії (відносно кореня SD-картки)
+---
+---@usage
+--- sdcard.rename("/folder/file.txt", "/folder/file2.txt")
+function sdcard.rename(old_path, new_path) end
+
+---@class File
+File = {}
+
+---Відкрити файл за вказаним шляхом.
+---
+---@param path string шлях до файлу (відносно кореня SD-картки)
+---@param mode string режим відкриття файлу (див. функцію ``fopen`` у документації ANSI C)
+---@return File
+---
+---@usage
+--- local file = sdcard.open("/file.txt", "a+") -- Відкриває файл для додавання тексту
+--- file:write("Hello, world!\n") -- Дописує текст в кінець файлу
+function sdcard.open(path, mode) end
+
+---Повернути розмір файлу.
+---
+---@return integer
+function File:size() end
+
+---Перемістити вказівник файлу на певну позицію.
+---
+---@param pos integer позиція в файлі
+function File:seek(pos) end
+
+---Прочитати з файлу.
+---
+---@param count integer максимальна кількість байт, які потрібно прочитати
+---@return string
+function File:read(count) end
+
+---Записати у файл.
+---
+---@param content string дані, які потрібно записати
+---@usage
+--- local file = sdcard.open("/file.txt", "w") -- Відкриває файл для запису
+--- file:write("Hello, world!\n") -- Записує текст у файл
+--- file:write("Привіт, світ!\n") -- Дописує текст у файл
+function File:write(content) end
+
+return sdcard