Toll Free 800-345-4220 (+831-458-9938)

CARTCart  

7000 RF Terminal Programming

 

There are 3 different methods available for programming on the RF Terminal system. The most common method is the:

next is for Windows only:

  • PromptCOM ActiveX is a drop in COM component that allows programmers to easily add the ability to send prompts to and receive data from their RF Terminal via an RF Base Station. It is compatible with Visual Basic, Visual C++, Delphi and most other Windows 32 bit developement platforms. Download the PDF programming guide.

and finally, Windows TCP/IP controls:

  • PromptNET TCP/IP ActiveX is a drop in COM component that allows programmers to easily add the ability to send prompts to and receive data from their RF Terminal via an RF Base station across a TCP/IP network connection. This configuration requires a "client" computer and a "server" computer. It is compatible with Visual Basic, Visual C++, Delphi, and most other 32-bit developement platforms. Download the PDF programming guide.

Low Level RF Programming

Messages from the host user program are written to the serial port to which the applicable Base Station is attached. Up to 64 RF Terminals can be controlled by one base station, so the host user program must address the applicable RF Terminal by its ID character. When the host receives a message from the Base Station, it will receive data with the Terminal ID also included. There are two types of messages; Host to Terminal and Base to Host.

Host to Terminal Programming
The basic format of a message that is transmitted from Host to Base to Terminal is fairly simple:

Byte position Function Possible values
1 RF Terminal ID

0-9,A-Z,a-z,=,-

2+ Command(s) **
Last Termination of message EOT (ASCII 4)

The RF Terminal ID is always the first byte and always only 1 character in length. There are 64 different possible values - the numbers 0-9, A-Z, a-z, =, or -.

The Command(s) section of the message always starts with the second byte and can consist of one or more commands - including data to be displayed or voice messages to be broadcast.

The last byte is always ASCII 4 (EOT) to terminate the message.

Here is a listing of valid commands and examples:

Command Characters Command Function
*@ Re-initializes all terminals
3@ Re-initializes Terminal #3
1@Bn Make Terminal #1 beep n (1-9) times
2@C0* Clears the entire screen (4 lines or 6 lines) on Terminal #2
0@C1 Clears line 1 on Terminal #0
1@C2 Clears line 2 on Terminal #1
2@C3 Clears line 3 on Terminal #2
0@C4 Clears line 4 on Terminal #0
3@C5* Clears line 5 on Terminal #3 (if 6 line display configured), Clears all lines if 4 line display configured.
1@C6* Clears line 6 on a 6 line display configuration.

1@C7 - 1@CF

Clears lines 7 thru 15 on a 15 line display. Will do nothing on a 4 or 6 line display. *See more about 4 and 6 line displays on page 6-4 in the Manual.

1@CX

Clears screen (same as @C0) and sets SMALL font, 15 lines with 26 characters per line

1@CY

Clears screen (same as @C0) and sets MEDIUM font, 10 lines with 20 characters per line

1@CZ

Clears screen (same as @C0) and sets LARGE font, 7 lines with 13 characters per line

1@C[fnfnfn...][\cb]

Clears screen (same as @C0) and sets font size for lines and sets default colors. f: Font Size can be L, M, or S for Large Medium, Small n: Number of lines to assign "f" to \cb defines User Default colors "c" is forground, "b" is background

1@Dn

Displays date and time on line n (1-4) in US (mm/dd/yy, hh:mm:ss) or Euro (dd/mm/yy, hh:mm:ss) format on Terminal #1

1@Vnn Play voice message #nn (01-99) on Terminal #1
1@Sdataxxxx

Output dataxxxxxxx to serial port on Terminal #1 -max 231chs

NOTE: The 15-line terminal defaults to small font on Sign-In.

Color Display Programming

New commands have been added to take advantage of the larger color display on the LT7001. You now have the ability to define the color and font size on a line by line basis.

There are 16 possible text and background colors available to choose from. They are the same 16 colors used in HTML programming.

