Metrologic Optimus S, Optimus R Programming Manual

"C" Programming Guide

Optimus S

Optimus R

Version 3.04.02

Printed on 20 March, 2006

Copyright Notice

Copyright © 2005 Metrologic Instruments Inc.

All rights reserved

The software contains proprietary information of the Company; it is provided under a license agreement
containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of
the software is prohibited.

Due to continued product development this information may change without notice. The information and
intellectual property contained herein is confidential between the Company and the client and remains the
exclusive property of the Company. If you find any problems in the documentation, please report them to us
in writing. The Company does not warrant that this document is error-free.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by
any means, electronic, mechanical, photocopying, recording or otherwise without the prior written
permission of the Company.

For product consultancy and technical support, please contact your local sales representative. Also, you may
visit our web site for more information.

i

Contents

Copyright Notice II

CHAPTER 1: Introduction 1

Revision History ...........................................................................................................................................1

CHAPTER 2: Development Environment 3

2.1 Directory Structure .................................................................................................................................3

2.1.1 BIN ...........................................................................................................................................4

2.1.2 ETC ..........................................................................................................................................4

2.1.3 INCLUDE.................................................................................................................................4

2.1.4 LIB............................................................................................................................................4

2.1.5 README .................................................................................................................................5

2.1.6 USER........................................................................................................................................5

2.2 Setup .......................................................................................................................................................5

2.3 Development Flow..................................................................................................................................5

2.3.1 Create Your Own C Source Program .......................................................................................7

2.3.2 Compile ....................................................................................................................................7

2.3.3 Link ..........................................................................................................................................8

2.3.4 Format Conversion .................................................................................................................12

2.3.5 Download Program to Flash Memory ....................................................................................12

2.4 C Compiler............................................................................................................................................12

2.4.1 Size of Types ..........................................................................................................................13

2.4.2 Representation Range of Integers ...........................................................................................13

2.4.3 Floating Types ........................................................................................................................14

2.4.4 Alignment ...............................................................................................................................14

2.4.5 Register and Interrupt Handling .............................................................................................14

2.4.6 Reserved Words......................................................................................................................14

2.4.7 Extended Reserved Words......................................................................................................15

2.4.8 Bit-Field Usage.......................................................................................................................15

CHAPTER 3: Terminal Specific Function Library 19

3.1 System...................................................................................................................................................20

3.1.1 General ...................................................................................................................................20

3.1.2 Power On Reset (POR) ...........................................................................................................23

3.1.3 System Global Variables ........................................................................................................24

3.1.4 System Information ................................................................................................................28

3.1.5 Security...................................................................................................................................33

3.1.6 Program Manager ...................................................................................................................35

3.2 Barcode Reader.....................................................................................................................................40

3.2.1 Barcode Decoding ..................................................................................................................40

3.2.2 Code Type ..............................................................................................................................41

3.2.3 ScannerDescriptionTable Array .............................................................................................42

3.2.4 Scan Modes ............................................................................................................................48

ii Contents

3.3 Keyboard Wedge Interface ...................................................................................................................60

3.3.1 Definition of the WedgeSetting Array....................................................................................60

3.3.2 KBD / Terminal Type .............................................................................................................61

3.3.3 Capital Lock Auto-Detection..................................................................................................62

3.3.4 Capital Lock Status Setting ....................................................................................................62

3.3.5 Alphabets Case .......................................................................................................................62

3.3.6 Digits Position ........................................................................................................................63

3.3.7 Shift / Capital Lock Keyboard................................................................................................63

3.3.8 Digit Transmission .................................................................................................................63

3.3.9 Inter-Character Delay .............................................................................................................64

3.3.10 Composition of Output String ..............................................................................................64

3.4 Buzzer ...................................................................................................................................................67

3.4.1 Beeper Sequence.....................................................................................................................67

3.4.2 Beep Frequency ......................................................................................................................67

3.4.3 Beep Duration.........................................................................................................................68

3.5 Real-time Clock ....................................................................................................................................70

3.5.1 Calendar..................................................................................................................................70

3.5.2 Alarm......................................................................................................................................72

3.6 LED ......................................................................................................................................................73

3.7 Keypad..................................................................................................................................................74

3.7.1 General ...................................................................................................................................74

3.7.2 ALPHA Key ...........................................................................................................................77

3.7.3 FN Key ...................................................................................................................................80

3.8 LCD ......................................................................................................................................................80

3.8.1 Properties................................................................................................................................81

3.8.2 Cursor .....................................................................................................................................84

3.8.3 Display....................................................................................................................................87

3.8.4 Clear .......................................................................................................................................92

3.8.5 Image ......................................................................................................................................94

3.9 Fonts .....................................................................................................................................................96

3.9.1 Font Size.................................................................................................................................96

3.9.2 Display Capability ..................................................................................................................96

3.9.3 Multi-Language Font ..............................................................................................................97

3.9.4 Special Fonts ..........................................................................................................................97

3.9.5 Font Files ..............................................................................................................................100

3.10 Battery...............................................................................................................................................101

3.11 Communication Ports .......................................................................................................................103

3.11.1 Port Mapping ......................................................................................................................103

3.11.2 Receive & Transmit Buffers ...............................................................................................103

3.11.3 RS-232, Serial IR & IrDA Communications ......................................................................109

3.11.4 PPP via IR/RS-232 .............................................................................................................112

3.12 Wireless Communications ................................................................................................................114

3.13.1 Wireless Models .................................................................................................................115

3.13.2 Network Configuration .......................................................................................................118

3.13.3 Initialization & Termination ...............................................................................................133

3.13.4 Network Status ...................................................................................................................135

3.13.5 WLAN (802.11b)................................................................................................................140

3.13.6 Bluetooth ............................................................................................................................174

3.13 Wireless Practice...............................................................................................................................180

3.13.1 WLAN (802.11b) - Practice ...............................................................................................180

3.13.2 Bluetooth - Practice ............................................................................................................182

3.14 File Manipulation..............................................................................................................................186

3.14.1 File System .........................................................................................................................186

3.14.2 Directory.............................................................................................................................186

3.14.3 File Name ...........................................................................................................................186

Contents

iii

3.14.4 File Handle (File Descriptor) ..............................................................................................187

3.14.5 Error Code ..........................................................................................................................187

3.14.6 DAT Files ...........................................................................................................................190

3.14.7 DBF Files and IDX Files ....................................................................................................201

3.15 Memory.............................................................................................................................................213

3.15.1 Flash ...................................................................................................................................213

3.15.2 SRAM.................................................................................................................................215

3.16 Miscellaneous ...................................................................................................................................217

CHAPTER 4: Standard Library Routine 219

4.1 Input & Output: <stdio.h> ..................................................................................................................220

4.2 Character Class Tests: <ctype.h>........................................................................................................221

4.3 String Functions: <string.h> ...............................................................................................................222

4.3.1 Functions start with "str" ......................................................................................................222

4.3.2 Functions start with "mem" ..................................................................................................223

4.4 Mathematical Functions: <math.h> ....................................................................................................224

4.5 Utility Functions: <stdlib.h> ...............................................................................................................226

4.5.1 Number Conversion..............................................................................................................226

4.5.2 Storage Allocation ................................................................................................................226

4.6 Diagnostics: <assert.h> .......................................................................................................................227

4.7 Variable Argument Lists: <stdarg.h> .................................................................................................227

4.8 Non-Local Jumps: <setjmp.h>............................................................................................................227

4.9 Signals: <signal.h> .............................................................................................................................227

4.10 Time & Date Functions: <time.h> ....................................................................................................227

4.11 Implementation-defined Limits: <limits.h>, <float.h> .....................................................................228

CHAPTER 5: Real-Time Kernel 229

Index 235

1

C H A P T E R 1

Introduction

This "C" Programming Guide describes the application development process with the "C"
Compiler in details. It starts with the general information about the features and usages of
the development tools, the definition of the functions/statements, as well as some sample
programs.

This programming guide is meant for users to write application programs for the Metrologic
Portable Terminals by using the "C" Compiler with the proprietary portable-specific
libraries. It is organized in five chapters giving outlines as follows:

 Chapter 1 “Introduction” – gives a brief on this manual.
 Chapter 2 “Development Environment” – gives a concise introduction about the "C"

Compiler and the development flow for applications, which provides step-by-step
description in developing application programs for the portable data terminals with the
"C" Compiler.

 Chapter 3 “Terminal-specific Functions” – presents callable routines that are specific

to the features of the portable data terminals.

 Chapter 4 “Standard Libraries Routines” – briefly describes the standard ANSI

library routines for in many ANSI related literatures there can be found more detailed
information.

 Chapter 5 “Real Time Kernel” – discusses the concepts of the real time kernel,

µC/OS. Users can generate a real time multi-tasking system by using the µC/OS
functions.

In This Chapter

Revision History................................................................ 1

Revision History

Version Release Date Notes

3.04.02 Dec 16, 2005



2 "C" Programming Guide

For Optimus S/R

3

C H A P T E R 2

Development Environment

In This Chapter

2.1 Directory Structure ...................................................... 3

2.2 Setup ............................................................................ 5

2.3 Development Flow....................................................... 5

2.4 C Compiler .................................................................. 12

2.1 Directory Structure

The C Language Development Kit for Metrologic Portable Terminals contains six
directories, namely, BIN, ETC, INCLUDE, LIB, README and USER. The purposes and
contents of each directory are listed below.

To set up the C language development environment on your PC, you may create the

\C_Compiler directory from the root directory and then simply copy the above six directories

from the CD-ROM to the \C_Compiler directory.

4 "C" Programming Guide

For Optimus S/R

2.1.1 BIN

It contains executable files. Usage will be described further in later sections.

 A number of execution files for compilation, linking, and so on.

asm900.exe cc900.exe Ezdriver.dll mac900.exe

thc1.exe thc2.exe tuapp.exe tuconv.exe

tufal.exe tulib.exe tulink.exe tumpl.exe

 ProgLoad.exe: for downloading program via RS-232/IrDA, Cradle-IR, or TCP/IP.

2.1.2 ETC

It contains help and version information of the C Compiler.

2.1.3 INCLUDE

It contains header files.

 "C" header files for standard library routines

 1 header file for terminal specific library: lib_ops.h or lib_opr.h
 1 header file for Real Time Kernel Library: ucos.h

Wemu387.386

assert.h ctype.h errno.h float.h limits.h

locale.h math.h setjmp.h signal.h stdarg.h

stddef.h stdio.h stdlib.h string.h time.h

2.1.4 LIB

It contains library object code files.

 "C" standard library: c900ml.lib
 Portable specific library: lib_ops.lib or lib_opr.lib

Chapter

2

Development

Environment

5

2.1.5 README

It contains C Compiler version update and supplemental information.

2.1.6 USER

It contains source code of the user's program or other sample programs.

2.2 Setup

Before using the compiler, some environmental variables must be added to the
autoexec.bat.

 path = C:\C_Compiler\BIN (or your own path)

So that all executable files (.EXE and .BAT) can be found.

 set THOME900 = C:\C_Compiler\

This is a must for the compiler to locate all necessary files.

 set tmp = C:\tmp

This is the temporary working directory for the compiler and linker (for memory and
file swapping). Skip this if tmp is already specified.

To improve efficiency, the compiler invokes a virtual memory manager "DOS4GW". It
recognizes and supports various PCs. However, if it does not work on your PC, the program

PMINFO can be used to identify the problem. If you encounter problems in using the

compiler, run the PMINFO. Then print all messages and contact Metrologic Instruments
Inc.

2.3 Development Flow

The development process is much like writing any other C programs on PC.

6 "C" Programming Guide

For Optimus S/R

The flow is illustrated as shown below.

Chapter

2

Development

Environment

7

2.3.1 Create Your Own C Source Program

The first step is to create or modify the desired C programs using any text editors. We
recommend that you use ".C" as the file extension and create them under the USER
directory, and then use the USER directory as the working directory. We also recommend
that you divide the whole program into modules while retaining function integrity, and put
modules into separate files to reduce compilation time.

2.3.2 Compile

To compile the C programs, use cc900 command in the directory of the target file.

cc900 -[options] FILENAME.C

For the usage of cc900 command and the options, please refer to cc900.hlp in the ETC
subdirectory.

The batch file "Y.BAT" which can be found under the USER directory has been created to
simplify the compiling process.

Y FILENAME.C

This batch file invokes the C compilation program which in turn calls many other
executable programs under the BIN directory. As these programs are invoked by the
compiler sequentially, their usages can be ignored. Also, many parameters are set in calling
the compiler driver to accommodate target machine environments. It is recommended to
use the Y.BAT file directly. If you attempt to write your own batch file, remember to put the
same parameters as shown below.

 -XA1, -XC1, -XD1, -Xp1: alignment setting, all 1
 -XF: no deletion of assembly file, if it is not necessary to examine the assembly file.

This option can be removed.

 -O3: set optimization level (can be 0 to 3, but not the maximum optimization). If code

size and performance is not a problem, this option can be removed which will then set to
the default - O0, that is, no optimization at all. If optimization is enabled, care must be
taken that some instructions might be optimized and removed. For example,

Test()

{

unsigned int old_msec;

old_msec = sys_msec;

while (old_msec == sys_msec);

}

8 "C" Programming Guide

For Optimus S/R

2.3.3 Link

