PropTerminal Description  Version 0.3
************************

The Propeller Terminal (PropTerminal) is a little Terminal program, that is made for
communication with a Propeller-chip. The advances over a standard Terminal program are:
- Propeller Character Set.
- Sends keys coded as in Keyboard.spin driver.
- Sends Mouse moves and clicks.
- Interpretes received characters 0..12 the same as TV_Text. 
- Can easy share the COM-Port with other applications, like Propeller Tool.
- Included Loader, to download binary and eeprom files. 

I have made special spin drivers, that makes the handling of PropTerminal compatibel to
using the PS2 keyboard and mouse and a TV with TV_Text:    

- PC_Keyboard.spin   (replaces Keyboard.spin)
- PC_Mouse.spin      (replaces Mouse.spin) 
- PC_Text.spin       (replaces TV_Text.spin)
- PC_Interface.spin  (a all in one driver, uses only 1 cog, but is not direct compatible)

The Terminal sends keystrokes and mouse-events over the serial link at pins 31/30 (normally used to
download the code). It also shows characters, received over the serial link, like a TV-Monitor
connected to the propeller and driven with TV_Text.spin (40 x 13 characters).

You can use the real devices and the emulated devices in any combination while choosing the
desired driver in the OBJ section of a spin application.

PropTerminal can also download *.binary and *.eeprom files, generated by the spin compiler, to the
connected Propeller chip.

Care was taken to share the COM-port easy and fast with the Propeller Tool at development time.
For this purpose exists a Auto-Mode that closes the COM-port if the PropTerminal is minimized to
the Windows-Taskbar, and open the port again if it reappears by clicking on it in the Taskbar.


This PropTerminal is a Beta version, and has some known disadvantages (and probably some bugs).
- fixed window-size
- flickering because the lack of a double-buffer
- no Color-palette change from Propeller application
- Background color always black

But for me it's usefull like it is, and I won't spend a lot of time to improve it.
The motivation to program this Tool cames when I was trying out the Propeller chip on a
breadboard, and had no PS2 connector. So I created a Keyboard driver with serial Interface, and
a small application on the PC. Later I improved that with Mouse and Display to the PropTerminal.
I learnd a lot about propeller spin and assembly programming with this project.

PropTerminal is made with PureBasic 4.02. It is not Open Source at the moment.
The PropTerminal.exe is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY,
without even the implied warranty of MERCHANTABILITY Or FITNESS For A PARTICULAR PURPOSE.
Use it at your own risk!

The spin drivers are free software, not copyrighted because they are based on the original
drivers of Parallax Inc.

For comments or questions go to the Parallax-Propeller-Forum. I will be there sometimes.
For german language users there is also a forum at www.propellerforum.de.vu. I like more
to write in german... ;)


May 2007,  Andy Schenk, Switzerland 



Installation
------------
The PropTerminal.exe is the only file, you need on the PC. It is the direct executable application.
Copy it where ever you want. It writes a second file, named PropTerminal.ini, if you click on
'Save settings' but it changes nothing in the registry or elsewhere.
You can add a link on the desktop by right clicking the .exe and choose 'Send to' -> 'Desktop'.

Copy the spin files in the same directory, where the keyboard.spin, the mouse.spin and the
TV_Text.spin are located.

For Deinstallation just delete the files.


Menu description
----------------

Screenshot:      Copy the Window-screen as picture to the clipboard, useful for documentations.

Copy Text:       Copy the received characters (after last home or clear) as text in the clipboard.

Save Text:       The same as Copy Text but writes the characters to a file instead of the clipboard.

Save Settings:   Saves COM-Port, Path and other settings in the file: PropTerminal.ini
                 The Settings will be reloaded when the PropTerminal launches next time.

Load Settings:   Loads a new .ini file to change colors, size etc. without the need to restart
                 PropTerminal.exe. To make different .ini files just copy and rename the
                 PropTerminal.ini and edit it with a texteditor like notepad.

Upload File:     You can choose a binary file that is loaded into the connected propeller chip.
                 So you dont need to start the Propeller Tool to use the PropTerminal.
                 Also EEPROM Files are allowed now.
                 To create a binary for the propeller, compile with F8 in the Propeller-
                 Tool, and save the code as .binary or .eeprom.
                 If you upload a text-file, it's the same as you would type in the content of
                 this file per keyboard. After every line (character 13) it waits 100ms. So
                 this is no code upload, it's a textfile upload to a spin-application that
                 expect to receive characters (for example you can upload basic code to
                 propterminal-femtobasic).

