Wavenet Technology BM29001 Wireless OEM Modem Module User Manual BOOMER

Download:
Mirror Download [FCC.gov]
Document ID	279700
Application ID	fodO6R8vgG//7u+3+4qR6Q==
Document Description	ex9 manual
Short Term Confidential	No
Permanent Confidential	No
Supercede	No
Document Type	User Manual
Display Format	Adobe Acrobat PDF - pdf
Filesize	145.28kB (1816051 bits)
Date Submitted	2002-10-29 00:00:00
Date Available	2003-01-21 00:00:00
Creation Date	2002-10-05 11:33:28
Producing Software	Acrobat PDFWriter 4.0 for Windows
Document Lastmod	2002-10-29 12:40:45
Document Title	BOOMER.PDF
Document Creator	Microsoft Word
Document Author:	ArtB

Consulting * Research * Training *Certification Testing Since 1981
FCC ID: PQS-BM29001
Exhibit 9 for Boomer II 900 MHz
User’s Manual
October 2002
APREL Project No.: WVTB-Boomer II Modem-3922-2
Boomer II
OEM Modem
User Manual
and
Integrator’s Guide
August 2002
© Wavenet Technology Pty Ltd
ACN 079 965 003
Publication No. BM210012WT11 (11 September 2002)
Published August 2002
This publication is copyright and no part may be reproduced or copied without the prior consent of:
Wavenet Technology Pty Ltd.
140 Burswood Rd
Burswood, 6100
Western Australia
Telephone:
Facsimile:
E-mail:
Web Site:
+61 8 9262 0200
+61 8 9355 5622
wavenet@wavenet.com.au
www.wavenet.com.au
This manual is intended to be used for the operation of Wavenet Technology equipment. Performance
figures quoted are typical values and subject to normal manufacturing and service tolerances.
Wavenet Technology Pty Ltd reserves the right to alter, without notice, the equipment, software or
specification to meet technological advancement.
Microsoft, Windows and the Windows logo are registered trademarks or trademarks of Microsoft
Corporation in the United States and other countries. Other product and company names herein may be
the trademarks of their respective owners.
Whilst every precaution has been taken in the preparation of this document, neither Wavenet
Technology Pty Ltd nor any of its representatives shall have any liability to any person or entity with
respect to any liability, loss or damage caused or alleged to be caused directly or indirectly by the
information contained in this book.
Published by Wavenet Technology Pty Ltd.
This device has not been authorized as required by the rules of the Federal Communications
Commission (FCC). This device is not, and may not be, offered for sale or lease, or sold or leased
within the USA, until authorization is obtained.
This product contains a transmitter approved under the FCC rules.
800MHz Modem FCC ID: PQS-BM28001
900MHz Modem FCC ID: PQS-BM29001
This device complies with Part 15 of the FCC rules.
Operation is subject to the following two conditions:
(1) This device may not cause harmful interference, and
(2) This device must accept any interference received including interference that may cause undesired
operation.
Boomer II User Manual & Integrator’s Guide __________________________________________________Contents
Contents
Introduction...................................................................................................................7
Applications ..............................................................................................................8
Compliance Statement ...........................................................................................9
Information for Your Safety................................................................................. 10
Host Requirements............................................................................................... 11
Installation.................................................................................................................. 13
Mounting the Boomer II OEM Modem to Your Device ................................... 14
Connecting the Data Interface Port ................................................................... 15
Pin Descriptions ................................................................................................ 15
Serial Communications Interface................................................................... 16
Status Input / Output lines............................................................................... 17
LED Interface .................................................................................................... 17
Connecting & Positioning the Antenna ............................................................. 20
Positioning ......................................................................................................... 20
Supplying Power................................................................................................... 21
Batteries............................................................................................................. 21
Plug-in Supplies................................................................................................ 21
Automotive Supplies ........................................................................................ 22
Environmental Considerations ....................................................................... 22
Test Jig....................................................................................................................... 23
Features ................................................................................................................. 23
Exploring the Boomer II Test Jig........................................................................ 24
Initial Calibration ................................................................................................... 27
Set Up..................................................................................................................... 28
RSUSER................................................................................................................ 30
Operations ......................................................................................................... 30
Using RSUSER................................................................................................. 31
Hot Key Descriptions........................................................................................ 31
Reprogramming Modems................................................................................ 35
Software Development Kit....................................................................................... 37
Native Control Language Application Programmer’s Interface..................... 38
Implementation.................................................................................................. 38
Logical Architecture.......................................................................................... 39
Application Interface......................................................................................... 41
Standard Context Routing Application Programmer’s Interface ................... 58
Implementation.................................................................................................. 59
SCR Structures ................................................................................................. 59
BM210012WT09
Wavenet Technology
Contents _________________________________________________ Boomer II User Manual & Integrator’s Guide
SCR Functions .................................................................................................. 64
Application Development......................................................................................... 77
Roaming Issues .................................................................................................... 78
Roaming Requirements................................................................................... 78
Inbound SDU Failures ..................................................................................... 80
Outbound SDU Failure .................................................................................... 81
Loss of Network Contact ................................................................................. 81
Power Management ............................................................................................. 82
PowerSave Mode ............................................................................................. 82
Inactivity Time-Out............................................................................................ 82
On/Off upon User Demand ............................................................................. 83
Radio On/Off on Application Command........................................................ 83
Battery Life Considerations ............................................................................. 83
PowerSave Protocol......................................................................................... 83
Wireless Data Systems Considerations............................................................ 84
Application Efficiency....................................................................................... 85
Large Message Transfer ................................................................................. 85
Message Transit Time ..................................................................................... 85
Message Routing and Migration ............................................................................ 88
Message Routing.............................................................................................. 88
Network Link Layers......................................................................................... 89
Standard Context Routing (SCR)....................................................................... 90
SCR Message Types ....................................................................................... 91
Highlights of SCR Differences........................................................................ 91
SCR Header Charts ............................................................................................. 95
Host Request Message Header Fields ......................................................... 96
Host Confirmation Message Header Fields ................................................. 98
Mobile Information Message Header Fields...............................................100
DataTAC Messaging (DM)................................................................................102
DM Message Types .......................................................................................102
Highlights of DM Differences ........................................................................102
DM Header Charts..............................................................................................103
Message Generate Header Fields...............................................................103
Receive Header Fields ..................................................................................105
Host Messaging (HM)........................................................................................107
Other Development Issues ...............................................................................107
Localizing an Application...............................................................................107
Testing an Application...................................................................................108
Appendix A - NCL Interface ..................................................................................110
Generic NCL (Native Mode)..............................................................................110
Wavenet Technology
BM210012WT09
Boomer II User Manual & Integrator’s Guide __________________________________________________Contents
Command SDUs (CMND, ASCII A).....................................................110
Event Report SDUs (EVENT, ASCII B) ..............................................113
Response Status SDUs (RESP, ASCII C) .........................................114
Wavenet specific NCL Extensions ...................................................................116
GET STATUS COMMANDS:................................................................116
Generic set RPM Configuration command (WN_SET_PARAM):...121
Generic get RPM Configuration command (WN_GET_PARAM): ..123
NCL Label Values...................................................................................124
SAR Routine Function .......................................................................................125
SAR Algorithm.....................................................................................................126
Appendix B - Sample Programs...........................................................................127
Client Application................................................................................................127
Server Application ..............................................................................................130
Initialisation and Login ...................................................................................131
Appendix C - Wavenet Application Loader.........................................................133
Updating Application Loader Software on Your Modem ..............................133
Troubleshooting ..................................................................................................135
Appendix D - Numeric Conversion Chart ...........................................................137
Appendix G - Specifications..................................................................................139
BM210012WT09
Wavenet Technology
Contents _________________________________________________ Boomer II User Manual & Integrator’s Guide
Wavenet Technology
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________________________Introduction
Introduction
The Boomer II OEM Modem is a radio packet modem, intended for
use on the Motorola DataTAC 4000 SFR and DataTAC 5000 MFR
data communication networks.
It is primarily designed to be integrated into customer equipment as an
OEM modem. There are two versions available, an 800MHz version (A
band) and a 900MHz version (B band).
The modem interfaces to the equipment’s controller by using the data
interface port. The protocol supported over this link is Native Control
Language (NCL).
Although the modem has embedded software, it has no built in
application software. All application software must be separately
installed and run from the device to which the modem is connected.
A Software Development Kit (SDK) is available and described later in
this manual to assist this process.
A picture of the Boomer II OEM Modem is shown below.
RF Connector
LED
Window
Data Interface Port
This manual contains the following sections:
Section 1: General product information.
Section 2: Installation Guide.
Section 3: Test Jig and Boomer II Evaluation Guide.
Section 4: Software Development Kit Guide for the modem interface
(NCL) and the network host interface (SCR).
Section 5: Client Application Guide.
Section 6: Message Routing Guide.
BM210012WT09
Wavenet Technology
Introduction _______________________________________________ Boomer II User Manual & Integrator’s Guide
Features
The Boomer II OEM modem is approximately the size of a credit card
and just 9mm thick. The modem is easily connected to many other
devices and can be incorporated into a variety of package formats. The
modem has a TTL serial port.
The Boomer II OEM Modem has the following features:
Serial communications interface port (TTL level)
running an NCL protocol
Indicator lights shows the status of the network coverage and
power supply
Four configurable digital input/output lines for external
control/monitoring
Software configurable RF calibration adjustments to suit
specific networks
High sensitivity reception
Small footprint and low profile design
Low-voltage and low standby current consumption for battery
based products
Auto-wake up of host on incoming messages
Roaming capabilities as used in DataTAC system
Modem is always online using the DataTAC network
Easy to install, service and update
Applications
Suitable devices in which the Boomer II OEM Modem can be used
include the following applications:
Meter Reading
The modem can be used to read billing information from intelligent
electrical meters and basic disc meters. Data is transmitted wirelessly
through a radio network to billing computers.
EFTPOS
The modem can perform handshaking and complete verification of all
data transmitted through the wireless network.
Vending Machines
Vending machines can also utilise radio data technology. Many
machines already transmit usage and refill requirements to company
head offices via standard telephone lines. Radio modems allow vending
machines to be placed in areas with poor access to telecommunications
infrastructure, providing a cost-effective alternative to installing new
telephone lines. On refilling, only the required refills will be
Wavenet Technology
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________________________Introduction
despatched to the required sites maximising truck carrying capacity and
consequently efficiency.
Fire Alarm Detection
Conventional telephone wire connections are slow to dial out and can
burn before the emergency call can be placed. Laws in many states and
countries require businesses to have an on-line dial out fire alarm
system. The Boomer II OEM Modem offers a real solution to this
problem.
Parking, Buses and Ticketing
Ticketing machines are being be converted to cashless operation. The
Boomer II OEM Modem is the best alternative to facilitate the
introduction of this cashless technology.
Compliance Statement
This device has not been authorized as required by the rules of the Federal
Communications Commission (FCC). This device is not, and may not be, offered
for sale or lease, or sold or leased within the USA, until authorization is obtained.
The Boomer II modem is supplied as an OEM Modem Module for
integration into a customer specific product. This combined product
will have it’s own antenna, RF cable and unique FCC ID. This
combined product will require its own testing by an FCC testing house
and submission to the FCC for approval.
This equipment generates, uses and can radiate radio frequency energy
and, if not installed and used in accordance with the manufacturer’s
instructions, may cause interference harmful to radio communications.
There is no guarantee however, that interference will not occur in a
particular installation. If this equipment does cause harmful
interference to radio or television reception, which can be determined
by turning the equipment off and on, the user is encouraged to try to
correct the interference by one or more of the following measures:
Reorient or relocate the receiving antenna.
Increase the separation between the equipment and receiver.
Connect the equipment into an outlet on a circuit different from
that to which the receiver is connected.
Consult your supplier or an experienced radio/TV technician
for assistance.
Warning : Changes or modifications to this unit not expressly
approved by the party responsible for compliance could void the user’s
authority to operate this equipment.
BM210012WT09
Wavenet Technology
Introduction _______________________________________________ Boomer II User Manual & Integrator’s Guide
Information for Your Safety
Please read these safety instructions and the operation instructions
provided in this manual before operating the Boomer II OEM Modem.
Safe Use
Switch the modem off in areas where radio devices are forbidden, or
when it may cause interference or danger. For example, fuel depots
(fuel storage and distribution areas), chemical plants, locations in
which hazardous or combustible gases may be present and where
blasting operations are in progress.
Do not use the modem in an aircraft. Such use may affect aircraft
instrumentation, communication and performance and may be illegal.
Be aware that the modem may interfere with the functionality of
inadequately protected medical devices, including pacemakers.
Additionally, the effect of the radio signals from the modem on other
electronic systems, including those in your car (such as electronic fuelinjection systems, electronic anti-skid braking systems, and electronic
cruise-control systems) may affect the operation of these systems,
which should be verified before use in the applications
Do not place the modem on an unstable surface. It may fall and damage
the equipment.
Never push objects of any kind into the modem through openings as
they may short out parts that could result in a fire or electrical shock.
Never spill liquid of any kind on the modem. Do not use the modem
near water (for example near a bathtub or sink, in a wet basement, near
a swimming pool etc.). The modem should be situated away from heat
sources.
Disconnect the modem from the power source before cleaning. Do not
use liquid or aerosol cleaners. Use a damp cloth to clean the unit.
Disconnect the modem from the power source and contact your
supplier if:
Liquid has been spilled or objects have fallen onto the modem.
It has been exposed to rain or water.
It has been dropped or damaged in any way.
It does not operate normally by following the instructions
contained in this manual.
It exhibits a distinct change in performance.
Failure to observe all these instructions will void the limited warranty.
Wavenet Technology
10
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________________________Introduction
Host Requirements
The minimum system requirements of the host interface PC in order to
utilise the Software Development Kit (SDK) are:
BM210012WT09
Intel compatible Pentium computer or higher
Windows 95 or later
16MB RAM (memory) minimum, 32MB recommended
1MB available hard disk space
9-pin serial Port using a 16550 UART
3.5-inch Disk Drive
CD-ROM drive
11
Wavenet Technology
Introduction _______________________________________________ Boomer II User Manual & Integrator’s Guide
Wavenet Technology
12
BM210012WT09
Boomer II User Manual & Integrator’s Guide _________________________________________________Installation
Installation
This section will help you to successfully integrate the Boomer II OEM
Modem into your custom application. Before using your modem you
must:
Mount the Boomer II OEM Modem to your device
Connect the Data Interface Port
Connect and position the antenna
Supply power
A picture of the Boomer II OEM Modem is shown below.
RF Connector
LED
Window
Data Interface Port
The modem has the following interfaces:
Data Interface Port
30-way connector
LED Window
Power
LED
Green, flashes when scanning
On, when locked
Off, when the modem is off
Receive
LED
Green, flashes when receiving
Transmit
LED
Red, flashes when transmitting
RF Connector
BM210012WT09
MMCX female socket
13
Wavenet Technology
Installation ________________________________________________ Boomer II User Manual & Integrator’s Guide
Mounting the Boomer II OEM Modem to Your Device
The Boomer II OEM Modem has an M2 Mounting Bolt hole in each
corner, which should be used to bolt the modem onto an appropriate
surface. The mounting hole pattern is four holes in a 60mm X 46mm X
42mm trapezoid, with each hole to suit an M2 (2.0mm) bolt. Refer to
the following diagram.
52
70
Hole diameter:
4 x 2.30mm
Fixing screw size:
M2
Top View
Side View
Mounting Details
The mating surface should be flat and ensure a rigid mounting for the
modem to minimise the transmission of vibration to the unit.
There should be an adequate supply of airflow to ensure the modem’s
temperature limits are not exceeded.
Wavenet Technology
14
BM210012WT09
Boomer II User Manual & Integrator’s Guide _________________________________________________Installation
Connecting the Data Interface Port
There are two connectors to interface the Boomer II OEM Modem with
your device.
RF Connector (described in the next section), and
Data Interface Port
The data interface port is used to interface the modem to a serial
computing device and a power supply. The power supply requirements
are described in the next section.
A flat 30-way Flexible Printed Circuit (FPC) cable 0.3mm thick with
1mm centreline spacing is used between the Boomer II OEM Modem’s
data interface port and your device.
The asynchronous serial interface on the Boomer II OEM Modem
operates at 3V and can be controlled by a wide variety of
microcontrollers and microprocessors. The modem can be connected
directly to a microcontroller or through a universal asynchronous
receiver/transmitter (UART) to a microprocessor data bus.
If the modem is to be connected directly to a PC or other RS232
device, an interface must be provided to convert the signal voltage to
the higher values required by an RS232 device.
Data Interface Pin Descriptions
Pin
BM210012WT09
Signal
Description
DCD
Data Carrier Detect
RXD
Receive Data
TXD
Transmit Data
DTR
Data transmit ready
GND
Ground
DSR
Data Set Ready
RTS
Request to Send
CTS
Clear to Send
RI
Ring Indicator
10
HCRESET
Modem Reset
11
TEST PIN
Not connected
12
HOSTPWR_ON
Modem Power on/off
13
LED0_MSGWTG
Message Waiting
14
LED1_INRANGE
In Range
15
LED2_LOWBAT
Low Battery
16
SS0/RXD2
Status Signal 0
17
SS1/TXD2
Status Signal 1
18
SS2
Status Signal 2
15
Wavenet Technology
Installation ________________________________________________ Boomer II User Manual & Integrator’s Guide
19
SS3
Status Signal 3
20
HOST 3.8V
Supply Voltage (3.4 – 4.2V)
21
HOST3.8V
Supply Voltage (3.4 – 4.2V)
22
HOST 3.8V
Supply Voltage (3.4 – 4.2V)
23
HOST3.8V
Supply Voltage (3.4 – 4.2V)
24
TEST-PIN
Not connected
25
HOST GND
Ground
26
HOST GND
Ground
27
HOST GND
Ground
28
HOST GND
Ground
29
TEST-PIN
Not connected
30
TEST-PIN
Not connected
Serial Communications Interface
The modem communicates with the controller using the Data Interface
Port connection interface. The protocol supported over this link is the
Native Control Language (NCL). The data format for NCL is: 8 data
bits, no parity, 1 stop bit.
The serial interface lines (RXD, TXD, DCD, DTR, DSR, RTS, CTS,
RI) are TTL compatible. They are fitted with a 33Ù series resistor and
clamp diode to the internal supply line for protection. The electrical
interface capability of these signals is as follows:
Input Voltage Range
0 – 3.3V or 0 - 5V
Output Voltage Range 0 - 3.3V
Current Source/Sink
± 3mA (maximum)
The operation and active condition of these lines is summarized below.
Serial Communications Interface Definitions
Wavenet Technology
J1
Pin #
Signal
Description
Signal
Active State
DCD
Data Carrier Detect
Output
Low when modem in-range
RXD
Receive Data
Output
Low when active
TXD
Transmit Data
Input
Low when active
DTR
Data transmit ready
Input
Low when ready
DSR
Data set ready
Output
Low when ready
RTS
Request to send
CTS
Clear to send
Output
High when modem requires
data throttling
RI
Ring indicator
Output
Pulses Low when messages
are waiting
16
Input
High when host requires data
throttling
BM210012WT09
Boomer II User Manual & Integrator’s Guide _________________________________________________Installation
Status Input / Output lines
Note: Not currently supported but may be added in future releases.
The status lines (SS0 to SS3) may be software configured for bidirectional operation. Each line has a 33Ù series resistor and clamp
diode to the internal supply line for protection. The electrical interface
capability and function of these signals are as follows:
Input Voltage Range
0 – 3.3V or 0 - 5V
Output Voltage Level
0 - 3.3V
Current Source/Sink
± 3mA (maximum)
The operation and active condition of these lines is summarized below.
Status Input/Output Interface Definitions
J1
Pin #
Signal
Description
Signal
16
SS0
Status Signal
Input/ Output
User configurable (future option)
17
SS1
Status Signal
Input/ Output
User configurable (future option)
18
SS2
Status Signal
Input/ Output
User configurable (future option)
19
SS3
Status Signal
Input/ Output
User configurable (future option)
Active State
LED Interface
The modem provides three on-board indicators (LEDs), for diagnostic
monitoring purposes as well as three modem controllable LED outputs
through the Data Interface Connector.
On-Board LED Indicators
The on-board LEDs are visible through a small window in the case of
the modem. In order of sequence (from left to right when viewing the
modem facing the data interface connector) the LEDs are as follows:
Power
LED
Transmit
BM210012WT09
Green flashes when power normal and scanning for
channel
On
when power normal and locked on channel
Off
when the modem is off
Red
flashes when data is transmitted
17
Wavenet Technology
Installation ________________________________________________ Boomer II User Manual & Integrator’s Guide
LED
Receive
LED
Wavenet Technology
Green flashes when data is received
18
BM210012WT09
Boomer II User Manual & Integrator’s Guide _________________________________________________Installation
LED Output Lines
In addition to the on-board LEDs there are three signal lines (Low
Battery, Message Waiting, In-range), which are controllable by the
modem for connection to an external LED. Each line has a 33Ù series
resistor and clamp diode to the internal supply line for protection. It is
recommended a series resistor be used with the external LED to limit
current accordingly. The electrical interface capability and function of
these signals are as follows:
Output Voltage Level
0 – 3.3V
Current Source/Sink
± 3mA (maximum)
The operation and active condition of these lines is summarized below.
LED Interface Definitions
J1
Pin #
Signal
13
14
15
Description
Signal
Active State
LED 0_ MSGWTG
Message
waiting
Output
Low when message waiting
LED 1_ INRANGE
In range
Output
Low when modem in-range
LED 2_ LOWBAT
Low battery
Output
Low when battery is less than
3.5V,
High when battery is greater
than 3.6V
Low Battery
The Low Battery signal is held active low whenever the supply voltage
drops below an acceptable level (less than 3.5V) and deactivated when
the voltage level becomes acceptable again (greater than 3.6V). The
transitions will occur at the same time as the low battery event occurs
(or would occur if the event was activated). Note that in the case of a
very fast transition between voltages, it may take up to 20 seconds for
the modem to confirm a change in battery status.
Message Waiting
The Message waiting signal is held active low whenever there is at
least one message waiting in the inbound buffers to finish being sent to
the network, or at least one complete message in the outbound buffers
which hasn’t been sent to the local device.
In-Range
The In Range signal is held active low whenever the modem is in
range. It tracks the function of the Data Carrier Detect (DCD) signal.
BM210012WT09
19
Wavenet Technology
Installation ________________________________________________ Boomer II User Manual & Integrator’s Guide
Connecting & Positioning the Antenna
The Boomer II OEM Modem provides an MMCX RF connector
interface located at the top of the unit, to attach to the antenna cable.
The antenna does not plug directly into the modem but uses an antenna
cable to interface between your device and the modem.
The antenna cable should be a low loss, 50Ω impedance and have a
MMCX plug that can mate with the modem’s MMCX socket
(82MMCX-S50-0-2). It is recommended that a Huber+Suhner
connector be used to connect to the modem as below;
11 MMCX
Straight Connector
16 MMCX
Right Angle Connector
If an extension cable is required to the antenna, it should be low loss, as
short as possible and an impedance of 50 ohms. Proper matching
connectors should be used, as each connector introduces a return loss
and reduces performance.
The minimum requirements for the antenna used with the Boomer II
OEM Modem are:
Impedance:
50Ω
Centre Frequency:
833MHz ± 5MHz
Frequencies of operation:
806 to 825MHz (transmit)
851 to 870MHz (receive)
Acceptable return loss:
VSWR < 1.5 or RL < -14dB (recommended)
VSWR < 2.0 or RL < -10dB (minimum)
The power output of the Boomer II OEM Modem is nominally 1.8W at
the antenna port. The antenna gain or loss will affect this value.
Positioning
Positioning the antenna will affect the gain provided by the antenna.
The antenna should be orientated so that it provides vertical
polarisation as the DataTAC network is based on vertically polarised
radio-frequency transmission.
The antenna should be located as far from the active electronics of the
computing device as possible. Typically, a metal case of a computing
device and its internal components may attenuate the signal in certain
directions. This is undesirable as the sensitivity and transmit
performance of the Boomer II would be reduced. However, careful use
of metal used for the ground plane for an antenna can improve the
antenna gain and the coverage area for the system.
If your device is designed to sit on a surface, the antenna should be
positioned as far from the bottom of the device as possible. This is to
Wavenet Technology
20
BM210012WT09
Boomer II User Manual & Integrator’s Guide _________________________________________________Installation
reduce the radio frequency reflections if the device is placed on a metal
surface.
If your device is hand held or is worn next to the body, the antenna
should be positioned to radiate away from the body.
Supplying Power
The Boomer II OEM Modem must be provided with a clean power
source capable of delivering bursts of high current.
The modem draws its power in bursts. The power required changes
rapidly depending on whether the modem is transmitting, receiving or
on standby.
The power supply requirements are:
Voltage:
3.8V (3.4 to 4.2V range)
Transmitter:
1.7A
Receiver:
85mA
Transmit Duration:
32ms (minimum)
1s (maximum)
Off current consumption:
< 100µA
Power Supply Ripple:
< 15mV peak to peak
Batteries
The Boomer II OEM Modem may be powered by batteries if used with
a handheld device.
Nickel cadmium (NiCad) batteries may be used for devices requiring
wide temperature ranges. Nickel metal hydride (NiMH) and lithium ion
(Li+) batteries may also be used for devices utilised above 0ºC.
Specifications for these batteries should be obtained from the
manufacturer.
The selected battery must be able to meet the Boomer II power
requirements as mentioned previously.
Plug-in Supplies
A mains plug-in supply must be designed to ensure that voltage spikes,
lightening and other power fluctuations cannot damage the Boomer II.
Transient voltage protection zener diodes or other spike arrestor
circuits may be added to keep the inputs within the power requirements
mentioned previously. These should have a value of 20V and be placed
on the supply side of the regulator circuit.
BM210012WT09
21
Wavenet Technology
Installation ________________________________________________ Boomer II User Manual & Integrator’s Guide
Automotive Supplies
Extra protection is required from an automotive supply to protect the
Boomer II OEM Modem from power fluctuations when used in an
automobile.
The electrical transient conditions (e.g. battery jump start), may
damage the modem if not adequately clamped and filtered.
Environmental Considerations
The environmental requirements of the Boomer II OEM Modem are as
follows:
Operating Temperature:
-30° to +60°C
Storage Temperature:
-40° to +70°C
You should ensure these limits are not exceeded in the intended
application.
Wavenet Technology
22
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________________________Test Jig
Test Jig
The Boomer II Test Jig provides RS-232 serial interface ports between
a PC and the modem. It is designed to enable you to quickly interface
the Boomer II to a standard PC (through a COM port) or a terminal
device with an RS-232 serial port.
The test jig acts as a temporary host for the modem and provides access
points to the radio’s communication port, allowing you to monitor
activity with a logic probe, multimeter or oscilloscope.
Features
All Input/Output Lines configurable by jumpers and/or
accessible through parallel FPC connector.
On-board dual RS232 Serial Communication interface ports
with DB9 connectors
Through the SPY MODEM connector, you can monitor the data
transmitted from the modem (RX, DSR, and CTS).
Through the PORT 2/SPY PC connector, you can monitor the
data transmitted from the PC (TX, RTS and DTR), or talk to the
second serial port of the modem. You can make this choice by
putting all five jumper links on the right or left side of the RDW
header connector near the port.
Switches and LED indicators on SS0 - SS3 modem I/O lines.
On-board voltage regulator for Boomer II OEM supply rail.
On-board LEDs for three external signals:
Low battery
Message waiting
In range
BM210012WT09
On-board antenna matching network allowing conversion from
MMCX to SMA connectors.
23
Wavenet Technology
Test Jig __________________________________________________ Boomer II User Manual & Integrator’s Guide
Exploring the Boomer II Test Jig
The test jig comprises the following components:
DC Jack
Input Supply
On/Off
Switch
3 RDW
Header
connector
VCC
test pin
3.15A Fuse
5X20mm
Port 2 / SPY PC Interface
DB9 Connector
8-way
DIP switch
SPY Modem Interface
DB9 Connector
ADJ VCC
52-pin header connector
Ground
test pin
Host PC Interface
DB9 Connector
Audio In
BNC Connector
Audio Out
BNC Connector
Parallel 30-pin FPC Connector
For signal access
Boomer II
On-board
LED indicators
Lower 30-pin FPC Connector
For connection to modem
SMA
Antenna
socket
SMA
Modem
socket
On / Off switch
Switches the power to the test jig on or off.
DC Jack
Provides power to the test jig. (3.8V)
DIP Switch
8-way DIP switch used to configure the test jig.
The following table shows the DIP switch configuration.
Dip
Switch #
Signal
On
PA7
Always leave this switch in the OFF position
OFF
OSC OFF
Always leave this switch in the ON position
ON
SS3
3V
10k Pul ldown to GND
OFF
SS2
3V
10k Pull down to GND
OFF
SS1
3V
10k Pull down to GND
OFF
SS0
3V
10k Pull down to GND
OFF
H-P-ON
Turn the modem off
Turn the modem on
OFF
RESET
Keep modem reset
Keep modem in working status
OFF
Wavenet Technology
Off
24
Default
Position
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________________________Test Jig
Port 2 / SPY PC
Connector
DB9 connector used for two purposes depending
upon the settings of the jumper switches located
just behind the connector on the PCB. If the
jumpers are used to connect the centre column to
the right hand outer column (TX, RTS etc), then
the port acts as a spy connection for the data
between the PC and the modem via the PC
connector.
An analyser program such as “spy.exe” can be
used to view the data.
SPY Modem
Connector
DB9 connector, used to spy on the RS-232 data
sent by the modem to the DTE (using DSR, RX,
CTS and GND signals).
An analyser program such as “spy.exe” can be
used to view the data. A communication program
such as “HyperTerminal” can be of limited use if
the data spied upon contains a lot of alphanumeric ASCII characters.
Host PC Connector DB9 connector, used to connect serial port 1
(of 2) of the modem to the DTE. The default
values for this RS-232 connection is 9600bps, 8
bits, no parity, 1 stop bit.
This port can also be used to download new
modem software to the Boomer II.
Parallel FPC
Connector
30-way FPC (Flexible Printed Circuit) connector
used for signal access.
Lower FPC
Connector
30-way FPC (Flexible Printed Circuit) connector
used to connect the Boomer II to the test jig.
Modem Connector
Used to connect the Boomer II’s antenna socket
to the antenna connector.
Antenna Connector Used to connect the external antenna.
LEDs
There are eight LEDs used to indicate the
following:
Power
Low Battery
In Range
Message Waiting
SS0
SS1
SS2
SS3
BM210012WT09
25
Wavenet Technology
Test Jig __________________________________________________ Boomer II User Manual & Integrator’s Guide
Audio Out
Connector for monitoring an audio output. Used
to monitor baseband signal, BIT Error Rate
(requires a PER test jig), receiver and
demodulation.
Warning : Must use a high impedance monitor,
100kÙ.
Audio In
Connector for monitoring an audio input. Used to
monitor modulation and transmission.
Warning : Must use a high impedance monitor,
100kÙ.
3 RDW
Header
connector
3 RDW
Header
connector
3 RDW Header
Connector
Connectors used for jumpers (supplied).
For Port 2 use, all the jumpers are positioned
from the centre column to the left hand column.
For Spy PC use, all the jumpers are positioned
from the centre column to the right hand column.
52-pin Header
Connector
Connector used for jumpers (supplied).
All the jumpers are connected as default.
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Wavenet Technology
DCD
RX
TX
DTR
GND
DSR
RTS
CTS
RI
RESET
H-P-ON
MSGWTG
INRANGE
LOWBAT
SSO/RX2
SS1/TX2
SS2/CTS2
SS3/RTS2
3.8V
3.8V
3.8V
3.8V
GND
GND
GND
GND
26
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________________________Test Jig
Initial Calibration
Without connecting a Boomer II OEM Modem to the Test Jig, initially
check the calibration of the on-board voltage regulator. (This regulator
supplies the RS232 converter and other on-board circuitry only. It does
not supply power to the modem).
1. Connect the centre pin of the DC jack to the +3.8V power
supply with 2A capability and the external pin to the ground.
2. Adjust the trimpot marked ADJ VCC to make sure the voltage
on the test pin next to the ADJ VCC is 3.3V.
3. Keep all of the switches on the dipswitch in the off position
(except DIP switch 2) for normal modem operation.
BM210012WT09
27
Wavenet Technology
Test Jig __________________________________________________ Boomer II User Manual & Integrator’s Guide
Set Up
With the power off,
1. Connect the Boomer II OEM modem to the lower FPC
connector on the test jig using a 30-way FPC cable.
Use the following procedure to insert the cable into the FPC
connector.
a. Lift up the lock lever of the FPC connector by flipping it
up with the nail of your thumb or index finger.
Lock Lever
b. Ensure that the cable is inline with the connector and
insert the FPC cable into the connector with the
conducting surface of the cable facing downwards.
FPC conductor side
c. Press down the lock lever.
Note: If the cable has been partially inserted, or out of
alignment, the lock lever will not engage. Should this
occur, remove the cable (see below) and repeat steps
a-c.
Wavenet Technology
28
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________________________Test Jig
Use the following procedure to remove the cable from the FPC
connector.
a. Lift up the lock lever of the FPC connector by flipping it
up with the nail of your thumb or index finger.
Lock Lever
b. Remove the cable after the lock is released.
2. Install an antenna to the modem. Use either the on-board SMA
connection and an adapter cable between the modem MMCX
connector and the test jig, or directly to the modem itself.
3. Connect the PC to the DB9 connector marked “PC” using a
standard serial cable.
4. Switch the power supply on.
5. Select the DIP switch labelled H-P-ON to the ON position.
The Power LED on the modem should illuminate.
You are now ready to communicate with the modem using the
PC as a host.
The modem should be able to talk to the PC by using Wavenet
RSUSER software, or other NCL protocol software.
BM210012WT09
29
Wavenet Technology
Test Jig __________________________________________________ Boomer II User Manual & Integrator’s Guide
RSUSER
The Radio Service Utility software (RSUSER ) enables a user to
exercise and configure Wavenet Modems. This software runs in a DOS
window under Windows 95, 98, NT, or 2000.
RSUSER interfaces with the Boomer II OEM Modem via a PC’s
communications port and the Test Jig’s PC port using an RS-232 cable
with DB9 connectors.
RSUSER is issued with the following files:
RSUSER.EXE
The executable
RSTEST.DEF
Definition file for scripts
RSUSER.INI
Initialisation file. Created by RSUSER.EXE
RPM.LOG
Log file. Created by RSUSER.EXE.
Refer to Appendix E for the NCL command list.
Operations
The following screen is displayed on start up or whenever the Help Hot
Key  is pressed.
*********RSUSER.M V2.xx HELP**********
NCL COMMANDS
- enable receive
_ - Get RPM status
@ - disable receive
- enable transmit
& - Get Next Msg
# - disable transmit
SEND MESSAGES (blocks composed of ...)
- Text ' '-'z'var length
, for short text
- random bytes var length % for short random
- Dotting ('U's) message
> for canned message
- sequential text var length
MISCELLANEOUS
F5 - Change COM regs [4,3F8]
Alt'b' - Change baud rate [9600]
F11 -Toggle dumping of data bytes of incoming NCL
F9 - Activate packet loopbacks
F10 - Configure loopback timing
CONFIG PROGRAMMING
Alt3 - Program home area
Alt6 - Program Group LLIs
Alt5 - Program Channels
Alt C -Read params from modem
Left/Right arrow - send XOFF/XON. Alt X/Z - rts off/on
Alt S/A - dtr off/on
Alt w - Batt. status Alt d - Radio status
F1 - Source LLI [90100001]
F2 - Destination LLI [90100001]
F3 - Sys Address[A1010A]
F4 - Compile NCL Msg
ESC - QUIT program
F6 - Auto sync LLIs and home area
Type '?' to get back to this help screen
RSUSER allows operators to exercise the modem via Native NCL
Commands (and Vendor Specific Commands), hot keys or an input
line. Common user commands such as enabling the modems receiver
and transmitter are included in the Hot Key list. Native NCL
commands can be issued from the F4 Hot key. A log file RPM.log is
automatically started for a new session of RSUSER. To save a session,
exit RSUSER and rename the RPM.log file.
Wavenet Technology
30
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________________________Test Jig
Using RSUSER
1. Supply power to the modem (e.g. via the test jig), switch it on
and plug the modem into the communications port of the
computer. (Refer to the modem’s user or test jig documentation
for cabling and connection instructions).
2. Execute RSUSER.EXE
3. Check that the communication port settings displayed are
correct under the Miscellaneous Heading.
4. If the communications port settings are incorrect, press ,
enter new settings, and exit from RSUSER by pressing
 and return to step 2.
5. Press the <_> key (the underline) to see if you receive a
response from the modem. If not, there may be a problem with
the connection or communication settings. Reset the modem,
exit from RSUSER, check all connections and return to step 1.
6. Use RSUSER as required and when finished, press 
to exit.
When first run, RSUSER.EXE creates a file RSUSER.INI in the
current directory, which saves the last used options (communications
configuration) of RSUSER.EXE. These options will be used next time
RSUSER is executed.
Hot Key Descriptions
 +<3>
Home Area Programming
Press  and <3> keys together to program the home area into the
modem's non-volatile memory. You will be asked to enter the home
area (e.g. C20101), and then press . You will see three
“CMND…..ILLEGAL BYTE” lines, followed by three “SUCCESS”
lines. This is normal. You must reset the modem ( 66 )
before the changes will take effect. If you do not receive the
“SUCCESS” responses, then reset the modem, reset RSUSER, and try
again.
 + <5>
Static Channel Programming
This allows you to change the static channel list in the modem's nonvolatile memory. You will be prompted to enter the channel list.
Type each channel individually, as per the example. You must type the
four hexadecimal digits of the channel (e.g. 25ED), followed by a
space, and then four hexadecimal digits for the channel attributes
(0401). (Refer to the DataTac RD-LAP manual for channel designators
and channel attribute descriptions.)
BM210012WT09
31
Wavenet Technology
Test Jig __________________________________________________ Boomer II User Manual & Integrator’s Guide
You should see two “CMND…..ILLEGAL BYTE” lines, followed by
two “SUCCESS” lines. This is normal. You must reset the modem
( 66 ) before the changes will take effect. If you do not
receive the “SUCCESS” responses, reset the modem, reset RSUSER,
and try again.
 + <6>
Group LLI Programming
This allows you to program up to 16 group LLIs into the non-volatile
memory of the modem. You will be prompted for each LLI
individually. When finished, press  when prompted for the
next LLI.
You should see two “CMND…..ILLEGAL BYTE” lines, followed by
two “SUCCESS” lines. This is normal. You must reset the modem
( 66 ) before the changes will take effect. If you do not
receive the “SUCCESS” responses, then reset the modem, reset
RSUSER, and try again.
 + 
Read Config Parameters
This option reads the current configuration from the modem, and
reports on it. The configuration includes the LLI, Serial #, home area,
channels, group LLIs and some redundant data.
 + 
Get Radio Status
This option sends a command to the modem requesting the current
radio status of the modem. The response contains information on the
current RSSI level, signal quality, current channel, base Id and several
other data.
 +  Get Battery Status
This option sends a command to the modem requesting the current
status of the battery power. The response contains the voltage level of
the battery as an absolute voltage and as an estimated percentage of
capacity.
 Set Source LLI
This option tells RSUSER which LLI should be listed as the source
LLI on all packets which are sent by RSUSER using the "SEND
MESSAGES" options. This setting will be saved in the RSUSER.INI
initialisation file. There is no need to reset the modem or RSUSER
after this option.
Wavenet Technology
32
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________________________Test Jig
 Set Destination LLI
Similar to the above option, but sets the destination LLI for messages
sent by the "SEND MESSAGES" options.
 Automatically Set SRC/Dest LLIs And Home Area
Automatically queries the modem for its LLI and home area, and sets
the above two options with that LLI for loopback tests, and the next
option with that home area address. This is easier than typing the LLI
for both source and destination options, and the destination address.
 SYS Address
This option sets the default destination area for messages sent with the
"Send Messages" option. This value is saved in the initialisation file.
 Compile NCL Message, or Send NCL Script
This option allows you to send any NCL command to the modem. For
example, by pressing , typing "4z" and then pressing 
will cause a command SDU to be sent to the modem asking for the
static channel table. To enter a non-ASCII value, use the form \7C
where the backslash indicates that the next two characters are to be
treated as a hexadecimal byte value (in this case 7C). This option is
only useful if you have a copy of the NCL specification to translate
commands into byte values.
RSUSER is also able to send commands taken from the definition file
rstest.def. This file contains a list of “scripts”, which contain
predefined commands. The comments in the sample rstest.def file
describe how to format the scripts in the file.
To send a script, press , and then type the script name prefixed by
the "=" (equals) sign.
For example, to run the "enablerx" script, press , and type
"=enablerx", followed by .
 Change Com Port Parameters
This option allows you to change the communications port settings
which RSUSER uses to communicate with the modem. You will be
asked for the port address and port IRQ. You will be given examples
for the common four PC com ports.
Note: You must exit from and restart RSUSER before these settings will
take effect.
BM210012WT09
33
Wavenet Technology
Test Jig __________________________________________________ Boomer II User Manual & Integrator’s Guide
 +  Change Baud Rate
This option changes the baud rate the RSUSER program uses. You will
be asked for the baud rate you wish to change to. Valid baud rates are
300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600 or 115200.
The change will take effect immediately. The baud rate is not preserved
on exit from RSUSER. It defaults back to 9600 on next invocation.
 Toggle Dumping Of NCL Data Bytes
Incoming NCL responses/events from the modem are translated and
displayed on screen by default. The actual data bytes making up the
packet may be optionally displayed. Press  to toggle this option.
< _ > Get Status Block
This option sends a status request command to the modem. It is a short
cut, rather than using the above F4 option and typing the ASCII
characters.
<(>
Receiver On / < @ > Receiver Off
This option sends a command to the modem to switch the receiver on
or off.
<)>
Transmitter On
/ < # > Transmitter Off
This option sends a command to the modem to switch the transmitter
on or off.
Send Messages Options
These varying options send messages to the modem to be sent to the
network. They each have a source and destination LLI and destination
area as set by F1, F2 and F3 respectively. The contents of the message
vary depending on the particular option. Some options are of fixed
length, and some ask you for the desired length. They are mainly selfexplanatory.
< > > Canned message.
You will be asked for a file name. The contents of this file will be used
as the contents of the data portion of the SDU.
<,>
A random sequence of binary numbers will form the data portion of the
message. Its length is approximately 20 characters.
Wavenet Technology
34
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________________________Test Jig
<<>
A sequential sequence of ASCII characters will form the data portion
of the message. You will be prompted for the length of the data portion
of the message. A number from 1 to 2010 is allowed.
Message Loopback Options
The F9 and F10 commands, together with the above “send message”
commands can be used to set up some automatic message sending and
loopback tests. When in loopback mode, RSUSER will cause a
message to be sent out for a definable amount of time (called “time
between”) after every time one is received from the network (or we
obtain a fail response to a send). The sent message will be the same
mode and length as the last message sent by a “send messages”
command above. We also send another packet if we don’t receive a
failure response, or a network packet within a definable time (called
“timeout”).

Toggles automatic packet sending (loopback mode) on and off.

Sets the timing parameters “time between” and “timeout”. These values
will be reset back to defaults (0 and 60 seconds respectively) whenever
RSUSER is executed.
For throughput tests where the network is bouncing back packets, the
values of 0 and 60 is recommended.
For throughput tests where the network doesn’t bounce back packets,
the values of 5 and 5 are recommended. This will send a packet every
five seconds (which allows time for retries etc.)
Reprogramming Modems
A self-extracting loader program is supplied for every software
upgrade. Refer to Appendix C - Wavenet Application Loader on page
133.
BM210012WT09
35
Wavenet Technology
Test Jig __________________________________________________ Boomer II User Manual & Integrator’s Guide
Wavenet Technology
36
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Software Development Kit
DataTAC networks allow wireless communication and are installed in
many different countries around the world. The Wavenet Software
Development Kit (SDK), has been developed to facilitate development
of applications for these networks by providing a simple program
interface for communicating with the network devices.
The SDK supports the following network types:
DataTAC ® 4000 networks
DataTAC ® 5000 networks
DataTAC ® 6000 networks
The SDK is made up of two major components:
Native Control Language Application Programmer's Interface
(NCL API)
Standard Context Routing Application Programmer's Interface
(SCR API)
The NCL API is the wireless client component of the SDK. It provides
routines for sending and receiving data using an NCL compliant Radio
Packet Modem (RPM).
The SCR API is the server component of the SDK. It provides routines
for encoding and decoding of SCR protocol messages and is used for
communicating with the network switch or radio network gateway
(RNG).
BM210012WT09
37
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Native Control Language Application Programmer’s
Interface
The Native Control Language Application Programmer's Interface
(NCL API) is the client component of the WAPI. The NCL API
provides routines for sending and receiving data messages through the
DataTAC wireless network, using a radio packet modem (RPM). It also
allows the client application to control configuration parameters of the
RPM and to retrieve status information from the RPM.
Implementation
The NCL API is implemented as a DLL library of written in C++ for
windows using Microsoft~ Visual C++ Version 6.0.
The NCL API communicates with PC or Pocket PC applications based
on the following model. The NCL API is supplied as a Virtual Device
Driver (VDD) for a PC (Win 98 or better) or a Pocket PC (Win CE
Version 3.0 or better). Multiple applications can access the RPM via
NCL encoded messages.
Layer 6 (Presentation)
Layer 5 (Session)
Level 4 (Transport )
MSMQ
Layer 3 (Network)
MSMQ IN 1
TX Queue
MSMQ IN N
Message Router & NCL Interpreter
Layer 2 (Data)
)))Link)
Serial Port Drivers
Layer 1 (Physical)
Serial Port to modem
Wavenet NCL API Model
Wavenet Technology
38
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Logical Architecture
The following table lists the required functionality for the API per
layer. The code forms a DLL, with only a subset of functions available
for third party developers.
LAYER NAME
CONTENT
FUNCTION
7.
APPLICATION
Application specific data.
Applications are to initialize a RX MSMQ (Microsoft
Message Queuing system) queue and open a session
with the VDD by passing the RX queue handler.
6.
PRESENTATION LAYER
Unused
5.
SESSION LAYER
Unused
4.
TRANSPORT LAYER
Unused
3.
NETWORK LAYER
MSMQ is run as a device driver on the Pocket PC
and is run from power up (ie Non-suspend mode).
The VDD will post events (RCV messages etc) to all
application RX queues enabled for that event.
Responses to application requests will be posted to
the calling application RX queue.
Router
The VDD process TX requests via a FIFO queue to
the NCL Interpreter. The Host base routing or Peerto-Peer routing SDU formatting is contained in the
NCL interpreter.
2.
DATA LINK LAYER
NCL Interpreter &
Extender port – Serial
Driver.
1.
PHYSICAL / BIT TRANSFER
LAYER
Extender Port to RPM.
Application NCL API function requests are processed
via a FIFO queue. RPM responses or received data is
tagged and encoded for the router as required Also
the UART DLL that handles the extender port UART
to modem communications resides in the link layer
modules..
9600, 8, 1, N on serial port and a wakeup line.
Wavenet’s current NCL API protocol stack is implemented with the
hierarchical structure. All DLLs including MSMQ files are included in
the install cabinet files for the VDD.
Router
The PC or PPC loads MSMQ as a device driver. Applications using the
modem must open a session with VDD by calling ‘VDDOpen()’ which
will create a private Receive MSMQ queue for the instance of the
application (client). The name of this private queue will be sent to the
serial port server (VDD) along with an open session request. The port
server will in turn create a private MSMQ queue to receive data from
the client. All Modem Events and response messages to be
communicated between the VDD and the application will be via the
receive queues. Transmit function requests from the applications
(clients) are queued by the VDD and are processed as a FIFO buffer by
the NCL interpreter. On Wakeup the VDD will be activated, if any
applications receive queues are open the RX event will be posted to
those queues. If no receive queues are active, the VDD will buffer the
RX events and start up the registered on_wakeup applications. After
BM210012WT09
39
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
the applications have successfully opened a VDD session the VDD will
pass the RX events to those applications.
Wavenet Technology
40
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
NCL Interpreter
The NCL Interpreter strips NCL API function calls from application
messages, queue the calls and execute the calls on a FIFO basis.
Received messages will be queued and matched against an appropriate
request (if not an event), and passed to the router with the
corresponding tags.
Link Layer
The RPM communicates with a PC via a standard communications port
and a user supplied RS232 to CMOS level device. For the Pocket PC
(PPC) the RPM communicates via the PPC extender port UART. The
PPC performs an auto detect and wakeup when an attached modem
receives some data and the PPC is in suspend mode.
Application Interface
Opening a Session
Applications are required to first open a session with the VDD by
calling the API function ‘VDDOpen()’. All other API functions will
return an error unless an open session with the VDD was established.
If successful this operation will result in the creation of two MSMQ
queues for use by the client. One MSMQ will be used to send messages
from the VDD to the client and the other for messages from the client
to the VDD. Note that the client does not deal with MSMQ queues
directly because all operations are wrapped in API calls.
Prototype:
int VDDOpen(void)
Description:
Opens a session with the VDD.
Input:
Ø
none
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
BM210012WT09
41
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Close Session
Applications can call this function to close its session with the VDD.
An application should call this function before it terminates if a session
was earlier established with the VDD. The reason for this is to ensure
that all created MSMQ queues for the client are deleted. This will
prevent irrelevant/outdated messages from being posted to inactive
MSMQ queues.
Prototype:
int VDDClose(void);
Description:
Close a session with the VDD.
Input:
Ø
None
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
Send Data to a Radio Host
Applications can call this function to send data to a radio host. The
Host ID will automatically be inserted into the data header of the SDU
for message routing purposes.
Prototype:
int nclSendData(word *usSduTag, byte *szHostId, byte ucIdLen, byte
*ucData, int iDatLen, bool bResend);
Response:
The VDD will track the response with the Host ID and SDU tag will
post the response to the corresponding RX queue for that session. The
application is responsible for reading and processing the response on
the RX queue. By calling ‘nclReceiveData()’.
Description:
Send application data to the radio host identified by the host ID.
Wavenet Technology
42
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Input:
Ø
usSduTag
Pointer to a word where the SDU tag can be stored
Ø
szHostId
Pointer to a buffer specifying the Host identity. The Host ID is
typically 3 bytes in length for DataTac systems. The NCL API will
truncate Host ID’s longer than NCL_MAX_UH_LEN (63) bytes in
length.
Ø
ucIdLen
Total length of the session ID
Ø
ucData
Pointer to the data to be sent
Ø
iDatLen
Length of the data to be sent
Ø
bResend
Resend flag must be set to false, except if the packet of data is
being re-sent due to a failure of the previous send. Setting the
flag to true prevents the possibility of receiving duplicate packets
at the server application. This flag cannot be used for resending
data prior to the previous packet.
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
×
usSduTag
Pointer to a word containing a reference of the corresponding
SDU tag which was generated by the NCL API for this command
to the RPM.
Receive Data From RPM
Applications can call this function to obtain data sent from the RPM.
This applies to both event and response type data from the RPM. Note
this is the only way to obtain response data originating from the RPM
as a result of issuing commands to it by means of other API functions
described in this document. The return code of all API functions
issuing commands to the modem only provides feedback about the
posted command. It does not guarantee delivery to the RPM. It is thus
imperative for applications to use ‘nclReceiveData()’ to obtain
feedback directly from the RPM on commands sent to it. Responses to
commands are asynchronous meaning multiple commands can be
issued to the RPM before the application needs to look at all the
responses. This is the reason why every command provides the
application with a copy of the unique SDU tag generated for the
command. Every response message contains the same SDU tag of its
associated command. The VDD uses the SDU tag to route response
messages to the originating application (client). The
‘nclReceiveData()’ function provides the SDU tag of the response
message. Applications can use these tags to tie up responses with
previously sent commands. One notable exception exist when the SDU
tag is equal to 65535 (FFFF hexadecimal). Only event messages
contain an SDU tag equal to 65535. The received event/ response
messages will be represented as an array of bytes which must be typed
cast to a structure identified by returned structure ID.
BM210012WT09
43
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
The RCV_MSG_NOTIFICATION event will be handled by the VDD,
which will read the messages from the RPM and pass the messages to
all clients with open sessions.
Other Event types shall be posted to all clients with open sessions
registered for that event. If no applications are registered for that event
the event will be disabled in the modem.
Prototype:
int nclReceiveData(DWORD dwTimeOut, BYTE *ucStructId, WORD
*usSduTag, int *iBufLen, BYTE *ucBuf);
Description:
Receive messages from the RPM.
Input:
Ø
dwTimeOut
The time (in milliseconds) to wait for the next message. Use 0 to
return immediately or FFFFFFFF (hexadecimal) to hang on
indefinitely for a message. The calling thread will be suspended
until a message arrive or the time-out period has elapsed,
whichever occurs first.
Ø
ucStructId
Pointer to a byte where the structure ID can be stored.
Ø
usSduTag
Pointer to a word where the SDU tag can be stored
Ø
iBufLen
Pointer to a integer specifying the total size of ucBuf.
Ø
ucBuf
Pointer to the buffer (of size iBufLen) where receive data can be
placed
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
×
ucStructId
This value identifies the structure of the data in ucBuf. See the
following paragraphs for details.
×
usSduTag
Pointer to a word containing a reference of the corresponding
SDU tag which was generated by the NCL API for this command
to the RPM.
×
iBufLen
Size (in bytes) of the data in ucBuf. Note: Buffer lengths of 0 is
possible – rely solely on the return value in such cases
×
ucBuf
Pointer to buffer containing the received data
Wavenet Technology
44
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
/*** Define types for retrieving data from the RPM ***/
typedef unsigned char
typedef unsigned short
BYTE;
WORD;
/*Parameter Structure IDs - Do not alter sequence*/
enum
NCLNone_ID = 0,
NCLEvent_ID,
NCLProdId_ID,
NCLVersion_ID,
NCLRpmId_ID,
NCLConfigBlock_ID,
NCLStatusBlock_ID,
NCLChanBlock_ID,
NCLGroupLlis_ID,
NCLChannelTable_ID,
NCLWaveSettings_ID,
NCLWaveRadio_ID,
NCLWaveGen_ID,
NCLByte_ID,
NCLByte2_ID,
NCLWord_ID,
NCLMsg_ID,
NCLRaw_ID
/*additional structure IDs to be added here including vendor specific types */
};
/* Use 1 byte alignment for the following structures */
#pragma pack(1)
/* Product ID structure */
typedef struct NCLProdId
BYTE hw_platform;
BYTE rf_protocol;
BYTE ncl_compliance;
BYTE release_level;
}NCLProdId;
/* NCL version structure */
typedef struct NCLVersion
char
major[2];
char
minor[2];
}NCLVersion;
/* RPM ID structure */
typedef struct NCLRpmId
BYTE
b_val[4];
}NCLRpmId;
/* Config block structure */
typedef struct NCLConfigBlock
BM210012WT09
45
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
NCLProdId
NCLVersion
NCLRpmId
WORD
WORD
}NCLConfigBlock;
/* Status block structure */
typedef struct NCLStatusBlock
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
WORD
WORD
WORD
}NCLStatusBlock;
/* Channel block structure */
typedef struct NCLChanBlock
BYTE
WORD
BYTE
BYTE
BYTE
}NCLChanBlock;
prod_id;
sw_version;
rpm_id;
reserved;
max_data_size;
rx_status;
tx_status;
antenna;
radio_in_range;
flow_control;
rcv_mode;
event_states;
ob_msg_count;
ib_msg_count;
radio_channel;
radio_in_range;
radio_channel;
attribute;
protocol;
rssi;
#define MAX_GROUP_LLIS
#define LLI_BYTE_WIDTH
#define NCL_NUM_CHANNELS 64
/* Group LLIs array */
typedef struct NCLGroupLlis
BYTE lli[MAX_GROUP_LLIS][LLI_BYTE_WIDTH];
BYTE num;
}NCLGroupLlis;
/* Channel Table */
typedef struct NCLChannelTable
WORD
BYTE
num;
}NCLChannelTable;
channel[NCL_NUM_CHANNELS];
/* Vendor Spesific: Wavenet Get Settings*/
typedef struct NCLWaveSettings {
BYTE
LLI[4];
BYTE
SerNum[16];
} NCLWaveSettings;
/* Vendor Spesific: Wavenet Get Radio Settings*/
Wavenet Technology
46
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
typedef struct NCLWaveRadio {
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
BYTE
} NCLWaveRadio;
rssi[2];
reserved1;
reserved2;
reserved3;
reserved4;
reserved5;
reserved6;
reserved7;
reserved8;
frequency[4];
channel[2];
base_id;
/* Vendor Spesific: Wavenet Generic*/
typedef struct NCLWaveGen {
BYTE
byte[100];
} NCLWaveGen;
/* NCL status information structure */
typedef union NCLStatus
NCLProdId
prod_id;
BYTE
vendor_id;
NCLVersion
sw_version;
NCLRpmId
rpm_id;
BYTE
rpm_vid[2];
NCLGroupLlis
rpm_gid;
WORD
max_data_size;
BYTE
rx_status;
BYTE
tx_status;
BYTE
antenna;
BYTE
radio_in_range;
WORD
ob_msg_count;
WORD
ib_msg_count;
BYTE
flow_control;
BYTE
rcv_mode;
BYTE
event_states;
WORD
radio_channel;
NCLChannelTable
chan_table;
NCLChannelTable
dchan_table;
NCLConfigBlockconfig_block;
NCLStatusBlock status_block;
NCLChanBlock
chan_block;
BYTE
bat_level;
NCLWaveSettings
wave_set;
NCLWaveRadio
wave_radio;
NCLWaveGen
wave_generic;
}NCLStatus;
/* Event Type */
typedef struct NCLEventType
BYTE etype;
/* NCL_RCV_MSG_DATA
/* NCL_MSG_NOTIFICATION
/* NCL_TX_EVENT
/* NCL_RX_EVENT
/* NCL_HW_EVENT
BM210012WT09
47
'A'
‘B’
'C'
'D'
'E'
Received message data
*/
Received Message notification */
Transmitter event
*/
Receiver event
*/
Hardware event
*/
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
/* NCL_RCV_ERR_EVENT
/* NCL_CONTROL_EVENT
'F'
'G'
Unreceivable Message Event
Control Event
*/
*/
BYTE EventCode;
/* NCL_MSG_NOTIFICATION_LEN N- Number of buffered msgs to be read */
/* NCL_TX_EVENT_KEYED
‘1’
Transmitter keyed
*/
/* NCL_TX_EVENT_DEKEYED ‘2’
Transmitter dekeyed
*/
/* NCL_RX_EVENT_INRANGE ‘1’
RF in range
*/
/* NCL_RX_EVENT_OUTRANGE ‘2’
RF out of range
*/
/* NCL_RX_EVENT_PSENAB ‘3’
Power Save enabled
*/
/* NCL_RX_EVENT_PSDISAB ‘4’
Power Save disabled
*/
/* NCL_HW_EVENT_STEST
‘1’
Self Test Failed
*/
/* NCL_HW_EVENT_LBATT
‘2’
Low battery
*/
/* NCL_HW_EVENT_MFULL
‘3’
Memory Full
*/
/* NCL_HW_EVENT_BATOK
‘4’
Battery Level OK
*/
/* NCL_HW_EVENT_MEMOK ‘5’
Memory Ok
*/
/* NCL_HW_EVENT_MEMOK ‘6’
Device shutdown is imminent
*/
/* NCL_RCV_ERR_EVENT_RTD ‘1’
ACK required PDU received but TX
disabled */
/* NCL_CONTROL_EVENT_C ‘1’
RPM / DTE connected
*/
}NCLEventType;
/* RCV_MSG_Data */
#define NCL_MAX_DATA_SIZE
#define NCL_MAX_UH_LEN
63
2048
/* max length of user header */
typedef struct NCLMsg
BYTE
is_message; /* If FALSE, only len and buf components are valid. */
BYTE
sessionID[NCL_MAX_UH_LEN + 1]; /* NULL terminated */
BYTE
msg_type; /* Used by NCL_DATATAC_5000 networks */
WORD
len;
BYTE
buf[NCL_MAX_DATA_SIZE];
} NCLMsg;
/* End of 1 byte alignment */
#pragma pack()
Wavenet Technology
48
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Get RPM Status Information
The application can call this function to obtain status information about
the RPM. The following types of status information can be obtained:
Status Request (non vendor
specific)
Response Structure
Description
NCL_R_CONFIG_BLOCK
NCLConfigBlock
Get RPM configuration block
NCL_R_STATUS_BLOCK
NCLStatusBlock
Get RPM status block
NCL_R_PROD_ID
NCLProdId
Get RPM product ID
NCL_R_SW_VERSION
NCLVersion
Get software version number
NCL_R_RPM_ID
NCLRpmId
Get RPM address
NCL_R_RPM_VID
NCLStatus.rpm_vid[2]
Get RPM VID address (MDC)
NCL_R_MAX_DATA_SIZE
NCLStatus.max_data_size
Get SDU data limit
NCL_R_RCV_MODE
NCLStatus.rcv_mode
Get mode of notification to
DTE for received SDUs.
NCL_R_RX_STATUS
NCLStatus.rx_status
Get receiver enable status
NCL_R_TX_STATUS
NCLStatus.tx_status
Get transmitter enable status
NCL_R_ANTENNA
NCLStatus.antenna
Get antenna selection status
NCL_R_RADIO_IN_RANGE
NCLStatus.radio_in_range
Get radio in range status
NCL_R_OB_MSG_COUNT
NCLStatus.ob_msg_count
Get count of outbound
messages queued
NCL_R_IB_MSG_COUNT
NCLStatus.ib_msg_count
Get count of inbound
NCL_R_FLOW_CONTROL
NCLStatus.flow_control
Get flow control status
NCL_R_EVENT_STATES
NCLStatus.event_states
Get current event reporting
(enable/disable) state
NCL_R_RADIO_CHANNEL
NCLStatus.radio_channel
Get current radio channel
NCL_R_CHAN_TABLE
NCLChannelTable
Read radio channel table
NCL_R_CHAN_BLOCK
NCLChanBlock
Read the channel block
NCL_R_BAT_LEVEL
NCLStatus.bat_level
Read the battery level
NCL_R_RPM_GID
NCLGroupLlis
Get RPM group IDs
NCL_R_VENDOR_ID
NCLStatus.vendor_id
Get vendor identification
NCL_R_DCHAN_TABLE
NCLChannelTable
Read the D-channel table
NCL_R_RF_STATISTICS
Specific to RF protocol used:
RD-LAP [F] or MDC [G]
Read the RF statistics
Status Request (Wavenet
Technology specific)
Response Structure
Description
WN_GET_STATUS_RADIO
NCLWaveRadio
Get RPM Radio Status
WN_GET_STATUS_BATTERY
NCLWaveGen
Get RPM Battery Status
WN_GET_STATUS_ONTIME
NCLWaveGen
Get RPM on-time status
WN_GET_STATUS_CONFIG
NCLWaveGen
Get RPM configuration status
BM210012WT09
49
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Prototype:
int nclGetStatus (word *usSduTag, byte ucVendor, byte ucType, byte
ucRequest);
Description:
Command the RPM to send the requested status information.
Input:
Ø
usSduTag
Pointer to a word where the SDU tag can be stored
Ø
ucVendor
Vendor identifier. Use:
NCL_NO_VEND = 0 if not vendor specific or
NCL_VEND_WAVENET = ’F’ for Wavenet Technology specific
requests
Ø
ucType
The type of status information to retrieve from the RPM (Used by
Vendor specific requests). Set to zero for non-vendor requests or
WN_GET_STATUS = ‘?’ for Wavenet Technology specific
requests
Ø
ucRequest
The requested status information, as listed in one of the
appropriate tables above, to retrieve from the RPM.
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
×
usSduTag
Pointer to a word containing a reference of the corresponding
SDU tag which was generated by the NCL API for this command
to the RPM.
The response is posted to the corresponding RX queue associated with
the VDD session ID. If the session ID is not recognized all active RX
queues will be posted the response.
Set Configuration ITEMS Within the RPM
By default the modem will have the receiver and transmitter enabled
and the RX notification event enabled. Modem Configuration items via
NCL are TBA and will be restricted to service personnel.
Wavenet Technology
50
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Reset RPM
The application can call this function to reset the RPM. There are
several different levels of RPM reset commands that may be issued to
the RPM, as listed below:
Reset Level
Description
NCL_RESET_INBOUND
Flush the Inbound queue
NCL_RESET_OUTBOUND
Flush the Outbound queue
NCL_RESET_BOTH
Flush both the Inbound and Outbound queues
NCL_RESET_WARM
Warm start: flush queues, default Native settings, remain in
Native mode
NCL_RESET_TRANS
Not Supported
NCL_RESET_FULL
Full reset: Power-on reset
NCL_RESET_NCL
Reset NCL interpreter
NCL_RESET_OFF
Power off the RPM
Prototype:
int nclResetRPM (word *usSduTag, byte ucResetLevel);
Description:
Command the RPM to perform a specified level reset
Input:
Ø
usSduTag
Pointer to a word where the SDU tag can be stored
Ø
ucResetLevel
The level of the Reset as listed in the above table
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
×
usSduTag
Pointer to a word containing a reference of the corresponding
SDU tag which was generated by the NCL API for this command
to the RPM.
The response is posted to the corresponding RX queue associated with
the VDD session ID. If the session ID is not recognized all active RX
queues will be posted the response.
BM210012WT09
51
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Register Event Callback Function
Since the RX events will be posted to private Receive MSMQ queues
the VDD is not required to support callback functions. Applications
can call the API function ‘nclReceiveData()’, to wait on response and
event messages from the RPM on their on account. The API function
‘nclReceiveData()’ will return within the time-out period specified, so
applications will not be hung-up indefinitely.
Enable / Disable Events
The application can call this function to enable or disable individual
event types being reported by the RPM. By default, only the Receive
Message Data event is enabled (NCL_RCV_MSG_DATA). All other
event types for an application are disabled unless they have been
specifically enabled / disabled using this function. The
NCL_RCV_MSG_NOTIF event is handled by the VDD, which will
post the received messages to all active RX queues (that have
NCL_RCV_MSG_DATA enabled) using the NCLRXDataID structure
type.
Prototype:
int nclSetEvent (word *usSduTag, byte ucType, byte ucSetting);
Description:
Enable / Disable event reporting by the RPM for the specified event
type.
Input:
Ø
iSessionID
VDD session ID
Ø
usSduTag
Pointer to a word where the SDU tag can be stored
Ø
ucType
The type of event to enable/disable:
NCL_RCV_MSG_DATA
(Received message data)
NCL_TX_EVENT (Physical-level transmitter event)
NCL_RX_EVENT (Physical-level receiver event)
NCL_HW_EVENT (Hardware event)
NCL_RCV_ERR (Un-receivable message event)
NCL_CONTROL (Control event)
NCL_VEND_EVENT (Vendor specific event)
Ø
ucSetting
Wavenet Technology
NCL_DISABLE
(Disable event reporting)
NCL_ENABLE
(Enable event reporting)
52
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
×
usSduTag
Pointer to a word containing a reference of the corresponding
SDU tag which was generated by the NCL API for this command
to the RPM.
Get Error Description
The application can call this function to obtain a string representation
for a specified error code.
Error Code
Value
Description
NCL_ERR_NONE
No error has occurred
NCL_ERR_SESSION_IS_CLOSED
-1
NCL API: Session has not been opened
NCL_ERR_SESSION_IS_OPEN
-2
NCL API: Session is already open
NCL_ERR_ENCODE
-3
NCL API: NCL Frame encoding error
NCL_ERR_DECODE
-4
NCL API: NCL Frame decoding error
NCL_ERR_PARAM
-5
NCL API: Invalid parameter passed
NCL_ERR_TIMEOUT
-6
NCL API: Time-out elapsed waiting for response
NCL_ERR_MSMQ_OPEN
-7
NCL API: An error occurred opening a MSMQ
NCL_ERR_MSMQ_CLOSE
-8
NCL API: An error occurred closing a MSMQ
NCL_ERR_MSMQ_SEND
-9
NCL API: An error occurred sending a MSMQ
NCL_ERR_MSMQ_RECEIVE
-10
NCL API: An error occurred receiving a MSMQ
NCL_ERR_MSMQ_CREATE
-11
NCL API: An error occurred creating a MSMQ
NCL_ERR_MSMQ_DELETE
-12
NCL API: An error occurred deleting a MSMQ
NCL_ERR_MSMQ_NAME
-13
NCL API: An error occurred searching for a MSMQ
NCL_ERR_MAX_CLIENTS
-14
NCL API: Maximum number of supported clients
reached
NCL_ERR_INVALID
'b'
NCL Syntax error: Invalid options
NCL_ERR_TOO_LONG
'c'
NCL Syntax error: Data too long
NCL_ERR_ES_NAME
'd'
NCL Syntax error: Invalid name
NCL_ERR_NO_RESPONSE
'A'
Execution error: No response from network
NCL_ERR_NO_ACK
'B'
Execution error: Negative ACK received
NCL_ERR_HOST_DOWN
'C'
Execution error: Host down
NCL_ERR_NOT_REGISTERED
'D'
Execution error: RPM not registered
NCL_ERR_LOW_BATTERY
'E'
Execution error: Low battery - can't transmit
NCL_ERR_IBQ_FULL
'F'
Execution error: RPM inbound queue full
NCL_ERR_TX_DISABLED
'G'
Execution error: Radio transmitter disabled
NCL_ERR_BUSY
'H'
Execution error: Resource unavailable
NCL_ERR_NOT_AVAILABLE
'I'
Execution error: Unimplemented services
NCL_ERR_HW_ERROR
'J'
Execution error: Generic
NCL_ERR_INVALID_MODE
'K'
Execution error: Invalid mode of operation
NCL_ERR_NO_MESSAGES
'L'
Execution error: No outbound messages available
BM210012WT09
53
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Error Code
Value
Description
NCL_ERR_MSGS_PENDING
'M'
Execution error: Pending inbound messages
NCL_ERR_SW_ERROR
'N'
Execution error: Software error has been
encountered
NCL_ERR_OUT_OF_RANGE
'O’
Execution error: Cannot send data when out of
range
NCL_ERR_PACKET_ERROR
'Z'
Execution error: SDU data corruption detected
Error Not Listed
All other
values
Unknown error
Prototype:
char * nclGetErrorDescription (int iErrorCode);
Description:
Return a pointer to a character string describing the specified error
code.
Input:
Ø
iErrorCode
Integer specifying the error code for which a string description is
required.
Output:
×
WCHAR *
Pointer to a NULL terminated wide character (Unicode) string
describing the error
Register Wakeup Application
By default the VDD is executed on wakeup. In addition an application
can register to be executed on wakeup via the VDD. On wakeup the
VDD will post any Received data to the current active queues. If there
are no active queues the VDD will execute the Registered applications.
Once an application has initiated a successful VDD session (i.e. via
‘VDDOpen ()’ ) the VDD will post the Received data to the
applications RX queue. A timeout (Wktm = 10 seconds) will be used to
hold the data for an application to initialize and commence a VDD
session before the data is discarded. The default application will be the
Modem Information application as supplied as a sample application
with the VDD.
Prototype:
int nclRegWakeupApp (WCHAR *usAppName, WORD
usWakeupReason);
Wavenet Technology
54
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Description:
Register an application for wakeup when specified events occur.
Input:
Ø
usAppName
Ø
usWakeupReason
Pointer to a buffer specifying the full path name (Null terminated)
of the application to execute on a wakeup.
Logical OR the required reasons for wakeup from the following
values (exclude unwanted reasons):
WAKE_MODEM_INSERTION – Wakeup application when
modem is attached
WAKE_MESSAGE_RECEIVED – Wakeup application when a
message is received but no client applications are running
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
Deregister Wakeup Application
The application can call this function to deregister an application that
was previously registered to wakeup.
Prototype:
int nclDeregWakeupApp (WCHAR *usAppName);
Description:
Deregister a wakeup application.
Input:
Ø
usAppName
Pointer to a buffer specifying the full path name (Null terminated)
of the application to execute on a wakeup.
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
BM210012WT09
55
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Switch RPM On/Off
The application can call this function to switch the RPM on or off.
Prototype:
int nclSwitchRPMPower (word usSetting);
Description:
Switch the RPM power to the desired setting.
Input:
Ø
usSetting
If this value is zero, the RPM should power down else it should
power up
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
Send Generic NCL Command To RPM
The application can call this function to send application specific
commands to the RPM.
Prototype:
int nclSendGenericCommand (WORD *usSduTag, BYTE ucLength, BYTE
*ucParam);
Description:
Send an NCL command to the RPM of which the payload contents consist of
data from the specified buffer.
Input:
Ø
usSduTag
Pointer to a word where the SDU tag can be stored
Ø
ucLength
Pointer to a byte specifying the total size of ucParam.
Ø
ucParam
Pointer to the buffer (of size ucLength) containing the data to be
send to the RPM
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
Wavenet Technology
56
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Get Software Version
The application can call this function obtain the software version of the
server application or the VDD DLL.
Prototype:
int VDDgetVersion (WORD* usVersion);
Description:
Obtain the software version of the specified software entity.
Input:
Ø
usVersion
Set this value to zero to request the VDD DLL version or to any
other value to request the server application version
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value specifies the error type
×
usVersion
BM210012WT09
The upper 8 bits contain the major version and the lower 8 bits
contain the minor software version if the return value is zero
57
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Standard Context Routing Application Programmer’s
Interface
The Standard Context Routing Application Programmer's Interface
(SCR API) is the server component of the SDK. The SCR API
provides routines for encoding and decoding SCR messages for
communication with the DataTAC ® network switch or radio network
gateway (RNG). Decoded SCR messages are stored in structures
defined to represent SCR messages. Encoded messages are stored in
memory buffers.
To encode a message, an application will first set up a structure
representing the desired SCR message. This structure is then passed to
the encoding function, scr_Encode(), which encodes the message into a
memory buffer. The application can then send this encoded message to
the DataTAC network switch or RNG.
To decode an SCR message received from the network switch, the
application passes the received message buffer to the decode routine,
scr_Decode(), which decodes the message into a structure containing
the data from the message.
Routines are also provided to convert some of the message codes into
English language descriptions of the code.
The SCR API does not contain routines for reading the SCR messages
from the message switch interface or for sending encoded SCR
messages to the message switch. The connection to the message switch
is normally via an X.25 connection or a TCP/IP connection.
When you are using an X.25 connection to the network switch or RNG,
communication will be via an X.25 card. You will need to get an X.25
and appropriate drivers for this card. To develop your own application,
you will also need the developer's kit for your X.25 card. The sample
application has been written to use an EICON X.25 card. To run over
an X.25 connection, the sample application requires an EICON X.25
card, plus EICON WAN Services driver software. To modify and
compile the sample application, or to write your own application, you
will also need the EICON X.25 Development Tools for Win 32.
Contact EICON Technology (www.eicon.com) for more information
on these products.
When you are using a TCP/IP connection to the network switch or
RNG, communication will be via some form of TCP/IP link. This may
be via an Ethernet card or through a modem connection running SLIP
or PPP. The appropriate drivers will need to be configured for the
Ethernet card, and TCP/IP will need to be configured as a network
protocol. Contact your hardware supplier for more details on
configuring the TCPm connection. To communicate through the
TCP/IP connection, the sample application uses the standard Winsock
interface provided with the Microsoft Windows operating system. Most
Wavenet Technology
58
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Windows compilers come with a standard developer's kit to interface to
the Winsock routines.
Implementation
The SCR API is implemented as a library of routines written in ANSI
C and compiled for Windows NT using the Microsoft Visual C++
compiler. All default project settings were used to compile the .lib file.
SCR Structures
The SCR API makes use of several important structures to store the
SCR messages. The main structure is the SCRMsg structure. This
structure is a union of structures, each of which represents a single
message type in the SCR protocol.
The SCRMsg structure is shown here. The msg_type field indicates
which element of the union is valid. The appropriate value for the
msg_type field is shown in the comments.
BM210012WT09
59
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
/* The SCR Message data structure. */
typedef struct SCRMsg {
int msg_type;
union{
SCRhrr r;
SCRar
ar;
SCRlr
lr;
SCRhc
hc;
SCRac
ac;
SCRlc
lc;
SCRmi
mi;
SCRci
ci;
SCRdi
di;
SCRrs
rs;
SCRrr
rr;
SCRib
ib;
SCRob
ob;
SCRab
ab;
SCRreqstat
reqstat;
SCR_REQ_STAT*/
SCRstatrsp
statrsp;
SCR_STAT_RSP*/
SCRtonet
tonet;
SCR_TO_NET*/
SCRfromnet
fromnet;
SCR_FROM_NET*/
SCRack
ack;
} u;
} SCRMsg;
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type:
SCR_HR*/
SCR_AR*/
SCR_LR*/
SCR_HC*/
SCR_AC*/
SCR_LC*/
SCR_MI*/
SCR_CI*/
SCR_DI*/
SCR_RS*/
SCR_RR*/
SCR_IB*/
SCR_OB*/
SCR_AB*/
/*msg_type:
/*msg_type:
/*msg_type:
/*msg_type: SCR_ACK*/
Definitions for all SCR message structures can be found in the file
scrapi.h. (SCR SDK)
Network Independent Messages
The SCR API provides several network independent message types.
These message types represent basic functions within the SCR protocol
that are applicable to all DataTAC network types. The SCR API
encodes and decodes these message types as the appropriate message
for the correct network type, as given in the call to the scr_Init()
function.
It is recommended that you use these network independent message
types wherever possible, to enhance the portability of the code between
different DataTAC network versions.
The three network independent message types are listed here:
SCR_FROM_NET
Generic From Network message. This is used
for receiving data from a wireless device.
Depending on the network setting, this
corresponds to either a Basic Outbound (OB)
message for DataTAC 4000 networks, or a
Message Indication (MI) for DataTAC 5000 or
6000 networks.
SCR_TO_NET
Generic To Network message. This is used for
sending data to a wireless device. Depending on
the network setting, this will be encoded as
either a Basic Inbound (IB) message for
Wavenet Technology
60
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
DataTAC 4000 networks, or a Host Request
(HR) message for DataTAC 5000 or 6000
networks.
SCR_ACK
Generic Acknowledgment message. This is
used to receive an acknowledgment for data
sent to a wireless device.
SCR_TO_NET messages may be passed to scr_Encode(), and they will
be encoded as the appropriate message type for the current network, as
set in the call to scr_Init(). When a received packet is decoded using
scr_Decode(), it converts the received packet to an SCRMsg structure.
The received messages are decoded for the current network type, and
stored in the SCRMsg structure as their actual message type. However,
the definition of the generic From Network message structure,
SCRfromnet, is exactly the same as both the Message Indication (MI)
message structure, SCRmi, and the Basic Outbound (OB) message
structure, SCRob. Because of this, the decoded message structure may
be interpreted as any of these structures. Similarly, the message type
values SCR_FROM_NET, SCR_MI, and SCR_OB are defined to be
the same value.
Also, the message types SCRack, SCRhc, and SCRab are all the same,
and the message-type constants SCR_ACK, SCR_HC, and SCR_AB
are all the same, and so may be interpreted interchangeably.
Coupled with the interchangeable use of the message structures
SCRack, SCRhc, and SCRab is the function scr_NakReasonText(). The
response code field within the SCRack structure is network specific,
but the scr_NakReasonText() function will interpret the response code
appropriately for the network type specified to scr_Init() and will return
a text description of the error code, or a NULL pointer if the code
represents successful delivery.
Network Specific Messages
The SCR API defines network specific message structures for each of
the network specific SCR message types. These messages apply only to
particular versions of the DataTAC network.
When a message is passed to the scr_Encode() routine, and that
message is not valid for the specified network type, it is encoded as the
corresponding message type for the network version specified to
scr_Init() wherever possible. For example, if scr_Init() is used to set the
network type to DataTAC 5000, and an SCR_IB message is passed to
scr_Encode(), it will be encoded as a Host Request (HR) message.
Also, due to the same structure definitions and equivalent message type
constants being used across all network types for the From Network
(OB and MI) and Acknowledgment (AB and HC) messages, the
decoded structures may be interpreted as network specific structures,
and this will still work on other network types. For example, if
scr_Init() is used to set the network type to DataTAC 5000, and a
SCR_MI message is received from the network and decoded, this
BM210012WT09
61
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
decoded structure may be interpreted as an SCR_OB structure with no
side effects.
DataTAC® 4000 Network Messages
The following message types are specific to the DataTAC 4000
network:
SCR_OB
Basic Outbound message for receiving data from a
wireless device
SCR_IB
Basic Inbound message for sending data to a wireless
device
SCR_AB
Basic Acknowledgment of data sent to a wireless device
DataTAC® 5000 Network Messages
The following message types are extended SCR messages that are only
used on the DataTAC 5000 network.
SCR_LR
Loopback Request
SCR_LC
Loopback Confirmation (response to LR)
SCR_CI
Connect Indication
SCR_DI
Disconnect Indication
SCR_AR
Activity Request
SCR_AC
Activity Confirmation (response to AR)
SCR_RS
Receiver Suspend
SCR_RR
Receiver Resume
DataTAC® 5000 and DataTAC® 6000 Network Messages
The following message types are common to the DataTAC 5000 and
6000 networks:
SCR_MI
Message Indication message for receiving data from a
wireless device.
SCR_HR
Host Request message for sending data to a wireless
device
SCR_HC
Host Confirmation for acknowledgment of data sent to a
wireless device
Wavenet Technology
62
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Data Header
All data messages (MI, HR, OB, IB, TO_NET, FROM_NET) contain a
data header field. This field is used to route messages to the correct
server from client RPM devices. The data header is also sometimes
referred to as the session, and this is reflected in some of the NCL API
function parameters. For example, the szHostId parameter in
nclSendData and in the data header for the nclReceiveData functions.
This data header is represented in the SDK as a NULL terminated
string.
Refer to section Message Routing and Migration sub section SCR
Header charts on page x for the formatting of the header fields. How
the use of the Data Header field varies between the network types is
described below.
For DataTAC 4000 and 6000 networks, a host slot is used to route data
from the wireless client to the correct server. RPM devices can be
configured with up to five host slots, each routed to a different server
application. When the client application sends a message, the data
header is used to specify which host slot to send on, and hence which
server application the data will be sent to. The host slot is represented
by a single ASCII digit from 1 to 5. This digit must be given as the last
character of the data header. For example, a data header of I would
route the information on host slot 1, whereas a data header of TE3
would route the data on host slot 3.
For the DataTAC 5000 network, a 2-character session ID is used for
routing data from the wireless client to the correct server. RPM devices
may be configured with many sessions, each routed to different server
applications. The session ID is made up of any two characters from A
to Z or 0 to 9. When a client application sends data to a server
application, it must set the first two characters of the data header to the
session number. For example, a data header of Al routes data on
session A1, and a data header of TEI routes data on session TE.
To simplify porting of applications between different network types,
the use 3-character data headers, such as TEI. Using a data header of
this format, DataTAC 4000 and 6000 networks look only at the last
character of the data header and route on host slot 1, while a DataTAC
5000 network will look at the first two characters and route on session
TE. This allows the same data header to be used on all network types.
It is recommended that the data header is also set for messages from
server to client. This is not critical for routing messages back to the
client, but it is useful for the client to know on which session or host
slot (and therefore from which host) the data came.
BM210012WT09
63
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
SCR Functions
scr_Init()
Prototype:
int scr_Init(byte l_network_type);
Description:
This routine initialises the library and sets the network type being usedDataTAC ® 4000, 5000, or 6000. The network type affects the encoding
and decoding of messages by validating that the message type is
applicable to this network type. This network type is also used to
correctly encode/decode the network independent message types
SCR_FROM_NET, SCR_TO_NET, and SCR_ACK.
Note: This function must be called before any other SCR API functions.
The operation of all other functions depends on the network type given
to this function.
Input:
Ø
l_network_type
The network type to be used.
Valid values are:
SCR_DATATAC_4000 SCR_DATATAC_5000
SCR_DATATAC_6000
Output:
×
Return value = 0
Operation was successful
×
Return value
Operation failed. Value SCR_ERROR is returned to indicate an
error
Example
#include 
main()
int lrc;
lrc = scr_Init(SCR_DATATAC_4000);
if (lrc == SCR_ERROR) {
exit(0);
/* perform other SCR operations */
. . .
Wavenet Technology
64
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
scr_Encode()
Prototype:
int scr_Encode(byte *l_buf, SCRMsg *l_msg)
Description
This routine encodes a SCRMsg structure into an SCR encoded data
buffer. This routine transparently converts and encodes IB, OB, AB,
HC, HR, and MI messages for the correct network type. For example,
if scr_Init() has been used to set the network type to DataTAC 4000,
and an MI message is passed to scr_Encode(), it will be encoded as an
OB message.
Input:
Ø
*l_buf
The buffer for the encoded message to be returned in. When
calling this function, this parameter must point to an allocated
buffer of at least SCR_MAX_LEN bytes. The encoded message
is returned as a binary array. It is not a NULL terminated string.
Ø
*l_msg
An SCRMsg structure representing the message to be encoded.
For a description of the SCRMsg structure, refer to "SCR
Structures.
Output:
×
Return value = 0
Operation was successful and the encoded message is returned
in l_buf.
×
Return value
Operation failed. Value SCR_ERROR is returned to indicate an
error
BM210012WT09
65
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Example
#include 
SCRMsg lmsg;
byte ldata[200];
byte lbuffer[SCR_MAX_LEN];
*/
int llen;
*/
/* SCR message struct */
/* data to send to host */
/* buffer for encoded SCR msg
/* length of encoded SCR msg
strcpy((char *)ldata, "Hello world")
/* initialize message structure */
lmsg.msg_type = SCR_TO_NET;
/* send data to client
device */
lmsg.u.tonet.lli = 0xEE021234;
/* set device LLI to
send to */
lmsg.u.tonet.ack = SCR_TONET_ACK_NONE; /* no
acknowledgment
*/
lmsg.u.tonet.data_header = “BB1”;
/* Note: On a DataTAC 4000 or 6000 network,
this message */
/* will be routed on host slot 1. On a
DataTAC 5000 */
/* network, the message will be routed on
session 'BB. '*/
/* See Section “Data Header” for further
details. */
lmsg.u.tonet.data.data = ldata;
lmsg.u.tonet.data.len = strlen(ldata);
llen = scr_Encode(lbuffer, &lmsg);
if (llen != SCR_ERROR) {
/* send encoded message to network */
x25_send(. . . [buffer, lien, . . .)
else {
/* report an error */
. . .
Wavenet Technology
66
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
scr_Decode()
Prototype:
int scr_Decode(int l_len, byte *l_buf, SCRMsg *l_msg)
Description
This routine is used to decode an SCR message from a received buffer
and produce an SCRMsg structure representing the received message.
When this routine returns successfully, some memory may have been
allocated within the SCRMsg structure. scr_FreeDecoding() should
always be called after a successful scr_Decode() to free any memory
that may have been allocated. When scr_Decode() returns
SCR_ERROR or 0, scr_FreeDecoding() should not be called.
Input:
Ø
l_len
The length of the data contained in l_buf.
Ø
*l_buf
The buffer containing received SCR data
Ø
*l_msg
The decoded SCRMsg is returned is l_msg. When calling this
function, this parameter must point to an allocated SCRMsg
structure. Refer to "SCR Structures".
Output:
×
Return value = 0
Operation was successful but the buffer contains only a partial
SCR message in l_msg.
×
Return value < 0
Operation failed. Value SCR_ERROR is returned to indicate an
error
×
Return value > 0
Operation was successful .and the decoded message is returned
in l_msg.
BM210012WT09
67
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
Example
#include 
*/
*/
*/
*/
SCRMsg lmsg;
/* SCR message struct
byte
lbuffer[SCR_MAX_LEN];/*buffer for received SCR msg
int
llen;
/* length of received SCR msg
int
lused;
/* return code from scr_Decode
/* receive data into lbuffer */
llen = x25recv( . . . lbuffer, .
.);
lused = scr_Decode(llen, lbuffer, &lmsg);
if (lused > 0) {
/* process message */
Wavenet Technology
scr_FreeDecoding(lmsg);
/* free decoded message */
else if (lused == 0) {
/* incomplete message received */
else {
/* report an.error */
. . .
68
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
scr_FreeDecoding()
Prototype:
void scr_FreeDecoding(SCRMsg *l_msg)
Description
This routine is used to free any memory allocated inside an SCRMsg
structure by a successful call to scr_Decode(). All calls to scr_Decode()
that return a successfully decoded SCR message (the return value is a
positive value) must be followed by a call to scr_FreeDecoding(), after
the caller has fully processed the decoded message. If
scr_FreeDecoding() is not called, memory leaks will occur.
Note: The SCRMsg structure itself is not freed. Only allocated memory
within this structure is freed. After scr_FreeDecoding() has been
called, all pointers within the SCRMsg structure will be invalid.
Input:
Ø
*l_msg
The SCRMsg structure to have its internal memory allocations
freed. Note that the SCRMsg structure itself is not freed.
Output: None
Example
Refer to the example for the function scr_Decode() on the previous
page.
BM210012WT09
69
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
scr_EncodeLogin()
Prototype:
int scr_EncodeLogin(byte *l_buf, char *l_hostid, char *l_passwd)
Description
For DataTAC® 5000 Networks Only. This function is used to encode
the RNG login packet that is sent to the RNG when the connection is
first established.
Input:
Ø
*l_buf
The buffer for the encoded login packet to be returned in. When
calling this function, this parameter must point to an allocated
buffer of at least SCR_MAX_LEN bytes.
Ø
*l_hostid
The DataTAC host login or host id
Ø
*l_passwd
The DataTAC host password
Output:
×
Return value = 0
Operation failed. The Network Type is not set to DataTAC 5000.
×
Return value < 0
Operation failed. Value SCR_ERROR is returned to indicate an
error
×
Return value > 0
Operation was successful and the number of bytes is returned in
l_buf.
Example
#include 
byte
lbuffer[SCR_MAX_LEN]; /*buffer for SCR login
packet*/
int
llen;
/*length of SCR login packet*/
x25call( .
. );
/*make the connection to the RNG*/
llen = scr_EncodeLogin(buffer, 'LOGIN', 'PASSWORD');
if (llen == SCR_ERROR) {
/*report an error*/
. . .
else if (llen > 0) { /*for non-DataTAC 5000 networks,'/
/*llen will be zero, so we do not
*/
/*need to send the login message.
*/
*/
/* For DataTAC S000, send encoded login message to RNG
x25_send(. . . [buffer, lien, . . .)
Wavenet Technology
70
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
BM210012WT09
71
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
scr_Print()
Prototype:
void scr_Print(FILE *l_fp, SCRMsg *lmsg)
Description
This routine prints an ASCII representation of the SCR message
structure to the given file. This is intended to be used for debugging or
tracing purposes.
Input:
Ø
*l_fp
The file pointer to write the message details to.
Ø
*l_msg
The message structure to print.
Output: None
Example
#include 
SCRMsg lmsg;
FILE *lfp;
/* SCR message struct */
/* file to dump message to */
/* receive a message and decode it into lmsg */
lfp = fopen(“debug.trc”, "a");
if (lfp != (FILE *)NULL) {
fprintf(lfp, “\nReceived the following
message:\n");
scr_Print(lfp, &lmsg);
fclose(lfp);
Wavenet Technology
/* process message */
. . .
72
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
Sample Output
The output from the scr_Print() function shows the message type,
followed by all the appropriate fields from the message structure.
Shown here are several examples of possible output from the
scr_Print() function:
FROM_NET Message
The FROM_NET message is printed as an OB message for a DataTAC
4000 network.
*** OB message ***
LLI 80051234
Data header - BB1
Data –
0 54 68 69 73 20 69 73 20 73 6F 6D 65 20 64 61 74 This is some
10 61 2E
data.
For DataTAC 5000 and DataTAC 6000 networks, a FROM_NET
message is printed as an MI message.
*** MI message ***
LLI 80051234
Data header - BB1
Data –
0 54 68 69 73 20 69 73 20 73 6F 6D 65 20 64 61 74 This is some
10 61 2E
data.
TO_NET Message
*** TO_NET message ***
LLI 87654321
Save bytes – AA
Acknowledgment - SCR_TONET_ACK_REMOTE
Data header - BB1
Data –
0 54 68 69 73 20 69 73 20 73 6F 6D 65 20 64 61 74 This is some
10 61 2E
data.
ACK Message
For DataTAC 5000 or DataTAC 6000 networks, an ACK message is
printed as an HC message.
*** HC message ***
LLI 87654321
Save bytes – AA
Response - 78 - MT out of range or powered off
For the DataTAC 4000 network, an ACK message is printed as an AB
message.
*** AB message ***
LLI 87654321
Save bytes – AA
Response - 78 - No response from wireless device
BM210012WT09
73
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
scr_NakReasonText()
Prototype:
char *scr_NakReasonText(char *l_reason_code)
Description
This routine converts a response code from an HC or AB message into
a text string describing that code. The returned pointer is a pointer to a
static text string within the library. This string must not be overwritten
or freed. This string pointer will stay valid for the duration of the
program's execution. The text strings correspond to the text given in
the DataTAC 5000 System Host Application Programmer's Manual.
This routine can also be used to perform a network independent test for
successful delivery by checking for a NULL return value from this
function.
Input:
Ø
*l_reason code
The response code from the Ack/AB/HC message.
Output:
×
Return NULL
Operation successful delivery of the message.
×
Return !NULL
Operation failed. Value a char pointer to a text string buffer
containing an English description for the meaning of the given
response code.
Example
#include 
SCRMsg lmsg;
char *lreason;
/* SCR message struct */
/* reason code string */
/* receive a message and decode it into lmsg */
if (lmsg.msg_type == SCR_ACK) {
lreason =
scr_NakReasonText(lmsg.u.ack.response_code)
Wavenet Technology
if (lreason == (char *)NULL) {
printf(“Successful delivery of message\n”);
else {
printf(“Failed delivery to LLI %08X reason ‘%s'\n", lmsg.u.ack.lli, lreason);
74
BM210012WT09
Boomer II User Manual & Integrator’s Guide ____________________________________________ SDK – SCR API
scr_ACReasonText()
Prototype:
char *scr_ACReasonText(char *I_reason_code)
Description
For the DataTAC 5000 Network Only.
This routine converts a reason code from an Activity Confirmation
(AC) message into a text string describing that code. The returned
pointer is a pointer to a static text string within the library. This string
must not be overwritten or freed. This string pointer stays valid for the
duration of the program's execution. The text strings correspond to the
text given in the DataTAC 5000 System Host Application
Programmer's Manual.
Input:
Ø
*l_reason code
The reason code from the AC message
Output:
×
Return !NULL
Operation successful. Value a char pointer to a text string buffer
containing an English description for the meaning of the given
response code.
×
Return NULL
Operation failed.
Example
#include 
SCRMsg lmsg;
char *lreason;
/* SCR message struct */
/* reason code string */
/* receive a message and decode it into lmsg */
BM210012WT09
if (lmsg.msg_type == SCR_AC) {
lreason = scr_ACReasonText(lmsg.u.ac.reason_code);
if (lreason != (char *)NULL) {
printf(“Activity Confirmation LLI %08X reason '%s'\n”, lmsg.u.ac.lli, lreason);
75
Wavenet Technology
SDK - SCR API ____________________________________________ Boomer II User Manual & Integrator’s Guide
scr_DIReasonText()
Prototype:
char *scr_DIReasonText(char *l_reason_code)
Description
For DataTAC 5000 Dynamic Routed Sessions Only
This routine converts a reason code from a Disconnect Indication (DI)
message into a text string describing that code. The returned pointer is
a pointer to a static text string within the library. This string must not
be overwritten or freed. This string pointer stays valid for the duration
of the program's execution. The text strings correspond to the text
given in the DataTAC 5000 System Host Application Programmer's
Manual.
Input:
Ø
*l_reason code
The reason code from the DI message
Output:
×
Return !NULL
Operation successful. Value a char pointer to a text string buffer
containing an English description for the meaning of the given
response code.
×
Return NULL
Operation failed.
Example
#include 
SCRMsg lmsg;
*/
char *lreason;
*/
/* SCR message struct
/* reason code string
/* receive a message and decode it into lmsg */
Wavenet Technology
if (lmsg.msg_type == SCR_DI) {
lreason = scr_DIReasonText(lmsg.u.di.reason_code);
if (lreason != (char *)NULL) {
printf(“Disconnection - LLI %08X – reason
'%s'\n”, lmag.u.di.lli, lreason);
76
BM210012WT09
Boomer II User Manual & Integrator’s Guide _____________________________________ Application Development
Application Development
This section provides comments and advice that can help you develop
successful wireless enabled applications for DataTAC systems.
Application development for NCL-compliant wireless modem devices
is a two-part process.
The first step sets up the interface between the device host and
the wireless modem. In this step you must consider the
interactions with the wireless modem, as established by the
NCL 1.2 reference specification and the vendor specific
extensions.
The second step involves addressing message routing
information to identify the message destination within the
DataTAC network.
Use the following suggestions to help you develop wireless enabled
applications.
Use PowerSave mode of operation to extend battery life and
operational time for the user. We recommend that the
application does not modify this mode dynamically.
Use the Confirmed mode of operation to perform the following
functions:
BM210012WT09
•
Check the SDU checksum for validity.
•
Re-read SDUs received in error.
•
Read past the last message in Confirmed mode to make
sure the device buffer is fully flushed. If the buffer is not
flushed, the last message is held, consuming valuable
buffer space.
Anticipate new NCL command, event, and response codes:
•
Perform exact matches on event and response codes.
•
Discard any unknown event type.
•
Map any unknown XFAIL code to be a NAK.
Use SDU tags to uniquely identify application-generated SDUs.
Anticipate the user will move between IN_RANGE and
OUT_OF_RANGE conditions. This means you need to
provide:
•
A user indicator that identifies the current operating
status.
•
Recovery mechanisms when application transactions
fail as a result of losing network contact.
77
Wavenet Technology
Application Development _____________________________________ Boomer II User Manual & Integrator’s Guide
Roaming Issues
During development, consider how the coverage for your wireless
enabled application could be affected by a user moving in and out of
the network coverage area. Coverage can be temporarily impacted by
moving from one side of a building to another. Coverage can be lost for
a longer time by moving beyond the network coverage boundary.
In application development, addressing this temporary or longer term
gap in coverage, even in midst of an application transaction, is
essential.
You can address this consideration by providing a transport level
protocol that can account for the following roaming related situations
when used with a DataTAC wire-less modem:
Inbound SDU failure
Outbound SDU failure
Loss of network contact
These situations are discussed in detail from page 80.
In this case, the transport level protocol must have components both
within the server and client application environment. This transport
level protocol can be provided using existing third party software for
DataTAC systems. Alternatively, you can develop a transport level
protocol with your application in mind.
Roaming Requirements
The roaming algorithms for the wireless modem are described as
follows:
Note: In each case, re-establishing network contact requires the
wireless modem to scan all likely channels and to handshake with the
network.
Send a quick (bounded) response to SDU transmit requests
When the wireless modem loses network contact, SDUs are returned
with an out-of-range failure code. In this case, the wireless modem also
indicates that it is out-of-range via an NCL event. When network
contact is re-established, the wireless modem indicates an in-range
event. The client application then resubmits any SDU last rejected with
an out-of-range response.
Acquire the channel quickly
All channels are scanned quickly, starting with the dynamic channel
list that contains the last used channel and its neighbours. (This list is
broadcast periodically by the network.) If you cannot establish network
contact using the dynamic channel list, the wireless modem scans
quickly using the preprogrammed, network-specific static channel list.
If network contact is not established using either list, this sequence is
Wavenet Technology
78
BM210012WT09
Boomer II User Manual & Integrator’s Guide _____________________________________ Application Development
repeated after a delay interval. See “Conserve battery life when out of
range” below.
Conserve battery life when out-of-range
When all channels (from both dynamic and static channel lists) are
scanned and network contact is not established, the wireless modem
enters a scan-delay state. The scan-delay starts at one second and
doubles on each scan cycle failure, to a maximum of 255 seconds
between scan cycles. This delay time is reset to one second by
establishing a network connection or by power-cycling the device.
Re-establish network contact following inbound SDU failure (no
response) and poor RF RSSI or signal quality
Any wireless modem experiencing a no-response inbound SDU failure
and either with RSSI or quality below the exit threshold level must reestablish network contact. If unable to re-establish network contact, the
modem indicates an out-of-range event. When network contact is reestablished, the wireless modem indicates an in-range event. The client
application then resubmits any queued inbound SDU last rejected with
an out-of-range response.
Re-establish network contact due to loss of outbound channel
The wireless modem attempts to re-establishes network contact
following loss of the outbound channel. If unable to re-establish
network contact, the modem indicates an out-of-range event, and
procedures to re-establish network contact are initiated. When network
contact is re-established, the wireless modem indicates an in-range
event. The client application then resubmits any queued inbound SDU
last rejected with an out-of-range response.
Seek and locate the preferred alternate channel when the existing
channel degrades to a marginal level
When the existing RF channel degrades to a marginal (but still usable)
level, the device periodically listens to neighbouring channels to
determine whether a preferred alternate channel exists. This action
occurs when the device would otherwise be sleeping, to prevent impact
to the device’s synchronized-receive capability with the network.
To be considered, a preferred alternate channel must meet the
minimum channel entry criteria and be 5 dBm better than the current
channel. If located, a full channel acquisition is performed to verify all
other aspects of the alternate channel before registering to the new
channel. This preferred-channel pre-roam algorithm is performed at
intervals that increase exponentially and with identical reset conditions.
See “Conserve battery life when out-of-range” above.
BM210012WT09
79
Wavenet Technology
Application Development _____________________________________ Boomer II User Manual & Integrator’s Guide
Inbound SDU Failures
Potential SDU inbound failure codes are described below. The list
identifies all likely SDU failure responses. The remaining SDU
responses that appear in the NCL 1.2 reference manual are not
expected to occur within the Motorola DataTAC wireless modem.
Inbound SDU failure, no response from network
The SDU was transmitted, but not acknowledged by the network. The
SDU may have been delivered; the acknowledgment might have been
the element that could not be successfully returned to the originating
device.
Inbound SDU failure, host down
This failure indicates that the internal network connection to the
application host computer is currently unavailable. Because DataTAC
networks are designed with very high reliability, this failure is
extremely rare.
Inbound SDU failure, low battery
The SDU could not be delivered due to a low battery condition. When
a low battery condition is reached, the radio network connection is
dropped until the low battery condition is corrected. (This can be
addressed by replacing the battery or, if trickle charging is enabled,
waiting for a sufficient charge level to be reached.)
Inbound SDU failure, inbound queue full
This response indicates that the maximum number (2) of SDUs are
already queued within the wireless modem. Another SDU can be
submitted when the NCL response for one of the pending SDUs has
been returned.
Inbound SDU failure, out of range
The wireless modem has either lost network coverage or is in the
process of re-establishing network contact. See “Loss of Network
Contact” on the following page.
Inbound SDU failure, transmitter disabled
This SDU failure code indicates that the radio transmitter has been
disabled, under application control, within the wireless modem. The
transmitter must be enabled prior to submitting an SDU.
Note: This could be the result of transmitting a Receiver Disable
command to the wireless modem. This command requires both
Receiver Enable and Transmitter Enable commands to recover twoway communications.
Wavenet Technology
80
BM210012WT09
Boomer II User Manual & Integrator’s Guide _____________________________________ Application Development
Outbound SDU Failure
Due to the unreliable delivery of RF data packets (and their responses),
a client application must consider the possibility of an outbound SDU
being delivered to the client, with the transport confirmation of that
data packet being lost (RF acknowledgment and/or transport level
acknowledgment).
Note: When developing a centralized server and distributed-mobile
client wireless enabled application, outbound SDU failure is primarily
a server application issue.
When this occurs, the client and server transport levels must
resynchronise to a common level before proceeding. Such an
understanding might require retransmission of the transaction or
retransmission of the transport confirmation.
Loss of Network Contact
When a wireless modem experiences a loss of network contact, queued
SDUs are returned with the out-of-range response code and with outof-range event indicated. A loss of contact can occur for the following
reasons:
Moving beyond network coverage
When the device moves beyond the network boundary, network contact
loss could occur for an extended period. Depending upon the user route
and network coverage area, this interval could extend from a few
minutes to several hours (or longer). Once network contact is reestablished, the client and server application must be resynchronised if
applications transactions have failed during the interval. After network
contact has been announced, further delays should be minimised, as the
user becomes acquainted with the coverage area.
Moving between areas of network coverage
Small movements within the area of network coverage can result in the
loss and reacquisition of network contact, as a result of RF penetration
difficulties with specific network topology and terrain. It might take
from a few tenths of a second to a few minutes to recognize the channel
has degraded to an unusable level, to qualify a new channel, and to reestablish network contact. Again, the client and server application must
be resynchronised if application transactions failed during this interval.
Acquiring improved network coverage
A channel might originally have been marginal, or might have
degraded from a good to a marginal level, or might be negatively
impacted by the presence of other objects that influence its capability
to send and receive data. Under such circumstances, the wireless
modem seeks a preferred alternate channel, as previously described.
BM210012WT09
81
Wavenet Technology
Application Development _____________________________________ Boomer II User Manual & Integrator’s Guide
Usually this situation does not produce notification of network contact
and reacquisition.
Low battery
Network contact is dropped when a low battery condition is reached.
This follows a battery alert notification (warning) that occurs while the
battery still has some remaining usable capacity. The time between
these events is much influenced by the battery technology and the level
of transmit activity within the wireless modem. A relatively inactive
device provides more warning time than an active device. Also, an
alkaline battery provides more warning than a NiCad battery.
Low buffers
If outbound SDUs remain unread within the wireless modem, its
outbound buffers are eventually filled. When this occurs, network
contact is dropped. Network contact is re-established when the internal
buffer pool within the wireless modem reaches a usable level, as a
result of SDU reads by the application. This situation never occurs
when the client application reads continuously to clear the wireless
modem of received outbound SDUs.
Receiver disabled
The client application can disable the wireless modem transceiver by
using the Receiver Disable NCL command. When this occurs, network
contact is dropped and the radio is turned off. Network contact is reestablished when the application issues the Receiver Enable, then the
Transmitter Enable NCL commands.
Power Management
The following modem power management options can be included in
an application to maximize battery life:
PowerSave Mode
The wireless modem defaults to PowerSave mode when turned on if
the network supports the PowerSave protocol. If you are concerned
about latency of unsolicited outbound messages, you can turn off the
PowerSave mode, but at the expense of consuming more battery power.
For details, refer to the NCL 1.2 command S_POWER_SAVE_MODE.
See “Battery Life Considerations” and “PowerSave Protocol” on the
following page.
Dynamically modifying the PowerSave mode of the device is not
recommended.
Inactivity Time-Out
Configure inactivity time-out to trigger if a message is not read from
the modem within a certain number of minutes.
Wavenet Technology
82
BM210012WT09
Boomer II User Manual & Integrator’s Guide _____________________________________ Application Development
To keep the wireless modem card from disconnecting from the network
(and turn off its radio) following an undeliverable outbound message,
disable the host inactivity timeout by issuing an
S_INACTIVITY_TIMEOUT command to the wireless modem card.
Set the timeout value to 255 (the default).
On/Off upon User Demand
To extend battery life, design the application to switch the modem on
and off as the usage need arises. This method is especially effective for
session-based, user-initiated applications.
Radio On/Off on Application Command
The radio is the primary power-consuming component in the wireless
modem card. Use S_RX_CONTROL for very effective control of
session-based, user-initiated applications.
Battery Life Considerations
In addition to specific power management options, some application
design decisions greatly affect battery life, as follows:
User traffic, amount and frequency
Commercially available compression techniques can significantly
reduce traffic volume, which improves device battery life and reduces
network usage costs. PowerSave mode batches outbound traffic at a
periodicity equal to the network-defined PowerSave protocol frame
size.
Data compression
Improve battery life by reducing and compressing the broad-cast
application data. Network usage costs can also be significantly reduced
as a result.
PowerSave Protocol
The following points describe unique operational characteristics of
devices that are compliant with the PowerSave protocol when
operating on a network, as compared to those that are not. Specific
PowerSave timing parameters can vary by network, based on how the
network operator sets up PowerSave protocol parameters.
Under PowerSave protocol, unsolicited outbound traffic to a nonawake device is delayed. The worst case delay until the first transmit
opportunity is 128 seconds under DataTAC 4000 networks and 64
seconds under DataTAC 5000 networks. The average delay until the
next delivery opportunity is one half of the worst case time, given the
current network and device configuration.
In DataTAC 4000 systems, initial unsolicited outbound transmission
attempts are actually “ping” messages used to locate the device.
BM210012WT09
83
Wavenet Technology
Application Development _____________________________________ Boomer II User Manual & Integrator’s Guide
In DataTAC 5000 systems, unsolicited outbound messages (or
messages that have missed the previous transmit opportunity) are
delivered in the “root” (that is, home) window for the recipient device.
Once the device is thus awakened, it remains awake for about n
seconds after each message or ACK transmission from the device.
During the wake time the network delivers messages to the device as it
would to a device that is non-compliant with the PowerSave protocol.
(Default n = 20 seconds for DataTAC 4000 networks and 8 seconds for
DataTAC 5000 networks.)
Roaming and location update reporting to the network happens more
slowly because the PowerSave protocol device takes longer to respond
to changes in the RF environment. The infrequent worst case latency in
responding to external stimuli (resulting in either a location update or
new channel scan) is about 9 minutes for DataTAC 4000 networks.
DataTAC 5000 networks respond typically in 1.5 Power-Save protocol
frame times, or about 96 seconds.
Wireless Data Systems Considerations
The wireless modems application developer must account for the
limitations of a wireless data system to minimize their impact on the
user.
Limited Data Capacity on Radio Frequency Channels
The channels available to wireless modems are narrow-band and have
limited information carrying capacity (bandwidth) when compared to
traditional wireline communications. Additional capacity can be gained
only by increasing the number of channels, improving the hardware
technology, or by developing more efficient applications. As a result of
all these limitations, it is not surprising that wireless networks are often
more expensive to operate on a per-packet basis than wireline Wide
Area Networks (WAN). To address this concern, the NCL has been
designed to provide the most efficient way of using the limited channel
bandwidth.
Message Delivery Cannot Be Guaranteed
Because a wireless device can roam without restriction, it can exit the
network RF coverage area, leaving it unable to receive or successfully
transmit messages. When a device is outside the coverage area, the
applications are informed of failed inbound delivery. The application is
required to take appropriate recovery action.
Variation in Message Transit Times Across the Network
The time interval messages transit the network is affected by the RF
protocol, the message load on the network, and the length of a
message. These variations might need to be taken into account by the
application.
The following sections address some of these shortcomings in more
detail.
Wavenet Technology
84
BM210012WT09
Boomer II User Manual & Integrator’s Guide _____________________________________ Application Development
Application Efficiency
One goal of application development is to provide the required
functionality with the least amount of messaging. The consideration
here is to minimize the number of interactions in an information
exchange. Doing so addresses the limited data capacity and increased
costs of wireless messaging. In addition, the pricing structure of
network operators encourages efficient application design. In fact,
applications can be designed to use data compression or to apply
techniques that send only data fields that change between transactions.
Large Message Transfer
Message size is a key factor affecting response times in wireless data
systems. To efficiently accommodate typical data applications, the
DataTAC 5000 system is optimized for the transfer of short and
medium length messages. Typically, messages up to 512 bytes are
transferred across the network as a single data packet. Messages larger
than 512 bytes are segmented into 512-byte packets by the DataTAC
system before being transmitted over the air. The packets are
reassembled before they are delivered to the application. For MDC
4800 operation on DataTAC 4000 systems, the segmentation size is
256 bytes.
For example, a 600-byte user message or service data unit (SDU)
results in the delivery of two packets, or protocol data units (PDU), that
are reassembled in the wireless device. Each PDU requires a Radio
Data-Link Access Procedure (RD-LAP) acknowledgment from the
device, which takes a few seconds to complete. The fewer PDUs in a
message, the shorter the delivery time. If messages larger than 2 kB are
to be sent across the system, the host and wireless device application
must provide the segmentation and reconstruction functions.
Message Transit Time
The time required for an inbound or outbound message to travel across
the network is primarily a function of the queuing delays associated
with each product in the network infrastructure and the message load
on the system. As system traffic builds, queuing delays increase for
outbound traffic, while the average time to access the inbound channel
increases, resulting in longer inbound message transit times.
Additional delays are encountered when the wireless terminal is in the
process of roaming from one cell on one radio channel to a cell on
another radio channel. If the cells are controlled by the same cell
controller, the delay time is quite short. The delay time can increase if
the cells are controlled by different cell controllers on different
subnetworks.
For a DataTAC 5000 fixed-end system operating at full rated capacity,
the mean transit delay between a network host and a wireless device is
typically no more than four seconds.
BM210012WT09
85
Wavenet Technology
Application Development _____________________________________ Boomer II User Manual & Integrator’s Guide
The application developer must develop operational scenarios to
accommodate the variable transit time in the application design.
Wavenet Technology
86
BM210012WT09
Boomer II User Manual & Integrator’s Guide _____________________________________ Application Development
BM210012WT09
87
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
Message Routing and Migration
This section offers developers advice on how to migrate their
applications. That is, how to create new versions of their wireless
applications for porting to other DataTAC ® systems. You can also use
this information to plan ahead for portability as you begin your initial
application development effort.
As the developer and user communities become more international in
scope, successful applications will be distinguished by their portability
across existing DataTAC networks. This is true whether you are
designing a new application or migrating an existing application to
other networks.
Message Routing
Three versions of DataTAC systems are in operation worldwide, as
noted by where they are currently implemented:
DataTAC 4000 systems (North America)
DataTAC 5000 systems (Asia-Pacific and Middle East)
DataTAC 6000 systems (Europe)
The architectures of the three systems are basically alike. Although
they support different link layer protocols, the systems the systems
differ mainly in their message header syntax.
The distinction between host communications and peer-to-peer
messaging is also important. Separate DataTAC protocols support each
of these application models. The primary host communications mode is
Standard Context Routing (SCR), also known as fleet mode. Another
application mode is DataTAC Messaging (DM) , which handles
messaging among terminals (subscriber units).
SCR and DM are the common sets of rules that describe how to format
message headers on DataTAC systems. Although the header format
differs slightly among DataTAC 4000, 5000, and 6000 systems, the
functional concepts of operation are the same. The exact SCR and DM
syntax for each system is available in their separate Host Application
Programmer’s Manuals.
Other connection options are available for DataTAC 5000 and 6000
systems. Two of these are known as “personal shared” (Type I)
connections and “personal dedicated” (Type II) connections. These are
covered in the system host programming guides.
Note: In this section, “host” refers to the network fixed host.
“Terminal” refers to a subscriber device. In these guidelines a byte is
8 bits.
Wavenet Technology
88
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
Network Link Layers
Before a message can be routed, it must contain a header and be
wrapped in a link layer protocol supported by the DataTAC network.
Many link layer protocols are available, but not all are supported by
each DataTAC network.
The X.25 protocol is common to all three systems and supports both
PVC and SVC host connection line types. X.25 is a popular choice for
developers looking for a worldwide connectivity solution.
Other supported protocols include:
BM210012WT09
DataTAC 4000 system
X.25, TCP/IP, LU6.2, leased line,
dial-up, RF-Loopback
DataTAC 5000 system
X.25, TCP/IP, SLIP
DataTAC 6000 system
X.25
89
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
Standard Context Routing (SCR)
SCR allows the central host to communicate with hundreds, even
thousands of terminals across a single host connection. But the real
advantage of using SCR is economic: The host only pays for a single
connection to the network, significantly reducing communications cost.
When a terminal sends a message to the host, the message must contain
a header that includes the sending terminal ID. This enables the host to
identify which terminal sent the message and which terminal the host is
to poll.
DataTAC System Architectures
Other header fields provide the host with options for instructing the
network on handling undeliverable messages. For example, the host
can ask the network to:
Provide a delivery status of messages.
Hold messages on the network for a later delivery.
Discard messages.
This header and instruction information is the basis of the SCR
protocol.
Wavenet Technology
90
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
SCR Message Types
Fleet mode of communications uses three types of messages:
Commands / Host Requests (host-to-network)
EXAMPLE: Send Message #1 to LLI 87654321
Responses / Host Confirmations (network-to-host)
EXAMPLE: Message #1 to LLI 87654321 was ACKed
Events / Mobile Information (terminal-to-network-to-host)
EXAMPLE: Message received from LLI 12345678
A fourth type of message, the status message, is allowed on DataTAC
4000 and 5000 systems, but it is not supported on DataTAC 6000
systems.
Each message type must include a unique header; small differences
within each type of header exist among the systems. The charts
graphically compare the headers for each system.
Highlights of SCR Differences
The following topics explain:
Which system or systems implement a particular function.
What this function does and how it varies by system.
How to migrate an application from one system to another.
Nomenclature
When migrating applications, use the correct message type codes.
Because DataTAC systems were originally designed for unique
markets during different development periods, each shows its separate
lineage and is described using inconsistent terminology. For example,
this occurs at the beginning of the SCR header, where the code
designating the message type varies by system, as shown in the
following table.
Message Type
(direction)
Command
(host-to-network)
Response
(network-to-host)
Event
(terminal-to-host)
DataTAC 4000
System
DataTAC 5000
System
IB
(inbound basic)
AB
(acknowledgment basic)
OB
(outbound basic)
HR
(host request)
HC
(host confirmation)
MI
(mobile information)
DataTAC 6000
System
HR
(host request)
HC
(host confirmation)
MI
(mobile information)
Note: The DataTAC 4000 system designates the direction of the
command message as inbound from the host to the network and
outbound from the network to the host (opposite from current industry
terminology).
BM210012WT09
91
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
ASCII versus Binary Encoding
DataTAC 4000 system SCR fields are all ASCII encoded fields of
numeric values or alphanumeric strings. DataTAC 5000 and 6000
systems use a mixture of ASCII and binary encoded fields. All three
systems allow the user to send binary data, regardless of header
encoding.
Support for TCP/IP
DataTAC 5000 systems provide support for TCP/IP hosts, allowing
interconnection across local Ethernet LANs or even the Internet. SCR
messages are carried within a single TCP/IP data stream, which allows
SCR communications with multiple terminals.
Although TCP/IP provides a reliable stream of contiguous data, the
application must be able to determine the beginning and end of each
SCR message. The SCR header on DataTAC 5000 systems must start
with a 16 bit (2 byte) length field (bytes L1 and L2), which specifies
the length of the frame.
Length Prefix Field
DataTAC 5000 systems require all SCR messages to be prefixed by a
two-byte binary encoded length field (L1 and L2). This field provides
TCP/IP based connections with data that determines the length of each
SCR message. The length count includes everything in the message
packet, except for the length prefix.
When converting an application to a DataTAC 5000 network, the
length field must be prefixed to all SCR messages.
Host Authentication
Before SCR transactions can be performed on DataTAC 5000 and
DataTAC 6000 systems using a host-initiated connection, the host first
sends a host authentication message to the radio network gateway
(RNG). The authentication message must be the first message sent to
the RNG after establishing link layer communications. The RNG drops
the connection when any of the following conditions occurs:
The host does not send the authentication message within one
minute
The host ID and password do not match those in the RNG
database
The host is not enabled in the RNG database
The host is already connected to the RNG
On DataTAC 5000 systems the authentication message consists of:
Wavenet Technology
Host ID (up to 20 characters)
ASCII ‘;’ (semicolon) delimiter
Host password of 1 to 8 bytes
Carriage return
92
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
On DataTAC 6000 systems the host ID field consists of:
1 to 4 bytes
ASCII ‘;’ (semicolon) delimiter
Host password of 1 to 8 bytes
Carriage return
On DataTAC 4000 systems the RNG (ARDIS switch) locates the
calling X.25 address to verify it is in the database. A valid calling
address is then associated with only those terminals allocated to a
particular host.
Extended SCR
DataTAC 4000 and 5000 systems support additional message types and
functions beyond the basic SCR functionality. Specifically, extended
SCR supports the following features:
On DataTAC 4000 systems:
Sends binary headers and data
Notifies the host of terminal network activity
On DataTAC 5000 systems:
Notifies the host of terminal network activity
Performs loopback diagnostics
Notifies the host of terminal-to-host connection (session)
activity
For a full description of these extensions, refer to the system host
application programmer’s manuals.
On DataTAC 4000 and 5000 systems the extended functions enable the
network to notify the host that a terminal has registered with or
deregistered from the network. This allows the host to avoid X.25
communications costs associated with attempting to reach a shut down
terminal.
This extension set also involves the no-acknowledgment (No-ACK)
option for host-to-terminal messages. When the No-ACK option is
used on DataTAC 5000 systems, the host instructs the RNG to deliver
the over-the-air message as “No-ACK-needed”, and none is returned.
On DataTAC 4000 and 6000 systems, which lack the No-ACK option,
the RNG sends all messages as “ACK-required,” regardless of a host
request for “No-ACK-needed.” When the RNG receives the ACK from
the terminal, it is discarded or used to provide input to other systemspecific features.
Avoid using additional message types if you want the application to be
widely compatible. These extended features are not always available on
all DataTAC 5000 systems. These features are enabled and controlled
by the network operator on a per-host basis. Check with your target
network operators before using SCR system extensions.
BM210012WT09
93
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
Note: To run your application on DataTAC 4000 or 6000 systems, you
must isolate the use of extended SCR or avoid it entirely.
Service Data Unit (SDU) Size
An application SDU consists of the complete message; both user data
and data header. See “Data Header Routing” below. The maximum size
of an application SDU is 2048 bytes for DataTAC 5000 and 6000
systems, and 2550 bytes for DataTAC 4000 systems. For this reason,
the recommended maximum SDU size for tri-system applications is
2048 bytes.
For transport over the air, the SDU is broken up into smaller physical
data units (PDUs). Most network operators price their service at cost
per PDU or cost per SDU. Gather data from your various operators to
develop an application design that favorably considers these cost
factors.
Note: As a general rule, it is less expensive to send fewer large packets
than many small packets. Try to take full advantage of the space
available in each packet.
Data Header Routing
To use the data header to route messages properly, first consider the
data header as a pointer to a destination.
In early DataTAC systems, all mobile units sent their messages to a
single host. Because all traffic went to one destination, there was no
need for a destination header. Later, a data header field was added to
inform the network where (to which host or peer) to direct a particular
SDU or message.
Although the data header field can range in size from 0 to 64 bytes, by
convention most applications are written using a 3-byte data header.
The DataTAC systems each use a different portion of these three bytes
as a pointer to a destination. This pointer is called a session ID. Setting
these three bytes (the entire data header field) to a common value
guarantees compatibility across all three systems.
Here are the specific differences in how the systems implement the
session ID:
On DataTAC 5000 systems, the first two bytes of the data header point
to a destination. (These two bytes are referred to as the session ID.)
On DataTAC 4000 and 6000 systems, the third byte only of the data
header points to a destination. (The third byte is also known as a host
slot on these systems.)
An example of these system differences is illustrated below. Each row
in the table depicts the application-visible portion of the DataTAC
system header for the identified system. In the data header column the
session ID bytes appear in bold typeface. The data header offset field
identifies the length in bytes of the data header field.
Wavenet Technology
94
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
DataTAC
Header Fields
Data Header
Offset
Data Header
Data
System Type
(Not Shown)
4000
...
03
T E1
Hello World
5000
...
03
TE1
Hello World
6000
...
03
T E1
Hello World
In this example the data header TE1 is a sample. The data header could
also have been RO3, TX4, SS2, or many others, depending on the
configuration of the network infrastructure.
The DataTAC 4000 and 6000 systems use 1 as a pointer to a
destination and TE to refer to an application ID. Conversely, the
DataTAC 5000 system uses TE as a pointer to a destination and 1 as an
extra byte, which only has meaning if active carrier management
(ACM) is used. Since SCR does not require ACM, this byte can be
ignored.
Note: Using this example, for cross compatible applications (to all
DataTAC systems), set a data header offset of 03 (ASCII) and set the
same data header for all three systems (in this example, TE1).
Consider another example. A DataTAC 4000 or 6000 system could use
a data header of XY3 for one message and a data header of AB3 for
another message. According to current system implementations of the
session ID feature, both SDUs would go to the same destination
because the third byte (the pointer to the destination) is the same.
SCR Header Charts
The charts in this section allow you to compare SCR syntax across all
three DataTAC systems. Each chart displays a different set of headers
based on message type. For example, the length prefix on the DataTAC
5000 system header and much of the DataTAC 4000 system header are
shaded in gray to highlight fields where differences exist. Two of the
data headers are shaded for the same reason, indicating that they differ
in unique ways from the DataTAC 5000 system data header.
Note: All header reserve fields must be set to ASCII 0 (0x30) or binary
NULL (0x00), depending on the format requirements of the field.
The following table shows the terminology of other communications
protocols (for example, Native Control Language), and the SCR header
types.
BM210012WT09
Other Protocol Terminology
SCR Terminology
Command Message
Host Request Message
Response Message
Host Confirmation Message
Event Message
Mobile Information Message.
95
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
The list preceding each chart describes the contents of the header
fields.
Host Request Message Header Fields
Wavenet Technology
Save Bytes
Supplied by the host and used by the network to tie
the confirmation to the original host request. Save
bytes are ASCII for DataTAC 4000 systems. Save
bytes can be ASCII or binary for DataTAC 5000 and
6000 systems.
Length
Prefix
DataTAC 5000 systems require all SCR messages to
designate the length of the message. The length count
does not include the length prefix itself, but does
include everything else in the message packet.
Type Code
Identifies the type of the SCR message: Use ‘I’ ‘B’ for
DataTAC 4000 systems. Use ‘H’ ‘R’ for the other
systems.
LLI
Identifies the subscriber terminal to which the
message is being routed. On DataTAC 4000 systems
the field (also known as Terminal ID) is ASCIIencoded in 8 bytes. On the other systems it is binary
encoded in 4 bytes (the first four bytes of this 8-byte
field are reserved).
Format
Indicator
Used in DataTAC 4000 systems only, to specify the
format of the data in the user data section of the
message. This field is reserved on the other systems
and handled by their Format field, as noted in this list.
Delivery
Option
DataTAC 4000 systems allow four priorities for a
message in the Priority field. Other systems allow two
delivery options: Send once and quit; send and queue
until delivered or timed out.
Confirmation
Mode
On DataTAC 4000 systems this is also known as
Acknowledgment Indicator. On all systems this mode
allows the host to specify the conditions under which
a confirmation message is returned for the message
being submitted.
Format
For DataTAC 5000 and 6000 systems only, a fixed
value set to $15 (hex). This field replaces the Format
Indicator field on DataTAC 4000 systems.
Format
Dependent
For DataTAC 5000 and 6000 systems only, a fixed
value set to $C0 (hex).
Data Header
Offset
On DataTAC 4000 systems this field is also called
Data Header Size. On all systems it specifies the
number bytes in the data header portion of the
message.
96
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
Information
BM210012WT09
For all systems, these fields include the data header
and user data for the application.
97
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
Host Confirmation Message Header Fields
Length Prefix
DataTAC 5000 systems require all SCR
messages to designate the length of the
message. The length count does not include
the length prefix itself, but does include
everything else in the message packet.
Type Code
Identifies the type of the SCR message: Use
‘A’ ‘B’ for DataTAC 4000 systems. Use ‘H’
‘C’ for the other systems.
LLI
Identifies the subscriber terminal to which the
message is being routed. On DataTAC 4000
systems the field (also known as Terminal ID)
is ASCII-encoded in 8 bytes. On the other
systems it is binary encoded in 4 bytes (the
first four bytes of this 8-byte field are
reserved).
Save Bytes
Supplied by the host and used by the network
to tie the confirmation to the original host
request. Save bytes are ASCII for DataTAC
4000 systems. Save bytes can be ASCII or
binary for DataTAC 5000 and 6000 systems.
Response Code
Known as Acknowledgment code in
DataTAC 4000 systems, this field indicates
the delivery status of the message to which
the save bytes refer. On DataTAC 4000
systems, acknowledgments are indicated by
the ASCII value ‘00’. On other systems,
acknowledgments are indicted by any value
(ASCII-encoded hex) from ‘08’ through ‘0F’.
NAKs (negative acknowledgments) are in the
range of ‘10’ to ‘A0’ for DataTAC 4000
systems and in the range of 40-97, A0-A5 for
DataTAC 5000 and 6000 systems. DataTAC
5000 and 6000 systems also have these
additional response codes:
‘A1’ Terminal message in progress
‘A2’ Terminal out of service
‘A3’ Invalid session or host ID (invalid
routing info.)
‘A4’ Maximum terminal queue exceeded.
Wavenet Technology
98
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
BM210012WT09
99
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
Mobile Information Message Header Fields
Wavenet Technology
Length Prefix
DataTAC 5000 systems require all SCR
messages to designate the length of the
message. The length count does not
include the length prefix itself, but does
include everything else in the message
packet.
Type Code
Identifies the type of the SCR message:
Use ‘O’ ‘B’ for DataTAC 4000 systems.
Use ‘M’ ‘I’ for the other systems.
LLI
Identifies the subscriber terminal from
which the message is being received. On
DataTAC 4000 systems the field (also
known as Terminal ID) is ASCIIencoded in 8 bytes. On the other systems
it is binary encoded in 4 bytes (the first
four bytes of this 8-byte field are
reserved).
Format Indicator
Used in DataTAC 4000 systems only, to
specify the format of the data in the user
data section of the message. This field is
reserved on the other systems and
handled by their format field, as noted
below in this list.
Delivery Option
DataTAC 4000 systems allow 4
priorities for a message in the field
formerly known as Priority. The
Delivery Option field is reserved on the
other systems.
Format
For DataTAC 5000 and 6000 systems
only, a fixed value set to $15 (hex). This
field replaces the format indicator field
on DataTAC 4000 systems.
Format Dependent
For DataTAC 5000 and 6000 systems
only, a fixed value set to $C0 (hex).
Data Header Offset
On DataTAC 4000 systems this field is
also called Data Header Size. On all
systems it specifies the number bytes in
the data header of the information
section of the message.
Information
For all systems, these fields include the
100
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
data header and user data for the
application.
BM210012WT09
101
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
DataTAC Messaging (DM)
DM allows one terminal to communicate with up to ten other terminals
by routing a message through the DataTAC system network. As such,
DM provides the protocol for basic E-mail functionality. System
differences with regard to DM appear mainly as differences in DM
syntax.
DM Message Types
Peer-to-peer communications uses two types of messages:
Generate (originator-to-network)
Receive (network-to-destination)
Each message type must include its own type of header. Within each
system, each type of header has small differences in syntax. The charts
graphically compare the headers across systems.
Highlights of DM Differences
Each of the three DataTAC systems varies slightly according to how it
implements DM. Use the table below to identify the system differences
by DM attribute.
DM attribute
DataTAC 4000
Systems
DataTAC
5000Systems
DataTAC
6000Systems
Address length
8 bytes
14 bytes
14 bytes
Error reporting
Does not include an
error number prefix
as part of the error
text.
Includes an error
number prefix as part
of the error text.
Does not include an
error number prefix
as part of the error
text.
Time-stamping
Yes
Yes
No
Message storage
Configurable
10 messages
100 messages
DataTAC Messaging Implementation Differences
Wavenet Technology
102
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
DM Header Charts
The charts in this section allow you to compare DM syntax across all
three DataTAC systems. Each chart displays a different set of headers
based on message type. The charts show the differences you need to be
aware of for your particular project. The list preceding each chart
describes the contents of the header fields.
Message Generate Header Fields
BM210012WT09
Type
All systems use ASCII ‘M’ ‘G’ to indicate
a Message Generate type message header.
Sender ID
The ID of the originating wireless
terminal. On DataTAC 4000 systems this
field is 8 bytes. On other systems it is 14
bytes.
First Destination ID
The ID of the first of up to 10 destination
terminals.
Last Destination ID
The ID of the last of up to 10 optional
destination terminals.
Flag Bytes
Settings for optional delivery services.
Date & Time of
Message Generation
The current date and time the message is
generated.
Date & Time for
Delayed Action
The date and time when the message is to
be displayed at the destination. This option
is present is the corresponding flag bit is
set.
Originator’s ID
The ID of the previous terminal of a
message being forwarded by a recipient.
This option is present is the corresponding
flag bit is set.
Sequence Number
A number used by a DM application to
match replies and error messages with a
previously sent message.
Message Text
Can be binary or ASCII, depending on
requirements of the application.
103
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
Wavenet Technology
104
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
Receive Header Fields
BM210012WT09
Type
All systems use ASCII ‘R’ ‘M’ to indicate
a Receive Message type message header.
Sender ID
The ID of the originating wireless
terminal. On DataTAC 4000 systems this
field is 8 bytes. On other systems it is 14
bytes.
First Destination ID
The ID of the destination terminal
Flag Bytes
Settings for optional delivery services.
Date & Time of
Message Generation
The current date and time the message is
generated.
Date & Time for
Delayed Action
The date and time when the message is to
be displayed at the destination. This option
is present is the corresponding flag bit is
set.
Originator’s ID
The ID of the previous terminal of a
message being forwarded by a recipient.
This option is present is the corresponding
flag bit is set.
Sequence Number
A number used by a DM application to
match replies and error messages with a
previously sent message.
Message Text
Can be binary or ASCII, depending on
requirements of the application.
105
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
Wavenet Technology
106
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
Host Messaging (HM)
Host Messaging (HM) is achieved by placing a DM header inside an
SCR header. In addition, the first two bytes (either MG or RM) must be
replaced with HM to signify the message was received from a host,
rather than a peer. HM used in conjunction with DM allows the
terminal to use the same routing protocol regardless of its destination.
(Despite its simplicity, use of HM is not recommended because it is
inefficient). For further details, refer to the InfoTAC Application
Developer’s Guide, Motorola reference: 6804018C65.
Other Development Issues
Localizing and testing your applications are not issues related
specifically to application migration. The following comments are
provided as a helpful reminder only.
Localizing an Application
Whether you are preparing your application for sale internationally or
developing it internally for an international company, consider
designing in international characteristics from the beginning, such as
character encoding, language enabling, and special text formatting.
While such an effort can take longer up front, any eventual re-porting
of the application will be much easier to manage.
Character Encoding
If your application supports languages that use Latin-based characters
(for example, English, Spanish, and German), design your application
for compatibility with 7-bit ASCII/ISO 646 and Latin 1/ISO 8859-1, 8bit display fonts.
If your application support dialects of non-Latin languages, such as
Chinese, Japanese, Korean, or Thai, design your application to work
with Unicode or another 16-bit character encoding standard. In
addition, provide your application with flexible keyboard mapping.
Language Enabling
Isolate all translatable strings, icons, and menus from your program.
Then the greater part of a localization effort will be translation, rather
than re-engineering. Allow for expansion of text strings during
localization. Most translations are longer than the orig-inal. Allow your
program to accept variable-length strings or use the international
language capabilities inherent in the application environment, such as
Windows 3.1, Windows 95, Windows NT, or Windows CE.
BM210012WT09
107
Wavenet Technology
Message Routing and Migration________________________________ Boomer II User Manual & Integrator’s Guide
Special Text Formatting
The display of dates, numbers, and monetary values varies among
locales. Support for these differences may be provided by your
programming environment to simplify the development of code. If your
programming environment doesn’t provide such support, include
alternative tables or options for use when localizing.
Testing an Application
Virtually all public network operators have some testing or certification
procedure available to help ensure that your new applications behave
appropriately when brought onto the network. Many systems also have
test nodes, which allow program testing without risk of interrupting the
public network. Because each operator’s procedures and requirements
differ, check with the operator of your target network regarding their
individual certification procedure.
With the proper documentation, writing an application that will operate
on a wireless network anywhere in the world is not difficult. You don’t
have to develop an application on site in the region where it will
operate. For example, if your local and target networks are the same,
the logistics associated with testing the application are fairly minimal.
Testing an application for a distant target network requires a bit more
planning, since the network is not directly accessible from your
development site. In this case, two approaches are worth considering:
If your application is designed for a DataTAC network in
another country and your local network uses the same version
of DataTAC system as the target network, sign up with your
local network operator for service during development, test, and
support. When the application is complete, it is likely that the
target network operator will require validation or certification
tests. After having used your local network for development
tests, validation testing will probably be a straightforward
process.
If your local network is other than the target network, you might still
want to develop a local version of the application to test the logic and
performance of your program in a controlled environment. (Be sure to
get advanced approval from the local operator to run your test version
without it being validated.) In this case, the target network will not be
tested directly and more verification testing will be required.
Wavenet Technology
108
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Message Routing and Migration
BM210012WT09
109
Wavenet Technology
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
Appendix A - NCL Interface
The Boomer II is compliant to Native Control Language (NCL) 1.2.
Wavenet Vendor-specific extensions are also listed here.
The specification for the NCL protocol may be obtained in Adobe
Acrobat format from the Motorola website at
http://www.mot.com/MIMS/WDG/pdf_docs/8-.pdf
Generic NCL (Native Mode)
Command SDUs (CMND, ASCII A)
Commands
Value
Parameters
Value
SEND
ASCII 1
Send message.
READ_MSG
ASCII 2
Read queued message in RPM. True only if confirmed delivery mode
enabled.
CTL_EVENT
ASCII 3
GET_STATUS
ASCII 4
Event Report SDUs.
Sub-values and Descriptions
Control event.
Get RPM status/configuration.
R_CONFIG_BLOCK
ASCII A
Get RPM configuration block.
R_RF_BLOCK
ASCII A
Vendor-specific: Get RF status block.
R_STATUS_BLOCK
ASCII B
Get RPM status block.
R_PROD_ID
ASCII C
Get RPM product ID:
RF_RDLAP_9.6
RF protocol is RD-LAP 9600.
ASCII 0
RF_RDLAP_19.2
RF protocol is RD-LAP 9200.
ASCII 1
RF_MDC4800
RF protocol is MDC 4800.
ASCII 2
RF_DUAL
Dual RD-LAP 9.2/MDC4800.
ASCII 3
NCL_PRE1.2
NCL support is R1.0 or R1.1.
ASCII 0
NCL_1.2
NCL support is R1.2.
ASCII 2
Wavenet Technology
110
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix A - NCL Interface
Commands
SET_CNF
Value
Parameters
Value
Sub-values and Descriptions
R_SYSID
ASCII C
Vendor-specific: Get system ID of current RF system.
R_SW_VERSION
ASCII D
Get software version number.
R_RPM_ID
ASCII E
Get RPM address.
R_RF_BLOCK_SHORT
ASCII E
Vendor-specific: Get short form of RF status block.
ASCII F
Reserved.
R_MAX_DATA_SIZE
ASCII G
Get SDU data limit.
R_RPM_GID
ASCII H
Get RPM group IDs.
R_WAN_TYPE
ASCII I
Get WAN Type Code.
R_RF_VERSION
ASCII J
Get RF protocol version number.
R_VENDOR_ID
ASCII K
Get vendor information: VEND_MOTOROLA Vendor is Motorola
ASCII 0
ASCII
L..Z
Reserved.
R_RCV_MODE
ASCII a
Get mode of notification to the DTE for received SDUs.
R_RX_STATUS
ASCII b
Get receiver enable status.
R_TX_STATUS
ASCII c
Get transmitter enable status.
R_ANTENNA
ASCII d
Get antenna selection status.
R_RADIO_IN_RANGE
ASCII e
Get radio in range status.
R_OB_MSG_COUNT
ASCII f
Count of outbound messages queued.
R_IB_MSG_COUNT
ASCII g
Count of inbound messages queued.
R_FLOW_CONTROL
ASCII h
Get flow control status.
R_EVENT_STATES
ASCII i
Get current event reporting enable/disable state.
R_RADIO_CHANNEL
ASCII j
Get current radio channel.
R_CHAN_BLOCK
ASCII k
Get RPM RF channel status block.
R_RF_STATISTICS
ASCII l
Get RPM RF statistics block.
R_BAT_LEVEL
ASCII m
Get battery status.
ASCII n..x
Reserved.
R_DCHAN_TABLE
ASCII y
Read dynamic channel table.
R_CHAN_TABLE
ASCII z
Read static channel table.
ASCII 5
Set modem configuration.
S_RCV_MODE
ASCII A
Select the confirmed/unconfirmed Receive Data mode.
S_INACTIVITY_
TIMEOUT
ASCII A
Vendor-specific: Set read time for outbound packet.
S_TX_CONTROL
ASCII B
Enable/disable the transmitter.
S_RX_CONTROL
ASCII C
Enable/disable the radio.
S_FLOW_CONTROL
ASCII D
Select the flow control method:
S_RADIO_CHANNEL
BM210012WT09
ASCII E
FLOW_NONE
No flow control.
ASCII 0
FLOW_XONXOFF
XON/XOFF
ASCII 1
FLOW_RTSCTS
RTS/CTS
ASCII 2
Select the radio channel.
111
Wavenet Technology
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
Commands
Value
Parameters
Value
Sub-values and Descriptions
S_CUR_CNF
ASCII F
Save the modem configuration
R_DEF_CNF
ASCII G
Restore the modem configuration
R_STO_CNF
ASCII H
Read the modem configuration:
CNF_EVENT_
Event control flag
ASCII 0
FLAGS
settings
CNF_DELIVERY_
Outbound SDU del.
MODE
mode
CNF_RADIO_
Radio control
ASCII 2
S_RX_CONTROL
ASCII C
S_TX_CONTROL
ASCII B
ASCII 1
CONTROLsettings:
S_POWER_SAVE
ASCII I
Set the PowerSave mode.
S_ROAM_MODE
ASCII J
Set the roaming mode:
ROAM_
MANUAL
Set to manual.
ASCII 0
ROAM_AUTO
Set to automatic.
ASCII 1
S_BAUD
ASCII K
Set the baud rate for NCL communications:
BAUD_1200
1200 baud
ASCII 0
BAUD_2400
2400 baud
ASCII 1
BAUD_4800
4800 baud
ASCII 2
BAUD_9600
9600 baud
ASCII 3
BAUD_19K2
19200 baud
ASCII 4
Wavenet Technology
112
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix A - NCL Interface
Commands
Value
Parameters
Value
Sub-values and Descriptions
BAUD_38K4
38400 baud
ASCII 5
S_ANTENNA
RESET_RPM
VENDOR
Undefined
Select the antenna
ASCII
L..Z
Reserved.
ASCII 6
Reset RPM.
FLUSH_INBOUND
ASCII 1
Flush inbound message queue.
FLUSH_OUTBOUND
ASCII 2
Flush outbound message queue.
FLUSH_BOTH
ASCII 3
Flush inbound and outbound message queues.
RESET_WARM
ASCII 4
Warm start RPM.
RESET_TRANS
ASCII 5
Reset to Transparent Mode, if Transparent Mode is supported.
RESET_FULL
ASCII 6
Full reset of RPM.
RESET_NCL
ASCII 7
Reset NCL interpreter only.
RESET_OFF
ASCII 8
Power off the RPM.
RESET_DIAG
ASCII A
Vendor-specific: Cause DTE to enter diagnostic mode.
ASCII
A..Y, 7..9
Reserved.
ASCII Z
Vendor-specific command.
Event Report SDUs (EVENT, ASCII B)
Events
Value
Event Report
Enable
Bit
RCV_MSG_
ASCII A
RCV_MSG_DATA_
$10
Received message
data.
$08
Received message
notification. True only
if confirmed delivery
mode enabled.
$04
Physical-level
transmitter event.
DATA
RCV_MSG_
RX_EVENT
Value
BIT
ASCII B
NOTIFICATION
TX_EVENT
Parameters
RCV_MSG_
NOTIFY_BIT
ASCII C
ASCII D
TX_EVENT_BIT
RX_EVENT_BIT
Descriptions
TX_KEYED
ASCII 1
Transmitter keyed.
TX_DEKEYED
ASCII 2
Transmitter dekeyed.
$02
Physical-level receiver
event.
RX_IN_RANGE
ASCII 1
RF in range.
RX_OUT_OF_RANGE
ASCII 2
RF out of range.
RX_PWR_SAVE_
ASCII 3
Power saving enabled.
ASCII 4
Power saving disabled.
RX_ACTIVE
ASCII 5
Device in active state
on RF channel.
CHAN_DISALLOWED
ASCII 6
Device disallowed on
channel.
RX_REG_DENIED
ASCII 7
Flash LED for
ENABLED
RX_PWR_SAVE_
DISABLED
BM210012WT09
113
Wavenet Technology
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
registration denial.
HW_EVENT
RCV_ERR
ASCII E
HW_EVENT_BIT
$01
Hardware event.
HW_SELF_TEST
ASCII 1
Self-test failed.
HW_LOW_BATT
ASCII 2
Low battery.
HW_MEM_FULL
ASCII 3
Memory full.
HW_BATT_OK
ASCII 4
Battery level OK.
HW_MEM_OK
ASCII 5
Memory OK.
HW_OFF
ASCII 6
Device shutdown
imminent.
HW_BATT_WARN
ASCII 7
Battery at warning
level.
ASCII F
Unreceivable message
event.
RCV_TX_DISABLED
CONTROL
ASCII G
CONTROL_BIT
$20
ASCII 1
NCL connect between
RPM and DTE .
ASCII
H..Y, 1..9
Reserved.
ASCII Z
Vendor-specific event.
Responses
Value
SUCCESS
ASCII 1
XFAIL
ACK required, PDU
received. Cannot
ACK, transmitter
disabled. PDU
discarded.
Control event.
CONNECT
VENDOR
ASCII 1
Response Status SDUs (RESP, ASCII C)
Parameters
Value
Description/Error Code
IBQ_FLUSHED
ASCII a
Successful.
ASCII 2
Wavenet Technology
Error code. Pending SDUs in inbound queue flushed;
transmitter disabled. Used only if the RPM cannot support
message buffering while transmitter disabled.
Command execution error. Note the following error codes:
NO_RESPONSE
ASCII A
No response from network.
NO_ACK
ASCII B
Negative ACK received.
HOST_DOWN
ASCII C
Host access is down.
NOT_REGISTERED
ASCII D
RPM not registered.
LOW_BATTERY
ASCII E
Low battery—cannot transmit.
IBQ_FULL
ASCII F
RPM inbound queue is full.
TX_DISABLED
ASCII G
Radio transmitter is disabled.
BUSY
ASCII H
Resource is unavailable.
NOT_AVAILABLE
ASCII I
Unimplemented services.
HW_ERROR
ASCII J
Generic error.
INVALID_MODE
ASCII K
Invalid mode of operation.
NO_MESSAGES
ASCII L
No outbound messages available.
MSGS_PENDING
ASCII M
Cannot execute command due to pending inbound messages.
SW_ERROR
ASCII N
Software error.
OUT_OF_RANGE
ASCII O
RF not in range.
PACKET_ERROR
ASCII Z
SDU data corruption. True only if confirmed delivery mode
enabled.
ASCII
Reserved.
114
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix A - NCL Interface
P..Y, 1..9
SYNTAX
VENDOR
ASCII 3
ASCII Z
BM210012WT09
Command SDU syntax error. Note the following error codes:
INVALID
ASCII b
Invalid options.
TOO_LONG
ASCII c
Data is too long.
ASCII Z
Vendor-specific response.
115
Wavenet Technology
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
Wavenet specific NCL Extensions
The following table describes Wavenet specific extensions to the NCL
1.2 specification. All SDUs include three VENDOR control byte and
the vendor Id. (the ‘\’ character is used as an escape character for
hexadecimal bytes below):
Command Type
1. Get status commands
2. Generic “Set RPM
configuration” command.
3. Generic “Get RPM
configuration” command.
Command Description
Ncl String
Get radio status
ZF?r
Get modem battery status
ZF?v
Get modem “on” time
ZF?t
Get saved modem configuration settings
ZF?u
Get modem serial number:
ZFts
Set modem configuration parameters, eg:
ZF^[2 Byte ID][2 byte Length][Val]
* Power save mode.
ZF^p\00\00\01[new mode (byte)]
* Select new active profile.
ZF^f\00\00\01[new profile (byte)]
* NCL receive message notify timer.
ZF^n\00\00\02[2 bytes time (msec)]
Get modem configuration, eg:
ZF$[2 Byte ID]
* Power save mode.
ZF$p\00
* Get list of profiles, number of
ZF$f\00
profiles and currently selected active
profile.
ZF$n\00
* NCL receive message notify timer.
GET STATUS COMMANDS:
This command allows the DTE to request the current status and
configuration settings of certain aspects of the modem.
FORMAT:
WN_GET_STATUS Command Syntax (NCL string “ZF?…”):
CMND
Length
VENDOR
‘Z’
SDU Tag
‘F’
VEND_ WAVENET
‘?’
Status
Request
WN_GET_STATUS
WN_GET_STATUS Response Syntax:
RESP
Length
SDU Tag
VENDOR
‘F’
‘1’
Response
data
...........
Wavenet Technology
116
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix A - NCL Interface
OPERAND DESCRIPTIONS AND RESPONSES:
The various Vendor Status Requests that can be made, and the format
of their response information in the SUCCESS response SDU, are
described as follows. Please note that all multiple byte fields are stored
MSB first.
WN_GET_RADIO:
Get radio status information (NCL string “ZF?r”).
SUCCESS is followed by a block of status information as shown
below:
WN_GET_RADIO Response Format:
RSSI [2 bytes]
Reserved (ignore) [1 byte]
Reserved (ignore) [1 byte]
Reserved (ignore) [1 byte]
Reserved (ignore) [1 byte]
Reserved (ignore) [1 byte]
Reserved (ignore) [1 byte]
Reserved (ignore) [1 byte]
Reserved (ignore) [1 byte]
Current Frequency [4 bytes]
Current Channel [2 bytes]
Current Base Station ID [1 unsigned byte]
Where:
RSSI:
Two byte signed integer representing the
strength of the received signal from the
base station measured in dBm. A typical
value could be -90.
Current Frequency:
Four byte unsigned integer representing
the frequency of the inbound signal in Hz
for the channel the modem is currently
scanning or locked on to.
Current channel:
Unsigned word (2 bytes) representing
current channel.
Current Base Station ID:
Unsigned byte representing
current base station ID.
BM210012WT09
117
Wavenet Technology
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
WN_GET_BATT_VOLT:
(NCL string “ZF?v”).
Get modem battery status information
SUCCESS is followed by a block of status information in the format
shown below:
WN_GET_BATT_VOLT Response For mat:
Battery Voltage (2 bytes)
Battery Percentage
Where:
Battery Voltage:
Battery Percentage:
WN_GET_TIME:
“ZF?t”).
Two byte unsigned integer representing
the Voltage of the battery in mV.
Estimate of the remaining capacity of the
battery. This value ranges from 0 to 100
(unsigned byte).
Get modem time information (NCL string
SUCCESS is followed by a block of status information in the format
shown below:
WN_GET_TIME Response Format:
Elapsed Time [4 bytes]
Elapsed Time is a four byte unsigned integer, which represents the
number of milliseconds, which have passed since the modem was last,
turned on or reset. It is accurate to within 50ms of when the last byte
of the request message was received by the modem.
Wavenet Technology
118
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix A - NCL Interface
WN_GET_SETTINGS :
string “ZF?u”).
Get configuration information (NCL
SUCCESS is followed by a block of status information in the format
shown below:
WN_GET_SETTINGS Response Format:
LLI [4 bytes]
Serial Number [16 bytes]
.......
Reserved (ignore)
Home System Prefix
Home System ID
Home Area ID
5 Reserved bytes (ignore)
NCL Confirmation Mode
NCL Rx Control
NCL Tx Control
NCL Event Flags
Number of Group LLIs (n)
Group LLIs [4*n bytes]
Number of static channels (m)
Static channels [2*m bytes]
Reserved (ignore) [17 bytes]
.............
Where:
LLI:
Four byte unsigned integer (the standard
NCL command 4E also gives the LLI
number back).
Serial Number:
ASCII string containing the serial number
of the modem. Unused bytes are zeros.
The NCL command ZFts also gives the
serial number back.
NCL Confirmation Mode:
Default start-up state for the
confirmation mode of the NCL layer. It
is a zero for unconfirmed mode, or a one
for confirmed mode.
NCL Rx Control and NCL Tx Control:
BM210012WT09
119
Wavenet Technology
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
Indicate the start-up state for the NCL
settings for RX_STATUS and
TX_STATUS respectively. A zero
indicates disabled, a one indicates
enabled.
NCL Event Flags:
Byte which indicates the start-up state of
the NCL event reporting. A set bit
indicates the relevant event is enabled. A
cleared bit indicates the event is disabled.
The bits are as follow:
Bit 7 - Reserved (ignore)
Bit 6 - Rx_Error
Bit 5 - Control
Bit 4 - Rcv_Msg_Data
Bit 3 - Rcv_Msg_Notify
Bit 2 - Tx
Bit 1 - Rx
Bit 0 - Hwr
Number of Group LLIs:Number of Group LLI fields which
follow.
Group LLIs:
Each is a four byte unsigned integer. The
number of Group LLIs is given in the
previous field.
Number of Static Channels:
Number of channel fields
which follow.
Static Channels:
Each is a two byte unsigned integer. The
number of Static Channels is given in the
previous field.
WN_GET_SERIAL: Get modem serial number (NCL string “ZFts”).
SUCCESS is followed by a block of status information in the format
shown below:
WN_GET_SERIAL Response Format:
Modem serial number [10 bytes]
The modem serial number is unique to each modem and consists of
ASCII characters. The tenth character is typically a null termination
character.
Wavenet Technology
120
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix A - NCL Interface
Generic set RPM Configuration command
(WN_SET_PARAM):
This command allows the DTE to set the configuration settings of
certain aspects of the modem.
FORMAT:
WN_SET_PARAM Command Syntax (NCL string “ZF^…”):
CMND
Length
SDU Tag
VENDOR
‘Z’
‘F’
VEND_WAVENET
‘^’
Parameter number
Parameter length
WN_SET_PARAM
WN_SET_PARAM Response Syntax:
RESP
Length
SDU Tag
VENDOR
VEND_WAVENET
SUCCESS
OPERAND DESCRIPTIONS AND RESPONSES:
The various Vendor Parameter settings that can be made are described
as follows. Please note that all multiple byte fields are stored MSB
first. Numbers prefixed with “0x” are expressed as hexadecimal.
“Byte” (optionally followed by a sequence number) is used to indicate
a single byte.
Parameter Number
Parameter Length
Parameter Contents
A 16-bit field, which is unique to each
parameter, used to differentiate them.
A 16 bit field, which indicates the length
of the following parameter, in bytes.
The actual bytes set for the parameter.
The format is parameter specific.
The Parameter Name is a label used to refer to particular parameters,
and is used as a definition for the parameter number.
WN_SET_PARAM :
BM210012WT09
Set Modem Configuration (NCL string
“ZF^[2 byte parameter number][2 Byte
parameter length][parameter block..]”).
121
Wavenet Technology
Parameter
contents …
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
Parameter name :
Parameter number :
Parameter length :
Parameter contents :
WN_PWR_SAVE_MODE
0x7000 (“Byte1Byte2”) (ASCII 0x70 = ‘p’)
0x0001 (“Byte3Byte4”)
One unsigned byte (“Byte5”) indicating the
PowerSave mode as follow:
ASCII ‘0’ :
EXPRESS (Disabled
PowerSave or “full awake” mode).
ASCII ‘1’ :
MAXIMUM (4 windows).
ASCII ‘2’ :
AVERAGE (8 windows).
ASCII ‘3’ :
MINIMUM (16 windows).
Parameter name:
Parameter number :
Parameter length :
Parameter contents:
WN_PROFILE
0x6600 (“Byte1Byte2”) (ASCII 0x66 = ‘f’)
0x0001 (“Byte3Byte4”)
One unsigned byte with the number of the new
active profile.
Parameter name:
Parameter number :
Parameter length :
Parameter contents:
Wavenet Technology
WN_MSG_RX_NOTIF_TMR
0x6E00 (“Byte1Byte2”) (ASCII 0x6E = ‘n’)
0x0002 (“Byte3Byte4”)
One unsigned word (2 bytes) containing the
number of milliseconds between message
notifications to the Palm. The maximum setting is
65 seconds (65000 milliseconds).
122
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix A - NCL Interface
Generic get RPM Configuration command
(WN_GET_PARAM):
This command allows the DTE to get the configuration settings of
certain aspects of the modem. This section should be seen together
with the previous section (“Generic GET RPM Configuration
command”).
FORMAT:
WN_GET_PARAM Command Syntax (NCL string “ZF$…”):
CMND
Length
SDU Tag
VENDOR
‘Z’
‘F’
VEND_WAVENET
‘$’
Parameter number
WN_GET_PARAM
WN_GET_PARAM Response Syntax:
CMND
Length
SDU Tag
VENDOR
‘Z’
‘F’
VEND_WAVENET
‘$’
Parameter
Length
Parameter
Value
SUCESS
OPERAND DESCRIPTIONS AND RESPONSES:
The various Vendor Parameter values that can be requested are listed
in the previous section (“Generic set RPM Configuration command”).
The responses to these commands obey the WN_GET_PARM response
syntax as shown above. The one exception is the “Get Active Profile”
command, which returns more than just the “active profile”:
Parameter Number
A 16-bit field, which is unique to each
parameter, used to differentiate them.
Parameter Length
A 16 bit field, which indicates the length
of the following parameter, in bytes.
Parameter Value
The actual value of the parameter. The
format is parameter specific.
WN_ PROFILE Get list of profiles from modem (NCL string
“ZF$f\00” with “\00” representing one byte with value of zero).
BM210012WT09
123
Wavenet Technology
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
SUCCESS is followed by a block of information in the format shown
below:
WN_GET_PROFILE_LIST Response Format:
Number of profiles (n) [1 byte]
Active profile number [1 byte]
Profile Name 1 (up to 24 byte null terminated string)
Profile Name 2 (up to 24 byte null terminated string)
Profile Name n (null terminated string) [24 bytes]
Where:
Number of profiles:
Unsigned byte giving the current number of
profiles in configuration sector. The number
of profiles may change.
Active profile number: Unsigned byte giving the number (or index) of
the currently active profile.
Profile name:
Null terminated string of 24 bytes of length
(the string may be shorter than the 24 bytes as
long as it is followed immediately by the null
termination character). The 24 bytes do not
include the null termination character.
NCL Label Values
Please note the following additions/clarifications to the NCL Label
Values Table:
CMND
RESP
SUCCESS
VENDOR
VEND_MOTOROLA
VEND_WAVENET
ASCII 'A'
ASCII 'C'
ASCII '1'
ASCII 'Z'
ASCII '0'
ASCII 'F'
WN_GET_STATUS
ASCII '?'
WN_GET_RADIO
ASCII 'r '
WN_GET_BATT_VOLT ASCII 'v'
WN_GET_TIME
ASCII 't'
WN_GET_SETTINGS
ASCII 'u'
WN_GET_SERIAL
ASCII ‘s’
WN_SET_PARAM
ASCII ‘^’
WN_GET_PARAM
ASCII ‘$’
WN_PWR_SAVE_MODE
0x7000
WN_PROFILE
0x6600
WN_MSG_RX_NOTIF_TMR
0x6E00
WN_CMD
ASCII '*'
Wavenet Technology
124
(eg NCL command ZF?r)
(eg NCL command ZF?v)
(eg NCL command ZF?t)
(eg NCL command ZF?u)
(eg NCL command ZFts)
(eg NCL cmd ZF^\04\00\00\01\09)
(eg NCL commandS ZF$..)
(eg NCL cmd ZF$\70\00 = ZF$p\00)
(eg NCL cmd ZF$\66\00 = ZF$f\00)
(eg NCL cmd ZF$\6E\00 = ZF$n\00)
(eg NCL commands ZF*..)
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix A - NCL Interface
SAR Routine Function
An SAR limiting function is available for end user applications to limit
the average transmitted power by preventing new data transmissions
until the previous period’s average transmitted power is less than the
required SAR level.
During all transmission times a Retransmit Delay Accumulator is
incremented by a value of:
time Td = Duty Factor constant x actual time of block.
The Duty Factor is a ratio of non transmit to transmit time:
= (100 – DutyCycle%) / DutyCycle%
When the current data block and any retries have been sent, the next
transmission is inhibited, dependent on the required duty cycle and the
last transmission time. Data to be transmitted will be accumulated in a
data buffer.
When not transmitting, the Retransmit Delay Accumulator decrements
until the timer has expired.
The transmit may restart again, if there is data to send.
The default setting of the modem is 10% Duty Cycle unless otherwise
programmed.
BM210012WT09
125
Wavenet Technology
Appendix A - NCL Interface___________________________________ Boomer II User Manual & Integrator’s Guide
SAR Algorithm
Initialise duty cycle of non transmit time, back off timer and Tx on
timer.
Then execute the following state machine.
Are we
backing off
Tx?
Tx
Data
Reque
Idle
Yes
Has back
off timer
expired?
No
No
Buffer data
Yes
Tx data
reset Tx on
time
All data
sent
Tx on
time
Expired?
Finish Tx
current
packet
No
Yes
Recalculate / Set
back off timer
based on duty
cycle and last
transmission time
More data to send?
Wavenet Technology
126
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Appendix B - Sample Programs
Appendix B - Sample Programs
Sample programs are provided with the SDK. The purpose of these
sample programs is to show how a complete working client server
application can be built using the SDK NCL API with the client
program and the SDK SCR API with the server program.
These sample programs demonstrate how to write a simple application
that allows a wireless client to send data to a central server application
and receive responses back from the central server application. The
sample programs are not intended to be a functional application, but the
programs are intended to serve as a guide to writing applications and
can be used as a basis for developing more complex applications.
The information given in this document is intended to supplement the
source code for the applications by providing a high-level overview of
the source code.
In the following sections, the client and server applications are
described separately.
Client Application
The client application is called ModemInfo that uses the NCL API to
interface to the DataTAC ® network. The sample client program
retrieves the modems current status, and enables the user to send and
receive messages on the current channel the device is registered to.
The Modem setting Tab displays the modems current profile (i.e.
Channel list, RD –Lap version, etc), if the modem is on or off, the
modems power save mode, and if supported it’s vibrator mode.
BM210012WT09
127
Wavenet Technology
Appendix B - Sample Programs ________________________________ Boomer II User Manual & Integrator’s Guide
The status tab displays the modem’s current channel (if registered) and
it’s RSSI level. If the device is not registered it will be in scan mode,
scanning the channels from the channel list in its current profile.
The versions Tab displays the devices LLI, serial number, Hardware
Platform and software version.
Wavenet Technology
128
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Appendix B - Sample Programs
The messages Tab allows a user to send and receive messages from the
channel the device is currently registered on.
BM210012WT09
129
Wavenet Technology
Appendix B - Sample Programs ________________________________ Boomer II User Manual & Integrator’s Guide
Server Application
The server program is a Windows NT command line program that
connects to the DataTAC ® network switch and waits to receive data
from wireless client devices. Any data received from wireless clients is
echoed back to the same client on the same session. The server
program can handle simultaneous connections from multiple clients.
All activity indications (data transfer, connections and disconnections)
are logged to the screen. The server program operates without requiring
any user input.
Communications to the RNG are established either via a TCP/IP or an
X.25 connection, based on command line parameters.
The server program is implemented in a single module: server.c.
The server program uses SCR API to decode, encode, and interpret the
messages from the network. The server program contains code to
communicate with the network switch or RNG via either X.25 or
TCP/IP. The X.25 connection code is written using the EICON X.25
Developer's Tools for Win32. To run the application over an X.25
connection, you must have an X.25 connection to the switch, as well as
an EICON X.25 card plus EICON WAN Services drivers for this card.
To run the sample application via TCP1IP, you must have a TCP/IP
connection to the network switch. For help in getting this connection
set up, contact your DataTAC network operator.
The following pseudo code outlines the implementation of the main() function.
main ()
Initialize application variables
Set default values for user configurable parameters
Process command line and update parameters
Initialize X.25 API or Winsock DLL (connection to
RNG)
Initialize SCR API using scr_Init()
Establish a connection to the DataTAC network
while (!terminate){
Read data from the network
Handle Message zHandleMessage()
Wavenet Technology
Terminate connection to RNG
Clean up
130
BM210012WT09
Boomer II User Manual & Integrator’s Guide ________________________________ Appendix B - Sample Programs
Initialisation and Login
zEstablishConnection() establishes the connection to the RNG, using
either TCP/IP or X.25. When either a DataTAC(D 4000 or DataTAC
6000 network is used, this is all that is needed for the server to connect
to the DataTAC network.
When a DataTAC 5000 network is being used, the server application
must login to the RNG to identify itself. The login message is encoded
using scr_EncodeLogin() with the host ID and password as specified
by the command line parameters. The encoded login message is then
sent to the RNG.
Before the program exits, the connection to the RNG is closed. No
special SCR processing is needed here.
Data Transfer
zSendData() is a function that sends data to the RNG, using TCP/IP or
X.25 as appropriate. zReceiveData() is a similar function used to
receive data from the RNG. These two routines hide the low-level
details of the X.25 or TCP/IP connection to the DataTAC network.
When the server application receives a message from the DataTAC
network, using zReceiveData(), the message is passed to
zHandleMessage(). This routine uses scr_Decode() to decode the
incoming data, and then uses a switch statement to process the
message.
All data transfer within the server program is interpreted using the
DataTAC network independent data message types, such as
SCR_FROM_NET and SCR_TO_NET messages. This makes the code
applicable to all DataTAC network versions and reduces the problems
in porting an application from one DataTAC network type to another.
The server application also handles message types SCR_LR, SCR_CI,
and SCR_DI, which are specific to the DataTAC 5000 network. These
message types will not be received on DataTAC 4000 or DataTAC
6000 networks, and therefore will not affect the operation of the
program.
All messages received from the DataTAC network result in a message
being output to the screen to indicate that the message was received.
Some message types, such as SCR_ACK or SCR_CI, require no further
processing other than the output of a message. Other message types,
such as SCR_FROM_NET or SCR_LR, require a response message to
be sent to the DataTAC network. This is handled by formatting the
response within the switch statement, and this response is sent to the
DataTAC network at the end of the zHandleMessage() function.
BM210012WT09
131
Wavenet Technology
Appendix B - Sample Programs ________________________________ Boomer II User Manual & Integrator’s Guide
The following pseudo code gives an overview of the implementation of
zHandleMessage().
zHandleMessage(msg)
scr_Decode (msg);
/* decode the message */
if (error decoding) {
Report SCR decoding error
return
switch (Message Type){
/* examine the message type*/
case SCR_LR:
/* loopback request*/
/* this message is only applicable */
Prepare message "LC" /* to DataTAC 5000 networks*/
break;
case SCR_ACK:
/* Host msg delivery Confirmation*/
scr_NakReasonText();
scr_NakReasonText()
/* returns NULL if no error
occurred */
if (an error occurred){
Print reason text
else{
break;
Report successful delivery of message
case SCR_FROM_NET: /* Received inbound message*/
prepare message "TO_NET"
/*echo data back to the client*/
break;
case SCR_CI: /* Connect indication DataTAC 5000 only */
Report 'LLI x has connected'
break;
*/
case SCR_DI:
/* Disconnect indication DataTAC 5000 only
Report 'LLI x has disconnected'
break;
default: /* Unknown message type*/
Report 'Unhandled message type'
break;
scr_FreeDecoding ();
/*free dynamically allocated buffers in API*/
/*when it decoded the current message*/
Wavenet Technology
if ( a Response has to be sent ){
scr_Encode (); /*encode the response message*/
If (encoded successfully){
Send data to the network
else{
Report 'SCR encoding error'
132
BM210012WT09
Boomer II User Manual & Integrator’s Guide _________________________________Appendix C – Wavenet Loader
Appendix C - Wavenet Application Loader
The Application Loader software is used to upgrade the resident
software installed on your Wavenet OEM modem.
For optimum performance ensure that you are using the latest
application version.
This appendix, for your convenience, explains the procedure for
updating the Application Loader software and has a troubleshooting
section to assist with any problems.
Please refer to the Application Loader User Manual to ensure you have
the latest information.
Updating Application Loader Software on Your Modem
The Application Loader software may be used for all Wavenet
modems. The procedure is the same for all modems but some of the
screens may differ in appearance.
Follow the procedure below to check the software version currently
loaded on your modem and if necessary, to upload the modem
application.
1. Connect the Boomer II to the Test Jig as described on page 22.
2. Connect the Data Communications Modem connector to the
Boomer II Test Jig’s PC connector.
3. Connect the Data Communications PC connector to a COM
(serial) port on your computer. Note that the Data Comms PC
connector is a 9-pin plug. If your computer has a 25-pin serial
port you will need a 9-pin to 25-pin adapter.
4. Switch the modem on.
5. Switch your PC on.
6. From the PC, open the appropriate Application Loader
(Apploader) file for your modem.
The letter(s) preceding the three numerical characters at the end
of the Apploader file name denotes which modem the file is
appropriate for, i.e. M for the Dualwave M modem, V for the
Dualwave V modem and BM2 for the Boomer II OEM modem.
The three numerical characters at the end of the file name show
the version number of the application software, i.e.
408 is software version 4.08 and
233 is software version 2.33
If you select the incorrect Apploader file for your modem the
following typical message will be displayed.
BM210012WT09
133
Wavenet Technology
Appendix C – Wavenet Loader ________________________________ Boomer II User Manual & Integrator’s Guide
Note: The message shown above will appear if you are
attempting to upgrade using ApploaderM408.exe with a
Dualwave V modem.
7. The following screen is displayed.
Displays the current
version of Application
software on your
modem.
Select the
appropriate
com port on
your PC that
the modem
is connected
to.
Click the
Download
Application
button to
download
the latest
version.
Displays the new
application available.
Status bar.
8. Select the appropriate PC communications port to which the
modem is connected.
9. If the program recognises that the version of Application you
are attempting to install is later than the version currently
installed, the Download Application button will become
enabled. A message is displayed in the status bar advising that
the application software versions differ and requesting that you
press the Download Application button to update.
If the program recognises that the version of Application you
are attempting to install is earlier than the version currently
installed, the Download Application button will remain
disabled. A message is displayed in the status bar advising that
the application software version on the modem is up to date and
requesting that you exit the program.
10. Click
to update the Application software.
A progress bar is displayed informing you of the progress of the
update.
11. After the application has been updated, the modem is
automatically switched off. A message is displayed prompting
you to switch the modem on again.
Wavenet Technology
134
BM210012WT09
Boomer II User Manual & Integrator’s Guide _________________________________Appendix C – Wavenet Loader
12. Press the modem’s On/Off button and click
13. A message is then displayed in the status bar, informing you
that that the application software on the modem is up to date.
14. Click
to exit the program. This will automatically
switch your modem off.
Troubleshooting
You shouldn’t encounter any problems updating the Application
Loader software, however the following messages may appear.
This message will appear if the modem is disconnected during the
download. Ensure that all the connections between the PC and the
modem are secure, check the battery connections, ensure the modem is
switched on and follow the instructions in the message to try again.
This message will appear if the modem is disconnected whilst running
the Application Loader. Ensure that all the connections between the PC
and the modem are secure, check the battery connections and ensure
the modem is switched on.
This message will appear if the bootloader version on the modem is too
old to allow you to upgrade the application. Return the modem to your
supplier to be upgraded.
This message (or similar) will appear if you have attempted to upgrade
your modem with the incorrect Application Loader file.
BM210012WT09
135
Wavenet Technology
Appendix C – Wavenet Loader ________________________________ Boomer II User Manual & Integrator’s Guide
The ApploaderM408.exe is applicable to the Dualwave M modem and
ApploaderV233.exe is applicable to the Dualwave V modem.
The letter preceding the three numerical characters at the end of the
Apploader file name denotes which modem the file is appropriate for,
i.e. BM2 for the Dualwave Boomer II OEM modem, M for Dualwave
M modem and V for Dualwave V modem.
If the modem does not respond after an error message and you cannot
switch it off/on, reset the modem by inserting the end of a paper clip
into the reset hole at the back of the modem. Then switch the modem
on and continue the upload.
Wavenet Technology
136
BM210012WT09
Boomer II User Manual & Integrator’s Guide _________________________ Appendix D - Numeric Conversion Chart
Appendix D - Numeric Conversion Chart
Binary/Octal/Decimal/Hex/C/ASCII Conversion Table
Binary
00000000
00000001
00000010
00000011
00000100
00000101
00000110
00000111
00001000
00001001
00001010
00001011
00001100
00001101
00001110
00001111
00010000
00010001
00010010
00010011
00010100
00010101
00010110
00010111
00011000
00011001
00011010
00011011
00011100
00011101
00011110
00011111
00100000
00100001
00100010
00100011
00100100
00100101
00100110
00100111
00101000
00101001
00101010
00101011
00101100
00101101
00101110
00101111
00110000
00110001
00110010
00110011
00110100
00110101
00110110
00110111
00111000
00111001
00111010
00111011
00111100
00111101
00111110
00111111
Oct
000
001
002
003
004
005
006
007
010
011
012
013
014
015
016
017
020
021
022
023
024
025
026
027
030
031
032
033
034
035
036
037
040
041
042
043
044
045
046
047
050
051
052
053
054
055
056
057
060
061
062
063
064
065
066
067
070
071
072
073
074
075
076
077
Dec
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
BM210012WT09
Hex
00
01
02
03
04
05
06
07
08
09
0A
0B
0C
0D
0E
0F
10
11
12
13
14
15
16
17
18
19
1A
1B
1C
1D
1E
1F
20
21
22
23
24
25
26
27
28
29
2A
2B
2C
2D
2E
2F
30
31
32
33
34
35
36
37
38
39
3A
3B
3C
3D
3E
3F
CS
CS
CS
CS
CS
NX
NX
NX
NX
NX
NX
NX
NX
NX
NX
ASCII
NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR
SO
SI
DLE
DC1
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC
FS
GS
RS
US
SP
Definition
Null, or all zeros
Start of Heading
Start of Text
End of Text
End of Transmission
Enquiry
Acknowledge
Bell
Backspace
Horizontal Tab
Line Feed
Vertical Tab
Form Feed
Carriage Return
Shift Out
Shift In
Data Link Escape
Device Control 1 (XON)
Device Control 2
Device Control 3 (XOFF)
Device Control 4
Negative Acknowledge
Synchronous Idle
End Transmission Block
Cancel
End of Medium
Substitute
Escape
File Separator
Group Separator
Record Separator
Unit Separator
Space
137
Binary
01000000
01000001
01000010
01000011
01000100
01000101
01000110
01000111
01001000
01001001
01001010
01001011
01001100
01001101
01001110
01001111
01010000
01010001
01010010
01010011
01010100
01010101
01010110
01010111
01011000
01011001
01011010
01011011
01011100
01011101
01011110
01011111
01100000
01100001
01100010
01100011
01100100
01100101
01100110
01100111
01101000
01101001
01101010
01101011
01101100
01101101
01101110
01101111
01110000
01110001
01110010
01110011
01110100
01110101
01110110
01110111
01111000
01111001
01111010
01111011
01111100
01111101
01111110
01111111
Oct
100
101
102
103
104
105
106
107
110
111
112
113
114
115
116
117
120
121
122
123
124
125
126
127
130
131
132
133
134
135
136
137
140
141
142
143
144
145
146
147
150
151
152
153
154
155
156
157
160
161
162
163
164
165
166
167
170
171
172
173
174
175
176
177
Dec
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
Hex
40
41
42
43
44
45
46
47
48
49
4A
4B
4C
4D
4E
4F
50
51
52
53
54
55
56
57
58
59
5A
5B
5C
5D
5E
5F
60
61
62
63
64
65
66
67
68
69
6A
6B
6C
6D
6E
6F
70
71
72
73
74
75
76
77
78
79
7A
7B
7C
7D
7E
7F
UX
UX
UX
UX
UX
UX
LX
LX
LX
LX
LX
LX
ASCII
DEL
Wavenet Technology
Appendix D - Numeric Conversion Chart_________________________ Boomer II User Manual & Integrator’s Guide
Wavenet Technology
138
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix E - Specifications
Appendix G - Specifications
Physical Properties
Weight
< 50g
Size (L x W x H)
70mm x 52mm x 9mm
Communication Protocols
Modem to radio network protocol
RD-LAP 3.1, 3.2, 3.3
Modem to terminal (e.g. handheld) protocol
NCL 1.2
Environmental Conditions
Operating temperature
-30°C to +60°C
Storage temperature
-40°C to 70°C
Ports
Data Interface Port
TTL compatible serial port,
9600 baud
RF Connector
MMCX female, 50Ω.
Straight connection or right angle
LED Indicators
Power
Green
flashes when scanning
On, when locked
Off, when the Boomer II is off
Receive
Green
flashes when receiving
Transmit
Red
flashes when transmitting
Power
Voltage
3.8V (3.4 to 4.2V range)
Transmitter
< 1.7A
Receiver
< 85mA
Transmit Duration
32ms (minimum)
1s (maximum)
Off current consumption
< 100µA
Power Supply Ripple
< 15mV peak to peak
BM210012WT09
139
Wavenet Technology
Appendix E - Specifications ___________________________________ Boomer II User Manual & Integrator’s Guide
Synthesiser
Frequency range
806 – 825MHz (A),
890 – 902MHz (B)
Channel spacing
25kHz (A)
12.5kHz (B)
Frequency Error
±1.5ppm (<1300Hz) (A)
(-30º ~ +60ºC)
±0.8ppm (750Hz) (B)
Transmitter
Frequency range
806 – 825MHz (A),
896 – 901MHz (B)
Channel spacing
25kHz (A)
12.5kHz (B)
Data rate
MDC 4.8kbps (A)
RDLAP 9.6kbps (A)
RDLAP 19.2kbps (A)
RDLAP 9.6kbps (B)
Modulation
2-Level FSK MDC 4.8 2.5kHz deviation (A)
4-Level FSK RDLAP 9.6 3.9kHz deviation (A)
4-Level FSK RDLAP 19.2 5.6kHz deviation (A)
4-Level FSK RDLAP 9.6 2.5kHz deviation (B)
RF output power (at 50Ω antenna port)
1.8W nominal (2W maximum)
Duty Cycle (over 5 min)
20% maximum
Turn on time
< 5ms
Spurious emission
< - 30dBm
Adjacent channel power
< - 55dBc at 25kHz channels (A)
< - 45dBc at 12.5kHz channels (B)
Receiver
Frequency range
851 – 870MHz (A)
935 – 941MHz (B)
Channel spacing
25kHz (A)
12.5kHz (B)
Settling time
< 5ms
Sensitivity
< -111dBm at 5% PER RD-LAP 19.2
< -114dBm at 5% PER MDC
Spurious emission (receive mode)
< -57dBm
Channel selectivity
> 50dB (5kHz dev 1kHz tone) (A)
> 50dB (2.5kHz dev 1kHz tone) (B)
Spurious rejection
> 70dB
Image rejection
> 60dB
Wavenet Technology
140
BM210012WT09
Boomer II User Manual & Integrator’s Guide ___________________________________ Appendix E - Specifications
RSSI Reading
BM210012WT09
-120dBm ~ -45dBm
141
Wavenet Technology

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
Creator                         : Microsoft Word
Create Date                     : 2002:10:05 11:33:28
Title                           : BOOMER.PDF
Author                          : ArtB
Producer                        : Acrobat PDFWriter 4.0 for Windows
Modify Date                     : 2002:10:29 12:40:45-05:00
Page Count                      : 142