This routine waits until sys_msec is changed. And sys_msec is a system variable that is
updated each 5 ms by background interrupt. If optimization is enabled, this whole
routine is truncated as it is meaningless (which is a dead-loop). To avoid this, the type
identifier "volatile" can be used to suppress optimization.

 -c: create object but no link
 -e cerr.lst: create error list file "CERR.LST"

After compilation is completed, a relocatable object file named "program_name.REL" is
created which can be used later by the linker to create the executable object program. As the
compiler compiles the program into assembler form during the process, an accompanying
assembler source file "program_name.ASM" is also created. This file helps in debugging if
necessary. If any error occurs, they will be put into the file "CERR.LST" for further
examination.

If the C source programs are successfully compiled into relocatable object files, the linker
must be used to create the absolute objects and then the file can be downloaded to the target
machine's flash memory for execution. However, a linker map file must be created.

TULINK FILENAME.LNK

This map file "FILENAME.LNK" is used to instruct the linker to allocate absolute addresses
of code, data, constant, and so on according to the target machine environments. This is a
lengthy process as it depends on the hardware architecture. Fortunately, a sample linker
map file is provided and few steps are required to customize it for your own need, while
leaving hardware-related stuff unchanged.

From the following sample linker file, you can see that only the file names need to be
changed (underlined & boldfaced sections). If the linking is successful, an absolute object
file names "FILE1.ABS" is created. Besides, a file named "FILE1.MAP" lists all code and
variable addresses, and, error messages if there is any.

Sample Linker File

-lm -lg -ll /* parameters for TULINK, do not change */

File1.rel /* your C program name */

File2.rel /* your C program name */

......

Chapter

2

Development

Environment

9

......

FileN.rel /* your C program name */

..\lib\lib_ops.lib /* Optimus S function library */

..\lib\c900ml.lib /* C standard library */

/*********************************************/

/* User could provide suitable values */

/* to the following variables */

/*********************************************/

MainStackSize = 0x001000;

HeapSize = 0x000100;

MaxSysRamSize = 0x020000;

/*********************************************/

/* Do not modify anything beyond this line */

/*********************************************/

memory

{

IRAM: org = 0x001100, len = 0x000e00 /* 0x1000 - 0x10ff IntVec */

/* 0x1f00 - 0x1fff Stack */

RAM : org = 0x205000, len = 0x3b000

ROM : org = 0xf00000, len = 0x0e0000

}

sections

{

10 "C" Programming Guide

For Optimus S/R

code org = 0xf00000 : {

*(f_head)

*(f_code)

} > ROM

area org = 0x205000 : {

. += MainStackSize;

. += HeapSize;

*(f_bcr)

*(f_area)

} > RAM

data org=org(code)+sizeof(code) addr=org(area)+sizeof(area) :
{

*(f_data)

} /* global variables with initial values */

xcode org = org(data) + sizeof(data) addr = addr(data) +
sizeof(data) : {

*(f_xcode) /* code reside on RAM */

}

RAM_OVERFLOW_CHECK org = org(area) + MaxSysRamSize : {

. += 1;

} > RAM

icode org = org(xcode) + sizeof(xcode) addr = 0x001100 : {

*(f_icode) /* code reside on IRAM */

Chapter

2

Development

Environment

11

}

const org = org(icode) + sizeof(icode) : {

*(f_const)

*(f_tail)

} > ROM

}

ActualRamSize = (addr(xcode) + sizeof(xcode)+3)/4*4 - 0x205000 ; /*
long boundary */

SysRamEnd = org(area) + MaxSysRamSize; /* long boundary */

DataRam = addr(data);

XCodeRam = addr(xcode);

ICodeRam = addr(icode);

HeapTop = org(area) + MainStackSize;

/* End */

12 "C" Programming Guide

For Optimus S/R

2.3.4 Format Conversion

The absolute object file created by TULINK is in TOSHIBA's own format. Before being
downloaded to the target machine, it must be converted to the Motorola S format by using
the "TUCONV" utility.

TUCONV -Fs32 -o FILENAME.shx FILENAME.abs

The file extension .SHX is a must for the code downloader.

The batch file "Z.BAT" which can be found under the USER directory has been created to
simplify the linking and format conversion process. Simply run the batch file:

Z

The target executable file (with SHX extension) will then be generated if no error is found.

2.3.5 Download Program to Flash Memory

Now that the Motorola S format object file FILENAME.shx is created successfully, it can be
downloaded to the flash memory for testing. Run the DOWNLOAD.exe utility (or
IRLOAD.exe for IR interface) and configure the following parameters properly.

 File Name:

 COM Port:

 Baud Rate:

 Parity:

 Data Bits:

 Flow Control:

The selected baud rate, parity, data bits, etc. must match the COM port settings of the target
machine.

2.4 C Compiler

This C compiler is for TOSHIBA TLCS-900 family 16-bit MCUs, and it is mostly ANSI
compatible. Some specific characteristics are presented in this section.

Specify the absolute object file.

Select the appropriate COM port for transmission.

Supported baud rates are 115200, 57600, 38400, 19200, and 9600.

None

8

None

Chapter

2

Development

Environment

13

2.4.1 Size of Types

Types Size in byte

char, unsigned char 1

short int, unsigned short int, int, unsigned int 2

long int, unsigned long int 4

pointer 4

structure, union 4

2.4.2 Representation Range of Integers

Regarding the representation range of the values of integer types, macros are defined in the
header file <limits.h> as follows.

Macro Name Contents

CHAR_BIT number of bits in a byte (the smallest object)

SCHAR_MIN minimum value of signed char type

SCHAR_MAX maximum value of signed char type

CHAR_MIN minimum value of char type

CHAR_MAX maximum value of char type

UCHAR_MAX maximum value of unsigned char type

MB_LEN_MAX number of bytes in a wide character constant

SHRT_MIN minimum value of short int type

SHRT_MAX maximum value of short int type

USHRT_MAX maximum value of unsigned short int type

INT_MIN minimum value of int type

INT_MAX maximum value of int type

UINT_MAX maximum value of unsigned int type

LONG_MIN minimum value of long int type

LONG_MAX maximum value of long int type

ULONG_MAX maximum value of unsigned long int type

14 "C" Programming Guide

For Optimus S/R

2.4.3 Floating Types

Float types are supported and conform to IEEE standards.

Types Size in bits

float 32

double 64

long double 64

2.4.4 Alignment

Alignment of different types can be adjusted. This is to facilitate CPU performance by
trading off memory space. However, when all target systems utilize 8-bit data bus, the
alignment does not improve performance and is fixed to 1 for all types. In invoking the C
compiler, driver (-XA1, -XD1, -XC1, and -Xp1) is specified.

2.4.5 Register and Interrupt Handling

Register and interrupt handling are possible through C. However, they are prohibited as all
the accessing to system resources is supposed to be made via proprietary library routines.

2.4.6 Reserved Words

These are the reserved words (common to all Cs) in general.

auto break case char const

continue default do double else

enum extern float for goto

if int long register return

short signed sizeof static struct

switch typedef union unsigned void

volatile while

Chapter

2

Development

Environment

15

2.4.7 Extended Reserved Words

These are the reserved words specific to this C compiler and all of them start with two
underscores ("_ _").

_ _adcel _ _cdcel _ _near _ _far

_ _tiny _ _asm _ _io

_ _XWA _ _XBC _ _XDE _ _XHL

_ _XIX _ _XIY _ _XIZ _ _XSP

_ _WA _ _BC _ _DE _ _HL

_ _IX _ _IY _ _IZ _ _W

_ _A _ _B _ _C _ _D

_ _E _ _H _ _L _ _SF

_ _ZF _ _VF _ _CF

_ _DMAS0 _ _DMAS1 _ _DMAS2 _ _DMAS3

_ _DMAD0 _ _DMAD1 _ _DMAD2 _ _DMAD3

_ _DMAC0 _ _DMAC1 _ _DMAC2 _ _DMAC3

_ _DMAM0 _ _DMAM1 _ _DMAM2 _ _DMAM3

_ _NSP _ _XNSP _ _INTNEST

2.4.8 Bit-Field Usage

The following types can be used as the bit field base types. The allocation is made as shown
in the illustrations.

Types Size in bits

char, unsigned char 8

short int, unsigned short int, int, unsigned int 16

long int, unsigned long int 32

The bit-field can be very useful in some cases. However, if memory is not a concern, it is
recommended not to use the bit-fields because the code size is downscaled at the cost of
degraded performance.

16 "C" Programming Guide

For Optimus S/R

Fields are stored from the highest bits

Little endien

If the base type of a bit field member is a type requiring two bytes or more (e.g.
unsigned int), the data is stored in memory after its bytes are turned upside down.

Different types (different size)

A bit field with different type is assigned to a new area.

Chapter

2 Development

Environment

17

Different types (signed/unsigned)

Different types (same size)

18 "C" Programming Guide

For Optimus S/R

19

C H A P T E R 3

Terminal Specific Function Library

There are a number of terminal specific library routines to facilitate the development of the
user's application. These functions cover a wide variety of tasks, including
communications, show string or bitmap on the LCD, buzzer control, scanning, file
manipulation, etc. They are categorized and described in this chapter by their functions or
the resources they work on.

The function prototypes of the library routines, as well as the declaration of the system
variables, can be found in the library header file (lib_ops.h or lib_opr.h). It is assumed that
the programmer has prior knowledge of the C language.

In This Chapter

3.1 System ......................................................................... 20

3.2 Barcode Reader............................................................ 40

3.3 Keyboard Wedge Interface.......................................... 60

3.4 Buzzer.......................................................................... 67

3.5 Real-time Clock........................................................... 70

3.6 LED ............................................................................. 73

3.7 Keypad......................................................................... 74

3.8 LCD ............................................................................. 80

3.9 Fonts ............................................................................ 96

3.10 Battery ....................................................................... 101

3.11 Communication Ports ................................................ 103

3.12 Wireless Communications......................................... 114

3.13 Wireless Practice ....................................................... 180

3.14 File Manipulation....................................................... 186

3.15 Memory ..................................................................... 213

3.16 Miscellaneous ............................................................ 217

20 "C" Progra

mming Guide

For Optimus S/R

3.1 System

3.1.1 General

ChangeSpeed

Purpose

Syntax

Example

Description

Return

To change the CPU running speed.

void ChangeSpeed (int speed);

ChangeSpeed (4);

When high speed operation is not necessary, selecting slower CPU speed can
save battery power. The parameter speed is set to one of the following values:

1 Sixteenth

2 Eighth

3 Quarter

4 Half

5 Full

None

CheckWakeUp Optimus S

Purpose

Syntax

Example

To check the wakeup event.

int CheckWakeUp (void);

event = CheckWakeUp();

Description

Return

_KeepAlive__

Purpose

Syntax

This routine checks on the wakeup event.

The return value can be one of the following:

POWER_KEY_PRESSED (1) The POWER key is pressed.

CHARGE_OK (2) Charging is completed.

TIME_IS_UP (3) The alarm time is up.

To let the user program keep on running and prevent it from being
automatically shut down by the system.

void _KeepAlive__ (void);

Chapter

3

Terminal

Specific

Function

Library

21

Example

Description

_KeepAlive__();

Whenever this routine is called, it will reset the counter governed by the global
variable AUTO_OFF, so that the user's application program will keep on
running without suffering from being automatically shut down by the system.

Return

None

SetPwrKey Optimus S

Purpose

Syntax

To set the POWER key as the wakeup event.

void SetPwrKey (int mode);

int mode; /* enable or disable the POWER key */

Example

Description

SetPwrKey (1); /* enable the POWER key for waking up the terminal*/

The parameter mode is set to one of the following values:

POWER_KEY_DISABLE (0) The POWER key is disabled.

POWER_KEY_ENABLE (1) The POWER key is enabled.

Return

None

shut_down

Purpose

Syntax

Example

Description

Return

SysSuspend

Purpose

Syntax

Example

Description

Return

To shut down the system.

void shut_down (void);

shut_down();

This routine shuts down the system. Upon powering on, the system will always
restart.

None

To shut down the system.

void SysSuspend (void);

SysSuspend();

This routine shuts down the system. Upon powering on, the system may
resume or restart itself, depending on the system setting.

None

22 "C" Progra

mming Guide

For Optimus S/R

system_restart

Purpose

Syntax

Example

Description

Return

To restart the system.

void system_restart (void);

system_restart();

This routine simply jumps to the Power On Reset point and restarts the system.

None

Chapter

3

Terminal

Specific

Function

Library

23

3.1.2 Power On Reset (POR)

After being reset, a portion of library functions called POR routine initializes the system
hardware, memory buffers, and parameters such as follows.

RS-232

Reader ports

Keypad scanning

LCD

Calendar

LED

Allocate stack area and other parameters.

: all disabled

: all disabled

: enabled

: initialized and cleared to blank, cursor is on and set to the upper-left corner
(0, 0)

: initialized

: off

There must be one and only one "main" function in the C program which is the entry point
of the application program. Control is then transferred to the "main" function whenever the
system initialization is done.

24 "C" Progra

mming Guide

For Optimus S/R

BKLIT_TIMEOUT; /* in units of 1 second */

3.1.3 System Global Variables

There are several global variables that are declared by the system.

 Two of them are system timers that are cleared to 0 upon powering up.

extern volatile unsigned long

sys_msec; /* in units of 5 ms */

extern volatile unsigned long

sys_sec; /* in units of 1 second */

