S5 Messaging Software Tools

Software Tools

Messaging Software Tools

S5, Version 02

The electronic version of this document allows you to use the built-in Hyperlinks and

bookmark links when using Adobe Reader

© 2008 SkyWave Mobile Communications Inc.

http://www.inmarsat.com/�

Software Tools – Messaging Software Tools

S5, Version 02 i

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 Developer’s Toolkit (SDK).

Contact Information SkyWave Mobile Communications Inc.

On-line : Web site:www.SkyWave.com

On-line documentation : Login at support.skywave.com and follow the link to the Downloads section

Customer Support by E-Mail [email protected].

Customer Support by Telephone + 1 613-836-6288 (press 1 for customer support)

http://www.skywave.com/

http://www.skywave.com/

http://support.skywave.com/

mailto:[email protected]


S5, Version 02 ii

Table of Contents Legal Notice ........................................................................................................................ i Contact Information........................................................................................................... i Table of Contents............................................................................................................... ii Preface ................................................................................................................................ v

What’s New? v Purpose v Audience v Notation v Requirements v Recommended Reading vi Reference vi

1 Overview...................................................................................................................... 1 2 Messaging Tutorial ..................................................................................................... 3

2.1 Configure the Message Service 3 2.2 Import the Definitions File 5 2.3 Send a Poll Message 6 2.4 Define a Custom Poll Message 8 2.5 Change the Poll Message Size and Save the File 11 2.6 Import a Custom Poll Message Definition 14 2.7 Send a Custom Poll Message Request 15

3 Message Service and Message Manager ................................................................. 17 3.1 Administration 17

3.1.1 Gateways 17 3.1.2 Events 17 3.1.3 Services 18

3.2 Database overview 18 3.3 Configuration tables 19

3.3.1 DapGateway Table 19 3.3.2 DapControlStation Table 20 3.3.3 DapOption Table 21 3.3.4 DapTerminal Table 22

3.4 Return tables 22 3.4.1 DapDeliverMessage Table 22 3.4.2 Poll message tables 23

3.5 Forward tables 24 3.5.1 DapSubmitMessage Table 24 3.5.2 DapDeliverNotification Table 26

3.6 Stored Procedures 26 4 DMR Message Designer ........................................................................................... 27

4.1 Properties 27 4.1.1 Message properties 27 4.1.2 Field properties 28 4.1.3 Field property calculation 31

Software Tools– Messaging Software Tools

S5, Version 02 iii

Document Versions.......................................................................................................... 32 Index ................................................................................................................................. 33

Software Tools– Messaging Software Tools

S5, Version 02 iv

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.


S5, Version 02 v

Preface

What’s New? Updates since the last release are below:

Updated figures and procedures throughout the document Included IsatM2M content throughout the document Minor wording changes throughout the document Added additional details on changing the poll message size, IsatM2M can go up to

192 bits (Section 2.5) Added IsatM2M information (Section 2.5) Updated information for DapOption Table (Section 3.3.3) Added DapTerminal table (Section 3.3.4) Added I/O lines 1 to 4, re-organized table, expanded poll message table (Section

3.4.2) Added PACC Ocean region (Section 3.5.1) Updated Message Designer (Section 4) Added version field to message properties table (Section 4.1.1) Added field properties: multiplier, divisor, offset (Section 4.1.2) Moved documentation version information to end of document

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:

• Microsoft Windows NT, 2000, or XP (does NOT work on Windows 9x/ME/SE)

• Microsoft SQL Server 2000 (or higher)

• Microsoft .NET Framework (free redistributable)


S5, Version 02 vi

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 Developer’s Toolkit (SDK), or support.skywave.com.

[G1] Introduction to SkyWave Products and Services

Reference The following reference documents are available on the SkyWave Developer’s Toolkit (SDK), or support.skywave.com:

[N3] DAP Protocol Specification

[R1] DMR Evaluation Kit – Getting Started Guide

[R4] SureLinx 8100 Evaluation Kit – Getting Started Guide

[S6] DAP Client API Reference

[T5] DMR-200 Satellite Terminal User’s Guide

[T8] DMR-800 and SureLinx User’s Guide

[T6] DMR-200 Satellite Terminal API Reference

[T9] DMR-800 and SureLinx API Reference




S5, Version 02 vii

THIS PAGE INTENTIONALLY LEFT BLANK


S5, Version 02 1

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

• DMR Message Designer

A graphical utility used to build custom poll messages. The output from the Message Designer feeds both the Message Manager and SkyWave terminal, which permits data to be programmed by the terminal and decoded by 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 2

Figure 1 Messaging Software Information Flow