The @C command has been expanded to set the foreground and background colors for the entire display and within the same command you can also set the font size for the entire display to all be the same or split up the display using different size fonts for each line.

The command structure is as follows:

@C[fnfnfn...][\cb]

@C are the 2 header bytes

f: is the font size and can be either S, M or L for small, medium or large

n: is the number of lines being defined. This is in single-character hexidecimal notation '1' through 'F' where 10='A' , 11='B', etc.

\cb: defines the user default colors, c=text color, b=background color

The \cb command can also change the active text/background color within a prompt at any time.

All screen formatting and color commands are dynamic and not stored in the unit so they will need to be sent at every sign-in.

The color codes are:

0 = AQUA 1 = BLACK 2 = BLUE 3 = FUCHSIA
4 = GRAY 5 = GREEN 6 = LIME 7 = MAROON
8 = NAVY 9 = OLIVE A = PURPLE B = RED
C = SILVER D = TEAL E = WHITE F = YELLOW

Here are some examples:

@CS2M2L2 will clear the screen and set the first two lines of the screen to be small fonts, the next two lines to be medium fonts, and the next two lines to be large fonts. Only 6 lines will be usable for prompts and data entry. The default colors will be used since there is no \cb at the end of the command.

followed by:

@1,1,0,\BEWarning@3,1,0,\21Invalid Data@5,1,1,\ACData will display "Warning" on the first line in small font with RED text on a WHITE background, "Invalid Data" on the third line in medium font with BLUE text on a BLACK background and "Data" on the 5th line in large font with PURPLE text on a SILVER background. The cursor will be positioned after the "Data" on the 5th line and entered text will be in the last color combination, PURPLE on SILVER.

Remember that if you only define 6 lines then you will only be able to use 6 lines. The remainder of the screen will be unusable and blank.

When you are defining the font size for each line of the screen be aware that the total pixel count of all the lines defined cannot exceed the height of the screen.

The total height of the screen is 240 pixels. A small font is 16 pixels tall, a medium font is 24 pixels tall and a large font is 32 pixels tall.

If you define 2 lines with small fonts, 2 lines with medium fonts and 2 lines with large fonts you will be using (2x16)+(2x24)+(2x32)=144 pixels out of a maximum of 240 pixels. The top 144 pixels of the display will be used, the bottom 96 pixels will be blank.

If you attempt to define a combination of fonts that exceeds 240 pixels total, a ? will be returned to the host for invalid command.

Here are some more examples:

@C\E1 will clear the screen and set the default colors to WHITE text on a BLACK background. In concept, @C\E1 is the same as @C0\E1; however, @C0\E1 is an invalid command. The change of user colors is always embedded in a Clear Screen Command.

@CS1M3L1S1L2\BE will clear the screen and set the first line to be small font, the next 3 lines to be medium font, the next line to be large font, the next line to be small font and the last two lines to be large font with RED text on a WHITE background for all lines. The total height of the lines will be (1x16)+(3x24)+(1x32)+(1x16)+(2x32)=200 pixels:

this is line 1

this is line 2

this is line 3

this is line 4

this is line 5

this is line 6

this is line 7

this is line 8

The active colors change whenever \cb is received in a prompt. The user default will be used to display all the prompts unless \cb changes the colors. All prompts will start with the user default. The active colors from the last prompt will NOT be carried over to the next prompt.

 

A typical "prompt" command sequence follows the format below:

0@n,m,o,[\cb]data

where:
n
is the line number (1-6) you want the prompt displayed on
 
m
is the character position (1-20) where you want the prompt displayed
 
o
is the character that determines whether the prompt is for display only (0) or is waiting for data input (1) See the table below for valid characters for this position.
 
\cb
optional colors if different from default. "c" is foreground, "b" is background
 
data
is the data you want displayed

For example, the command @1,1,1, Enter Quantity would display "Enter Quantity" starting at position 1 on line 1, then wait for the operator to enter their data.

These are valid entries for the third position character:

