1. Tổng Quan Dự Án: Lợi Ích Của Việc Mô Phỏng AirUI Trên Máy Tính

LuatOS là một hệ điều hành thời gian thực (RTOS) nhẹ dành cho các thiết bị IoT, đi kèm với AirUI - một framework giao diện người dùng đồ họa được tối ưu hóa để chạy mượt mà trên các vi điều khiển (MCU) có tài nguyên hạn chế. Tuy nhiên, việc liên tục biên dịch, nạp firmware và khởi động lại phần cứng thật chỉ để tinh chỉnh một chi tiết nhỏ trên giao diện sẽ làm giảm đáng kể năng suất phát triển.

Thiết lập một môi trường mô phỏng LuatOS trên PC để chạy AirUI tạo ra một sandbox调试 (debug) hiệu quả. Môi trường này cho phép lập trình viên xem trước bố cục giao diện, kiểm thử logic tương tác và xác minh mã nghiệp vụ ngay lập tức mà không cần phụ thuộc vào phần cứng vật lý. Điều này đặc biệt hữu ích trong giai đoạn thiết kế UI/UX ban đầu, xác thực luồng dữ liệu và trình diễn sản phẩm.

2. Chuẩn Bị Môi Trường Và Công Cụ

2.1. Tải Và Cài Đặt LuatOS Simulator

LuatOS Simulator là công cụ chính để chạy mã Lua trên PC. Quy trình thiết lập bao gồm các bước sau:

• Tải xuống: Truy cập kho lưu trữ GitHub chính thức của LuatOS, tìm đến thư mục tools hoặc trang Release để tải gói biên dịch sẵn của LuatOS-Simulator (thường là file ZIP chứa simulator.exe cho Windows).
• Đồng bộ phiên bản: Phiên bản của Simulator nên tương đồng với phiên bản firmware LuatOS đang chạy trên phần cứng mục tiêu (ví dụ: Air780E, Air601). Sự chênh lệch phiên bản có thể dẫn đến hành vi API không nhất quán. Nếu không chắc chắn, hãy chọn bản Stable Release mới nhất.
• Giải nén: Giải nén gói tải về vào một thư mục có đường dẫn hoàn toàn bằng tiếng Anh và không chứa dấu cách (ví dụ: D:\LuatOS_Simulator). Nhiều công cụ và script nội bộ không xử lý tốt đường dẫn chứa ký tự Unicode, dễ dẫn đến lỗi khởi động.

2.2. Cấu Trúc Và Thích Nghi Mã Nguồn AirUI

Một dự án AirUI tiêu chuẩn thường chứa các file mô tả giao diện, tài nguyên đồ họa và script logic. Cấu trúc thư mục cơ bản như sau:

IoT_Dashboard/
├── layouts/          # File bố cục UI (JSON/Lua)
│   ├── home.json
│   └── settings.json
├── assets/           # Tài nguyên (ảnh, icon)
│   ├── bg_dark.png
│   └── icon_wifi.png
├── fonts/            # File font chữ
│   └── roboto.ttf
└── main.lua          # Script khởi chạy

Thích nghi mã nguồn cho môi trường PC:

• Đường dẫn tệp: Trên thiết bị thật, đường dẫn có thể bắt đầu bằng /luadb/, nhưng trên Simulator thường sử dụng đường dẫn tương đối hoặc tuyệt đối của hệ thống tệp ảo. Cần chuẩn hóa các hàm đọc/ghi tệp.
• API phần cứng: Các hàm như gpio.setup hoặc i2c.send có thể không tồn tại hoặc trả về giá trị giả lập trên PC. Cần bọc các lệnh này trong các hàm trừu tượng hóa để tránh lỗi sập script.

-- Hàm trừu tượng hóa thiết lập chân GPIO
local function configure_pin(pin_id, default_state)
    if type(gpio) == "table" and type(gpio.setup) == "function" then
        gpio.setup(pin_id, default_state)
    else
        log.warn("ENV", "Bỏ qua thiết lập GPIO cho chân:", pin_id)
    end
end

2.3. Tích Hợp Dự Án Vào Simulator

Simulator cần được chỉ định vị trí chứa mã nguồn của dự án. Thông thường, mã người dùng sẽ được đặt trong thư mục app hoặc script bên trong thư mục gốc của Simulator. Sau khi sao chép thư mục dự án vào vị trí quy định, cần cấu hình script khởi động của Simulator để nạp đúng file main.lua của dự án.

-- Thêm vào file khởi động mặc định của Simulator
local project_status, project_entry = pcall(require, "app.IoT_Dashboard.main")
if not project_status then
    log.error("BOOT", "Không thể khởi động dự án:", project_entry)
end

3. Khởi Chạy Simulator Và Nạp Giao Diện AirUI