Satellite

Message Service

Message Manager

Database

User’s Application

Message Designer

Script file

Message definition

file

MHS and SkyWave Gateways

DMR Scope

User’s External controller (optional)User’s DMR

or SureLinx Terminal


S5, Version 02 3

2 Messaging Tutorial

2.1 Configure the Message Service 1. Install the SkyWave Developer’s 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

3. Click Service>Install from the menu.

The service state will change to stopped (Figure 2). Do not start the service yet.

4. Click Edit>Database from the menu. The Database main window appears. Figure 3 Database window

5. Click Edit Connection. The Data Link Properties window appears (Figure 4).


S5, Version 02 4

Figure 4 Data Link Properties window

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 5

Figure 6 Control Stations window

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

13. Continue with section 2.2 Import the Definitions File.

2.2 Import the Definitions File The SkyWave terminal contains a number of built-in Standard Poll messages, which we will use for testing purposes. We must configure Message Service with the Standard Poll message definitions.

Refer to [T6 or T9] for more information on standard Poll messages.

1. Click File>Import Message Definitions from the Message Manager menu, select the StandardPoll.dmd file from the list and click Open (Figure 8).

Since the Standard Poll definitions are already stored in the terminal firmware, there is no need to program the terminal with the definition.


S5, Version 02 6

Figure 8 Import Message Definitions window

2.3 Send a Poll Message 1. Click View>Forward Messages from the Message Manager menu.

The empty grid indicates that no messages have been sent. Figure 9 Forward Messages window

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 7

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

4. Click Refresh a few times.

When the message is sent to the SkyWave gateway, you will see the Submit Date, Submit Time, and Error columns change (Figure 12).

When the message is transmitted you will see the State and State Time columns change. Figure 12 Forward Message States – submitted and transmitted 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 8

Figure 13 Return Message

By sending and receiving messages, we have verified that to end-to-end messaging through Message Service is working.

2.4 Define a Custom Poll Message In this section, you will define and use a custom poll message. See section 4 for additional information about DMR Message Designer.

1. Install the SkyWave Developer’s Toolkit (SDK) on your PC if not already installed. See [R1 or R4] for instructions.

2. Launch DMR Message Designer from the Start menu on the PC by clicking SkyWave Developers Toolkit>Applications>DMR Message Designer. The DMR Message Designer window appears.

3. Click File>Open from the menu. You will need to locate the StandardPoll.dmd file in the DMRMessageDesigner folder installed with the SDK (Figure 14). Select StandardPoll.dmd and then click Open. A list of Standard Poll messages appears (Figure 15).

Figure 14 Standard Poll File Location

StandardPoll.dmd file in this folder


S5, Version 02 9

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

• heading with an emphasis on precision for the location.

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 10

Figure 15 Standard Poll B Message Details

6. Click Edit>Add New Poll from the menu.

A message named New Poll appears at the end of the poll list (Figure 16).

7. Click Latitude under the Poll B heading, drag and drop it on the New Poll message. Repeat this for the Longitude field (Figure 16).

Note: Dragging these fields moves them from Standard Poll messages. This does not matter because we will delete the Standard Poll messages before we save the file. If you want to copy rather than move fields, you can hold down the <CTRL> key while dropping, just like copying files in explorer. You may also use Edit >Copy and Edit >Paste from the menu items instead of drag-drop to duplicate fields (you may NOT use the <CTRL> X, <CTRL> C, and <CTRL> V keys).

Number of bits assigned to the

field


S5, Version 02 11

Figure 16 New Custom Poll Message

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

Larger message size

New poll number


S5, Version 02 12

stations. Also select this option to increase IsatM2M payloads to 192 bits (must also have Extended burst under the Satellite Payload Size selected).

• Decrease the size of one or more fields in the message.

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.

Use this to increase the payload size for

D+ or IsatM2M

Use this for extended payload

messages with IsatM2M service


S5, Version 02 13

Figure 18 Changing the Size of a Custom Poll Message

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: Do not save to the same file name as “StandardPoll” since this will overwrite your Standard Poll messages.

Change the Size field and the

Divisor field values

The Multiplier field value should match


S5, Version 02 14

Figure 19 Renamed Custom Poll Message

2.6 Import a Custom Poll Message Definition Once we have created our new custom poll message we need to communicate the definition to the SkyWave terminal and the Message Service so that both know how to pack and unpack the messages.

1. Launch Message Manager from the Start menu on the PC by clicking SkyWave Developers Toolkit>Applications>Message Manager. The Message Manager notification window appears.

