
                             JOYTERM v 1.1
                   A simple terminal emulator
             for the GP2X -- a Linux based gaming machine


Implemented by Martin Richards (c) July 2006
(heavily based on 'sterm' written by Chih-Chung Chang.)

09/Jan/2012
Updated to use on four joystick positions (not 8).


It works but is still being modified. Any feed back would be welcomed.
(mr10@cl.cam.ac.uk)

The only file needed is joyterm.gpu.  Put it on the SD card. I chose
to put it in a newly created Bin directory and either run it using the
Utility menu or by running a shell script using the Game menu. See the
scripts bcpl.gpe and cintpos.gpe in this package.

Joyterm allows the user to send 8-bit ASCII characters to a bash shell
using the joystick and/or buttons and to display the output from the
shell. With practice input can be quite quick. I currently find the
shoulder buttons more reliable than the joystick, although with practice
the joy stick might be faster.

The bottom line of the display shows the character being constructed
in binary, eg

ASCII Code   The character in the current minipage   Session

0 11 10***  `abc defg hijk lmno pqrs tuvw xyz{ |}~   A
| -- -----                      ---------            -
|  |   |                        Highlighted          The bash session
|  |   |
|  |   The L-R sequence representing the least significant 5 bits of
|  |   the character, asterisks (*) denote currently unspecified bits.
|  |   The bits are supplied by either using the left and right shoulder
|  |   buttons or the joystick. When all five bits are given, the
|  |   character is transmitted to the current bash shell. The bottom
|  |   line highlights the subset of character still possible.
|  |
|  The number of the mini-page of 32 characters currently selected.
|  This number can be changed by pressing the A button.
|
The senior bit. This is normally 0 but can be set to 1 by pressing the
VOL+ button with Select held down. Every time a character is
transmitted to a bash shell this bit is reset to 0.

The controls are as follows:

A:      Increment the bash session number modulo 4 -- Sessions are not
        yet implemented.
B:      If the L-R sequence is empty this transmits a backspace to the
        current bash shell, otherwise undo the last pressing of L or R.
X:      Send a Space character to the current bask shell.
Y:      Send a Tab character to the current bask shell.
L:      Append a 0 to the L-R sequence
R:      Append a 1 to the L-R sequence. When the L-R sequence reaches
        length 5, the character specified by the most significant bit,
        the minipage number and the L-R sequence is transmitted to the
        bash shell, and the L-R sequence reset to empty.
VOL+:   If SELECT held down set the most significant bit of the next
        character to 1, otherwise increment the mini-page number modulo 4.
VOL-:   If SELECT held down set the most significant bit of the next
        character to 0, otherwise deccrement the mini-page number modulo 4.
SELECT: While pressed the joystick will enter bits in the L-R sequence
        as described below.
CLICK:  Enter key
START:  Quit -- This is dangerous and will probably be changed.

Joystick input.

If SELECT is not held down, the joystick positions UP, RIGHT, DOWN and
LEFT send send the correponding cursor key input to bash.

If SELECT is held down between 1 and 3 of the unspecified bits in
the ASCII code are specified, as follows.

If all 5 bits are unspecified
  LEFT   is eqivalent to LLL
  UP     is eqivalent to LLR
  DOWN   is eqivalent to LRL
  RIGHT  is eqivalent to LRR

If between 1 and 3 bits are unspecified
  LEFT   is eqivalent to LL
  UP     is eqivalent to LR
  DOWN   is eqivalent to RL
  RIGHT  is eqivalent to RR

If 4 bits are unspecified
  LEFT   is eqivalent to L
  UP     is eqivalent to L
  DOWN   is eqivalent to R
  RIGHT  is eqivalent to R

So codes 00000 to 01111 can be given by 2 joystick movements and
   codes 10000 to 11111 can be given by R followed by 2 joystick movements.

Possibly future extensions.

(1) Allow switching between different shell sessions.

(2) Allow scrolling over taller and wider virtual screens.




APPENDIX --  Joystick input for Joyterm with SELECT held down

  ^ = Joystick UP
  > = Joystick RIGHT
  v = Joystick DOWN
  < = Joystick LEFT
  R = Right shoulder button

       Sequence       page 00   page 01  page 10  page 11

0 00 00   <<     =>     ^@       space      @        `   
0 00 01   <^     =>     ^A         !        A        a
0 00 10   <v     =>     ^B         "        B        b
0 00 11   <>     =>     ^C         #        C        c
0 01 00   ^<     =>     ^D         $        D        d
0 01 01   ^^     =>     ^E         %        E        e
0 01 10   ^v     =>     ^F         &        F        f
0 01 11   ^>     =>     ^G         '        G        g
0 10 00   v<     =>     ^H         (        H        h
0 10 01   v^     =>     tab        )        I        i
0 10 10   vv     =>     lf         *        J        j
0 10 11   v>     =>     ^K         +        K        k
0 11 00   ><     =>     ff         ,        L        l
0 11 01   >^     =>     cr         -        M        m
0 11 10   >v     =>     ^N         .        N        n
0 11 11   >>     =>     ^O         /        O        o
1 00 00  R<<     =>     ^P         0        P        p
1 00 01  R<^     =>     ^Q         1        Q        q
1 00 10  R<v     =>     ^R         2        R        r
1 00 11  R<>     =>     ^S         3        S        s
1 01 00  R^<     =>     ^T         4        T        t
1 01 01  R^^     =>     ^U         5        U        u
1 01 10  R^v     =>     ^V         6        V        v
1 01 11  R^>     =>     ^W         7        W        w
1 10 00  Rv<     =>     ^X         8        X        x
1 10 01  Rv^     =>     ^Y         9        Y        y
1 10 10  Rvv     =>     ^Z         :        Z        z
1 10 11  Rv>     =>     esc        ;        [        {
1 11 00  R><     =>                <        \        |
1 11 01  R>^     =>                =        ]        }
1 11 10  R>v     =>                >        ^        ~
1 11 11  R>>     =>                ?        _       del 


Martin Richards
mr10@cl.cam.ac.uk
www.cl.cam.ac.uk/users/mr
Revised 2 Feb 2012