3.1. Thực Thi Simulator

Mở terminal (CMD hoặc PowerShell), điều hướng đến thư mục chứa Simulator và thực thi file chạy:

cd D:\LuatOS_Simulator
.\simulator.exe

Giữ cửa sổ terminal mở để theo dõi luồng log. Mọi lỗi cú pháp Lua hoặc lỗi thiếu tệp tài nguyên sẽ được in ra tại đây trước khi cửa sổ đồ họa được render.

3.2. Khởi Tạo Engine Và Cửa Sổ Chính

Trong file main.lua của dự án, tiến hành khởi tạo instance của AirUI và thiết lập cửa sổ hiển thị:

local air_ui = require("ui")
local sys = require("sys")

local gui_manager = air_ui.Application()
-- Thiết lập độ phân giải màn hình giả lập (ví dụ: 480x320)
local primary_screen = air_ui.Window(480, 320, "Bảng Điều Khiển IoT")

gui_manager:run(primary_screen)

3.3. Nạp Bố Cục Và Tài Nguyên

Sau khi cửa sổ được tạo, tiến hành nạp file JSON mô tả giao diện và các tài nguyên đi kèm:

-- Nạp bố cục từ đường dẫn ảo của Simulator
local layout_node = primary_screen:loadUI("/app/IoT_Dashboard/layouts/home.json")

-- Xử lý an toàn khi tải hình ảnh
local is_loaded, bg_asset = pcall(air_ui.Image, "/app/IoT_Dashboard/assets/bg_dark.png")
if not is_loaded then
    log.error("ASSET", "Lỗi tải hình nền:", bg_asset)
else
    layout_node:setBackground(bg_asset)
end

Ngoài việc nạp từ JSON, các control có thể được khởi tạo động bằng mã Lua:

local action_btn = air_ui.Button(120, 40)
action_btn:setText("Kích Hoạt Relay")
action_btn:setPosition(180, 240)
primary_screen:addView(action_btn)

action_btn:onClick(function()
    log.info("ACTION", "Nút Relay đã được nhấn")
    -- Thực thi logic cập nhật trạng thái UI
end)

4. Kỹ Thuật Debug Và Tối Ưu Hóa Hiệu Năng

4.1. Khai Thác Console Log

Sử dụng hệ thống log phân cấp để theo dõi luồng dữ liệu và trạng thái của các component:

local function process_sensor_payload(raw_bytes)
    log.debug("SENSOR", "Dữ liệu thô:", raw_bytes:toHex())
    local decoded = json.decode(raw_bytes)
    if decoded and decoded.temp then
        log.info("SENSOR", "Nhiệt độ hiện tại:", decoded.temp)
        update_temperature_label(decoded.temp)
    else
        log.error("SENSOR", "Giải mã JSON thất bại")
    end
end

4.2. Giả Lập Sự Kiện Phần Cứng

Để kiểm thử các luồng nghiệp vụ phụ thuộc vào phần cứng (như nhận gói tin MQTT hoặc chạm màn hình), có thể tiêm các sự kiện giả lập thông qua các nút debug ẩn hoặc biến môi trường:

-- Tạo nút giả lập sự kiện mạng khi chạy trên Simulator
if os.getenv("SIMULATOR_MODE") then
    local mock_btn = air_ui.Button(80, 30)
    mock_btn:setText("Mock Net")
    mock_btn:setPosition(10, 10)
    mock_btn:onClick(function()
        inject_mock_mqtt_message('{"status": "online", "temp": 25.5}')
    end)
    primary_screen:addView(mock_btn)
end

4.3. Quan Sát Và Cải Thiện Hiệu Suất

LuatOS hoạt động theo mô hình sự kiện đơn luồng. Mọi tác vụ UI và logic Lua đều chạy trên cùng một vòng lặp (main loop). Việc thực thi các tác vụ đồng bộ tốn nhiều thời gian sẽ làm đóng băng giao diện.

-- Cách tiếp cận sai: Vòng lặp nặng làm đóng băng UI
action_btn:onClick(function()
    local hash_result = ""
    for idx = 1, 500000 do
        hash_result = hash_result .. crypto.md5(tostring(idx))
    end
    display_hash(hash_result)
end)

-- Cách tiếp cận đúng: Sử dụng sys.taskInit để chạy bất đồng bộ
action_btn:onClick(function()
    sys.taskInit(function()
        local hash_result = compute_hash_async()
        display_hash(hash_result)
    end)
end)

Bên cạnh đó, cần đảm bảo kích thước ảnh tài nguyên khớp với kích thước control hiển thị để giảm tải cho bộ nhớ RAM và bộ giải mã ảnh của MCU khi đưa lên thiết bị thật.

5. Xử Lý Các Lỗi Thường Gặp