RF Programming

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

• Low Level Programming, which allows you to program from any language, on any platform. It provides for strings of ASCII control sequences transmitted out a serial port. This method works with DOS, UNIX, Linux, Windows, etc. Click here for more information on the Low Level programming instructions.

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

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

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:

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

0@n,m,o,data

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:

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).

. Prior to RF Terminal version 9075, the RF Terminal was available only with a 4 line display. The "Clear lines" command (@Cx) for the 4 line displays differ slightly from the "Clear lines" command for the current 6 line displays. The following table shows the programming differences :

There are several other changes concerning the display in version 9075 and after:

. In order to use 6 line display terminals as 6 line terminals in a existing 4 line system, the Base Station must have firmware version DLC9075 or greater.

. In order to maintain compatibility with 4 line display terminals in an existing system, there is a new option in the RF Terminal Setup for 6 line display terminals. The LCD DISPLAY MODE allows the user to configure a 6 line display terminal as a 4 line display (centering the data on the display and conforming to the old programming command format, ie. @C05 clears all lines).

. The SIGN ON character for a 6 line display RF Terminal operating in 6 line display mode (see the previous point concerning LCD DISPLAY MODE) is different than for a 4 line display. Prior to 9075, all terminals signed on using ASCII 15. As of 9075, a 6 line display terminal operating in 6 line mode signs on using ASCII 22. If the 6 line terminal is configured for 4 line display, it signs on using ASCII 15, as do all terminals prior to version 9075. This allows you to use both types of display in the same system and be able to distinguish between the two terminal types.

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

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

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

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.

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:

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.

Prior to RF Terminal version 9075, all terminals signed on using ASCII 15. As of RF Terminal version 9075, in order to distinguish between 4 line and 6 line display terminals, an additional SIGN ON character was added. A 6 line display terminal configured as a 6 line display now sends ASCII 22 as its' SIGN ON character. A 6 line display terminal configured as a 4 line display will transmit the ASCII 15 character for SIGN ON. All 4 line display terminals regardless of their version, will SIGN ON using the ASCII 15 character.

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:

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:

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:

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:

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:

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 is 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 Application Programming Interface (API) for PromptCOM consists of the following functions:

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:

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:

---

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.

---