Documente Academic
Documente Profesional
Documente Cultură
Messaging Software
Tools
S5, Version 02
Legal Notice
This documentation is owned by SkyWave Mobile Communications Inc. (SkyWave) and protected by
applicable copyright laws and international treaty provisions. Other copyrighted names used are the property
of their respective owners. Therefore, you must treat this documentation like any other copyrighted material.
You may not make the documentation, or copies thereof, available in any manner or form, or use, copy or
transfer any part, to anyone outside your company.
If you received this documentation by electronic transmission or download, by installation or use of the
documentation, you acknowledge that you have read and understand this license agreement and agree to be
bound by its terms and conditions.
This documentation is provided on an as-is basis without any warranty of any kind. You assume the entire
risk as to the results or performance of the software and hardware. Under no circumstance shall SkyWave be
held liable for any direct, indirect, consequential, or incidental damages arising from the use or inability to
use the software, hardware or documentation.
From www.SkyWave.com login and follow the link to the Downloads section. The complete Software and
Documentation License Agreement is distributed as a part of the SkyWave Developers Toolkit (SDK).
Contact Information
SkyWave Mobile Communications Inc.
On-line :
Web site:www.SkyWave.com
On-line documentation :
support@skywave.com.
S5, Version 02
Table of Contents
Legal Notice ........................................................................................................................ i
Contact Information........................................................................................................... i
Table of Contents............................................................................................................... ii
Preface ................................................................................................................................ v
Whats New?
v
Purpose
v
Audience
v
Notation
v
Requirements
v
Recommended Reading
vi
Reference
vi
1
Overview ...................................................................................................................... 1
ii
S5, Version 02
Document Versions.......................................................................................................... 32
Index ................................................................................................................................. 33
iii
S5, Version 02
NOTE
THIS DOCUMENT CONTAINS INFORMATION ABOUT D+ AND ISATM2M.
PLEASE MAKE SURE TO USE THE INFORMATION APPROPRIATE FOR
THE SERVICE TYPE YOU ARE USING.
PLEASE CONTACT SKYWAVE CUSTOMER SUPPORT FOR ADDITIONAL
ASSISTANCE.
iv
S5, Version 02
Preface
Whats New?
Updates since the last release are below:
Purpose
This document describes the SkyWave messaging software. It is intended to assist
developers and system integrators in the rapid creation of custom SCADA and/or
tracking applications using SkyWave terminals and network services.
Audience
This document is intended for a technical audience, such as software developers and
system integrators.
Notation
This document uses satellite or satellite service to refer to D+ and IsatM2M service
except when discussing information specific to a particular service (D+ only or IsatM2M
only) or a specific satellite (GPS satellite or Inmarsat satellite).
Requirements
The following additional software is required:
S5, Version 02
Recommended Reading
It is recommended that you be familiar with the content of the following documents
before using this guide. These documents are available from the SkyWave Developers
Toolkit (SDK), or support.skywave.com.
[G1]
Reference
The following reference documents are available on the SkyWave Developers Toolkit
(SDK), or support.skywave.com:
[N3]
[R1]
[R4]
[S6]
[T5]
[T8]
[T6]
[T9]
vi
S5, Version 02
vii
S5, Version 02
Overview
The messaging software tools enable the rapid development of customized SkyWave
satellite applications. The three components are:
Message Service
A Microsoft Windows service that allows user applications to exchange messages
with SkyWave terminals. To receive and send messages, the user application simply
queries and updates tables in a Microsoft SQL Server database.
Message Manager
A graphical desktop utility to control, configure and monitor the operation of the
Message Service.
The easiest way to become familiar with the operation of the messaging software tools is
follow the tutorial in this document.
The custom messaging facilities are especially useful when the SkyWave terminal is
connected to an I/O module. Data from various external sensors can be packed into
messages for transmission over satellite, then unpacked and stored in a database for easy
access by any application that requires the sensor data.
The following diagram shows the flow of information between each component in the
system:
S5, Version 02
Satellite
Message
Manager
MHS and
SkyWave
Gateways
Users DMR
or SureLinx
Terminal
DMR
Scope
Message
definition
file
Database
Users External
controller
(optional)
Script
Users
Application
Message
Service
Message
Designer
file
S5, Version 02
Messaging Tutorial
2.1 Configure the Message Service
1. Install the SkyWave Developers Toolkit (SDK) on your PC if not already installed.
See [R1 or R4] for instructions.
2. Launch Message Manager from the Start menu on the PC by clicking SkyWave
Developers Toolkit>Applications>Message Manager. The Message Manager
notification window appears (Figure 2).
Since it is not yet configured, the Message Service is not installed and the there is no
database connection available.
Figure 2 Message Manager Service windows
5. Click Edit Connection. The Data Link Properties window appears (Figure 4).
S5, Version 02
6. Enter the information, on the Connection tab, about the database server you wish to
use, include the user name, password, and database name.
If you do not have a database to connect to, create one now using SQL Enterprise
Manager.
7. Click in the checkbox next to Allow saving password if you entered a password.
8. Click Test Connection to verify that the information you entered is correct (Figure
4). If not, re-enter the information or enter data for a different database server.
9. Click Install Tables to create the required tables in the selected database.
The database status will change to 0 messages (Figure 5).
Figure 5 Connection String window
10. Click Edit>Control Station from the menu. The default list of control stations is
blank (Figure 6).
S5, Version 02
11. Enter your control station and password information then click OK. For most
applications, only one control station is necessary.
Configuration is complete.
12. Click Service>Start from the menu.
The service state changes to running and the light bulb icon glows (Figure 7).
Note: Message Service continues to run after you close Message Manager.
Figure 7 Message Manager Service Running window
S5, Version 02
2. Click New and enter the terminal ID of the SkyWave terminal where you want to
send the poll request.
Use the terminal ID found in the e-mail from Customer Support or on the bottom of
the terminal.
Figure 10 New Message
S5, Version 02
3. Click the Poll tab, select Poll C and then click Send.
The Forward Messages window updates to show the unsent outgoing message
(Figure 11).
Figure 11 Forward Message State unsent message
5. Click View>Return Messages then select Poll C from the pull-down menu and wait
a few minutes before clicking Refresh to check for a reply (Figure 13).
This may take several minutes from the time the poll request was transmitted.
S5, Version 02
StandardPoll.dmd file
in this folder
S5, Version 02
The .dmd file loads the definition of the Standard Poll messages. Use this definition
file as the basis for creating new custom poll messages.
In our application example we want a position report that contains only
latitude,
longitude,
speed, and
By clicking the + next to a poll number/letter, we see the fields included with that
poll.
4. Click + next to Poll B.
In Figure 15 we see that a Poll B message includes latitude, longitude, and altitude.
Since Poll B has most of the fields we want for our application example, we will use
it as the basis for creating our custom poll message.
Note: If you are not familiar with the fields for each poll, you can refer to the
Standard Poll Report tables in [T6 and T9] for a complete description.
Note: You can use any Standard Poll Message as the basis for your custom poll
message. Using an existing message with most of the fields/bit sizes, you
need saves time when creating a custom poll message.
5. Click Latitude (Figure 15) under the Poll B heading to see the field details. If you are
familiar with the different types of poll messages, you will notice that Poll B has the
highest number of bits defined for latitude and longitude and Poll 8 has the highest
bits defined for speed.
Note: The higher the bit value for a field, the more accurate the information
received from the terminal about that field.
S5, Version 02
Number of bits
assigned to the
field
10
S5, Version 02
New poll
number
Larger
message
size
8. Click + next to Poll 8 to expand the window, then drag and drop the speed and
heading fields to the New Poll message.
Note: Your new message has been allocated a poll number of hex 20.
Note: The size of this new poll message is larger than 64 bits. See section 2.5.
We have now completed the definition of our new custom message. Before we can save it
and use it, we need to verify the size of our poll message and eliminate the Standard Poll
messages from our custom poll file.
2.5 Change the Poll Message Size and Save the File
1. Click New Poll from the list.
The bottom of the window (Figure 16) shows that the new poll is using 68 of 64 bits.
If the terminal is accessing IsatM2M service, a message this size should be fine since
IsatM2M allows for extended payloads (up to 184 bits). In this case, you must click
the checkbox next to Extended burst under the Satellite Payload Size heading (Figure
17).
Note: Extended payloads are only available on DMR-800 and SureLinx systems
with IsatM2M service.
If the terminal is accessing D+ service then we have exceeded the number of bits
allowed in the payload. In this case we can do one of two things
Increase the payload size to 72 bits by selecting the message and clicking the
checkbox next to Use for extra payload space under the Destination Address
heading (Figure 17). This option does not allow the use of multiple control
11
S5, Version 02
stations. Also select this option to increase IsatM2M payloads to 192 bits (must
also have Extended burst under the Satellite Payload Size selected).
In our example we will decrease the size of the heading field since we decide that we
do not need that much precision. Currently, the heading is 7 bits, and the divisor is 5.
This allows the heading to range from 0 to 355 degrees in 5 degree steps.
Figure 17 Extended Burst Custom Poll Message
2. Click the down arrow in the Size field under the Source heading to reduce the bits
from the current value of 7 bits to 3 bits (Figure 18).
3. Click the down arrow in the Divisor field under Source to reduce the size of the
divisor to 45.
This allows the heading to range from 0 to 315 degrees by 45 degree steps. Also,
increase the multiplier to 45 so that the heading is properly decoded before being
inserted into the database.
You will notice that the number of bits used decreased to 64 bits from 68 bits.
We can now delete the unnecessary poll messages.
12
S5, Version 02
4. Right-click the first poll message in the list and click Delete. You can also click the
poll message and then click Edit>Delete from the menu.
5. Repeat with the other poll messages in the list until only the New Poll message
remains.
6. Click + next to New Poll and type My Custom Poll in the Poll Name field (Figure
19).
7. Click File>Save As and save the file as My Custom Poll.dmd.
CAUTION:
13
S5, Version 02
14
S5, Version 02
3. Launch DMR Scope from the Start menu on the PC by clicking SkyWave
Developers Toolkit>Applications>DMR Scope. The DMR Scope main window
appears. We will program the custom message into the SkyWave terminal.
4. Click File>Connect from the menu and wait for the initialization process to finish.
5. Click File>Load File from the menu.
6. Click the My Custom Poll.dmd file you recently created. Loading this file causes the
definition of the custom poll message to be stored in the terminals non-volatile
memory.
15
S5, Version 02
4. Select the Poll tab and choose Poll 20 from the pull-down menu, then click Send.
5. Click View>Return Messages then click Refresh until you receive the response
(Figure 22).
Figure 22 From Terminal Traffic Response
16
S5, Version 02
Gateways
Launch Message Manager and click Edit >Gateways to display the SkyWave Gateway
configuration window (Figure 23).
Figure 23 SkyWave Gateway Configuration window
The table is pre-configured with all of the valid SkyWave Gateways. Only change the
Address, Port, or SSL fields in this table if you receive a notice from SkyWave
announcing a change to the gateway network configuration.
The Enable column controls the gateways actively used by Message Service. Gateways
DAP1 and DAP2 are enabled by default. Enabling two gateways with different addresses
provides a back up, allowing Message Service to continue to operate in the event one of
the gateways is unreachable.
If your business requires secure communication, enable only gateways SSL1 and SSL2.
Using the XML gateways can improve performance for large message volumes and high
network latencies. Because of differences in behavior, it is recommended to enable DAP
or XML, but not both at the same time.
3.1.2
Events
Message Service uses the Windows Event Log (Figure 24) to report problems.
Launch Message Manager and click View>Events. You can also start the Windows
Event Viewer from the Windows Control Panel (usually in the Administrative Tools
folder). Click Start> Control Panel> Administrative Tools> Event Viewer>
Application, and look for events with the name SkyWaveMessageService under the
source heading. Double-clicking on each event provides additional information.
17
S5, Version 02
3.1.3
Services
1. Launch Message Manager and click View>Services to display the Windows Service
Viewer. You can also start the Service Viewer from the Windows Control Panel
(usually in the Administrative Tools folder). Click Start> Control Panel>
Administrative Tools> Services> Standard tab.
2. Double-click SkyWave Message Service (Figure 25) to change its properties.
3. Select your preferred startup type from the pull-down menu (Figure 25). Automatic
will automatically start when Windows starts so that it is always running. Windows
2000 and XP also permit the service to be automatically restarted in the event of
failure.
Figure 25 Service Viewer window and Properties window
18
S5, Version 02
Message
Manager
configuration tables
DapGateway
DapCustomMessage
DapControlStation
DapCustomField
DapOption
DapTerminal
Internet
Message Service
SkyWave Versa
gateway
DapDeliverNotification
DapSubmitMessage
Poll Message Tables
User Application
DapGateway Table
This configuration table defines the gateways used to retrieve messages. Every 30
seconds the next gateway on the list checks for new messages. The Edit>Gateways
(Figure 26) menu item shows a dialog which provides a convenient user interface for
editing this table.
19
S5, Version 02
Field
Description
ID
Enable
Name
Address
Port
SSL
3.3.2
DapControlStation Table
This configuration table lists the control stations that are checked for messages. The
Edit>Control Stations (Figure 27) menu item shows a dialog which provides a
convenient user interface for editing this table.
Figure 27 Edit Control Stations window
Field
Description
ID
Enable
Name
Control Station
Password
GatewayEnable01-12
20
S5, Version 02
3.3.3
DapOption Table
This configuration table controls the behaviour of the Message Service. Use the Edit
>Options menu item to edit the values in this table.
Figure 28 Edit Options window
Description
PollInterval
DeliverEnable
SubmitEnable
21
S5, Version 02
Field
Description
SubmitRate
3.3.4
DapTerminal Table
This configuration table allows a name to be associated with each terminal. The use of
this table is optional. Message Manager displays the name of the terminal rather than the
terminal ID if the terminal appears in the table.
Use the Edit >Terminals menu item to edit the values in this table.
Figure 29 Edit Terminals window
Field
Description
ID
Enable
Name
Terminal ID
DapDeliverMessage Table
Description
ID
ControlStationID
TerminalID
ControlWord
DestinationAddress
22
S5, Version 02
Field
Description
MessageDescriptor
UserData
ReplyRequested
ReceivedTimestamp
MessageIdentifier
Timestamp
Region
3.4.2
The poll message tables are created by the Message Manager when a message definition
file (*.dmd) is imported. The message definition file determines the name of the table and
the name and type of the fields it contains. When the Message Service receives a poll
message whose poll type corresponds to a defined message, it decodes the message
according to the definition and inserts a new row in the appropriate poll message table.
Field
Description
MessageIdentifier
<field 1>
<field 2>
<field n>
The message definition file StandardPoll.dmd defines the following fields:
Field
Description
Alarm C
Alarm D
Alarm E
23
S5, Version 02
Field
Description
Alarm F
Altitude
Battery 1
Battery status 2
Digital Input (1-4)
Digital Output (1-2)
Firmware Version
Flag 0
Flag 1
Hardware
Heading
Line (1-4) Type
DapSubmitMessage Table
The messaging application inserts rows into this table in order to queue messages to be
sent. For additional information on the various fields, see To-Terminal Message
Parameters in [T5 or T8].
Field
Description
ID
The DAPC API [S6] refers to battery as batteryVolts and battery delta as batteryVoltDiff
24
S5, Version 02
Field
Description
TerminalID
25
S5, Version 02
Field
Description
MessageIdentifier
3.5.2
DapDeliverNotification Table
The Message Service inserts the notification messages received into this table.
Field
Description
ID
ControlStationID
26
S5, Version 02
4.1 Properties
4.1.1
Message properties
Selecting a poll <value> in the tree to the left of the Message Designer window (Figure
30) displays the properties of that message on the right.
Figure 30 DMR Message Designer main window
27
S5, Version 02
Property
Description
Poll Name
Poll
Number
4.1.2
Field properties
Selecting a field in the tree of the Message Designer window (Figure 31) displays the
properties of that field on the right:
28
S5, Version 02
Poll report
fields
Property
Description
Field Name
Units
Encode
Size
Module
29
S5, Version 02
Property
Description
Port
The port index from which to read data. See Terminal API Port
Definitions in [T6 and T9].
Refer to 4.1.3
Determines whether the most significant bit of the field is interpreted
as a sign bit. Unsigned quantities (such as speed) should not use
signed arithmetic so that a bit is not wasted when negative values are
not possible
Overflows occur when a quantity exceeds the number of bits
allocated to it. With this option enabled, the value will be clamped to
the maximum legal value rather than wrapping. For example, if the
vehicles speed is 130, but only 7 bits are allocated for speed, we
would probably want the speed to be reported as 127 km/h rather
than wrapping and being reported as 2 km/h.
When an error is introduced by dividing a quantity by a certain
factor, it may be desirable to round the value to the nearest value
rather than truncating it. For example, if speed is divided by 10 to
save bits, we would probably want a vehicle traveling at 78 km/h to
be reported with a speed of 80 km/h rather than 70 km/h.
Divisor
Use Signed
Arithmetic
Limit to Max or
Min Value
Round Value
Decode
Type
Precision
Scale
Multiplier
Divisor
Offset
30
S5, Version 02
4.1.3
The remaining properties are numeric values used in formulas used to condition the data
in the terminal before sending the message, as well as in Message Service before writing
into the database. The role of each constant is summarized by the following diagram:
Module n
Port 0
Port 1
Port 2
Port 3
get data from Terminal module
Value
Encode divisor
Round
Payload
Field 1
Field 2
Field 3
Field 4
Value
Decode multiplier
+ Decode Offset
Decode divisor
scale data and store fields in database
Database
Field 1
Field 2
31
Field 3
Field 4
S5, Version 02
Document Versions
Version
Date
Description
Rev A
Rev B
1.0
1.1
1.2
1.3
1.4
Initial release
Post-beta update
Applied new template
Update for XML support
Moved Standard Poll Message
Definitions cross reference table to [T6 or
T9]. Minor fixes.
Minor fixes.
Update for Message Manager and
Message Service version 2.1
See the Whats New section.
02
32
S5, Version 02
Index
Message Manager ................................. 1, 17
Message Service ................................... 1, 17
configuring.............................................. 5
p_GetFromTerminalMessages.................. 26
p_GetToTerminalMessages...................... 26
p_SendPollMessage.................................. 26
poll message
table of field definitions........................ 23
poll name .................................................. 28
poll number............................................... 28
queue lifetime ........................................... 28
queue priority............................................ 28
reference .................................................... vi
requirements ............................................... v
scope ........................................................... v
services ..................................................... 18
size - Message Designer ........................... 29
SkyWave Developers Toolkit (SDK)......... i
StandardPoll.dmd ....................................... 8
stored procedures...................................... 26
to terminal tables ...................................... 24
type - Message Designer........................... 30
units - Message Designer.......................... 29
administration............................................17
configuration tables ...................................19
custom poll message
importing a definition ............................15
sending a request ...................................16
DapControlStation table ............................20
DapDeliverMessage table..........................22
DapDeliverNotification table ....................26
DapGateway table .....................................19
DapOption Table .......................................21
DapSubmitMessage table ..........................24
database overview .....................................18
destination address ....................................28
events.........................................................17
field name - Message Designer .................29
field properties
calculation..............................................31
from terminal tables...................................22
I/O module...................................................1
importing standard poll message definitions
.................................................................5
Message Designer..................................1, 27
field properties.......................................28
33
S5, Version 02
www.SkyWave.com