MKDeck v2.0 — by Gebo Lab
============================================================
中文說明在前，English version below.


############################################################
#  繁體中文
############################################################

MKDeck 是一個給 Autodesk Fusion 用的桌上視角控制器：
推搖桿就能轉動 Fusion 的視角，小螢幕上會即時顯示目前的視角方塊。
加上四顆按鍵（選配）之後，還能平移畫面、取消指令、復原和重做。

只做「螢幕 + 搖桿」就能使用；四顆按鍵可以之後再加，韌體和外掛都是同一份。


這個包裡有什麼
--------------
MKDeck\                        Fusion 外掛（Windows）
firmware\MKDeck\MKDeck.ino     ESP32-S3 韌體原始碼（自己編譯、燒錄）
firmware\MKDeck\icons.h        按鍵圖示（跟 MKDeck.ino 放在同一個資料夾，不用另外開啟）
firmware\MKDeck\hershey_simplex.h   開機動畫用的線條字型（同上）
LICENSE.txt                    使用條款（完整版）
README.txt                     本說明

※ 請先把整個 zip「全部解壓縮」到一般資料夾，再開啟裡面的檔案。
  不要在壓縮檔視窗裡直接點開 .ino 或外掛，Arduino IDE 和 Fusion 都會讀不到。


零件清單
--------
必要：
- ESP32-S3 開發板（DevKitC-1 類型，有兩個 USB 孔：原生 USB 和 UART）
- ST7789 SPI 彩色螢幕，解析度 240×320（建議買 IPS 面板，斜著看才不會變色）
- 雙軸類比搖桿模組，要有按壓開關（例如 KY-023 這類 PS2 搖桿模組）
- 杜邦線或麵包板
- USB 資料線（要能傳資料，不是只能充電的線）

選配：
- 機械軸或一般按鍵開關 4 顆（排成 2×2）

電腦端：
- Windows 電腦，已安裝 Autodesk Fusion
- Arduino IDE 2（燒錄韌體用）：https://www.arduino.cc/en/software


第一步：接線
------------
搖桿：
  VRx -> GPIO 1
  VRy -> GPIO 2
  SW  -> GPIO 21
  +   -> 3.3V（模組上可能印 +5V，一樣接 3.3V，不要接 5V）
  GND -> GND

螢幕（ST7789，SPI）：
  SCL  -> GPIO 4     （模組上也可能印 SCLK、SCK、CLK）
  SDA  -> GPIO 5     （也可能印 MOSI、DIN；這是 SPI 的資料線，不是 I2C）
  RST  -> GPIO 6     （可能印 RES、RESET）
  DC   -> GPIO 7
  CS   -> GPIO 8
  BL   -> GPIO 9     （可能印 BLK、LED）
  VCC  -> 3.3V
  GND  -> GND

四顆按鍵（選配，2×2，從正面看）：

                左行        右行
               GPIO 16     GPIO 15
                 |           |
  上排 GPIO 12 --[Esc]-------[平移]
                 |           |
  下排 GPIO 11 --[復原]------[重做]

  每顆按鍵有兩隻腳：一隻接它那一「排」的線，另一隻接它那一「行」的線。
  所以總共只有 4 條線接到開發板（GPIO 11、12、15、16），不用接電源也不用接 GND。
  排的線和行的線交叉的地方不能互相碰到。
  按鍵不需要二極體就能正常使用。

如果你的腳位不一樣，打開 MKDeck.ino 修改對應的數字即可。


第二步：燒錄韌體
----------------
1. 安裝 Arduino IDE 2。
2. 在「檔案 → 偏好設定」的「額外的開發板管理員網址」加入：
   https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   然後在「工具 → 開發板 → 開發板管理員」搜尋 esp32 並安裝（Espressif Systems 出的那個）。
3. 在「工具 → 管理程式庫」搜尋並安裝 LovyanGFX。
4. 用 Arduino IDE 開啟（已解壓縮的）firmware\MKDeck\MKDeck.ino。
5. 在「工具」選單設定：
     開發板：ESP32S3 Dev Module
     USB CDC On Boot：Enabled   ← 一定要開，不然電腦認不到裝置
     USB Mode：Hardware CDC and JTAG