Quit:            Quits the program without confirmation.

Com Port:        Choose the COM Number of the serial link to the propeller chip.

Com Enable:      Opens or closes the COM Port. You have to enable (open) the COM before you can
                 somthing send to, or receive from the propeller.

Auto Mode:       If this Menupoint is checked, the Com Port will be closed every time, you
                 minimize the Terminal Window with the Minimize field right top of a 
                 window [_] . You get the window back when you click on its name in the Taskbar.
                 This opens the Com Port again and you can use the Terminal.
                 When the Terminal window is minimized the Propeller Tool, or another application,
                 can use the port to download code to the Propeller chip, or doing something
                 else.
                 The PC_Text.spin driver has a Delay of 2 sec in the start methode, if the spin
                 application displays a menu after start, you have 2 seconds time to change to
                 the Terminal, after the download (you can increase this STARTDELAY Time, or set
                 it to 0, if you compile a binary). 

Mouse Move Off:  Disables sending of Mouse-Move-Events. Useful if you use PropTerminal only as
                 Text-Terminal. Mouse buttons will be sent anyway, if you click in the Window.

TextCursor:      Enables or disables a Text-Cursor. Useful if you use PropTerminal as normal
                 Terminal.

VirtualKeycodes: Switch between two Modes of Key-coding. If Virtual Keycodes enabled, every key
                 on the Keyboard sends a unique code (provided by Windows), unaffected by the
                 Shift/Control/Alt Keys. In this mode on Key-Release the same code, with the
                 byte $03 before will be sent.

Reset Propeller: Toggles DTR line of the serial link to reset the propeller chip.

Clear:           Clears the Terminal screen to black and sets the cursor left top.

About:           Shows some information about the program.

Website:         Starts your default browser with my Website, dedicated to the propeller chip.


Technical Informations:
-----------------------

Serial Interface:
  the COM settings are  115200 Baud, 8 DataBits, 2 Stopbits.
  The keystrokes are sent as single bytes with codes from 8 to 255.
  codes 0..7 have special meanings:
  1 = Shift ON   , the keyboard driver reports no key
  2 = Control ON , the keyboard driver reports no key
  3 = Shift Off  , the keyboard driver reports no key
  4 = Control Off, the keyboard driver reports no key
  5 = Mouse Event, 3 data bytes follows, the keyboard driver reports no key

  Mouse events are sent on every button change or move of the mouse. Event coding:
  5, buttons, x-position, y-position
    buttons value is  0=noButton, 1=LeftButton, 2=RightButton, 3=BothButtons 
    x-position: mousex >> 1 (the LSBit is in buttons bit5): 0..320
    y-position: mousey >> 1 (the LSBit is in buttons bit4): 0..238

  The keyboard-driver ignores mouse-events, and the mouse-driver ignores Key events.
  But both has his own receiving cog, (same cog count as the original drivers).

Key Codes:
  The encoding of the Key-codes is done in the PropTerminal.exe according to the original
  Keyboard-driver codes. Only the Shift and Control state is added in the PC_keyboard.spin.
  For coding see the original Keyboard.spin (at the end of the source). Not all Keys are
  supported, especially not the Alt/Window-Keys, the F12, and the Pause-Key. F10 is
  used for the Menu in Purebasic, so I use F12 as F10. 
  The keyState methode is not supported.

  The PropTerminal has a second Mode for KeyCoding. To Enable, set the Flag VKeys in the
  ini-file to 1. Then the Virtual-Key Code defined by Windows will be sent for every Key at
  Key-pressing. At Release of a Key the same code is sent after a the Prefix $03.
  This allows you writing a spin keyboard-driver that supports all modes and keys and can
  help to write a configurable driver, if the internal key-coding of PropTerminal not works
  with all keyboard-layouts.
 
