Tự viết ứng dụng cho VReader

Bộ đếm, thẻ từ vựng, theo dõi thói quen, hẹn giờ, trò chơi nhỏ… Bạn không cần biết lập trình: nhờ trợ lý AI như Claude hay ChatGPT viết giúp, rồi chép một tệp vào thẻ nhớ.

Có trong bản cập nhật phần mềm sắp tới. Phần mềm hiện tại (1.0.4) chưa chạy được ứng dụng tự viết. Trong lúc chờ, bạn đã có thể viết và chạy thử ngay trên trình duyệt.

Ứng dụng là gì

Một ứng dụng là một tệp chữ nhỏ, đuôi .lua, viết bằng ngôn ngữ Lua. Tệp đó nói cho máy biết vẽ gì lên màn hình (chữ, khung, nút) và làm gì khi bạn chạm vào. Máy đọc tệp từ thẻ nhớ và chạy nó trong mục Ứng dụng.

Bạn chỉ cần nói bằng lời mình muốn gì. Trợ lý AI viết tệp, bạn chép tệp vào thẻ. Muốn sửa thì nói tiếp với AI.

Năm bước (khoảng 10 phút)

  1. Chép lời nhắn cho AI ở cuối trang này (nút Chép) và dán vào Claude, ChatGPT hoặc trợ lý AI bạn hay dùng.
  2. Ở cuối lời nhắn, dưới dòng "My app", mô tả ứng dụng bạn muốn. Ví dụ: "Ứng dụng đếm số trang tôi đọc mỗi ngày, có nút +10 trang, hiện tổng của tuần này. Chữ trên màn hình bằng tiếng Việt."
  3. AI trả về một tệp Lua. Lưu tệp đó với tên ngắn, không dấu, không khoảng trắng, đuôi .lua, ví dụ dem-trang.lua. Muốn xem trước: dán vào trình mô phỏng và bấm Chạy.
  4. Cắm máy vào máy tính bằng cáp USB-C (hoặc cắm thẻ nhớ vào máy tính). Tạo thư mục apps ở thư mục gốc của thẻ, chép tệp vào đó: apps/dem-trang.lua. Ngắt kết nối trên máy tính rồi rút cáp.
  5. Trên máy, mở Ứng dụng → Ứng dụng của bạn và chạm vào ứng dụng.

Muốn sửa: nói với AI điều cần đổi ("nút to hơn", "thêm nút xoá"), chép đè tệp cũ trên thẻ, mở lại ứng dụng.

Khi ứng dụng báo lỗi

  • Tệp chưa hoàn chỉnh (chép thiếu, AI viết sai cú pháp): ứng dụng vẫn hiện trong danh sách, nhưng dòng mô tả ghi Lỗi dòng 12: ….
  • Lỗi khi đang chạy: máy hiện Ứng dụng dừng vì lỗi kèm thông báo, ví dụ dem-trang:12: attempt to add a nil value. Số 12 là dòng bị lỗi.

Cách sửa: chép nguyên dòng báo lỗi, gửi cho AI và nhờ sửa: "Máy báo lỗi: dem-trang:12: attempt to add a nil value. Hãy sửa và gửi lại cả tệp." Rồi chép tệp mới đè lên tệp cũ.

Giới hạn

  • Danh sách hiện tối đa 8 ứng dụng (8 tên đầu theo thứ tự chữ cái); mỗi tệp tối đa 64 KB, tên tệp tối đa 31 ký tự. Tệp quá lớn, rỗng hoặc tên quá dài vẫn hiện trong danh sách, kèm lý do.
  • Mỗi ứng dụng lưu được một ít dữ liệu của riêng nó (4 KB), ví dụ số đếm hay danh sách việc đã xong.
  • Màn hình giấy điện tử vẽ lại chậm (khoảng nửa giây mỗi lần, có nháy). Ứng dụng hợp nhất là loại ít đổi màn hình, nút to, chữ to. Không hợp với trò chơi cần chuyển động nhanh.
  • Nhập liệu bằng cách chạm. Không có bàn phím trong ứng dụng.
  • Ứng dụng không dùng Internet.

An toàn

  • Ứng dụng chạy trong một vùng riêng: không đọc hay sửa được sách, cài đặt, từ vựng hay dữ liệu của ứng dụng khác. Nó chỉ ghi được tệp dữ liệu của chính nó.
  • Ứng dụng chạy quá lâu, dùng quá nhiều bộ nhớ hoặc bị lỗi sẽ tự dừng; máy vẫn chạy bình thường. Chạm mũi tên quay lại để thoát.
  • Muốn gỡ một ứng dụng: xoá tệp của nó trong thư mục apps.
  • Chỉ chép những tệp bạn tự làm hoặc lấy từ nơi bạn tin.

Ứng dụng mẫu

Sáu ứng dụng có sẵn để dùng ngay hoặc gửi cho AI làm mẫu. Tải tệp về, chép vào thư mục apps trên thẻ. Cả sáu đều có trong trình mô phỏng.

Xin chào

Bộ đếm nhỏ nhất: bấm +1, số được lưu lại.

Tải hello.lua

Thẻ từ

Ôn từ vựng: chạm thẻ để lật, chọn Biết hoặc Chưa biết.

Tải the-tu.lua

Thói quen