6. 用 USB 線接電腦，「工具 → 序列埠」選對應的 COM 埠。
7. 按上傳（→ 圖示）。
8. 上傳完成後，如果有開「序列埠監控窗」，請把它關掉（它會佔住 USB，Fusion 就連不上）。

※ 每次開機時請不要碰搖桿，韌體會把開機當下的位置當成中心點。


第三步：安裝 Fusion 外掛
------------------------
1. 把整個 MKDeck 資料夾複製到 Fusion 的外掛資料夾：
     %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\
   （在檔案總管的網址列貼上這個路徑按 Enter 就能打開。）
   複製完應該是：...\API\AddIns\MKDeck\MKDeck.py
2. 打開 Fusion，上方「實用程序（UTILITIES）」分頁 → 「附加模組（ADD-INS）」→
   「腳本和附加模組（Scripts and Add-Ins）」。
3. 在「我的附加模組（My Add-Ins）」清單裡找到 MKDeck，按「執行（Run）」。
   想要每次開 Fusion 都自動載入，勾選「在啟動時執行（Run on Startup）」。

   如果找不到上面那個 AddIns 資料夾：也可以在清單上方按綠色「+」，直接選 MKDeck 資料夾。
   但 Fusion 只會記住路徑、不會複製檔案，所以請先把 MKDeck 放在一個固定、不會刪掉的地方
   （不要放在「下載」資料夾裡）。

4. 「文本命令（Text Commands）」視窗應該會顯示：
     [MKDeck] vX.X 已啟動：ESP32 自動尋找中
   接上 ESP32 之後幾秒內會顯示：
     [MKDeck] 已連上 MKDeck 裝置（COMxx）
   同時小螢幕右上角的圓點會從紅色變綠色，代表連線成功。


開始使用
--------
把 ESP32 的原生 USB 孔（板子有兩個 USB 孔時，是標示 USB 的那個）接到電腦。

開機動畫：
  每次接上電源會先看到一個旋轉的方塊。推搖桿，方塊會縮小，縮到一定程度就會爆開，
  接著出現星空和 Gebo Lab 字樣。這時再推一下搖桿、按搖桿或按任何一顆鍵，就進入正常畫面。
  想直接跳過：在方塊還在轉的時候，按一下搖桿或任何一顆鍵。

搖桿：
  左／右：順時針／逆時針轉 90 度
  上／下：平滑轉到頂視／底視
  按下：拉正到最近的面

有兩種轉動手感，搖桿按鈕快速按兩下切換（畫面上會短暫顯示 Precise 或 Smooth）：
  精準模式 Precise（開機預設）：推一下轉 90 度，跟 ViewCube 對齊面的手感一樣。
  連續模式 Smooth：推著搖桿不放，視角連續轉動，像用手指撥動一顆方塊，推越多轉越快，放開就停。
                  連續轉動後模型可能會歪一邊，按一下搖桿就會拉正。
連點兩下切換模式時，還是會照常拉正一次。

四顆按鍵（有接才有）：
  Esc（左上）：取消目前進行中的指令
  平移（右上）：按住不放再推搖桿，畫面就會平移；放開後搖桿恢復成轉動視角。
               畫面上方會顯示 Pan。單獨按一下沒有作用。
  復原（左下）：等於 Ctrl+Z
  重做（右下）：等於 Ctrl+Y

  平移鍵快速按兩下：切換螢幕版面（只有方塊 ↔ 方塊加四顆鍵的圖示）
  平移鍵快速按三下：重播開機動畫


疑難排解
--------
- 小螢幕一直顯示「Not linked」（紅點）或「Waiting for Fusion」：
  1. 確認「工具 → USB CDC On Boot」是 Enabled。這是燒進韌體的設定，改了要重新上傳才會生效。
  2. 確認 Arduino IDE 的序列埠監控窗已經關閉（USB 同一時間只能給一個程式用）。
  3. 確認接的是原生 USB 孔，而不是燒錄用的 UART 孔；重插一次 USB 線。
  4. 在 Fusion 文本命令視窗檢查有沒有錯誤訊息。
- 開機後一直停在旋轉的方塊：這是開機動畫，推搖桿或按一下搖桿就會繼續。
- Arduino IDE 顯示「sketch 缺少主檔」：通常是直接從壓縮檔裡開啟 .ino，請先全部解壓縮。
- 編譯時說找不到 icons.h 或 hershey_simplex.h：這兩個檔要跟 MKDeck.ino 放在同一個資料夾，
  請不要只把 .ino 單獨搬走。
- 按鍵按了位置不對（例如按左上卻是重做）：排或行的線接反了，把 GPIO 11 和 12 的線對調，
  或把 GPIO 15 和 16 的線對調。
- 某顆鍵一直像被按住：那顆鍵的兩條線碰在一起了。
- 找不到「文本命令」視窗：實用程序分頁 → 面板最右邊「顯示文本命令」。
- 同時接兩台以上 MKDeck：目前外掛只會連線第一台找到的裝置。
- 更新外掛：在「腳本和附加模組」先停止 MKDeck，用新版整個資料夾覆蓋舊的，再執行一次。
- 從舊版（Level 1 v1.8）升級：外掛和韌體都要換成這一版，只換其中一個會缺功能。


使用條款（摘要，完整內容見 LICENSE.txt）
----------------------------------------
- 個人可以免費下載、使用，也可以為了自己使用而修改。
- 不得販售或轉售本軟體、韌體，或預先燒錄本韌體的裝置／套件。
- 可以免費轉發，但必須註明出自 Gebo Lab，並保留本條款。
- 商業用途請先聯絡 Gebo Lab 取得授權：wavestudiolab@gmail.com
- 本軟體依「現況」提供，不提供任何保證，使用風險自負。


聲明
----
MKDeck 為 Gebo Lab 的獨立作品，與 Autodesk, Inc. 無關，也未經其認可或贊助。
Autodesk 和 Fusion 是 Autodesk, Inc. 的註冊商標。


第三方元件
----------
外掛的 MKDeck\lib\serial 資料夾是 pySerial 3.5（https://github.com/pyserial/pyserial），
作者 Chris Liechti，採用 BSD-3-Clause 授權，完整授權條文見 MKDeck\lib\pyserial-LICENSE.txt。

韌體的 firmware\MKDeck\hershey_simplex.h 是 Hershey 向量字型「Roman Simplex」，
由 Dr. A. V. Hershey 於 1967 年為美國國家標準局製作並公開發行，
資料取自 https://github.com/kamalmostafa/hershey-fonts 。
這套字型可以自由使用、複製和散佈，但不得把字型本身當成商品販售，散佈時要保留出處說明
（寫在 hershey_simplex.h 的開頭）。

以上兩項不受 Gebo Lab 使用條款限制，各自依其原本的條款使用。


版本
----
外掛：MKDeck v2.0（新增平移、四顆按鍵；連續模式的左右改成以畫面為準）
韌體：MKDeck v3.0（新增四顆按鍵、兩種螢幕版面、開機動畫）
上一版：MKDeck Level 1 v1.8（只有螢幕 + 搖桿）



############################################################
#  English
############################################################

MKDeck is a desktop view controller for Autodesk Fusion:
push the joystick to rotate the Fusion view, and the small screen shows the current view cube in real time.
With four optional keys you can also pan the view, cancel a command, undo and redo.

It works with just the screen and joystick; the four keys can be added later.
The firmware and add-in are the same either way.


What's in this package
----------------------
MKDeck\                        Fusion add-in (Windows)
firmware\MKDeck\MKDeck.ino     ESP32-S3 firmware source (compile and flash it yourself)
firmware\MKDeck\icons.h        Key icons (must stay in the same folder as MKDeck.ino; no need to open it)
firmware\MKDeck\hershey_simplex.h   Stroke font used by the boot animation (same as above)
LICENSE.txt                    Terms of use (full text)
README.txt                     This file

* Extract the whole zip ("Extract All") to a normal folder first.
  Do not open the .ino or the add-in directly from inside the zip window;
  Arduino IDE and Fusion cannot read files that way.


Parts list
----------
Required:
- ESP32-S3 development board (DevKitC-1 style, with two USB ports: native USB and UART)
- ST7789 SPI color display, 240x320 (an IPS panel is recommended for better viewing angles)
- Dual-axis analog joystick module with a push switch (e.g. KY-023 / PS2-style joystick module)
- Jumper wires or a breadboard
- USB data cable (must support data, not a charge-only cable)