0 No data input for this Command, Display ONLY
1 Data input required from the keypad or scanner
2 Only keypad input allowed, start un-shifted
3 Only keypad input allowed, start SHIFTED
4 Only scanner input allowed
5 Only accept YES (Enter key) or NO (0 key) keypad response. (Terminal sends 1 for YES, 0 for NO)
A same as 1, but time stamped as prefix (hhmmss)
B same as 2, but time stamped as prefix (hhmmss)
C same as 3, but time stamped
D same as 4, but time stamped
E same as 4, but can press END key to break-out of scanner-only input mode. Terminal ID + CR is sent to host
S SHIFTED keypad input or scanner input
p un-shifted keypad entry with no display (for passwords)
P SHIFTED keypad entry with no display (for passwords)
R Data input required from the RS-232 serial port (waiting for serial input can be bypassed by pressing the ENTER key which will send a NULL data string back to host computer.)Uses for this are PDF 417 Serial Scanners, and the Cameo Printer's magnetic stripe input. A POS terminal becomes possible. Scan the credit card and print the receipt, all on the RF Terminal.
K Data input from an external serial keyboard that attaches to the serial port. As data is keyed, the characters are displayed on the RF Terminal LCD display.

Here are some rules and useful tips for creating commands:

. Re-initialize commands *@, or x@ clear the buffer for terminals in the Base Station. Following a re-initialization, the host program should re-display of all the screen data necessary to start the application.

. A message with multiple commands is legal and useful. For example, the command "@1,1,0, PLEASE ENTER@2,1,1,QTY" would display PLEASE ENTER on line 1, display QTY on line 2, then wait for data input. All 4 lines can be filled with one message.

. "Prompt" commands requesting data entry (third position character is 1) can only be combined with Clear statements @Cx and data display statements (third position character is 0). Multiple data entry "prompt" commands cannot be combined. For example:

@1,1,1,ITEM@2,1,1,QTY

is an illegal statement - it has two data entry "prompt" commands combined. If this command were sent to the RF Terminal, it would be ignored as a command and displayed on the terminal display exactly as written.

. The @S command (for serial output) statement cannot be combined with any other command - even clear (@Cx) commands. After a @S command is successfully completed, the Base Station sends back to the host the RF Terminal ID followed by a CR (ASCII 13). There is a 231 character limit on data for this command. Anything after 231 characters will be lost. If you are using the @S command with a printer, you should have the Protocol parameter in the RF Terminal set to XON/XOFF. This will allow the RF Terminal to deal with the character buffer limitations of your particular printer. If you are using the O'Neil MicroFlash Printer, you must send a NULL character before the valid data to wake up the printer. See your printer manual for details.

• The @M command is similar to the @S command, except it can be combined with other commands because it is a data entry command too. This command is for a printer initialization and magstripe input on the Zebra Cameo printer equipped with the magstripe option. The format of the command is:

@Mdddatttta(EOT)

where dddatttta might be ! U1 MCR 80 T1 T2+ CR + LF

(Refer to the Cameo manual for the exact string sequence you need to send. The above example sends over an 10 second request for reading Track 1 and Track 2). There is no reply to the host except the magstripe data. If the card cannot be read, pressing the ENTER key on the Terminal will send back ID+CR. This is the breakout method.

This command must be the last in a series of commands. For example, the following would be a typical multi-command statement:

@C0@1,1,0,Swipe Card@M! U1 MCR 80 T2 (CR)(LF)(EOT)

where CR is ASCII 13
LF is ASCII 10
EOT is ASCII 4

The statement causes the RF Terminal to transmit the string

!U1 MCR 80 T2 CR LF