Display (Monitor):
  The Display uses a BitMap-Font with a fix size, thats why also the Window has a fixed size.
  The Bitmap contains all Parallax-Font characters of the Propeller chip.
  Received codes 0..12 have special meanings:
  0 = Cls
  1 = Home
  5 = Grafics see later (3 following bytes)
  8 = Backspace
  9 = Tabulator (8 spaces per tab)
  10= Set X Position, value 0..39 (as following byte)
  11= Set Y Position, value 0..12 (as following byte)
  12= Set Color, value 0..7 (as following byte)

  To allow also some simple Graphic-drawing, the coding-scheme of the mouse events is used:
  5, mode, x-position, y-position
    mode: 0=At (set start point), 1=Draw Point, 2=Draw Line to previous Point
          3=Draw filled Box (to prev Point), 4=Clear Area (like box) 5=Invert Area (like box)
          6=Draw Mouse-Pointer (xor), 7=Draw Circle (X - prev.X = radius)
          8=Draw rounded outlined Box (like box)
    x-position: 0..160 with a resolution of 2 pixels (gives 0..320, LSBit in mode bit5) 
    y-position: 0..120 with a resolution of 2 pixels (gives 0..240, LSBit in mode bit4)
    NEW in version 0.2: Bit4 of mode can contain LSBit of Y, and Bit5 contain LSBit of X, so
                        the resolution is now 1 pixel. X=0..320, Y=0..240. 
  This is not compatibel to TV_text.spin, or VGA_text.spin and also not to Graphics.spin.
  (if you simply send back the mouse-events to the Terminal you can draw with the mouse)

  The Monitor is not full compatibel to TV_text, but good enough to work with most spin files.
  The Background-color of a character is always black, the foreground color comes from a
  internal Palette. If you want to change the colors you can modify the .ini-file. The colors
  are there coded as RGB values: BBGGRR (in hex).
 
  Starting with version 0.2, the size of the PropTerminal window can be defined in the .ini file.
  You can define the size in Characters, standard is 40 x 13 characters, but for VGA compatibelity
  32 x 15 is better.

Commandline Parameter:
  PropTerminal.exe [filename] [-option] [ComNr]

  just a filename as first parameter defines a settings-file that is loaded at startup instead
  of "PropTerminal.ini"

  You can use PropTerminal also as a Download-Tool for other Programs. For that, use option:
  -L ComNr   (and a .binary or .eeprom file as first parameter).
  the program loads the binary file into the propeller and terminates.

Downloader Functionality: (new in version 0.3)
- You can define a .binary or .eeprom file for Autoload at start of PropTerminal in the .ini file.
- If you set ComNr=0 in the .ini file, then PropTerminal searches on all Com Ports for a
  Propeller-Chip and uses the first found Com-Port.
- The Propeller can request a new Download by sending a special character sequence to the Terminal.
  The Sequence is: 1) Home or Clear (1 or 0)
                   2) Send file name with extension (for example: "Test.binary")
                   3) Send: 5, $82, Size of Filename, mode
  Size of Filename: Number of characters sent in 2)
  mode: "b" for binary, "e" for eeprom, "t" for a text file
- The Propeller can request the actual Date and Time of the PC-watch. For requests send:
    5, $81, type, type
  type: 2=Time-string 3=Date-string
  PropTerminal sends a formated string as respond with a character 13 at the end.

  This functions allows to use the PropTerminal as an Install-,Update- or Service-Tool for hardware
  with built in propeller chip and eeprom. It's not necessary to install the PropellerTools IDE
  to (re)load the EEPROM. You only need in minimum the PropTerminal.exe, the PropTerminal.ini
  and the *.eeprom file to upload. Set ComNr=0 and AutoLd=<filename>.eeprom in the .ini.
  Because of the Request-Download feature, it is possible to run first a spin program in the RAM
  of the propeller, and then choose one of several versions of *.eeprom, according to connected
  hardware, installed version, date or somehing else. Also User interaction is possible, because
  this is the main job of PropTerminal ;)

  Note that PropTerminal shows a big logo of insonix at upload. I don't forbid to use PropTerminal
  also for commercial applications, but for serious products you can buy a customized version of
  PropTerminal with your Logo and your Website-Link in the Menu. Contact www.insonix.ch if you are
  interested.

Reset "problem":
  With the existing DTR Reset-hardware the Propeller will be reseted when the COM-Port is closed.
  When open/close the COM-Port, this affects the DTR line.
  But it's not that bad because, when I close the COM, I normally will write a new code into
  the propeller chip.
  New in version 0.3: If you use an USB-Serial Interface with FT232R-chip, you can set the Flag
                      FT232R=1 in the .ini file, and after next start of PropTerminal, no Resets
                      occure when you Open/Close the COM.
