Merge pull request #2 from 8bitmcu/zm

ZMachine Interpreter

Author: 8bitmcu

LICENSE.md

@@ -40,19 +40,29 @@ The `vi` implementation is derived from Toybox.
 * **License:** **0BSD** (Zero-Clause BSD).
 * **Summary:** Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
 
-### 3. st7789_mpy
+### 3. frotz (Zmachine interpreter)
+The Z-Machine interpreter is based on Frotz.
+* **Copyright:** 1995-1997 Stefan Jokisch, 1998-present David Griffith and contributors.
+* **License:** **GNU General Public License v2.0 (or later)**.
+* **Summary:** Frotz is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
+
+### 4. st7789_mpy
 * **Copyright:** Russ Hughes.
 * **License:** **MIT License**.
 
-### 4. Terminus Font
+### 5. Terminus Font
 * **Copyright:** (c) 2020 Dimitar Zhekov. 
 * **License:** **SIL Open Font License 1.1**.
 
-### 5. MicroPython
+### 6. MicroPython
 * **Copyright:** (c) Damien P. George.
 * **License:** **MIT License**.
 
 ---
 
 ### Implementation Note for the T-Deck
 While the original `vi` code follows the 0BSD license and the `st` engine follows the MIT/X Consortium license, the specific architectural modifications in this repository—including the **MicroPython VFS Bridge**, **NLR Exception Guarding**, **Zero-allocation Status Bar**, and **GC-safe Memory Management**—are contributed under the project's primary MIT license.
+
+---
+
+While the original source code for mpy_vt is provided under the MIT license, compiling it with the optional frotz module creates a combined work that falls under the GNU General Public License v2.0 (GPL-2.0) upon distribution.

README.md

@@ -17,7 +17,7 @@ As a showcase of the engine's capabilities, this project includes a fully functi
 
 ## ⚡ Quick Install (Pre-compiled Binaries)
 
-Don't want to set up a build environment? You can download and flash the latest pre-compiled firmware directly to your T-Deck.
+You can download and flash the latest pre-compiled firmware directly to your T-Deck.
 
 ### Option A: Flash from command line
 
@@ -61,6 +61,7 @@ You can execute the following commands directly in the MicroPython REPL:
 | `clear` | Clears the screen |
 | `telehack` | Connects telnet to telehack.com |
 | `retrocampus` | Connects telnet to bbs.retrocampus.com |
+| `zork` | Launches Zork through the ZMachine interpreter. Note: `zork1.dat` must be present on your SD card root directory |
 
 ## 🚀 VT Features
 
@@ -92,6 +93,7 @@ This project is composed of six specialized modules that works in tandem:
 | `tdeck_trk` | Motion Engine | Interrupts | Low-level driver for the T-Deck trackball. Uses GPIO interrupts to track relative motion (deltas) and supports edge-detection for short/long click durations. |
 | `tdeck_kvm` | Stream Glue | Read/Write | A composite Keyboard-Video-Mouse (trackball) object. It binds vt (Output) and tdeck_kbd (Input) into a single stream object compatible with os.dupterm. |
 | `vi` | Text Editor | Read/Write | A C-integrated port of the classic `vi` editor. |
+| `zm` | ZMachine Interpreter | Read/Write | A port of the `frotz` Zmachine interpreter. |
 
 
 ## 📟 T-Deck Hardware Integration
@@ -302,14 +304,22 @@ make repl PORT=/dev/ttyUSB0
 | **`inject()`** | `data` | **Macro Injection.** Accepts a string or bytes and places them into the high-priority ring buffer to be read by the REPL or active application. |
 | **`ioctl()`** | `cmd, arg` | Aggregates status from both objects (e.g., checks if KBD has data or if VT is ready). |
 
-### **5. `vi.Vi` (Text Editor)**
+### **5. `zm.ZMachine` (ZMachine Interpreter)**
+*Port of the `frotz` interpreter.*
+
+| Method | Parameters | Description |
+| :--- | :--- | :--- |
+| **`ZMachine()`** | `filename, stream, cols, rows` | **Constructor.** Creates a ZMachine instance with a given filename, using `stream` for input/outputs. |
+| **`run()`** | None | Launches the Zmachine interpreter. |
+
+### **6. `vi.Vi` (Text Editor)**
 *Port of the classic `vi` text-editor.*
 
 | Method | Parameters | Description |
 | :--- | :--- | :--- |
 | **`Vi()`** | `filename, stream, cols, rows` | **Constructor.** Launches the vi editor, opening a given filename, using `stream` for input/outputs. |
 
-### **6. `st7789` (Modified Display Driver)**
+### **7. `st7789` (Modified Display Driver)**
 *Standard display driver with specific C-layer extensions for terminal performance.*
 
 | Feature | Type | Description |
@@ -318,12 +328,13 @@ make repl PORT=/dev/ttyUSB0
 
 ## ⚖️ License & Attribution
 