Note: Do not write to these system timers as they are updated by the timer interrupt.

 Other system variables are as follows.

extern unsigned int

AUTO_OFF; /* in units of 1 second */

This variable governs the timer for the system to automatically shut down the user’s
program whenever there is no operation during the preset period.

When it is set to 0, the AUTO_OFF function will be disabled.

extern unsigned int

POWER_ON;

This variable can be set to either POWERON_RESUME or POWERON_RESTART.
By default, it is set to POWERON_RESUME, i.e., upon powering on, the user program
will start from the last powering off session.

However, in some cases the user program will always restart itself upon powering on:

 when batteries being removed and loaded back;

 when entering the System Menu before normal operation.

extern unsigned int

This variable holds the backlight timer for the LCD when its backlight is set on. By
default, it is set to 20 seconds.

Chapter

3

Terminal

Specific

Function

Library

25

/* in units of 5 ms */

extern long

AIMING_TIMEOUT;

This variable holds the aiming timer for the Aiming mode of the scanner. By default, it
is set to 200 (= 1 second).

extern int

IrDA_Timeout;

This variable governs the timer for the IrDA connection, i.e. the system will give up
trying to establish connection with an IrDA device when the timer expires.

Possible value of this variable can be one of the following time intervals. By default, it
is set to 1, i.e., 3 seconds.

1 : 3 sec

2 : 8 sec

3 : 12 sec

4 : 16 sec

5 : 20 sec

6 : 25 sec

7 : 30 sec

8 : 40 sec

extern int

BC_X, BC_Y;

These two variables govern the location of the battery icon, i.e. once their values are
changed, the battery icon will be moved.

 Optimus S: Set to (96, 51) by default.

 Optimus R: Set to (120, 51) by default.

extern int

KEY_CLICK [4];

This variable holds the frequency-duration pair of the key click.

The following example can be used to generate a beeping sound like the key click.

on_beeper (KEY_CLICK);

extern unsigned char

WakeUp_Event_Mask;

 For the Optimus R, it is possible to wake up the terminal by one of the following

pre-defined events:

26 "C" Progra

mming Guide

For Optimus S/R

Wedge_WakeUp when the keyboard wedge cable is connected

RS232_WakeUp when the RS-232 cable is connected

Charging_WakeUp when the terminal is being charged

ChargeDone_WakeUp when the battery charging is done

For example,

WakeUp_Event_Mask = RS232_WakeUp|Charging_WakeUp;

/* wake up by RS-232 connection or battery charging events */

 For the Optimus S, it is possible to wake up the terminal by one of the following

pre-defined events:

PwrKey_WakeUp when the POWER key is pressed

Alarm_WakeUp when the alarm time is up

extern char

ProgVersion[16];

This character array can be used to store the version information of the user program.
Such version information can be checked from the submenu: System Menu > Version.

Note that your C program needs to declare this variable to overwrite the system default
setting. For example,

char ProgVersion[16] = "Power AP 1.00";

Chapter

3

Terminal

Specific

Function

Library

27

3.1.4 System Information

These routines can be used to collect information on components, either hardware or
software.

Change Serial Number/Device ID

A custom serial number may be desired to meet specific requirements. After any change
made to the serial number, the manufacturing serial number still can be traced down by
calling OriginalSerialNumber().

It is not recommended that user should make any change to the manufacturing device ID.
Be aware that the terminal will not work with wrong device ID.

Step 1 – Go to Kernel Menu > 1. Information. The current system information is displayed.

Note: The Kernel Menu is launched by pressing three keys simultaneously: [1], [7], and
the POWER key.

Step 2 – Press down [1] + [7] for approximately 3 seconds.

Step 3 – Type the password “8647116686471166”, and then press [ENTER].

Instead of key-in, you may scan the barcode below.

8647116686471166

Step 4 – Press [1] for changing Serial Number, or press [2] for Device ID.

Step 5 – Type new serial number or device ID, and then press [ENTER].

Step 6 – Press [F9] to confirm updating. It takes several seconds to complete.

Step 7 – Press the POWER key to restart the terminal.

DeviceType

Purpose

To get information of modular components in hardware.

Syntax

Example

Description

void* DeviceType (void);

printf ("DEV:%s - %01d", DeviceType(), KeypadLayout());

The information of device type is displayed as as "abcd".

28 "C" Progra

mming Guide

For Optimus S/R

Return

Digits a b c d

Types Reader Module Wireless Module Reserved Reserved

Optimus S a=0, 1, 2 b=0, 5 c=0 d=0

Optimus R a=0, 1, 2 b=0, 4, 5 c=0 d=0

Device Type Meaning

0xxx No reader

1xxx CCD reader

2xxx Laser reader

x0xx No module

x4xx IEEE 802.11b module

x5xx Bluetooth module only

It always returns a pointer indicating where the information is stored.

See Also

FontVersion

Purpose

Syntax

Example

Description

Return

See Also

GetRFmode

FontVersion, GetRFmode, HardwareVersion, KernelVersion, KeypadLayout,
LibraryVersion, ManufactureDate, NetVersion, OriginalSerialNumber,
SerialNumber

To get version information of font file.

void* FontVersion (void);

printf ("FONT:%s", FontVersion);

By default, the version information will be "System Font".

If any font file is downloaded to the terminal, its file name is copied for the
version information.

It always returns a pointer indicating where the information is stored.

DeviceType, GetRFmode, HardwareVersion, KernelVersion, KeypadLayout,
LibraryVersion, ManufactureDate, NetVersion, OriginalSerialNumber,
SerialNumber

Purpose

Syntax

Example

Description

To get RF mode.

int GetRFmode (void);

GetRFmode();

This routine gets the current RF mode.

0x00 NO_RF_MODEL (Optimus S, Optimus R)

Chapter

3

Terminal

Specific

Function

Library

29

Return

0x04 MODE_802DOT11 (Optimus R)

0x05 MODE_BLUETOOTH (Optimus S, Optimus R)

The return value is model-dependent.

See Also

HardwareVersion

Purpose

Syntax

Example

Description

Return

See Also

KernelVersion

Purpose

DeviceType, FontVersion, HardwareVersion, KernelVersion, KeypadLayout,
LibraryVersion, ManufactureDate, NetVersion, OriginalSerialNumber,
SerialNumber

To get version information of hardware.

void* HardwareVersion (void);

printf("H/W:%s", HardwareVersion());

This routine gets the version information of PCB.

It always returns a pointer indicating where the information is stored.

DeviceType, FontVersion, GetRFmode, KernelVersion, KeypadLayout,
LibraryVersion, ManufactureDate, NetVersion, OriginalSerialNumber,
SerialNumber

To get version information of kenel.

Syntax

Example

Description

Return

See Also

KeypadLayout

Purpose

Syntax

Example

Description

void* KernelVersion (void);

printf("KNL:%s", KernelVersion());

This routine gets the version information of kernel.

It always returns a pointer indicating where the information is stored.

DeviceType, FontVersion, GetRFmode, HardwareVersion, KeypadLayout,
LibraryVersion, ManufactureDate, NetVersion, OriginalSerialNumber,
SerialNumber

To get layout information of keypad.

int KeypadLayout (void);

printf("DEV:%s - %01d", DeviceType(), KeypadLayout());

This routine gets the layout information of keypad.

Series Keypad Layout

Optimus S 21-key

30 "C" Progra

mming Guide

For Optimus S/R

Return

Optimus R 24-key or 39-key

For the Optimus S, it always returns 0.

For the Optimus R, it returns 0 for 24-key or 1 for 39-key.

See Also

LibraryVersion

Purpose

Syntax

Example

Description

Return

See Also

DeviceType, FontVersion, GetRFmode, HardwareVersion, KernelVersion,
LibraryVersion, ManufactureDate, NetVersion, OriginalSerialNumber,
SerialNumber

To get version information of library.

void* LibraryVersion (void);

printf("LIB:%s", LibraryVersion());

This routine gets the version information of portable specific library.

Series LibraryVersion()

Optimus S lib_ops.lib

Optimus R lib_opr.lib

It always returns a pointer indicating where the information is stored.

DeviceType, FontVersion, GetRFmode, HardwareVersion, KernelVersion,
KeypadLayout, ManufactureDate, NetVersion, OriginalSerialNumber,
SerialNumber

ManufactureDate

Purpose

Syntax

Example

Description

Return

See Also

NetVersion

Purpose

Syntax

Example

To get the manufacturing date.

void* ManufactureDate (void);

printf("M/D:%s", ManufactureDate());

This routine gets the manufacturing date.

It always returns a pointer indicating where the information is stored.

DeviceType, FontVersion, GetRFmode, HardwareVersion, KernelVersion,
KeypadLayout, LibraryVersion, NetVersion, OriginalSerialNumber,
SerialNumber

To get version information of external library.

void* NetVersion (void);

printf("NetLIB:%s", NetVersion());

Chapter

3

Terminal

Specific

Function

Library

31

Description

Return

See Also

OriginalSerialNumber

Purpose

Syntax

Example

Description

This routine gets the version information of external library, if there is any.

Otherwise, it will get the version information of portable specific library.

Series NetVersion()

If external library exists… No external library…

Optimus S ops_ppp.lib, ops_bnep.lib lib_ops.lib

Optimus R opr_ppp.lib, opr_bnep.lib,

It always returns a pointer indicating where the information is stored.

DeviceType, FontVersion, GetRFmode, HardwareVersion, KernelVersion,
KeypadLayout, LibraryVersion, ManufactureDate, OriginalSerialNumber,
SerialNumber

To get the original serial number of the terminal.

void* OriginalSerialNumber (void);

printf("S/N:%s", OriginalSerialNumber());

This routine gets the original serial number of the terminal.

opr_wlan.lib

lib_opr.lib

Return

See Also

SerialNumber

Purpose

Syntax

Example

Description

Return

See Also

Note that if the original serial number is "???", it means the serial number has
never been modified.

It always returns a pointer indicating where the information is stored.

DeviceType, FontVersion, GetRFmode, HardwareVersion, KernelVersion,
KeypadLayout, LibraryVersion, ManufactureDate, NetVersion, SerialNumber

To get the current serial number of the terminal.

void* SerialNumber (void);

printf("S/N:%s", SerialNumber());

This routine gets the current serial number of the terminal.

It always returns a pointer indicating where the information is stored.

DeviceType, FontVersion, GetRFmode, HardwareVersion, KernelVersion,
KeypadLayout, LibraryVersion, ManufactureDate, NetVersion,
OriginalSerialNumber

32 "C" Progra

mming Guide

For Optimus S/R

3.1.5 Security

To provide the System Menu with password protection so that unauthorized users cannot
gain access to it, you may either directly enable the password protection mechanism from
the System Menu, or through programming.

In addition, a number of security-related functions are available for using the same
password to protect your own application.

CheckPasswordActive

Purpose

Syntax

Example

Description

Return

See Also

CheckSysPassword

Purpose

Syntax

Example

Description

To check if the system password is enabled.

int CheckPasswordActive (void);

if (CheckPasswordActive())

printf ("Please input password:");

This routine detects whether the system password is enabled or not.

By default, the System Menu is not password-protected.

If enabled, it returns 1.

Otherwise, it returns 0 (i.e. no password required).

CheckSysPassword, InputPassword, SaveSysPassword

To check if the input string matches the system password.

int CheckSysPassword (const char *psw);

if (!CheckSysPassword (szInput))

printf ("Password incorrect!!!");

If the system password is enabled and you want to use the same password to
protect your application, then this routine can be used to check if the input
string matches the system password.

Return

See Also

InputPassword

Purpose

If matching, it returns 1.

Otherwise, it returns 0.

CheckPasswordActive, InputPassword, SaveSysPassword

To let the user input the password.

Chapter

3

Terminal

Specific

Function

Library

33

Syntax

Example

Description

Return

See Also

SaveSysPassword

Purpose

Syntax

Example

int InputPassword (char *psw);

char szPsw [10];

printf ("Input password:");

if (InputPassword (szPsw))

if (!CheckSysPassword (szPsw))

printf ("Illegal password!");

This routine provides simple edit control for the user to input the password.
Yet, instead of showing normal characters, it shows an asterisk (*) on the
display whenever the user inputs a character.

If input is confirmed by hitting [Enter], it returns 1.

If input is cancelled by hitting [ESC], it returns 0.

CheckPasswordActive, CheckSysPassword, SaveSysPassword

To save or change the system password.

int SaveSysPassword (const char *psw);

SaveSysPassword ("12345");

Description

Return

See Also

This routine allows you to change the system password, but the length of
password is limited to 8 characters maximum. If the input string is a NULL, the
system password will be disabled.

If successful, it returns 1.

Otherwise, it returns 0 to indicate the length of password is over 8 characters.

CheckPasswordActive, CheckSysPassword, InputPassword

34 "C" Progra

mming Guide

For Optimus S/R

3.1.6 Program Manager

The Program Manager, being part of the kernel for the Optimus S and Optimus R, is capable
of managing multiple programs.

Flash Memory (Program Manager)

 It is possible to download up to 6 programs by calling LoadProgram().

 But only one of them can be activated by calling ActivateProgram(), and then the

program gets to running upon powering on.

SRAM (File System)

 By calling DownLoadProgram(), programs can be downloaded to the file system as

well.

 The number of programs that can be downloaded depends on the size of SRAM or

memory card, but it cannot exceed 253.

 After downloading, the setting of ProgVersion[], if it exists, will be used to be the

