Plugin 開發：這是什麼

這個教學帶你從完全沒碰過這套架構開始，準備好編譯器，一路寫出第一顆 Plugin， 再把它載進主程式看它動起來。你需要會一點 C 語言（宣告變數、寫函式、用指標就夠了）； 不需要懂 Windows DLL 的細節，用到的地方教學會一句一句講。

Plugin 是什麼、能做什麼

主程式本身只認得「一顆 I2C 裝置有一串暫存器」這個最一般的概念。Plugin 讓它認得 你的那顆 IC：

• 宣告這顆 IC 的位址與暫存器，主程式就知道怎麼跟它講話。
• 提供自訂指令：在指令列打你定義的指令名稱，Plugin 就去做事（例如「初始化這顆 IC」、「讀出溫度並換算成攝氏」）。沒有畫面的 Plugin，自訂指令就是它的全部介面。
• 畫自己的面板：用 Widget 模式宣告按鈕、數值、下拉選單， 由主程式負責排版；或用 Canvas 模式自己畫整個面板。
• 背景輪詢、監看、存設定：定時去讀某些暫存器、在值變化時通知你、把使用者的 選擇存進設定檔。

Plugin 是一顆 DLL（.dll）。把它放進主程式旁邊的 plugins\ 資料夾，程式啟動時 會掃描並載入。不需要重新編譯主程式，也拿不到主程式的原始碼——你只需要 PDK。

生態：四個東西

1. 主程式

nexus_tui.exe（終端機版）與 nexus_gui.exe（視窗版），兩者共用同一個核心， Plugin 寫一次兩邊都能用。主程式的安裝與操作見安裝與首次使用。

2. PDK（Plugin Development Kit）

寫 Plugin 需要的全部東西，一個 zip，從下載頁取得。解壓後有：

PDK 的版本號就是主程式的版本號，sdk/ 的 API 版本要跟你的使用者手上的主程式相符。 一份 PDK 同時支援 32 位元與 64 位元。

3. Plugin Manager 與線上目錄

寫好的 Plugin 可以交給營運方上線上目錄（見把 Plugin 交給使用者），使用者在主程式的 Plugin Manager 裡就能瀏覽、安裝、 更新。見 ☰ → Plugin，官方目前有哪些 Plugin 見 Plugin 清單。

4. 四顆範例，從哪一顆開始

如果你手上已經有韌體程式碼，建議先照本教學做完 hello_ic，弄懂整條路以後再回頭看 port_demo。

這個教學怎麼走

1. 架構總覽：主程式怎麼分層、Plugin 站在哪裡、三種模式、 哪些程式碼跑在哪個執行緒。

2. 準備編譯器：五種工具鏈各一頁。沒有偏好的話選第一個（llvm-mingw）。 已經裝了 Visual Studio 或 gcc，就直接看對應那一頁。

3. 架構要對：x86／x64：最容易做錯、錯誤訊息又沒說原因的一件事。

4. 第一個 Plugin hello_ic，分四步，每一步都能載進主程式看到結果：

   • 步驟 1：載入：最小的 Plugin，載入時寫一行 Log。
   • 步驟 2：自訂指令：加一個 hello 指令。
   • 步驟 3：讀暫存器：加一個 read 指令，真的讀一次 IC。
   • 步驟 4：Widget 面板：加一個數值與一顆按鈕。

5. 做完第一顆之後，依需要挑著讀：

   • 生命週期與執行緒、讀寫硬體的三種方式：每個 callback 在哪條執行緒、怎麼安全地碰硬體。
   • Widget 模式深入、Widget 型別詳解、nxlayout 工具與視覺化編輯器：做面板。
   • Canvas 模式、設定持久化、Batch／headless、移植既有韌體。
   • 版本號與 ABI 相容、把 Plugin 交給使用者、除錯與常見錯誤。
   • Plugin API 地圖：依用途分組的 API 總覽，每個 callback 與 HostAPI 一行，連到詳細參考。

你需要準備的

• 一台 Windows 電腦，裝好主程式，並下載好 PDK。
• 一個編譯器（下一步選）。
• 不一定要有硬體。 沒有 I2C dongle 也能跟著做完：主程式內建模擬後端 mock， 教學在需要的地方會告訴你怎麼用。有硬體的話，你會需要知道自己那顆 IC 的 I2C 位址； 不知道也沒關係，步驟 1 教你用 scan 找。

本教學裡的規則與細節只講到「夠你做出第一顆」的程度。更完整的規則在 PDK 內的 docs/ 裡，網站上也有同一份內容：開發指南 （NEXUS_TUI_PLUGIN_GUIDE.md）講怎麼做與為什麼，API 參考 （NEXUS_TUI_PLUGIN_API_REFERENCE.md）逐支列出每個函式的精確規格；想先看全貌， 從 Plugin API 地圖開始。