Py2eZ80

Ahead-of-Time Python Transpiler and Native SDK for the TI-84 Plus CE

Compile standard Python scripts directly into bare-metal binary .8xp executables.

Overview | Why Py2eZ80 | Prerequisites and Setup | Features | Language Support | Quickstart | Architecture | License

---

Overview

Py2eZ80 is an Ahead-of-Time (AOT) transpiler built in D. It takes standard Python code and translates it directly into optimized C99 targeting the Zilog eZ80 processor inside the TI-84 Plus CE.

Instead of running a heavy interpreter like MicroPython on the calculator, Py2eZ80 compiles your code down to native machine code on your PC before sending it over. You get the readable syntax and convenience of Python with the raw speed, small memory footprint, and instant startup times of native C programs.

+-----------------+       +-----------------+       +-----------------+       +-----------------+
|  Python Source  |  -->  |     Py2eZ80     |  -->  |    eZ80 C Code  |  -->  | CEdev Toolchain |  --> .8xp Native Binary
|   (script.py)   |       | (Lex/Parse/Gen) |       |    (main.c)     |       | (CEdev Folder)  |      (Runs directly)
+-----------------+       +-----------------+       +-----------------+       +-----------------+

---

Why Py2eZ80?

Writing C or C++ for the TI-84 Plus CE gives you peak performance, but it can be tedious for quick scripts or logic-heavy apps. Py2eZ80 bridges the gap: write high-level Python on your PC, then build and run a lightweight .8xp file on hardware.

Feature	Built-in TI Python	Py2eZ80 Transpiler
Execution Method	Crummy On-Device interpereter	bare-metal assembly
Startup Speed	Takes a second	Instant
Performance	Interpreted (slower execution)	Full native hardware speed
Dependencies	Requires TI Python OS app and python chip	Standalone .8xp
RAM Usage	High usage, low given amount (because of the coprocessor for python)	Native processing, much faster
Hardware Access	Supposedly None	C libraries able to directly touch the chip

---

Prerequisites and Setup

Py2eZ80 compiles Python source files down to C and uses the CEdev toolchain behind the scenes to generate .8xp files.

You do not need to compile the transpiler yourself. For standard use, compiling from source is overkill—just grab the pre-built py2ez80.exe directly from the Releases page. You only need to build it yourself if you plan on modifying the D compiler codebase.

1. Requirements

• Py2eZ80 Executable: Download py2ez80.exe from Releases (or install DMD if you specifically want to compile from source).
• CEdev SDK: Download the CEdev toolchain release.

2. Setting Up the CEdev Folder

Py2eZ80 expects the CEdev toolchain to exist in a folder named CEdev inside the main py2ez80 directory.

1. Download the latest release archive of CEdev.
2. Extract the archive contents directly into your project root as a subfolder named CEdev.
3. Make sure your folder looks like this:

py2ez80/
├── CEdev/
│   ├── cedev.bat
│   ├── build_project/
│   └── ... (CEdev toolchain files)
├── py2ez80.exe
└── README.md

If CEdev\cedev.bat is present in that directory, Py2eZ80 can automatically handle background builds and output binary files without extra configuration.

---

What Py2eZ80 Provides

Py2eZ80 handles the entire build process under the hood:

• Zero-Interpreter Output: Outputs pure C99 code to be further compiled with CEdev.
• Automated Pipeline: Parses Python, creates necessary Makefiles, triggers CEdev, and copies the final .8xp program all at once.
• Name Truncation: Shrinks names down to the max name length (8 characters) on the CE (for example, space_invaders.py converts to SPACE_IN.8xp).
• Data Type Mapping: Automatically infers primitive types (int, float, bool, str), arrays, and dynamic data structures.
• OOP Structure Lowering: Translates Python classes into native C struct representations.
• Exception Engine: Lowers Python try, except, finally, and raise blocks into standard C setjmp and longjmp execution commands.
• Standard Library Lowering: Converts module calls like import math and import random to standard C system headers like <math.h> and <stdlib.h>.

---

Language Support

Syntax & Control Flow

• Global and local variable declarations & reassignments
• Compound arithmetic operations (+=, -=, *=, /=)
• Conditionals (if, elif, else)
• Loops (while loops and for loops using range())
• Loop control statements (break, continue, pass)
• Custom functions, parameter passing, and recursion

