Page 1 Optimus S Optimus R "C" Programming Guide Version 3.04.02 Printed on 20 March, 2006...
Page 2 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.
Page 3: Table Of Contents
Contents Copyright Notice CHAPTER 1: Introduction Revision History ............................1 CHAPTER 2: Development Environment 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...
Page 4 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...
Page 5 Contents 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 4.1 Input & Output: <stdio.h> ........................220 4.2 Character Class Tests: <ctype.h>......................221 4.3 String Functions: <string.h>...
Page 7: Chapter 1: Introduction
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”...
Page 8 "C" Programming Guide For Optimus S/R...
Page 9: Chapter 2: Development Environment
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, . The purposes and BIN, ETC, INCLUDE, LIB, README USER contents of each directory are listed below.
Page 10: Bin
"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...
Page 11: Readme
PCs. However, if it does not work on your PC, the program can be used to identify the problem. If you encounter problems in using the PMINFO compiler, run the . Then print all messages and contact Metrologic Instruments PMINFO Inc. 2.3 Development Flow...
Page 12 "C" Programming Guide For Optimus S/R The flow is illustrated as shown below.
Page 13: Create Your Own C Source Program
Chapter 2 Development Environment 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 " " as the file extension and create them under the USER directory, and then use the USER directory as the working directory.
Page 14: Link
"C" Programming Guide For Optimus S/R 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 "...
Page 15 Chapter 2 Development Environment ..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;...
Page 16 "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 */...
Page 17 Chapter 2 Development Environment 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);...
Page 18: Format Conversion
"C" Programming Guide For Optimus S/R 2.3.4 Format Conversion The absolute object file created by is in TOSHIBA's own format. Before being TULINK downloaded to the target machine, it must be converted to the Motorola S format by using the "...
Page 19: Size Of Types
Chapter 2 Development Environment 2.4.1 Size of Types Types Size in byte char, unsigned char short int, unsigned short int, int, unsigned int long int, unsigned long int pointer structure, union 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>...
Page 20: Floating Types
"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 double long double 2.4.4 Alignment Alignment of different types can be adjusted. This is to facilitate CPU performance by trading off memory space.
Page 21: Extended Reserved Words
Chapter 2 Development Environment 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...
Page 22 "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.
Page 23 Chapter 2 Development Environment Different types (signed/unsigned) Different types (same size)
Page 24 "C" Programming Guide For Optimus S/R...
Page 25: Chapter 3: Terminal Specific Function Library
H A P T E R 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.
Page 26: System
"C" Programming Guide For Optimus S/R 3.1 System 3.1.1 General ChangeSpeed Purpose To change the CPU running speed. Syntax void ChangeSpeed (int speed); Example ChangeSpeed (4); When high speed operation is not necessary, selecting slower CPU speed can Description save battery power. The parameter speed is set to one of the following values:...
Page 27 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 To set the POWER key as the wakeup event. Syntax void SetPwrKey (int mode);...
Page 28 "C" Programming Guide For Optimus S/R system_restart Purpose To restart the system. Syntax void system_restart (void); Example system_restart(); This routine simply jumps to the Power On Reset point and restarts the system. Description Return None...
Page 29: Power On Reset (Por)
Chapter 3 Terminal Specific Function Library 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 : all disabled Reader ports : all disabled Keypad scanning : enabled : initialized and cleared to blank, cursor is on and set to the upper-left corner...
Page 30: System Global Variables
"C" Programming Guide For Optimus S/R 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;...
Page 31 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.
Page 32 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...
Page 33: System Information
Chapter 3 Terminal Specific Function Library 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().
Page 34 "C" Programming Guide For Optimus S/R Digits Types Reader Module Wireless Module Reserved Reserved Optimus S a=0, 1, 2 b=0, 5 Optimus R a=0, 1, 2 b=0, 4, 5 Device Type Meaning 0xxx No reader 1xxx CCD reader 2xxx Laser reader...
Page 35 Chapter 3 Terminal Specific Function Library 0x04 MODE_802DOT11 (Optimus R) 0x05 MODE_BLUETOOTH (Optimus S, Optimus R) Return The return value is model-dependent. See Also DeviceType, FontVersion, HardwareVersion, KernelVersion, KeypadLayout, LibraryVersion, ManufactureDate, NetVersion, OriginalSerialNumber, SerialNumber HardwareVersion Purpose To get version information of hardware.
Page 36 "C" Programming Guide For Optimus S/R Optimus R 24-key or 39-key Return For the Optimus S, it always returns 0. For the Optimus R, it returns 0 for 24-key or 1 for 39-key. DeviceType, FontVersion, GetRFmode, HardwareVersion, KernelVersion, See Also...
Page 37 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, lib_opr.lib opr_wlan.lib...
Page 38: Security
"C" Programming 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.
Page 39 Chapter 3 Terminal Specific Function Library Syntax int InputPassword (char *psw); Example char szPsw [10]; printf ("Input password:"); if (InputPassword (szPsw)) if (!CheckSysPassword (szPsw)) printf ("Illegal password!"); Description 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.
Page 40: Program Manager
"C" Programming 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().
Page 41 Chapter 3 Terminal Specific Function Library Description 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 CLEAR_FILE_SYSTEM 1 The original program resided in the active area will then be replaced by the...
Page 42 "C" Programming Guide For Optimus S/R LoadProgram Purpose To download a user program (.SHX) to flash memory. Syntax void LoadProgram (int Prog); int Prog; /* 1 ~ 6, represents one of the 6 resident locations */ LoadProgram (3); /* load the user program to location #3 */...
Page 43 Chapter 3 Terminal Specific Function Library Description 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. Return None See Also ActivateProgram, LoadProgram, ProgramInfo UpdateBank Purpose...
Page 44 "C" Programming Guide For Optimus S/R KEEP_FILE_SYSTEM 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.
Page 45: Barcode Reader
Chapter 3 Terminal Specific Function Library 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.
Page 46: Code Type
"C" Programming 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)
Page 47: Scannerdescriptiontable Array
Chapter 3 Terminal Specific Function Library 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 Description 1: Enable Code 39 0: Disable Code 39 1: Enable Italian Pharmacode 0: Disable Italian Pharmacode 1: Enable CIP 39...
Page 48 "C" Programming Guide For Optimus S/R 1: Enable EAN-8 Addon 5 0: Disable EAN-8 Addon 5 1: Enable EAN-13 0: Disable EAN-13 1: Enable EAN-13 Addon 2 0: Disable EAN-13 Addon 2 1: Enable EAN-13 Addon 5 0: Disable EAN-13 Addon 5...
Page 49 1: Transmit RSS14 Expanded Code ID 0: DO NOT transmit RSS14 Expanded Code ID 1: Enable UPCE 1 0: Enable UPCE 0 (These are applicable to Optimus S/Optimus R.) 5 - 0 Reserved 1: Transmit Code 39 Start/Stop Character 0: DO NOT transmit Code 39 Start/Stop Character...
Page 50 "C" Programming Guide For Optimus S/R 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 - 6 Select Matrix 25 Start/Stop Pattern...
Page 51 Chapter 3 Terminal Specific Function Library 1: Convert UPCA to EAN-13 0: No conversion 1: Enable ISBN Conversion 0: No conversion 1: Enable ISSN Conversion 0: No conversion 1: Transmit UPCE Check Digit 0: DO NOT transmit UPCE Check Digit 1: Transmit UPCA Check Digit 0: DO NOT transmit UPCA Check Digit 1: Transmit EAN-8 Check Digit...
Page 52 "C" Programming Guide For Optimus S/R 1: Interleave 25 Code Length Limitation in Max/Min Length Format 0: Interleave 25 Code Length Limitation in Fixed Length Format 6 - 0 Interleave 25 Max Code Length / Fixed Length 1 7 - 0...
Page 53: Scan Modes
Chapter 3 Terminal Specific Function Library 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.
Page 54 "C" Programming 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.
Page 55 Chapter 3 Terminal Specific Function Library 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.
Page 56 "C" Programming 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.
Page 57 Chapter 3 Terminal Specific Function Library Momentary mode Hold down the scan trigger to start scanning. The scanning continues until the trigger is released.
Page 58 "C" Programming Guide For Optimus S/R Alternate mode Press the scan trigger to start scanning. The scanning continues until the trigger is pressed again.
Page 59 Chapter 3 Terminal Specific Function Library 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.
Page 60 "C" Programming 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.
Page 61 Chapter 3 Terminal Specific Function Library 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.
Page 62 "C" Programming 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...
Page 63 Chapter 3 Terminal Specific Function Library Decode Purpose To perform barcode decoding. Syntax int Decode (void); Example while (1) { if (Decode()) break;} Description 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.
Page 64 "C" Programming Guide For Optimus S/R The scanner port will not work unless it is initialized. Description Return None See Also Decode, HaltScanner1...
Page 65: Keyboard Wedge Interface
Chapter 3 Terminal Specific Function Library 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().
Page 66: Kbd / Terminal Type
"C" Programming 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 Null (Data Not Transmitted)
Page 67: Capital Lock Auto-Detection
Chapter 3 Terminal Specific Function Library 3.3.3 Capital Lock Auto-Detection When " " is enabled, the SendData() routine can automatically Capital Lock Auto-Detection 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.
Page 68: Digits Position
"C" Programming 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.
Page 69: Inter-Character Delay
Chapter 3 Terminal Specific Function Library 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...
Page 70 "C" Programming 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.
Page 71 Chapter 3 Terminal Specific Function Library Syntax int WedgeReady (void); Example if (WedgeReady()) SendData (CodeBuf); Description Before sending data via keyboard wedge, it is recommended to check if the cable is well connected; otherwise, the transmission may be blocked. Return If connection is OK, it returns 1.
Page 72: Buzzer
"C" Programming 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.
Page 73: Beep Duration
Chapter 3 Terminal Specific Function Library 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.
Page 74 "C" Programming Guide For Optimus S/R If there is a beeper sequence already in progress, the later will override the original one. Return None See Also beeper_status, off_beeper, play play Purpose To play melody by specifying a sequence of how a beeper is activated.
Page 75: Real-Time Clock
Chapter 3 Terminal Specific Function Library 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.
Page 76 "C" Programming Guide For Optimus S/R This routine reads the current date and time from the calendar chip and copies Description 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.
Page 77: Alarm
Chapter 3 Terminal Specific Function Library 3.5.2 Alarm These are applicable to the Optimus S only. GetAlarm Optimus S Purpose To get the current alarm time. Syntax void GetAlarm (char *cur_time); char *cur_time; /* pointer a buffer where alarm time will be copied to */ Example GetAlarm (alarm_time);...
Page 78: Led
"C" Programming Guide For Optimus S/R 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 To set the LED indicator.
Page 79: Keypad
Chapter 3 Terminal Specific Function Library 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.
Page 80 "C" Programming Guide For Optimus S/R If successful, it returns 1. Return Otherwise, it returns 0. See Also OSTimeDly clr_kb Purpose To clear the keyboard buffer. void clr_kb (void); Syntax Example clr_kb(); Description This routine is automatically called by the system upon powering up the terminal.
Page 81 Chapter 3 Terminal Specific Function Library kbhit Purpose To check if there is any key being pressed. Syntax int kbhit (void); Example for (;!kbhit();); /* wait till a key is pressed */ Description This routine checks if there is any character waiting in the keyboard buffer for being read out.
Page 82: Alpha Key
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.
Page 83 The return value can be one of the following: Return Numeric mode Upper case alpha mode Lower case alpha mode Function mode (Optimus S only) See Also LockAlphaState, set_alpha_lock LockAlphaState Purpose To set the ALPHA (α) state for input mode and lock (= disable) the ALPHA (α) key.
Page 84 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) Return None dis_alpha, en_alpha, get_alpha_enable_state, get_alpha_lock_state, See Also set_alpha_lock set_alpha_lock Purpose To set the ALPHA (α) state for input mode.
Page 85: Fn Key
Chapter 3 Terminal Specific Function Library 3.7.3 FN Key These are applicable to the Optimus R only. GetFuncToggle Optimus R Purpose To get information of the FN key state. Syntax int GetFuncToggle (void); Example state = GetFuncToggle(); Description This routine gets the current state of the FN (function) key. Return The return value can be 0 ~ 3.
Page 86: Lcd
"C" Programming 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...
Page 87 Chapter 3 Terminal Specific Function Library Example if (GetVideoMode() == VIDEO_NORMAL) puts ("Normal Mode"); Description This routine indicates the current display mode of the LCD. Return The return value can be one of the following, depending on the display mode: VIDEO_NORMAL (0) : Normal mode in use VIDEO_REVERSE (1)
Page 88 "C" Programming Guide For Optimus S/R SetContrast Purpose To set the contrast level of the LCD. Syntax void SetContrast (int level); Example SetContrast (4); This routine specifies the contrast level of the LCD, and the valid value ranges Description from 0 (low) to 7 (high).
Page 89: 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)
Page 90 "C" Programming Guide For Optimus S/R void SetCursor (int cursor); Syntax int cursor; /* state of cursor indication */ Example SetCursor (0); /* turn off the cursor indication */ This routine displays or hides the cursor on the LCD according to the value Description specified.
Page 91 Chapter 3 Terminal Specific Function Library Description This routine retrieves the y coordinate of the current cursor position. Return It returns the y coordinate. See Also wherex, wherexy...
Page 92: Display
"C" Programming Guide For Optimus S/R 3.8.3 Display fill_rect Purpose To fill a rectangular area on the LCD. Syntax 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;...
Page 93 Chapter 3 Terminal Specific Function Library 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.
Page 94 "C" Programming 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.
Page 95 Chapter 3 Terminal Specific Function Library puts Purpose To display a string on the LCD. Syntax int puts (char *string); char* string; /* string being sent to the LCD */ Example puts ("Password : "); Description This routine sends a string, whose address is specified in the argument string, to the LCD at the current cursor position.
Page 96: Clear
"C" Programming Guide For Optimus S/R 3.8.4 Clear clr_eol Purpose To clear from where the cursor is to the end of the line. Syntax void clr_eol (void); Example clr_eol(); This routine clears from where the cursor is to the end of the line, and then Description moves the cursor to its original position.
Page 97 Chapter 3 Terminal Specific Function Library The cursor position is not affected after the operation. Return None See Also fill_rect clr_scr Purpose To clear everything on the LCD. Syntax void clr_scr (void); Example clr_scr(); Description This routine clears contents of the current screen and places the cursor at the first column of the first line, i.e.
Page 98: Image
"C" Programming 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.
Page 99 Chapter 3 Terminal Specific Function Library Description 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 Return See Also...
Page 100: Fonts
"C" Programming 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: 8x16 The LCD will show 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.
Page 101: Multi-Language Font
Chapter 3 Terminal Specific Function Library 3.9.3 Multi-Language Font This font file may include English (default), French, Hebrew, Latin, Nordic, Portuguese, Turkish, Russian, Polish, Slavic, Slovak, etc. To display in any of these languages except English, you need to call SetLanguage() to specify the language by region. 3.9.4 Special Fonts Fonts with file name specifying Tc12 (Traditional Chinese), Sc12 (Simplified Chinese), or Jp12 (Japanese) are referred to as the special font files.
Page 102 "C" Programming Guide For Optimus S/R int GetFont (void); Syntax Example if (GetFont()) == FONT_8X16 puts ("Font: 8X16"); Description This routine returns font size information about the current font type. The return value can be one of the following: Return...
Page 103 Chapter 3 Terminal Specific Function Library SetLanguage Purpose To select which language is to be used from the multi-language font file. Syntax void SetLanguage (int setting); int setting; /* integer represents the language to be used */ Example SetLanguage (0x14); /* choose the Nodic font */ Description If the multi-language font file has been downloaded to the terminal, then this...
Page 104: Font Files
"C" Programming Guide For Optimus S/R 3.9.5 Font Files Font_OP_Japanese.shx Font size: 16x16 (4 lines) Font_OP_Japanese12.shx Font size: 6x12 or 12x12 (5 lines) Font_OP_Korean.shx Font size: 16x16 (4 lines) Font_OP_Simplified_Chinese.shx Font size: 16x16 (4 lines) Font_OP_Simplified_Chinese12.shx Font size: 6x12 or 12x12 (5 lines) Font_OP_Traditional_Chinese.shx...
Page 105: Battery
Chapter 3 Terminal Specific Function Library 3.10 Battery This section describes the power management functions that can be used to monitor the voltage level of the main and backup batteries. The portable terminal is equipped with a main battery for normal operation, and, a backup battery for keeping SRAM data, as well as for time accuracy.
Page 106 "C" Programming Guide For Optimus S/R bat1 = get_vbackup(); Example Description This routine reads the voltage level of the backup battery, in units of mV. Return It returns the voltage reading (milli-volt). get_vmain See Also...
Page 107: Communication Ports
3.11.1 Port Mapping The following table shows the mapping of the communication (COM) ports. Model# COM1 COM2 Optimus S Serial IR, IrDA Bluetooth (SPP/DUN) Optimus R RS-232, Serial IR, IrDA Bluetooth (SPP/DUN) Specifying which type of interface is to be used, user can use the same commands to open, close, read, and write the data via different interfaces: RS-232, Serial IR, IrDA, or Bluetooth (SPP/DUN).
Page 108 "C" Programming Guide For Optimus S/R Relevant routines are grouped by different communication types and described separately in the following sections. clear_com To clear the receive buffer. Purpose Syntax void clear_com (int port); int port; /* COM port whose receive buffer is to be cleared */ clear_com (1);...
Page 109 Chapter 3 Terminal Specific Function Library com_overrun Purpose To check if overrun error occurs. Syntax int com_overrun (int port); int port; /* which COM port (1 or 2) to be checked */ Example if (overrun (1) > 0) clear_com (1); /* if overrun, data stored in the buffer is not complete, clear them all */ Description This routine checks if overrun error occurs on COM 1 or COM 2.
Page 110 "C" Programming Guide For Optimus S/R 0x00 Baud rate (bps) BAUD_115200 0x01 BAUD_76800 * 0x02 BAUD_57600 0x03 BAUD_38400 0x04 BAUD_19200 0x05 * (asterisk): BAUD_9600 0x06 Not applicable to Serial IR. BAUD_4800 * 0x07 BAUD_2400 * 0x00 Data bits DATA_BIT7 0x08...
Page 111 Chapter 3 Terminal Specific Function Library read_com Purpose To read one character from the receive buffer of a specified COM port. Syntax int read_com (int port, char *c); int port; /* receive buffer of a specified COM port */ char *c; /* pointer to character returned */ Example char c;...
Page 112 "C" Programming Guide For Optimus S/R write_com Purpose To send a null-terminated string through a specified COM port. Syntax int write_com (int port, char *s); int port; /* COM port to be used */ char *s; /* string to be sent out */ Example char s[ ] = {"Hello\n"};...
Page 113: Rs-232, Serial Ir & Irda Communications
Chapter 3 Terminal Specific Function Library 3.11.3 RS-232, Serial IR & IrDA Communications RS-232 Parameters Baud Rate: 115200, 76800, 57600, 38400, 19200, 9600, 4800, 2400 Data Bits: 7 or 8 Parity: Even, Odd, or None Stop Bit: Flow Control: RTS/CTS, XON/XOFF, or None Serial IR Parameters Baud Rate: 115200, 57600, 38400, 19200, 9600...
Page 114 "C" Programming Guide For Optimus S/R However, due to the UART design (on-chip temporary transmission buffer), up to five characters might be sent after the CTS signal is de-asserted. Receive The RTS signal is used to indicate whether the storage of receive buffer is free or not.
Page 115 Chapter 3 Terminal Specific Function Library com_cts Optimus R Purpose To get CTS level. Syntax int com_cts (int port); int port; /* usually COM port 1 mapped to RS-232 */ Example if (com_cts (1) == 0) printf ("COM 1 CTS is negated"); else printf ("COM 1 CTS is asserted");...
Page 116: Ppp Via Ir/Rs-232
Internet. PPP Connection via IR It is supported on the Optimus S and Optimus R when being connected to the proprietary modem cradle. Note: The version of IR control board on the modem cradle must be greater than SV3.01.
Page 117 Chapter 3 Terminal Specific Function Library Bluetooth ops_ppp.lib, or ops_bnep.lib Optimus R Batch opr_ppp.lib Bluetooth opr_ppp.lib, or opr_bnep.lib 802.11b opr_ppp.lib, or opr_wlan.lib...
Page 118: Wireless Communications
"C" Programming Guide For Optimus S/R 3.12 Wireless Communications Include File All programs that call TCP/IP stack routines need to contain the following include statement. #include <opr_tcpip.h> The header file, opr_tcpip.h or ops_tcpip.h, contains the function prototypes (declarations) and error code definitions. This file should normally be placed under the "include"...
Page 119: Wireless Models
Chapter 3 Terminal Specific Function Library 3.13.1 Wireless Models This section describes the commands related to wireless network configuration. These command sets are only applicable to the models below. Wireless Product Family Bluetooth WLAN (IEEE 802.11b) Terminal 8061 8360 8071 8370 Access Point 3560...
Page 120 "C" Programming Guide For Optimus S/R IEEE 802.11b IEEE 802.11b is an industrial standard for Wireless Local Area Networking (WLAN), which enables wireless communications over a long distance. The speed of the connection between wireless devices will vary with range and signal quality.
Page 121 Chapter 3 Terminal Specific Function Library Bluetooth Serial Port Profile (SPP) is for ad hoc networking, without going through any access point. Personal Area Networking Profile (PAN) makes use of Bluetooth Network Encapsulation Protocol (BNEP) for IP networking over Bluetooth. Access points (AP) required.
Page 122: Network Configuration
"C" Programming Guide For Optimus S/R 3.13.2 Network Configuration Before bringing up (initializing) the network, some related parameters must be configured. These parameters are grouped into a structure, NETCONFIG or BTCONFIG or PPPCONFIG structure, and are saved in the system. They are kept by the system during normal operations and power on/off cycles.
Page 123 Chapter 3 Terminal Specific Function Library WLAN (802.11b) - Config NETCONFIG Structure struct NETCONFIG { int DhcpEnable; unsigned char IpAddr[4]; unsigned char SubnetMask[4]; unsigned char DefaultGateway[4]; unsigned char DnsServer[4]; char DomainName[129]; char LocalName[33]; char SSID[33]; int SystemScale; WLAN_FLAG Flag; int WepLen; int DefaultKey;...
Page 124 "C" Programming Guide For Optimus S/R Note: Only one network interface can be used at a time: 802.11b or PAN Parameter Default Description WLAN int DhcpEnable 0: disable DHCP 1: enable DHCP unsigned char IpAddr[4] 0.0.0.0 Local IP Address unsigned char SubnetMask[4] 0.0.0.0...
Page 125 Chapter 3 Terminal Specific Function Library WLAN_FLAG Structure typedef struct { unsigned int Authen: 1; unsigned int Wep: 1; unsigned int Eap: 1; unsigned int PWRSave: 1; unsigned int Preamble: 2; unsigned int AdHoc: 1; unsigned int Reservedflag: 9; } WLAN_FLAG; Note: Only one network interface can be used at a time: 802.11b or PAN Parameter Default...
Page 126 "C" Programming Guide For Optimus S/R GetNetConfig Purpose To retrieve the whole networking configurations from the system. Syntax void GetNetConfig (struct NETCONFIG *config); Example struct NETCONFIG nc; struct NETSTATUS ns; ......GetNetConfig (&nc); nc.DhcpEnable = 1; SetNetConfig (&nc); if (NetInit() < 0) { printf ("Initialization Fail");...
Page 127 Chapter 3 Terminal Specific Function Library SetNetConfig Purpose To write the whole networking configurations to the system. Syntax void SetNetConfig (struct NETCONFIG *config); Example struct NETCONFIG nc; struct NETSTATUS ns; ......GetNetConfig (&nc); nc.DhcpEnable = 1; SetNetConfig (&nc); if (NetInit() < 0) { printf ("Initialization Fail");...
Page 128 "C" Programming Guide For Optimus S/R Bluetooth - Config BTCONFIG Structure typedef struct { char BTRemoteName[20]; unsigned char BTPINCode[16]; unsigned char BTLinkKey[16]; BTSearchInfo Dev[8]; BT_FLAG Flag; unsigned char BTGPRSAPname[20]; char ReservedByte[220]; } BTCONFIG; Parameter Default Description Index char BTRemoteName[20] Null...
Page 129 Chapter 3 Terminal Specific Function Library BT_FLAG Structure typedef struct { unsigned int BTPWRSaveON: 1; unsigned int BTSecurity: 1; unsigned int BTBroadcastON: 1; unsigned int Reservedflag: 13; } BT_FLAG; Parameter Default Description Index unsigned int BTPWRSaveON Bluetooth Power-saving 0: disable 1: enable unsigned int BTSecurity Bluetooth Security...
Page 130 "C" Programming Guide For Optimus S/R BTSearchInfo Structure typedef struct { unsigned char Machine; unsigned char ADDR[6]; unsigned char Name[12]; unsigned char PINCode[16]; unsigned char LinkKey[16]; } BTSearchInfo; size = 51 bytes Parameter Default Description unsigned char Machine Host profile indication...
Page 131 Chapter 3 Terminal Specific Function Library GetBTConfig Purpose To retrieve the whole Bluetooth configurations from the system. Syntax void GetBTConfig (BTCONFIG *config); Example Description This routine gets the whole Bluetooth configurations from the system. It is useful when the application wants to change more than one part of the configuration parameters.
Page 132 "C" Programming Guide For Optimus S/R PPP via IR/RS-232 - Config PPPCONFIG Structure typedef struct { unsigned char DialUpPhone[20]; unsigned char LoginName[20]; unsigned char LoginPassword[20]; int ComBaudRate; } PPPCONFIG; Parameter Default Description Index unsigned char Null Phone number of ISP...
Page 133 Chapter 3 Terminal Specific Function Library NetParameters by Index Note: Only one network interface can be used at a time: 802.11b or PAN Index 1 ~ 32 Data Type WLAN SPP DUN PAN P_LOCAL_IP unsigned char [4] P_SUBNET_MASK unsigned char [4] P_DEFAULT_GATEWAY unsigned char [4] P_DNS_SERVER...
Page 134 "C" Programming Guide For Optimus S/R P_BT_BROADCAST_ON unsigned int P_BT_POWER_SAVE_ON unsigned int P_ADHOC unsigned int P_FIRMWARE_VERSION char [4] Read only P_BT_GPRS_APNAME unsigned char [20] Index 40 ~ 47 Data Type WLAN SPP DUN PAN P_BT_FREQUENT_DEVICE1 BTSearchInfo P_BT_FREQUENT_DEVICE2 BTSearchInfo P_BT_FREQUENT_DEVICE3 BTSearchInfo...
Page 135 Chapter 3 Terminal Specific Function Library GetNetParameter Purpose To retrieve one networking configuration item from the system. Syntax void GetNetParameter (void *return-value, int index); Example int DhcpEnable; unsigned char IP[4]; ......DhcpEnable = 1; SetNetParameter ((void*) &DhcpEnable, P_DHCP_ENABLE); if (NetInit() < 0) { printf ("Initialization Fail");...
Page 136 "C" Programming Guide For Optimus S/R SetNetParameter Purpose To write one networking configuration item to the system. Syntax void SetNetParameter (void *setting, int index); Example int DhcpEnable; unsigned char IP[4]; ......DhcpEnable = 1; SetNetParameter ((void*) &DhcpEnable, P_DHCP_ENABLE); if (NetInit() < 0) { printf ("Initialization Fail");...
Page 137: Initialization & Termination
Chapter 3 Terminal Specific Function Library 3.13.3 Initialization & Termination After the networking parameters are properly configured, an application program can call NetInit() to initialize any wireless module (802.11b or Bluetooth) and networking protocol stack. The wireless modules will not be powered until NetInit() is called. When an application program needs to stop using the network, NetClose() must be called to shut down the network as well as the modules (so that power can be saved).
Page 138 "C" Programming Guide For Optimus S/R It is necessary for the application to check the status of IPReady (one of the NetStatus items) before performing any networking operations. NetInit() is to enable the default module, either Bluetooth PAN or 802.11b.
Page 139: Network Status
Chapter 3 Terminal Specific Function Library 3.13.4 Network Status Once the network has been initialized, there is some status information can be retrieved from the system. This status information is grouped into a structure, NETSTATUS or BTSTATUS structure, and the system will periodically update it. Note: User program must explicitly call CheckNetStatus() to get the latest status.
Page 140 "C" Programming Guide For Optimus S/R int Signal Signal Strength 0 ~ 30 Weak Level 30 ~ 60 Moderate over 60 Strong int Noise Noise Level Weak 2 ~ 3 Moderate 4 ~ 5 Strong int Channel Current Channel 1 ~ 11...
Page 141 Chapter 3 Terminal Specific Function Library Bluetooth - Status BTSTATUS Structure typedef struct { int State; int Signal; int Reserved[10]; } BTSTATUS; Parameter Description Value Index int State Connection State BT_DISCONNECTED BT_CONNECTED int Signal RSSI Signal Level -10 ~ -6 Weak -6 ~ 5 Moderate...
Page 142 "C" Programming Guide For Optimus S/R NetStatus by Index Note: Only one network interface can be used at a time: 802.11b or PAN; refers to Bluetooth DUN for connecting a modem; refers to Bluetooth DUN-GPRS for activating a mobile’s GPRS.
Page 143 Chapter 3 Terminal Specific Function Library CheckNetStatus Purpose To check on networking status from the system. Syntax int CheckNetStatus (int index); Example int DhcpEnable; unsigned char IP[4]; ......DhcpEnable = 1; SetNetParameter ((void*) &DhcpEnable, P_DHCP_ENABLE); if (NetInit() < 0) { printf ("Initialization Fail");...
Page 144: Wlan (802.11B)
"C" Programming Guide For Optimus S/R 3.13.5 WLAN (802.11b) Native Programming Interface Opening & Closing of Connections The section gives details on how to open and close connections. The Nopen() function is used to establish connections. After the connection is...
Page 145 Chapter 3 Terminal Specific Function Library Remote port number, For a passive open (server), this value should be specified as 0, and any remote port will be accepted for the connection. flags Normally, its value is set to 0. To determine if connection is established, use socket_isopen(). S_NOCON: no connection for UDP S_NOWA: non-blocking open IPADDR: remote_ip is binary (4 bytes)
Page 146 "C" Programming Guide For Optimus S/R Reading & Writing Data The section describes the Nread() and Nwrite() routines, which are used to send and receive data on the network. Nread Purpose To read a message from a connection. Syntax int Nread (int conno, char *buff, int len);...
Page 147 Chapter 3 Terminal Specific Function Library Example if (socket_cansend (conno, strlen (buf))) Nwrite (conno, buf, strlen (buf)); Description This routine writes a number of bytes (len) from a specified buffer (buff) to a connection (conno). The protocol stack will keep the data and send them in background. Normally, this routine will return immediately.
Page 148 "C" Programming Guide For Optimus S/R Socket Programming Interface Include File #include <errno.h> This "errno.h file contains the error code definitions, and it should normally be placed under "include" directory compiler (say, "C:\TOSHIBA\INCLUDE\"). Note: For relevant structures, please refer to the header file for terminal specific library.
Page 149 Chapter 3 Terminal Specific Function Library Connectionless Protocol (UDP) For a connectionless, message-oriented socket, datagrams can be sent to and received from a specific connected peer using sendto() and recvfrom() respectively.
Page 150 "C" Programming Guide For Optimus S/R accept Purpose To accept a connection on a socket. Syntax int accept (SOCKET s, struct sockaddr *name, int *namelen); Descriptor identifying a socket in a listening state name Pointer to a sockaddr structure receiving the remote IP address...
Page 151 Chapter 3 Terminal Specific Function Library Description This routine is used by a server application to perform a passive open, permitting a connection request from client. The name is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer.
Page 152 "C" Programming Guide For Optimus S/R memset (&name, 0, sizeof (name)); name.sin_family = AF_INET; name.sin_port = htons (3000); if (bind (s, (struct sockaddr*) &name, sizeof (name)) < 0) { printf ("Error in Binding on socket: %d", s); ..... Description This routine binds the local IP address and listening port number information to the socket specified.
Page 153 ("SOCKET allocation failed"); ....memset (&name, 0, &sizeof (name)); name.sin_family = AF_INET; name.sin_port = htons (3000); phostent = gethostbyname ("server1.Metrologic.com.tw"); if (!phostent) { printf ("Can not get IP from DNS server"); ....memcpy (&name.sin_addr, phostent->h_addr_list[0], 4); if (connect (s, (struct sockaddr*) &name, sizeof(name)) < 0) { printf ("Error in Establishing connection");...
Page 154 "C" Programming Guide For Optimus S/R accept, getpeername, getsockname, listen, select, socket See Also fcntlsocket To provide file control over descriptors. Purpose Syntax int fcntlsocket (int fildes, int cmd, int arg); Example The routine provides for control over descriptors. Description The argument fildes is a descriptor to be operated on by cmd as described below.
Page 155 Chapter 3 Terminal Specific Function Library name.sin_family = AF_INET; name.sin_port = htons (3000); phostent = gethostbyname ("server1.Metrologic.com.tw"); if (!phostent) { printf ("Can not get IP from DNS server"); ....... memcpy (&name.sin_addr, phostent->h_addr_list[0], 4); if (connect (s, (struct sockaddr*) &name, sizeof (name)) < 0) { printf ("Error in Establishing connection");...
Page 156 "C" Programming Guide For Optimus S/R printf ("Can not get remote name info"); ....... This routine returns the name of the peer connected to socket s. It only can be Description used on a connected socket. (?) The name is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer.
Page 157 Chapter 3 Terminal Specific Function Library The name is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the name parameter is determined by the address family in which the communication is occurring.
Page 158 "C" Programming Guide For Optimus S/R SO_DONTROUTE Enables routing bypass for outgoing messages SO_BROADCAST Enables permission to transmit broadcast messages SO_BINDTODEVI SO_LINGER Returns the current Linger option SO_OOBINLINE Enables reception of out-of-band data in band SO_SNDBUF Gets buffer size for sends...
Page 159 Chapter 3 Terminal Specific Function Library inet_ntoa Purpose To convert an IP address to a string in standard dot notation. Syntax char *inet_ntoa (struct in_addr addr); addr A in_addr structure containing the IP address to be converted Example struct sockaddr_in name; char ip_addr[16];...
Page 160 "C" Programming Guide For Optimus S/R SOCKET s; Example struct sockaddr_in name; s = socket (PF_INET, SOCK_STREAM, TCP); if (s < 0) { printf ("SOCKET allocation failed"); ....memset (&name, 0, sizeof (name)); name.sin_family = AF_INET; name.sin_port = htons (3000);...
Page 161 Chapter 3 Terminal Specific Function Library recv Purpose To receive data from a connected or bound socket. Syntax int recv (SOCKET s, char *buf, int len, int flags); Descriptor identifying a connected socket Pointer to the buffer in which data is received Maximum number of bytes to be received flags MSG_OOB: process out-of-band data...
Page 162 "C" Programming Guide For Optimus S/R recvfrom, select, send, socket_hasdata See Also recvfrom To receive data from a socket and stores the source address. Purpose Syntax int recvfrom (SOCKET s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen);...
Page 163 Chapter 3 Terminal Specific Function Library select Purpose To synchronize I/O multiplexing. Syntax int select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); domain Protocol family; this should always be PF_INET or AF_INET. type Socket type, either SOCK_STREAM or SOCK_DGRAM. protocol Depending on the type parameter specified, the protocol to be used can be TCP, UDP, or ICMP.
Page 164 "C" Programming Guide For Optimus S/R send Purpose To send data to a connected socket. Syntax int send (SOCKET s, char *buf, int len, int flags); Descriptor identifying a connected socket Pointer to the buffer in which data is to be sent...
Page 165 Chapter 3 Terminal Specific Function Library Syntax int sendto (SOCKET s, char *buf, int len, int flags, struct sockaddr *to, int tolen); Descriptor identifying a connected socket Pointer to the buffer in which data is to be sent Maximum number of bytes to be sent flags MSG_OOB: process out-of-band data MSG_DONTROUTE: bypass routing, use direct interface...
Page 166 "C" Programming Guide For Optimus S/R Although options may exist at multiple protocol levels, they are always present at the uppermost socket level. Options affect socket operations, such as the packet routing and OOB data transfer. When manipulating socket options, the level at which the option resides and the name of the option must be specified.
Page 167 Chapter 3 Terminal Specific Function Library 0: shuts down receive data path 1: shuts down send data path and send FIN (final) 2: shuts down both receive and send data path Example SOCKET s; ....if (shutdown (s, 2) < 0) { printf ("shutdown fails on socket: %d", s);...
Page 168 "C" Programming Guide For Optimus S/R The protocol argument specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type within a given protocol family. However, it is possible that many protocols may exist, in which case a particular protocol must be specified in this manner.
Page 169 Chapter 3 Terminal Specific Function Library Byte Swapping htonl Purpose To convert an unsigned long integer from host byte order to network byte order. unsigned long htonl (unsigned long val); Syntax unsigned long val; /* an unsigned long integer to be converted */ Example This routine converts an unsigned long integer from host byte order to network Description...
Page 170 "C" Programming Guide For Optimus S/R ntohl Purpose To convert an unsigned long integer from network byte order to host byte order. Syntax unsigned long ntohl (unsigned long val); unsigned long val; /* an unsigned long integer to be converted */...
Page 171 *remote_ip; /* pointer to remote_ip returned */ Example char IP[4]; DNS_resolver ("www.metrologic.com", IP); Description This function gets the remote IP address by remote name. It is necessary to define the DNS server IP before calling this function. If successful, it returns 0.
Page 172 "C" Programming Guide For Optimus S/R This function sets non-blocking operation back to blocking operation. Description Blocking operation is the default behavior for network functions. When in blocking operation, calls to network functions will run to completion, or return a timeout error if an associated time limit is run out.
Page 173 Chapter 3 Terminal Specific Function Library socket_hasdata Purpose To check if data is available. Syntax int socket_hasdata (int conno); int conno; /* connection number */ Example if (socket_hasdata (conno)) Nread (conno, buf, sizeof (buf)); Description This function checks if data from the connection specified conno is available to be read.
Page 174 "C" Programming Guide For Optimus S/R If connected, it returns a non-zero value. Return Otherwise, it returns 0. See Also Nopen socket_keepalive Purpose To set the dummy sending period for a connection. int socket_keepalive (int conno, unsigned long val); Syntax int conno;...
Page 175 Chapter 3 Terminal Specific Function Library Syntax int socket_push (int conno); int conno; /* connection number */ Example val = socket_push (conno); Description The next TCP segment to be written, following a call to this function, will have the PSH flag set in the TCP header. This is useful for indicating to the TCP on the remote system that all internally buffered segments up through this segment should be delivered to the application as soon as possible.
Page 176 "C" Programming Guide For Optimus S/R If successful, it returns 0. Return On error, it returns -1. The global variable errno is set to indicate the error condition encountered. Refer to the header files for error codes. See Also socket_state Purpose To get the socket status for a connection.
Page 177 Chapter 3 Terminal Specific Function Library Syntax int socket_txstat (int conno); int conno; /* connection number */ Example val = socket_txstat (conno); Description The function gets the transmit status for a connection. Return The return value can be one of the following: S_PSH 0x01 push...
Page 178: Bluetooth
"C" Programming Guide For Optimus S/R 3.13.6 Bluetooth On the Bluetooth terminal, it makes use of the pairing procedure to keep record of the latest connected device(s) for different modes, regardless of authentication enabled or not. This is so-called "Frequent Device List".
Page 179 Chapter 3 Terminal Specific Function Library Frequent Device List Get Freq. Dev. List The length of Frequent Device List by calling GetNetParameter() is 83 characters: LIST$ = GetNetParameter(40) The first character of Frequent Device List is the service type that the device is engaged.
Page 180 "C" Programming Guide For Optimus S/R Set Freq. Dev. List To enable quick connection to a specific device without going through the inquiry and pairing procedure, a user-definable Frequent Device List can be set up by calling SetNetParameter(). If there is an existing Frequent Device List generated from the inquiry and pairing procedure, it then may be partially or overall updated by this, and vice versa.
Page 181 Chapter 3 Terminal Specific Function Library Pairing With the information on nearby Bluetooth devices, the application can then try to pair with any of the remote devices by calling BTPairingTest(). BTPairingTest Purpose To pair with one Bluetooth device. Syntax int BTPairingTest (BTSearchInfo *Info, int TargetMachine); Example BTSearchInfo Info[4];...
Page 182 "C" Programming Guide For Optimus S/R Useful Function Call We also provide some simple function calls for pairing with a Bluetooth device easily. Example Code #include <lib_ops.h> #include <ucos.h> static const MENU_ENTRY PAIRING_ENTRY; static const MENU_ENTRY DEVICELIST_ENTRY; MENU SPP_MENU = { 2, 1, 0, "Bluetooth",...
Page 183 Chapter 3 Terminal Specific Function Library BTPairingTestMenu Purpose To create a menu and try to pair with one Bluetooth device. Syntax void BTPairingTestMenu (void); Example See example code Description This routine creates a menu and tries to pair with one Bluetooth device. Once pairing successfully, the MAC ID of this remote device will be updated to the Frequent Device List.
Page 184: Wireless Practice
"C" Programming Guide For Optimus S/R 3.13 Wireless Practice 3.13.1 WLAN (802.11b) - Practice TCP/IP Application Network Configuration: Generally, network configuration has to be done in advance by calling GetNetParameter() and SetNetParameter(). Initialization of Networking Protocol Stack & Wireless Module: The wireless module, 802.11b or Bluetooth, will not be powered until NetInit() is...
Page 185 Chapter 3 Terminal Specific Function Library b) Before receiving data from the network, call socket_hasdata() to check if there is data in the buffer. Then, call Nread() to receive data on the network. Note: In case of an abnormal break during PPP or DUN-GPRS connection, CheckNetStatus(NET_IPReady) will return -1.
Page 186: Bluetooth - Practice
"C" Programming Guide For Optimus S/R 3.13.2 Bluetooth - Practice SPP Application Call SetCommType (2, COMM_RF) to set COM2 to Bluetooth communication. To initialize the Bluetooth module as SPP Master or Slave, call open_com (2, BT_SERIALPORT_MASTER) or open_com (2, BT_SERIALPORT_SLAVE).
Page 187 Chapter 3 Terminal Specific Function Library Call write_com() and read_com() to transmit and receive data respectively. Call com_eot() to detect if connection is broken. For example, if (com_eot (2)) printf ("Connection break"); Call close_com (2) to terminate communication and shut down the Bluetooth module.
Page 188 "C" Programming Guide For Optimus S/R Example Code For this purpose, the application should call these functions in the beginning: #include <lib_opr.h> #include <ucos.h> static const int beep[] = {32, 5, 0, 0}; main() SetCommType (2, COMM_RF); //Add WEDGE_EMULATOR flag to open_com // open_com (2, BT_SERIALPORT_SLAVE|WEDGE_EmULATOR);...
Page 189 Chapter 3 Terminal Specific Function Library clr_scr(); gotoxy (0, 0); printf (" Virtual Wedge "); gotoxy (0, 1); printf ("===================="); gotoxy (0, 2); printf (" Ready "); gotoxy (0, 3); printf ("Press a key to start"); gotoxy (0, 4); printf ("===================="); on_beeper (beep);...
Page 190: File Manipulation
There is a limit for the total number of files, which includes all DAT files as well DBF files and their associated IDX files. Max. 255 files for the Optimus S and Optimus R To get the information of the file directory, you can call filelist().
Page 191: File Handle (File Descriptor)
Chapter 3 Terminal Specific Function Library If a file name specified is longer than eight characters, it will be truncated to eight characters. The file name can be changed later by calling rename(). Note: The file name is case-sensitive. 3.14.4 File Handle (File Descriptor) File handle is the identification of a file after the file is opened.
Page 192 "C" Programming Guide For Optimus S/R On error, it returns -1. An error code is set to the global variable fErrorCode to indicate the error condition encountered. Below are possible error codes and their interpretation. Error Code Interpretation filename is a NULL string.
Page 193 Chapter 3 Terminal Specific Function Library If the file to be deleted is a DBF file, the DBF file and all the index (key) files associated to it will be deleted together. If successful, it returns 1. Return On error, it returns 0. An error code is set to the global variable fErrorCode to indicate the error condition encountered.
Page 194: Dat Files
"C" Programming Guide For Optimus S/R 3.14.6 DAT Files DAT files have a sequential file structure. Data at the beginning of a DAT file can be removed by calling the delete_top() or delete_topln() function. The new file top, the file pointer, and the size of the DAT file will be adjusted accordingly after calling either of the two functions.
Page 195 Chapter 3 Terminal Specific Function Library The value of count is negative. No free file space for file extension. appendln, read, readln, write, writeln See Also appendln Purpose To write a line (null-terminated string) to the bottom (EOF) of a DAT file. Syntax int appendln (int fd, char *buffer);...
Page 196 "C" Programming Guide For Optimus S/R int fd; /* file handle of the target DAT file */ long size; /* new size of file in bytes */ Example if (chsize (fd, 0L)) puts ("file is truncated!\n"); This routine extends or truncates a DAT file (fd) to match the new file length in Description bytes given in the argument size.
Page 197 Chapter 3 Terminal Specific Function Library delete_top Purpose To delete a specified number of bytes from the top (beginning-of-file position) of a DAT file. Syntax int delete_top (int fd, int count); int fd; /* file handle of the target DAT file */ int count;...
Page 198 "C" Programming Guide For Optimus S/R Removal of data starts at the beginning-of-file position of the file, and the file pointer position is adjusted accordingly. This routine will resize the file size automatically. Return If successful, it returns the number of bytes actually removed from the file, including the null character.
Page 199 Chapter 3 Terminal Specific Function Library filelength Purpose To get the length information of a DAT file. Syntax long filelength (int fd); int fd; /* file handle of the target DAT file */ Example data_size = filelength (fd); Description This routine gets the size information (in bytes) of a DAT file (fd). Return If successful, it returns the number of bytes for file size.
Page 200 "C" Programming Guide For Optimus S/R Error Code Interpretation File specified by fd does not exist. File specified by fd is not a DAT file. Invalid file handle. File not opened. Invalid value in argument: origin New position is beyond end-of-file.
Page 201 Chapter 3 Terminal Specific Function Library read Purpose To read a specified number of bytes from a DAT file. Syntax int read (int fd, char *buffer, int count); int fd; /* file handle of the target DAT file */ char *buffer; /* pointer to a buffer where data is read into */ int count;...
Page 202 "C" Programming Guide For Optimus S/R If characters are read until a null character (\0) is encountered. The null character is also read into buffer, that is, it is also counted for the return value. Otherwise, there may not be a null character stored in buffer.
Page 203 Chapter 3 Terminal Specific Function Library See Also lseek write Purpose To write a specified number of bytes to a DAT file. Syntax int write (int fd, char *buffer, int count); int fd; /* file handle of the target DAT file */ char *buffer;...
Page 204 "C" Programming Guide For Optimus S/R write (fd, data_buffer); Example Description This routine writes a null-terminated string from the character array buffer to a DAT file (fd). Characters are written to the file until a null character (\0) is encountered.
Page 205: Dbf Files And Idx Files
Chapter 3 Terminal Specific Function Library 3.14.7 DBF Files and IDX Files DBF files and IDX files form the platform of database system. A DBF file has a fixed record length structure. This is the file that stores data records (members). Whereas, the associate IDX files are the files that keep information of the position of each record stored in the DBF files, but they are re-arranged (sorted) according to some specific key values.
Page 206 "C" Programming Guide For Optimus S/R This routine adds a data record (member) to a DBF file (DBF_fd) and adds Description index entries to all the associated IDX files. If the length of the added member is greater than that defined for the DBF file (member_len in the create_DBF function), the member will be truncated to fit in.
Page 207 Chapter 3 Terminal Specific Function Library create_DBF Purpose To create a DBF file and get its file handle for further processing. Syntax int create_DBF (char *filename, int member_len); char *filename; /* name of the file to be created */ int member_len; /* member (record) length of the DBF file */ Example if (fd = create_DBF ("data1", 64) >...
Page 208 "C" Programming Guide For Optimus S/R This routine creates an IDX file (key_number), which is associated with a DBF Description file (DBF_fd). The key field of the IDX file is specified by the arguments key_offset and key_len. The key field should be within member_len as defined in the create_DBF function.
Page 209 Chapter 3 Terminal Specific Function Library Return If successful, it returns 1. On error, it returns 0. An error code is set to the global variable fErrorCode to indicate the error condition encountered. Below are possible error codes and their interpretation. Error Code Interpretation File specified by DBF_fd does not exist.
Page 210 "C" Programming Guide For Optimus S/R File not opened. Invalid value in argument: key_number IDX file specified by key_number does not exist. No members exist in the DBF file. See Also has_member has_member Purpose To check if a data record (member) exists in a DBF file.
Page 211 Chapter 3 Terminal Specific Function Library lseek_DBF Purpose To reposition the file pointer of an IDX file. Syntax long lseek_DBF (int DBF_fd, int key_number, long offset, int origin); int DBF_fd; /* file handle of the associated DBF file */ int key_number; /* key number of the target IDX file */ long offset;...
Page 212 "C" Programming Guide For Optimus S/R total_member = member_in_DBF (DBF_fd); Example Description This routine returns the number of members in a DBF file whose file handle is specified by DBF_fd. Return If successful, it returns the number of members. On error, it returns -1L.
Page 213 Chapter 3 Terminal Specific Function Library See Also close_DBF, create_DBF, create_index rebuild_index Purpose To rebuild an IDX file for a DBF file. Syntax int rebuild_IDX (int DBF_fd, int key_number, int base_index, int key_offset, int key_len); int DBF_fd; /* file handle of the associated DBF file */ int key_number;...
Page 214 "C" Programming Guide For Optimus S/R Cannot create file. Because it is beyond the maximum number of files allowed in the system. Invalid file handle. File not opened. No free file space for rebuilding index. Invalid value in argument: key_number IDX file specified by key_number does not exist.
Page 215 Chapter 3 Terminal Specific Function Library tell_DBF Purpose To get the current index pointer position of an IDX file. Syntax long tell_DBF (int DBF_fd, int key_number); int DBF_fd; /* file handle of the associated DBF file */ int key_number; /* key number of the target IDX file */ Example rank_number = tell_DBF (DBF_fd, 1);...
Page 216 "C" Programming Guide For Optimus S/R An error code is set to the global variable fErrorCode to indicate the error condition encountered. Below are possible error codes and their interpretation. Error Code Interpretation File specified by DBF_fd does not exist.
Page 217: Memory
Chapter 3 Terminal Specific Function Library 3.15 Memory This section describes the commands related to the flash memory and SRAM, where the Program Manager and File System reside respectively. The terminal has 1 MB flash memory for program storage and up to 4 MB SRAM for data storage.
Page 218 "C" Programming Guide For Optimus S/R FlashSize Purpose To get the size of flash memory. Syntax int FlashSize (void); Example FlashSize(); Description This routine gets the size of flash memory, which is available to the user program. This routine returns the size of the flash memory in kilobyte.
Page 219: Sram
Chapter 3 Terminal Specific Function Library 3.15.2 SRAM The File System keeps user data in SRAM, which is maintained by the backup battery. However, data loss may occur during low battery condition or when the battery is drained. It is necessary to upload data to a host computer before putting away the terminal. free_memory Purpose To get the size of free memory in SRAM.
Page 220 "C" Programming Guide For Optimus S/R FlashSize, free_memory See Also...
Page 221: Miscellaneous
This routine sets the terminal to the "Download mode". The "Download" page will be displayed, and user can select the COM port and baud rate for program downloading. For the Optimus S and Optimus R, it is possible to pass arguments to suppress the download submenu. For example, DownLoadPage(NO_MENU, COMM_DIRECT, BAUD_115200);...
Page 222 "C" Programming Guide For Optimus S/R Example void FuncUpload (void) /* to do: add your own program code here */ void FuncDownload (void) /* to do: add your own program code here */ prc_menu (&MyMenu); /* process MyMenu menu */ Description This routine creates a user-defined menu.
Page 223: Chapter 4: Standard Library Routine
H A P T E R Standard Library Routine The standard library routines supported are categorized and listed below. In This Chapter 4.1 Input & Output: <stdio.h> ........... 220 4.2 Character Class Tests: <ctype.h> ........ 221 4.3 String Functions: <string.h> ........222 4.4 Mathematical Functions: <math.h>......
Page 224: Input & Output:
"C" Programming Guide For Optimus S/R 4.1 Input & Output: <stdio.h> File Operations: Not supported. Please use proprietary Library routines. Formatted Output: Only sprintf is supported. For formatted output to display, refer to proprietary Library "LCD". Formatted Input: Only sscanf is supported.

Page 225: Character Class Tests:
Chapter 4 Standard Library Routine 4.2 Character Class Tests: <ctype.h> For each function, the argument is a character, whose value must be EOF or representable as an unsigned char, and the return value is an integer. The functions return non-zero (true) if the argument c satisfies the condition described; otherwise, zero is returned.

Page 226: String Functions:
"C" Programming Guide For Optimus S/R 4.3 String Functions: <string.h> 4.3.1 Functions start with "str" In this list, types of variables are as follows. char *s; const chr *cs, ct; size_t n; int c; char *strcpy (s, ct) copy string ct to string s, including 0x00, return s...

Page 227: Functions Start With "Mem
Chapter 4 Standard Library Routine 4.3.2 Functions start with "mem" In this list, types of variables are as follows. void *s; const void *cs, *ct; size_t n; int c; void *memcpy (s, ct, n) copy n characters from ct to s, return s void *memmove (s, ct, n) same as memcpy except that it works fine even if objects overlap...
Page 228: Mathematical Functions:
"C" Programming Guide For Optimus S/R 4.4 Mathematical Functions: <math.h> Mathematical functions are listed below. All of them return a value of double. In this list, types of variables are as follows. double x, y; int n; sin (x) sine of x...

Page 229 Chapter 4 Standard Library Routine modf (x, double split x into its integer and fraction parts, each with the same sign *ip) as x. Returns the fractional part and loads the integer part into *ip. fmod (x, y) the remainder of x/y, with the same sign as x. If y = 0, the result is implementation-defined.
Page 230: Utility Functions:
"C" Programming Guide For Optimus S/R 4.5 Utility Functions: <stdlib.h> 4.5.1 Number Conversion double atof (const char *s) Convert s to double, equivalent to strtod (s, (char **) NULL) int atoi (const char *s) Convert s to integer, equivalent to strtol (s, (char **)

Page 231: Diagnostics:
Chapter 4 Standard Library Routine 4.6 Diagnostics: <assert.h> Not supported. 4.7 Variable Argument Lists: <stdarg.h> Functions for processing variable arguments are listed below. va_start (va_list ap, lastarg) type va_arg (va_list ap, type) void va_end (va_list ap) 4.8 Non-Local Jumps: <setjmp.h> Not supported.

Page 232: Implementation-Defined Limits: ,
"C" Programming Guide For Optimus S/R 4.11 Implementation-defined Limits: <limits.h>, <float.h> Refer to limit.h and float.h.

Page 233: Chapter 5: Real-Time Kernel
H A P T E R Real-Time Kernel All the portable terminals come with a real-time kernel (µC/OS) that allows user to generate a preemptive multi-tasking application. User can apply the real-time kernel functions to split the application into multiple tasks that each task takes turns to gain the access to the system resource by a priority-based schedule.
Page 234 "C" Programming Guide For Optimus S/R To ensure this, user can call this routine to disable interrupts prior to executing the critical code, and then enable the interrupts when the critical code is done. This function executes in about 5 CPU clock cycles.
Page 235 Chapter 5 Real-Time Kernel Allow a task to synchronize with either an ISR or a task Gain exclusive access to a resource Signal the occurrence of an event Note that semaphores must be created before they are used. This function cannot be called from an ISR.
Page 236 "C" Programming Guide For Optimus S/R OSSemPost Purpose To signal the semaphore. Syntax unsigned char OSSemPost (OS_Event *pevent); where, pevent is a pointer to the semaphore. This pointer is returned to your application when the semaphore is created. Example err = OSSemPost (DispSem);...
Page 237 Chapter 5 Real-Time Kernel Return If successful, it returns OS_NO_ERR. If the requested priority already exists, it returns OS_PRIO_EXIST. See Also OSTaskDel OSTaskDel Purpose To delete a task. Syntax unsigned char OSTaskDel (unsigned char prio); where, prio is the task priority. A unique priority number must be assigned to each task;...
Page 238 "C" Programming Guide For Optimus S/R...
Page 239: Index
Index clr_scr • 91 CodeBuf • 39 CodeLen • 39 _KeepAlive__ • 20 CodeType • 39 com_cts • 109 com_eot • 102 accept • 144 com_overrun • 103 access • 185 com_rts • 109 ActivateProgram • 34 connect • 147 add_member •...
Page 240 Index get_image • 92 listen • 153 get_member • 203 LoadProgram • 36 get_time • 69 LockAlphaState • 77 get_vbackup • 99 lseek • 193 get_vmain • 99 lseek_DBF • 205 GetAlarm • 71 GetBTStatus • 135 getchar • 74 ManufactureDate •...
Page 241 Index socket_rxstat • 169 socket_rxtout • 169 socket_state • 170 RamSize • 213 socket_testfin • 170 read • 195 socket_txstat • 170 read_com • 105 sys_msec • 24 read_error_code • 186 sys_sec • 24 readln • 195 SysSuspend • 21 rebuild_index •...

This manual is also suitable for:

Optimus r

Metrologic Optimus S Programming Manual

CHAPTER 1: Introduction

CHAPTER 2: Development Environment

CHAPTER 3: Terminal Specific Function Library

CHAPTER 4: Standard Library Routine

CHAPTER 5: Real-Time Kernel

Quick Links

Need help?

Questions and answers

Related Manuals for Metrologic Optimus S

Summary of Contents for Metrologic Optimus S

This manual is also suitable for:

Table of Contents