Optional:
- 4 mechanical switches or push buttons (arranged 2x2)

On the computer:
- Windows PC with Autodesk Fusion installed
- Arduino IDE 2 (for flashing the firmware): https://www.arduino.cc/en/software


Step 1: Wiring
--------------
Joystick:
  VRx -> GPIO 1
  VRy -> GPIO 2
  SW  -> GPIO 21
  +   -> 3.3V (the module may be labeled +5V; still connect it to 3.3V, do NOT use 5V)
  GND -> GND

Display (ST7789, SPI):
  SCL  -> GPIO 4     (may also be labeled SCLK, SCK or CLK)
  SDA  -> GPIO 5     (may also be labeled MOSI or DIN; this is the SPI data line, not I2C)
  RST  -> GPIO 6     (may be labeled RES or RESET)
  DC   -> GPIO 7
  CS   -> GPIO 8
  BL   -> GPIO 9     (may be labeled BLK or LED)
  VCC  -> 3.3V
  GND  -> GND

Four keys (optional, 2x2, seen from the front):

                    Left col    Right col
                    GPIO 16     GPIO 15
                      |           |
  Top row    GPIO 12 --[Esc]-------[Pan]
                      |           |
  Bottom row GPIO 11 --[Undo]------[Redo]

  Each key has two legs: one goes to the wire of its row, the other to the wire of its column.
  That makes only 4 wires to the board (GPIO 11, 12, 15, 16). No power or GND connection is needed.
  The row wires and column wires must not touch where they cross.
  The keys work fine without diodes.

If you use different pins, change the numbers in MKDeck.ino.


Step 2: Flash the firmware
--------------------------
1. Install Arduino IDE 2.
2. In "File > Preferences", add this to "Additional boards manager URLs":
   https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   Then open "Tools > Board > Boards Manager", search for esp32 and install it (by Espressif Systems).
3. In "Tools > Manage Libraries", search for and install LovyanGFX.
4. Open the (extracted) firmware\MKDeck\MKDeck.ino in Arduino IDE.
5. In the "Tools" menu, set:
     Board: ESP32S3 Dev Module
     USB CDC On Boot: Enabled   <- required, otherwise the PC cannot find the device
     USB Mode: Hardware CDC and JTAG
6. Connect the board with a USB cable and select its COM port in "Tools > Port".
7. Click Upload (the arrow icon).
8. After uploading, close the Serial Monitor if it is open (it holds the USB port and blocks Fusion).

* Do not touch the joystick while the board powers up; the firmware uses the position at power-up as the center.


Step 3: Install the Fusion add-in
---------------------------------
1. Copy the whole MKDeck folder into Fusion's add-ins folder:
     %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\
   (Paste this path into the File Explorer address bar and press Enter.)
   The result should be: ...\API\AddIns\MKDeck\MKDeck.py
2. Open Fusion, go to the UTILITIES tab > ADD-INS > Scripts and Add-Ins.
3. Find MKDeck under "My Add-Ins" and click Run.
   To load it automatically every time Fusion starts, check "Run on Startup".

   If you cannot find the AddIns folder above: click the green "+" in the list and pick the MKDeck folder.
   Fusion only remembers the path and does not copy the files, so keep MKDeck in a permanent
   location first (not in your Downloads folder).