Data Structures & Types

• Primitives: int, float, bool, str
• Lists: Lowered array structures supporting operations like .append()
• Tuples: Fixed-length immutable arrays
• Dictionaries & Sets: Struct-backed pointer abstractions
• Classes: Class definitions lowered to standard C structures

Built-ins & Standard Library

• print(): Prints text to the screen
• input(): Allows for input
• len(): Check array length
• import math: Allows for math functions
• import random: Allows for random functions
• Exception handling (try, except, finally, raise)

---

Quickstart

1. Get py2ez80.exe

Download py2ez80.exe from the Releases tab.

If you prefer to compile from source instead, clone the repo and build with static linking (-m32):

git clone https://github.com/Voblit/py2ez80.git
cd py2ez80

dmd -m32 src/main.d src/lexer.d src/parser.d src/ast.d src/codegen.d -of=py2ez80.exe
Get-ChildItem *.obj -ErrorAction SilentlyContinue | Remove-Item -Force

(Note: if there is no .exe extension after building, just add the file extension.)

2. Add the CEdev Toolchain

Before transpiling your code, make sure the CEdev SDK is placed in the root directory alongside py2ez80.exe:

1. Download the latest CEdev SDK release.
2. Extract the downloaded archive directly into your py2ez80 folder so that py2ez80.exe and the CEdev folder sit in the exact same directory:

py2ez80/
├── CEdev/
│   ├── cedev.bat
│   └── ...
├── py2ez80.exe
└── ...

3. Write a Python Script

Create a script named demo.py:

import math
import random

class Particle:
    pass

def calculate_distance(x, y):
    return math.sqrt(x * x + y * y)

print("--- Py2eZ80 Engine ---")

random.seed(42)

scores = [100, 250, 500]
player_name = "Hero"
energy = 100.0

crit_chance = random.random()
bonus_damage = random.randint(15, 50)
print("Random Crit Chance:")
print(crit_chance)
print("Random Bonus Damage:")
print(bonus_damage)

for i in range(0, 3):
    energy -= 10.5
    scores.append(i * 50 + random.randint(1, 10))

dist = calculate_distance(30, 40)
print("Calculated Distance:")
print(dist)

try:
    if energy < 0:
        raise 1
    print("Energy Normal!")
except:
    print("Energy Depleted!")
finally:
    print("Execution complete.")

4. Transpile and Build

Py2eZ80 offers a few flexible ways to run and compile your Python files:

Standard Execution

Simply pass your Python file directly to the executable:

.\py2ez80.exe demo.py

Interactive Wizard Mode

If you run py2ez80.exe without arguments (e.g. by double-clicking it) or pass --wizard, an interactive setup wizard will launch:

.\py2ez80.exe --wizard

Transpile to C Only (--only-c)

To bypass the CEdev toolchain and inspect the generated .c code directly:

.\py2ez80.exe --only-c demo.py

Multi-file Processing (--multi)

To compile multiple Python scripts sequentially:

.\py2ez80.exe --multi script1.py script2.py

5. Build Output

Py2eZ80 runs the compilation pipeline and outputs status updates directly to your terminal:

2 warnings generated.
[lto opt] obj\lto.bc
[convimg] description
[linking] bin\DEMO.bin
[success] bin\DEMO.8xp, 7810 bytes.


================================================================================
                    MAKE COMPLETED, CHECK FOR ANY ERRORS ABOVE
================================================================================


Press any key to continue . . .
[3/4] Copying DEMO.8xp to root project directory...
[4/4] Success! Final calculator output: C:\path\to\py2ez80\DEMO.8xp

Transfer the resulting DEMO.8xp file to your TI-84 Plus CE using TI Connect CE or TIlp, press PRGM, and launch your application.

---

Architecture

The compiler codebase is structured into clean, modular D source files:

src/
├── main.d         # CLI interface, process management, and interactive wizard
├── lexer.d        # Lexical analyzer for tokenizing Python source code
├── parser.d       # Recursive-descent parser producing Abstract Syntax Trees
├── ast.d          # Strongly-typed AST node structure definitions
└── codegen.d      # C code generator, type analysis, and runtime preamble injector

---

License

This project is licensed under the MIT License.