1
Palm
Touch
Charles Lee
Steve Ruiz
ECE 145
UC Irvine
Winter 2001
2
Introduction
Graphical User Interface (GUI) applications have gained wide acceptance
as a means to implement software tools that were once only command
line driven. GUI’s provide a user-friendly environment for end users and
also allow an individual to use a GUI based program without having to
read through an extensive thousand-page manual. Microsoft is a prime
example of a company that has used graphical user interface
programming successfully for PC applications. 3Com has taken the idea
of GUI based applications farther and created a GUI based Personal
Digital Assistant (PDA), the Palm Pilot. The Palm Pilot integrates itself to
be used in conjunction with a PC to do various tasks, and the ability to be
able to implement an interface between these two devices so that one
could control the Palm or the PC is the driving goal behind our project.
The objective of this project was to implement a mouse using the Palm
Pilot interfacing the mouse through the infrared port on the Palm or the
serial port of the cradle. Using the Palm’s built in screen, one can use the
pen and buttons as a mouse for a PC.
Background and Related Work
PalmOS.com
Palm OS SDK Companion
http://www.palmos.com/dev/tech/docs/palmos/CompanionTOC.html
General overview of programming in Palm OS
3
App Event Loop – flow of events, first given to system, menu, application
In event loop, process events with switch relating to event type
Low level events – Pen queue – keeps points traveled by pent
Key queue – keeps track of key presses
Serial Communication
Normal serial hardware in palm
Byte ordering – opposite Intel, MSB at lowest address
New serial manager – IRComm built in
SrmOpen(‘ircm’) to use IR as comm. Port
SrmOpen(0x8000) for serial port
SrmSend to send data, SrmGetStatus to view PC serial hardware status
Palm OS SDK Reference
http://www.palmos.com/dev/tech/docs/palmos/ReferenceTOC.html
Complete SDK reference, all functions can be looked up here
PenDownEvent – event when pen is put on screen
PenMoveEvent – occasional events generated by pen movement, usually
taken care of by system
PenUpEvent – generated when pen lifted, includes info about complete
pen stroke
System Event Manager – handles events on palm
EvtGetPen – get current status of pen – location and if up or down
EvtGetEvent – main appeventloop, waits for event – if specify wait time,
will wait certain amount of time and then execute event loop with nilEvent
KeyCurrentState – Returns a UInt32 with bits set for keys that are
depressed
Palm Programming : the Developers Guide
Printing Text to screen – pg 118
Serial – outdated old serial mgr examples
New Serial manager documentation and Examples
http://www.devnation.net/present/1107.cfm
List of new functionality available in new serial manager
Advice on opening serial ports, sending data
New Serial Manager API reference
http://www.palmos.com/dev/tech/docs/palmos/NewSerialManager.html#92
4904
All info about Srm functions and constants
SrmControl() function sets serial settings (data bits, stop bits, baud, ect)
Serial Communications in Palm OS
http://home.olemiss.edu/~grkanth/
New Serial Manager specifications
4
Walk through Opening and closing ports
Mouse Protocol Specification from Open-Source Mouse Driver
http://www.vein.hu/~nagyd/
(In CuteMouse driver release package)
Reset of mouse : RTS and DTR set low, wait, set high, wait for ‘M’
character to identify mouse
MS Mouse format : 1200bps, 1 stop bit, no parity
1st byte – Button data, header, 1st 2 bits of X and Y dir
2nd and 3rd bytes – Rest of distance values
Buttons are each 1 bit, on when depressed, set to 0 when released
Only transmits when something happens – movement, button press
Infrared Data Communications
www.irda.org
Primary initiates “discovery” process, finds devices that are visible and two
do a handshaking protocol in which both learn about each others
capabilities and also find a common ground for com settings
IrLAP, Link Access Protocol used for discovery process and setting up IR
connection
Project Specification
General Specification:
•
•
•
•
•
•
•
Application to enable Palm Pilot to be used as a mouse/touchpad for a
Personal Computer
I/O will be done through either the serial port or IR port, user
selectable.
Protocol - standard serial protocol for data, encapsulated in IRComm
protocol when used with infrared port. Serial data will be transmitted in
7 data bit, 1 stop bit, 1200 bps. Data packets follow standard Microsoft
Mouse data format, with 3 bits specifying distance moved and button
status - see this page for details on the MS Mouse data packet format.
Output during normal operation is MS Mouse data packet format as
explained above. Upon detecting a RTS line reset from the PC serial
controller, the program will send out an 'M' character to identify itself as
a Microsoft Mouse.
Input will only be requests for the status of the registers in the serial
controller, monitoring the status of the RTS line to know when to
transmit identification data.
Other data the application deals with will be accessing and writing to
the preferences database for the application, which will store the
preferred method of transfer, serial or infrared.
There seem to be no constraints on the project imposed by the Palm
platform, as all requirements are within specifications for the Palm, PC,
5
and infrared hardware and associated software. The line speed needs
to be 1200 baud, with 7 data bits and 1 stop bit, all selectable in the
Palm OS.
Platform Specifications
•
•
The platforms used in the application will be the Palm OS and IBM
compatible personal computers running various flavors of Microsoft
Windows - Windows 95, 98, 2000, anything with a standard Microsoft
Mouse driver and, for infrared ability, IR port - IRComm compatible
drivers.
Palm IIIe, Palm V, Palm VII, Handspring Visors, and variations of those
models should be compatible, provided they have both IR and serial
ports. Memory should not be an issue - the application will use less
than 1KB temporary storage memory, and binary + DB should occupy
less than 20KB on the device itself.
User Interface:
•
•
•
User interface will be a startup screen, and then a blank screen for the
mousepad. Mousing will be done using the stylus, with full click and
drag usability
Mouse buttons will be implemented using hardware buttons on Palm
device itself
Configuration menu will exist for user to select Communications
preferences.
Project Design
High Level Modules:
CalcMouseMovement() - Calculates the distance moved on the
Palm silk screen, creates the Microsoft mouse packet and transmi ts
the mouse packets.
SendMouseID() – Sends PnP Id information when the PC requests
it.
Setup/Config – Opens the serial port and also sets the setting for
the serial port including the baud rate, number of data bits and the
number of stop bits. This portion of the code is contained within the
AppHandleEvent() and occurs whenever the application is started
up. In the future, options will be selectable in a setup for within the
application, to choose between infrared and serial.
6
Data Types:
We did not have any true data types but one interesting aspect of our
code was contained inside the MousePacket() function – our main ‘data
type,’ the hex byte. In the function, we used eight UInt16 to do bitwise
comparisons in order to create our packets. Basically our algorithm would
initialize the eight Uint16 variables such that each one would have a single
bit set from the LSB to bit 7. (Our first value in binary was 00000000
00000001, our second value was 00000000 00000010, etc.) Using these
values, we would compare it to the distance values calculated from
CalcMouseMovement() and add certain values to the packets accordingly.
Development Plan
•
•
•
Development Environment: CodeWarrior for Palm OS, version 6, full
version. Palm OS SDK 3.5. CodeWarrior can be found at any leading
software store, and the newer Palm OS SDK 3.5 can be found at
www.palmos.com/dev.
Version Control: Version control will be done using CVS for NT, which
can be found at www.cvsnt.org. We are using WinCVS as our client,
which can be downloaded at www.wincvs.org. Both products are held
under the GNU license, and allow simultaenous editing and merging of
source. The server is setup on my home machine, with an on -campus
always-on internet connection.
Cross-development: Testing will be done under both emulation and native
execution, depending on the portions of code being tested. To test code
relating to calculations and general serial debugging, we will be using the
Palm OS emulator, for this debugging environment is far quicker than
downloading to the actual Palm device. Debugging functions will be done
7
•
•
•
through both custom debugging code (i.e. printing characters to screen)
and PalmOS debugging avenues (ErrDisplay, ect.). Also, we will be using
the PalmOS Emulator to test the serial port data in raw form, to make sure
our output is correct, using the ComLite app for Windows 95 to read serial
port data (available at www.comlite.com). For testing the operation of the
program, we will be using native execution, with my Palm 5 connected to
the serial port of our PC, to ensure proper program operation.
Nothing platform specific besides Palm OS tools is needed for testing.
Testing Methodology: Testing of the project will be handcrafted, the only
input to the program being manually through the touchpad. To test the
device to handle all cases, there are only a limited number of
combinations needed : General movement, movement while holding the
mouse buttons down, and rapid clicking of the buttons. Most likely, the
test results wont produce anything unexpected, and hopefully it will be
fully functional.
Development Schedule:
-Event Handler
-Mouse Packet Creation
-Serial Transmission
-Plug and Play detection
Most development will be done concurrently, with tasks dispersed across
both partners - we will be using CVS to merge changes.
Evaluation
Qualitative:
Specification: We were able to meet the specifications of the
mouse in emulating the cursor movements and the button
functions. Unfortunately, we were unable to bring the PnP
capability of the mouse to full functionality since the Palm Pilot
serial port lacks the DSR pin that is key to being able to implement
the PnP protocol. The DSR pin signals the PC that a COM device
is present, and the PC will then ask the COM device to send its
COM ID. Without this pin, there is no way to signal the PC to start
the COM device detection sequence. Besides not being able to
implement the PnP protocol, we were also unable to implement
mouse functionality through the infrared port. The implementation
of this specification would have required an infrared device driver,
which we simply did not have time to implement. Standard mouse
drivers are written to function only through hardware comm ports in
Windows, and would not recognize our device as a mouse, even if
we were sending mouse data using the IRComm protocol. The
8
most difficult specification was the PnP capability of our device,
which we were not able to implement due to hardware limitations –
the Palm serial interface is lacking the DSR pin, and we did not
have an expendable cradle to hard-wire the DSR pin with.
Design:
The design of our project allows for easy modular decomposition of
our program. One could just as easily implement our Palm mouse
on any architecture such as a Macintosh. All that would be
required is the format of the mouse packet and a simple change to
our mouse packet creation function. The separation of individual
tasks in implementing the mouse helped in our modules integrating
well, and the modules integrated such that after one module
completed its task, the next module is called to complete its
required task. The design of our mouse was well within the
constraints of the platform, for the Palm and PC met most of the
design constraints imposed by our project specification, except for
the requirement of the Palm serial cradle to have a DSR pin.
Development:
Our methodology for development worked well. Since our modules
were well defined and the task required for each module clearly
known, we were able to divide the tasks and work independently on
the code. In order to easily keep track of the code revisions, Steve
set up WinCvs accounts for the both of us. Using CVS, we were
able to submit the work that we had done and to also merge
updates between our two code copies. Another plus to using the
WinCvs software was that we were able to keep an archive of all
our revisions, which saved us when we made some bad code
changes.
Quantitative:
The performance of our device was excellent in regards to
functionality -- since our mouse was to be run on a portable device
with limited resources, we strived to use the smallest amount of
resources possible but to also achieve our project specifications. In
order to conserve resources, we used a fairly simple user interface.
Another method we used to try to conserve resources was to cut
down on the polling done in our program. Our program runs the
application event loop once every 25 milliseconds. By using a
9
simple user interface, we were able to conserve valuable memory
and by polling every 25 milliseconds, we were able to conserve the
power usage consumed by the Palm, instead of running and using
the CPU constantly when there is no input activity. There was little
if any memory copying and additional overhead in our application.
The memory footprint for our Palm Touch only occupied 4.6KB of
memory.
Concluding Remarks
This project proved to be a very valuable experience, and along with the
basics of Palm and serial hardware programming, we learned higher-level
project organization and management. In being completely responsible
for an application from idea to installation, we learned design,
implementation decision making, and organization, all invaluable tools in
the engineering world. On a lower level, we increased both our
programming proficiency and specific knowledge of computer software
and hardware.
While we were fairly successful in getting a good portion of our project to
work (all normal mouse functionality), we did run into difficulties related to
the Palm platform and time. Our greatest shortcoming was related to PnP
detection – being newcomers to both Palm and hardware programming,
we at first did not have the knowledge of what to search for. If we were to
do things differently, we would put more effort into research on the PC
side – going into the project, we were convinced that the PC could not tell
the difference between our software and a hardware mouse, but late in the
project we came to realize that an small but important link (The DSR pin
on the Palm serial interface) was missing, and prevented our project for
being practical.
We do plan on continuing the project, as it will be (if completed) a great
demonstration of our abilities in both a job interview and graduate school
interview setting. We now have tools for Windows driver development,
and throughout next quarter and this summer plan to develop an infrared
driver on the PC side to support our application.
Credits
Steve Ruiz
•
•
•
Introduction
Background and Related Work
Project Specifications
10
•
•
•
•
•
•
•
•
•
Development Plan
Concluding Remarks
Bibliography
Pen Events
Pen Queue Programming
Serial Transmission
Infrared Research
PnP (not operational)
Functions
o SendMouseData
o SendMouseID
o CalcMouseMovement
o MainFormHandleEvent
o AppEventLoop
Charles Lee
•
•
•
•
•
•
•
•
•
•
Introduction
Background and Related Work
Project Design
Evaluation
Credits
Bibliography
Key Events
Serial Transmission
Infrared Research
Functions
o RomVersionCompatible
o MousePacket
o AppHandleEvent
o AppEventLoop
o StarterPalmMain
Joey Pascual (PalmAmp Group) – Helped with debugging the problems in
our Palm constructor
Justin (PalmAmp Group) – Helped with serial settings (SrmControl()
functions)
Rodger Flores (Sub Hunt Code) – Intercepting Hard Key Events
Rhodes & McKeehan (Palm Programming Book) – code to print text to
field on screen
11
Bibliography
- Palm OS SDK Companion
http://www.palmos.com/dev/tech/docs/palmos/CompanionTOC.html
- Palm OS SDK Reference
http://www.palmos.com/dev/tech/docs/palmos/ReferenceTOC.html
- New Serial manager documentation and Examples
Author: Ben Manuto
http://www.devnation.net/present/1107.cfm
- Serial Communications in Palm OS
http://home.olemiss.edu/~grkanth/
- Mouse Protocol Specification from Open-Source Mouse Driver
Author: Arkady V. Belousov
http://www.vein.hu/~nagyd/
- Palm Programming : The Developer’s Guide
Neil Rhodes, Julie McKeehan, O’Reilly, January 1999