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 Eclipse for compiling the sources. You will
need to install the Android SDK and NDK. You should also install the
accompanying ADT plugin for Eclipse (be sure to check "NDK" when
installing the ADT for Android in Eclipse).

Next clone the TRS-80 Emulator sources via git:

git clone git clone git://git.code.sf.net/p/trs80/code trs80

The TRS-80 emulator depends on Android's Support Library.
In order to make the project independent of user-specific directory layouts,
the v7 version of the Support Library needs to be copied to the parent
directory where the emulator sources were cloned:

cp -r <android-sdk-root>/extras/android/support/v7/appcompat/*
      <parent-dir-of-git-repo>/android-support-v7-appcompat/

Note that the Support Library is designed as an Android Library project and
cannot be bundled with the emulator. It needs to be imported as a separate
Eclipse project into your workspace.

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. It is recommended
to use a real device for testing and debugging.

Quick Overview

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.

External Resources

The following resources have been used for this project:

• sdltrs
• xtrs
• Retro Fonts
• Font Squirrel
• Icons 1
• Icons 2
• ACRA
• ACRA Mailer