Đánh dấu thói quen mỗi ngày trong tuần này. Cần đặt ngày giờ.

Tải thoi-quen.lua

Xếp số

Trò trượt ô xếp từ 1 đến 15: một ứng dụng đầy đủ để tham khảo.

Tải slide.lua

Lời nhắn cho AI

Chép toàn bộ khung dưới đây vào trợ lý AI, rồi viết ứng dụng bạn muốn ở cuối, sau dòng "My app". Lời nhắn bằng tiếng Anh để AI hiểu đúng; bạn cứ mô tả bằng tiếng Việt.

Lời nhắn (tiếng Anh)
You are writing a small app for an e-ink e-reader (the E707). Apps are written in **Lua 5.4** and run in a sandbox.
Reply with ONE complete Lua file in a single code block (the user saves it as `apps/<name>.lua` on the card).

## Screen and input
- Screen 758 x 1024 pixels, portrait, black and white with 16 greys. (0,0) is the top-left corner.
- The device draws a header with the app's name and a back arrow at the top. Your area starts at `gfx.top`
  (130) and ends at 1010. Do not draw above `gfx.top`.
- Input is touch (`tap(x, y)`) and three keys: "up", "down", "select". There is no keyboard, no swipe and no
  long press.
- E-ink is slow: every redraw takes about half a second and flashes. Redraw only when something visible changed.
  Use big touch targets (at least 80 x 80 pixels) and big text (22 or more).

## Callbacks (define any of these as global functions)
- `open()` — the app starts. Load saved data here.
- `draw()` — draw the whole screen. The screen is already white. Only draw inside `draw()`.
- `tap(x, y)` — the screen was touched. Return `true` to have `draw()` called again.
- `key(k)` — k is "up", "down" or "select". Return `true` to redraw.
- `tick()` — the timer fired (see `device.every`). Return `true` to redraw.
- `close()` — the app is closed.

## Drawing (gfx)
- `gfx.width` = 758, `gfx.height` = 1024, `gfx.top` = 130
- `gfx.text(x, y, text, size, bold)` — size 10..120 (default 26), bold true/false. (x, y) is the top-left of the
  text. Text is ONE line: it is cut with "…" at the right edge, so wrap long text yourself into several calls.
  Vietnamese and other UTF-8 text works.
- `gfx.rect(x, y, w, h, thickness)` — an outline (thickness default 3)
- `gfx.fill(x, y, w, h, color)` — a filled box; color 0 = black .. 255 = white (default 0)
- `gfx.circle(cx, cy, r, color)` — a filled circle
- `gfx.line(x0, y0, x1, y1, width, color)`
- `gfx.button(x, y, w, h, label, size, filled)` — a ready-made button (outline, or black with white text when
  filled is true). Check taps on it yourself in `tap`.

## Saving and the device
- `data.save(text)` — saves one string (at most 4096 bytes) for this app; returns true when it was saved.
  `data.load()` returns it, or nil. Store numbers and lists as text, e.g. "3 7 12" or "key=value" pairs. Save when
  something changed, not in a loop.
- `device.every(seconds)` — calls `tick()` every 1..3600 seconds while the app is open; `device.every(0)` stops it.
- `device.date()` — a table {year, month, day, hour, min, sec, wday} (wday 1 = Monday .. 7 = Sunday), or nil if
  the clock is not set. Handle nil.
- `device.battery()` — percent (or nil) and whether it is charging.
- `device.millis()` — milliseconds since the app was opened.
- `print(...)` — writes to the debug log (not the screen); lines are cut at 120 characters.

## Limits (the app stops with an error if it breaks one)
- Available: Lua base functions, `string`, `table`, `math` (incl. `math.random`), `utf8`.
  NOT available: `io`, `os`, `require`, `load`, `dofile`, `debug`, `collectgarbage`, network, other files.
  `setmetatable` works but `__gc` is not allowed.
- Keep nesting shallow: at most about 15 nested `pcall`s or metamethod calls, and no more than 40 levels of nested
  blocks, functions, brackets and tables in the source ("C stack overflow" otherwise). Plain recursion of your own
  Lua functions is fine.
- Numbers are 32-bit: integers up to about 2 billion; floats are single precision.
- 256 KB of memory, `main.lua` at most 64 KB, a limited amount of work per callback (no endless loops, no
  long computations in one call), at most about 4000 drawing calls per redraw.
- Use `string.len`/`#` for bytes but `utf8.len` for letters: Vietnamese letters take 2-3 bytes.

## File format
Start the file with two comment lines; they name the app in the device's app list:

```lua
-- title: Short name
-- blurb: One line saying what it does
```

## Example

```lua
-- title: Xin chào
-- blurb: A counter that remembers its number

local count = 0

function open()
  count = tonumber(data.load() or "0") or 0
end

function draw()
  gfx.text(24, 150, "Hello!", 36, true)
  gfx.text(24, 300, tostring(count), 120, true)
  gfx.button(24, 520, 340, 90, "+1", 40, true)
  gfx.button(394, 520, 340, 90, "Reset", 32)
end

function tap(x, y)
  if y >= 520 and y < 610 then
    if x < 380 then count = count + 1 else count = 0 end
    data.save(tostring(count))
    return true
  end
  return false
end
```

## My app
(Describe the app you want here. Write texts shown on screen in the language you want, e.g. Vietnamese.)