default file name. Otherwise, it will be named as “Unknown” automatically. This
file name may be changed by rename if necessary.

 A program in the file system can be loaded to the Program Manager (flash memory)

by calling UpdateBank(). Its file name, as well as the program version, will be copied
to the Program manager accordingly. Then it can be activated by calling
ActivateProgram().

 Alternatively, a program in the file system can be directly activated by calling

UpdateUser(). If the file system is not cleared, it allows options for removing the
program from the file system.

ActivateProgram

Purpose

Syntax

To make a resident program become the active program, and to clear/keep the
original file system.

void ActivateProgram (int Prog, int mode);

int Prog; /* 1 ~ 6, represents one of the 6 resident programs */

int mode; /* clear or keep file system */

Example

ActivateProgram (3, KEEP_FILE_SYSTEM);

/* make program #3 become active and keep the file system */

Chapter

3

Terminal

Specific

Function

Library

35

Description

Return

See Also

DownLoadProgram

Purpose

Syntax

This routine copies the desired program (Prog) in flash memory from its
residence location to the active area, and thus makes it become the active
program. The original file system may be kept or cleared (mode).

KEEP_FILE_SYSTEM 0

CLEAR_FILE_SYSTEM 1

 The original program resided in the active area will then be replaced by the

new program.

 The POWER key is disabled to protect the system while replacing the

program.

 This routine will not return, however, once the execution continues

running to the next instruction, it means the operation of this routine fails.

 If successful, the new program will be activated immediately.

None

LoadProgram, ProgramInfo, ProgramManager

To download a user program (.SHX) to SRAM.

int DownLoadProgram (char *filename, int comport, int baudrate);

Example

Description

Return

See Also

char *filename;

/* pointer to a buffer where filename of the program is stored */

int comport; /* COM1 or COM2 for transmission */

int baudrate; /* appropriate baud rate */

val = DownLoadProgram (filename_buffer, 1, BAUD_115200);

/* download user program via COM1 at 115200 bps and return file name to
filename_buffer */

This routine is used to download a user program to the file system (SRAM).

 A file name can be 8 bytes at most, the null character not included.

 If its file name is identical to an existing program, the execution will fail.

 For the Optimus R, it is necessary to set the communication type of the

specified port before calling this routine, i.e. SetCommType(1, 0) for
Direct RS-232 or SetCommType(1, 2) for Cradle-IR. Download via IrDA
is allowed for LoadProgram() only, not for this routine.

If successful, it returns 1.

On error, it returns 0.

Otherwise, it returns -1 to indicate the action is aborted.

UpdateBank, UpdateUser

36 "C" Progra

mming Guide

For Optimus S/R

LoadProgram

Purpose

Syntax

Example

Description

Return

See Also

ProgramInfo

Purpose

Syntax

To download a user program (.SHX) to flash memory.

void LoadProgram (int Prog);

int Prog; /* 1 ~ 6, represents one of the 6 resident locations */

LoadProgram (3); /* load the user program to location #3 */

Upon calling this routine, the system exists the user application and enters the
Program Manager menu > Download page immediately.

Simply choose "Download Via" and then "Baud Rate" in order to download the
user program to the specified location.

None

ActivateProgram, ProgramInfo, ProgramManager

To list program information.

int ProgramInfo (int slot, char *programtype, char *programname);

int slot; /* 1 ~ 6, represents one of the 6 resident locations */

Example

Description

Return

See Also

ProgramManager

Purpose

Syntax

char *programtype; /* pointer to a buffer where program type is stored */

char *programname; /* pointer to a buffer where program name is stored */

val = ProgramInfo (2, typebuffer, namebuffer);

This routine retrieves program information including its size and name.

 The program size, in kilo-bytes, depends on how many memory banks one

program occupies.

 The program name is the same one as shown in the menu of Program

Manager.

 The file type will be returned with a small letter: "c" for a C program, "b"

for a BASIC program, and "f" for a font file.

 Since one bank is 64 KB, the return value will be 64, 128, ..., etc.

If successful, it returns the bank size of program.

Otherwise, it returns 0 to indicate the program does not exist.

ActivateProgram, LoadProgram, ProgramManager

To enter the kernel and bring up the menu of Program Manager.

void ProgramManager (void);

Example

ProgramManager(); /* jump to the menu of Program Manager */

Chapter

3

Terminal

Specific

Function

Library

37

Description

Return

See Also

UpdateBank

Purpose

Syntax

Example

Description

Return

Upon calling this routine, the user program stops running and jumps to the
kernel, and then the Program Manager will take over the control.

The Program Manager menu is displayed.

None

ActivateProgram, LoadProgram, ProgramInfo

To copy a user program from SRAM to flash memory.

int UpdateBank (const char *filename);

char *filename; /* file name of program to be loaded */

val = UpdateBank ("PlayTest");

This routine copies a user program from the file system (SRAM) to Program
Manager (flash memory).

 A file name can be 8 bytes at most, the null character not included.

 If the file name specified is identical to that of an existing program in flash

memory, the new program will replace the old one.

 Otherwise, it will be stored in an automatically assigned residence

location.

If successful, it returns the residence location of program, i.e. slot 1 ~ 6.

See Also

UpdateUser

Purpose

Syntax

Example

Description

On error, it returns -1.

DownLoadProgram, UpdateUser

To make a user program (.SHX) in SRAM become the active program.

int UpdateUser (const char *filename, int mode, int remove);

char *filename;

/* pointer to a buffer where filename of the program is stored */

int mode; /* clear or keep file system */

int remove; /* if file system is kept, may remove the program from it */

val = UpdateUser ("PlayTest", KEEP_FILE_SYSTEM, 0);

/* activate the program, and keep the file system as well as this program */

This routine copies the desired program from the file system directly to the
active area of the Program Manager in flash memory, and thus makes it become
the active program. The original file system may be kept or cleared (mode).

38 "C" Progra

mming Guide

For Optimus S/R

Return

KEEP_FILE_SYSTEM 0

CLEAR_FILE_SYSTEM 1

If the file system is kept, the program may be removed from it (remove). Set 0
to keep program; 1 to remove program.

 A file name can be 8 bytes at most, the null character not included.

 The original program resided in the active area will then be replaced by the

new program.

 While replacing the program, the POWER key is disabled to protect the

system.

 If successful, this routine will not return. However, once the execution

continues running to the next instruction, it means the operation of this
routine fails.

On error, it returns 0 to indicate the file does not exist.

See Also

DownLoadProgram, UpdateBank

Chapter

3

Terminal

Specific

Function

Library

39

3.2 Barcode Reader

The barcode decoding routines consist of 3 functions:

InitScanner1() : to initialize the scanner port.

Decode() : to perform decoding.

HaltScanner1() : to stop the scanner port from operating.

3.2.1 Barcode Decoding

To enable barcode decoding capability in the system, the first thing is that the scanner port
must be initialized by calling the InitScanner1() function. After the scanner port is
initialized, the Decode() function can be called in the program loops to perform barcode
decoding.

Below are four global variables related to the barcode decoding routines. These variables
are declared by the system, and therefore, the user program needs not to declare them.

extern unsigned char

ScannerDesTbl[23];

This unsigned character array governs the operation of the Decode() routine.

extern char

CodeBuf[];

This buffer contains the decoded data after successful decoding.

extern char

CodeType;

This character indicates the type of code (symbology) being decoded after successful
decoding.

extern int

CodeLen;

This integer indicates the length of the decoded data after successful decoding.

40 "C" Progra

mming Guide

For Optimus S/R

3.2.2 Code Type

The following list shows the possible values of the CodeType variable.

Symbology CodeType Symbology CodeType

Code 39 65(A) EAN-8 with Addon 2 78(N)

Italian Pharmacode 66(B) EAN-8 with Addon 5 79(O)

CIP 39 67(C) EAN-13 80(P)

Industrial 25 68(D) EAN-13 with Addon 2 81(Q)

Interleave 25 69(E) EAN-13 with Addon 5 82(R)

Matrix 25 70(F) MSI 83(S)

Codabar (NW7) 71(G) Plessey 84(T)

Code 93 72(H) EAN-128 85(U)

Code 128 73(I)

UPCE 74(J) GTIN 87(W)

UPCE with Addon 2 75(K)

UPCE with Addon5 76(L) Telepen 90 (Z)