to the Cameo printer. The printer then wakes up and blinks to indicate the magstripe input is ready to be swiped; when the swipe is complete, the Terminal sends back the data to the host computer as: ID+T2:Data on Card+CR (the printer's CR LF stuff is stripped). If the request is for Track 1 and Track 2, the data sent back is ID+T1:data on 1+T2:data on 2+CR.

. Every statement must end with a data entry "prompt" command, whether the statement is a single command by itself or several commands combined together. Any illegal statement will be ignored as a command but will be displayed on the addressed RF Terminal display exactly as written. If no Terminal ID was included in the statement, it will try to display the invalid statement on ID 0. Once the ENTER key is pressed on the Terminal displaying the invalid statement, the terminal sends the Base Station a "?" character. The Base Station then in turn sends the message n?CR (where n is the Terminal ID and CR is a carriage return) back to the Host computer. RF Terminal software versions prior to 9.059 did not handle illegal statements the same way; for backwards compatibility, see the setup parameter for Protocol (change it to E).

 

Here are some sample command statements utilizing some of the programming tips offered previously:

@2,1,1,ENTER ITEM NO Display ENTER ITEM NO on line 2, position 1 and wait for wait for data input
@V23@1,2,1,WRONG ITEM Play voice message 23, display WRONG ITEM on line1, position 2 and wait for data input
@C1@1,7,0,PICKING Clear line 1. Display PICKING at position 7 of line 1. This command by itself is illegal. To be a valid statement, it must end with a data entry request. For example: @C1@1,7,0,PICKING@2,7,1,ITEM
@1,1,1,ITEM@2,1,1,QTY Since only one command can be a "prompt" data entry request, this is an
illegal statement and would be ignored as a command.


Base Station to Host Formats
The basic format of a message that is transmitted from Base to Host is fairly simple:

Byte position Function Possible values
1 RF Terminal ID

0-9,A-Z,a-z,=,-

2+ Data Transmitted **
Last Termination of message CR (ASCII 13)

Typically, the Base Station is sending the "answer" to the hosts "question" - for example, if a Base sent a host message to a terminal #2 that said:

2@1,1,1,ITEM NUMBER + EOT

The RF Terminal would display ITEM NUMBER on line 1, position 1 and accordingly, the operator would then enter an item number by scanning or using the keypad. The RF Terminal transmits the data entered -say it's 123 - to the Base Station, which in turn transmits the following to the host:

2123+CR

where:
2
is the Terminal ID
 
123
is the data
 
CR
is the termination

Besides data, there are other messages that the Base Station will send to the Host:

Illegal Command
When a terminal receives an illegal statement from the host, it will display the entire statement on the terminal. Once the ENTER key is pressed on the terminal, the terminal sends a "?" back to the Base Station.

Byte position Function Possible values
1 RF Terminal ID

0-9,A-Z,a-z,=,-

2+ Illegal Command ?
Last Termination of message CR (ASCII 13)

For example, if Terminal #2 received an illegal command, the Base station would transmit to the host:

2?CR

Serial Reply
After a Serial command (@S) has been successfully completed, the Base Station sends to the Host the Terminal ID followed by a CR. If you don't have a serial device attached, this is a good way to check if a specific terminal is on-line and functioning.

SIGN ON
To login to the host computer, the user presses a key on the RF Terminal at power-up to get to the SIGN ON screen. As the user SIGNs ON, the Base Station sends back the following SIGN ON message to the host:

Byte position Function Possible values
1 RF Terminal ID

0-9,A-Z,a-z,=,-

2+ SIGN ON DC4 (ASCII 20) if 15-line color display terminal
    SYN (ASCII 22) if 15-line color terminal configured as a 6-line terminal
   

SI (ASCII 15) if 15-line color terminal configured as a 4-line terminal

Last Termination of message CR (ASCII 13)

After a terminal SIGNS ON, the host should be prepared to acknowledge the SIGN ON and give the terminal instructions, such as:

Standby for Assignment, Press ENTER to acknowledge
or
Nothing to do, Press ENTER and See Supervisor
or
Pick Item 1234

If there is something for the Terminal to do, the host should send instruction to the terminal (as in "Pick Item 1234" above). If there is nothing to do at the time of SIGN ON, the host should acknowledge the SIGN ON and tell the terminal to Stand By or See Supervisor (see lines 1 and 2 above). You will notice that in lines 1 & 2 above, there is a request for the operator to press the ENTER key. This is required for the message to be a valid command - remember that all messages must end with a request for data input. The host should then expect a response from the terminal of Terminal ID + CR.

SIGN ON is a good way for the terminal operator who has not received instruction from the host for several minutes to determine if he is still connected and if the host is still functioning. By SIGNing OUT and SIGNing back ON, the operator should receive a message that there is nothing to do. It is also a good idea for the host to keep track of elapsed time that a terminal has not had a message sent out to it. The host should then send a message periodically to re-assure the operator (remember to ask him to press ENTER) that instruction is coming or tell him to see his supervisor for re-assignment (or whatever makes sense for your application).

Ideally, if the operator is leaving the area (to go to lunch or move to another building) before he is out of range of the network, he should SIGN OUT, then SIGN ON upon his return. An alternative is to have the operator press the END key followed by the ENTER key before he leaves. This could trigger a prompt from the host to send a message saying " Press BEGIN when ready again". Upon the operators return, he would press the BEGIN key followed by the ENTER key, allowing him to receive a message immediately.

SIGN OUT
When a RF Terminal is powered down manually or the user presses the F1 key to exit data entry mode to go to one of the other modes (SETUP or ONE WAY), the host receives the following SIGN OUT message:

Byte position Function Possible values
1 RF Terminal ID

0-9,A-Z,a-z,=,-

2+ SIGN OUT SO (ASCII 14)
Last Termination of message CR (ASCII 13)

Addressing a Terminal not SIGNed ON
If the host attempts to send a message to a terminal that is not SIGNed ON, the Base Station sends back the following message to the host computer:

Byte position Function Possible values
1 RF Terminal ID

0-9,A-Z,a-z,=,-

2+ Terminal NOT Signed In DC1(ASCII 17)
Last Termination of message CR (ASCII 13)

The ASCII 17 character can be changed to ASCII 16 for XON/XOFF sensitive systems by changing the Base Station Setup.

Sequence Error Message
The one-for-one "host prompt/terminal response" protocol must be observed by the host program at all times. The host cannot send a second data entry prompt until it has received a response to the first data entry prompt. If it does, this is considered a Sequence Error. If the Base Station receives a command that is out of sequence, it sends the following message back to the host:

Byte position Function Possible values
1 RF Terminal ID

0-9,A-Z,a-z,=,-

2+ Sequence Error DC2(ASCII 18)
Last Termination of message CR (ASCII 13)

If the Base Station receives 5 Sequence Errors in a row, it transmits the following message to the Terminal and shuts down:

Base Shut Down
Due to Host Logic
Error

Check your program for the sequence error before starting again. You will have to cycle power on the Base Station and have the Terminal Sign On again in order to continue.

Base Station Initialized Message
Whenever the Base Station is powered up, it sends a message back to the host as follows:

Byte position Function Possible values
1 BASE ID

* (Base ID is fixed)

2+ Base Initialization DC3 (ASCII 19)
Last Termination of message CR (ASCII 13)

Since ASCII 19 is XOFF, the ASCII 19 character can be changed to ASCII 20 for XON/XOFF sensitive systems by changing the Base Station Setup.

The Base Station Initialized message is provided so that the host will know that there has been a power interruption on the Base Station. When a serial device powers up, the first byte transmitted is often garbage. QBASIC handles the garbage character without incidence, but GWBASIC does not unless ON ERROR GOTO is used to trap the error. Be aware of this potential garbage-byte problem in your programming. To isolate and test for the problem, power up the Base without the serial cable connected. After you power the Base up, plug in the serial cable. You will not see the "Base Initialized" message but it should not matter when testing for the garbage data.

Transmitting ASCII characters using the terminal keypad
There are some keys on the RF Terminal keypad that when pressed, can transmit special ASCII characters back to the host program. This feature might be used by a programmer to allow the operator to review transactions. The keys are as follows:

Key Code transmitted to Host
UP ARROW key FS (ASCII 28)
DOWN ARROW key GS (ASCII 29)
LEFT ARROW key RS (ASCII 30)
RIGHT ARROW key US (ASCII 31)
BEGIN key ETB (ASCII 23)
END key CAN (ASCII 24)
SEARCH key VT (ASCII 11)

The STATUS key is reserved to only display the Time and Date.

For these codes to be transmitted, there are a few rules to follow:

  • They cannot be part of a multi-character data entry. In other words, they cannot be used in combination with other data. If another key has been pressed, these special keys are ignored. If you are using the SHIFTED character on one of the special keys, it is accepted as the shifted character.

  • For these keys to be transmitted, they must be pressed individually and exclusively and MUST be followed by the ENTER key.

  • The ARROW keys can be used without pressing the ENTER key by using the Arrow Keys Only Terminal Setup parameter.

DLL for Windows Programmers

If you cannot use the ActiveX or TCP/IP ActiveX components, there is a DLL included with every RF Terminal system. To install the program, run the INSTALL.EXE program from Windows Explorer. The program, PromptCOM comes in both 16 bit and 32 bit versions of a Windows Dynamic Link Library (DLL) that allows programmers to easily add the ability to send prompts and receive data from their RF Terminal via the RF Base Station or direct serial link.

The DLL will only work with 4-line 70 series and 6-line 70 or 700 series terminals, or on the new 7000 series 15-line color terminal configured as a legacy 6-line or 4-line terminal

The Application Programming Interface (API) for PromptCOM consists of the following functions:

InitComDLL Initializes the PromptCOM system
CloseComDLL Shuts down the PromptCOM system and frees resources without closing the parent application.
Setup Setup is used to configure the com port
SendCommand This function both sends a command to the terminal with the given ID
GetCommData This function returns the data entered at the remote unit for that prompt
DataAvailable Use this function to check if there is data to process before calling GetCommData

There are sample programs distributed on the diskette for Visual Basic, Access and Delphi. There is also a Visual Basic code example that does not require the DLL. Use the Help System as documentation and view the README file for the latest changes.


Changing the Base Station parameters from the Host

Once a Base Station has been hung from a ceiling or other high place, you don't want to have to get a ladder every time you need to change one of the Setup Parameters on it. To allow for this situation, there is a way to change all of the Setup Parameters except frequency from the host computer. The command for the Base Station Setup follows this format:

@@*S b r p d s l aa EOT

Where:

Letter Parameter Possible values
@@*S
message prefix always @@*S
b
baud rate

0=300
1
=600
2=1200
3
=2400
4=4800
5
=9600
6
=19200

r
XON/XOFF Sensitive 0=NO
1=YES
p
Parity 0=None
1=even
2=odd
d
Data Bits 0=7 bits
1=8 bits
s
Stop Bits 0=1 bit
1=2 bits
l
Listening to: 0=Terminals and Relays
1
=Relays Only
a
future use use 0 for present
a
future use use 0 for present
EOT
Host to Base message terminator always EOT (ASCII 4)

If the command does not have the exact length of all bytes present and/or any byte does not have a valid value, the command will be ignored. Be careful when using this command as it does change the way you communicate with the Base station. Your program must make the same adjustments immediately in order to resume communication.

The command for the Relay Station Setup is:

@@nSmEOT

where:

Letter Parameter Possible Value
n current Terminal ID

0-9,A-Z,a-z,=,-

m new Terminal ID 0-9,A-Z,a-z,=,-
EOT Host to Base always EOT (ASCII 4) message terminator

Host to Base Link Testing

You can also issue a command to test the data transmission to and from the base from the host. The command format is:

@@*Edataaaaaa<EOT>

where:

dataaaaaa


is any string of data sent in the command terminated by EOT (ASCII 04). If the data is received by the Base, it is echoed back to the host for reading in the format:

dataaaaaa<CR>

where dataaaaaa is the echoed data string and CR is the termination character. This verifies both directions of traffic to the Base.