記錄與傾印

這一頁介紹幾個把資料留下記錄用的函式：dump() 印出目前這一頁的暫存器內容、 dump_all() 依 Bank 逐頁存成檔案、file.append() 讓腳本自己寫檔，以及 timestamp() 產生時間字串（例如拿來當檔名的一部分）。

dump([slot])：印出並回傳目前分頁的 256 個位元組

local t = dump()   -- 印出目前分頁 256 個位元組的內容，同時回傳一個 table

印出來是一張十六進位表格（每列 16 個位元組），跟畫面上的暫存器表用同一種排版； 回傳值是一個從 t[1] 到 t[256] 的 table，方便腳本接著自己判斷內容。

file.append(檔名, 字串)：把字串附加寫進一個檔案

file.append("my_result.txt", "run 1: PASS\n")

把字串原樣附加寫進目前資料夾（執行時的工作目錄）底下 logs/ 資料夾裡的一個 檔案；logs/ 資料夾不存在會自動建立，檔案不存在也會自動建立。多次呼叫是純附加， 不會覆蓋之前寫過的內容。檔名限定英數字、.、_、-，長度 1~64 個字元。

timestamp()：目前時間字串

local ts = timestamp()   -- 例如 "20260928_221030"，格式固定是 YYYYMMDD_HHMMSS

回傳的字串長度固定是 15 個字元，適合拿來當檔名的一部分，讓每次執行寫出的檔案 名稱都不一樣。

範例：dump()、file.append()、timestamp() 一次看

-- 先設定這顆 IC 的 slave 位址，之後才能用 i2c.* 存取（見「I2C 讀寫」頁）。
i2c.addr(0x58)

-- 展示 dump() 傾印暫存器、file.append() 寫檔，以及 timestamp() 產生時間字串
-- （時間值本身會變動，範例只檢查長度，不印出實際值）。
local t = {}
for i = 0, 255 do
  t[i + 1] = i
end
i2c.write(0, t)

dump()

local ts = timestamp()
check(#ts == 15, "timestamp length is 15")

file.append("lua_example_dump_log.txt", "dump_log example ran\n")
log("info", "dump_log example done")

DUMP: Addr 0x58 Bank 0x00 (256 bytes)
        00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0x0000  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0x0010  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
0x0020  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F
0x0030  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
0x0040  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
0x0050  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F
0x0060  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F
0x0070  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F
0x0080  80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F
0x0090  90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
0x00A0  A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF
0x00B0  B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF
0x00C0  C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF
0x00D0  D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF
0x00E0  E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF
0x00F0  F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF
CHECK OK: timestamp length is 15
dump_log example done

dump_all([slot [, count]])：依 Bank 逐頁把暫存器內容存成檔案

dump_all() 沒有現成的範例可以跑（它寫出的檔名裡帶著執行當下的時間，每次跑 出來的內容都不一樣，沒辦法像其他範例一樣附一份固定的「預期輸出」），這裡直接 說明它的行為：

• 這個掛載沒設定過 Bank 頁碼暫存器時（沒呼叫過Bank 切換講過 的 i2c.bank_reg()，也沒下過 bank reg <位移> <遮罩>）：省略 count （或給 1）dump_all() 照樣能跑，當成「這顆 IC 沒有 Bank」處理，只傾印 目前這一頁（1 頁）。給大於 1 的 count 會直接出錯（訊息提醒你先用 i2c.bank_reg() 設定頁碼暫存器）——沒有頁碼暫存器就沒有「第 2 頁」可以 切換，若靜默只傾印 1 頁卻回報成功，你會誤以為真的拿到了 count 頁。
• 設定過頁碼暫存器、遮罩收窄過（例如只用低 2 個位元、遮罩 0x03）：頁數 由遮罩推算——0x03 代表 2 個位元、共 4 頁，省略 count 就依序切 4 頁各傾印 一次；顯式給 count 則蓋過推算值，但不能超過遮罩允許的頁數上限。
• 設定過頁碼暫存器、但遮罩是 0xFF（Bank 切換頁教學示範用的那個全遮罩， 代表「整個位元組都是頁碼，沒有收窄範圍」）：單看遮罩無法推算共有幾頁， 這時要顯式給 count（例如 dump_all(0, 256)，或依你實際的硬體規格給 一個更小的數字）——省略 count 仍然直接出錯，訊息會提醒你可以設窄遮罩， 或改用 count 引數。
• count 不是整數、小於 1 或大於 256，一律出錯。
• 頁數確定後（不論是「沒有 Bank」的 1 頁，還是依遮罩推算出的頁數），它會 逐頁切換、各讀 256 個位元組，每切一頁在 Log 裡記一行進度；全部完成後把 整份內容寫成一個檔案，檔名格式是 logs/dump_<時間戳記>_addr<位址>_ allbanks.txt（同樣在目前資料夾底下的 logs/），並在 Log 裡記最後一行 「完成，共寫入幾頁」的摘要。
• 呼叫成功時，回傳值就是這次寫出的相對路徑（例如 logs/dump_20260928_223611_addr58_allbanks.txt，不是絕對路徑）。
• 如果中途某一頁讀取失敗，已經完成的頁面內容仍然會被寫進檔案裡（不會整份丟掉）， 但這次呼叫本身會回報錯誤，錯誤訊息裡會附上檔案路徑，方便你自己去看已經寫下的 部分。

接下來

下一頁介紹 poll.on／poll.off 與 watch.*：怎麼跟背景輪詢、監看清單互動。