-This project is licensed under the **MIT License**.
+This project's source code is licensed under the **MIT License**. However, if you compile the firmware with the optional `frotz` module enabled, the resulting compiled binary is distributed under the **GPLv2 License**.
 
 ### Third-Party Components:
 * **st License:** MIT (c) st engineers.
 * **st7789_mpy:** (c) Russ Hughes. MIT License
 * **vi** (Toybox): (c) Rob Landley, Jarno Mäkipää. 0BSD License (Zero-Clause BSD).
+* **frotz**: (c) Stefan Jokisch, David Griffith. GPLv2 License
 * **MicroPython**: (c) Damien P. George. MIT License.
 
 ### Fonts & Assets:

modules/micropython.cmake

@@ -16,3 +16,8 @@ include(${CMAKE_CURRENT_LIST_DIR}/tdeck_trk/micropython.cmake)
 # include the vi editor module
 include(${CMAKE_CURRENT_LIST_DIR}/vi/micropython.cmake)
 
+# include the zm module (Z-machine interpreter)
+include(${CMAKE_CURRENT_LIST_DIR}/zm/micropython.cmake)
+
+# include the tu (text ui) module
+include(${CMAKE_CURRENT_LIST_DIR}/tu/micropython.cmake)

modules/scripts/main.py

@@ -15,6 +15,7 @@
 import time
 import status
 
+
 # Screen dimensions in pixel
 screen_width = 320
 screen_height = 240
@@ -28,21 +29,47 @@
 rows = usable_height // rfont.HEIGHT
 
 # Must be called before initializing LCD / Keyboard
-pwr_en = machine.Pin(10, machine.Pin.OUT)
-pwr_en.value(1)
+machine.Pin(10, machine.Pin.OUT, value=1)
+time.sleep(0.1)
+
+# Pull all SPI CS pins HIGH before touching the bus (prevents bus conflicts)
+machine.Pin(12, machine.Pin.OUT, value=1)  # display CS
+machine.Pin(9, machine.Pin.OUT, value=1)   # LoRa CS
+machine.Pin(39, machine.Pin.OUT, value=1)  # SD CS
+machine.Pin(38, machine.Pin.IN, machine.Pin.PULL_UP)  # MISO pull-up
 time.sleep(0.1)
 
+# Mount SD Card (Experimental; doesn't seem to always work)
+try:
+    import sdcard
+    sd_spi = machine.SoftSPI(baudrate=400000, sck=machine.Pin(40), mosi=machine.Pin(41), miso=machine.Pin(38))
+    sd = sdcard.SDCard(sd_spi, machine.Pin(39, machine.Pin.OUT))
+
+    os.mount(os.VfsFat(sd), '/sd')
+    print("SD mounted at /sd")
+except Exception as e:
+    print("SD mount failed: ", e)
+    sd = None
+
+# Create hardware SPI; this configures the GPIO matrix for pins 40/41.
+# SoftSPI is no longer used after this point.
+spi = machine.SPI(1, baudrate=40000000, sck=machine.Pin(40), mosi=machine.Pin(41), miso=machine.Pin(38))
+
+# The card is already initialized. Only the transport changes.
+# Gives the already-mounted SD card faster hardware SPI for data transfers.
+if sd is not None:
+    sd.spi = spi
+
 # Initialze LCD
-spi = machine.SPI(1, baudrate=40000000, sck=machine.Pin(40), mosi=machine.Pin(41))
 tft = st7789.ST7789(spi,
-    screen_height,
-    screen_width,
-    reset=machine.Pin(1, machine.Pin.OUT),
-    dc=machine.Pin(11, machine.Pin.OUT),
-    cs=machine.Pin(12, machine.Pin.OUT),
-    backlight=machine.Pin(42, machine.Pin.OUT),
-    rotation=1,
-    buffer_size=screen_width*rfont.HEIGHT*2)
+                    screen_height,
+                    screen_width,
+                    reset=machine.Pin(1, machine.Pin.OUT),
+                    dc=machine.Pin(11, machine.Pin.OUT),
+                    cs=machine.Pin(12, machine.Pin.OUT),
+                    backlight=machine.Pin(42, machine.Pin.OUT),
+                    rotation=1,
+                    buffer_size=screen_width*rfont.HEIGHT*2)
 tft.init()
 
 # Initialize ST engine
@@ -61,7 +88,7 @@
 # Redirect to REPL
 os.dupterm(kvm)
 
-# status bar component
+# Status bar component
 sts = status.StatusBar(term, width=cols)
 sts.refresh()
 
@@ -209,7 +236,10 @@ def telnet_retrocampus():
 retrocampus = Command(telnet_retrocampus)
 
 
+def zm_zork():
+    import zm
+    m = zm.ZMachine("/sd/zork1.dat", kvm, cols, rows)
+    m.run()
 
+zork = Command(zm_zork)
 
-# type wlan to connect to wifi
-# type telehack for telnet telehack