TRS-80 Emulator for Android
This is the first version of a TRS-80 Emulator for Android. It is based on sdltrs that is itself derived from the popular xtrs emulator originally written for X-Windows. This port adds a layer for Android.
Compiling from Source
It is recommended to use Android Studio for compiling the sources. You will need to install the Android SDK and NDK.
Next clone the TRS-80 Emulator sources via git:
git clone email@example.com:apuder/TRS-80.git
Next import the project into Android Studio via File -> Import Project... At this point you should be able to compile the sources. Note that running the TRS-80 emulator inside the Android emulator is very slow and Chromecast is also not supported by the Android emulator. It is recommended to use a real device for testing and debugging.
Compiling with Gradle
- Download and unpack the Android SDK and Android NDK.
- Run the Android SDK Manager and make sure you have the following installed:
- Android SDK Tools
- Android SDK Platform-tools
- Android SDK Built-tools (latest version, write down the revision number)
- The latest SDK Platform
- Under 'Extras':
- Android Support Repository
- Android Support Library
- Google Play services
- Google Repository
- For Windows users: Google USB driver, if you have a Nexus phone.
- Create a 'local.properties' file to define your SDK and NDK locations, e.g.:
- Change the 'buildToolsVersion' in build.gradle to match your latest version.
You will find this inside your SDK's
build-toolsdirectory or check the SDK manager entry.
- Then install:
adb install -d -r app/build/outputs/apk/app-debug.apk
The original C sources of sdltrs reside in the 'jni' folder. The Android layer uses JNI (Java Native Interface) to access the C sources from Java. Whenever I made a change to the original sdltrs sources, I used #ifdef ANDROID to annotate my changes. This should make it easy to see what was changed.
Some of the key files:
- MainActivity.java: main entry point of the Android app.
- EmulatorActivity.java: this is the Android activity that runs the emulator.
- XTRS: this class is the gateway to the C sources of xtrs/sdltrs. All down-calls and up-calls to the C code will go through this class. The native methods declared in XTRS are implemented in jni/native.c. Folder jni/SDL contains a SDL emulation to facilitate integration of the sdltrs sources.
- Hardware: defines the hardware characteristics of the TRS machine (e.g., TRS Model, disks to be mounted, etc). An instance of class Hardware is passed to XTRS.init() to initialize the native layer.
- keyboard_original.xml: Android XML layout that defines the original Model 3 keyboard layout.
- Key.java: the accompanying Android custom widget that implements the behavior of one key of the keyboard.
Details of the keyboard
The emulator features different keyboard layouts (original, compact, etc). The XML layout resources can be found in res/layout/keyboard_*.xml. Class Key implements the behavior of one key of the keyboard. Class Key is a custom Android widget that is referenced from the aforementioned XML layout files. Whenever the user 'clicks' on a key, class Key uses the KeyboardManager to add a key event which will eventually be delivered to xtrs via SDL_PollEvent. File res/values/attrs.xml defines an enum for all the keys available on a TRS machine. The TK_* constants in class Key mirror the definitions in attrs.xml. When a user presses a key, the TK_* ID needs to be mapped to a SDL_KeyboardEvent. Specifically, the SDL virtual key code and the unicode character are needed to populate SDL_KeyboardEvent. This mapping is achieved with file res/xml/keymap_us.xml. Once the virtual key code and unicode character are determined, KeyboardManager uses XTRS.addKeyEvent() to fill a key buffer in the native layer.
The following resources have been used for this project: