Wavenet Technology BM28001 Wireless OEM Modem Module User Manual BOOMER

Wavenet Technology Pty Ltd. Wireless OEM Modem Module BOOMER

ex9 manual

August 2002 APREL Project No.: WVTB-Boomer II Modem-3922-1    Consulting * Research * Training * Certification Testing  Since 1981FCC ID: PQS-BM28001Exhibit 9User’s Manual
Boomer IIOEM ModemUser ManualandIntegrator’s GuideAugust 2002
© Wavenet Technology Pty LtdACN 079 965 003Publication No. BM210012WT11 (11 September 2002)Published August 2002This publication is copyright and no part may be reproduced or copied without the prior consent of:Wavenet Technology Pty Ltd.140 Burswood RdBurswood, 6100Western AustraliaTelephone: +61 8 9262 0200Facsimile: +61 8 9355 5622E-mail: wavenet@wavenet.com.auWeb Site: www.wavenet.com.auThis manual is intended to be used for the operation of Wavenet Technology equipment. Performancefigures 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 orspecification to meet technological advancement.Microsoft, Windows and the Windows logo are registered trademarks or trademarks of MicrosoftCorporation in the United States and other countries. Other product and company names herein may bethe trademarks of their respective owners.Whilst every precaution has been taken in the preparation of this document, neither WavenetTechnology Pty Ltd nor any of its representatives shall have any liability to any person or entity withrespect to any liability, loss or damage caused or alleged to be caused directly or indirectly by theinformation contained in this book.Published by Wavenet Technology Pty Ltd.This device has not been authorized as required by the rules of the Federal CommunicationsCommission (FCC). This device is not, and may not be, offered for sale or lease, or sold or leasedwithin the USA, until authorization is obtained.This product contains a transmitter approved under the FCC rules.800MHz Modem FCC ID: PQS-BM28001900MHz Modem FCC ID: PQS-BM29001This 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 undesiredoperation.
Boomer II User Manual & Integrator’s Guide__________________________________________________ContentsBM210012WT09 3Wavenet TechnologyContentsIntroduction...................................................................................................................7Applications ..............................................................................................................8Compliance Statement...........................................................................................9Information for Your Safety................................................................................. 10Host Requirements............................................................................................... 11Installation.................................................................................................................. 13Mounting the Boomer II OEM Modem to Your Device................................... 14Connecting the Data Interface Port ................................................................... 15Pin Descriptions................................................................................................ 15Serial Communications Interface................................................................... 16Status Input / Output lines............................................................................... 17LED Interface .................................................................................................... 17Connecting & Positioning the Antenna ............................................................. 20Positioning ......................................................................................................... 20Supplying Power................................................................................................... 21Batteries............................................................................................................. 21Plug-in Supplies................................................................................................ 21Automotive Supplies ........................................................................................ 22Environmental Considerations ....................................................................... 22Test Jig....................................................................................................................... 23Features................................................................................................................. 23Exploring the Boomer II Test Jig........................................................................ 24Initial Calibration................................................................................................... 27Set Up..................................................................................................................... 28RSUSER................................................................................................................ 30Operations ......................................................................................................... 30Using RSUSER................................................................................................. 31Hot Key Descriptions........................................................................................ 31Reprogramming Modems................................................................................ 35Software Development Kit....................................................................................... 37Native Control Language Application Programmer’s Interface..................... 38Implementation.................................................................................................. 38Logical Architecture.......................................................................................... 39Application Interface......................................................................................... 41Standard Context Routing Application Programmer’s Interface................... 58Implementation.................................................................................................. 59SCR Structures................................................................................................. 59
Contents_________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 4BM210012WT09SCR Functions.................................................................................................. 64Application Development......................................................................................... 77Roaming Issues.................................................................................................... 78Roaming Requirements................................................................................... 78Inbound SDU Failures ..................................................................................... 80Outbound SDU Failure .................................................................................... 81Loss of Network Contact ................................................................................. 81Power Management............................................................................................. 82PowerSave Mode............................................................................................. 82Inactivity Time-Out............................................................................................ 82On/Off upon User Demand ............................................................................. 83Radio On/Off on Application Command........................................................ 83Battery Life Considerations............................................................................. 83PowerSave Protocol......................................................................................... 83Wireless Data Systems Considerations............................................................ 84Application Efficiency....................................................................................... 85Large Message Transfer ................................................................................. 85Message Transit Time..................................................................................... 85Message Routing and Migration............................................................................ 88Message Routing.............................................................................................. 88Network Link Layers......................................................................................... 89Standard Context Routing (SCR)....................................................................... 90SCR Message Types....................................................................................... 91Highlights of SCR Differences........................................................................ 91SCR Header Charts ............................................................................................. 95Host Request Message Header Fields......................................................... 96Host Confirmation Message Header Fields ................................................. 98Mobile Information Message Header Fields...............................................100DataTAC Messaging (DM)................................................................................102DM Message Types.......................................................................................102Highlights of DM Differences........................................................................102DM Header Charts..............................................................................................103Message Generate Header Fields...............................................................103Receive Header Fields ..................................................................................105Host Messaging (HM)........................................................................................107Other Development Issues ...............................................................................107Localizing an Application...............................................................................107Testing an Application...................................................................................108Appendix A - NCL Interface..................................................................................110Generic NCL (Native Mode)..............................................................................110
Boomer II User Manual & Integrator’s Guide__________________________________________________ContentsBM210012WT09 5Wavenet TechnologyqCommand SDUs (CMND, ASCII A).....................................................110qEvent Report SDUs (EVENT, ASCII B)..............................................113qResponse Status SDUs (RESP, ASCII C).........................................114Wavenet specific NCL Extensions...................................................................116qGET STATUS COMMANDS:................................................................116qGeneric set RPM Configuration command (WN_SET_PARAM):...121qGeneric get RPM Configuration command (WN_GET_PARAM):..123qNCL Label Values...................................................................................124SAR Routine Function.......................................................................................125SAR Algorithm.....................................................................................................126Appendix B - Sample Programs...........................................................................127Client Application................................................................................................127Server Application..............................................................................................130Initialisation and Login...................................................................................131Appendix C - Wavenet Application Loader.........................................................133Updating Application Loader Software on Your Modem..............................133Troubleshooting ..................................................................................................135Appendix D - Numeric Conversion Chart...........................................................137Appendix G - Specifications..................................................................................139
Contents_________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 6BM210012WT09
Boomer II User Manual & Integrator’s Guide________________________________________________IntroductionBM210012WT09 7Wavenet TechnologyIntroductionThe Boomer II OEM Modem is a radio packet modem, intended foruse on the Motorola DataTAC 4000 SFR and DataTAC 5000 MFRdata communication networks.It is primarily designed to be integrated into customer equipment as anOEM modem. There are two versions available, an 800MHz version (Aband) and a 900MHz version (B band).The modem interfaces to the equipment’s controller by using the datainterface port. The protocol supported over this link is Native ControlLanguage (NCL).Although the modem has embedded software, it has no built inapplication software. All application software must be separatelyinstalled and run from the device to which the modem is connected.A Software Development Kit (SDK) is available and described later inthis manual to assist this process.A picture of the Boomer II OEM Modem is shown below.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.LEDWindowData Interface PortRF Connector
Introduction_______________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 8BM210012WT09FeaturesThe Boomer II OEM modem is approximately the size of a credit cardand just 9mm thick. The modem is easily connected to many otherdevices and can be incorporated into a variety of package formats. Themodem has a TTL serial port.The Boomer II OEM Modem has the following features:q Serial communications interface port (TTL level)running an NCL protocolq Indicator lights shows the status of the network coverage andpower supplyq Four configurable digital input/output lines for externalcontrol/monitoringq Software configurable RF calibration adjustments to suitspecific networksq High sensitivity receptionq Small footprint and low profile designq Low-voltage and low standby current consumption for batterybased productsq Auto-wake up of host on incoming messagesq Roaming capabilities as used in DataTAC systemq Modem is always online using the DataTAC networkq Easy to install, service and updateApplicationsSuitable devices in which the Boomer II OEM Modem can be usedinclude the following applications:Meter ReadingThe modem can be used to read billing information from intelligentelectrical meters and basic disc meters. Data is transmitted wirelesslythrough a radio network to billing computers.EFTPOSThe modem can perform handshaking and complete verification of alldata transmitted through the wireless network.Vending MachinesVending machines can also utilise radio data technology. Manymachines already transmit usage and refill requirements to companyhead offices via standard telephone lines. Radio modems allow vendingmachines to be placed in areas with poor access to telecommunicationsinfrastructure, providing a cost-effective alternative to installing newtelephone lines. On refilling, only the required refills will be
Boomer II User Manual & Integrator’s Guide________________________________________________IntroductionBM210012WT09 9Wavenet Technologydespatched to the required sites maximising truck carrying capacity andconsequently efficiency.Fire Alarm DetectionConventional telephone wire connections are slow to dial out and canburn before the emergency call can be placed. Laws in many states andcountries require businesses to have an on-line dial out fire alarmsystem. The Boomer II OEM Modem offers a real solution to thisproblem.Parking, Buses and TicketingTicketing machines are being be converted to cashless operation. TheBoomer II OEM Modem is the best alternative to facilitate theintroduction of this cashless technology.Compliance StatementThis device has not been authorized as required by the rules of the FederalCommunications Commission (FCC). This device is not, and may not be, offeredfor 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 forintegration into a customer specific product. This combined productwill have it’s own antenna, RF cable and unique FCC ID. Thiscombined product will require its own testing by an FCC testing houseand submission to the FCC for approval.This equipment generates, uses and can radiate radio frequency energyand, if not installed and used in accordance with the manufacturer’sinstructions, may cause interference harmful to radio communications.There is no guarantee however, that interference will not occur in aparticular installation. If this equipment does cause harmfulinterference to radio or television reception, which can be determinedby turning the equipment off and on, the user is encouraged to try tocorrect the interference by one or more of the following measures:q Reorient or relocate the receiving antenna.q Increase the separation between the equipment and receiver.q Connect the equipment into an outlet on a circuit different fromthat to which the receiver is connected.q Consult your supplier or an experienced radio/TV technicianfor assistance.Warning:Changes or modifications to this unit not expresslyapproved by the party responsible for compliance could void the user’sauthority to operate this equipment.
Introduction_______________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 10 BM210012WT09Information for Your SafetyPlease read these safety instructions and the operation instructionsprovided in this manual before operating the Boomer II OEM Modem.Safe UseSwitch the modem off in areas where radio devices are forbidden, orwhen it may cause interference or danger. For example, fuel depots(fuel storage and distribution areas), chemical plants, locations inwhich hazardous or combustible gases may be present and whereblasting operations are in progress.Do not use the modem in an aircraft. Such use may affect aircraftinstrumentation, communication and performance and may be illegal.Be aware that the modem may interfere with the functionality ofinadequately protected medical devices, including pacemakers.Additionally, the effect of the radio signals from the modem on otherelectronic systems, including those in your car (such as electronic fuel-injection systems, electronic anti-skid braking systems, and electroniccruise-control systems) may affect the operation of these systems,which should be verified before use in the applicationsDo not place the modem on an unstable surface. It may fall and damagethe equipment.Never push objects of any kind into the modem through openings asthey 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 modemnear water (for example near a bathtub or sink, in a wet basement, neara swimming pool etc.). The modem should be situated away from heatsources.Disconnect the modem from the power source before cleaning. Do notuse liquid or aerosol cleaners. Use a damp cloth to clean the unit.Disconnect the modem from the power source and contact yoursupplier if:q Liquid has been spilled or objects have fallen onto the modem.q It has been exposed to rain or water.q It has been dropped or damaged in any way.q It does not operate normally by following the instructionscontained in this manual.q It exhibits a distinct change in performance.Failure to observe all these instructions will void the limited warranty.
Boomer II User Manual & Integrator’s Guide________________________________________________IntroductionBM210012WT09 11 Wavenet TechnologyHost RequirementsThe minimum system requirements of the host interface PC in order toutilise the Software Development Kit (SDK) are:q Intel compatible Pentium computer or higherq Windows 95 or laterq 16MB RAM (memory) minimum, 32MB recommendedq 1MB available hard disk spaceq 9-pin serial Port using a 16550 UARTq 3.5-inch Disk Driveq CD-ROM drive
Introduction_______________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 12 BM210012WT09
Boomer II User Manual & Integrator’s Guide_________________________________________________InstallationBM210012WT09 13 Wavenet TechnologyInstallationThis section will help you to successfully integrate the Boomer II OEMModem into your custom application. Before using your modem youmust:q Mount the Boomer II OEM Modem to your deviceq Connect the Data Interface Portq Connect and position the antennaq Supply powerA picture of the Boomer II OEM Modem is shown below.The modem has the following interfaces:Data Interface Port 30-way connectorLED Window PowerLED Green, flashes when scanningOn, when lockedOff, when the modem is offReceiveLED Green, flashes when receivingTransmitLED Red, flashes when transmittingRF Connector MMCX female socketLEDWindowData Interface PortRF Connector
Installation________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 14 BM210012WT09Mounting the Boomer II OEM Modem to Your DeviceThe Boomer II OEM Modem has an M2 Mounting Bolt hole in eachcorner, which should be used to bolt the modem onto an appropriatesurface. The mounting hole pattern is four holes in a 60mm X 46mm X42mm trapezoid, with each hole to suit an M2 (2.0mm) bolt. Refer tothe following diagram.  The mating surface should be flat and ensure a rigid mounting for themodem to minimise the transmission of vibration to the unit.There should be an adequate supply of airflow to ensure the modem’stemperature limits are not exceeded.Top ViewSide ViewMounting DetailsHole diameter:4 x 2.30mmFixing screw size:M270529
Boomer II User Manual & Integrator’s Guide_________________________________________________InstallationBM210012WT09 15 Wavenet TechnologyConnecting the Data Interface PortThere are two connectors to interface the Boomer II OEM Modem withyour device.q RF Connector (described in the next section), andq Data Interface PortThe data interface port is used to interface the modem to a serialcomputing device and a power supply. The power supply requirementsare described in the next section.A flat 30-way Flexible Printed Circuit (FPC) cable 0.3mm thick with1mm centreline spacing is used between the Boomer II OEM Modem’sdata interface port and your device.The asynchronous serial interface on the Boomer II OEM Modemoperates at 3V and can be controlled by a wide variety ofmicrocontrollers and microprocessors. The modem can be connecteddirectly to a microcontroller or through a universal asynchronousreceiver/transmitter (UART) to a microprocessor data bus.If the modem is to be connected directly to a PC or other RS232device, an interface must be provided to convert the signal voltage tothe higher values required by an RS232 device.Data Interface Pin DescriptionsPin Signal Description1DCD Data Carrier Detect2RXD Receive Data3TXD Transmit Data4DTR Data transmit ready5GND Ground6DSR Data Set Ready7RTS Request to Send8CTS Clear to Send9RI Ring Indicator10 HCRESET Modem Reset11 TEST PIN Not connected12 HOSTPWR_ON Modem Power on/off13 LED0_MSGWTG Message Waiting14 LED1_INRANGE In Range15 LED2_LOWBAT Low Battery16 SS0/RXD2 Status Signal 017 SS1/TXD2 Status Signal 118 SS2 Status Signal 2
Installation________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 16 BM210012WT0919 SS3 Status Signal 320 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 connected25 HOST GND Ground26 HOST GND Ground27 HOST GND Ground28 HOST GND Ground29 TEST-PIN Not connected30 TEST-PIN Not connectedSerial Communications InterfaceThe modem communicates with the controller using the Data InterfacePort connection interface. The protocol supported over this link is theNative Control Language (NCL). The data format for NCL is: 8 databits, 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 andclamp diode to the internal supply line for protection. The electricalinterface capability of these signals is as follows:Input Voltage Range 0 – 3.3V or 0 - 5VOutput Voltage Range 0 - 3.3VCurrent Source/Sink ± 3mA (maximum)The operation and active condition of these lines is summarized below.Serial Communications Interface DefinitionsJ1Pin # Signal Description Signal Active State1DCD Data Carrier Detect Output Low when modem in-range2RXD Receive Data Output Low when active3TXD Transmit Data Input Low when active4DTR Data transmit ready Input Low when ready6DSR Data set ready Output Low when ready7RTS Request to send Input High when host requires datathrottling8CTS Clear to send Output High when modem requiresdata throttling9RI Ring indicator Output Pulses Low when messagesare waiting
Boomer II User Manual & Integrator’s Guide_________________________________________________InstallationBM210012WT09 17 Wavenet TechnologyStatus Input / Output linesNote: Not currently supported but may be added in future releases.The status lines (SS0 to SS3) may be software configured for bi-directional operation. Each line has a 33Ù series resistor and clampdiode to the internal supply line for protection. The electrical interfacecapability and function of these signals are as follows:Input Voltage Range 0 – 3.3V or 0 - 5VOutput Voltage Level 0 - 3.3VCurrent Source/Sink ± 3mA (maximum)The operation and active condition of these lines is summarized below.Status Input/Output Interface DefinitionsJ1Pin # Signal Description Signal Active State16 SS0 Status Signal0Input/ Output User configurable (future option)17 SS1 Status Signal1Input/ Output User configurable (future option)18 SS2 Status Signal2Input/ Output User configurable (future option)19 SS3 Status Signal3Input/ Output User configurable (future option)LED InterfaceThe modem provides three on-board indicators (LEDs), for diagnosticmonitoring purposes as well as three modem controllable LED outputsthrough the Data Interface Connector.On-Board LED IndicatorsThe on-board LEDs are visible through a small window in the case ofthe modem. In order of sequence (from left to right when viewing themodem facing the data interface connector) the LEDs are as follows:PowerLED Green flashes when power normal and scanning forchannelOn when power normal and locked on channelOff when the modem is offTransmit Red flashes when data is transmitted
Installation________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 18 BM210012WT09LEDReceiveLED Green flashes when data is received
Boomer II User Manual & Integrator’s Guide_________________________________________________InstallationBM210012WT09 19 Wavenet TechnologyLED Output LinesIn addition to the on-board LEDs there are three signal lines (LowBattery, Message Waiting, In-range), which are controllable by themodem for connection to an external LED. Each line has a 33Ù seriesresistor and clamp diode to the internal supply line for protection. It isrecommended a series resistor be used with the external LED to limitcurrent accordingly. The electrical interface capability and function ofthese signals are as follows:Output Voltage Level 0 – 3.3VCurrent Source/Sink ± 3mA (maximum)The operation and active condition of these lines is summarized below.LED Interface DefinitionsJ1Pin # Signal Description Signal Active State13 LED0_MSGWTG Messagewaiting Output Low when message waiting14 LED1_INRANGE In range Output Low when modem in-range15 LED2_LOWBAT Low battery OutputLow when battery is less than3.5V,High when battery is greaterthan 3.6VLow BatteryThe Low Battery signal is held active low whenever the supply voltagedrops below an acceptable level (less than 3.5V) and deactivated whenthe voltage level becomes acceptable again (greater than 3.6V).  Thetransitions 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 avery fast transition between voltages, it may take up to 20 seconds forthe modem to confirm a change in battery status.Message WaitingThe Message waiting signal is held active low whenever there is atleast one message waiting in the inbound buffers to finish being sent tothe network, or at least one complete message in the outbound bufferswhich hasn’t been sent to the local device.In-RangeThe In Range signal is held active low whenever the modem is inrange. It tracks the function of the Data Carrier Detect (DCD) signal.
Installation________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 20 BM210012WT09Connecting & Positioning the AntennaThe Boomer II OEM Modem provides an MMCX RF connectorinterface 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 antennacable to interface between your device and the modem.The antenna cable should be a low loss, 50Ω impedance and have aMMCX plug that can mate with the modem’s MMCX socket(82MMCX-S50-0-2). It is recommended that a Huber+Suhnerconnector be used to connect to the modem as below;11 MMCX Straight Connector16 MMCX Right Angle ConnectorIf an extension cable is required to the antenna, it should be low loss, asshort as possible and an impedance of 50 ohms. Proper matchingconnectors should be used, as each connector introduces a return lossand reduces performance.The minimum requirements for the antenna used with the Boomer IIOEM Modem are:Impedance: 50ΩCentre Frequency: 833MHz ± 5MHzFrequencies 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 atthe antenna port. The antenna gain or loss will affect this value.PositioningPositioning the antenna will affect the gain provided by the antenna.The antenna should be orientated so that it provides verticalpolarisation as the DataTAC network is based on vertically polarisedradio-frequency transmission.The antenna should be located as far from the active electronics of thecomputing device as possible. Typically, a metal case of a computingdevice and its internal components may attenuate the signal in certaindirections. This is undesirable as the sensitivity and transmitperformance of the Boomer II would be reduced. However, careful useof metal used for the ground plane for an antenna can improve theantenna gain and the coverage area for the system.If your device is designed to sit on a surface, the antenna should bepositioned as far from the bottom of the device as possible. This is to
Boomer II User Manual & Integrator’s Guide_________________________________________________InstallationBM210012WT09 21 Wavenet Technologyreduce the radio frequency reflections if the device is placed on a metalsurface.If your device is hand held or is worn next to the body, the antennashould be positioned to radiate away from the body.Supplying PowerThe Boomer II OEM Modem must be provided with a clean powersource capable of delivering bursts of high current.The modem draws its power in bursts. The power required changesrapidly depending on whether the modem is transmitting, receiving oron standby.The power supply requirements are:Voltage: 3.8V (3.4 to 4.2V range)Transmitter: 1.7AReceiver: 85mATransmit Duration: 32ms (minimum) 1s (maximum)Off current consumption: < 100µAPower Supply Ripple: < 15mV peak to peakBatteriesThe Boomer II OEM Modem may be powered by batteries if used witha handheld device.Nickel cadmium (NiCad) batteries may be used for devices requiringwide 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 themanufacturer.The selected battery must be able to meet the Boomer II powerrequirements as mentioned previously.Plug-in SuppliesA 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 arrestorcircuits may be added to keep the inputs within the power requirementsmentioned previously. These should have a value of 20V and be placedon the supply side of the regulator circuit.
Installation________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 22 BM210012WT09Automotive SuppliesExtra protection is required from an automotive supply to protect theBoomer II OEM Modem from power fluctuations when used in anautomobile.The electrical transient conditions (e.g. battery jump start), maydamage the modem if not adequately clamped and filtered.Environmental ConsiderationsThe environmental requirements of the Boomer II OEM Modem are asfollows:Operating Temperature: -30° to +60°CStorage Temperature: -40° to +70°CYou should ensure these limits are not exceeded in the intendedapplication.
Boomer II User Manual & Integrator’s Guide___________________________________________________Test JigBM210012WT09 23 Wavenet TechnologyTest JigThe Boomer II Test Jig provides RS-232 serial interface ports betweena PC and the modem. It is designed to enable you to quickly interfacethe Boomer II to a standard PC (through a COM port) or a terminaldevice with an RS-232 serial port.The test jig acts as a temporary host for the modem and provides accesspoints to the radio’s communication port, allowing you to monitoractivity with a logic probe, multimeter or oscilloscope.Featuresq All Input/Output Lines configurable by jumpers and/oraccessible through parallel FPC connector.q On-board dual RS232 Serial Communication interface portswith DB9 connectorsq Through the SPY MODEM connector, you can monitor the datatransmitted from the modem (RX, DSR, and CTS).q Through the PORT 2/SPY PC connector, you can monitor thedata transmitted from the PC (TX, RTS and DTR), or talk to thesecond serial port of the modem. You can make this choice byputting all five jumper links on the right or left side of the RDWheader connector near the port.q Switches and LED indicators on SS0 - SS3 modem I/O lines.q On-board voltage regulator for Boomer II OEM supply rail.q On-board LEDs for three external signals:Low batteryMessage waitingIn rangeq On-board antenna matching network allowing conversion fromMMCX to SMA connectors.
Test Jig__________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 24 BM210012WT09Exploring the Boomer II Test JigThe test jig comprises the following components: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.DipSwitch # Signal On Off DefaultPosition1PA7 Always leave this switch in the OFF position OFF2OSC OFF Always leave this switch in the ON position ON3SS3 3V 10k Pul ldown to GND OFF4SS2 3V 10k Pull down to GND OFF5SS1 3V 10k Pull down to GND OFF6SS0 3V 10k Pull down to GND OFF7H-P-ON Turn the modem off Turn the modem on OFF8RESET Keep modem reset Keep modem in working status OFFOn/OffSwitchDC JackInput SupplyPort 2 / SPY PC InterfaceDB9 Connector8-wayDIP switchOn-boardLED indicatorsSMAAntennasocketSMAModemsocketHost PC InterfaceDB9 ConnectorSPY Modem InterfaceDB9 ConnectorAudio OutBNC ConnectorAudio InBNC Connector3.15A Fuse5X20mmLower 30-pin FPC ConnectorFor connection to modemADJ VCCVCCtest pinGroundtest pinBoomer II3 RDWHeaderconnector52-pin header connectorParallel 30-pin FPC ConnectorFor signal access
Boomer II User Manual & Integrator’s Guide___________________________________________________Test JigBM210012WT09 25 Wavenet TechnologyPort 2 / SPY PCConnector DB9 connector used for two purposes dependingupon the settings of the jumper switches locatedjust behind the connector on the PCB. If thejumpers are used to connect the centre column tothe right hand outer column (TX, RTS etc), thenthe port acts as a spy connection for the databetween the PC and the modem via the PCconnector.An analyser program such as “spy.exe” can beused to view the data.SPY ModemConnector DB9 connector, used to spy on the RS-232 datasent by the modem to the DTE (using DSR, RX,CTS and GND signals).An analyser program such as “spy.exe” can beused to view the data. A communication programsuch as “HyperTerminal” can be of limited use ifthe data spied upon contains a lot of alpha-numeric ASCII characters.Host PC ConnectorDB9 connector, used to connect serial port 1(of 2) of the modem to the DTE. The defaultvalues for this RS-232 connection is 9600bps, 8bits, no parity, 1 stop bit.This port can also be used to download newmodem software to the Boomer II.Parallel FPCConnector 30-way FPC (Flexible Printed Circuit) connectorused for signal access.Lower FPCConnector 30-way FPC (Flexible Printed Circuit) connectorused to connect the Boomer II to the test jig.Modem Connector Used to connect the Boomer II’s antenna socketto the antenna connector.Antenna Connector Used to connect the external antenna.LEDs There are eight LEDs used to indicate thefollowing:PowerLow BatteryIn RangeMessage WaitingSS0SS1SS2SS3
Test Jig__________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 26 BM210012WT09Audio Out Connector for monitoring an audio output. Usedto monitor baseband signal, BIT Error Rate(requires a PER test jig), receiver anddemodulation.Warning: Must use a high impedance monitor,100kÙ.Audio In Connector for monitoring an audio input. Used tomonitor modulation and transmission.Warning: Must use a high impedance monitor,100kÙ.3 RDW HeaderConnector Connectors used for jumpers (supplied).For Port 2 use, all the jumpers are positionedfrom the centre column to the left hand column.For Spy PC use, all the jumpers are positionedfrom the centre column to the right hand column.52-pin HeaderConnector Connector used for jumpers (supplied).All the jumpers are connected as default.1DCD2RX3TX4DTR5GND6DSR7RTS8CTS9RI10 RESET11 H-P-ON12 MSGWTG13 INRANGE14 LOWBAT15 SSO/RX216 SS1/TX217 SS2/CTS218 SS3/RTS219 3.8V20 3.8V21 3.8V22 3.8V23 GND24 GND25 GND26 GND3 RDWHeaderconnector3 RDWHeaderconnector
Boomer II User Manual & Integrator’s Guide___________________________________________________Test JigBM210012WT09 27 Wavenet TechnologyInitial CalibrationWithout connecting a Boomer II OEM Modem to the Test Jig, initiallycheck the calibration of the on-board voltage regulator. (This regulatorsupplies the RS232 converter and other on-board circuitry only. It doesnot supply power to the modem).1. Connect the centre pin of the DC jack to the +3.8V powersupply with 2A capability and the external pin to the ground.2. Adjust the trimpot marked ADJ VCC to make sure the voltageon 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.
Test Jig__________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 28 BM210012WT09Set UpWith the power off,1. Connect the Boomer II OEM modem to the lower FPCconnector on the test jig using a 30-way FPC cable.Use the following procedure to insert the cable into the FPCconnector.a. Lift up the lock lever of the FPC connector by flipping itup with the nail of your thumb or index finger.b. Ensure that the cable is inline with the connector andinsert the FPC cable into the connector with theconducting surface of the cable facing downwards.c. Press down the lock lever.Note: If the cable has been partially inserted, or out ofalignment, the lock lever will not engage. Should thisoccur, remove the cable (see below) and repeat stepsa-c.Lock LeverFPC conductor side
Boomer II User Manual & Integrator’s Guide___________________________________________________Test JigBM210012WT09 29 Wavenet TechnologyUse the following procedure to remove the cable from the FPCconnector.a. Lift up the lock lever of the FPC connector by flipping itup with the nail of your thumb or index finger.b. Remove the cable after the lock is released.2. Install an antenna to the modem. Use either the on-board SMAconnection and an adapter cable between the modem MMCXconnector and the test jig, or directly to the modem itself.3. Connect the PC to the DB9 connector marked “PC” using astandard 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 thePC as a host.The modem should be able to talk to the PC by using WavenetRSUSER software, or other NCL protocol software.Lock Lever
Test Jig__________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 30 BM210012WT09RSUSERThe Radio Service Utility software (RSUSER ) enables a user toexercise and configure Wavenet Modems. This software runs in a DOSwindow under Windows 95, 98, NT, or 2000.RSUSER interfaces with the Boomer II OEM Modem via a PC’scommunications port and the Test Jig’s PC port using an RS-232 cablewith DB9 connectors.RSUSER is issued with the following files:q RSUSER.EXE The executableq RSTEST.DEF Definition file for scriptsq RSUSER.INI Initialisation file. Created by RSUSER.EXEq RPM.LOG Log file. Created by RSUSER.EXE.Refer to Appendix E for the NCL command list.OperationsThe following screen is displayed on start up or whenever the Help HotKey <?> is pressed.                        *********RSUSER.M V2.xx HELP**********NCL COMMANDS (   - enable receive    _  - Get RPM status     @ - disable receive )   - enable transmit   &  - Get Next Msg       # - disable transmitSEND 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 lengthMISCELLANEOUS 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 timingCONFIG 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 areaType '?' to get back to this help screenRSUSER allows operators to exercise the modem via Native NCLCommands (and Vendor Specific Commands), hot keys or an inputline. Common user commands such as enabling the modems receiverand transmitter are included in the Hot Key list. Native NCLcommands can be issued from the F4 Hot key. A log file RPM.log isautomatically started for a new session of RSUSER. To save a session,exit RSUSER and rename the RPM.log file.
Boomer II User Manual & Integrator’s Guide___________________________________________________Test JigBM210012WT09 31 Wavenet TechnologyUsing RSUSER1. Supply power to the modem (e.g. via the test jig), switch it onand plug the modem into the communications port of thecomputer. (Refer to the modem’s user or test jig documentationfor cabling and connection instructions).2. Execute RSUSER.EXE3. Check that the communication port settings displayed arecorrect under the Miscellaneous Heading.4. If the communications port settings are incorrect, press <F5>,enter new settings, and exit from RSUSER by pressing<Escape> and return to step 2.5. Press the <_> key (the underline) to see if you receive aresponse from the modem. If not, there may be a problem withthe 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 <Escape>to exit.When first run, RSUSER.EXE creates a file RSUSER.INI in thecurrent directory, which saves the last used options (communicationsconfiguration) of RSUSER.EXE. These options will be used next timeRSUSER is executed.Hot Key Descriptions<Alt> +<3>Home Area ProgrammingPress <Alt> and <3> keys together to program the home area into themodem's non-volatile memory. You will be asked to enter the homearea (e.g. C20101), and then press <Enter>. You will see three“CMND…..ILLEGAL BYTE” lines, followed by three “SUCCESS”lines. This is normal. You must reset the modem (<F4> 66 <Enter>)before the changes will take effect. If you do not receive the“SUCCESS” responses, then reset the modem, reset RSUSER, and tryagain.<Alt> + <5>Static Channel ProgrammingThis allows you to change the static channel list in the modem's non-volatile memory. You will be prompted to enter the channel list.Type each channel individually, as per the example. You must type thefour hexadecimal digits of the channel (e.g. 25ED), followed by aspace, and then four hexadecimal digits for the channel attributes(0401). (Refer to the DataTac RD-LAP manual for channel designatorsand channel attribute descriptions.)
Test Jig__________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 32 BM210012WT09You should see two “CMND…..ILLEGAL BYTE” lines, followed bytwo “SUCCESS” lines. This is normal. You must reset the modem(<F4> 66 <Enter>) before the changes will take effect. If you do notreceive the “SUCCESS” responses, reset the modem, reset RSUSER,and try again.<Alt> + <6>Group LLI ProgrammingThis allows you to program up to 16 group LLIs into the non-volatilememory of the modem. You will be prompted for each LLIindividually. When finished, press <Enter> when prompted for thenext LLI.You should see two “CMND…..ILLEGAL BYTE” lines, followed bytwo “SUCCESS” lines. This is normal. You must reset the modem(<F4> 66 <Enter>) before the changes will take effect. If you do notreceive the “SUCCESS” responses, then reset the modem, resetRSUSER, and try again.<Alt> + <C>Read Config ParametersThis option reads the current configuration from the modem, andreports on it. The configuration includes the LLI, Serial #, home area,channels, group LLIs and some redundant data.<Alt> + <D>Get Radio StatusThis option sends a command to the modem requesting the currentradio status of the modem. The response contains information on thecurrent RSSI level, signal quality, current channel, base Id and severalother data.<Alt> + <W>Get Battery StatusThis option sends a command to the modem requesting the currentstatus of the battery power. The response contains the voltage level ofthe battery as an absolute voltage and as an estimated percentage ofcapacity.<F1>Set Source LLIThis option tells RSUSER which LLI should be listed as the sourceLLI on all packets which are sent by RSUSER using the "SENDMESSAGES" options. This setting will be saved in the RSUSER.INIinitialisation file. There is no need to reset the modem or RSUSERafter this option.
Boomer II User Manual & Integrator’s Guide___________________________________________________Test JigBM210012WT09 33 Wavenet Technology<F2>Set Destination LLISimilar to the above option, but sets the destination LLI for messagessent by the "SEND MESSAGES" options.<F6>Automatically Set SRC/Dest LLIs And Home AreaAutomatically queries the modem for its LLI and home area, and setsthe above two options with that LLI for loopback tests, and the nextoption with that home area address. This is easier than typing the LLIfor both source and destination options, and the destination address.<F3>SYS AddressThis option sets the default destination area for messages sent with the"Send Messages" option. This value is saved in the initialisation file.<F4>Compile NCL Message, or Send NCL ScriptThis option allows you to send any NCL command to the modem. Forexample, by pressing <F4>, typing "4z" and then pressing <Enter>will cause a command SDU to be sent to the modem asking for thestatic channel table. To enter a non-ASCII value, use the form \7Cwhere the backslash indicates that the next two characters are to betreated as a hexadecimal byte value (in this case 7C). This option isonly useful if you have a copy of the NCL specification to translatecommands into byte values.RSUSER is also able to send commands taken from the definition filerstest.def. This file contains a list of “scripts”, which containpredefined commands. The comments in the sample rstest.def filedescribe how to format the scripts in the file.To send a script, press <F4>, and then type the script name prefixed bythe "=" (equals) sign.For example, to run the "enablerx" script, press <F4>, and type"=enablerx", followed by <Enter>.<F5>Change Com Port ParametersThis option allows you to change the communications port settingswhich RSUSER uses to communicate with the modem. You will beasked for the port address and port IRQ. You will be given examplesfor the common four PC com ports.Note: You must exit from and restart RSUSER before these settings willtake effect.
Test Jig__________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 34 BM210012WT09<Alt> + <b>Change Baud RateThis option changes the baud rate the RSUSER program uses. You willbe asked for the baud rate you wish to change to. Valid baud rates are300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600 or 115200.The change will take effect immediately. The baud rate is not preservedon exit from RSUSER. It defaults back to 9600 on next invocation.<F11>Toggle Dumping Of NCL Data BytesIncoming NCL responses/events from the modem are translated anddisplayed on screen by default. The actual data bytes making up thepacket may be optionally displayed. Press <F11> to toggle this option.< _ >Get Status BlockThis option sends a status request command to the modem. It is a shortcut, rather than using the above F4 option and typing the ASCIIcharacters.< ( >Receiver On /  < @ >  Receiver OffThis option sends a command to the modem to switch the receiver onor off.< ) >Transmitter On /  < # >  Transmitter OffThis option sends a command to the modem to switch the transmitteron or off.Send Messages OptionsThese varying options send messages to the modem to be sent to thenetwork. They each have a source and destination LLI and destinationarea as set by F1, F2 and F3 respectively. The contents of the messagevary depending on the particular option. Some options are of fixedlength, and some ask you for the desired length. They are mainly self-explanatory.< > > Canned message.You will be asked for a file name. The contents of this file will be usedas the contents of the data portion of the SDU.< , >A random sequence of binary numbers will form the data portion of themessage. Its length is approximately 20 characters.
Boomer II User Manual & Integrator’s Guide___________________________________________________Test JigBM210012WT09 35 Wavenet Technology< < >A sequential sequence of ASCII characters will form the data portionof the message. You will be prompted for the length of the data portionof the message. A number from 1 to 2010 is allowed.Message Loopback OptionsThe F9 and F10 commands, together with the above “send message”commands can be used to set up some automatic message sending andloopback tests. When in loopback mode, RSUSER will cause amessage to be sent out for a definable amount of time (called “timebetween”) after every time one is received from the network (or weobtain a fail response to a send). The sent message will be the samemode and length as the last message sent by a “send messages”command above. We also send another packet if we don’t receive afailure response, or a network packet within a definable time (called“timeout”).<F9>Toggles automatic packet sending (loopback mode) on and off.<F10>Sets the timing parameters “time between” and “timeout”. These valueswill be reset back to defaults (0 and 60 seconds respectively) wheneverRSUSER is executed.For throughput tests where the network is bouncing back packets, thevalues 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 everyfive seconds (which allows time for retries etc.)Reprogramming ModemsA self-extracting loader program is supplied for every softwareupgrade. Refer to Appendix C - Wavenet Application Loader on page133.
Test Jig__________________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 36 BM210012WT09
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 37 Wavenet TechnologySoftware Development KitDataTAC networks allow wireless communication and are installed inmany different countries around the world. The Wavenet SoftwareDevelopment Kit (SDK), has been developed to facilitate developmentof applications for these networks by providing a simple programinterface for communicating with the network devices.The SDK supports the following network types:q DataTAC® 4000 networksq DataTAC® 5000 networksq DataTAC® 6000 networksThe SDK is made up of two major components:q Native Control Language Application Programmer's Interface(NCL API)q Standard Context Routing Application Programmer's Interface(SCR API)The NCL API is the wireless client component of the SDK. It providesroutines for sending and receiving data using an NCL compliant RadioPacket Modem (RPM).The SCR API is the server component of the SDK. It provides routinesfor encoding and decoding of SCR protocol messages and is used forcommunicating with the network switch or radio network gateway(RNG).
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 38 BM210012WT09Native Control Language Application Programmer’sInterfaceThe Native Control Language Application Programmer's Interface(NCL API) is the client component of the WAPI. The NCL APIprovides routines for sending and receiving data messages through theDataTAC wireless network, using a radio packet modem (RPM). It alsoallows the client application to control configuration parameters of theRPM and to retrieve status information from the RPM.ImplementationThe NCL API is implemented as a DLL library of written in C++  forwindows using Microsoft~ Visual C++ Version 6.0.The NCL API communicates with PC or Pocket PC applications basedon the following model. The NCL API is supplied as a Virtual DeviceDriver (VDD) for a PC (Win 98 or better) or a Pocket PC (Win CEVersion 3.0 or better). Multiple applications can access the RPM viaNCL encoded messages. MSMQ MSMQ IN N MSMQ IN 1 Layer 1 (Physical) Layer 2 (Data) )))Link)   Layer 3  (Network) Level 4 (Transport ) Layer 6 (Presentation) Serial Port  to modem Message Router & NCL Interpreter Serial Port Drivers       TX Queue Layer 5 (Session) Wavenet NCL API Model
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 39 Wavenet TechnologyLogical ArchitectureThe following table lists the required functionality for the API perlayer. The code forms a DLL, with only a subset of functions availablefor third party developers.LAYER NAME CONTENT FUNCTION7. APPLICATION Application specific data. Applications are to initialize a RX MSMQ (MicrosoftMessage Queuing system) queue and open a sessionwith the VDD by passing the RX queue handler.6. PRESENTATION LAYER Unused5. SESSION LAYER Unused4. TRANSPORT LAYER Unused3. NETWORK LAYER RouterMSMQ is run as a device driver on the Pocket PCand is run from power up (ie Non-suspend mode).The VDD will post events (RCV messages etc) to allapplication RX queues enabled for that event.Responses to application requests will be posted tothe calling application RX queue.The VDD process TX requests via a FIFO queue tothe NCL Interpreter. The Host base routing or Peer-to-Peer routing SDU formatting is contained in theNCL interpreter.2. DATA LINK LAYER NCL Interpreter &Extender port – SerialDriver.Application NCL API function requests are processedvia a FIFO queue. RPM responses or received data istagged and encoded for the router as required Alsothe UART DLL that handles the extender port UARTto modem communications resides in the link layermodules..1. PHYSICAL / BIT TRANSFERLAYER Extender Port to RPM. 9600, 8, 1, N on serial port and a wakeup line.Wavenet’s current NCL API protocol stack is implemented with thehierarchical structure. All DLLs including MSMQ files are included inthe install cabinet files for the VDD.RouterThe PC or PPC loads MSMQ as a device driver. Applications using themodem must open a session with VDD by calling ‘VDDOpen()’ whichwill create a private Receive MSMQ queue for the instance of theapplication (client). The name of this private queue will be sent to theserial port server (VDD) along with an open session request. The portserver will in turn create a private MSMQ queue to receive data fromthe client. All Modem Events and response messages to becommunicated between the VDD and the application will be via thereceive queues. Transmit function requests from the applications(clients) are queued by the VDD and are processed as a FIFO buffer bythe NCL interpreter. On Wakeup the VDD will be activated, if anyapplications receive queues are open the RX event will be posted tothose queues. If no receive queues are active, the VDD will buffer theRX events and start up the registered on_wakeup applications. After
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 40 BM210012WT09the applications have successfully opened a VDD session the VDD willpass the RX events to those applications.
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 41 Wavenet TechnologyNCL InterpreterThe NCL Interpreter strips NCL API function calls from applicationmessages, queue the calls and execute the calls on a FIFO basis.Received messages will be queued and matched against an appropriaterequest (if not an event), and passed to the router with thecorresponding tags.Link LayerThe RPM communicates with a PC via a standard communications portand a user supplied RS232 to CMOS level device. For the Pocket PC(PPC) the RPM communicates via the PPC extender port UART.  ThePPC performs an auto detect and wakeup when an attached modemreceives some data and the PPC is in suspend mode.Application Interfaceq Opening a SessionApplications are required to first open a session with the VDD bycalling the API function ‘VDDOpen()’. All other API functions willreturn an error unless an open session with the VDD was established.If successful this operation will result in the creation of two MSMQqueues for use by the client. One MSMQ will be used to send messagesfrom the VDD to the client and the other for messages from the clientto the VDD. Note that the client does not deal with MSMQ queuesdirectly because all operations are wrapped in API calls.Prototype:int VDDOpen(void)Description:Opens a session with the VDD.Input:Ø noneOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error type
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 42 BM210012WT09q Close SessionApplications can call this function to close its session with the VDD.An application should call this function before it terminates if a sessionwas earlier established with the VDD.  The reason for this is to ensurethat all created MSMQ queues for the client are deleted. This willprevent irrelevant/outdated messages from being posted to inactiveMSMQ queues.Prototype:int VDDClose(void);Description:Close a session with the VDD.Input:Ø NoneOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error typeq Send Data to a Radio HostApplications can call this function to send data to a radio host. TheHost ID will automatically be inserted into the data header of the SDUfor 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 willpost the response to the corresponding RX queue for that session. Theapplication is responsible for reading and processing the response onthe RX queue. By calling ‘nclReceiveData()’.Description:Send application data to the radio host identified by the host ID.
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 43 Wavenet TechnologyInput:Ø usSduTag Pointer to a word where the SDU tag can be storedØ szHostId Pointer to a buffer specifying the Host identity. The Host ID istypically 3 bytes in length for DataTac systems. The NCL API willtruncate Host ID’s longer than NCL_MAX_UH_LEN (63) bytes inlength.Ø 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 isbeing re-sent due to a failure of the previous send. Setting theflag to true prevents the possibility of receiving duplicate packetsat the server application. This flag cannot be used for resendingdata prior to the previous packet.Output:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error type× usSduTag Pointer to a word containing a reference of the correspondingSDU tag which was generated by the NCL API for this commandto the RPM.q Receive Data From RPMApplications can call this function to obtain data sent from the RPM.This applies to both event and response type data from the RPM. Notethis is the only way to obtain response data originating from the RPMas a result of issuing commands to it by means of other API functionsdescribed in this document. The return code of all API functionsissuing commands to the modem only provides feedback about theposted command. It does not guarantee delivery to the RPM. It is thusimperative for applications to use ‘nclReceiveData()’ to obtainfeedback directly from the RPM on commands sent to it. Responses tocommands are asynchronous meaning multiple commands can beissued to the RPM before the application needs to look at all theresponses.  This is the reason why every command provides theapplication with a copy of the unique SDU tag generated for thecommand. Every response message contains the same SDU tag of itsassociated command. The VDD uses the SDU tag to route responsemessages to the originating application (client). The‘nclReceiveData()’ function provides the SDU tag of the responsemessage. Applications can use these tags to tie up responses withpreviously sent commands.  One notable exception exist when the SDUtag is equal to 65535 (FFFF hexadecimal). Only event messagescontain an SDU tag equal to 65535. The received event/ responsemessages will be represented as an array of bytes which must be typedcast to a structure identified by returned structure ID.
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 44 BM210012WT09The RCV_MSG_NOTIFICATION event will be handled by the VDD,which will read the messages from the RPM and pass the messages toall clients with open sessions.Other Event types shall be posted to all clients with open sessionsregistered for that event. If no applications are registered for that eventthe 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 toreturn immediately or FFFFFFFF (hexadecimal) to hang onindefinitely for a message. The calling thread will be suspendeduntil 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 beplacedOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error type× ucStructId This value identifies the structure of the data in ucBuf. See thefollowing paragraphs for details.× usSduTag Pointer to a word containing a reference of the correspondingSDU tag which was generated by the NCL API for this commandto the RPM.× iBufLen Size (in bytes) of the data in ucBuf. Note: Buffer lengths of 0 ispossible – rely solely on the return value in such cases× ucBuf Pointer to buffer containing the received data
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 45 Wavenet Technology/*** Define types for retrieving data from the RPM ***/typedef unsigned char       BYTE;typedef unsigned short      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{
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 46 BM210012WT09NCLProdId prod_id;NCLVersion sw_version;NCLRpmId rpm_id;WORD reserved;WORD max_data_size;}NCLConfigBlock;/* Status block structure */typedef struct NCLStatusBlock{BYTE rx_status;BYTE tx_status;BYTE antenna;BYTE radio_in_range;BYTE flow_control;BYTE rcv_mode;BYTE event_states;WORD ob_msg_count;WORD ib_msg_count;WORD radio_channel;}NCLStatusBlock;/* Channel block structure */typedef struct NCLChanBlock{BYTE radio_in_range;WORD radio_channel;BYTE attribute;BYTE protocol;BYTE rssi;}NCLChanBlock;#define MAX_GROUP_LLIS  8#define LLI_BYTE_WIDTH   8#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 channel[NCL_NUM_CHANNELS];    BYTE            num;}NCLChannelTable;/* Vendor Spesific: Wavenet Get Settings*/typedef struct NCLWaveSettings {BYTE LLI[4];BYTE SerNum[16];} NCLWaveSettings;/* Vendor Spesific: Wavenet Get Radio Settings*/
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 47 Wavenet Technologytypedef struct NCLWaveRadio {BYTE rssi[2];BYTE reserved1;BYTE reserved2;BYTE reserved3;BYTE reserved4;BYTE reserved5;BYTE reserved6;BYTE reserved7;BYTE reserved8;BYTE frequency[4];BYTE channel[2];BYTE base_id;} NCLWaveRadio;/* 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 'A' Received message data               *//* NCL_MSG_NOTIFICATION    ‘B’ Received Message notification     *//* NCL_TX_EVENT   'C'  Transmitter event                          *//* NCL_RX_EVENT   'D'  Receiver event                              *//* NCL_HW_EVENT   'E'  Hardware event                            */
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 48 BM210012WT09/* NCL_RCV_ERR_EVENT   'F'  Unreceivable Message Event       *//* NCL_CONTROL_EVENT   'G'  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 TXdisabled *//* NCL_CONTROL_EVENT_C ‘1’ RPM / DTE connected                   */}NCLEventType;/* RCV_MSG_Data  */#define NCL_MAX_DATA_SIZE   2048#define NCL_MAX_UH_LEN      63 /* 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()
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 49 Wavenet Technologyq Get RPM Status InformationThe application can call this function to obtain status information aboutthe RPM. The following types of status information can be obtained:Status Request (non vendorspecific) Response Structure DescriptionNCL_R_CONFIG_BLOCK NCLConfigBlock Get RPM configuration blockNCL_R_STATUS_BLOCK NCLStatusBlock Get RPM status blockNCL_R_PROD_ID NCLProdId Get RPM product IDNCL_R_SW_VERSION NCLVersion Get software version numberNCL_R_RPM_ID NCLRpmId Get RPM addressNCL_R_RPM_VID NCLStatus.rpm_vid[2] Get RPM VID address (MDC)NCL_R_MAX_DATA_SIZE NCLStatus.max_data_size Get SDU data limitNCL_R_RCV_MODE NCLStatus.rcv_mode Get mode of notification toDTE for received SDUs.NCL_R_RX_STATUS NCLStatus.rx_status Get receiver enable statusNCL_R_TX_STATUS NCLStatus.tx_status Get transmitter enable statusNCL_R_ANTENNA NCLStatus.antenna Get antenna selection statusNCL_R_RADIO_IN_RANGE NCLStatus.radio_in_range Get radio in range statusNCL_R_OB_MSG_COUNT NCLStatus.ob_msg_count Get count of outboundmessages queuedNCL_R_IB_MSG_COUNT NCLStatus.ib_msg_count Get count of inboundNCL_R_FLOW_CONTROL NCLStatus.flow_control Get flow control statusNCL_R_EVENT_STATES NCLStatus.event_states Get current event reporting(enable/disable) stateNCL_R_RADIO_CHANNEL NCLStatus.radio_channel Get current radio channelNCL_R_CHAN_TABLE NCLChannelTable Read radio channel tableNCL_R_CHAN_BLOCK NCLChanBlock Read the channel blockNCL_R_BAT_LEVEL NCLStatus.bat_level Read the battery levelNCL_R_RPM_GID NCLGroupLlis Get RPM group IDsNCL_R_VENDOR_ID NCLStatus.vendor_id Get vendor identificationNCL_R_DCHAN_TABLE NCLChannelTable Read the D-channel tableNCL_R_RF_STATISTICS Specific to RF protocol used:RD-LAP [F] or MDC [G] Read the RF statisticsStatus Request (WavenetTechnology specific) Response Structure DescriptionWN_GET_STATUS_RADIO NCLWaveRadio Get RPM Radio StatusWN_GET_STATUS_BATTERY NCLWaveGen Get RPM Battery StatusWN_GET_STATUS_ONTIME NCLWaveGen Get RPM on-time statusWN_GET_STATUS_CONFIG NCLWaveGen Get RPM configuration status
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 50 BM210012WT09Prototype:int nclGetStatus (word *usSduTag, byte ucVendor, byte ucType, byteucRequest);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 orNCL_VEND_WAVENET = ’F’ for Wavenet Technology specificrequestsØ ucType The type of status information to retrieve from the RPM (Used byVendor specific requests). Set to zero for non-vendor requests orWN_GET_STATUS = ‘?’ for Wavenet Technology specificrequestsØ ucRequest The requested status information, as listed in one of theappropriate tables above, to retrieve from the RPM.Output:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error type× usSduTag Pointer to a word containing a reference of the correspondingSDU tag which was generated by the NCL API for this commandto the RPM.The response is posted to the corresponding RX queue associated withthe VDD session ID. If the session ID is not recognized all active RXqueues will be posted the response.q Set Configuration ITEMS Within the RPMBy default the modem will have the receiver and transmitter enabledand the RX notification event enabled. Modem Configuration items viaNCL are TBA and will be restricted to service personnel.
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 51 Wavenet Technologyq Reset RPMThe application can call this function to reset the RPM. There areseveral different levels of RPM reset commands that may be issued tothe RPM, as listed below:Reset Level DescriptionNCL_RESET_INBOUND Flush the Inbound queueNCL_RESET_OUTBOUND Flush the Outbound queueNCL_RESET_BOTH Flush both the Inbound and Outbound queuesNCL_RESET_WARM Warm start: flush queues, default Native settings, remain inNative modeNCL_RESET_TRANS Not SupportedNCL_RESET_FULL Full reset: Power-on resetNCL_RESET_NCL Reset NCL interpreterNCL_RESET_OFF Power off the RPMPrototype:int nclResetRPM (word *usSduTag, byte ucResetLevel);Description:Command the RPM to perform a specified level resetInput:Ø usSduTag Pointer to a word where the SDU tag can be storedØ ucResetLevel The level of the Reset as listed in the above tableOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error type× usSduTag Pointer to a word containing a reference of the correspondingSDU tag which was generated by the NCL API for this commandto the RPM.The response is posted to the corresponding RX queue associated withthe VDD session ID. If the session ID is not recognized all active RXqueues will be posted the response.
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 52 BM210012WT09q Register Event Callback FunctionSince the RX events will be posted to private Receive MSMQ queuesthe VDD is not required to support callback functions. Applicationscan call the API function ‘nclReceiveData()’, to wait on response andevent messages from the RPM on their on account. The API function‘nclReceiveData()’ will return within the time-out period specified, soapplications will not be hung-up indefinitely.q Enable / Disable EventsThe application can call this function to enable or disable individualevent types being reported by the RPM. By default, only the ReceiveMessage Data event is enabled (NCL_RCV_MSG_DATA). All otherevent types for an application are disabled unless they have beenspecifically enabled / disabled using this function. TheNCL_RCV_MSG_NOTIF event is handled by the VDD, which willpost the received messages to all active RX queues (that haveNCL_RCV_MSG_DATA enabled) using the NCLRXDataID structuretype.Prototype:int nclSetEvent (word *usSduTag, byte ucType, byte ucSetting);Description:Enable / Disable event reporting by the RPM for the specified eventtype.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 NCL_DISABLE     (Disable event reporting)NCL_ENABLE      (Enable event reporting)
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 53 Wavenet TechnologyOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error type× usSduTag Pointer to a word containing a reference of the correspondingSDU tag which was generated by the NCL API for this commandto the RPM.q Get Error DescriptionThe application can call this function to obtain a string representationfor a specified error code.Error Code Value DescriptionNCL_ERR_NONE 0No error has occurredNCL_ERR_SESSION_IS_CLOSED -1 NCL API: Session has not been openedNCL_ERR_SESSION_IS_OPEN -2 NCL API: Session is already openNCL_ERR_ENCODE -3 NCL API: NCL Frame encoding errorNCL_ERR_DECODE -4 NCL API: NCL Frame decoding errorNCL_ERR_PARAM -5 NCL API: Invalid parameter passedNCL_ERR_TIMEOUT -6 NCL API: Time-out elapsed waiting for responseNCL_ERR_MSMQ_OPEN -7 NCL API: An error occurred opening a MSMQNCL_ERR_MSMQ_CLOSE -8 NCL API: An error occurred closing a MSMQNCL_ERR_MSMQ_SEND -9 NCL API: An error occurred sending a MSMQNCL_ERR_MSMQ_RECEIVE -10 NCL API: An error occurred receiving a MSMQNCL_ERR_MSMQ_CREATE -11 NCL API: An error occurred creating a MSMQNCL_ERR_MSMQ_DELETE -12 NCL API: An error occurred deleting a MSMQNCL_ERR_MSMQ_NAME -13 NCL API: An error occurred searching for a MSMQNCL_ERR_MAX_CLIENTS -14 NCL API: Maximum number of supported clientsreachedNCL_ERR_INVALID 'b' NCL Syntax error: Invalid optionsNCL_ERR_TOO_LONG 'c' NCL Syntax error: Data too longNCL_ERR_ES_NAME 'd' NCL Syntax error: Invalid nameNCL_ERR_NO_RESPONSE 'A' Execution error: No response from networkNCL_ERR_NO_ACK 'B' Execution error: Negative ACK receivedNCL_ERR_HOST_DOWN 'C' Execution error: Host downNCL_ERR_NOT_REGISTERED 'D' Execution error: RPM not registeredNCL_ERR_LOW_BATTERY 'E' Execution error: Low battery - can't transmitNCL_ERR_IBQ_FULL 'F' Execution error: RPM inbound queue fullNCL_ERR_TX_DISABLED 'G' Execution error: Radio transmitter disabledNCL_ERR_BUSY 'H' Execution error: Resource unavailableNCL_ERR_NOT_AVAILABLE 'I' Execution error: Unimplemented servicesNCL_ERR_HW_ERROR 'J' Execution error: GenericNCL_ERR_INVALID_MODE 'K' Execution error: Invalid mode of operationNCL_ERR_NO_MESSAGES 'L' Execution error: No outbound messages available
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 54 BM210012WT09Error Code Value DescriptionNCL_ERR_MSGS_PENDING 'M' Execution error: Pending inbound messagesNCL_ERR_SW_ERROR 'N' Execution error: Software error has beenencounteredNCL_ERR_OUT_OF_RANGE 'O’ Execution error: Cannot send data when out ofrangeNCL_ERR_PACKET_ERROR 'Z' Execution error: SDU data corruption detectedError Not Listed All othervalues Unknown errorPrototype:char * nclGetErrorDescription (int iErrorCode);Description:Return a pointer to a character string describing the specified errorcode.Input:Ø iErrorCode Integer specifying the error code for which a string description isrequired.Output:× WCHAR * Pointer to a NULL terminated wide character (Unicode) stringdescribing the errorq Register Wakeup ApplicationBy default the VDD is executed on wakeup. In addition an applicationcan register to be executed on wakeup via the VDD. On wakeup theVDD will post any Received data to the current active queues. If thereare 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 theapplications RX queue. A timeout (Wktm = 10 seconds) will be used tohold the data for an application to initialize and commence a VDDsession before the data is discarded. The default application will be theModem Information application as supplied as a sample applicationwith the VDD.Prototype:int nclRegWakeupApp (WCHAR *usAppName, WORDusWakeupReason);
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 55 Wavenet TechnologyDescription:Register an application for wakeup when specified events occur.Input:Ø usAppName Pointer to a buffer specifying the full path name (Null terminated)of the application to execute on a wakeup.Ø usWakeupReason Logical OR the required reasons for wakeup from the followingvalues (exclude unwanted reasons):WAKE_MODEM_INSERTION – Wakeup application whenmodem is attachedWAKE_MESSAGE_RECEIVED – Wakeup application when amessage is received but no client applications are runningOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error typeq Deregister Wakeup ApplicationThe application can call this function to deregister an application thatwas 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   0 Operation failed. Value specifies the error type
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 56 BM210012WT09q Switch RPM On/OffThe 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 shouldpower upOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error typeq Send Generic NCL Command To RPMThe application can call this function to send application specificcommands 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 ofdata 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 besend to the RPMOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error type
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 57 Wavenet Technologyq Get Software VersionThe application can call this function obtain the software version of theserver 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 anyother value to request the server application versionOutput:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value specifies the error type× usVersion The upper 8 bits contain the major version and the lower 8 bitscontain the minor software version if the return value is zero
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 58 BM210012WT09Standard Context Routing Application Programmer’sInterfaceThe Standard Context Routing Application Programmer's Interface(SCR API) is the server component of the SDK. The SCR APIprovides routines for encoding and decoding SCR messages forcommunication with the DataTAC® network switch or radio networkgateway (RNG). Decoded SCR messages are stored in structuresdefined to represent SCR messages. Encoded messages are stored inmemory buffers.To encode a message, an application will first set up a structurerepresenting the desired SCR message. This structure is then passed tothe encoding function, scr_Encode(), which encodes the message into amemory buffer. The application can then send this encoded message tothe DataTAC network switch or RNG.To decode an SCR message received from the network switch, theapplication passes the received message buffer to the decode routine,scr_Decode(), which decodes the message into a structure containingthe data from the message.Routines are also provided to convert some of the message codes intoEnglish language descriptions of the code.The SCR API does not contain routines for reading the SCR messagesfrom the message switch interface or for sending encoded SCRmessages to the message switch. The connection to the message switchis 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.25and appropriate drivers for this card. To develop your own application,you will also need the developer's kit for your X.25 card. The sampleapplication has been written to use an EICON X.25 card. To run overan X.25 connection, the sample application requires an EICON X.25card, plus EICON WAN Services driver software. To modify andcompile the sample application, or to write your own application, youwill also need the EICON X.25 Development Tools for Win 32.Contact EICON Technology (www.eicon.com) for more informationon these products.When you are using a TCP/IP connection to the network switch orRNG, communication will be via some form of TCP/IP link. This maybe via an Ethernet card or through a modem connection running SLIPor PPP. The appropriate drivers will need to be configured for theEthernet card, and TCP/IP will need to be configured as a networkprotocol. Contact your hardware supplier for more details onconfiguring the TCPm connection. To communicate through theTCP/IP connection, the sample application uses the standard Winsockinterface provided with the Microsoft Windows operating system. Most
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 59 Wavenet TechnologyWindows compilers come with a standard developer's kit to interface tothe Winsock routines.ImplementationThe SCR API is implemented as a library of routines written in ANSIC and compiled for Windows NT using the Microsoft Visual C++compiler. All default project settings were used to compile the .lib file.SCR StructuresThe SCR API makes use of several important structures to store theSCR messages. The main structure is the SCRMsg structure. Thisstructure is a union of structures, each of which represents a singlemessage type in the SCR protocol.The SCRMsg structure is shown here. The msg_type field indicateswhich element of the union is valid. The appropriate value for themsg_type field is shown in the comments.
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 60 BM210012WT09/* The SCR Message data structure. */typedef struct SCRMsg {int msg_type;union{ SCRhrr r; /*msg_type: SCR_HR*/SCRar ar; /*msg_type: SCR_AR*/SCRlr lr; /*msg_type: SCR_LR*/SCRhc hc; /*msg_type: SCR_HC*/SCRac ac; /*msg_type: SCR_AC*/SCRlc lc; /*msg_type: SCR_LC*/SCRmi mi; /*msg_type: SCR_MI*/SCRci ci; /*msg_type: SCR_CI*/SCRdi di; /*msg_type: SCR_DI*/SCRrs rs; /*msg_type: SCR_RS*/SCRrr rr; /*msg_type: SCR_RR*/SCRib ib; /*msg_type: SCR_IB*/SCRob ob; /*msg_type: SCR_OB*/SCRab ab; /*msg_type: SCR_AB*/SCRreqstat reqstat;  /*msg_type:SCR_REQ_STAT*/SCRstatrsp statrsp; /*msg_type:SCR_STAT_RSP*/SCRtonet tonet; /*msg_type:SCR_TO_NET*/SCRfromnet fromnet; /*msg_type:SCR_FROM_NET*/SCRack ack; /*msg_type: SCR_ACK*/} u;} SCRMsg;Definitions for all SCR message structures can be found in the filescrapi.h. (SCR SDK)Network Independent MessagesThe SCR API provides several network independent message types.These message types represent basic functions within the SCR protocolthat are applicable to all DataTAC network types. The SCR APIencodes and decodes these message types as the appropriate messagefor the correct network type, as given in the call to the scr_Init()function.It is recommended that you use these network independent messagetypes wherever possible, to enhance the portability of the code betweendifferent DataTAC network versions.The three network independent message types are listed here:SCR_FROM_NET Generic From Network message. This is usedfor receiving data from a wireless device.Depending on the network setting, thiscorresponds to either a Basic Outbound (OB)message for DataTAC 4000 networks, or aMessage Indication (MI) for DataTAC 5000 or6000 networks.SCR_TO_NET Generic To Network message. This is used forsending data to a wireless device. Depending onthe network setting, this will be encoded aseither a Basic Inbound (IB) message for
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 61 Wavenet TechnologyDataTAC 4000 networks, or a Host Request(HR) message for DataTAC 5000 or 6000networks.SCR_ACK Generic Acknowledgment message. This isused to receive an acknowledgment for datasent to a wireless device.SCR_TO_NET messages may be passed to scr_Encode(), and they willbe encoded as the appropriate message type for the current network, asset in the call to scr_Init(). When a received packet is decoded usingscr_Decode(), it converts the received packet to an SCRMsg structure.The received messages are decoded for the current network type, andstored 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) messagestructure, SCRob. Because of this, the decoded message structure maybe interpreted as any of these structures. Similarly, the message typevalues SCR_FROM_NET, SCR_MI, and SCR_OB are defined to bethe 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_ABare all the same, and so may be interpreted interchangeably.Coupled with the interchangeable use of the message structuresSCRack, SCRhc, and SCRab is the function scr_NakReasonText(). Theresponse code field within the SCRack structure is network specific,but the scr_NakReasonText() function will interpret the response codeappropriately for the network type specified to scr_Init() and will returna text description of the error code, or a NULL pointer if the coderepresents successful delivery.Network Specific MessagesThe SCR API defines network specific message structures for each ofthe network specific SCR message types. These messages apply only toparticular versions of the DataTAC network.When a message is passed to the scr_Encode() routine, and thatmessage is not valid for the specified network type, it is encoded as thecorresponding message type for the network version specified toscr_Init() wherever possible. For example, if scr_Init() is used to set thenetwork type to DataTAC 5000, and an SCR_IB message is passed toscr_Encode(), it will be encoded as a Host Request (HR) message.Also, due to the same structure definitions and equivalent message typeconstants being used across all network types for the From Network(OB and MI) and Acknowledgment (AB and HC) messages, thedecoded structures may be interpreted as network specific structures,and this will still work on other network types. For example, ifscr_Init() is used to set the network type to DataTAC 5000, and aSCR_MI message is received from the network and decoded, this
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 62 BM210012WT09decoded structure may be interpreted as an SCR_OB structure with noside effects.DataTAC® 4000 Network MessagesThe following message types are specific to the DataTAC 4000network:SCR_OB Basic Outbound message for receiving data from awireless deviceSCR_IB Basic Inbound message for sending data to a wirelessdeviceSCR_AB Basic Acknowledgment of data sent to a wireless deviceDataTAC® 5000 Network MessagesThe following message types are extended SCR messages that are onlyused on the DataTAC 5000 network.SCR_LR Loopback RequestSCR_LC Loopback Confirmation (response to LR)SCR_CI Connect IndicationSCR_DI Disconnect IndicationSCR_AR Activity RequestSCR_AC Activity Confirmation (response to AR)SCR_RS Receiver SuspendSCR_RR Receiver ResumeDataTAC® 5000 and DataTAC® 6000 Network MessagesThe following message types are common to the DataTAC 5000 and6000 networks:SCR_MI Message Indication message for receiving data from awireless device.SCR_HR Host Request message for sending data to a wirelessdeviceSCR_HC Host Confirmation for acknowledgment of data sent to awireless device
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 63 Wavenet TechnologyData HeaderAll data messages (MI, HR, OB, IB, TO_NET, FROM_NET) contain adata header field. This field is used to route messages to the correctserver from client RPM devices. The data header is also sometimesreferred to as the session, and this is reflected in some of the NCL APIfunction parameters. For example, the szHostId parameter innclSendData and in  the data header for the nclReceiveData functions.This data header is represented in the SDK as a NULL terminatedstring.Refer to section Message Routing and Migration sub section SCRHeader charts on page x for the formatting of the header fields. Howthe use of the Data Header field varies between the network types isdescribed below.For DataTAC 4000 and 6000 networks, a host slot is used to route datafrom the wireless client to the correct server. RPM devices can beconfigured with up to five host slots, each routed to a different serverapplication. When the client application sends a message, the dataheader is used to specify which host slot to send on, and hence whichserver application the data will be sent to. The host slot is representedby a single ASCII digit from 1 to 5. This digit must be given as the lastcharacter of the data header. For example, a data header of I wouldroute the information on host slot 1, whereas a data header of TE3would route the data on host slot 3.For the DataTAC 5000 network, a 2-character session ID is used forrouting data from the wireless client to the correct server. RPM devicesmay be configured with many sessions, each routed to different serverapplications. The session ID is made up of any two characters from Ato Z or 0 to 9. When a client application sends data to a serverapplication, it must set the first two characters of the data header to thesession number. For example, a data header of Al routes data onsession 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 ofthis format, DataTAC 4000 and 6000 networks look only at the lastcharacter of the data header and route on host slot 1, while a DataTAC5000 network will look at the first two characters and route on sessionTE. 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 fromserver to client. This is not critical for routing messages back to theclient, but it is useful for the client to know on which session or hostslot (and therefore from which host) the data came.
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 64 BM210012WT09SCR Functionsq scr_Init()Prototype:int scr_Init(byte l_network_type);Description:This routine initialises the library and sets the network type being used-DataTAC® 4000, 5000, or 6000. The network type affects the encodingand decoding of messages by validating that the message type isapplicable to this network type. This network type is also used tocorrectly encode/decode the network independent message typesSCR_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 givento this function.Input:Ø l_network_type The network type to be used.Valid values are:SCR_DATATAC_4000 SCR_DATATAC_5000SCR_DATATAC_6000Output:× Return value = 0 Operation was successful× Return value   0 Operation failed. Value SCR_ERROR is returned to indicate anerrorExample#include <scrapi.h>main(){int lrc;lrc = scr_Init(SCR_DATATAC_4000);if (lrc == SCR_ERROR) {exit(0);}/* perform other SCR operations */ . . .}
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 65 Wavenet Technologyq scr_Encode()Prototype:int scr_Encode(byte *l_buf, SCRMsg *l_msg)DescriptionThis routine encodes a SCRMsg structure into an SCR encoded databuffer. 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 anOB message.Input:Ø *l_buf The buffer for the encoded message to be returned in. Whencalling this function, this parameter must point to an allocatedbuffer of at least SCR_MAX_LEN bytes. The encoded messageis 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 "SCRStructures.Output:× Return value = 0 Operation was successful and the encoded message is returnedin l_buf.× Return value   0 Operation failed. Value SCR_ERROR is returned to indicate anerror
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 66 BM210012WT09Example#include <scrapi.h>{SCRMsg lmsg; /* SCR message struct */byte ldata[200]; /* data to send to host */byte lbuffer[SCR_MAX_LEN]; /* buffer for encoded SCR msg*/int llen; /* length of encoded SCR msg*/.  .  .strcpy((char *)ldata, "Hello world")/* initialize message structure */lmsg.msg_type = SCR_TO_NET;  /* send data to clientdevice */lmsg.u.tonet.lli = 0xEE021234; /* set device LLI tosend to */lmsg.u.tonet.ack = SCR_TONET_ACK_NONE; /* noacknowledgment*/lmsg.u.tonet.data_header = “BB1”;/* Note: On a DataTAC 4000 or 6000 network,this message *//* will be routed on host slot 1. On aDataTAC 5000 *//* network, the message will be routed onsession 'BB. '*//* See Section “Data Header” for furtherdetails. */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 */.  .  .}.  .  .}
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 67 Wavenet Technologyq scr_Decode()Prototype:int scr_Decode(int l_len, byte *l_buf, SCRMsg *l_msg)DescriptionThis routine is used to decode an SCR message from a received bufferand produce an SCRMsg structure representing the received message.When this routine returns successfully, some memory may have beenallocated within the SCRMsg structure. scr_FreeDecoding() shouldalways be called after a successful scr_Decode() to free any memorythat may have been allocated. When scr_Decode() returnsSCR_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 thisfunction, this parameter must point to an allocated SCRMsgstructure. Refer to "SCR Structures".Output:× Return value = 0 Operation was successful but the buffer contains only a partialSCR message  in l_msg.× Return value  < 0 Operation failed. Value SCR_ERROR is returned to indicate anerror× Return value  > 0 Operation was successful .and the decoded message is returnedin l_msg.
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 68 BM210012WT09Example#include <scrapi.h>{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 */.  .  .scr_FreeDecoding(lmsg); /* free decoded message */}else if (lused == 0) {/* incomplete message received */}else {/* report an.error */.  .  .}}
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 69 Wavenet Technologyq scr_FreeDecoding()Prototype:void scr_FreeDecoding(SCRMsg *l_msg)DescriptionThis routine is used to free any memory allocated inside an SCRMsgstructure by a successful call to scr_Decode(). All calls to scr_Decode()that return a successfully decoded SCR message (the return value is apositive value) must be followed by a call to scr_FreeDecoding(), afterthe caller has fully processed the decoded message. Ifscr_FreeDecoding() is not called, memory leaks will occur.Note: The SCRMsg structure itself is not freed. Only allocated memorywithin this structure is freed. After scr_FreeDecoding() has beencalled, all pointers within the SCRMsg structure will be invalid.Input:Ø *l_msg The SCRMsg structure to have its internal memory allocationsfreed. Note that the SCRMsg structure itself is not freed.Output: NoneExampleRefer to the example for the function scr_Decode() on the previouspage.
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 70 BM210012WT09q scr_EncodeLogin()Prototype:int scr_EncodeLogin(byte *l_buf, char *l_hostid, char *l_passwd)DescriptionFor DataTAC® 5000 Networks Only. This function is used to encodethe RNG login packet that is sent to the RNG when the connection isfirst established.Input:Ø *l_buf The buffer for the encoded login packet to be returned in. Whencalling this function, this parameter must point to an allocatedbuffer of at least SCR_MAX_LEN bytes.Ø *l_hostid The DataTAC host login or host idØ *l_passwd The DataTAC host passwordOutput:× 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 anerror× Return value  > 0 Operation was successful and the number of bytes is returned inl_buf.Example#include <scrapi.h>{byte lbuffer[SCR_MAX_LEN]; /*buffer for SCR loginpacket*/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, . . .)}.  .  .}
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 71 Wavenet Technology
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 72 BM210012WT09q scr_Print()Prototype:void scr_Print(FILE *l_fp, SCRMsg *lmsg)DescriptionThis routine prints an ASCII representation of the SCR messagestructure to the given file. This is intended to be used for debugging ortracing purposes.Input:Ø *l_fp The file pointer to write the message details to.Ø *l_msg The message structure to print.Output: NoneExample#include <scrapi.h>{SCRMsg lmsg; /* SCR message struct */FILE *lfp; /* 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 followingmessage:\n");scr_Print(lfp, &lmsg);fclose(lfp);}/* process message */.  .  .}
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 73 Wavenet TechnologySample OutputThe 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 thescr_Print() function:FROM_NET MessageThe FROM_NET message is printed as an OB message for a DataTAC4000 network.*** OB message ***LLI 80051234Data header - BB1Data –0 54 68 69 73 20 69 73 20 73 6F 6D 65 20 64 61 74 This is some10 61 2E               data.For DataTAC 5000 and DataTAC 6000 networks, a FROM_NETmessage is printed as an MI message.*** MI message ***LLI 80051234Data header - BB1Data –0 54 68 69 73 20 69 73 20 73 6F 6D 65 20 64 61 74 This is some10 61 2E              data.TO_NET Message*** TO_NET message ***LLI 87654321Save bytes – AAAcknowledgment - SCR_TONET_ACK_REMOTEData header - BB1Data –0 54 68 69 73 20 69 73 20 73 6F 6D 65 20 64 61 74 This is some10 61 2E              data.ACK MessageFor DataTAC 5000 or DataTAC 6000 networks, an ACK message isprinted as an HC message.*** HC message ***LLI 87654321Save bytes – AAResponse - 78 - MT out of range or powered offFor the DataTAC 4000 network, an ACK message is printed as an ABmessage.*** AB message ***LLI 87654321Save bytes – AAResponse - 78 - No response from wireless device
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 74 BM210012WT09q scr_NakReasonText()Prototype:char *scr_NakReasonText(char *l_reason_code)DescriptionThis routine converts a response code from an HC or AB message intoa text string describing that code. The returned pointer is a pointer to astatic text string within the library. This string must not be overwrittenor freed. This string pointer will stay valid for the duration of theprogram's execution. The text strings correspond to the text given inthe DataTAC 5000 System Host Application Programmer's Manual.This routine can also be used to perform a network independent test forsuccessful delivery by checking for a NULL return value from thisfunction.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 buffercontaining an English description for the meaning of the givenresponse code.Example#include <scrapi.h>{SCRMsg lmsg; /* SCR message struct */char *lreason; /* 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)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);}}}
Boomer II User Manual & Integrator’s Guide____________________________________________SDK – SCR APIBM210012WT09 75 Wavenet Technologyq scr_ACReasonText()Prototype:char *scr_ACReasonText(char *I_reason_code)DescriptionFor 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 returnedpointer is a pointer to a static text string within the library. This stringmust not be overwritten or freed. This string pointer stays valid for theduration of the program's execution. The text strings correspond to thetext given in the DataTAC 5000 System Host ApplicationProgrammer's Manual.Input:Ø *l_reason code The reason code from the AC messageOutput:× Return !NULL Operation successful. Value a char pointer to a text string buffercontaining an English description for the meaning of the givenresponse code.× Return NULL Operation failed.Example#include <scrapi.h>{SCRMsg lmsg; /* SCR message struct */char *lreason; /* reason code string */.  .  ./* receive a message and decode it into lmsg */.  .  .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);}}}
SDK - SCR API____________________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 76 BM210012WT09q scr_DIReasonText()Prototype:char *scr_DIReasonText(char *l_reason_code)DescriptionFor DataTAC 5000 Dynamic Routed Sessions OnlyThis routine converts a reason code from a Disconnect Indication (DI)message into a text string describing that code. The returned pointer isa pointer to a static text string within the library. This string must notbe overwritten or freed. This string pointer stays valid for the durationof the program's execution. The text strings correspond to the textgiven in the DataTAC 5000 System Host Application Programmer'sManual.Input:Ø *l_reason code The reason code from the DI messageOutput:× Return !NULL Operation successful. Value a char pointer to a text string buffercontaining an English description for the meaning of the givenresponse code.× Return NULL Operation failed.Example#include <scrapi.h>{SCRMsg lmsg; /* SCR message struct*/char *lreason; /* reason code string*/.  .  ./* receive a message and decode it into lmsg */.  .  .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);}}}
Boomer II User Manual & Integrator’s Guide_____________________________________Application DevelopmentBM210012WT09 77 Wavenet TechnologyApplication DevelopmentThis section provides comments and advice that can help you developsuccessful wireless enabled applications for DataTAC systems.Application development for NCL-compliant wireless modem devicesis a two-part process.q The first step sets up the interface between the device host andthe wireless modem. In this step you must consider theinteractions with the wireless modem, as established by theNCL 1.2 reference specification and the vendor specificextensions.q The second step involves addressing message routinginformation to identify the message destination within theDataTAC network.Use the following suggestions to help you develop wireless enabledapplications.q Use PowerSave mode of operation to extend battery life andoperational time for the user. We recommend that theapplication does not modify this mode dynamically.q Use the Confirmed mode of operation to perform the followingfunctions:• Check the SDU checksum for validity.• Re-read SDUs received in error.• Read past the last message in Confirmed mode to makesure the device buffer is fully flushed. If the buffer is notflushed, the last message is held, consuming valuablebuffer space.q 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.q Use SDU tags to uniquely identify application-generated SDUs.q Anticipate the user will move between IN_RANGE andOUT_OF_RANGE conditions. This means you need toprovide:• A user indicator that identifies the current operatingstatus.• Recovery mechanisms when application transactionsfail as a result of losing network contact.
Application Development_____________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 78 BM210012WT09Roaming IssuesDuring development, consider how the coverage for your wirelessenabled application could be affected by a user moving in and out ofthe network coverage area. Coverage can be temporarily impacted bymoving from one side of a building to another. Coverage can be lost fora longer time by moving beyond the network coverage boundary.In application development, addressing this temporary or longer termgap in coverage, even in midst of an application transaction, isessential.You can address this consideration by providing a transport levelprotocol that can account for the following roaming related situationswhen used with a DataTAC wire-less modem:q Inbound SDU failureq Outbound SDU failureq Loss of network contactThese situations are discussed in detail from page 80.In this case, the transport level protocol must have components bothwithin the server and client application environment. This transportlevel protocol can be provided using existing third party software forDataTAC systems. Alternatively, you can develop a transport levelprotocol with your application in mind.Roaming RequirementsThe roaming algorithms for the wireless modem are described asfollows:Note: In each case, re-establishing network contact requires thewireless modem to scan all likely channels and to handshake with thenetwork.Send a quick (bounded) response to SDU transmit requestsWhen the wireless modem loses network contact, SDUs are returnedwith an out-of-range failure code. In this case, the wireless modem alsoindicates that it is out-of-range via an NCL event. When networkcontact is re-established, the wireless modem indicates an in-rangeevent. The client application then resubmits any SDU last rejected withan out-of-range response.Acquire the channel quicklyAll channels are scanned quickly, starting with the dynamic channellist that contains the last used channel and its neighbours. (This list isbroadcast periodically by the network.) If you cannot establish networkcontact using the dynamic channel list, the wireless modem scansquickly using the preprogrammed, network-specific static channel list.If network contact is not established using either list, this sequence is
Boomer II User Manual & Integrator’s Guide_____________________________________Application DevelopmentBM210012WT09 79 Wavenet Technologyrepeated after a delay interval. See “Conserve battery life when out ofrange” below.Conserve battery life when out-of-rangeWhen all channels (from both dynamic and static channel lists) arescanned and network contact is not established, the wireless modementers a scan-delay state. The scan-delay starts at one second anddoubles on each scan cycle failure, to a maximum of 255 secondsbetween scan cycles. This delay time is reset to one second byestablishing a network connection or by power-cycling the device.Re-establish network contact following inbound SDU failure (noresponse) and poor RF RSSI or signal qualityAny wireless modem experiencing a no-response inbound SDU failureand either with RSSI or quality below the exit threshold level must re-establish network contact. If unable to re-establish network contact, themodem indicates an out-of-range event. When network contact is re-established, the wireless modem indicates an in-range event. The clientapplication then resubmits any queued inbound SDU last rejected withan out-of-range response.Re-establish network contact due to loss of outbound channelThe wireless modem attempts to re-establishes network contactfollowing loss of the outbound channel. If unable to re-establishnetwork contact, the modem indicates an out-of-range event, andprocedures to re-establish network contact are initiated. When networkcontact is re-established, the wireless modem indicates an in-rangeevent. The client application then resubmits any queued inbound SDUlast rejected with an out-of-range response.Seek and locate the preferred alternate channel when the existingchannel degrades to a marginal levelWhen the existing RF channel degrades to a marginal (but still usable)level, the device periodically listens to neighbouring channels todetermine whether a preferred alternate channel exists. This actionoccurs when the device would otherwise be sleeping, to prevent impactto the device’s synchronized-receive capability with the network.To be considered, a preferred alternate channel must meet theminimum channel entry criteria and be 5 dBm better than the currentchannel. If located, a full channel acquisition is performed to verify allother aspects of the alternate channel before registering to the newchannel. This preferred-channel pre-roam algorithm is performed atintervals that increase exponentially and with identical reset conditions.See “Conserve battery life when out-of-range” above.
Application Development_____________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 80 BM210012WT09Inbound SDU FailuresPotential SDU inbound failure codes are described below. The listidentifies all likely SDU failure responses. The remaining SDUresponses that appear in the NCL 1.2 reference manual are notexpected to occur within the Motorola DataTAC wireless modem.Inbound SDU failure, no response from networkThe SDU was transmitted, but not acknowledged by the network. TheSDU may have been delivered; the acknowledgment might have beenthe element that could not be successfully returned to the originatingdevice.Inbound SDU failure, host downThis failure indicates that the internal network connection to theapplication host computer is currently unavailable. Because DataTACnetworks are designed with very high reliability, this failure isextremely rare.Inbound SDU failure, low batteryThe SDU could not be delivered due to a low battery condition. Whena low battery condition is reached, the radio network connection isdropped until the low battery condition is corrected. (This can beaddressed by replacing the battery or, if trickle charging is enabled,waiting for a sufficient charge level to be reached.)Inbound SDU failure, inbound queue fullThis response indicates that the maximum number (2) of SDUs arealready queued within the wireless modem. Another SDU can besubmitted when the NCL response for one of the pending SDUs hasbeen returned.Inbound SDU failure, out of rangeThe wireless modem has either lost network coverage or is in theprocess of re-establishing network contact. See “Loss of NetworkContact” on the following page.Inbound SDU failure, transmitter disabledThis SDU failure code indicates that the radio transmitter has beendisabled, under application control, within the wireless modem. Thetransmitter must be enabled prior to submitting an SDU.Note: This could be the result of transmitting a Receiver Disablecommand to the wireless modem. This command requires bothReceiver Enable and Transmitter Enable commands to recover two-way communications.
Boomer II User Manual & Integrator’s Guide_____________________________________Application DevelopmentBM210012WT09 81 Wavenet TechnologyOutbound SDU FailureDue to the unreliable delivery of RF data packets (and their responses),a client application must consider the possibility of an outbound SDUbeing delivered to the client, with the transport confirmation of thatdata packet being lost (RF acknowledgment and/or transport levelacknowledgment).Note: When developing a centralized server and distributed-mobileclient wireless enabled application, outbound SDU failure is primarilya server application issue.When this occurs, the client and server transport levels mustresynchronise to a common level before proceeding. Such anunderstanding might require retransmission of the transaction orretransmission of the transport confirmation.Loss of Network ContactWhen a wireless modem experiences a loss of network contact, queuedSDUs are returned with the out-of-range response code and with out-of-range event indicated. A loss of contact can occur for the followingreasons:Moving beyond network coverageWhen the device moves beyond the network boundary, network contactloss could occur for an extended period. Depending upon the user routeand network coverage area, this interval could extend from a fewminutes to several hours (or longer). Once network contact is re-established, the client and server application must be resynchronised ifapplications transactions have failed during the interval. After networkcontact has been announced, further delays should be minimised, as theuser becomes acquainted with the coverage area.Moving between areas of network coverageSmall movements within the area of network coverage can result in theloss and reacquisition of network contact, as a result of RF penetrationdifficulties with specific network topology and terrain. It might takefrom a few tenths of a second to a few minutes to recognize the channelhas degraded to an unusable level, to qualify a new channel, and to re-establish network contact. Again, the client and server application mustbe resynchronised if application transactions failed during this interval.Acquiring improved network coverageA channel might originally have been marginal, or might havedegraded from a good to a marginal level, or might be negativelyimpacted by the presence of other objects that influence its capabilityto send and receive data. Under such circumstances, the wirelessmodem seeks a preferred alternate channel, as previously described.
Application Development_____________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 82 BM210012WT09Usually this situation does not produce notification of network contactand reacquisition.Low batteryNetwork contact is dropped when a low battery condition is reached.This follows a battery alert notification (warning) that occurs while thebattery still has some remaining usable capacity. The time betweenthese events is much influenced by the battery technology and the levelof transmit activity within the wireless modem. A relatively inactivedevice provides more warning time than an active device. Also, analkaline battery provides more warning than a NiCad battery.Low buffersIf outbound SDUs remain unread within the wireless modem, itsoutbound buffers are eventually filled. When this occurs, networkcontact is dropped. Network contact is re-established when the internalbuffer pool within the wireless modem reaches a usable level, as aresult of SDU reads by the application. This situation never occurswhen the client application reads continuously to clear the wirelessmodem of received outbound SDUs.Receiver disabledThe client application can disable the wireless modem transceiver byusing the Receiver Disable NCL command. When this occurs, networkcontact is dropped and the radio is turned off. Network contact is re-established when the application issues the Receiver Enable, then theTransmitter Enable NCL commands.Power ManagementThe following modem power management options can be included inan application to maximize battery life:PowerSave ModeThe wireless modem defaults to PowerSave mode when turned on ifthe network supports the PowerSave protocol. If you are concernedabout latency of unsolicited outbound messages, you can turn off thePowerSave 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 thefollowing page.Dynamically modifying the PowerSave mode of the device is notrecommended.Inactivity Time-OutConfigure inactivity time-out to trigger if a message is not read fromthe modem within a certain number of minutes.
Boomer II User Manual & Integrator’s Guide_____________________________________Application DevelopmentBM210012WT09 83 Wavenet TechnologyTo 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 anS_INACTIVITY_TIMEOUT command to the wireless modem card.Set the timeout value to 255 (the default).On/Off upon User DemandTo extend battery life, design the application to switch the modem onand off as the usage need arises. This method is especially effective forsession-based, user-initiated applications.Radio On/Off on Application CommandThe radio is the primary power-consuming component in the wirelessmodem card. Use S_RX_CONTROL for very effective control ofsession-based, user-initiated applications.Battery Life ConsiderationsIn addition to specific power management options, some applicationdesign decisions greatly affect battery life, as follows:User traffic, amount and frequencyCommercially available compression techniques can significantlyreduce traffic volume, which improves device battery life and reducesnetwork usage costs. PowerSave mode batches outbound traffic at aperiodicity equal to the network-defined PowerSave protocol framesize.Data compressionImprove battery life by reducing and compressing the broad-castapplication data. Network usage costs can also be significantly reducedas a result.PowerSave ProtocolThe following points describe unique operational characteristics ofdevices that are compliant with the PowerSave protocol whenoperating on a network, as compared to those that are not. SpecificPowerSave timing parameters can vary by network, based on how thenetwork operator sets up PowerSave protocol parameters.Under PowerSave protocol, unsolicited outbound traffic to a non-awake device is delayed. The worst case delay until the first transmitopportunity is 128 seconds under DataTAC 4000 networks and 64seconds under DataTAC 5000 networks. The average delay until thenext delivery opportunity is one half of the worst case time, given thecurrent network and device configuration.In DataTAC 4000 systems, initial unsolicited outbound transmissionattempts are actually “ping” messages used to locate the device.
Application Development_____________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 84 BM210012WT09In DataTAC 5000 systems, unsolicited outbound messages (ormessages that have missed the previous transmit opportunity) aredelivered in the “root” (that is, home) window for the recipient device.Once the device is thus awakened, it remains awake for about nseconds after each message or ACK transmission from the device.During the wake time the network delivers messages to the device as itwould to a device that is non-compliant with the PowerSave protocol.(Default n = 20 seconds for DataTAC 4000 networks and 8 seconds forDataTAC 5000 networks.)Roaming and location update reporting to the network happens moreslowly because the PowerSave protocol device takes longer to respondto changes in the RF environment. The infrequent worst case latency inresponding to external stimuli (resulting in either a location update ornew channel scan) is about 9 minutes for DataTAC 4000 networks.DataTAC 5000 networks respond typically in 1.5 Power-Save protocolframe times, or about 96 seconds.Wireless Data Systems ConsiderationsThe wireless modems application developer must account for thelimitations of a wireless data system to minimize their impact on theuser.Limited Data Capacity on Radio Frequency ChannelsThe channels available to wireless modems are narrow-band and havelimited information carrying capacity (bandwidth) when compared totraditional wireline communications. Additional capacity can be gainedonly by increasing the number of channels, improving the hardwaretechnology, or by developing more efficient applications. As a result ofall these limitations, it is not surprising that wireless networks are oftenmore expensive to operate on a per-packet basis than wireline WideArea Networks (WAN). To address this concern, the NCL has beendesigned to provide the most efficient way of using the limited channelbandwidth.Message Delivery Cannot Be GuaranteedBecause a wireless device can roam without restriction, it can exit thenetwork RF coverage area, leaving it unable to receive or successfullytransmit messages. When a device is outside the coverage area, theapplications are informed of failed inbound delivery. The application isrequired to take appropriate recovery action.Variation in Message Transit Times Across the NetworkThe time interval messages transit the network is affected by the RFprotocol, the message load on the network, and the length of amessage. These variations might need to be taken into account by theapplication.The following sections address some of these shortcomings in moredetail.
Boomer II User Manual & Integrator’s Guide_____________________________________Application DevelopmentBM210012WT09 85 Wavenet TechnologyApplication EfficiencyOne goal of application development is to provide the requiredfunctionality with the least amount of messaging. The considerationhere is to minimize the number of interactions in an informationexchange. Doing so addresses the limited data capacity and increasedcosts of wireless messaging. In addition, the pricing structure ofnetwork operators encourages efficient application design. In fact,applications can be designed to use data compression or to applytechniques that send only data fields that change between transactions.Large Message TransferMessage size is a key factor affecting response times in wireless datasystems. To efficiently accommodate typical data applications, theDataTAC 5000 system is optimized for the transfer of short andmedium length messages. Typically, messages up to 512 bytes aretransferred across the network as a single data packet. Messages largerthan 512 bytes are segmented into 512-byte packets by the DataTACsystem before being transmitted over the air. The packets arereassembled before they are delivered to the application. For MDC4800 operation on DataTAC 4000 systems, the segmentation size is256 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), thatare reassembled in the wireless device. Each PDU requires a RadioData-Link Access Procedure (RD-LAP) acknowledgment from thedevice, which takes a few seconds to complete. The fewer PDUs in amessage, the shorter the delivery time. If messages larger than 2 kB areto be sent across the system, the host and wireless device applicationmust provide the segmentation and reconstruction functions.Message Transit TimeThe time required for an inbound or outbound message to travel acrossthe network is primarily a function of the queuing delays associatedwith each product in the network infrastructure and the message loadon the system. As system traffic builds, queuing delays increase foroutbound traffic, while the average time to access the inbound channelincreases, resulting in longer inbound message transit times.Additional delays are encountered when the wireless terminal is in theprocess of roaming from one cell on one radio channel to a cell onanother radio channel. If the cells are controlled by the same cellcontroller, the delay time is quite short. The delay time can increase ifthe cells are controlled by different cell controllers on differentsubnetworks.For a DataTAC 5000 fixed-end system operating at full rated capacity,the mean transit delay between a network host and a wireless device istypically no more than four seconds.
Application Development_____________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 86 BM210012WT09The application developer must develop operational scenarios toaccommodate the variable transit time in the application design.
Boomer II User Manual & Integrator’s Guide_____________________________________Application DevelopmentBM210012WT09 87 Wavenet Technology
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 88 BM210012WT09Message Routing and MigrationThis section offers developers advice on how to migrate theirapplications. That is, how to create new versions of their wirelessapplications for porting to other DataTAC®  systems. You can also usethis information to plan ahead for portability as you begin your initialapplication development effort.As the developer and user communities become more international inscope, successful applications will be distinguished by their portabilityacross existing DataTAC networks. This is true whether you aredesigning a new application or migrating an existing application toother networks.Message RoutingThree versions of DataTAC systems are in operation worldwide, asnoted by where they are currently implemented:q DataTAC 4000 systems (North America)q DataTAC 5000 systems (Asia-Pacific and Middle East)q DataTAC 6000 systems (Europe)The architectures of the three systems are basically alike. Althoughthey support different link layer protocols, the systems the systemsdiffer mainly in their message header syntax.The distinction between host communications and peer-to-peermessaging is also important. Separate DataTAC protocols support eachof these application models. The primary host communications mode isStandard Context Routing (SCR), also known as fleet mode. Anotherapplication mode is DataTAC Messaging (DM) , which handlesmessaging among terminals (subscriber units).SCR and DM are the common sets of rules that describe how to formatmessage headers on DataTAC systems. Although the header formatdiffers slightly among DataTAC 4000, 5000, and 6000 systems, thefunctional concepts of operation are the same. The exact SCR and DMsyntax for each system is available in their separate Host ApplicationProgrammer’s Manuals.Other connection options are available for DataTAC 5000 and 6000systems. Two of these are known as “personal shared” (Type I)connections and “personal dedicated” (Type II) connections. These arecovered 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 is8 bits.
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 89 Wavenet TechnologyNetwork Link LayersBefore a message can be routed, it must contain a header and bewrapped in a link layer protocol supported by the DataTAC network.Many link layer protocols are available, but not all are supported byeach DataTAC network.The X.25 protocol is common to all three systems and supports bothPVC and SVC host connection line types. X.25 is a popular choice fordevelopers looking for a worldwide connectivity solution.Other supported protocols include:q DataTAC 4000 system X.25, TCP/IP, LU6.2, leased line,   dial-up, RF-Loopbackq DataTAC 5000 system X.25, TCP/IP, SLIPq DataTAC 6000 system X.25
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 90 BM210012WT09Standard Context Routing (SCR)SCR allows the central host to communicate with hundreds, eventhousands of terminals across a single host connection. But the realadvantage of using SCR is economic: The host only pays for a singleconnection to the network, significantly reducing communications cost.When a terminal sends a message to the host, the message must containa header that includes the sending terminal ID. This enables the host toidentify which terminal sent the message and which terminal the host isto poll.DataTAC System ArchitecturesOther header fields provide the host with options for instructing thenetwork on handling undeliverable messages. For example, the hostcan ask the network to:q Provide a delivery status of messages.q Hold messages on the network for a later delivery.q Discard messages.This header and instruction information is the basis of the SCRprotocol.
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 91 Wavenet TechnologySCR Message TypesFleet mode of communications uses three types of messages:q Commands / Host Requests (host-to-network)EXAMPLE: Send Message #1 to LLI 87654321q Responses / Host Confirmations (network-to-host)EXAMPLE: Message #1 to LLI 87654321 was ACKedq Events / Mobile Information (terminal-to-network-to-host)EXAMPLE: Message received from LLI 12345678A fourth type of message, the status message, is allowed on DataTAC4000 and 5000 systems, but it is not supported on DataTAC 6000systems.Each message type must include a unique header; small differenceswithin each type of header exist among the systems. The chartsgraphically compare the headers for each system.Highlights of SCR DifferencesThe following topics explain:q Which system or systems implement a particular function.q What this function does and how it varies by system.q How to migrate an application from one system to another.NomenclatureWhen migrating applications, use the correct message type codes.Because DataTAC systems were originally designed for uniquemarkets during different development periods, each shows its separatelineage and is described using inconsistent terminology. For example,this occurs at the beginning of the SCR header, where the codedesignating the message type varies by system, as shown in thefollowing table.Message Type(direction) DataTAC 4000System DataTAC 5000System DataTAC 6000SystemCommand(host-to-network) IB(inbound basic) HR(host request) HR(host request)Response(network-to-host) AB(acknowledgment basic) HC(host confirmation) HC(host confirmation)Event(terminal-to-host) OB(outbound basic) MI(mobile information) MI(mobile information)Note: The DataTAC 4000 system designates the direction of thecommand message as inbound from the host to the network andoutbound from the network to the host (opposite from current industryterminology).
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 92 BM210012WT09ASCII versus Binary EncodingDataTAC 4000 system SCR fields are all ASCII encoded fields ofnumeric values or alphanumeric strings. DataTAC 5000 and 6000systems use a mixture of ASCII and binary encoded fields. All threesystems allow the user to send binary data, regardless of headerencoding.Support for TCP/IPDataTAC 5000 systems provide support for TCP/IP hosts, allowinginterconnection across local Ethernet LANs or even the Internet. SCRmessages are carried within a single TCP/IP data stream, which allowsSCR communications with multiple terminals.Although TCP/IP provides a reliable stream of contiguous data, theapplication must be able to determine the beginning and end of eachSCR message. The SCR header on DataTAC 5000 systems must startwith a 16 bit (2 byte) length field (bytes L1 and L2), which specifiesthe length of the frame.Length Prefix FieldDataTAC 5000 systems require all SCR messages to be prefixed by atwo-byte binary encoded length field (L1 and L2). This field providesTCP/IP based connections with data that determines the length of eachSCR message. The length count includes everything in the messagepacket, except for the length prefix.When converting an application to a DataTAC 5000 network, thelength field must be prefixed to all SCR messages.Host AuthenticationBefore SCR transactions can be performed on DataTAC 5000 andDataTAC 6000 systems using a host-initiated connection, the host firstsends a host authentication message to the radio network gateway(RNG). The authentication message must be the first message sent tothe RNG after establishing link layer communications. The RNG dropsthe connection when any of the following conditions occurs:q The host does not send the authentication message within oneminuteq The host ID and password do not match those in the RNGdatabaseq The host is not enabled in the RNG databaseq The host is already connected to the RNGOn DataTAC 5000 systems the authentication message consists of:q Host ID (up to 20 characters)q ASCII ‘;’ (semicolon) delimiterq Host password of 1 to 8 bytesq Carriage return
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 93 Wavenet TechnologyOn DataTAC 6000 systems the host ID field consists of:q 1 to 4 bytesq ASCII ‘;’ (semicolon) delimiterq Host password of 1 to 8 bytesq Carriage returnOn DataTAC 4000 systems the RNG (ARDIS switch) locates thecalling X.25 address to verify it is in the database. A valid callingaddress is then associated with only those terminals allocated to aparticular host.Extended SCRDataTAC 4000 and 5000 systems support additional message types andfunctions beyond the basic SCR functionality. Specifically, extendedSCR supports the following features:On DataTAC 4000 systems:q Sends binary headers and dataq Notifies the host of terminal network activityOn DataTAC 5000 systems:q Notifies the host of terminal network activityq Performs loopback diagnosticsq Notifies the host of terminal-to-host connection (session)activityFor a full description of these extensions, refer to the system hostapplication programmer’s manuals.On DataTAC 4000 and 5000 systems the extended functions enable thenetwork to notify the host that a terminal has registered with orderegistered from the network. This allows the host to avoid X.25communications costs associated with attempting to reach a shut downterminal.This extension set also involves the no-acknowledgment (No-ACK)option for host-to-terminal messages. When the No-ACK option isused on DataTAC 5000 systems, the host instructs the RNG to deliverthe 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 hostrequest for “No-ACK-needed.” When the RNG receives the ACK fromthe terminal, it is discarded or used to provide input to other system-specific features.Avoid using additional message types if you want the application to bewidely compatible. These extended features are not always available onall DataTAC 5000 systems. These features are enabled and controlledby the network operator on a per-host basis. Check with your targetnetwork operators before using SCR system extensions.
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 94 BM210012WT09Note: To run your application on DataTAC 4000 or 6000 systems, youmust isolate the use of extended SCR or avoid it entirely.Service Data Unit (SDU) SizeAn application SDU consists of the complete message; both user dataand data header. See “Data Header Routing” below. The maximum sizeof an application SDU is 2048 bytes for DataTAC 5000 and 6000systems, and 2550 bytes for DataTAC 4000 systems. For this reason,the recommended maximum SDU size for tri-system applications is2048 bytes.For transport over the air, the SDU is broken up into smaller physicaldata units (PDUs). Most network operators price their service at costper PDU or cost per SDU. Gather data from your various operators todevelop an application design that favorably considers these costfactors.Note: As a general rule, it is less expensive to send fewer large packetsthan many small packets. Try to take full advantage of the spaceavailable in each packet.Data Header RoutingTo use the data header to route messages properly, first consider thedata header as a pointer to a destination.In early DataTAC systems, all mobile units sent their messages to asingle host. Because all traffic went to one destination, there was noneed for a destination header. Later, a data header field was added toinform the network where (to which host or peer) to direct a particularSDU or message.Although the data header field can range in size from 0 to 64 bytes, byconvention most applications are written using a 3-byte data header.The DataTAC systems each use a different portion of these three bytesas a pointer to a destination. This pointer is called a session ID. Settingthese three bytes (the entire data header field) to a common valueguarantees compatibility across all three systems.Here are the specific differences in how the systems implement thesession ID:On DataTAC 5000 systems, the first two bytes of the data header pointto a destination. (These two bytes are referred to as the session ID.)On DataTAC 4000 and 6000 systems, the third byte only of the dataheader points to a destination. (The third byte is also known as a hostslot on these systems.)An example of these system differences is illustrated below. Each rowin the table depicts the application-visible portion of the DataTACsystem header for the identified system. In the data header column thesession ID bytes appear in bold typeface. The data header offset fieldidentifies the length in bytes of the data header field.
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 95 Wavenet TechnologyDataTACSystem TypeHeader Fields(Not Shown)Data HeaderOffset Data Header Data4000 . . . 03 TE1 Hello World5000 . . . 03 TE1 Hello World6000 . . . 03 TE1 Hello WorldIn this example the data header TE1 is a sample. The data header couldalso have been RO3, TX4, SS2, or many others, depending on theconfiguration of the network infrastructure.The DataTAC 4000 and 6000 systems use 1 as a pointer to adestination and TE to refer to an application ID. Conversely, theDataTAC 5000 system uses TE as a pointer to a destination and 1 as anextra byte, which only has meaning if active carrier management(ACM) is used. Since SCR does not require ACM, this byte can beignored.Note: Using this example, for cross compatible applications (to allDataTAC systems), set a data header offset of 03 (ASCII) and set thesame data header for all three systems (in this example, TE1).Consider another example. A DataTAC 4000 or 6000 system could usea data header of XY3 for one message and a data header of AB3 foranother message. According to current system implementations of thesession ID feature, both SDUs would go to the same destinationbecause the third byte (the pointer to the destination) is the same.SCR Header ChartsThe charts in this section allow you to compare SCR syntax across allthree DataTAC systems. Each chart displays a different set of headersbased on message type. For example, the length prefix on the DataTAC5000 system header and much of the DataTAC 4000 system header areshaded in gray to highlight fields where differences exist. Two of thedata headers are shaded for the same reason, indicating that they differin unique ways from the DataTAC 5000 system data header.Note: All header reserve fields must be set to ASCII 0 (0x30) or binaryNULL (0x00), depending on the format requirements of the field.The following table shows the terminology of other communicationsprotocols (for example, Native Control Language), and the SCR headertypes.Other Protocol Terminology SCR TerminologyCommand Message Host Request MessageResponse Message Host Confirmation MessageEvent Message Mobile Information Message.
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 96 BM210012WT09The list preceding each chart describes the contents of the headerfields.Host Request Message Header FieldsSave Bytes Supplied by the host and used by the network to tiethe confirmation to the original host request. Savebytes are ASCII for DataTAC 4000 systems. Savebytes can be ASCII or binary for DataTAC 5000 and6000 systems.LengthPrefix DataTAC 5000 systems require all SCR messages todesignate the length of the message. The length countdoes not include the length prefix itself, but doesinclude everything else in the message packet.Type Code Identifies the type of the SCR message: Use ‘I’ ‘B’ forDataTAC 4000 systems. Use ‘H’ ‘R’ for the othersystems.LLI Identifies the subscriber terminal to which themessage is being routed. On DataTAC 4000 systemsthe field (also known as Terminal ID) is ASCII-encoded in 8 bytes. On the other systems it is binaryencoded in 4 bytes (the first four bytes of this 8-bytefield are reserved).FormatIndicator Used in DataTAC 4000 systems only, to specify theformat of the data in the user data section of themessage. This field is reserved on the other systemsand handled by their Format field, as noted in this list.DeliveryOption DataTAC 4000 systems allow four priorities for amessage in the Priority field. Other systems allow twodelivery options: Send once and quit; send and queueuntil delivered or timed out.ConfirmationMode On DataTAC 4000 systems this is also known asAcknowledgment Indicator. On all systems this modeallows the host to specify the conditions under whicha confirmation message is returned for the messagebeing submitted.Format For DataTAC 5000 and 6000 systems only, a fixedvalue set to $15 (hex). This field replaces the FormatIndicator field on DataTAC 4000 systems.FormatDependent For DataTAC 5000 and 6000 systems only, a fixedvalue set to $C0 (hex).Data HeaderOffset On DataTAC 4000 systems this field is also calledData Header Size. On all systems it specifies thenumber bytes in the data header portion of themessage.
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 97 Wavenet TechnologyInformation For all systems, these fields include the data headerand user data for the application.
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 98 BM210012WT09Host Confirmation Message Header FieldsLength Prefix DataTAC 5000 systems require all SCRmessages to designate the length of themessage. The length count does not includethe length prefix itself, but does includeeverything 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 themessage is being routed. On DataTAC 4000systems the field (also known as Terminal ID)is ASCII-encoded in 8 bytes. On the othersystems it is binary encoded in 4 bytes (thefirst four bytes of this 8-byte field arereserved).Save Bytes Supplied by the host and used by the networkto tie the confirmation to the original hostrequest. Save bytes are ASCII for DataTAC4000 systems. Save bytes can be ASCII orbinary for DataTAC 5000 and 6000 systems.Response Code Known as Acknowledgment code inDataTAC 4000 systems, this field indicatesthe delivery status of the message to whichthe save bytes refer. On DataTAC 4000systems, acknowledgments are indicated bythe ASCII value ‘00’. On other systems,acknowledgments are indicted by any value(ASCII-encoded hex) from ‘08’ through ‘0F’.NAKs (negative acknowledgments) are in therange of ‘10’ to ‘A0’ for DataTAC 4000systems and in the range of 40-97, A0-A5 forDataTAC 5000 and 6000 systems. DataTAC5000 and 6000 systems also have theseadditional response codes:‘A1’ Terminal message in progress‘A2’ Terminal out of service‘A3’ Invalid session or host ID (invalidrouting info.)‘A4’ Maximum terminal queue exceeded.
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 99 Wavenet Technology
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 100 BM210012WT09Mobile Information Message Header FieldsLength Prefix DataTAC 5000 systems require all SCRmessages to designate the length of themessage. The length count does notinclude the length prefix itself, but doesinclude everything else in the messagepacket.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 fromwhich the message is being received. OnDataTAC 4000 systems the field (alsoknown as Terminal ID) is ASCII-encoded in 8 bytes. On the other systemsit is binary encoded in 4 bytes (the firstfour bytes of this 8-byte field arereserved).Format Indicator Used in DataTAC 4000 systems only, tospecify the format of the data in the userdata section of the message. This field isreserved on the other systems andhandled by their format field, as notedbelow in this list.Delivery Option DataTAC 4000 systems allow 4priorities for a message in the fieldformerly known as Priority. TheDelivery Option field is reserved on theother systems.Format For DataTAC 5000 and 6000 systemsonly, a fixed value set to $15 (hex). Thisfield replaces the format indicator fieldon DataTAC 4000 systems.Format Dependent For DataTAC 5000 and 6000 systemsonly, a fixed value set to $C0 (hex).Data Header Offset On DataTAC 4000 systems this field isalso called Data Header Size. On allsystems it specifies the number bytes inthe data header of the informationsection of the message.Information For all systems, these fields include the
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 101 Wavenet Technologydata header and user data for theapplication.
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 102 BM210012WT09DataTAC Messaging (DM)DM allows one terminal to communicate with up to ten other terminalsby routing a message through the DataTAC system network. As such,DM provides the protocol for basic E-mail functionality. Systemdifferences with regard to DM appear mainly as differences in DMsyntax.DM Message TypesPeer-to-peer communications uses two types of messages:q Generate (originator-to-network)q Receive (network-to-destination)Each message type must include its own type of header. Within eachsystem, each type of header has small differences in syntax. The chartsgraphically compare the headers across systems.Highlights of DM DifferencesEach of the three DataTAC systems varies slightly according to how itimplements DM. Use the table below to identify the system differencesby DM attribute.DM attribute DataTAC 4000Systems DataTAC5000Systems DataTAC6000SystemsAddress length 8 bytes 14 bytes 14 bytesError reporting Does not include anerror number prefixas part of the errortext.Includes an errornumber prefix as partof the error text.Does not include anerror number prefixas part of the errortext.Time-stamping Yes Yes NoMessage storage Configurable 10 messages 100 messagesDataTAC Messaging Implementation Differences
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 103 Wavenet TechnologyDM Header ChartsThe charts in this section allow you to compare DM syntax across allthree DataTAC systems. Each chart displays a different set of headersbased on message type. The charts show the differences you need to beaware of for your particular project. The list preceding each chartdescribes the contents of the header fields.Message Generate Header FieldsType All systems use ASCII ‘M’ ‘G’ to indicatea Message Generate type message header.Sender ID The ID of the originating wirelessterminal. On DataTAC 4000 systems thisfield is 8 bytes. On other systems it is 14bytes.First Destination ID The ID of the first of up to 10 destinationterminals.Last Destination ID The ID of the last of up to 10 optionaldestination terminals.Flag Bytes Settings for optional delivery services.Date & Time ofMessage Generation The current date and time the message isgenerated.Date & Time forDelayed Action The date and time when the message is tobe displayed at the destination. This optionis present is the corresponding flag bit isset.Originator’s ID The ID of the previous terminal of amessage being forwarded by a recipient.This option is present is the correspondingflag bit is set.Sequence Number A number used by a DM application tomatch replies and error messages with apreviously sent message.Message Text Can be binary or ASCII, depending onrequirements of the application.
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 104 BM210012WT09
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 105 Wavenet TechnologyReceive Header FieldsType All systems use ASCII ‘R’ ‘M’ to indicatea Receive Message type message header.Sender ID The ID of the originating wirelessterminal. On DataTAC 4000 systems thisfield is 8 bytes. On other systems it is 14bytes.First Destination ID The ID of the destination terminalFlag Bytes Settings for optional delivery services.Date & Time ofMessage Generation The current date and time the message isgenerated.Date & Time forDelayed Action The date and time when the message is tobe displayed at the destination. This optionis present is the corresponding flag bit isset.Originator’s ID The ID of the previous terminal of amessage being forwarded by a recipient.This option is present is the correspondingflag bit is set.Sequence Number A number used by a DM application tomatch replies and error messages with apreviously sent message.Message Text Can be binary or ASCII, depending onrequirements of the application.
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 106 BM210012WT09
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 107 Wavenet TechnologyHost Messaging (HM)Host Messaging (HM) is achieved by placing a DM header inside anSCR header. In addition, the first two bytes (either MG or RM) must bereplaced with HM to signify the message was received from a host,rather than a peer. HM used in conjunction with DM allows theterminal to use the same routing protocol regardless of its destination.(Despite its simplicity, use of HM is not recommended because it isinefficient). For further details, refer to the InfoTAC ApplicationDeveloper’s Guide, Motorola reference: 6804018C65.Other Development IssuesLocalizing and testing your applications are not issues relatedspecifically to application migration. The following comments areprovided as a helpful reminder only.Localizing an ApplicationWhether you are preparing your application for sale internationally ordeveloping it internally for an international company, considerdesigning in international characteristics from the beginning, such ascharacter encoding, language enabling, and special text formatting.While such an effort can take longer up front, any eventual re-portingof the application will be much easier to manage.Character EncodingIf your application supports languages that use Latin-based characters(for example, English, Spanish, and German), design your applicationfor compatibility with 7-bit ASCII/ISO 646 and Latin 1/ISO 8859-1, 8-bit display fonts.If your application support dialects of non-Latin languages, such asChinese, Japanese, Korean, or Thai, design your application to workwith Unicode or another 16-bit character encoding standard. Inaddition, provide your application with flexible keyboard mapping.Language EnablingIsolate all translatable strings, icons, and menus from your program.Then the greater part of a localization effort will be translation, ratherthan re-engineering. Allow for expansion of text strings duringlocalization. Most translations are longer than the orig-inal. Allow yourprogram to accept variable-length strings or use the internationallanguage capabilities inherent in the application environment, such asWindows 3.1, Windows 95, Windows NT, or Windows CE.
Message Routing and Migration________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 108 BM210012WT09Special Text FormattingThe display of dates, numbers, and monetary values varies amonglocales. Support for these differences may be provided by yourprogramming environment to simplify the development of code. If yourprogramming environment doesn’t provide such support, includealternative tables or options for use when localizing.Testing an ApplicationVirtually all public network operators have some testing or certificationprocedure available to help ensure that your new applications behaveappropriately when brought onto the network. Many systems also havetest nodes, which allow program testing without risk of interrupting thepublic network. Because each operator’s procedures and requirementsdiffer, check with the operator of your target network regarding theirindividual certification procedure.With the proper documentation, writing an application that will operateon a wireless network anywhere in the world is not difficult. You don’thave to develop an application on site in the region where it willoperate. 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 moreplanning, since the network is not directly accessible from yourdevelopment site. In this case, two approaches are worth considering:q If your application is designed for a DataTAC network inanother country and your local network uses the same versionof DataTAC system as the target network, sign up with yourlocal network operator for service during development, test, andsupport. When the application is complete, it is likely that thetarget network operator will require validation or certificationtests. After having used your local network for developmenttests, validation testing will probably be a straightforwardprocess.If your local network is other than the target network, you might stillwant to develop a local version of the application to test the logic andperformance of your program in a controlled environment. (Be sure toget advanced approval from the local operator to run your test versionwithout it being validated.) In this case, the target network will not betested directly and more verification testing will be required.
Boomer II User Manual & Integrator’s Guide________________________________Message Routing and MigrationBM210012WT09 109 Wavenet Technology
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 110 BM210012WT09Appendix A - NCL InterfaceThe 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 AdobeAcrobat format from the Motorola website athttp://www.mot.com/MIMS/WDG/pdf_docs/8-.pdfGeneric NCL (Native Mode)q Command SDUs (CMND, ASCII A)Commands Value Parameters Value Sub-values and DescriptionsSEND ASCII 1 Send message.READ_MSG ASCII 2 Read queued message in RPM. True only if confirmed delivery modeenabled.CTL_EVENT ASCII 3 Event Report SDUs. Control event.GET_STATUS ASCII 4 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.6RF protocol is RD-LAP 9600.ASCII 0RF_RDLAP_19.2RF protocol is RD-LAP 9200.ASCII 1RF_MDC4800RF protocol is MDC 4800.ASCII 2RF_DUALDual RD-LAP 9.2/MDC4800.ASCII 3NCL_PRE1.2NCL support is R1.0 or R1.1.ASCII 0NCL_1.2NCL support is R1.2.ASCII 2
Boomer II User Manual & Integrator’s Guide___________________________________Appendix A - NCL InterfaceBM210012WT09 111 Wavenet TechnologyCommands Value Parameters Value Sub-values and DescriptionsR_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 MotorolaASCII 0ASCIIL..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.SET_CNF 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:FLOW_NONE No flow control. ASCII 0FLOW_XONXOFF XON/XOFF ASCII 1FLOW_RTSCTS RTS/CTS ASCII 2S_RADIO_CHANNEL ASCII E Select the radio channel.
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 112 BM210012WT09Commands Value Parameters Value Sub-values and DescriptionsS_CUR_CNF ASCII F Save the modem configurationR_DEF_CNF ASCII G Restore the modem configurationR_STO_CNF ASCII H Read the modem configuration:CNF_EVENT_ Event control flag ASCII 0FLAGS settingsCNF_DELIVERY_ Outbound SDU del.  ASCII 1MODE modeCNF_RADIO_ Radio control ASCII 2CONTROLsettings:S_RX_CONTROL ASCII CS_TX_CONTROL ASCII BS_POWER_SAVE ASCII I Set the PowerSave mode.S_ROAM_MODE ASCII J Set the roaming mode:ROAM_MANUALSet to manual.ASCII 0ROAM_AUTOSet to automatic.ASCII 1S_BAUD ASCII K Set the baud rate for NCL communications:BAUD_12001200 baudASCII 0BAUD_24002400 baudASCII 1BAUD_48004800 baudASCII 2BAUD_96009600 baudASCII 3BAUD_19K219200 baudASCII 4
Boomer II User Manual & Integrator’s Guide___________________________________Appendix A - NCL InterfaceBM210012WT09 113 Wavenet TechnologyCommands Value Parameters Value Sub-values and DescriptionsBAUD_38K438400 baudASCII 5S_ANTENNA Undefined Select the antennaASCIIL..Z Reserved.RESET_RPM 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.ASCIIA..Y, 7..9 Reserved.VENDOR ASCII Z Vendor-specific command.q Event Report SDUs (EVENT, ASCII B)Events Value Event ReportEnable Bit Parameters Value DescriptionsRCV_MSG_DATAASCII A RCV_MSG_DATA_BIT$10 Received messagedata.RCV_MSG_NOTIFICATIONASCII B RCV_MSG_NOTIFY_BIT$08 Received messagenotification. True onlyif confirmed deliverymode enabled.TX_EVENT ASCII C TX_EVENT_BIT $04 Physical-leveltransmitter event.TX_KEYED ASCII 1 Transmitter keyed.TX_DEKEYED ASCII 2 Transmitter dekeyed.RX_EVENT ASCII D RX_EVENT_BIT $02 Physical-level receiverevent.RX_IN_RANGE ASCII 1 RF in range.RX_OUT_OF_RANGE ASCII 2 RF out of range.RX_PWR_SAVE_ENABLEDASCII 3 Power saving enabled.RX_PWR_SAVE_DISABLEDASCII 4 Power saving disabled.RX_ACTIVE ASCII 5 Device in active stateon RF channel.CHAN_DISALLOWED ASCII 6 Device disallowed onchannel.RX_REG_DENIED ASCII 7 Flash LED for
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 114 BM210012WT09registration denial.HW_EVENT 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 shutdownimminent.HW_BATT_WARN ASCII 7 Battery at warninglevel.RCV_ERR ASCII F Unreceivable messageevent.RCV_TX_DISABLED ASCII 1 ACK required, PDUreceived. CannotACK, transmitterdisabled. PDUdiscarded.CONTROL ASCII G CONTROL_BIT $20 Control event.CONNECT ASCII 1 NCL connect betweenRPM and DTE .ASCIIH..Y, 1..9 Reserved.VENDOR ASCII Z Vendor-specific event.q Response Status SDUs (RESP, ASCII C)Responses Value Parameters Value Description/Error CodeSUCCESS ASCII 1 Successful.IBQ_FLUSHED ASCII a Error code. Pending SDUs in inbound queue flushed;transmitter disabled. Used only if the RPM cannot supportmessage buffering while transmitter disabled.XFAIL ASCII 2 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 modeenabled.ASCII Reserved.
Boomer II User Manual & Integrator’s Guide___________________________________Appendix A - NCL InterfaceBM210012WT09 115 Wavenet TechnologyP..Y, 1..9SYNTAX ASCII 3 Command SDU syntax error. Note the following error codes:INVALID ASCII b Invalid options.TOO_LONG ASCII c Data is too long.VENDOR ASCII Z ASCII Z Vendor-specific response.
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 116 BM210012WT09Wavenet specific NCL ExtensionsThe following table describes Wavenet specific extensions to the NCL1.2 specification. All SDUs include three VENDOR control byte andthe vendor Id.  (the ‘\’ character is used as an escape character forhexadecimal bytes below):Command Type Command Description Ncl StringGet radio statusGet modem battery statusGet modem “on” timeGet saved modem configuration settingsZF?rZF?vZF?tZF?u1. Get status commandsGet modem serial number: ZFts2. Generic “Set RPMconfiguration” command. Set modem configuration parameters, eg:  * Power save mode.  * Select new active profile.  * NCL receive message notify timer.ZF^[2 Byte ID][2 byte Length][Val]ZF^p\00\00\01[new mode (byte)]ZF^f\00\00\01[new profile (byte)]ZF^n\00\00\02[2 bytes time (msec)]3. Generic “Get RPMconfiguration” command. Get modem configuration, eg:   * Power save mode.* Get list of profiles, number of    profiles and currently selected active    profile.* NCL receive message notify timer.ZF$[2 Byte ID]ZF$p\00ZF$f\00ZF$n\00q GET STATUS COMMANDS:This command allows the DTE to request the current status andconfiguration settings of certain aspects of the modem.FORMAT:WN_GET_STATUS Command Syntax (NCL string “ZF?…”):WN_GET_STATUS Response Syntax:CMND Length SDU TagVENDOR‘Z’ ‘F’ ‘?’StatusRequestWN_GET_STATUSVEND_WAVENETRESP Length SDU Tag VENDOR ‘F’ ‘1’   Response   data...........
Boomer II User Manual & Integrator’s Guide___________________________________Appendix A - NCL InterfaceBM210012WT09 117 Wavenet Technologyq OPERAND DESCRIPTIONS AND RESPONSES:The various Vendor Status Requests that can be made, and the formatof their response information in the SUCCESS response SDU, aredescribed as follows.  Please note that all multiple byte fields are storedMSB first.WN_GET_RADIO: Get radio status information (NCL string “ZF?r”).SUCCESS is followed by a block of status information as shownbelow:WN_GET_RADIO Response Format:76543210RSSI [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 thestrength of the received signal from thebase station measured in dBm.  A typicalvalue could be -90.Current Frequency:  Four byte unsigned integer representingthe frequency of the inbound signal in Hzfor the channel the modem is currentlyscanning or locked on to.Current channel: Unsigned word (2 bytes) representingcurrent  channel.Current  Base Station ID:  Unsigned byte representingcurrent base station ID.
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 118 BM210012WT09WN_GET_BATT_VOLT:  Get modem battery status information(NCL string “ZF?v”).SUCCESS is followed by a block of status information in the formatshown below:WN_GET_BATT_VOLT Response Format:76543210Battery Voltage (2 bytes)Battery PercentageWhere:Battery Voltage: Two byte unsigned integer representingthe Voltage of the battery in mV.Battery Percentage: Estimate of the remaining capacity of thebattery.  This value ranges from 0 to 100(unsigned byte).WN_GET_TIME:Get modem time information (NCL string“ZF?t”).SUCCESS is followed by a block of status information in the formatshown below:WN_GET_TIME Response Format:76543210Elapsed Time [4 bytes]Elapsed Time is a four byte unsigned integer, which represents thenumber of milliseconds, which have passed since the modem was last,turned on or reset.  It is accurate to within 50ms of when the last byteof the request message was received by the modem.
Boomer II User Manual & Integrator’s Guide___________________________________Appendix A - NCL InterfaceBM210012WT09 119 Wavenet TechnologyWN_GET_SETTINGS:Get configuration information (NCLstring “ZF?u”).SUCCESS is followed by a block of status information in the formatshown below:WN_GET_SETTINGS Response Format:76543210LLI [4 bytes]Serial Number [16 bytes].......Reserved (ignore)Home System PrefixHome System IDHome Area ID5 Reserved bytes (ignore)NCL Confirmation ModeNCL Rx ControlNCL Tx ControlNCL Event FlagsNumber 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 standardNCL command 4E also gives the LLInumber back).Serial Number: ASCII string containing the serial numberof the modem.  Unused bytes are zeros.The NCL command ZFts also gives theserial number back.NCL Confirmation Mode: Default start-up state for theconfirmation mode of the NCL layer.  Itis a zero for unconfirmed mode, or a onefor confirmed mode.NCL Rx Control and NCL Tx Control:
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 120 BM210012WT09Indicate the start-up state for the NCLsettings for RX_STATUS andTX_STATUS respectively.  A zeroindicates disabled, a one indicatesenabled.NCL Event Flags:  Byte which indicates the start-up state ofthe NCL event reporting.  A set bitindicates the relevant event is enabled.  Acleared bit indicates the event is disabled.The bits are as follow:Bit 7 - Reserved (ignore)Bit 6 - Rx_ErrorBit 5 - ControlBit 4 - Rcv_Msg_DataBit 3 - Rcv_Msg_NotifyBit 2 - TxBit 1 - RxBit 0 - HwrNumber of Group LLIs:Number of Group LLI fields whichfollow.Group LLIs: Each is a four byte unsigned integer.  Thenumber of Group LLIs is given in theprevious field.Number of Static Channels: Number of channel fieldswhich follow.Static Channels: Each is a two byte unsigned integer.  Thenumber of Static Channels is given in theprevious field.WN_GET_SERIAL:Get modem serial number (NCL string “ZFts”).SUCCESS is followed by a block of status information in the formatshown below:WN_GET_SERIAL Response Format:76543210Modem serial number [10 bytes]The modem serial number is unique to each modem and consists ofASCII characters.  The tenth character is typically a null terminationcharacter.
Boomer II User Manual & Integrator’s Guide___________________________________Appendix A - NCL InterfaceBM210012WT09 121 Wavenet Technologyq Generic set RPM Configuration command(WN_SET_PARAM):This command allows the DTE to set the configuration settings ofcertain aspects of the modem.FORMAT:WN_SET_PARAM Command Syntax (NCL string “ZF^…”):WN_SET_PARAM Response Syntax:q OPERAND DESCRIPTIONS AND RESPONSES:The various Vendor Parameter settings that can be made are describedas follows.  Please note that all multiple byte fields are stored MSBfirst.  Numbers prefixed with “0x” are expressed as hexadecimal.“Byte” (optionally followed by a sequence number) is used to indicatea single byte.Parameter Number A 16-bit field, which is unique to eachparameter, used to differentiate them.Parameter Length A 16 bit field, which indicates the lengthof the following parameter, in bytes.Parameter Contents 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:Set Modem Configuration  (NCL string“ZF^[2 byte parameter number][2 Byteparameter length][parameter block..]”).RESP Length SDU Tag VENDORSUCCESSVEND_WAVENETCMND Length SDU TagVENDOR‘Z’ ‘F’ ‘^’WN_SET_PARAMVEND_WAVENETParameter number Parameter lengthParametercontents …
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 122 BM210012WT09Parameter name : WN_PWR_SAVE_MODEParameter number : 0x7000 (“Byte1Byte2”)  (ASCII 0x70 = ‘p’)Parameter length : 0x0001 (“Byte3Byte4”)Parameter contents : One unsigned byte (“Byte5”) indicating thePowerSave mode as follow:ASCII ‘0’ : EXPRESS  (DisabledPowerSave or  “full awake” mode).ASCII ‘1’ :   MAXIMUM  (4 windows).ASCII ‘2’ :    AVERAGE  (8 windows).ASCII ‘3’ :     MINIMUM (16 windows).Parameter name: WN_PROFILEParameter number : 0x6600 (“Byte1Byte2”) (ASCII 0x66 = ‘f’)Parameter length : 0x0001 (“Byte3Byte4”)Parameter contents: One unsigned byte with the number of the newactive profile.Parameter name: WN_MSG_RX_NOTIF_TMRParameter number : 0x6E00 (“Byte1Byte2”) (ASCII 0x6E = ‘n’)Parameter length : 0x0002 (“Byte3Byte4”)Parameter contents: One unsigned word (2 bytes) containing thenumber of milliseconds between messagenotifications to the Palm.  The maximum setting is65 seconds (65000 milliseconds).
Boomer II User Manual & Integrator’s Guide___________________________________Appendix A - NCL InterfaceBM210012WT09 123 Wavenet Technologyq Generic get RPM Configuration command(WN_GET_PARAM):This command allows the DTE to get the configuration settings ofcertain aspects of the modem.  This section should be seen togetherwith the previous section (“Generic GET RPM Configurationcommand”).FORMAT:WN_GET_PARAM Command Syntax (NCL string “ZF$…”):WN_GET_PARAM Response Syntax:q OPERAND DESCRIPTIONS AND RESPONSES:The various Vendor Parameter values that can be requested  are listedin the previous section (“Generic set RPM Configuration command”).The responses to these commands obey the WN_GET_PARM responsesyntax 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 eachparameter, used to differentiate them.Parameter Length A 16 bit field, which indicates the lengthof the following parameter, in bytes.Parameter Value The actual value of the parameter.  Theformat 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).CMND Length SDU Tag VENDOR‘Z’ ‘F’ ‘$’WN_GET_PARAMVEND_WAVENETParameter numberCMND Length SDU Tag VENDOR‘Z’ ‘F’ ‘$’SUCESSVEND_WAVENETParameterLengthParameterValue
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 124 BM210012WT09SUCCESS is followed by a block of information in the format shownbelow: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 ofprofiles in configuration sector.  The numberof profiles may change.Active profile number: Unsigned byte giving the number (or index) ofthe currently active profile.Profile name: Null terminated string of 24 bytes of length(the string may be shorter than the 24 bytes aslong as it is followed immediately by the nulltermination character). The 24 bytes do notinclude the null termination character.q NCL Label ValuesPlease note the following additions/clarifications to the NCL LabelValues Table:CMND ASCII 'A'RESP ASCII 'C'SUCCESS ASCII '1'VENDOR ASCII 'Z'VEND_MOTOROLA ASCII '0'VEND_WAVENET ASCII 'F'WN_GET_STATUS ASCII '?'WN_GET_RADIO ASCII 'r '(eg NCL command ZF?r)WN_GET_BATT_VOLT ASCII 'v' (eg NCL command ZF?v)WN_GET_TIME ASCII 't' (eg NCL command ZF?t)WN_GET_SETTINGS ASCII 'u' (eg NCL command ZF?u)WN_GET_SERIAL ASCII ‘s’ (eg NCL command ZFts)WN_SET_PARAM ASCII ‘^’ (eg NCL cmd ZF^\04\00\00\01\09)WN_GET_PARAM ASCII ‘$’ (eg NCL commandS ZF$..)WN_PWR_SAVE_MODE  0x7000 (eg NCL cmd  ZF$\70\00 = ZF$p\00)WN_PROFILE 0x6600  (eg NCL cmd  ZF$\66\00 = ZF$f\00)WN_MSG_RX_NOTIF_TMR 0x6E00 (eg NCL cmd ZF$\6E\00 = ZF$n\00)WN_CMD          ASCII  '*'  (eg NCL commands ZF*..)
Boomer II User Manual & Integrator’s Guide___________________________________Appendix A - NCL InterfaceBM210012WT09 125 Wavenet TechnologySAR Routine FunctionAn SAR limiting function is available for end user applications to limitthe average transmitted power by preventing new data transmissionsuntil the previous period’s average transmitted power is less than therequired SAR level.During all transmission times a Retransmit Delay Accumulator isincremented 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 nexttransmission is inhibited, dependent on the required duty cycle and thelast transmission time. Data to be transmitted will be accumulated in adata buffer.When not transmitting, the Retransmit Delay Accumulator decrementsuntil 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 otherwiseprogrammed.
Appendix A - NCL Interface___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 126 BM210012WT09SAR AlgorithmInitialise duty cycle of non transmit time, back off timer and Tx ontimer.Then execute the following state machine.Idle Buffer dataHas backoff timerexpired?Are webacking offTx?Tx datareset Tx ontimeFinish TxcurrentpacketRecalculate / Setback off timerbased on dutycycle and lasttransmission timeMore data to send?TxDataRequeYes NoYesNoTx ontimeExpired?All datasentYesNo
Boomer II User Manual & Integrator’s Guide________________________________Appendix B - Sample ProgramsBM210012WT09 127 Wavenet TechnologyAppendix B - Sample ProgramsSample programs are provided with the SDK. The purpose of thesesample programs is to show how a complete working client serverapplication can be built using the SDK NCL API with the clientprogram and the SDK SCR API with the server program.These sample programs demonstrate how to write a simple applicationthat allows a wireless client to send data to a central server applicationand receive responses back from the central server application. Thesample programs are not intended to be a functional application, but theprograms are intended to serve as a guide to writing applications andcan be used as a basis for developing more complex applications.The information given in this document is intended to supplement thesource code for the applications by providing a high-level overview ofthe source code.In the following sections, the client and server applications aredescribed separately.Client ApplicationThe client application is called ModemInfo that uses the NCL API tointerface to the DataTAC® network. The sample client programretrieves the modems current status, and enables the user to send andreceive 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, themodems power save mode, and if supported it’s vibrator mode.
Appendix B - Sample Programs________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 128 BM210012WT09The status tab displays the modem’s current channel (if registered) andit’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, HardwarePlatform and software version.
Boomer II User Manual & Integrator’s Guide________________________________Appendix B - Sample ProgramsBM210012WT09 129 Wavenet TechnologyThe messages Tab allows a user to send and receive messages from thechannel the device is currently registered on.
Appendix B - Sample Programs________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 130 BM210012WT09Server ApplicationThe server program is a Windows NT command line program thatconnects to the DataTAC® network switch and waits to receive datafrom wireless client devices. Any data received from wireless clients isechoed back to the same client on the same session. The serverprogram 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 requiringany user input.Communications to the RNG are established either via a TCP/IP or anX.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 themessages from the network. The server program contains code tocommunicate with the network switch or RNG via either X.25 orTCP/IP. The X.25 connection code is written using the EICON X.25Developer's Tools for Win32. To run the application over an X.25connection, you must have an X.25 connection to the switch, as well asan EICON X.25 card plus EICON WAN Services drivers for this card.To run the sample application via TCP1IP, you must have a TCP/IPconnection to the network switch. For help in getting this connectionset up, contact your DataTAC network operator.The following pseudo code outlines the implementation of the main() function.main (){Initialize application variablesSet default values for user configurable parametersProcess command line and update parametersInitialize X.25 API or Winsock DLL (connection toRNG)Initialize SCR API using scr_Init()Establish a connection to the DataTAC networkwhile (!terminate){Read data from the networkHandle Message zHandleMessage()}Terminate connection to RNGClean up}
Boomer II User Manual & Integrator’s Guide________________________________Appendix B - Sample ProgramsBM210012WT09 131 Wavenet TechnologyInitialisation and LoginzEstablishConnection() establishes the connection to the RNG, usingeither TCP/IP or X.25. When either a DataTAC(D 4000 or DataTAC6000 network is used, this is all that is needed for the server to connectto the DataTAC network.When a DataTAC 5000 network is being used, the server applicationmust login to the RNG to identify itself. The login message is encodedusing scr_EncodeLogin() with the host ID and password as specifiedby the command line parameters. The encoded login message is thensent to the RNG.Before the program exits, the connection to the RNG is closed. Nospecial SCR processing is needed here.Data TransferzSendData() is a function that sends data to the RNG, using TCP/IP orX.25 as appropriate. zReceiveData() is a similar function used toreceive data from the RNG. These two routines hide the low-leveldetails of the X.25 or TCP/IP connection to the DataTAC network.When the server application receives a message from the DataTACnetwork, using zReceiveData(), the message is passed tozHandleMessage(). This routine uses scr_Decode() to decode theincoming data, and then uses a switch statement to process themessage.All data transfer within the server program is interpreted using theDataTAC network independent data message types, such asSCR_FROM_NET and SCR_TO_NET messages. This makes the codeapplicable to all DataTAC network versions and reduces the problemsin 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. Thesemessage types will not be received on DataTAC 4000 or DataTAC6000 networks, and therefore will not affect the operation of theprogram.All messages received from the DataTAC network result in a messagebeing output to the screen to indicate that the message was received.Some message types, such as SCR_ACK or SCR_CI, require no furtherprocessing other than the output of a message. Other message types,such as SCR_FROM_NET or SCR_LR, require a response message tobe sent to the DataTAC network. This is handled by formatting theresponse within the switch statement, and this response is sent to theDataTAC network at the end of the zHandleMessage() function.
Appendix B - Sample Programs________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 132 BM210012WT09The following pseudo code gives an overview of the implementation ofzHandleMessage().zHandleMessage(msg){scr_Decode scr_Decode (msg);   /* decode the message */if (error decoding) {Report SCR decoding errorreturn}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 erroroccurred */if (an error occurred){Print reason text}else{ Report successful delivery of message}break;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*/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'}}}
Boomer II User Manual & Integrator’s Guide_________________________________Appendix C – Wavenet LoaderBM210012WT09 133 Wavenet TechnologyAppendix C - Wavenet Application LoaderThe Application Loader software is used to upgrade the residentsoftware installed on your Wavenet OEM modem.For optimum performance ensure that you are using the latestapplication version.This appendix, for your convenience, explains the procedure forupdating the Application Loader software and has a troubleshootingsection to assist with any problems.Please refer to the Application Loader User Manual to ensure you havethe latest information.Updating Application Loader Software on Your ModemThe Application Loader software may be used for all Wavenetmodems. The procedure is the same for all modems but some of thescreens may differ in appearance.Follow the procedure below to check the software version currentlyloaded on your modem and if necessary, to upload the modemapplication.1. Connect the Boomer II to the Test Jig as described on page 22.2. Connect the Data Communications Modem connector to theBoomer 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 PCconnector is a 9-pin plug. If your computer has a 25-pin serialport 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 endof the Apploader file name denotes which modem the file isappropriate for, i.e. M for the Dualwave M modem, V for theDualwave V modem and BM2 for the Boomer II OEM modem.The three numerical characters at the end of the file name showthe version number of the application software, i.e.408 is software version 4.08 and233 is software version 2.33If you select the incorrect Apploader file for your modem thefollowing typical message will be displayed.
Appendix C – Wavenet Loader________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 134 BM210012WT09Note: The message shown above will appear if you areattempting to upgrade using ApploaderM408.exe with aDualwave V modem.7. The following screen is displayed.8. Select the appropriate PC communications port to which themodem is connected.9. If the program recognises that the version of Application youare attempting to install is later than the version currentlyinstalled, the Download Application button will becomeenabled. A message is displayed in the status bar advising thatthe application software versions differ and requesting that youpress the Download Application button to update.If the program recognises that the version of Application youare attempting to install is earlier than the version currentlyinstalled, the Download Application button will remaindisabled. A message is displayed in the status bar advising thatthe application software version on the modem is up to date andrequesting that you exit the program.10. Click   to update the Application software.A progress bar is displayed informing you of the progress of theupdate.11. After the application has been updated, the modem isautomatically switched off. A message is displayed promptingyou to switch the modem on again.Select theappropriatecom port onyour PC thatthe modemis connectedto.Click theDownloadApplicationbutton todownloadthe latestversion.Displays the currentversion of Applicationsoftware on yourmodem.Displays the newapplication available.Status bar.
Boomer II User Manual & Integrator’s Guide_________________________________Appendix C – Wavenet LoaderBM210012WT09 135 Wavenet Technology12. Press the modem’s On/Off button and click 13. A message is then displayed in the status bar, informing youthat that the application software on the modem is up to date.14. Click   to exit the program. This will automaticallyswitch your modem off.TroubleshootingYou shouldn’t encounter any problems updating the ApplicationLoader software, however the following messages may appear.This message will appear if the modem is disconnected during thedownload. Ensure that all the connections between the PC and themodem are secure, check the battery connections, ensure the modem isswitched on and follow the instructions in the message to try again.This message will appear if the modem is disconnected whilst runningthe Application Loader. Ensure that all the connections between the PCand the modem are secure, check the battery connections and ensurethe modem is switched on.This message will appear if the bootloader version on the modem is tooold to allow you to upgrade the application. Return the modem to yoursupplier to be upgraded.This message (or similar) will appear if you have attempted to upgradeyour modem with the incorrect Application Loader file.
Appendix C – Wavenet Loader________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 136 BM210012WT09The ApploaderM408.exe is applicable to the Dualwave M modem andApploaderV233.exe is applicable to the Dualwave V modem.The letter preceding the three numerical characters at the end of theApploader file name denotes which modem the file is appropriate for,i.e. BM2 for the Dualwave Boomer II OEM modem, M for DualwaveM modem and V for Dualwave V modem.If the modem does not respond after an error message and you cannotswitch it off/on, reset the modem by inserting the end of a paper clipinto the reset hole at the back of the modem. Then switch the modemon and continue the upload.
Boomer II User Manual & Integrator’s Guide_________________________Appendix D - Numeric Conversion ChartBM210012WT09 137 Wavenet TechnologyAppendix D - Numeric Conversion ChartBinary/Octal/Decimal/Hex/C/ASCII Conversion TableBinary Oct Dec Hex CASCII Definition Binary Oct Dec Hex CASCII00000000 000 0 00 CNUL Null, or all zeros 01000000 100 64 40 P@00000001 001 1 01 CSOH Start of Heading 01000001 101 65 41 UX A00000010 002 2 02 CSTX Start of Text 01000010 102 66 42 UX B00000011 003 3 03 CETX End of Text 01000011 103 67 43 UX C00000100 004 4 04 CEOT End of Transmission 01000100 104 68 44 UX D00000101 005 5 05 CENQ Enquiry 01000101 105 69 45 UX E00000110 006 6 06 CACK Acknowledge 01000110 106 70 46 UX F00000111 007 7 07 CBEL Bell 01000111 107 71 47 UG00001000 010 8 08 CBS Backspace 01001000 110 72 48 U H00001001 011 9 09 CS HT Horizontal Tab 01001001 111 73 49 UI00001010 012 10 0A CS LF Line Feed 01001010 112 74 4A UJ00001011 013 11 0B CS VT Vertical Tab 01001011 113 75 4B UK00001100 014 12 0C CS FF Form Feed 01001100 114 76 4C UL00001101 015 13 0D CS CR Carriage Return 01001101 115 77 4D UM00001110 016 14 0E CSO Shift Out 01001110 116 78 4E U N00001111 017 15 0F CSI Shift In 01001111 117 79 4F UO00010000 020 16 10 CDLE Data Link Escape 01010000 120 80 50 UP00010001 021 17 11 CDC1 Device Control 1 (XON) 01010001 121 81 51 UQ00010010 022 18 12 CDC2 Device Control 2 01010010 122 82 52 U R00010011 023 19 13 CDC3 Device Control 3 (XOFF) 01010011 123 83 53 US00010100 024 20 14 CDC4 Device Control 4 01010100 124 84 54 UT00010101 025 21 15 CNAK Negative Acknowledge 01010101 125 85 55 U U00010110 026 22 16 CSYN Synchronous Idle 01010110 126 86 56 UV00010111 027 23 17 CETB End Transmission Block 01010111 127 87 57 UW00011000 030 24 18 CCAN Cancel 01011000 130 88 58 UX00011001 031 25 19 CEM End of Medium 01011001 131 89 59 UY00011010 032 26 1A CSUB Substitute 01011010 132 90 5A UZ00011011 033 27 1B CESC Escape 01011011 133 91 5B P[00011100 034 28 1C CFS File Separator 01011100 134 92 5C P\00011101 035 29 1D CGS Group Separator 01011101 135 93 5D P]00011110 036 30 1E CRS Record Separator 01011110 136 94 5E P^00011111 037 31 1F CUS Unit Separator 01011111 137 95 5F P_00100000 040 32 20 S SP Space 01100000 140 96 60 P`00100001 041 33 21 P!01100001 141 97 61 LX a00100010 042 34 22 P"01100010 142 98 62 LX b00100011 043 35 23 P#01100011 143 99 63 LX c00100100 044 36 24 P$01100100 144 100 64 LX d00100101 045 37 25 P%01100101 145 101 65 LX e00100110 046 38 26 P & 01100110 146 102 66 LX f00100111 047 39 27 P'01100111 147 103 67 L g00101000 050 40 28 P(01101000 150 104 68 L h00101001 051 41 29 P)01101001 151 105 69 L i00101010 052 42 2A P*01101010 152 106 6A Lj00101011 053 43 2B P+01101011 153 107 6B Lk00101100 054 44 2C P,01101100 154 108 6C Ll00101101 055 45 2D P-01101101 155 109 6D Lm00101110 056 46 2E P.01101110 156 110 6E L n00101111 057 47 2F P/01101111 157 111 6F L o00110000 060 48 30 NX 001110000 160 112 70 L p00110001 061 49 31 NX 101110001 161 113 71 L q00110010 062 50 32 NX 201110010 162 114 72 L r00110011 063 51 33 NX 301110011 163 115 73 L s00110100 064 52 34 NX 401110100 164 116 74 L t00110101 065 53 35 NX 501110101 165 117 75 L u00110110 066 54 36 NX 601110110 166 118 76 L v00110111 067 55 37 NX 701110111 167 119 77 L w00111000 070 56 38 NX 801111000 170 120 78 L x00111001 071 57 39 NX 901111001 171 121 79 L y00111010 072 58 3A P:01111010 172 122 7A Lz00111011 073 59 3B P;01111011 173 123 7B P{00111100 074 60 3C P<01111100 174 124 7C P|00111101 075 61 3D P=01111101 175 125 7D P}00111110 076 62 3E P>01111110 176 126 7E P~00111111 077 63 3F P?01111111 177 127 7F CDEL
Appendix D - Numeric Conversion Chart_________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 138 BM210012WT09
Boomer II User Manual & Integrator’s Guide___________________________________Appendix E - SpecificationsBM210012WT09 139 Wavenet TechnologyAppendix G - SpecificationsPhysical PropertiesWeight < 50gSize (L x W x H) 70mm x 52mm x 9mmCommunication ProtocolsModem to radio network protocol RD-LAP 3.1, 3.2, 3.3Modem to terminal (e.g. handheld) protocol NCL 1.2Environmental ConditionsOperating temperature -30°C to +60°CStorage temperature -40°C to 70°CPortsData Interface Port TTL compatible serial port,9600 baudRF Connector MMCX female, 50Ω.Straight connection or right angleLED IndicatorsPower Green flashes when scanningOn, when lockedOff, when the Boomer II is offReceive Green flashes when receivingTransmit Red flashes when transmittingPowerVoltage 3.8V (3.4 to 4.2V range)Transmitter < 1.7AReceiver < 85mATransmit Duration 32ms (minimum)1s (maximum)Off current consumption < 100µAPower Supply Ripple < 15mV peak to peak
Appendix E - Specifications___________________________________Boomer II User Manual & Integrator’s GuideWavenet Technology 140 BM210012WT09SynthesiserFrequency range 806 – 825MHz (A),890 – 902MHz (B)Channel spacing 25kHz (A)12.5kHz (B)Frequency Error(-30º ~ +60ºC)±1.5ppm (<1300Hz) (A)±0.8ppm (750Hz) (B)TransmitterFrequency range 806 – 825MHz (A),896 – 902MHz (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% maximumTurn on time < 5msSpurious emission < - 30dBmAdjacent channel power < - 55dBc at 25kHz channels (A)< - 45dBc at 12.5kHz channels (B)ReceiverFrequency range 851 – 870MHz (A)935 – 941MHz (B)Channel spacing 25kHz (A)12.5kHz (B)Settling time < 5msSensitivity < -111dBm at 5% PER RD-LAP 19.2< -114dBm at 5% PER MDCSpurious emission (receive mode) < -57dBmChannel selectivity > 50dB (5kHz dev 1kHz tone) (A)> 50dB (2.5kHz dev 1kHz tone) (B)Spurious rejection > 70dBImage rejection > 60dB
Boomer II User Manual & Integrator’s Guide___________________________________Appendix E - SpecificationsBM210012WT09 141 Wavenet TechnologyRSSI Reading -120dBm ~ -45dBm

Navigation menu