EAN-8 77(M) RSS14 91 ([)

Cha

pter 3

Terminal

Specific

Function

Library

41

3.2.3 ScannerDescriptionTable Array

The unsigned character array ScannerDesTbl governs the behavior of the Decode() function.
This table describes the details of the ScannerDesTbl variable.

Subscriptor Bit Description

0 7 1: Enable Code 39

0: Disable Code 39

0 6 1: Enable Italian Pharmacode

0: Disable Italian Pharmacode

0 5 1: Enable CIP 39

0: Disable CIP 39

0 4 1: Enable Industrial 25

0: Disable Industrial 25

0 3 1: Enable Interleave 25

0: Disable Interleave 25

0 2 1: Enable Matrix 25

0: Disable Matrix 25

0 1 1: Enable Codabar (NW7)

0: Disable Codabar (NW7)

0 0 1: Enable Code 93

0: Disable Code 93

1 7 1: Enable Code 128

0: Disable Code 128

1 6 1: Enable UPCE

0: Disable UPCE

1 5 1: Enable UPCE Addon 2

0: Disable UPCE Addon 2

1 4 1: Enable UPCE Addon 5

0: Disable UPCE Addon 5

1 3 1: Enable EAN-8

0: Disable EAN-8

1 2 1: Enable EAN-8 Addon 2

0: Disable EAN-8 Addon 2

42 "C" Progra

mming Guide

For Optimus S/R

1 1 1: Enable EAN-8 Addon 5

0: Disable EAN-8 Addon 5

1 0 1: Enable EAN-13

0: Disable EAN-13

2 7 1: Enable EAN-13 Addon 2

0: Disable EAN-13 Addon 2

2 6 1: Enable EAN-13 Addon 5

0: Disable EAN-13 Addon 5

2 5 1: Enable MSI

0: Disable MSI

2 4 1: Enable Plessey

0: Disable Plessey

2 3 Reserved

2 2 1: Enable Telepen

0: Disable Telepen

2 1 1: Enable AIM Telepen (Full ASCII)

0: Enable original Telepen (Numeric)

2 0 1: Enable RSS14 Limited

0: Disable RSS14 Limited

3 7 1: Enable RSS14 Expanded

0: Disable RSS14 Expanded

3 6 1: Enable RSS14

0: Disable RSS14

3 5 1: Transmit RSS14 Code ID

0: DO NOT transmit RSS14 Code ID

3 4 1: Transmit RSS14 Application ID

0: DO NOT transmit RSS14 Application ID

3 3 1: Transmit RSS14 Check Digit

0: DO NOT transmit RSS14 Check Digit

3 2 1: Transmit RSS14 Limited Code ID

0: DO NOT transmit RSS14 Limited Code ID

3 1 1: Transmit RSS14 Limited Application ID

0: DO NOT transmit RSS14 Limited Application ID

3 0 1: Transmit RSS14 Limited Check Digit

0: DO NOT transmit RSS14 Limited Check Digit

Chapter

3

Terminal

Specific

Function

Library

43

4 7 1: Transmit RSS14 Expanded Code ID

0: DO NOT transmit RSS14 Expanded Code ID

4 6 1: Enable UPCE 1

0: Enable UPCE 0 (These are applicable to Optimus S/Optimus R.)

4 5 - 0 Reserved

5 7 1: Transmit Code 39 Start/Stop Character

0: DO NOT transmit Code 39 Start/Stop Character

5 6 1: Verify Code 39 Check Character

0: DO NOT verify Code 39 Check Character

5 5 1: Transmit Code 39 Check Character

0: DO NOT transmit Code 39 Check Character

5 4 1: Full ASCII Code 39

0: Standard Code 39

5 3 1: Transmit Italian Pharmacode Check Character

0: DO NOT transmit Italian Pharmacode Check Character

5 2 1: Transmit CIP 39 Check Character

0: DO NOT transmit CIP 39 Check Character

5 1 1: Verify Interleave 25 Check Digit

0: DO NOT verify Interleave 25 Check Digit

5 0 1: Transmit Interleave 25 Check Digit

0: DO NOT transmit Interleave 2 Check Digit

6 7 1: Verify Industrial 25 Check Digit

0: DO NOT verify Industrial 25 Check Digit

6 6 1: Transmit Industrial 25 Check Digit

0: DO NOT transmit Industrial 25 Check Digit

6 5 1: Verify Matrix 25 Check Digit

0: DO NOT verify Matrix 25 Check Digit

6 4 1: Transmit Matrix 25 Check Digit

0: DO NOT transmit Matrix 25 Check Digit

6 3 - 2 Select Interleave 25 Start/Stop Pattern

00: Use Industrial 25 Start/Stop Pattern

01: Use Interleave 25 Start/Stop Pattern

10: Use Matrix 25 Start/Stop Pattern

11: Undefined

44 "C" Progra

mming Guide

For Optimus S/R

6 1 - 0 Select Industrial 25 Start/Stop Pattern

00: Use Industrial 25 Start/Stop Pattern

01: Use Interleave 25 Start/Stop Pattern

10: Use Matrix 25 Start/Stop Pattern

11: Undefined

7 7 - 6 Select Matrix 25 Start/Stop Pattern

00: Use Industrial 25 Start/Stop Pattern

01: Use Interleave 25 Start/Stop Pattern

10: Use Matrix 25 Start/Stop Pattern

11: Undefined

7 5 - 4 Codabar Start/Stop Character

00: abcd/abcd

01: abcd/tn*e

10: ABCD/ABCD

11: ABCD/TN*E

7 3 1: Transmit Codabar Start/Stop Character

0: DO NOT transmit Codabar Start/Stop Character

7 2 - 0 Reserved

8 7 - 0 Reserved

9 7 - 6 MSI Check Digit Verification

00: Single Modulo 10

01: Double Modulo 10

10: Modulo 11 and Modulo 10

11: Undefined

9 5 - 4 MSI Check Digit Transmission

00: the last Check Digit is not transmitted

01: both Check Digits are transmitted

10: both Check Digits are NOT transmitted

9 3 1: Transmit Plessey Check Characters

0: DO NOT transmit Plessey Check Characters

9 2 1: Convert Standard Plessey to UK Plessey

0: No conversion

9 1 1: Convert UPCE to UPCA

0: No conversion

Chapter

3

Terminal

Specific

Function

Library

45

9 0 1: Convert UPCA to EAN-13

0: No conversion

10 7 1: Enable ISBN Conversion

0: No conversion

10 6 1: Enable ISSN Conversion

0: No conversion

10 5 1: Transmit UPCE Check Digit

0: DO NOT transmit UPCE Check Digit

10 4 1: Transmit UPCA Check Digit

0: DO NOT transmit UPCA Check Digit

10 3 1: Transmit EAN-8 Check Digit

0: DO NOT transmit EAN-8 Check Digit

10 2 1: Transmit EAN-13 Check Digit

0: DO NOT transmit EAN-13 Check Digit

10 1 1: Transmit UPCE System Number

0: DO NOT transmit UPCE System Number

10 0 1: Transmit UPCA System Number

0: DO NOT transmit UPCA System Number

11 7 1: Convert EAN-8 to EAN-13

0: No conversion

11 6 Reserved

11 5 1: Enable GTIN

0: Disable GTIN

11 4 1: Enable Negative Barcode

0: Disable Negative Barcode

11 3 - 2 00: No Read Redundancy for Scanner Port 1

01: One Time Read Redundancy for Scanner Port 1

10: Two Times Read Redundancy for Scanner Port 1

11: Three Times Read Redundancy for Scanner Port 1

11 1 - 0 Reserved

12 7 1: Industrial 25 Code Length Limitation in Max/Min Length Format

0: Industrial 25 Code Length Limitation in Fixed Length Format

12 6 - 0 Industrial 25 Max Code Length / Fixed Length 1

13 7 - 0 Industrial 25 Min Code Length / Fixed Length 2

46 "C" Progra

mming Guide

For Optimus S/R

14 7 1: Interleave 25 Code Length Limitation in Max/Min Length Format

0: Interleave 25 Code Length Limitation in Fixed Length Format

14 6 - 0 Interleave 25 Max Code Length / Fixed Length 1

15 7 - 0 Interleave 25 Min Code Length / Fixed Length 2

16 7 1: Matrix 25 Code Length Limitation in Max/Min Length Format

0: Matrix 25 Code Length Limitation in Fixed Length Format

16 6 - 0 Matrix 25 Max Code Length / Fixed Length 1

17 7 - 0 Matrix 25 Min Code Length / Fixed Length 2

18 7 1: MSI 25 Code Length Limitation in Max/Min Length Format

0: MSI 25 Code Length Limitation in Fixed Length Format

18 6 - 0 MSI Max Code Length / Fixed Length 1

19 7 - 0 MSI Min Code Length / Fixed Length 2

20 7 - 4 Scan Mode for Scanner Port 1

0000: Auto Off Mode

0001: Continuous Mode

0010: Auto Power Off Mode

0011: Alternate Mode

0100: Momentary Mode

0101: Repeat Mode

0110: Laser Mode

0111: Test Mode

1000: Aiming Mode

20 3 - 0 Reserved

21 7 - 0 Scanner Time-out Duration in seconds for Aiming mode, Laser mode,

Auto Off mode, and Auto Power Off mode

22 7 - 0 Reserved

Chapter

3

Terminal

Specific

Function

Library

47

3.2.4 Scan Modes

The barcode reader supports up to 9 scanning modes as described below.

Set the 21st byte of the unsigned character array ScannerDesTbl to define a scan mode that
best suits the requirements of a specific application.

If necessary, set the 22nd byte for timeout duration.

ON OFF Scan Mode

Continuous mode

Test mode

Repeat mode

Momentary mode

Alternate mode

Aiming mode

Laser mode

Auto Off mode

Auto Power Off mode

Always Press

trigger
once













Hold
trigger





Press
trigger
twice



Release
trigger





Press
trigger
once



Barcode
being
read

 

 

 

Timeout



48 "C" Progra

mming Guide

For Optimus S/R

Continuous mode

 The reader is always scanning, but only one decoding is allowed for the same

barcode.

That is, to read (i.e. scan and decode) the same barcode multiple times, the barcode
must be re-approached for new scanning.

 Several modes have been developed based on this mode.

Chapter

3

Terminal

Specific

Function

Library

49

Test mode

 The reader is always scanning for testing purpose.

 Comparing to the Continuous mode, it will decode repeatedly even with the same

barcode without re-approaching.

50 "C" Progra

mming Guide

For Optimus S/R

Repeat mode

This mode is most useful when the same barcode is to be read many times. When
the scan trigger is pressed within one second after a successful reading, the same
data will be re-transmitted without actually reading the barcode. Such
re-transmission can be activated as many times as needed, as long as the time
interval between each triggering does not exceed one second.

 The reader is always scanning.

 It will decode once for the same barcode and allow for re-transmission when

triggering within one second.

Chapter

3

Terminal

Specific

Function

Library

51

Momentary mode

 Hold down the scan trigger to start scanning.

 The scanning continues until the trigger is released.

52 "C" Progra

mming Guide

For Optimus S/R

Alternate mode

 Press the scan trigger to start scanning.

 The scanning continues until the trigger is pressed again.

Chapter

3

Terminal

Specific

Function

Library

53

Aiming mode

This mode best applies when two barcodes are printed too close to each other. It is
necessary to take aim first to make sure the correct barcode will be scanned.

 Press the scan trigger to aim at a barcode. Within one second, press the trigger again

to decode the barcode.

 The scanning continues until one of the events happens:

(1) A barcode is read.

(2) The preset timeout expires.

Note: The system global variable AIMING_TIMEOUT can be used to change the default
one-second timeout interval for aiming. The unit for this variable is 5 ms.

54 "C" Progra

mming Guide

For Optimus S/R

Laser mode

This mode is most often used on laser scanners.

 Hold down the scan trigger to start scanning.

 The scanning continues until one of the events happens:

(1) A barcode is read.

(2) The preset timeout expires.

(3) The trigger is released.

Chapter

3

Terminal

Specific

Function

Library

55

Auto Off mode

This is the default mode.

 The reader will start to scan once the scan trigger is pressed.

 The scanning continues until one of the events happens:

(1) A barcode is read.

(2) The preset timeout expires.

56 "C" Progra

mming Guide

For Optimus S/R

Auto Power Off mode

 The reader will start to scan once the scan trigger is pressed.

 The scanning continues until one of the events happens:

(1) The preset timeout expires.

 Comparing to the Auto Off mode, the reader continues to scan whenever there is a

successful reading of barcode because its timeout period re-counts.

Chapter

3

Terminal

Specific

Function

Library

57

Decode

Purpose

Syntax

Example

Description

Return

See Also

To perform barcode decoding.

int Decode (void);

while (1) { if (Decode()) break;}

Once the scanner port is initialized by calling InitScanner1(), call this routine to
perform barcode decoding.

 This routine should be called constantly in user's program loops when

barcode decoding is required.

 If the barcode decoding is not required for a long period of time, it is

recommended that the scanner port should be stopped by calling
HaltScanner1().

 If the Decode function decodes successfully, the decoded data will be

placed in the string variable CodeBuf[] with a string terminating character
appended. And integer variable CodeLen, as well as the character variable
CodeType will reflect the length and code type of the decoded data
respectively.

If successful, it returns an integer whose value equals to the string length of the
decoded data.

Otherwise, it returns 0.

HaltScanner1, InitScanner1

HaltScanner1

Purpose

Syntax

Example

Description

Return

See Also

InitScanner1

Purpose

Syntax

Example

To stop the scanner port from operating.

void HaltScanner1 (void);

HaltScanner1();

Once the scanner port is stopped from operating by this routine, it cannot be
restarted unless it is initialized again by calling InitScanner1().

It is recommended that the scanner port should be stopped if the barcode
decoding is not required for a long period of time.

None

Decode, InitScanner1

To initialize the scanner port.

void InitScanner1 (void);

InitScanner1();

while (1) {if (Decode()) break;}

58 "C" Progra

mming Guide

For Optimus S/R

Description

Return

See Also

The scanner port will not work unless it is initialized.

None

Decode, HaltScanner1

Chapter

3

Terminal

Specific

Function

Library

59

3.3 Keyboard Wedge Interface

The portables, which are equipped with keyboard wedge interface, are able to send data to
the host through the wedge interface by using the SendData() routine.

SendData() is governed by a 3-element unsigned character string - WedgeSetting, which is a
system-defined global character array and must be filled with appropriate values before
calling SendData().

extern unsigned char

WedgeSetting[3];

This unsigned character array governs the operation of the SendData routine.

3.3.1 Definition of the WedgeSetting Array

Subscriptor Bit Description

0 7 - 0 KBD / Terminal Type

1 7 1: Enable capital lock auto-detection

0: Disable capital lock auto-detection

1 6 1: Capital lock on

0: Capital lock off

1 5 1: Ignore alphabets' case

0: Alphabets are case-sensitive

1 4 - 3 00: Normal

10: Digits at lower position

11: Digits at upper position

1 2 - 1 00: Normal

10: Capital lock keyboard

11: Shift lock keyboard

1 0 1: Use numeric keypad to transmit digits

0: Use alpha-numeric key to transmit digits

2 7 - 0 Inter-character delay

60 "C" Progra

mming Guide

For Optimus S/R

3.3.2 KBD / Terminal Type

The possible value of WedgeSetting[0] is listed as follows. It determines which type of
keyboard wedge is applied.

Setting Value Terminal Type Setting Value Terminal Type

0 Null (Data Not Transmitted) 21 PS55 002-81, 003-81

1 PCAT (US) 22 PS55 002-2, 003-2

2 PCAT (FR) 23 PS55 002-82, 003-82

3 PCAT (GR) 24 PS55 002-3, 003-3

4 PCAT (IT) 25 PS55 002-8A, 003-8A

5 PCAT (SV) 26 IBM 3477 TYPE 4

6 PCAT (NO) 27 PS2-30

7 PCAT (UK) 28 Memorex Telex 122 Keys

8 PCAT (BE) 29 PCXT

9 PCAT (SP) 30 IBM 5550

10 PCAT (PO) 31 NEC 5200

11 PS55 A01-1 32 NEC 9800

12 PS55 A01-2 33 DEC VT220, 320, 420

13 PS55 A01-3 34 Macintosh (ADB)

14 PS55 001-1 35 Hitachi Elles

15 PS55 001-81 36 Wyse Enhance KBD (US)

16 PS55 001-2 37 NEC Astra

17 PS55 001-82 38 Unisys TO-300

18 PS55 001-3 39 Televideo 965

19 PS55 001-8A 40 ADDS 1010

20 PS55 002-1, 003-1

For example, if the terminal type is PCAT (US), then the first element of the WedgeSetting
can be defined as follows,

WedgeSetting[0] = 1

Chapter

3

Terminal

Specific

Function

Library

61

3.3.3 Capital Lock Auto-Detection

When "Capital Lock Auto-Detection" is enabled, the SendData() routine can automatically
detect the capital lock status of keyboard when the keyboard type selected is PCAT (all
available languages), PS2-30, PS55, or Memorex Telex. If this is the case, SendData() will
ignore the capital lock status setting and perform auto-detection when transmitting data.

When "Capital Lock Auto-Detection" is disabled, SendData() will transmit alphabets
according to the setting of the capital lock status.

If the keyboard type selected is not one among PCAT, PS2-30, PS55, and Memorex Telex,
SendData() will transmit the alphabets according to the setting of the capital lock status,
even though the auto-detection setting is enabled.

To enable "Capital Lock Auto-Detection", add 128 to the value of the second element of the

WedgeSetting array.

3.3.4 Capital Lock Status Setting

In order to send alphabets with correct case (upper or lower case), the SendData() routine
must know the capital lock status of keyboard when transmitting data. Incorrect capital lock
setting will result in different letter case (for example, 'A' becomes 'a', and 'a' becomes 'A').

To set "Capital Lock ON", add 64 to the value of the second element of the WedgeSetting
array.

3.3.5 Alphabets Case

The setting of this bit affects the way the SendData() routine transmits alphabets. SendData()
can transmit alphabets according to their original case (case sensitive) or just ignore it. If
ignoring case is selected, SendData() will always transmit alphabets without adding shift
key.

To set "Ignore Alphabets Case", add 32 to the value of the second element of the

WedgeSetting array.

62 "C" Progra

mming Guide

For Optimus S/R

3.3.6 Digits Position

This setting can force the SendData() routine to treat the position of the digit keys on the
keyboard differently. If this setting is set to upper, SendData() will add shift key when
transmitting digits. This setting will be effective only when the keyboard type selected is
PCAT (all available language), PS2-30, PS55, or Memorex Telex. However, if the user
chooses to send digits using numeric keypad, this setting is meaningless.

To set "Lower Position", add 16 to the value of the second element of the WedgeSetting
array. To set "Upper Position", add 24 to the value of the second element of the
WedgeSetting array.

Note: Do not set this setting unless the user is sure about the selection.

3.3.7 Shift / Capital Lock Keyboard

This setting can force the SendData() routine to treat the keyboard type to be a shift lock
keyboard or a capital lock keyboard. This setting will be effective only when the keyboard
type selected is PCAT (all available language), PS2-30, PS55, or Memorex Telex.

To set "Capital Lock", add 4 to the value of the second element of the WedgeSetting array.
To set "Shift Lock", add 6 to the value of the second element of the WedgeSetting array.

Note: Do not set this setting unless the user is sure about the selection.

3.3.8 Digit Transmission

This setting instructs the SendData() routine which group of keys is used to transmit digits,
whether to use the digit keys on top of the alphabet keys or use the digit keys on the numeric
keypad.

To set "Use Numeric Keypad to Transmit Digits", add 2 to the value of the second element of
the WedgeSetting array.

Chapter

3

Terminal

Specific

Function

Library

63

3.3.9 Inter-Character Delay

A millisecond inter-character delay, in the range of 0 to 255, can be added before
transmitting each character. This is used to provide some response time for PC to process
keyboard input. For example, to set the inter-character delay to be 10 millisecond, the third
element of the WedgeSetting array can be defined as,

WedgeSetting[2] = 10

3.3.10 Composition of Output String

The keyboard wedge character mapping is shown below. Each character in the output string
is translated by this table when the SendData() routine transmits data.

00 10 20 30 40 50 60 70 80

0 F2 SP 0 @ P ` p

1 INS F3 ! 1 A Q a q

2 DLT F4 " 2 B R b r

3 Home F5 # 3 C S c s

4 End F6 $ 4 D T d t

5 Up F7 % 5 E U e u

6 Down F8 & 6 F V f v

7 Left F9 ' 7 G W g w

8 BS F10 ( 8 H X h x

9 HT F11 ) 9 I Y i y

A LF F12 * : J Z j z

B Right ESC + ; K [ k {

C PgUp Exec , < L \ l |

D CR CR* - = M ] m }

E PgDn . > N ^ n ~

F F1 / ? O _ o Dly





















Note: (1) Dly: Delay 100 millisecond (2) ~: Digits of numeric keypad
(3) CR*: Enter key on the numeric keypad

64 "C" Progra

mming Guide

For Optimus S/R

The SendData() routine can not only transmit simple characters as above, but also provide a
way to transmit combination key status, or even direct scan codes. This is done by inserting
some special command codes in the output string. A command code is a character whose
value is between 0xC0 and 0xFF.

0xC0 : Indicates that the next character is to be treated as scan code. Transmit it as it is, no
translation required.

0xC0 | 0x01 : Send next character with Shift key.

0xC0 | 0x02 : Send next character with left Ctrl key.

0xC0 | 0x04 : Send next character with left Alt key.

0xC0 | 0x08 : Send next character with right Ctrl key.

0xC0 | 0x10 : Send next character with right Alt key.

0xC0 | 0x20 : Clear all combination status key after sending the next character.

For example, to send [A] [Ctrl-Insert] [5] [scan code 0x29] [Tab] [2] [Shift-Ctrl-A] [B]
[Alt-1] [Alt-2-Break] [Alt-1] [Alt-3], the following characters are inserted into the string
supplied to the SendData() routine.

0x41, 0xC2, 0x01, 0x35, 0xC0, 0x29, 0x09, 0x32, 0xC3, 0x41, 0x42, 0xC4, 0x31
0xE4, 0x32, 0xC4, 0x31, 0xC4, 0x33

Please note that, the scan code 0x29 is actually a space for PCAT, Alt-12 is a form feed
character, and Alt-13 is an Enter. The break after Alt-12 is necessary, if omitted the
characters will be treated as Alt-1213 instead of Alt-12 and Alt-13.

SendData

Purpose

Syntax

Example

Description

Return

See Also

To send a string to the host via keyboard wedge interface.

void SendData (char *out_str);

SendData (CodeBuf);

This routine transmits a string pointed by out_str to the keyboard wedge
interface.

None

WedgeReady

WedgeReady

Purpose

To check if the keyboard wedge is ready to send data.

Chapter

3

Terminal

Specific

Function

Library

65

Syntax

Example

Description

Return

See Also

int WedgeReady (void);

if (WedgeReady())

SendData (CodeBuf);

Before sending data via keyboard wedge, it is recommended to check if the
cable is well connected; otherwise, the transmission may be blocked.

If connection is OK, it returns 1.

Otherwise, it returns 0.

SendData

66 "C" Progra

mming Guide

For Optimus S/R

3.4 Buzzer

This section describes the beeper manipulation routines.

The activation of the beeper is conducted by specifying a beeper sequence, which comprises
a number of beep frequency and beep duration pairs. Once a beeper sequence is specified,
the activation of the beeper is automatically handled by the background operating system.
There is no need for the application program to wait for the beeper to stop.

In addition, there are routines for determining whether a beeper sequence is undergoing, or
a beeper sequence is to be terminated immediately.

3.4.1 Beeper Sequence

A beeper sequence is an integer array that is used to instruct how the beeper is activated. It
comprises a number of pairs of beep frequency and duration. Each pair is one beep. When
the value of the beep duration is set to 0, it means the end of a beeper sequence, i.e. the
beeper will then terminate activation.

3.4.2 Beep Frequency

A beep frequency is an integer that is used to specify the frequency (tone) of the beeper
when it is activated. However, the value specified to the beep frequency is not the actual
frequency that the beeper generates. It is calculated by the following formula:

Beep Frequency = 76000 / Actual Frequency Desired

For example, if a frequency of 4 KHz is desired, the value of beep frequency should be 19.
If no sound is desired (pause), the beep frequency should be set to 0. Note that a beep with
frequency 0 does not terminate the beeper sequence. Suitable frequency range is from 1
KHz to 6 KHz, whereas the peak is at 4 KHz.

Chapter

3

Terminal

Specific

Function

Library

67

3.4.3 Beep Duration

Beep duration is an integer that is used to specify how long a beeper is activated with a
specified beep frequency; it is specified in units of 0.01 second. To set the beeper in
activation for one second, the beep duration should be set to 100.

Note: When the value of beep duration is set to 0, it will terminate the beeper sequence.

beeper_status

Purpose

Syntax

Example

Description

Return

See Also

off_beeper

Purpose

Syntax

Example

Description

Return

See Also

To check if a beeper sequence is undergoing.

int beeper_status (void);

while (beeper_status()); /* wait till a beeper sequence is completed */

This routine checks if there is a beeper sequence in progress.

If beeper sequence is undergoing, it returns 1.

Otherwise, it returns 0.

off_beeper, on_beeper, play

To terminate the beeper sequence.

void off_beeper (void);

off_beeper();

This routine terminates the beeper sequence immediately if there is a beeper
sequence in progress.

None

beeper_status, on_beeper, play

on_beeper

Purpose

Syntax

Example

Description

To specify a beeper sequence of how a beeper is activated.

void on_beeper (int *sequence);

int *sequence; /* pointer to a buffer where a beeper sequence resides */

int two_beeps[ ] = {19, 10, 0, 10, 19, 10, 0, 0};

on_beeper(two_beeps);

This routine specifies a beeper sequence to instruct how a beeper is activated.

68 "C" Progra

mming Guide

For Optimus S/R

play

Return

See Also

Purpose

Syntax

Example

Description

If there is a beeper sequence already in progress, the later will override the
original one.

None

beeper_status, off_beeper, play

To play melody by specifying a sequence of how a beeper is activated.

void play (const char *sequence);

char *sequence; /* pointer to a buffer where a melody sequence resides */

const char song[ ]={0x31,10,0x32,10,0x33,10,0x34,10,

0x35,10,0x36,10,0x37,10,0x41,10,

0x31,4,0x32,4,0x33,4,0x34,4,

0x35,4,0x36,4,0x37,4,0x41,4,0x00,0x00};

play(song);

This routine is similar to on_beeper(). However, the frequency character is
specified as:

Bit 7 6 5 4 3 2 1 0

Return

See Also

Frequency for A (La)

None

beeper_status, off_beeper, on_beeper

Scale

000: Reserved

001(1): 55 Hz

010(2): 110 Hz

011(3): 220 Hz

100(4): 440 Hz

101(5): 880 Hz

110(6): 1760 Hz

111(7): 3520 Hz

# key Musical Scale Reserved

0: disable

1: enable

000: Reserved

001(1): Do

010(2): Re

011(3): Mi

100(4): Fa

101(5): So

110(6): La

111(7): Ti

Chapter

3

Terminal

Specific

Function

Library

69

3.5 Real-time Clock

This section describes the calendar manipulation routines.

The system date and time are maintained by the calendar chip, and they can be retrieved
from or set to the calendar chip by the get_time() and set_time() functions. A backup
rechargeable Lithium battery keeps the calendar chip running even when the power is
turned off.

The calendar chip automatically handles the leap year. The year field set to the calendar
chip must be in four-digit format.

Note: The system time variable sys_msec and sys_sec is maintained by CPU timers and
has nothing to do with this calendar chip.
Accuracy of these two time variables depends on the CPU clock and is not suitable
for precise time manipulation. They are reset to 0 upon powering up.

3.5.1 Calendar

DayOfWeek

get_time

Purpose

Syntax

Example

Description

Return

See Also

Purpose

Syntax

To get the day of the week information.

int DayOfWeek (void);

day = DayOfWeek();

This routine returns the day of the week information based on the current date.

1 ~ 6: Monday to Saturday

7: Sunday

get_time, set_time

To get the current date and time.

void get_time (char *cur_time);

char *cur_time; /* pointer to a buffer where date and time will be copied to */

Example

get_time (system_time);

70 "C" Progra

mming Guide

For Optimus S/R

set_time

Description

Return

See Also

Purpose

Syntax

Example

Description

This routine reads the current date and time from the calendar chip and copies
them to a character array (cur_time).

 The character array cur_time allocated must have a minimum of 15 bytes

to accommodate the date, time, and the string terminator.

 The format of the system date and time is "YYYYMMDDhhmmss".

None

DayOfWeek, set_time

To set new date and time to the calendar chip.

int set_time (char *new_time);

char *new_time;

set_time ("20050805125800"); /* AUGUST 5, 2005 12:58:00 */

This routine sets new date and time (new_time) to the calendar chip.

new_time must have the following format, "YYYYMMDDhhmmss".

YYYY year 4 digits

MM month 2 digits, 01 ~ 12

DD day 2 digits, 01 ~ 31

hh hour 2 digits, 00 ~ 23

mm minute 2 digits, 00 ~ 59

ss second 2 digits, 00 ~ 59

If the format is invalid (e.g. set hour to 25), the operation is simply denied and
the time remains unchanged.

Return

If successful, it returns 1.

Otherwise, it returns 0. (i.e. malfunctioning of calendar chip or wrong format)

See Also

DayOfWeek, get_time

Chapter

3

Terminal

Specific

Function

Library

71

3.5.2 Alarm

These are applicable to the Optimus S only.

GetAlarm Optimus S

Purpose

Syntax

To get the current alarm time.

void GetAlarm (char *cur_time);

char *cur_time; /* pointer a buffer where alarm time will be copied to */

Example

Description

GetAlarm (alarm_time);

This routine reads the current alarm time and copies it to a character array
(cur_time).

 The character array cur_time allocated must have a minimum of 15 bytes

to accommodate the date, time, and the string terminator.

 The format of the system date and time is "YYYYMMDDhhmmss".

Return

See Also

None

SetAlarm

SetAlarm Optimus S

Purpose

Syntax

Example

To set the alarm time.

void SetAlarm (char *new_time);

char *new_time;

SetAlarm ("20050805125800"); /* AUGUST 5, 2005 12:58:00 */

Description

Return

See Also

This routine sets alarm time (new_time). The character string new_time must
have the following format, "YYYYMMDDhhmmss".

YYYY: year 4 digits

MM: month 2 digits, 01 ~ 12

DD: day 2 digits, 01 ~ 31

hh: hour 2 digits, 00 ~ 23

mm: minute 2 digits, 00 ~ 59

ss: second 2 digits, 00 ~ 59

If the format is invalid (e.g. set hour to 25), the operation is simply denied and
the time remains unchanged.

None

GetAlarm

72 "C" Progra

mming Guide

For Optimus S/R

Flash, turn on and then off for (duration *0.01) seconds.

3.6 LED

In general, the dual-color LED indicator on the portable terminals is used to indicate the
system status, such as good read or bad read, error occurrence, etc.

set_led

Purpose

Syntax

Example

Description

Return

To set the LED indicator.

void set_led (int led, int mode, int duration);

int led; /* color of LED to be accessed */

int mode; /* activation mode */

int duration; /* duration in units of 10 milli-second. */

set_led (LED_RED,LED_FLASH,50);

/* set red LED to flash for each 1 second cycle */

This routine sets the LED operation mode.

The value of the parameter led can be one of the following:

LED_RED (0) Use red led light

LED_GREEN (1) Use green led light

The value of the parameter mode can be one of the following:

LED_OFF (0) Off for (duration * 0.01) seconds and then on

LED_ON (1) On for (duration * 0.01) seconds and then off

LED_FLASH (2)

None

Then repeat.

Chapter

3

Terminal

Specific

Function

Library

73

3.7 Keypad

A scanning circuitry of 4 by 8 matrix is utilized on the keypad of the portable terminals.

The background routine constantly scans the keypad to check if any key is being pressed.
There is a keyboard buffer of size 32 bytes. However, if the buffer is full, the keystrokes
followed will be ignored. Normally, a C program needs constantly to check if any keystroke
is available in the buffer.

3.7.1 General

CheckKey

Purpose

Syntax

Example

Description

To detect if the specified keys have been pressed simultaneously or not.

int CheckKey (const int scan_code,...);

Specify the scan codes of the keys as many as you like, but be sure to specify
the type as the last parameter. There are two types:

CHK_EXC (-1) /* exclusive checking, only the keys being pressed match

the keys specified will the function return 1 */

CHK_INC (-2) /* inclusive checking, as long as the keys being pressed

include the keys specified, this function will return 1 */

while (1)

{

if (CheckKey(SC_1, SC_2, SC_3, CHK_EXC))

printf ("The user presses 1, 2, 3 simultaneously");

OSTimeDly (8); // delay 8x5 = 40 ms

}

This routine scans the keypad to check if the specified keys are being pressed
or not. Usually, this is used to detect special key combinations for a special
purpose.

Note that it may need up to 40 ms for the system to scan the whole keypad,
therefore, two consecutive calls should not be made within 40 ms. If you are
not sure how long it may take to run your code between two calls, you may call
the OSTimeDly routine to ensure the delay is enough.

74 "C" Progra

mming Guide

For Optimus S/R

clr_kb

getchar

Return

See Also

Purpose

Syntax

Example

Description

Return

See Also

Purpose

If successful, it returns 1.

Otherwise, it returns 0.

OSTimeDly

To clear the keyboard buffer.

void clr_kb (void);

clr_kb();

This routine is automatically called by the system upon powering up the
terminal.

None

getchar, kbhit

To read one character from the keyboard buffer and then remove it.

Syntax

Example

Description

Return

See Also

GetKeyClick

Purpose

Syntax

Example

Description

Return

int getchar (void);

c = getchar();

if (c > 0) printf ("Key %d pressed",c);

else printf ("No key pressed");

This routine can be used with menu operation to detect a shortcut key being
pressed.

If successful, it returns the character read from the keyboard buffer.

Otherwise, it returns 0 to indicate the keyboard buffer is already empty.

clr_kb, kbhit

To get the current setting of key click.

int GetKeyClick (void);

state = GetKeyClick();

The key click is set to be enabled by default, but it can be changed from the
System Menu or through programming.

If key click is enabled, it returns 1~5 to indicate different tones.

Otherwise, it returns 0.

See Also

SetKeyClick

Chapter

3

Terminal

Specific

Function

Library

75

kbhit

Purpose

Syntax

Example

Description

Return

See Also

SetKeyClick

Purpose

Syntax

Example

Description

To check if there is any key being pressed.

int kbhit (void);

for (;!kbhit();); /* wait till a key is pressed */

This routine checks if there is any character waiting in the keyboard buffer for
being read out.

If any key is pressed, it returns 1 to indicate a character is put in the buffer.

Otherwise, it returns 0 to indicate the buffer is empty.

clr_kb, getchar

To set key click.

void SetKeyClick (int status);

int status; /* 0: disable key click, 1(~5): enable key click */

SetKeyClick (1); /* enable key click sound */

There are five different tones available. You can choose a tone from the System
Menu or through programming.

Moreover, the frequency and duration pair of the key click is held in the system
global variable KEY_CLICK, which can be used to generate the key click
sound. Example: on_beeper(KEY_CLICK);

Return

See Also

TriggerStatus

Purpose

Syntax

Example

Description

Return

See Also

None

GetKeyClick

To check if the scan key has been pressed.

int TriggerStatus (void);

if (TriggerStatus())

printf ("Scan key is pressed");

This routine is used to check if the scan key has been pressed or not.

If the scan key is pressed, it returns 1.

Otherwise, it returns 0.

dis_alpha, en_alpha, get_alpha_enable_state, get_alpha_lock_state

76 "C" Progra

mming Guide

For Optimus S/R

3.7.2 ALPHA Key

dis_alpha

Purpose

To disable the ALPHA (α) key.

Syntax

Example

Description

Return

See Also

en_alpha

Purpose

Syntax

Example

Description

void dis_alpha (void);

dis_alpha();

This routine disables the ALPHA (α) key and sets the input mode to numeric
only. The same result can be obtained from LockAlphaState(0).

None

en_alpha, get_alpha_enable_state, LockAlphaState

To enable or unlock the ALPHA (α) key.

void en_alpha (int type); // Optimus S, Optimus R

int type; // key rolling type

en_alpha();

By default, the input mode is numeric and can be modified by the ALPHA (α)
key.

 If the ALPHA key is disabled by dis_alpha(), this routine is used to enable

it.

 If the ALPHA key is locked by LockAlphaState(), this routine is used to

unlock it.

 For the Optimus S and 24-key Optimus R, the type of behaviour should be

specified ALPHA_ROLLING.

 For the 39-key Optimus R, there are two types of behaviors:

ALPHA_FIXED (1) It shows only one character when pressing one key.

The character displayed depends on the current
input mode.

ALPHA_ROLLING (2) It takes turns to show alphabet and numeric when

pressing the same key. For example, the "2ABC"
key can generate "2", "A", "B" and "C" by turns.



Return

See Also

None

dis_alpha, get_alpha_enable_state, LockAlphaState

Chapter

3

Terminal

Specific

Function

Library

77

get_alpha_enable_state

Purpose

To get the state of the ALPHA (α) key.

Syntax

Example

Description

Return

See Also

get_alpha_lock_state

Purpose

Syntax

Example

int get_alpha_enable_state (void);

state = get_alpha_enable_state();

By default, the ALPHA (α) key is enabled.

The return value can be one of the following:

0 The ALPHA key is disabled, resulting from dis_alpha() and

LockAlphaState().

1 The ALPHA key is enabled and the keypad behavior is set to

ALPHA_FIXED, resulting from en_alpha().

2 The ALPHA key is enabled and the keypad behavior is set to

ALPHA_ROLLING, resulting from en_alpha().

dis_alpha, en_alpha, LockAlphaState

To get information of the ALPHA (α) state for input mode, either locked or
unlocked.

int get_alpha_lock_state (void);

state = get_alpha_lock_state();

Description

Return

See Also

LockAlphaState

Purpose

Syntax

Example

This routine gets the current state of input mode, resulting from either
LockAlphaState() or set_alpha_lock().

The return value can be one of the following:

0 Numeric mode

1 Upper case alpha mode

2 Lower case alpha mode

3 Function mode (Optimus S only)

LockAlphaState, set_alpha_lock

To set the ALPHA (α) state for input mode and lock (= disable) the ALPHA
(α) key.

void LockAlphaState (int state);

int state; /* input mode that cannot be modified by ALPHA key */

LockAlphaState (2); /* lower case alpha mode, ALPHA key disabled */

78 "C" Progra

mming Guide

For Optimus S/R

Description

Return

See Also

set_alpha_lock

Purpose

Syntax

Example

This routine specifies the input mode, which cannot be modified by the
ALPHA (α) key.

The value of the parameter state can be one of the following:

NUMERIC_KAYPAD (0) Locked to numeric mode

UPPER_CASE (1) Locked to upper case alpha mode

LOWER_CASE (2) Locked to lower case alpha mode

FUNCTION_KEY (3) Locked to function mode (Optimus S only)

None

dis_alpha, en_alpha, get_alpha_enable_state, get_alpha_lock_state,
set_alpha_lock

To set the ALPHA (α) state for input mode.

void set_alpha_lock (int state);

int state; /* input mode that can be modified by ALPHA key*/

set_alpha_lock (1); /* upper case alpha mode, ALPHA key enabled */

Description

Return

See Also

This routine sets the input mode, which can be modified by the ALPHA (α)
key. If the ALPHA key is disabled by dis_alpha() or locked by
LockAlphaState(), use en_alpha() to enable (=unlock) it.

The value of the parameter state can be one of the following:

0 Numeric mode, unlocked

1 Upper case alpha mode, unlocked

2 Lower case alpha mode, unlocked

3 Function mode, unlocked (Optimus S only)

None

dis_alpha, en_alpha, get_alpha_enable_state, get_alpha_lock_state,
LockAlphaState

Chapter

3

Terminal

Specific

Function

Library

79

3.7.3 FN Key

These are applicable to the Optimus R only.

GetFuncToggle Optimus R

Purpose

Syntax

Example

Description

Return

See Also

To get information of the FN key state.

int GetFuncToggle (void);

state = GetFuncToggle();

This routine gets the current state of the FN (function) key.

The return value can be 0 ~ 3.

SetFuncToggle

SetFuncToggle Optimus R

Purpose

Syntax

Example

Description

To set the state of the FN (function) key.

void SetFuncToggle (int state);

int state: /* FN key state */

SetFuncToggle (0) /* set the FN key unlocked */

This routine sets the current state of the FN key. It is set to be "unlocked" by
default.

The value of the parameter state can be one of the following:

0 Unlocked (default)

Return

See Also

1 Locked

None

GetFuncToggle

80 "C" Progra

mming Guide

For Optimus S/R

3.8 LCD

The liquid crystal display (LCD) on the portable terminals is FSTN graphic display. For
different models, it varies slightly in the display capability due to the size of LCD panel.

Model Optimus S Optimus R

Display Capability

3.8.1 Properties

DecContrast

100 x 64 dots 128 x 64 dots

Purpose

Syntax

Example

Description

To decrease the LCD contrast.

void DecContrast (void);

DecContrast();

This routine decreases the LCD contrast by one level each time it is called, and
the minimum value is 0.

Return

See Also

None

GetContrast, IncContrast, SetContrast

GetContrast

Purpose

Syntax

Example

Description

Return

See Also

To get the contrast level of the LCD.

int GetContrast (void);

int nContrastLevel = GetContrast();

This routine indicates the current contrast level of the LCD.

It returns the current contrast level, ranging from 0 to 7.

DecContrast, IncContrast, SetContrast

GetVideoMode

Purpose

Syntax

To get the display mode of the LCD.

int GetVideoMode (void);

Chapter

3

Terminal

Specific

Function

Library

81

Example

Description

Return

if (GetVideoMode() == VIDEO_NORMAL) puts ("Normal Mode");

This routine indicates the current display mode of the LCD.

The return value can be one of the following, depending on the display mode:

VIDEO_NORMAL (0) : Normal mode in use

VIDEO_REVERSE (1) : Reverse mode in use

See Also

SetVideoMode

IncContrast

Purpose

Syntax

Example

Description

Return

See Also

To increase the LCD contrast.

void IncContrast (void);

IncContrast();

This routine increases the LCD contrast by one level each time it is called, and
the maximum value is 7.

None

DecContrast, GetContrast, SetContrast

lcd_backlit

Purpose

Syntax

Example

Description

Return

See Also

To set the LCD backlight.

void lcd_backlit (int state);

int state; /* LCD backlight state */

lcd_backlit (1); /* turn on LCD backlight, low density */

This routine toggles the LCD backlight depending on the value of state.

 The value of the parameter state can be one of the following:

BKLIT_OFF (0) : Backlight off

BKLIT_LO (1) : Backlight on

 The system global variable BKLIT_TIMEOUT can be used to specify the

backlight duration in units of second. However, if the value of
BKLIT_TIMEOUT is zero, it means that the backlight will be on until it is
either turned off manually or its state is set to BKLIT_OFF.

None

BKLIT_TIMEOUT

82 "C" Progra

mming Guide

For Optimus S/R

/* set reverse video mode */

SetContrast

Purpose

Syntax

Example

Description

Return

See Also

SetVideoMode

Purpose

Syntax

Example

Description

To set the contrast level of the LCD.

void SetContrast (int level);

SetContrast (4);

This routine specifies the contrast level of the LCD, and the valid value ranges
from 0 (low) to 7 (high).

None

DecContrast, GetContrast, IncContrast

To set the display mode of the LCD.

void SetVideoMode (int mode);

int mode; /* video mode, reverse or normal */

SetVideoMode (VIDEO_REVERSE);

This routine determines the display mode of the LCD.

The value of the parameter mode can be one of the following:

VIDEO_NORMAL (0) : Normal mode in use

Return

See Also

VIDEO_REVERSE (1) : Reverse mode in use

None

GetVideoMode

Chapter

3

Terminal

Specific

Function

Library

83

3.8.2 Cursor

A coordinate system is used for the cursor movement routines to determine the cursor
location. The coordinates given to the top left point is (0, 0), while those of the bottom right
point depend on the varying size of both screen and font.

Model Optimus S Optimus R

Top_Left

(0, 0) (0, 0)

Bottom_Right

GetCursor

Purpose

Syntax

Example

Description

Return

See Also

gotoxy

Purpose

Syntax

(99, 63) (127, 63)

To get the current cursor status.

int GetCursor (void);

if (GetCursor() == 0) puts ("Cursor Off");

This routine checks the cursor indication on the LCD, i.e. whether it is visible
(On) or not (Off).

If visible, it returns 1.

Otherwise, it returns 0.

SetCursor

To move the cursor to a new position.

void gotoxy (int x_position, int y_position);

Example

Description

Return

See Also

SetCursor

Purpose

int x_position; /* x coordinate of the new cursor position desired */

int y_position; /* y coordinate of the new cursor position desired */

gotoxy (10, 0) /* move the cursor to the 11th column of the first line */

This routine moves the cursor to a new position whose coordinates are
specified in the argument x_position and y_position.

None

wherexy

To turn on/off the cursor indication on the LCD.

84 "C" Progra

mming Guide

For Optimus S/R

Syntax

Example

Description

Return

See Also

wherex

Purpose

Syntax

Example

Description

Return

void SetCursor (int cursor);

int cursor; /* state of cursor indication */

SetCursor (0); /* turn off the cursor indication */

This routine displays or hides the cursor on the LCD according to the value
specified. The value of the parameter status can be one of the following:

CURSOR_OFF (0) : Hide cursor (Off)

CURSOR_ON (1) : Display cursor (On)

None

GetCursor

To get the x coordinate of the current cursor position.

int wherex (void);

x_position = wherex();

This routine retrieves the x coordinate of the current cursor position.

It returns the x coordinate.

See Also

wherexy

Purpose

Syntax

Example

Description

Return

See Also

wherey

Purpose

wherexy, wherey

To get the x coordinate and y coordinate of the current cursor position.

void wherexy (int *column, int *row);

int *column; /* pointer to integer where x coordinate is stored */

int *row; /* pointer to integer where y coordinate is stored */

wherexy (&x_position, &y_position);

This routine copies the values of the x coordinate and y coordinate of the
current cursor position to the variables whose address is specified in the
arguments column and row.

None

gotoxy, wherex, wherey

To get the y coordinate of the current cursor position.

Syntax

Example

int wherey (void);

y_position = wherey();

Chapter

3

Terminal

Specific

Function

Library

85

Description

Return

See Also

This routine retrieves the y coordinate of the current cursor position.

It returns the y coordinate.

wherex, wherexy

86 "C" Progra

mming Guide

For Optimus S/R

3.8.3 Display

fill_rect

Purpose

Syntax

Example

Description

Return

See Also

ICON_ZONE

Purpose

Syntax

To fill a rectangular area on the LCD.

void fill_rect (int left, int top, int width, int height);

int left; /* x coordinate of the upper left corner of the rectangle */

int top; /* y coordinate of the upper left corner of the rectangle */

int width; /* width of the rectangle to be filled, in dots */

int height; /* height of the rectangle to be filled, in dots */

fill_rect (12, 8, 40, 8);

This routine fills a rectangular area on the LCD whose top left position and size
are specified by left, top, width, and height. The cursor position is not affected
after the operation.

None

clr_rect

To enable or disable the printing of characters in the icon area.

void ICON_ZONE (int mode);

int mode; /* 1 for printing enabled; 0 for printing disabled (default) */

Example

Description

ICON_ZONE (1);

The icon zone refers to an area on the LCD that is reserved for showing status
icon, such as the battery icon, alpha icon, etc. By default, the icon zone cannot
show characters and is accessed by graphic commands only.

The value of the parameter mode can be one of the following:

ICON_ZONE_DISABLE (0) : Show status icons by default

ICON_ZONE_ENABLE (1) : Show characters

 Display of 128x64 dots (Optimus R)

The icon zone occupies the right-most 8x64 dots. When ICON_ZONE is
enabled, the display can show up to 8 lines * 21 characters for 6x8 font, or 4
lines * 16 characters for 8x16 font.

 Display of 100x64 dots (Optimus S)

The icon zone occupies the right-most 4x64 dots. Yet, 4 pixels' width
cannot hold one character. Therefore, even when ICON_ZONE is enabled,
the display remains to show up to 8 lines * 16 characters for 6x8 font, or 4
lines * 12 characters for 8x16 font.

Chapter

3

Terminal

Specific

Function

Library

87

Return

printf

Purpose

Syntax

Example

Description

For any of the above displays, when ICON_ZONE is enabled, the entire screen
will be erased after calling clr_scr().

Note that the system may still show the status icons in this icon area, even
though ICON_ZONE is enabled. This is because these status icons are
constantly maintained by the system, and they may override the printing of
characters from time to time.

None

To write character strings and values of C variables in a specified format to the
LCD.

int printf (char *format, var...);

char *format; /* character string that describes the format to be used */

var...; /* any variable whose value is being printed on the LCD */

pritnf ("ID: %s", id_buffer);

This routine accepts any variable and prints its value to the LCD. The value of
each variable is formatted according to the codes embedded in the format
specification format.

To print values of C variables, a format specification must be embedded in
format for each variable to be printed. The format specification for each
variable has the following form:

%[flags][width].[precision][size][type]

Field Explanation

% (required) Indicates the beginning of a format specification. Use

%% to print a percentage sign.

flags (optional) One of more of the '-', '+', '#' characters or a blank space

specifies justification, and the appearance of plus/minus
signs in the values printed (see below).

width (optional) A number that indicates how many characters, at

maximum, must be used to print the value.

precision (optional) A number that indicates how many characters, at

maximum, can be used to print the value.

When printing integer variables, this is the minimum
number of digits used.

size (optional) A character that modifies the type field which comes

next. One of the characters 'h', 'l', and 'L' can appear in
this field to differentiate between short and long
integers. 'h' is for short integers, and 'l' or 'L' for long
integers.

88 "C" Progra

mming Guide

For Optimus S/R

type (required) A letter that indicates the type of variable being printed

(see below).

Flags Meaning

- Left justify output value. The default is right justification.

+ If the output value is a numerical one, print a '+' or '-' character

according to the sign of the value. A '-' character is always printed
for a negative value no matter this flag is specified or not.

blank Positive numerical values are prefixed with blank spaces. This flag

is ignored if the + flag also appears.

# When used in printing variables of type o, x, or X (see below),

non-zero output values are prefixed with 0, 0x, or 0X respectively.

Type Expected Input

c

Single character

Return

putchar

Purpose

Syntax

Example

Description

d

i

o

u

x

X

s

Signed decimal integer

Signed decimal integer

Octal digits without sign

Unsigned decimal integer

Hexadecimal digits using lower case letter

Hexadecimal digits using upper case letter

A null terminated character string

It returns the character count that sent to the LCD.

To display a character on the LCD.

int putchar (int c);

int c; /* character being sent to the LCD */

putchar ('A');

This routine sends a character specified in the argument c to the LCD at the
current cursor position. The cursor is moved accordingly.

Return

See Also

It always returns 1.

puts

Chapter

3

Terminal

Specific

Function

Library

89

puts

Purpose

Syntax

To display a string on the LCD.

int puts (char *string);

char* string; /* string being sent to the LCD */

Example

Description

puts ("Password : ");

This routine sends a string, whose address is specified in the argument string,
to the LCD at the current cursor position. The cursor is moved accordingly as
each character of string is sent to the LCD. The operation continues until a
terminating null character is encountered.

Return

See Also

It returns the character count of the string.

putchar

WaitHourglass

Purpose

Syntax

To show a moving hourglass on the LCD.

void WaitHourglass (int UppLeftX, int UppLeftY, int type);

int UppLeftX; /* x coordinate of the upper left corner of the hourglass */

int UppLeftY; /* y coordinate of the upper left corner of the hourglass */

int type; /* type (size) of the hourglass */

Example

Description

Return

while (IsRunning)

{...

WaitHourglass(68, 68, HOURGLASS_24x23);

/* show the 24x23 hourglass during the loop */

...}

This routine has to be called constantly to maintain its functionality.

The value of the parameter type can be one of the following:

HOURGLASS_24x23 (1) 24X23 pixels

HOURGLASS_8x8 (2) 8x8 pixels

 Five different patterns of an hourglass type take turns to show on the LCD

by a certain interval to symbolize the passage of time.

 The time factor is decided by programming but never less than two

seconds.

None

90 "C" Progra

mming Guide

For Optimus S/R

3.8.4 Clear

clr_eol

Purpose

Syntax

Example

Description

Return

See Also

clr_icon

Purpose

Syntax

Example

Description

To clear from where the cursor is to the end of the line.

void clr_eol (void);

clr_eol();

This routine clears from where the cursor is to the end of the line, and then
moves the cursor to its original position.

None

clr_scr

To clear the icon zone on the LCD.

void clr_icon (void);

clr_icon();

The icon zone is an unprintable area reserved for showing some status icons,
such as the battery icon, antenna, system time, etc. Programmers can show
custom icons in this area by using the show_image function.

When calling clr_scr() to clear the screen, this icon zone won't be cleared.
Therefore, if you need to erase the icon zone, you have to call clr_icon().

Return

See Also

clr_rect

Purpose

Syntax

Example

Description

None

clr_scr

To clear a rectangular area on the LCD.

void clr_rect (int left, int top, int width, int height);

int left; /* x coordinate of the upper left corner of the rectangle */

int top; /* y coordinate of the upper left corner of the rectangle */

int width; /* width of the rectangle to be cleared, in dots */

int height; /* height of the rectangle to be cleared, in dots */

clr_rect (12, 8, 40, 8);

This routine clears a rectangular area on the LCD whose top left position and
size are specified by left, top, width, and height.

Chapter

3

Terminal

Specific

Function

Library

91

Return

See Also

clr_scr

Purpose

Syntax

Example

Description

Return

See Also

The cursor position is not affected after the operation.

None

fill_rect

To clear everything on the LCD.

void clr_scr (void);

clr_scr();

This routine clears contents of the current screen and places the cursor at the
first column of the first line, i.e. (0, 0).

None

clr_eol, clr_icon, clr_rect

92 "C" Progra

mming Guide

For Optimus S/R

3.8.5 Image

The show_image() function can be used to display images on the LCD. The user needs to
allocate an unsigned char array to store the bitmap data of the image. This array begins with
the top row of pixels. Each row begins with the left-most pixels. Each bit of the bitmap
represents a single pixel of the image. If the bit is set to 1, the pixel is marked, and if it is 0,
the pixel is unmarked. The 1st pixel in each row is represented by the least significant bit of
the 1st byte in each row. If the image is wider than 8 pixels, the 9th pixel in each row is
represented by the least significant bit of the 2nd byte in each row.

get_image

Purpose

Syntax

Example

Description

Return

See Also

show_image

Purpose

Syntax

To read a bitmap pattern from a rectangular area on the LCD.

void get_image (int left, int top, int width, int height, unsigned char *pat);

int left; /* x coordinate of the upper left corner of the rectangle */

int top; /* y coordinate of the upper left corner of the rectangle */

int width; /* width of the rectangle, in dots */

int height; /* height of the rectangle, in dots */

unsigned char *pat; /* pointer to a buffer where bitmap data will be copied to */

get_image (12, 32, 60, 16, buf);

This routine copies the bitmap pattern of a rectangular area on the LCD (whose
top left position and size are specified by left, top, width, and height) to a buffer
(pat). The cursor position is not affected after the operation.

None

show_image

To put a bitmap pattern to a rectangular area on the LCD.

void show_image (int left, int top, int width, int height, unsigned char *pat);

int left; /* x coordinate of the upper left corner of the rectangle */

int top; /* y coordinate of the upper left corner of the rectangle */

int width; /* width of the rectangle, in dots */

int height; /* height of the rectangle, in dots */

unsigned char *pat;

/* pointer to a buffer where bitmap data is kept for displaying on the LCD */

Example

show_image (35, 5, 52, 24, Company_logo[]);

Chapter

3

Terminal

Specific

Function

Library

93

Description

Return

See Also

This routine displays the bitmap pattern from a buffer (pat) to a rectangular
area on the LCD (whose top left position and size are specified by left, top,
width, and height). The cursor position is not affected after the operation.

None

get_image

94 "C" Progra

mming Guide

For Optimus S/R

3.9 Fonts

3.9.1 Font Size

Basically, the portable terminals provide two size options for the system font: 6x8 and 8x16.
The LCD will show 6x8 alphanumeric characters by default.

These options are also applicable to other alphanumerical font files (for single byte
languages), such as the multi-language font file and Hebrew/Nordic/Polish/Russian font
files.

In addition to the system font, the terminals support a number of font files as shown below.
Available font size options depend on which font file is downloaded to the terminal.

Single-byte

Double-byte

Font Files Custom Font Size SetFont Options

System font (default) N/A FONT_6X8, FONT_8X16

Multi-language font file N/A FONT_6X8, FONT_8X16

Others: He, Nd, Po, Ru N/A FONT_6X8, FONT_8X16

Tc, Sc, Jp, Kr 16X16 FONT_6X8, FONT_8X16

Tc12, Sc12, Jp12 12X12 FONT_6X12, FONT_12X12

3.9.2 Display Capability

Varying by the display size and the font size of alphanumerics, the display capability can be
viewed by lines and characters as follows.

Model Alphanumerical Font Display Capability

Optimus R

Size in dots Characters Lines Icon Area

6x8 20 per line 8 Last column (8x64)

8x16 15 per line 4 Last column (8x64)

Optimus S

6x8 16 per line 8 Last column (4x64)

8x16 12 per line 4 Last column (4x64)