2. Click File>Import Message Definitions, select the .dmd custom poll message you just created then click Open (Figure 20).

This will import the file and create a new database table called Custom Poll with the appropriate columns to store the data.


S5, Version 02 15

Figure 20 Select Your Custom Poll File

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 terminal’s non-volatile memory.

2.7 Send a Custom Poll Message Request 1. Launch Message Manager from the Start menu on the PC by clicking SkyWave

Developers Toolkit>Applications> Message Manager. The Message Manager main window appears.

2. Click View >Forward Messages. 3. Click New and enter the terminal ID of the SkyWave terminal control station where

you wish to send the poll request.


S5, Version 02

Figure 21 New Message main window

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 17

3 Message Service and Message Manager

3.1 Administration

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


S5, Version 02 18

Figure 24 Event Log window

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

3.2 Database overview The messaging database tables and fields follow the design of messages and parameters used by the DAP protocol. Please see [N3] for more information.


S5, Version 02 19

3.3 Configuration tables

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

Message Service

configuration tables

DapTerminal

DapGateway

DapControlStation

DapOption

DapCustomMessage

DapCustomField

forward message tables

DapDeliverNotification

DapSubmitMessage

return message tables

DapDeliverMessage

Poll Message Tables

User Application

SkyWave Versa gateway

Internet

Message Manager


S5, Version 02 20

Figure 26 Edit Gateways window

Field Description

ID Gateway unique identifier Enable True = use this gateway

False = do not use this gateway Name Comment field, ignored Address DNS host name or IP address Port TCP port number SSL True = port supports SSL

False = port does not support 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 Control station unique identifier Enable True = check this control station

False = do not check this control station Name Comment field, ignored Control Station The control station subscription ID is typically a string of

8 numeric characters. Password The password for the control station is typically a string

of 8 alpha characters. GatewayEnable01-12

Controls which gateways will be used when accessing this control station. By default, all gateways are enabled.


S5, Version 02 21

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

Retrieve return messages and notifications Selecting this option retrieves and displays all return messages and notifications.

Send forward messages Selecting this option automatically sends all forward messages in the queue.

Check for messages The interval, in seconds, between checking the satellite gateway for from-terminal messages and checking the database for to-terminal messages.

Send messages at up to <value> bytes/minute Limits the size of the messages submitted. The value is in bytes per minute. The size of each message is the number of payload bytes plus 6 for overhead. A zero, minimum value, means no limit. The maximum value is 52.

Field Description

PollInterval The interval between checking the satellite gateway for from-terminal messages, and checking the database for to-terminal messages (in seconds). The minimum interval is 15 seconds. Default value is 30.

DeliverEnable True = request delivery of from-terminal messages False = do not request delivery Default is true.

SubmitEnable True = submit forward messages False = do not submit messages Default is true.


S5, Version 02 22

Field Description

SubmitRate Limits the number of messages submitted to avoid saturating the forward message link. The value is in bytes per minute. The size of each message is the number of payload bytes plus 6 for overhead. A zero value means no limit. Default is 26.

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 Terminal unique identifier Enable True = use this terminal name

False = do not use this terminal name Name Comment field, ignored Terminal ID The terminal’s subscription ID

3.4 Return tables

3.4.1 DapDeliverMessage Table Message Server inserts into this table from-terminal messages.

Field Description

ID Received message unique identifier ControlStationID The control station subscription ID of the receiving

control station, typically a string of 8 numeric characters.

TerminalID The terminal subscription ID of the sending terminal, typically a string of 8 numeric characters.

ControlWord Provides 4 additional bits of payload data. DestinationAddress If multiple control stations are used, the destination


S5, Version 02 23

Field Description address is used to decide which control station receives the message. Otherwise, this field is free to be used to provide 8 additional bits of payload data.

MessageDescriptor 8 bits – xxyy yyyy xx = 00 – user message (yyyyyy is extra payload data) xx = 01 – user message (yyyyyy is extra payload data) xx = 10 – poll report (yyyyyy is poll number) xx = 11 – terminal message (yyyyy is class) See [T6 or T9] for more information.

UserData A string of hexadecimal digits containing the raw payload of the message.

ReplyRequested A bit set by the terminal indicating that an application-level reply is expected. This field can also be used to provide 1 more bit of payload data.

ReceivedTimestamp The time the message was received by the satellite (UTC).

MessageIdentifier A unique identifier for the message assigned by the Versa gateway.

Timestamp The time the message was retrieved from the Versa gateway (UTC).

Region The region from which the message was received: D+/IsatM2M – the ocean region (AORWGL, AOREGL, IORGL, PORGL, PACCGL) GPRS – the cellular service provider ID