4. The Text Commands window should show:
     [MKDeck] vX.X 已啟動：ESP32 自動尋找中     (add-in started, searching for the device)
   A few seconds after you plug in the ESP32:
     [MKDeck] 已連上 MKDeck 裝置（COMxx）       (connected to the device)
   The dot in the top-right corner of the small screen also turns from red to green.
   (The add-in's log messages are in Chinese.)


How to use
----------
Connect the ESP32's native USB port (on boards with two USB ports, the one labeled USB) to the PC.

Boot animation:
  Every time it powers up you first see a spinning cube. Push the joystick and the cube shrinks;
  once it is small enough it bursts, followed by a starfield and the Gebo Lab title. Push the joystick,
  press the joystick or press any key again to enter the normal screen.
  To skip it: press the joystick or any key while the cube is still spinning.

Joystick:
  Left / right: rotate 90 degrees clockwise / counterclockwise
  Up / down:    smoothly turn to the top / bottom view
  Press:        snap to the nearest face

There are two rotation modes. Double-press the joystick button quickly to switch
(the screen briefly shows "Precise" or "Smooth"):
  Precise (default at power-up): each push rotates 90 degrees, like clicking the ViewCube.
  Smooth: hold the joystick to rotate the view continuously, as if nudging a cube with your finger;
          the further you push, the faster it turns; release to stop.
          After a lot of free rotation the model may end up tilted; press the joystick to straighten it.
A double-press still snaps to the nearest face as usual.

Four keys (only if you wired them):
  Esc (top left):      cancel the command in progress
  Pan (top right):     hold it and push the joystick to pan the view; release it and the joystick
                       rotates the view again. The screen shows "Pan" while held.
                       A single press on its own does nothing.
  Undo (bottom left):  same as Ctrl+Z
  Redo (bottom right): same as Ctrl+Y

  Double-press the Pan key: switch the screen layout (cube only <-> cube plus the four key icons)
  Triple-press the Pan key: replay the boot animation


Troubleshooting
---------------
- The small screen keeps showing "Not linked" (red dot) or "Waiting for Fusion":
  1. Make sure "Tools > USB CDC On Boot" is Enabled. This setting is compiled into the firmware,
     so you must upload again after changing it.
  2. Make sure the Arduino IDE Serial Monitor is closed (only one program can use the USB port at a time).
  3. Make sure you are using the native USB port, not the UART port used for flashing. Re-plug the cable.
  4. Check the Fusion Text Commands window for error messages.
- It stays on the spinning cube after power-up: that is the boot animation. Push or press the joystick to continue.
- Arduino IDE says the sketch is missing its main file: you probably opened the .ino from inside the zip.
  Extract everything first.
- The compiler cannot find icons.h or hershey_simplex.h: both files must be in the same folder as MKDeck.ino.
  Do not move the .ino out on its own.
- A key triggers the wrong function (e.g. top left does Redo): the row or column wires are swapped.
  Swap the wires on GPIO 11 and 12, or the wires on GPIO 15 and 16.
- A key behaves as if it is always pressed: its two wires are touching.
- Cannot find the Text Commands window: UTILITIES tab > the rightmost "Show Text Commands" button.
- More than one MKDeck connected: the add-in only connects to the first device it finds.
- Updating the add-in: stop MKDeck in Scripts and Add-Ins, replace the whole folder with the new one, then Run it again.
- Upgrading from the previous release (Level 1 v1.8): replace both the add-in and the firmware.
  Updating only one of them leaves features missing.


Terms of use (summary, see LICENSE.txt for the full text)
---------------------------------------------------------
- Free to download and use for personal purposes, and to modify for your own use.
- You may not sell or resell this software, the firmware, or devices/kits pre-loaded with this firmware.
- You may share it for free, but you must credit Gebo Lab and keep these terms.
- For commercial use, contact Gebo Lab for permission first: wavestudiolab@gmail.com
- Provided "as is" without any warranty; use at your own risk.


Disclaimer
----------
MKDeck is an independent project by Gebo Lab. It is not affiliated with, endorsed by,
or sponsored by Autodesk, Inc. Autodesk and Fusion are registered trademarks of Autodesk, Inc.


Third-party components
----------------------
The MKDeck\lib\serial folder is pySerial 3.5 (https://github.com/pyserial/pyserial) by Chris Liechti,
licensed under BSD-3-Clause. See MKDeck\lib\pyserial-LICENSE.txt for the full license text.

firmware\MKDeck\hershey_simplex.h contains the Hershey vector font "Roman Simplex", created by
Dr. A. V. Hershey in 1967 for the U.S. National Bureau of Standards and publicly released.
The data comes from https://github.com/kamalmostafa/hershey-fonts .
The font may be freely used, copied and distributed, but the font itself may not be sold as a product,
and the attribution notice (at the top of hershey_simplex.h) must be kept when distributing it.

Neither of these is covered by the Gebo Lab terms above; each is used under its own terms.


Version
-------
Add-in: MKDeck v2.0 (adds panning and four keys; left/right in Smooth mode now follows the screen)
Firmware: MKDeck v3.0 (adds four keys, two screen layouts and a boot animation)
Previous release: MKDeck Level 1 v1.8 (screen + joystick only)
