Programming the Palm OS for Embedded IR Applications
Total Page:16
File Type:pdf, Size:1020Kb
M AN888 Programming the Palm OS™ for Embedded IR Applications A Palm OS application program to interface to an Author: Frank Ableson embedded system via IrCOMM is included in the CFG Solutions Inc. Mark Palmer Appendices of this application note. This source code shows the system calls that can be used for IR Microchip Technology Inc. communication. Appendix A describes the system and documents the INTRODUCTION tool used to create this Palm® application program and This application note strives to impart core, Appendix B through Appendix G is the Palm fundamental programming concepts and design Application Program source code. ® considerations for the development of Palm OS Figure 1 shows an IrDA® standard system, where a application programs. Attention is given to each of the Palm PDA device is communicating to an embedded fundamental areas of Palm OS application system. In this system, the Palm PDA operates as the development in the “C” programming language. Primary device and the embedded system operates as the Secondary device. FIGURE 1: PALM™ PDA - EMBEDDED SYSTEM BLOCK DIAGRAM Embedded System with IrDA® Port (Secondary Device) Host Controller MCP215X Optical and Embedded or Transceiver Circuitry MCP2140 Circuitry Palm™ Handheld Device with IrDA® Standard Port (Primary Device) 2004 Microchip Technology Inc. DS00888A-page 1 AN888 Terminology FIGURE 2: IrDA DATA - PROTOCOL STACKS Below is a list of useful terms and their definitions: • Palm OS device: Any device running the Palm IrTran-P IrObex IrLan IrComm (1) IrMC OS operating system. This includes devices from Palm Computing such as the V and m series LM-IAS Tiny Transport Protocol (Tiny TP) units, the IBM® Workpad, a Sony Clié®, or a ® ® Handspring Visor . IR Link Management - Mux (IrLMP) • HotSync™: The process of synchronizing the Palm OS device to a host system. IR Link Access Protocol (IrLAP) • Host System: The computer with which a Palm OS device performs a HotSync. The host system Asynchronous Synchronous Synchronous is also where development takes place. Host Serial IR (2, 3) Serial IR 4PPM systems are typically Windows®, Macintosh® or (9600 -115200 b/s) (1.152 Mb/s) (4 Mb/s) Linux. • Conduit: Code containing the logic necessary for synchronizing a database on the Palm OS device with the host system. Each conduit is invoked Supported by Optional IrDA data during the HotSync operation. Conduits on the PC the MCP215X protocols not platform are packaged as dynamically linked and MCP2140 supported by the libraries (DLLs). Conduits work differently under MCP215X and MCP2140 Linux, where each conduit is an application Note 1: The MCP215X and MCP2140 instead of a library. implement the 9-wire “cooked” service • POSE: The Palm OS Emulator. A desktop tool class serial replicator. useful for debugging applications. 2: An optical transceiver is required. • Primary Device: The IrDA standard device that 3: The MCP2140 support 9600 Baud IR queries for other devices. communication only. • Secondary Device: The IrDA standard device that waits to detect IR communication before doing any IR communication. • Host Controller: The controller in the embedded system that communicates to the MCP215X or MCP2140. • MCP215X: An IrCOMM protocol handler IC that supports IR communication from 9600 baud to 115,200 baud. • MCP2140: A low-cost IrCOMM protocol handler IC that supports IR communication at 9600 baud. • Protocol Stack: A set of network protocol layers that work together. Figure 2 shows the IrDA standard protocol stack. • IrCOMM (9-wire “cooked” service class): IrDA standard specification for the protocol to replace the serial cable (using flow control). DS00888A-page 2 2004 Microchip Technology Inc. AN888 Environment Basics EMULATING A MULTI-TASK ENVIRONMENT This application note begins with a discussion of the The operating system is multi-tasking, though the basics of the Palm OS environment, including resource threads are not available for “user” applications; the limitations, tasking model, user interface basics and few existing threads are for system use only. deployment options. Palm OS application developers Surprisingly, Palm OS applications do an elegant job of must understand these basic boundaries to emulating a multi-tasking environment. Applications successfully develop for this platform. As the create this effect by remembering the currently application note progresses, more detailed information displayed record when the application ends. When the conveys the specifics of communications programming application is restarted, it jumps directly to the most for the Palm OS platform. recently displayed record, as if the application had been running the entire time. In reality, the application Resource limitations was terminated and restarted. Palm OS devices face typical hand-held computer USER INTERFACE (UI) AND APPLICATION system resource limitations, such as storage capacity, PROGRAMMING INTERFACE (APIs) available Random Access Memory (RAM), processor The Palm OS offers an economical User Interface (UI). speed, input devices and power consumption. Traditional user interface elements (such as edit boxes, Fortunately, working with restricted resources is lists, drop-downs, bitmaps, etc.) are available for nothing new to the embedded developer. These building applications. Limited screen size and lack of a limitations go beyond the problem of not having enough keyboard impose some restrictions on the user resources to run all of the applications common on the interface. Later-model devices add greater color depth, desktop. They also pose specific challenges to the bringing a little more appeal to the display. The Palm developer building the applications. For example, a OS provides a rich Application Programming Interface Palm OS application cannot allocate an arbitrarily large (API) for manipulating each type of user interface data structure since heap memory is limited (measured element. in Kilobytes instead of Megabytes). Global variables consume part of this allocation, leaving a very finite The UI should be thought out in advance, based on amount of space for dynamically allocated data what the customer needs to achieve with the structures. application. Care should be taken to ensure that the UI is easy to use. The storage capacity of Palm OS devices currently range from 2 Mbytes to 64 Mbytes. There is no real Some suggestions that can help are: distinction made between what is traditionally • Keep the UI “clean” by minimizing the number of considered volatile RAM and nonvolatile, or persistent buttons, pull downs, icons, etc. storage, as in a hard drive on a desktop. Storage of • Minimize the number of steps performed to see applications, database records and running vital information: applications consume this relatively scarce resource. - most information should be accessible in a This shared space means that the quantity of Address minimal (1 or 2) number of stylus taps or DateBook records stored on a device directly • Optimize which features to include to ensure a impacts the space available for the applications positive user experience themselves. APIs are available for virtually every action necessary More importantly, this resource consumption can in a Palm OS application. It is possible for a user directly impact the application needing to allocate application to go straight to the metal (the Hardware) temporary storage for an operation at run-time. The on a Palm OS device. This practice is discouraged in preferred algorithm for a specific problem may fail on most cases and is considered a programming “hack”. devices with too many Address records. For example, This may cause the user application to no longer work an application cannot slowly spool a graphical print job, on a later-model device, due to different hardware due to insufficient storage space. characteristics. However, this technique of “hacking” can offer interesting opportunities to insert custom code into various portions of the operating system. The result is similar to the functionality of a TSR in the days of DOS, where an interrupt vector is “hooked”, allowing custom code to be invoked when certain events occur. The recommended technique for function (or trap) hooking for the Palm OS involves using a hack manager to coordinate the precedence of multiple custom hacks in use at the same time. 2004 Microchip Technology Inc. DS00888A-page 3 AN888 PALM OS DATABASE TYPES FIGURE 3: PALM DATABASE HEADER The Palm OS file system is actually a database Byte manager. Everything stored on a Palm OS device is a database. Applications are stored as databases, while 00h name user interface components are stored as resource databases. Of course, data, such as phone numbers and to-do lists, are stored as records in a database. Figure 3 shows a representation of the Palm Database 20h attributes version Header, while Example 1 shows what the programming structure looks like. 24h creationDate Two database types of primary concern on the Palm 28h modificationDate OS are: 2Ch lastBackupDate •PRC 30h modificationNumber •PDB 34h appInfoID The first database type is commonly referred to as a 38h sortInfoID “PRC” because of the file extension used on host 3Ch type systems. The PRC file contains a “ready to run” Palm 40h creator OS application, or a Palm OS Shared Library (the end result of the build process). The applications built in this 44h uniqueIDSeed application note result in files with a PRC extension, 48h recordList which are loaded to a Palm OS device. 4Ch The second type of database is a “PDB” file.