3.4.2 Poll message tables 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 Identifier of the corresponding entry in the DapDeliverMessage table.

<field 1> <field 2> … <field n>

Field names and types determined by the message definition file.

The message definition file StandardPoll.dmd defines the following fields:

Field Description

Alarm C State of script alarm 12 Alarm D State of script alarm 13 Alarm E State of script alarm 14


S5, Version 02 24

Field Description

Alarm F State of script alarm 15 Altitude Altitude in meters Battery1

Battery voltage in volts Battery status2

State of battery error flag Digital Input (1-4) State of digital input (1-4) Digital Output (1-2) State of digital output (1-2) Firmware Version Firmware version installed Flag 0 State of script flag 0 Flag 1 State of script flag 1 Hardware Hardware version of the board Heading Heading in degrees (0 to 359) Line (1-4) Type 0 – Digital input

1 – Analog input, voltage 2 – Analog input, current 4 – Digital output

Line (1-4) Invert 0 – Digital input not inverted 1 – Digital input inverted

Line (1-4) Output Digital output value Line (1-4) Input Digital or analog input value Latitude Latitude in degrees (-90 to 90) (91 indicates invalid fix) Longitude Longitude in degrees (-180 to 180) (181 indicates invalid fix) Operational mode Current operational mode (0 to 3) Reserved Unused bits Schedule Current active schedule (0 to 7) Speed Absolute speed in kilometers per hour Temperature Temperature in degrees Celsius Time of Day Number of minutes past midnight UTC (0 to 1439)

3.5 Forward tables

3.5.1 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 Submit message unique identifier

1 The DAPC API [S6] refers to battery as batteryVolts and battery delta as batteryVoltDiff 2 The DAPC API [S6] refers to battery status as batteryErrorFlag.


S5, Version 02 25

Field Description

TerminalID The terminal subscription ID of the recipient terminal.

ControlStationID The control station subscription ID of the sending control station.

ControlStationAuthenticationCode The control station password of the sending control station.

MessageCategory 1 – command message (tone-only) 2 – numeric message 3 – alphanumeric message 4 – transparent message

Payload A string of hexadecimal digits containing the raw payload of the message.

MessageNumber NULL – automatically use the message number of the previous forward message sent to this terminal, plus one. Range 0 to 31 – explicitly set the message number

CommandCode Alert code. Range 0 to 3. InformationType 0 – External message (to external controller)

15 – Internal message (to terminal firmware) Priority 1 – low

2 – normal (default) 3 – high

ValidTime Time after which undelivered messages will be deleted.

NotificationRequested Set to true to request that notification messages be delivered.

DeferredDeliveryTime Time at which the message will be delivered. Transport NULL – Use any available (GPRS preferred)

0 – Use any available (GPRS preferred) 1 – Use Satellite only 2 – Use GPRS only

RepeatsCount Number of times the message should be transmitted.

RepeatInterval Interval in minutes between repeating message transmission.

Region Satellite ocean region to send the message (AORWGL, AOREGL, IORGL, PORGL, PACCGL)

TerminalAcknowledgementRequested Set to true to request that the terminal send an acknowledgment to indicate successful reception.

ResponseCode DAPC response code


S5, Version 02 26

Field Description

MessageIdentifier A unique identifier for the message assigned by the Versa gateway.

3.5.2 DapDeliverNotification Table The Message Service inserts the notification messages received into this table.

Field Description

ID Deliver Notification unique identifier ControlStationID The control station subscription ID of the control station

requesting the notification. TerminalID The terminal subscription ID of the recipient terminal. MessageDeliveryStatus New status of the message. DeliveryStatusTimestamp The time the status change. MessageNumber The message number as received by the terminal. MessageIdentifier The unique identifier for the message assigned by the Versa

gateway. Timestamp The time the notification was retrieved from the Versa

gateway (UTC).

3.6 Stored Procedures The Message Manager uses three stored procedures which can be also used by user applications, or as samples for how user applications can use the database. The procedures are:

p_GetFromTerminalMessages – returns records shown in Figure 12. p_GetToTerminalMessages – returns records shown in Figure 13. p_SendPollMessage – sample which demonstrates how to insert a poll request

Use Microsoft SQL Server Enterprise Manager to inspect the code to see what parameters are necessary for each stored procedure.


S5, Version 02 27

4 DMR Message Designer Message Designer is the desktop utility used to define the information sent by terminals.

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


S5, Version 02 28

Property Description

Poll Name Determines the name of poll message table Poll Number

0x00 to 0x1F reserved for standard poll messages 0x20 to 0x3F available for custom poll messages Two messages should not share the same poll number. The poll number determines which message definition to use when encoding or decoding poll messages.

Version If redefining an existing Custom Poll by sending an over-air command, increment the version number. The terminal will ignore the over-air command if it already has a defined Custom Poll with the same poll number and an equal or higher version.

Satellite Payload Size

Use this to set the size of your To-Terminal payload message. Extended burst (184 bits) is only available on SureLinx and DMR-800 terminals with IsatM2M service.

Destination Address

Determines the value stored in the destination address of the message. The destination address normally selects which control station will receive the message. If only a single control station exists, the destination address is not needed and can be used to carry payload data.

Use default – destination address is determined by terminal parameter 0x15 (select this setting if 64 bits or fewer are needed in payload).

Use for extra payload space – destination address is considered part of the available payload space, increasing it from 64 bits to 72 bits. This option should only be used if there is only one destination address (normally a control station). IsatM2M service allows for payloads of up to 192 bits.

Set to <value> - sets the destination address to a particular value. This allows different control stations to receive different types of poll messages.

Queue Lifetime

Determines the maximum time that the poll message can be queued in the terminal waiting for transmission.

Use default – queue lifetime is determined by terminal parameter 0x4a (recommended setting)

Set to <value> – sets the queue lifetime to a particular number of seconds. Options Queue Priority – Determines the priority of the message in the transmit

queue. 0 is the lowest, 3 is highest. When multiple messages are waiting for transmission, the higher priority messages are sent before lower priority ones. Recommended setting is 0.

Set application response bit – another bit passed to the user application, not interpreted either by the terminal or by the gateway. May be used to indicate that the terminal expects the user application to respond, but may be used for another purpose.

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:


S5, Version 02 29

Figure 31 DMR Message Designer Fields


Field Name Determines the name of the field in the poll message table Units Indicates the base units for the field (i.e. km/h, degrees, and volts).

This is an optional comment field. Encode Size Number of bits occupied by the field in the payload. To pack the

most data possible into a message, it is important to allocate the minimum number of bits required by each field. The total number of bits occupied by the message is shown in the status bar of the DMR Message Designer.

Module The module ID from which to read data. See API Port Access in [T6 and T9].

Poll report fields


S5, Version 02 30


Port The port index from which to read data. See Terminal API Port Definitions in [T6 and T9].

Divisor Refer to 4.1.3

Use Signed Arithmetic

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

Limit to Max or Min Value

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 vehicle’s 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.

Round Value 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.

Decode Type The data type of the database field:

discard (0 bits) – do not create database field bit (1 bit) – (0, 1) tinyint (8 bits) – (0 to 255) smallint (16 bits) – (-32,768 to 32,767) int (32 bits) – (-2,147,483,648 to 2,147,483,647) bigint (64 bits) – (-9223372036854775808 to 9223372036854775807) decimal (see Precision property) float (approximation)

Precision Total number of digits used for decimal data type. Scale Number of digits to the right of the decimal point for the decimal

data type Multiplier Refer to 4.1.3

Divisor Refer to 4.1.3

Offset Refer to 4.1.3


S5, Version 02 31

4.1.3 Field property calculation 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:

Value

Encode divisor + Round( ) • Round Multiplier + Round Offset

Payload

scale data and pack into assigned bits

Database

Decode multiplier Decode divisor

Field 1 Field 2 Field 3 Field 4

Field 1 Field 2 Field 3 Field 4

Value •

send message over satellite

scale data and store fields in database

Module n

Port 0 Port 1

Port 2 Port 3

get data from Terminal module

+ Decode Offset


S5, Version 02 32

Document Versions Version Date Description

Rev A Feb 14, 2003 Initial release Rev B July 8, 2003 Post-beta update 1.0 Aug 25, 2004 Applied new template 1.1 Sept 15, 2004 Update for XML support 1.2 Feb 10, 2005 Moved Standard Poll Message

Definitions cross reference table to [T6 or T9]. Minor fixes.

1.3 Sept 21, 2005 Minor fixes. 1.4 December 20,

2006 Update for Message Manager and Message Service version 2.1

02 Jan 2008 See the What’s New section.


S5, Version 02 33

Index 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

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 Developer’s Toolkit (SDK)......... i StandardPoll.dmd ....................................... 8 stored procedures...................................... 26 to terminal tables ...................................... 24 type - Message Designer........................... 30 units - Message Designer.......................... 29

www.SkyWave.com

Date post:	31-Jan-2016
Category:	Documents
Upload:	henry
View:	7 times
Download:	0 times

S5 Messaging Software Tools

Documents