You are on page 1of 130

SAT-200/202 SCRIPTING API AND COMMAND INTERFACE

Document No: GDN-0559

Issue: 1

Copy No: .................

Date: .................

SAT-200/202 SCRIPTING API AND


COMMAND INTERFACE
Project: PRN-0090

Date: 11 May 2009

Amendment Record
Issue Description Date Implemented By Approved By
1 Initial Issue 22nd April 2009 John Hatherall John Hatherall
2
3
[This document complies fully with the Design Inputs referenced within]

Typing Reference: JRH

Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

COPYRIGHT
Copyright in this document is vested in Satamatics Ltd. This document is issued in confidence for the
purpose only for which it is supplied. It must not be reproduced in whole or in part except with the
consent in writing of Satamatics Ltd and then only on the condition that this notice is included in any
such reproduction. No information as to the contents or subject matter of this document or any part
thereof arising directly or indirectly therefrom shall be given orally or in writing or communicated in
any manner whatsoever to any third party being an individual firm or company or any employee
thereof without the prior consent in writing of Satamatics Ltd.

© Satamatics Ltd Page i of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

CONTENTS

1 INTRODUCTION........................................................................................................................ 1
2 TERMINAL DETAILS ............................................................................................................... 2
2.1 Processors .............................................................................................................................. 2
2.2 Physical Interface .................................................................................................................. 2
3 PROGRAMMING MODEL ....................................................................................................... 3
4 SCRIPTING OVERVIEW .......................................................................................................... 4
5 SCRIPTING MODULES AND REGISTERS ........................................................................... 5
5.1 Functional Modules ............................................................................................................... 5
5.2 Registers ................................................................................................................................ 6
5.2.1 Configuration Module Registers................................................................................... 7
5.2.2 Timer Module Registers ............................................................................................... 8
5.2.3 Alarm Module Registers ............................................................................................. 10
5.2.4 Interface Module Registers ......................................................................................... 12
5.2.5 GPS Module Registers................................................................................................ 13
5.2.6 Messaging Module Registers...................................................................................... 14
5.2.7 Scratchpad Module Registers ..................................................................................... 15
5.2.8 Operation Configuration Registers ............................................................................. 16
5.2.9 Constant Generator Registers ..................................................................................... 17
5.3 Configuration Module ......................................................................................................... 18
5.3.1 Ocean Region Selection Register................................................................................ 18
5.3.2 Service ID Selection Register ..................................................................................... 18
5.3.3 Satellite Selection Mode ............................................................................................. 19
5.3.3.1 Auto Select on Start Up.......................................................................................... 19
5.3.3.2 Follow Best Satellite Operation.............................................................................. 19
5.3.3.3 Switch On Satellite Loss ........................................................................................ 19
5.3.4 Power Control Register............................................................................................... 20
5.3.5 DSP Firmware Version Number................................................................................. 21
5.3.6 MSP Firmware Version Number ................................................................................ 21
5.3.7 Application Script Version Number ........................................................................... 21
5.3.8 Store Application Script.............................................................................................. 21
5.3.9 Delete Application Script............................................................................................ 21
5.3.10 Power Supply Status ................................................................................................... 21
5.3.11 NMEA Message Output.............................................................................................. 22
5.3.12 Slotted Receive Mode Register................................................................................... 22
5.3.13 Slotted Receive Mode Maximum Acquisition Retries ............................................... 22
5.3.14 ISN, & PSN................................................................................................................. 23
5.3.15 Hardware Version ....................................................................................................... 23
5.3.16 Group PID................................................................................................................... 23
5.3.17 Service ID / Beam ID.................................................................................................. 23
5.3.18 Operational Flags........................................................................................................ 23
5.3.19 Terminal Mobility....................................................................................................... 23
5.3.20 PACC Enable.............................................................................................................. 23
5.3.21 GEM Compatibility Enable ........................................................................................ 24
5.3.22 Terminal Reset............................................................................................................ 24
5.3.23 Scripting Capabilities.................................................................................................. 24
5.4 Timer Module...................................................................................................................... 25
5.4.1 Timer Functionality .................................................................................................... 25
5.4.1.1 Updating Timer Trigger Values ............................................................................. 25
5.4.2 Timer Count Register.................................................................................................. 25
5.4.3 Timer Configuration Register ..................................................................................... 25

© Satamatics Ltd Page ii of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.4.3.1 Enable ..................................................................................................................... 26


5.4.3.2 Repeat ..................................................................................................................... 26
5.4.3.3 Mode....................................................................................................................... 26
5.4.3.4 Operation Number .................................................................................................. 26
5.4.3.5 Terminal Count Value ............................................................................................ 26
5.4.4 Timer Control ............................................................................................................. 26
5.4.4.1 Stop Timers ............................................................................................................ 26
5.4.4.2 Start Timers ............................................................................................................ 26
5.4.4.3 Reset Timers........................................................................................................... 27
5.4.4.4 Restart Timers ........................................................................................................ 27
5.4.4.5 Combined Operation to Enable and Disable Timer Channels................................ 27
5.4.4.6 Combined Operation to Restart and Reset Timer Channels................................... 27
5.4.5 Mixed Timer/Alarm Operations ................................................................................. 27
5.4.5.1 Mixed Operation to Enable Timer and Alarm Channels ........................................ 27
5.4.5.2 Mixed Operation to Disable Timer and Alarm Channels....................................... 27
5.4.5.3 Mixed Operation to Restart Timer and Alarm Channels........................................ 28
5.4.5.4 Mixed Operation to Reset Timer and Alarm Channels .......................................... 28
5.4.6 Real Time Functionality ............................................................................................. 28
5.4.6.1 Seconds Past Midnight ........................................................................................... 28
5.4.6.2 Time and Date ........................................................................................................ 28
5.5 Alarm Module ..................................................................................................................... 29
5.5.1 Alarm Functionality .................................................................................................... 29
5.5.1.1 Updating Alarm Threshold Values......................................................................... 29
5.5.2 Alarm Control/Status .................................................................................................. 29
5.5.3 Alarm Configuration................................................................................................... 30
5.5.3.1 Enable ..................................................................................................................... 30
5.5.3.2 Latch Mode............................................................................................................. 30
5.5.3.3 Auto Latch Release................................................................................................. 30
5.5.3.4 Operation Number .................................................................................................. 30
5.5.3.5 Comparison Mode .................................................................................................. 31
5.5.3.6 Target Register ID .................................................................................................. 31
5.5.4 Alarm Threshold ......................................................................................................... 31
5.5.5 Alarm Control ............................................................................................................. 31
5.5.5.1 Disable Alarms ....................................................................................................... 31
5.5.5.2 Enable Alarms ........................................................................................................ 31
5.5.5.3 Reset Alarms .......................................................................................................... 32
5.5.5.4 Trigger Alarms ....................................................................................................... 32
5.5.5.5 Toggle Alarms ........................................................................................................ 32
5.5.5.6 Restart Alarms ........................................................................................................ 32
5.5.5.7 Combined Operation to Enable and Disable Alarm Channels ............................... 32
5.6 Interface Module ................................................................................................................. 33
5.6.1 I/O Configuration Register ......................................................................................... 33
5.6.2 Analogue Inputs.......................................................................................................... 34
5.6.3 Digital Inputs .............................................................................................................. 34
5.6.4 Digital Outputs............................................................................................................ 35
5.6.5 Processor Supply Voltage ........................................................................................... 35
5.6.6 External Supply Voltage............................................................................................. 35
5.6.7 GEM-100 Battery Supply Voltage.............................................................................. 35
5.6.8 Device Temperature.................................................................................................... 36
5.6.9 Calibrated Temperature .............................................................................................. 36
5.6.10 GEM-100 Battery Temperature .................................................................................. 36
5.6.11 GEM-100 Battery Power Output ................................................................................ 36
5.6.12 GEM-100 User LED State .......................................................................................... 36

© Satamatics Ltd Page iii of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.7 GPS Module ........................................................................................................................ 37


5.7.1 Current Position .......................................................................................................... 37
5.7.1.1 Status ...................................................................................................................... 37
5.7.1.2 Latitude................................................................................................................... 37
5.7.1.3 Longitude................................................................................................................ 37
5.7.1.4 Speed ...................................................................................................................... 37
5.7.1.5 Heading .................................................................................................................. 37
5.7.1.6 Altitude ................................................................................................................... 38
5.7.1.7 Horizontal Dilution of Precision (HDOP) .............................................................. 38
5.7.2 Reference Position ...................................................................................................... 38
5.7.2.1 Store Current Position as Reference....................................................................... 38
5.7.2.2 Reference Latitude.................................................................................................. 38
5.7.2.3 Reference Longitude .............................................................................................. 38
5.7.2.4 Distance from Reference ........................................................................................ 38
5.7.3 Target Positions .......................................................................................................... 38
5.7.3.1 Distance from Target .............................................................................................. 38
5.7.3.2 Distance to Closest Target...................................................................................... 39
5.7.3.3 Distance to the Farthest Away Target .................................................................... 39
5.7.3.4 Target Latitude ....................................................................................................... 39
5.7.3.5 Target Longitude .................................................................................................... 39
5.7.4 NMEA registers .......................................................................................................... 39
5.7.5 Last GPS fix................................................................................................................ 39
5.7.6 Geofence ..................................................................................................................... 39
5.7.6.1 Geofence Status ...................................................................................................... 39
5.8 Messaging Module .............................................................................................................. 40
5.8.1 Return Burst Message ID Register ............................................................................. 40
5.8.1.1 Creating User Defined Messages ........................................................................... 41
5.8.2 Return Burst Destination Address Register ................................................................ 41
5.8.3 Combined Control Word and Destination Address .................................................... 41
5.8.4 Return Burst Acknowledge Flags ............................................................................... 41
5.8.5 Return Burst Control Flags ......................................................................................... 41
5.8.6 Return Channel Message Scrambling Vector ............................................................. 41
5.8.7 Terminal Receiver Status Registers ............................................................................ 42
5.8.7.1 Receiver Channel Number ..................................................................................... 42
5.8.7.2 Receiver Signal Quality.......................................................................................... 42
5.8.7.3 Receiver Status ....................................................................................................... 42
5.8.8 Terminal Transmitter Status Register ......................................................................... 42
5.8.9 Transmit Randomisation Period ................................................................................. 43
5.8.10 Transmit Retries.......................................................................................................... 44
5.8.11 Receive Signal Level .................................................................................................. 44
5.8.12 Receive Frequency Offset........................................................................................... 44
5.8.13 Receive Rate of Change Frequency............................................................................ 44
5.8.14 Receive Symbol Errors ............................................................................................... 44
5.8.15 Number of Messages in the Transmit Queue.............................................................. 44
5.8.16 Transmit Queue Configuration ................................................................................... 44
5.8.17 Poll Message Control Registers .................................................................................. 44
5.8.17.1 Poll Message ID ..................................................................................................... 45
5.8.17.2 Poll Message Repeat Rate ...................................................................................... 45
5.8.18 Tone Only Message Response Registers .................................................................... 45
5.8.19 Forward Channel Message Output Mode Register ..................................................... 45
5.9 Scratchpad Module.............................................................................................................. 46
5.9.1 Scratchpad Register Special Functions....................................................................... 46
5.9.1.1 Scratchpad Register 0 ............................................................................................. 46

© Satamatics Ltd Page iv of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.9.1.2 Scratchpad Registers 1 and 2.................................................................................. 46


5.10 Operations Module .............................................................................................................. 47
5.10.1 Operation Definitions ................................................................................................. 47
5.10.2 Operation Configuration Register............................................................................... 47
5.10.2.1 Operation Enable .................................................................................................... 47
5.10.2.2 Operation Chaining ................................................................................................ 47
5.10.2.3 Operation Function Codes...................................................................................... 48
5.10.2.4 Update Stored Script............................................................................................... 48
5.10.2.5 Do Not Update Running Script .............................................................................. 48
5.10.2.6 Target Register ID .................................................................................................. 49
5.10.3 Operation Value Register............................................................................................ 49
5.10.4 Disable Operations...................................................................................................... 49
5.10.5 Enable Operations....................................................................................................... 49
5.10.6 Reset Operations ......................................................................................................... 49
5.10.7 Trigger Operations...................................................................................................... 49
5.11 Constant Generator Module................................................................................................. 50
6 OVER AIR REMOTE CONTROL .......................................................................................... 51
6.1 Trigger Operation Message ................................................................................................. 51
6.2 Remote Terminal Poll.......................................................................................................... 51
6.3 Remote Digital Output Control ........................................................................................... 52
6.4 Set Target Position .............................................................................................................. 52
6.5 Read/Write Terminal Register............................................................................................. 53
6.6 Return ‘Read Register’ Message Format............................................................................. 54
7 SERIAL COMMAND INTERFACE ....................................................................................... 55
7.1 Command & Response Formats .......................................................................................... 55
7.1.1 Command format ........................................................................................................ 55
7.1.2 Response Format......................................................................................................... 55
7.2 Command Availability ........................................................................................................ 56
7.3 Terminal Configuration Module Commands....................................................................... 57
7.3.1 CA – Get/Set the Terminal Satellite Selection Mode ................................................. 57
7.3.2 CB – Select Ocean Region.......................................................................................... 57
7.3.3 CE – Get/Set the Terminal Power Control State......................................................... 57
7.3.4 CF –Set the Terminal to Factory Defaults .................................................................. 58
7.3.5 CI – Get/Set the Service ID Selection......................................................................... 58
7.3.6 CN – NMEA Message Output Control....................................................................... 58
7.3.7 CP – Get MSP Firmware Version............................................................................... 59
7.3.8 CR – Reload Terminal Application Script.................................................................. 59
7.3.9 CS – Get/Set Application Script Software Version .................................................... 59
7.3.10 CU – Get/Set Operating Power Mode ........................................................................ 59
7.3.11 CV – Get DSP Software Version................................................................................ 60
7.3.12 CW – Wipe Script Software ....................................................................................... 60
7.3.13 CZ – Store Script in Non-Volatile Memory................................................................ 60
7.4 Interface Module Commands .............................................................................................. 61
7.4.1 IA – Get Analogue Input ............................................................................................ 61
7.4.2 IC – Configure Inputs/Outputs.................................................................................... 61
7.4.3 ID – Get Digital Inputs ............................................................................................... 62
7.4.4 IE – Get/Set Digital Outputs ....................................................................................... 62
7.4.5 II – Get GEM-100 External Power Supply Status ...................................................... 62
7.4.6 IP – Get MSP Power Supply Level............................................................................. 63
7.4.7 IO – Configure GEM-100 Battery Power Output....................................................... 63
7.4.8 IQ – Get GEM-100 Battery Temperature ................................................................... 63
7.4.9 IS – Get External Power Supply Level ....................................................................... 63
7.4.10 IT – Get Terminal Temperature.................................................................................. 64

© Satamatics Ltd Page v of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.4.11 IU – Get/SET GEM-100 User LED State................................................................... 64


7.4.12 IX – Get GEM-100 Battery Power Supply Level ....................................................... 64
7.5 Timer Module Commands................................................................................................... 65
7.5.1 TC – Configure Timer ................................................................................................ 65
7.5.2 TD – Disable Timers................................................................................................... 65
7.5.3 TE – Enable Timers .................................................................................................... 65
7.5.4 TM – Get/Set Timer Trigger Value ............................................................................ 65
7.5.5 TR – Reset Timers ...................................................................................................... 66
7.5.6 TS – Restart Timers .................................................................................................... 66
7.5.7 TT – Get Current Time and Date (UTC) .................................................................... 66
7.5.8 TV – Get Current Timer Value................................................................................... 67
7.6 Alarm Module Commands .................................................................................................. 68
7.6.1 AC – Configure Alarms .............................................................................................. 68
7.6.2 AD – Disable Alarms.................................................................................................. 68
7.6.3 AE – Enable Alarms ................................................................................................... 68
7.6.4 AF – Trigger Alarms................................................................................................... 69
7.6.5 AR – Reset Alarms ..................................................................................................... 69
7.6.6 AT – Alarm Threshold................................................................................................ 69
7.7 Operation Module Commands............................................................................................. 70
7.7.1 OC – Configure Operation.......................................................................................... 70
7.7.2 OD – Disable Operations ............................................................................................ 70
7.7.3 OE – Enable Operations ............................................................................................. 71
7.7.4 OR – Reset Operations ............................................................................................... 71
7.7.5 OT – Trigger Operations............................................................................................. 71
7.8 GPS Module Commands ..................................................................................................... 72
7.8.1 GPS Status and Configuration Commands ................................................................. 72
7.8.1.1 GM – Get GPS Satellite Signal Strengths .............................................................. 72
7.8.1.2 GS – Get GPS Status .............................................................................................. 72
7.8.1.3 GE – Get GPS Software Version Number.............................................................. 72
7.8.2 GPS Position Commands............................................................................................ 73
7.8.2.1 GA – Get Current GPS Altitude ............................................................................. 73
7.8.2.2 GH – Get Current GPS Heading............................................................................. 73
7.8.2.3 GP – Get Current GPS Position.............................................................................. 73
7.8.2.4 GV – Get Current GPS Speed ................................................................................ 74
7.8.3 Geofence Commands .................................................................................................. 74
7.8.3.1 GD – Define Geofence ........................................................................................... 74
7.8.3.2 GF – Define Geofence Point .................................................................................. 74
7.8.3.3 GW – Store Geofence Data .................................................................................... 75
7.8.3.4 GZ – Define Geofence Zone .................................................................................. 75
7.8.4 Reference Position Commands ................................................................................... 76
7.8.4.1 GL – Distance to Reference.................................................................................... 76
7.8.4.2 GR – Define Reference Point ................................................................................. 76
7.8.4.3 GX – Store Current Position as Reference ............................................................. 76
7.8.5 Target Position Commands......................................................................................... 77
7.8.5.1 GK – Distance to Target Position........................................................................... 77
7.8.5.2 GT – Define Target Position .................................................................................. 77
7.8.6 Logging Commands.................................................................................................... 78
7.8.6.1 GI – Set GPS Logging Interval............................................................................... 79
7.8.6.2 LN – Get Number of Logged Positions.................................................................. 80
7.8.6.3 LR – Get Logged Record ....................................................................................... 80
7.9 Messaging Module Commands ........................................................................................... 82
7.9.1 Forward Channel Message Handling.......................................................................... 82
7.9.1.1 Forward Channel Message Buffering..................................................................... 82

© Satamatics Ltd Page vi of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.9.1.2 MC–Get Number of Forward Messages Buffered.................................................. 82


7.9.1.3 mf – Forward Channel Message Data .................................................................... 82
7.9.1.4 MN – Get Next Forward Message from the Buffer................................................ 83
7.9.1.5 MO – Configure Forward Channel Message Output.............................................. 83
7.9.2 Return Channel Messaging ......................................................................................... 84
7.9.2.1 MA – Get/Set Return Message Destination Address ............................................. 84
7.9.2.2 MB – Transmit a Return Message.......................................................................... 84
7.9.2.3 MK – Get/Set Return Message Acknowledge Flags .............................................. 84
7.9.2.4 ML – Get/Set Return Message Control Flags Field ............................................... 85
7.9.2.5 MM – Transmit Return Message............................................................................ 85
7.9.2.6 MP – Configure Automatic Poll............................................................................. 85
7.9.2.7 MQ – Get/Set Response to a Tone only Message .................................................. 86
7.9.2.8 MR – Report Receiver Status ................................................................................. 86
7.9.2.9 MS – Get/Set Return Message Transmission Slot Randomisation ........................ 86
7.9.2.10 MT – Report Transmitter Status............................................................................. 87
7.10 Scratchpad Module Commands........................................................................................... 87
7.10.1 SR – Read/Set Register............................................................................................... 87
7.11 Register Direct Access Commands ..................................................................................... 88
7.11.1 RR – Read Register..................................................................................................... 88
7.11.2 RW – Write Register................................................................................................... 88
7.12 User Return Message Definition Commands ...................................................................... 89
7.12.1 BD – Define Message Number ................................................................................... 89
7.12.2 BF – Define Field Contents ........................................................................................ 89
7.12.3 BI – Initialise User Message Database ....................................................................... 89
7.12.4 BN – Get Number of Message Definitions................................................................. 89
7.12.5 BQ – Get Message Definition..................................................................................... 90
7.12.6 BW – Close Message Database .................................................................................. 90
7.13 Terminal System Commands............................................................................................... 91
7.13.1 Firmware Upload ........................................................................................................ 91
7.13.1.1 PD – Program Upload ............................................................................................ 91
7.13.1.2 pa – Program Record Acknowledge....................................................................... 91
7.13.1.3 pn – Program Record NAK .................................................................................... 92
7.13.2 PI – Reset .................................................................................................................... 92
7.13.3 PR – Configure Serial Port Baud Rate........................................................................ 92
7.13.4 PS – Scripting Enable/Disable .................................................................................... 93
7.13.5 PT – Run Production Tests ......................................................................................... 93
7.13.6 PV – Report Bootloader Version ................................................................................ 93
7.13.7 PY – Report MSP Software Information .................................................................... 93
7.13.8 PZ – Report Unit Serial Number ................................................................................ 94
7.14 Inmarsat-D Network Configuration Commands ................................................................. 95
7.14.1 DS PY – Report DSP Software Information............................................................... 95
7.14.2 DS PW – Enter Access Password ............................................................................... 95
7.14.3 DS TA – Get/Set Service ID (SID)............................................................................. 95
7.14.4 DS TC – Get/Set Pager Subset Number (PSN)........................................................... 96
7.14.5 DS TE – Get/Set Beam ID .......................................................................................... 96
7.14.6 DS TG – Get/Set the Group PID’s.............................................................................. 96
7.14.7 DS TJ – Get Configured Service IDs.......................................................................... 97
7.14.8 DS TK – Get/Set the Number of RC Transmission Retries........................................ 97
7.14.9 DS TM – Get/Set the Terminal Mobility.................................................................... 97
7.14.10 DS TN – Get the Terminal ISN .................................................................................. 98
7.14.11 DS TO – Get/Set the Operational Flags...................................................................... 98
7.14.12 DS TR – Report Receiver Status ................................................................................ 98
7.14.13 DS TS – Report Signal Status..................................................................................... 99

© Satamatics Ltd Page vii of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.14.14 DS TT – Report Transmitter Status .......................................................................... 100


7.14.15 DS TW – Return Channel Transmission Queue Write Function.............................. 101
7.14.16 DS TZ –Write/Restore Configuration to/from Non-Volatile Memory ..................... 101
7.15 NMEA Input/Output Messages ......................................................................................... 103
7.16 Script Debugging Messages .............................................................................................. 105
7.16.1 za - Alarm Trigger Message ..................................................................................... 105
7.16.2 zo – Operation Chain Message ................................................................................. 105
7.16.3 zt – Timer Trigger Message...................................................................................... 105
7.17 Error Messages .................................................................................................................. 106
7.18 Command Summary .......................................................................................................... 108
A APPENDIX A – EXAMPLE GEOFENCE DEFINITION...................................................A-1
A.1 Introduction .......................................................................................................................A-1
A.2 Definition...........................................................................................................................A-1
A.3 Geofence Constraints.........................................................................................................A-2
A.4 Geofence Definition Sequence ..........................................................................................A-2
A.5 Example Geofence Definition ...........................................................................................A-3
B APPENDIX B – EXAMPLE USER MESSAGE DEFINITION .......................................... B-1
B.1 Message Number Definition.............................................................................................. B-1
B.2 Message Field Data Selection............................................................................................ B-1
B.3 Message Definition Rules.................................................................................................. B-1
B.4 Message Definition Commands......................................................................................... B-2
B.5 Programming Command Sequence ................................................................................... B-2
B.6 Example - Time Stamped Analogue Input Report ............................................................ B-2
C APPENDIX C – NOTES FOR USERS MIGRATING FROM THE SAT-201 SERIES. ..C-4

© Satamatics Ltd Page viii of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

TABLES
Table 1 – Terminal Module ID Codes .................................................................................................... 5
Table 2 – Configuration Module Registers............................................................................................. 7
Table 3 – Timer Module Registers ......................................................................................................... 9
Table 4 – Alarms Module Registers ..................................................................................................... 11
Table 5 – Interface Module Registers ................................................................................................... 12
Table 6 – GPS Module Registers.......................................................................................................... 13
Table 7 – Messaging Module Registers................................................................................................ 14
Table 8 – Scratchpad Module Registers ............................................................................................... 15
Table 9 – Operations Module Registers................................................................................................ 16
Table 10 – Constant Generators............................................................................................................ 17
Table 11 – Bulletin Board Selection Codes .......................................................................................... 18
Table 12 – Terminal Satellite Selection Mode Control Word .............................................................. 19
Table 13 – Power Control Register Bit Definitions ..............................................................................20
Table 14 – Register Bits Modified to Switch Terminal Operating Modes ........................................... 20
Table 15 – Power Supply Status Bit Definitions .................................................................................. 21
Table 16 – NMEA Message Enable Bits .............................................................................................. 22
Table 17 – Slotted Receive Mode Register Values............................................................................... 22
Table 18 - ISN Register Bit Allocation................................................................................................. 23
Table 19 – Timer Control Codes........................................................................................................... 25
Table 20 – Timer Configuration Register Field Definitions................................................................. 25
Table 21 – Alarm Control Codes .......................................................................................................... 29
Table 22 – Alarm Configuration Register Field Definitions ................................................................ 30
Table 23 – Alarm Comparison Mode Codes ........................................................................................ 31
Table 24 – Valid I/O Channel Configurations ...................................................................................... 33
Table 25 – I/O Pin Mode Configuration Codes .................................................................................... 34
Table 26 – User LED Colour Codes ..................................................................................................... 36
Table 27 – Latitude/Longitude Data Format......................................................................................... 37
Table 28 – Geofence Status Register .................................................................................................... 39
Table 29 – Return Message Type Numbers.......................................................................................... 41
Table 30 – Receiver Status Byte Fields ................................................................................................ 42
Table 31 – Transmitter Status Register Fields ...................................................................................... 43
Table 32 – Operation Configuration Register Field Definitions........................................................... 47
Table 33 – Operation Function Codes .................................................................................................. 48
Table 34 – Trigger Operation Forward Channel Message.................................................................... 51
Table 35 – Remote Poll Forward Channel Message............................................................................. 51
Table 36 - Remote Digital Output Control Forward Channel Message................................................ 52
Table 37 – Target Position Definition Message.................................................................................... 52
Table 38 – Remote Register Read/Write Message ............................................................................... 53
Table 39 – Example of Multiple Register Update Message Data Structure ......................................... 54
Table 40 – Return Burst Message Format ............................................................................................ 54
Table 41 – Operating Power Modes ..................................................................................................... 60
Table 42 - GPS data log record format ................................................................................................. 79
Table 43 - Forward Channel Message Header Format ......................................................................... 83
Table 44 – DS TO Operational Flags.................................................................................................... 98
Table 45 – DS TR Receiver Inhibit Status Codes.................................................................................99
Table 46 – DS TR Receiver Progress Codes ........................................................................................ 99
Table 47 – DS TR Terminal Error Codes ............................................................................................. 99
Table 48 – DS TT Transmit Progress ................................................................................................. 100
Table 49 – DS TT Transmit inhibit status........................................................................................... 101
Table 50 – NMEA RMC Sentence Format......................................................................................... 103
Table 51 – NMEA GGA Sentence Format ......................................................................................... 104

© Satamatics Ltd Page ix of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Table 52 – NMEA GSV Sentence Format.......................................................................................... 104


Table 53 – Terminal Error Report Codes............................................................................................ 107
Table 54 - Command Summary .......................................................................................................... 111
Table 55 – Example Message Definition ............................................................................................ B-3

REFERENCES
[1]. MAN-0048 SAT-200/202 Functional Manual
[2]. GDN-0051 Satamatics Application Message Registry
[3]. MAN-0012 Programming in TSL

© Satamatics Ltd Page x of x


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

1 INTRODUCTION
This document describes the application programming interface to the Satamatics SAT-202 series of
Inmarsat-D terminals and other Satamatics products that incorporate the Satamatics, Inmarsat Type
Approved, SAT-200 module. This document also applies to the SAT-202 series when used in
combination with the GEM-100 interface module.

The SAT-202 terminal comprises a SAT-200 module contained within a SAT-201 type enclosure.
The SAT-202 supersedes, and provides a plug in replacement for, the SAT-201/201i series of
terminals. Backwards compatibility with regards to functionality has been largely maintained, but
there are some differences as detailed in Appendix C – Notes for Users Migrating from the SAT-201
Series..

Two methods of programming or configuring the SAT-202 terminal are available:

• Using the terminals internal scripting engine. This method would be used if autonomous
operation is required.
• Using the serial communications interface to control the terminal. This method would be used
if the terminal is operated in conjunction with an external controller.

There is some commonality between these two methods but sections 4 and 5 of this document are
more relevant to the use of the scripting engine whereas section 7 focuses on external control.

© Satamatics Ltd Page 1 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

2 TERMINAL DETAILS
A full description of the terminal variants and their capabilities is given in the relevant user
manual. You are also advised to read the SAT-200 Functional Manual, Ref. [1], before using the
commands detailed in this document to program a terminal.

2.1 Processors
The SAT-200 module contains three processors each with certain dedicated functions. These are:

MSP – a low power microprocessor that runs all of the time that power is applied to the terminal.
This processor provides the overall control of the terminal enabling the other two processors as
required for correct terminal operation. The MSP provides the scripting engine and processes the
commands received over the serial port interface.

DSP – a digital signal processor that provides the INMARSAT-D modem functionality, i.e.
transmission and reception of messages between the terminal and the satellite.

GPS – a dedicated processor that receives and decodes the GPS satellite signals to provide the
position data used by the terminal.

These three processors are referred to as MSP, DSP and GPS throughout this document.

2.2 Physical Interface


The command serial interface to the terminal is configured as an RS-232, bi-directional, asynchronous
serial port operating at 9600 or, following an operator command, 4800 baud, 8 bit data, no parity and
1 stop bit. The interface comprises the two data lines and a signal ground. There are no modem
control lines (CTS, RTS…). There is no software flow control implemented on the interface.

Note: The serial port baud rate can be increased during a firmware upload (paragraph 7.13.1.1)

© Satamatics Ltd Page 2 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

3 PROGRAMMING MODEL
A script is a simple program that is interpreted by the ‘scripting engine’, implemented within the
MSP, to perform autonomous control of the terminal.

To run a script it must first be uploaded to the terminal via the serial interface. The uploaded script
file would normally comprise a “configuration” part and an “operating script” part. The configuration
part consists of standard terminal commands that perform a one-time configuration of those functions
within the terminal that are not accessible through the autonomous operation of the scripting engine.
The operating script is that part of the uploaded file that is interpreted by the scripting engine – i.e. it
is run within the terminal in a manner similar to a software program.

Figure 1 shows access to the terminal functionality and status information. All functions are
accessible via the serial interface whereas some functionality and information is not accessible to an
operating script. (Configuration functions not accessible to the operating part of a script can still be
included in the configuration part of the uploaded script file as explained above.)

INMARSAT-D Terminal

Functions and status


information inaccessible to
scripting engine

Terminal control and


monitoring
Serial port Access Serial Interface

Script accessible modules


and registers

Scripting engine

This document is structured as follows:

Section 5 – Details the scripting modules and registers and how these are interpreted by the
scripting engine.

Section 6 - Provides details of ‘over air’ remote control operation.

Section 7 – Provides details of the serial command interface including command syntax and
function. Most of these functional specific commands control/monitor the terminal
through indirect access of the scripting registers, however the RR & RW commands
(paragraph 7.11) provide direct access, and Satamatics advise, where possible, the use
of the RR & RW commands for control and monitoring.

© Satamatics Ltd Page 3 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

4 SCRIPTING OVERVIEW
For autonomous operation the terminal must be configured to perform actions (operations) in
response to events (alarms or timers).

Events are detected by monitoring values and status information, including that of user configurable
timers, held in the scripting registers. These values are compared with threshold or trigger values set
within the script and, if the comparison results in a trigger, then a number of response operations may
be performed.

The process of performing operations is controlled by the scripting engine. The terminal can be
considered to be running a script if at least one operations register (paragraph 5.10) has been
configured to perform an action in response to an event.

The terminal scripting functionality is provided by a set of functional modules that may be
programmed by a user to produce the required results. Each of the programmable modules has a set
of addressable registers that configure the module operation. The registers are addressable directly
through the RR & RW commands (paragraph 7.11), or indirectly via many of the other serial interface
commands listed in section 7.

Note: Satamatics advise the use of the RR & RW commands where possible. In any future
extensions, scripting registers will only be accessible via the RR & RW commands. The other
serial commands listed in section 7 are kept to maintain compatibility with legacy products.

Not all of the resources and functionality defined by the programming model is available on all
terminal variants. Functionality affected in this way is identified in this document. Any attempt to use
an unimplemented function will be ignored.

Determining the values to be written to the appropriate registers in order to realise an operational
script can be a lengthy and error prone process. Satamatics therefore provide a TSL (Terminal
Scripting Language) compiler, ref.[3], that enables users to write their script in a textual format and
environment more familiar to software programmers. Once written the script is compiled to produce a
file that comprises the serial commands (described in this document) that can then be sent to the
terminal to configure all the appropriate registers and functions.

© Satamatics Ltd Page 4 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5 SCRIPTING MODULES AND REGISTERS

5.1 Functional Modules


The functional modules provided are:

• Terminal Configuration Module


• Interface Module
• GPS Module
• Messaging Module
• Timer Module
• Alarms Module
• Operations Module
• Scratchpad Module
• Constant Generator Module

The functionality provided by each of the modules is described in sections 5.3 to 5.11.

The functional modules within the terminal each contain a number of registers. These are addressed
by concatenating their module and internal register addresses. The address is used to access the
registers either through the RR & RW commands (paragraph 7.11) or, if being accessed as part of a
script, through the Operations registers (paragraph 5.10.1).

The module addresses used within the terminal are listed in Table 1.

Module Name Module ID Number


Configuration 0x00
Timers 0x01
Alarms 0x02
Interfaces 0x03
GPS 0x04
Messaging 0x05
Scratchpad 0x06
Operations 0x07
Constant Generator 0x0F
Table 1 – Terminal Module ID Codes

© Satamatics Ltd Page 5 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2 Registers
Read/write access to the registers is indicated in the ‘Access’ column as follows:

R = Read only
W = Write only
R/W = Read and Write operation possible using the RR an RW commands respectively.
R/[W] = Register can be read using RR command but write access is achieved indirectly by
writing to another register or via a serial command other than RW.

Paragraph references are given for both the register description and, where applicable, the serial
command by which it can be accessed. It should be noted that all registers can be accessed by the RR
and/or RW commands (paragraph 7.11) and hence this reference is not listed. Some registers can only
be accessed via the RW/RR commands and in these cases no serial command reference is provided.

© Satamatics Ltd Page 6 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.1 Configuration Module Registers


Module 0x00
Register Size Access Function TSL Register Name Para ref.
(bits)
0x00 5 R/W Bulletin Board/Ocean Region OceanRegion 5.3.1, 7.3.2
0x01 3 R/W Service ID Selection SelectedServiceID 5.3.2, 7.3.5
0x02 16 R/W Satellite Selection Mode SatelliteSelectionMode 5.3.3, 7.3.1
0x03 9 R/W Power Control Register PowerControl 5.3.4, 7.3.3
0x04 32 R Notification Flags NotificationFlags
[Not yet available]
0x05 32 R DSP Firmware Version FirmwareVersionDSP 5.3.5, 7.3.11
0x06 32 R MSP Firmware Version FirmwareVersionMSP 5.3.6, 7.3.7
0x07 32 R/W Script Application Version ScriptVersion 5.3.7, 7.3.9
0x08 32 W Store Application Script StoreScript 5.3.8, 7.3.13
0x09 32 W Delete Application Script DeleteScript 5.3.9, 7.3.12
0x0A 2 R Power Supply Status PowerSupplyStatus 5.3.10, 7.4.5
0x10 8 R <Reserved>
: :
0x1F 8 R <Reserved>
0x20 8 R/W NMEA output control OutputNMEA 5.3.11, 7.3.6
0x30 8 R <Reserved>
: :
0x34 8 R <Reserved>
0x40 8 R/W Slotted Receive - Wakeup Period SlottedWakeupPeriod 5.3.12
0x41 8 R/W Slotted Receive - Max SlottedRetries 5.3.13
Acquisition Retries
0x50 32 R ISN & PSN ISN 5.3.14
0x51 8 R Hardware Version HardwareVersion 5.3.15
0x52 20 R/[W] GPID 0 GPID0 5.3.16
0x53 20 R/[W] GPID 1 GPID1
0x54 20 R/[W] GPID 2 GPID2
0x55 20 R/[W] GPID 3 GPID3
0x56 20 R/[W] GPID 4 GPID4
0x57 8 R/[W] SID/BID for Service 0 SID0 5.3.17
0x58 8 R/[W] SID/BID for Service 1 SID1
0x59 8 R/[W] SID/BID for Service 2 SID2
0x5A 8 R/[W] SID/BID for Service 3 SID3
0x5B 8 R/[W] SID/BID for Service 4 SID4
0x5C 24 R/[W] Operational Flags OperationalFlags 5.3.18, 7.14.11
0x5D 8 R/W Terminal Mobility TerminalMobility 5.3.19
0xFC 1 R/W PACC Enable PACCEnable 5.3.20
0xFD 1 R/W GEM-100 compatibility enable GEMEnable 5.3.21
0xFE 32 W Terminal reset TerminalReset 5.3.22
0xFF 32 R Scripting capabilities ScriptingCapabilities 5.3.23

Table 2 – Configuration Module Registers

© Satamatics Ltd Page 7 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.2 Timer Module Registers


Module 0x01
Register Size Access Function TSL Register Name Para Ref.
(bits)
R Timer 0 Count 5.4.2, 7.5.8
0x00 32 TimerCountCtrl0
W Timer 0 Control
R Timer 1 Count
0x01 32 TimerCountCtrl1
W Timer 1 Control
: : :
R Timer 14 Count
0x0E 32 TimerCountCtrl14
W Timer 14 Control
R Timer 15 Count
0x0F 32 TimerCountCtrl15
W Timer 15 Control
0x10 32 R/W Timer 0 Configuration TimerConfig0 5.4.3, 7.5.1
0x11 32 R/W Timer 1 Configuration TimerConfig1
: : :
0x1E 32 R/W Timer 14 Configuration TimerConfig14
0x1F 32 R/W Timer 15 Configuration TimerConfig15
0x20 32 W Stop timers designated by bitmap StopTimers 5.4.4.1
0x21 32 W Start timers designated by bitmap StartTimers 5.4.4.2
0x22 32 W Reset timers designated by bitmap ResetTimers 5.4.4.3, 7.5.5
0x23 32 W Restart timers designated by RestartTimers 5.4.4.4, 7.5.6
bitmap
0x28 32 W Enable/Disable Timers EnableDisableTimers 5.4.4.5, 7.5.2, 7.5.3
0x29 32 W Reset/Restart Timers ResetRestartTimers 5.4.4.6, 7.5.5, 7.5.6
0x2C 32 W Enable Timers & Alarms EnableTimersAlarms 5.4.5.1, 7.5.3, 7.6.3
0x2D 32 W Disable Timers & Alarms DisableTimersAlarms 5.4.5.2, 7.5.2, 7.6.2
0x2E 32 W Restart Timers & Alarms RestartTimersAlarms 5.4.5.3, 7.5.6
0x2F 32 W Reset Timers & Alarms ResetTimersAlarms 5.4.5.4, 7.5.5, 7.6.5
0x30 32 R Current UTC time in seconds past TimeUTC 5.4.6.1
midnight
0x32 12 R Current date: year, full year value DateYear 5.4.6.2, 7.5.7
0x33 4 R Current date: month (1..12) DateMonth
0x34 5 R Current date: day (1..31) DateDay
0x35 5 R Current time: hour (0..23) TimeHours
0x36 6 R Current time: minute (0..59) TimeMinutes
0x37 6 R Current time: second (0..59) TimeSeconds
0x40 32 R/W Timer 0 Terminal Count TerminalCount0 5.4.3.5, 7.5.4
0x41 32 R/W Timer 1 Terminal Count TerminalCount1
: : :
0x4E 32 R/W Timer 14 Terminal Count TerminalCount14
0x4F 32 R/W Timer 15 Terminal Count TerminalCount15
0x50 32 R/W UTC Resynchronisation Period UTCResyncPeriod
[Not available]

Continued on following page…

© Satamatics Ltd Page 8 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Register Size Access Function TSL Register Name Para Ref.


(bits)
R Timer 16 Count 5.4.2, 7.5.8
0x80 32 TimerCountCtrl16
W Timer 16 Control
R Timer 17 Count
0x81 32 TimerCountCtrl17
W Timer 17 Control
: : :
R Timer 30 Count
0x8E 32 TimerCountCtrl30
W Timer 30 Control
R Timer 31 Count
0x8F 32 TimerCountCtrl31
W Timer 31 Control
0x90 32 R/W Timer 16 Configuration TimerConfig16 5.4.3, 7.5.1
0x91 32 R/W Timer 17 Configuration TimerConfig17
: : :
0x9E 32 R/W Timer 30 Configuration TimerConfig30
0x9F 32 R/W Timer 31 Configuration TimerConfig31
0xA0 32 R/W Timer 16 Terminal Count TerminalCount16 5.4.3.5, 7.5.4
0xA1 32 R/W Timer 17 Terminal Count TerminalCount17
: : :
0xAE 32 R/W Timer 30 Terminal Count TerminalCount30
0xAF 32 R/W Timer 31 Terminal Count TerminalCount31

Table 3 – Timer Module Registers

© Satamatics Ltd Page 9 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.3 Alarm Module Registers


Module 0x02
Register Size Access Function TSL Register Name Para Ref.
(bits)
R Alarm 0 Status 5.5.2
0x00 32 AlarmStatusCtrl0
W Alarm 0 Control
R Alarm 1 Status
0x01 32 AlarmStatusCtrl1
W Alarm 1 Control
: : :
R Alarm 14 Status
0x0E 32 AlarmStatusCtrl14
W Alarm 14 Control
R Alarm 15 Status
0x0F 32 AlarmStatusCtrl15
W Alarm 15 Control
0x10 32 R/W Alarm 0 Configuration AlarmConfig0 5.5.3, 7.6.1
0x11 32 R/W Alarm 1 Configuration AlarmConfig1
: : :
0x1E 32 R/W Alarm 14 Configuration AlarmConfig14
0x1F 32 R/W Alarm 15 Configuration AlarmConfig15
0x20 32 R/W Alarm 0 Threshold AlarmThreshold0 5.5.4, 7.6.6
0x21 32 R/W Alarm 1 Threshold AlarmThreshold1
: :
0x2E 32 R/W Alarm 14 Threshold AlarmThreshold14
0x2F 32 R/W Alarm 15 Threshold AlarmThreshold15
0x30 32 W Disable Alarms designated by bitmap DisableAlarms 5.5.5.1, 7.6.2
0x31 32 W Enable Alarms designated by bitmap EnableAlarms 5.5.5.2, 7.6.3
0x32 32 W Reset Alarm Latches designated by ResetAlarms 5.5.5.3, 7.6.5
bitmap
0x33 32 W Trigger Alarms designated by bitmap TriggerAlarms 5.5.5.4, 7.6.4
0x34 32 W Toggle Alarm enable state ToggleAlarms 5.5.5.5
0x35 32 W Reset Latch and Enable Alarms RestartAlarms 5.5.5.6
designated by bitmap
0x38 32 W Enable/Disable Alarms designated EnableDisableAlarms 5.5.5.7
by bitmap

Continued on following page…

© Satamatics Ltd Page 10 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Register Size Access Function TSL Register Name Para Ref.


(bits)
R Alarm 16 Status 5.5.2
0x40 32 AlarmStatusCtr16
W Alarm 16 Control
R Alarm 17 Status
0x41 32 AlarmStatusCtr17
W Alarm 17 Control
: : :
R Alarm 30 Status
0x4E 32 AlarmStatusCtrl30
W Alarm 30 Control
R Alarm 31 Status
0x4F 32 AlarmStatusCtrl31
W Alarm 31 Control
0x50 32 R/W Alarm 16 Configuration AlarmConfig16 5.5.3, 7.6.1
0x51 32 R/W Alarm 17 Configuration AlarmConfig17
: : :
0x5E 32 R/W Alarm 30 Configuration AlarmConfig30
0x5F 32 R/W Alarm 31 Configuration AlarmConfig31
0x60 32 R/W Alarm 16 Threshold AlarmThreshold16 5.5.4, 7.6.6
0x61 32 R/W Alarm 17 Threshold AlarmThreshold17
: :
0x6E 32 R/W Alarm 30 Threshold AlarmThreshold30
0x6F 32 R/W Alarm 31 Threshold AlarmThreshold31

Table 4 – Alarms Module Registers

© Satamatics Ltd Page 11 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.4 Interface Module Registers


Module 0x03
Register Size Access Function TSL Register Name Para Ref.
(bits)
0x00 8 R Digital Input States DigitalInputs 5.6.3, 7.4.3
0x01 8 R/W Digital Output States DigitalOutputs 5.6.4, 7.4.4
0x02 32 R/W I/O Configuration IOConfiguration 5.6.1, 7.4.2
(Input/Output, Digital/Analogue)
0x03 1 R/W GEM-100 Battery output enable state 5.6.11, 7.4.7
0x10 12 R Analogue Input Channel 0 Conversion Result AnalogueInput0 5.6.2, 7.4.1
: : :
0x17 12 R Analogue Input Channel 7 Conversion Result AnalogueInput7
0x18 32 R Processor Supply Voltage ProcessorSupply 5.6.5, 7.4.6
0x19 32 R External Supply Voltage ExternalSupply 5.6.6, 7.4.9
0x1A 16 R Device Temperature ProcessorTemperature 5.6.8, 7.4.10
0x1B 32 R GEM-100 Battery Supply Voltage BatterySupply 5.6.7, 7.4.12
0x1C 16 R GEM-100 Battery Temperature BatteryTemperature 5.6.10, 7.4.8
0x1F 16 R/W Calibrated Temperature CalibratedTemperature 5.6.9
0x20 12 R/W Analogue Output Channel 0 Value AnalogueOutput0
[Not available]
: : :
0x27 12 R/W Analogue Output Channel 7 Value AnalogueOutput7
[Not available]
0x30 2 R/W GEM-100 User LED state GEMLED 5.6.12, 7.4.11

Table 5 – Interface Module Registers

© Satamatics Ltd Page 12 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.5 GPS Module Registers


Module 0x04
Address Size Access Function TSL Register Name Para Ref.
(bits)
0x00 1 R GPS Status Register GPSStatus 5.7.1.1, 7.8.1.2
0x01 32 R GPS Latitude Latitude 5.7.1.2, 7.8.2.3
0x02 32 R GPS Longitude Longitude 5.7.1.3, 7.8.2.3
0x03 16 R GPS Speed Speed 5.7.1.4, 7.8.2.4
0x04 16 R GPS Heading Heading 5.7.1.5, 7.8.2.2
0x05 16 R GPS Altitude Altitude 5.7.1.6, 7.8.2.1
0x08 16 R Horizontal Dilution of Precision HDOP 5.7.1.7
0x10 32 W Store Current as Reference StoreReference 5.7.2.1, 7.8.4.3
0x11 32 R/[W] Reference Latitude ReferenceLatitude 5.7.2.2, 7.8.4.2
0x12 32 R/[W] Reference Longitude ReferenceLongitude 5.7.2.3, 7.8.4.2
0x13 1 R/W Odometer function enable OdometerEnable
0x14 32 R Odometer accumulated distance OdometerDistance
0x15 - W Odometer reset OdometerReset
[Clears the Odometer accumulated
distance register]
0x20 32 R Distance to Reference DistanceToReference 5.7.2.4, 7.8.4.1
0x28 8 R Geofence 1 Status GeofenceStatus1 5.7.6.1
0x29 8 R Geofence 2 Status GeofenceStatus2 5.7.6.1
0x30 16 R/W GPS Update Rate UpdateGPS
[For SAT-200 products, the update rate is
fixed at 1 second. Writing to this register
has no effect]
0x38 32 R Distance to Closest Target DistanceToClosest 5.7.3.2
0x39 32 R Distance to Farthest Away Target DistanceToFurthest 5.7.3.3
0x40 32 R Distance to Target 0 DistanceToTarget0 5.7.3.1, 7.8.5.1
: : : : :
0x47 32 R Distance to Target 7 DistanceToTarget7
0x50 32 R/[W] Target 0 Latitude TargetLatitude0 5.7.3.4, 7.8.5.2
0x51 32 R/[W] Target 0 Longitude TargetLongitude0 5.7.3.5, 7.8.5.2
: : : : :
0x5E 32 R/[W] Target 7 Latitude TargetLatitude7 5.7.3.4, 7.8.5.2
0x5F 32 R/[W] Target 7 Longitude TargetLongitude7 5.7.3.5, 7.8.5.2
0x80 1 R NMEA Input Status Register NMEAStatus 7.15
0x81 32 R NMEA Input Latitude NMEALatitude
0x82 32 R NMEA Input Longitude NMEALongitude
0x83 16 R NMEA Input Speed NMEASpeed
0x84 16 R NMEA Input Heading NMEAHeading
0x85 16 R NMEA Input Altitude NMEAAltitude
0xF0 3 R Hours since last GPS fix HoursSinceLastFix 5.7.5
0xF1 17 R Time at last GPS fix TimeAtLastFix 5.7.5

Table 6 – GPS Module Registers

© Satamatics Ltd Page 13 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.6 Messaging Module Registers


Module 0x05
Address Size Access Function TSL Register Name Para Ref.
(bits)
0x10 8 W Return Burst Message ID Code ReturnBurstMessageID 5.8.1, 7.9.2.2
0x11 8 R/W Return Burst Destination Address ReturnBurstDestAddr or 5.8.2, 7.9.2.1
ReturnBurstCannedMessage
0x12 8 R/W <Reserved>
0x13 20 R/W Concatenated Registers 0x11:0x12 plus ReturnBurstRegisters 5.8.3
Control Flags
0x14 2 R/W Return Burst Acknowledge Flags ReturnBurstAckFlags 5.8.4, 7.9.2.3
0x15 4 R/W Return Burst Control Flags Field ReturnBurstCtrlFlags 5.8.5, 7.9.2.4
0x18 32 R/W Return message scrambling vector ScramblingVector 5.8.6
0x20 12 R Receive Channel Number ReceiveChannel 5.8.7.1,
7.9.2.8
0x21 12 R Receive Signal Quality ReceiveSignalLevel 5.8.7.2,
7.9.2.8
0x22 8 R Receive Status ReceiveStatus 5.8.7.3,
7.9.2.8
0x23 32 R Transmit Status TransmitStatus 5.8.8
7.9.2.10
0x24 8 R/W Transmit Randomisation Period TransmitRandomisation 5.8.9, 7.9.2.9
0x28 32 R/W Number of Transmit Retries TransmitRetries 5.8.10
0x29 32 R Receive Signal Level ReceiveSignal 5.8.11
0x2A 32 R Receive Frequency Offset ReceiveFrequencyOffset 5.8.12
0x2B 32 R Receive Doppler Rate of Change ReceiveDoppler 5.8.13
0x2C 32 R Receive Symbol Errors ReceiveSymbolErrors 5.8.14
0x2D 32 R Number of Messages in Transmit Queue TransmitQueue 5.8.15
0x2E 32 R Transmit Queue Configuration TransmitQueueConfig 5.8.16
0x30 8 R/W Poll Message ID code PollMessageID 5.8.17.1,
7.9.2.6
0x31 16 R/W Poll Message Repeat Rate PollMessageRate 5.8.17.2,
7.9.2.6
0x38 8 R/W Response Message for Tone Only type 1 ResponseToTone1 5.8.18,
0x39 8 R/W Response Message for Tone Only type 2 ResponseToTone2 7.9.2.7
0x3A 8 R/W Response Message for Tone Only type 3 ResponseToTone3
0x3B 8 R/W Response Message for Tone Only type 4 ResponseToTone4
0x40 1 R/W Forward channel message output mode ForwardChannelOutput 5.8.19,
7.9.1.5
Table 7 – Messaging Module Registers

© Satamatics Ltd Page 14 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.7 Scratchpad Module Registers


Module 0x06
Address Size Access Function TSL Register Name Para Ref.
(bits)
0x00 32 R/W Scratchpad Register 0 ScratchPad0 5.9, 5.9.1.1, 7.10.1
0x01 32 R/W Scratchpad Register 1 ScratchPad1 5.9, 5.9.1.2, 7.10.1
0x02 32 R/W Scratchpad Register 2 ScratchPad2
: : : 5.9, 7.10.1
0x0E 32 R/W Scratchpad Register 14 ScratchPad14
0x0F 32 R/W Scratchpad Register 15 ScratchPad15
Table 8 – Scratchpad Module Registers

© Satamatics Ltd Page 15 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.8 Operation Configuration Registers


Module 0x07
Address Size Access Function TSL Register Name Para Ref.
(bits)
0x00 32 R/W Operation 0 Configuration OperationConfig0 5.10.2, 7.7.1
0x01 32 R/W Operation 1 Configuration OperationConfig1
: :
0x1E 32 R/W Operation 30 Configuration OperationConfig30
0x1F 32 R/W Operation 31 Configuration OperationConfig31
0x20 32 R/W Operation 0 Value OperationValue0 5.10.3, 7.7.1
0x21 32 R/W Operation 1 Value OperationValue1
: :
0x3E 32 R/W Operation 30 Value OperationValue30
0x3F 32 R/W Operation 31 Value OperationValue31
0x40 32 W Disable all operations in bit mask DisableOperations 5.10.4, 7.7.2
(Affects operations 0 to 31)
0x41 32 W Enable all operations in bit mask EnableOperations 5.10.5, 7.7.3
(Affects operations 0 to 31)
0x42 32 W Reset all operations in bit mask ResetOperations 5.10.6, 7.7.4
(Affects operations 0 to 31)
0x43 32 W Trigger all operations in bit mask TriggerOperations 5.10.7, 7.7.5
(Affects operations 0 to 31)
0x44 32 W Disable operations in bit mask DisableOperationsExt 5.10.4
(Affects operations 32 to 63)
0x45 32 W Enable operations in bit mask EnableOperationsExt 5.10.5
(Affects operations 32 to 63)
0x46 32 W Reset operations in bit mask ResetOperationsExt 5.10.6
(Affects operations 32 to 63)
0x47 32 W Trigger operations in bit mask TriggerOperationsExt 5.10.7
(Affects operations 32 to 63)
0x80 32 R/W Operation 32 Configuration OperationConfig32 5.10.2, 7.7.1
0x81 32 R/W Operation 33 Configuration OperationConfig33
: :
0x9E 32 R/W Operation 62 Configuration OperationConfig62
0x9F 32 R/W Operation 63 Configuration OperationConfig63
0xA0 32 R/W Operation 32 Value OperationValue32 5.10.3, 7.7.1
0xA1 32 R/W Operation 33 Value OperationValue33
: :
0xBE 32 R/W Operation 62 Value OperationValue62
0xBF 32 R/W Operation 63 Value OperationValue63
Table 9 – Operations Module Registers
Note: Serial port access to the registers 0x44 to 0x47 inclusive, is via the RW/RR commands
only (section 7.11).

© Satamatics Ltd Page 16 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.2.9 Constant Generator Registers


Module 0x0F

Register Number Value Returned TSL Register Name Para Ref.


0x00 0x00000000 ConstantRegister0 or 5.11
PaddingZeroes
0x01 0x00000001 ConstantRegister1
: : :
0x0F 0x0000000F ConstantRegister15
0x10 0x00000010
: :
0xFE 0x000000FE
0xFF 0xFFFFFFFF ConstantRegister255 or
PaddingOnes
Table 10 – Constant Generators
Note: The TSL Register definition file SatConst.tsl does not define names for the Constant module
registers 0x10 to 0xFE.

© Satamatics Ltd Page 17 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.3 Configuration Module


Module ID = 0x00
Register addresses = Table 2

The configuration module provides access to the operational parameters of the terminal.

5.3.1 Ocean Region Selection Register


This register contains the ID number for the currently active bulletin board (see Table 11 for Bulletin
Board ID to Ocean Region mapping). If a new value is written to this register then the terminal will
attempt to acquire and use the new bulletin board.

Bulletin Board ID Ocean Region


0 Invalid value
1 AORW (Atlantic Ocean Region West)
2 AORE (Atlantic Ocean Region East)
3 IOR (Indian Ocean Region)
4 POR (Pacific Ocean Region)
5 PACC (Pacific Ocean Central)
6..16 Spare
17..31 Invalid value
Table 11 – Bulletin Board Selection Codes

If the automatic satellite switching is enabled (section 5.3.3) then selecting an ocean region by writing
to the Ocean Region register may not result in the terminal using the selected ocean region. For
example, consider a terminal that is located in Brazil and configured in follow best mode. In this
location two satellites are visible; AORE and AORW, with the latter being higher in the sky. If a
value of 02 is written to this register then the terminal will switch to use AORE but, on the next GPS
update, the follow best algorithm will switch the terminal back to AORW.

5.3.2 Service ID Selection Register


This register contains the number of the currently active service used by the terminal. The register
takes a value between 0x00 and 0x04 to select one of the 5 Service ID (SID) / Beam ID (BID)
pairings pre-programmed into the terminal. The SID/BID pairings corresponding to the service
selected can be read from the SID/BID registers (see paragraph 5.3.17)

© Satamatics Ltd Page 18 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.3.3 Satellite Selection Mode


The satellite selection algorithm is controlled by the states of the control word bits as defined in Table
12. When the terminal performs a satellite switch it can optionally be programmed to transmit a
message over the satellite link so that the LES can detect that the terminal has changed ocean regions.

Bit Function (when bit set)


0 Auto select on start up (see 5.3.3.1)
1 Enable Automatic switching during terminal operation.
2 Only valid if Automatic switching enabled:
1 = Follow Best (see 5.3.3.1)
0 = Switch on loss (see 5.3.3.3)
3 Spot beam Roaming enable. (Not implemented)
4 Transmit Message on ocean region switch. Only valid if automatic switching enabled
5 <Reserved>
6 <Reserved>
7 <Reserved>
8..15 Message number to transmit on an ocean region change. Only valid if bit 4 is set.
Table 12 – Terminal Satellite Selection Mode Control Word

5.3.3.1 Auto Select on Start Up

With this option enabled, the terminal uses GPS position to select the ‘best’ satellite (ocean region) on
power on or wake from sleep. If this option is disabled then the last configured satellite is used.

Note: This option should not be enabled if slotted receive (5.3.12) is used.

5.3.3.2 Follow Best Satellite Operation

The terminal will attempt to follow the best satellite based on the GPS position. The best satellite is
defined as the one with the highest elevation in the sky. Each time that the GPS provides a new valid
position fix this is compared with the satellite positions to determine the satellite that is highest in the
sky. If this is the currently selected satellite then the terminal will continue to use this satellite. If the
highest satellite is not currently selected then the terminal will switch over to the new best satellite.

If the terminal loses the signal from the best satellite due to antenna masking then it will suspend the
follow best algorithm and will try to acquire the satellites either side of the best. If it acquires the
signal from the second best satellite then it will use that satellite until its signal is lost and the follow
best satellite based on GPS position will resume.

When the terminal switches between satellites it can be configured to send a message. This notifies
the server application that the terminal has switched regions and allows any forward channel traffic
for the terminal to be routed correctly.

5.3.3.3 Switch On Satellite Loss

The terminal will attempt to switch satellites when the one currently in use is lost. A satellite is
considered lost when the terminal misses six successive traffic channel frames (three minutes
maximum) followed by two bulletin board frames (8 minutes maximum) or if, when the terminal
attempts to switch to the bulletin board frequency, it cannot detect the satellite signal.

© Satamatics Ltd Page 19 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.3.4 Power Control Register


The power control register provides access to the power saving modes of operation for the terminal.
The functions controlled by this register are described in Table 13.

Bit Function
0 1 = Enable RS-232 serial port drivers
1 1 = Enable Terminal Power
2 1 = Enable terminal indicator LED
3 1 = Enable ADC (analogue to digital converter) module.
If disabled the processor power rails, temperature and unit analogue inputs are
not measured.
4 1 = Disable GPS receiver
5 1 = Disable Inmarsat-D transceiver
6 <reserved> write as 0
7 <reserved> write as 0
8 1 = Enable IsatM2M slotted receive mode
NOTE It is NOT possible to change the state of this bit of the power control register
using the CE or CU commands. It can be changed using the RW command,
read with the RR command and used within terminal scripts.
9..31 <reserved> write as 0
Table 13 – Power Control Register Bit Definitions

In order to reduce overall power consumption the terminal uses an intelligent switch on method for
controlling power. Once the terminal has set its internal clock to UTC, it will power up the
Inmarsat-D transceiver at the optimal time to allow acquisition of the next Traffic Channel frame
header. As a consequence, a command to switch the power on to the terminal might not take effect for
up to 30 seconds.

Power to the Inmarsat-D transceiver and GPS module can be controlled independently.

The terminal operating mode can be switched by setting and clearing the register bits as shown in
Table 14 below:

Operating Register Register Bits Bits 0 to 8 (bits 9..31 set to 0)


Mode Bits Set Cleared x = don’t care
y = Function as Table 13
Sleep none 1 yyyxxyy0y
Standby 1,4,5 none yyy11yy1y
GPS Tracking 1,5 4 yyy10yy1y
Static 1,4 5 yyy01yy1y
Mobile 1 4,5 yyy00yy1y
Table 14 – Register Bits Modified to Switch Terminal Operating Modes

© Satamatics Ltd Page 20 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.3.5 DSP Firmware Version Number


This read only register holds the terminal DSP firmware version number in the form of 4 ASCII
characters. The version number is of the form AB.XY where AB and XY represent the major and
minor version numbers. This is stored in the 32-bit register as YXBA.

5.3.6 MSP Firmware Version Number


This read only register holds the terminal MSP firmware version number in the form of 4 ASCII
characters. The version number is of the form AB.XY where AB and XY represent the major and
minor version numbers. This is stored in the 32-bit register as YXBA.

5.3.7 Application Script Version Number


This register contains a user supplied application script version number. It allows the script
application revision to be identified. The four character version number is stored in the 32 bit register
in byte reversed order.

5.3.8 Store Application Script


Performing a write access with the data value 0xA5F00F5A to this register causes the terminal to
copy the current contents of the configuration registers in each of the functional modules into non-
volatile memory. Any existing script data is erased from the non-volatile memory store before the
current state is saved. If power is removed from the terminal and then re-applied the stored application
script will automatically be reloaded. It is important to note that this command stores the values of
the registers at the time that the command is issued. If the terminal has a running script then the
values stored will almost certainly not be those required at the start of script operation.

Four of the timers and alarms have non volatile updates such that if their trigger values are changed
the updated value is also written back to non-volatile memory, modifying the stored script. (See
paragraphs 5.4.1.1 and 5.5.1.1.)

5.3.9 Delete Application Script


Performing a write access with the script version number value to this register resets the script timers,
alarms and operation registers.

5.3.10 Power Supply Status


If no GEM-100 unit is connected, this register will always be read as 1; i.e. external supply present
and no solar panel supply. If a GEM-100 is utilised, this register reports the status of the power
supplies connected to the GEM-100.

Bit Function
0 External dc power supply present
1 Solar panel supply present
2..31 Reserved for future use. Write as 0
Table 15 – Power Supply Status Bit Definitions

© Satamatics Ltd Page 21 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.3.11 NMEA Message Output


The terminal can output NMEA-0183 type sentences over the serial port. The NMEA sentences
supported are RMC, GGA and GSV. The sentences to be output are enabled by setting individual bits
in the NMEA output control register as detailed in Table 16.

Bit Function Primary Information


0 Enable output of RMC sentence Time, 2D location, heading, speed
1 Enable output of GGA sentence Time, 3D location
2 Enable output of GSV sentence Satellites in view: azimuth, elevation, signal strength
3..31 Reserved for future use. Write as 0
Table 16 – NMEA Message Enable Bits

One set of enabled NMEA sentences is output on each GPS position update (i.e. once per second). If
GPS is not enabled then the output of NMEA sentences is inhibited.

The GSV sentence only holds information for up to four satellites, therefore if more satellites are in
view multiple GSV sentences might be output at each update. See paragraph 7.15 for details on the
RMC, GGA and GSV sentences.

5.3.12 Slotted Receive Mode Register


The terminal can be programmed to wake at intervals so that it can listen to the forward channel
traffic channel frame header and receive any messages that are being sent to it. The slotted receive
mode register sets the interval between terminal wakeup events. The values that can be written to the
register are shown in Table 17 below.

Value Interval in Frames Interval in Minutes


0,1 0 (Continuous Operation) 0 (Continuous Operation)
2 4 2
3 8 4
4 16 8
5 32 16
6 64 32
Table 17 – Slotted Receive Mode Register Values
If a forward message is received that is a poll and/or requires an acknowledgement, then the terminal
will remain awake to transmit the response.

5.3.13 Slotted Receive Mode Maximum Acquisition Retries


When the terminal is operating in slotted receive mode it may fail to acquire the satellite signal due to
either the terminal having an obstructed view of the sky or the terminal having moved out of the
satellite coverage area. If the terminal wakes up but cannot acquire either GPS or the Traffic Channel
it will assume that it has a totally blocked sky-view and will go back to sleep until the next wake up
slot. If the Traffic Channel cannot be acquired but GPS can then, if this condition persists for n wake
up slots, the terminal will stay awake and perform a satellite search. The value n is held in this
‘Maximum Acquisition Retries’ register.

© Satamatics Ltd Page 22 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.3.14 ISN, & PSN


This is a read only register containing the terminal ISN and PSN.
Bits Contents
0..23 Terminal ISN (not including the DSTxxx part)
24..27 Spare (zeros)
28..31 Terminal PSN
Table 18 - ISN Register Bit Allocation

5.3.15 Hardware Version


This is a read only register containing the terminal hardware build configuration value. Bits 0..3 hold
the build number and Bits 4..7 hold the Printed Circuit Board (PCB) issue number..

5.3.16 Group PID


These read only registers contain the terminals Group PIDs. A zero indicates that a Group PID has not
been configured.

The Inmarsat-D Service provides for messages to be sent to a group of terminals. This service is
achieved by programming terminals with a further PID (i.e. Group PID), which is identical for all
terminals in one group. The terminal can be programmed with up to 5 Group PIDs.

Contact Satamatics for more information or to obtain a Group PID

Programming of GPIDs is done via the password protected DS TG command (paragraph 7.14.6).

5.3.17 Service ID / Beam ID


These read only registers contain the pre-programmed Service ID / Beam ID pairings. A specific
pairing is selected via the Service ID Selection register (see paragraph 5.3.2).

5.3.18 Operational Flags


This read only register reflects the value of the Operational flags as configured via the DS TO
command (paragraph 7.14.11).

5.3.19 Terminal Mobility


This read only register reflects the value of the Terminal Mobility flag as configured via the DS TM
command (paragraph 7.14.9).

5.3.20 PACC Enable


Writing a 1 to this register enables the PACC satellite to be used as a candidate for selection by the
satellite roaming algorithm. If disabled, then a terminal that is within the coverage area for PACC will
choose either POR or AOR-W when it is selecting the best satellite using the GPS position
information. The state of this register is stored in non volatile memory and is not erased when the
processor firmware is updated. The default setting is PACC enabled.

© Satamatics Ltd Page 23 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.3.21 GEM Compatibility Enable


This bit must be set to 1 if the terminal is connected to a GEM-100, otherwise the bit should be
cleared to 0 (default). The GEM-100 provides additional interfaces and battery back up capability.
When the GEM-100 interface is enabled, interface channels 4 and 5 on the terminal are disabled (see
paragraph 5.6).

5.3.22 Terminal Reset


Write only register. Writing to this register will cause the terminal to perform a reset. If a value of 0 is
written, the terminal reset is delayed until the transmit queue is empty so that a reset request sent over
the forward channel may be acknowledged. If any other value is written then the terminal reset will be
performed immediately with no acknowledgement (even if requested) being transmitted.

5.3.23 Scripting Capabilities


This read only register provides details on the total number of scripting operations, timers and alarms
that are available within this particular terminal product.

Bits Information
0..7 Number of alarms
8..15 Number of timers
16..23 Number of operations

© Satamatics Ltd Page 24 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.4 Timer Module


Module ID = 0x01
Register addresses = Table 3

5.4.1 Timer Functionality


The timer module provides 32 independent timer channels that may be used to trigger operations. The
timers operate with a resolution of 1 second derived from the terminal internal frequency reference.

5.4.1.1 Updating Timer Trigger Values

The timer channels in the terminal are divided into two groups that differ in the effect that an update
to the trigger value has upon the stored script. If the trigger value on any of the timer channels 0 to 11
or 16 to 31 is updated as the result of a script operation then, if the terminal is restarted following a
power down, the timer trigger value will reset to the initial value defined in the original script. The
operation of timer channels 12 to 15 is slightly different. In the case of these four channels the timer
will restart with the updated trigger value that was set by the script operation. This allows, for
example, permanent changes to a terminal’s reporting rate to be made by triggering an operation
remotely with a forward channel message.

5.4.2 Timer Count Register


There is one timer count register for each of the timer channels provided by the terminal. These
registers have different functions on read and write. When read, the register contains the current
value of the timer count for the timer channel. When written the register uses the two LSB of the
value to control the timer channel, as shown in Table 19 below.

Timer Control Value Action


00 Stop Timer and hold current count value
01 Start Timer count from current value
10 Stop Timer and clear count value
11 Restart Timer count from zero
Table 19 – Timer Control Codes

5.4.3 Timer Configuration Register


There is one timer configuration register for each of the timer channels provided by the terminal. The
register is a 32-bit value divided up into fields as shown in the table below.

Bits Field Width Function


0 1 Timer Enable
1 1 Timer Repeat Mode
2 1 Timer Mode
7..3 5 Operation Number
31..8 24 Timer Trigger Value
Table 20 – Timer Configuration Register Field Definitions

© Satamatics Ltd Page 25 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.4.3.1 Enable

When this bit is set the timer channel is enabled, when cleared the timer channel is disabled.

5.4.3.2 Repeat

When this bit is clear the timer channel operates in single shot mode, when the timer reaches its
terminal count the operation is triggered and the timer is automatically disabled. When the bit is set
the timer operates in repeat mode; when it reaches its terminal count the operation is triggered, the
count register is reset to zero and the count restarts.

5.4.3.3 Mode

The mode bit sets the timer to operate in either interval (bit clear) or time of day (bit set) modes. In
interval mode the terminal count value represents the number of seconds that the timer is to count
before the event trigger. In the time of day mode the terminal count value indicates the time, in
seconds past midnight UTC, at which the event is to be triggered.

5.4.3.4 Operation Number

The operation number field is a 5 bit number (0..31) indicating the operation that is to be triggered
when the timer reaches its terminal count. This field size limits the operations that the timer channels
can trigger, i.e. a timer channel cannot trigger operations in the range 32 to 63.

5.4.3.5 Terminal Count Value

The terminal count value is a 24-bit number representing the trigger value for the timer. The
maximum value that can be stored is 16777215 seconds or just over 194 days. The terminal count
value may also be set by writing to the terminal count value register for the channel. This provides an
easy way to modify a timer trigger value from within a script without having to preserve the least
significant bits of the configuration register.

5.4.4 Timer Control


There is a set of 6 registers that allow the timers to be controlled in groups. These write only registers
allow a defined group of timers to be stopped, started, reset or restarted together.

5.4.4.1 Stop Timers

The stop timers register is a 32-bit write only register. The value written to this register is a bit mask
of the channels to be stopped. Timer 0 is indicated by the LSB of the value and timer 31 by the MSB.
Writing a 1 to the channel control bit causes the timer to stop counting. The value reached in the
timer count register is held.

5.4.4.2 Start Timers

The start timers register is a 32-bit write only register. The value written to this register is a bit mask
of the channels to be started. Timer 0 is indicated by the LSB of the value and timer 31 by the MSB.
Writing a 1 to the channel control bit causes the timer to start counting from the current value in the
count register.

© Satamatics Ltd Page 26 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.4.4.3 Reset Timers

The reset timers register is a 32-bit write only register. The value written to this register is a bit mask
of the channels to be reset. Timer 0 is indicated by the LSB of the value and timer 31 by the MSB.
Writing a 1 to the channel control bit causes the timer to stop counting and the count register to be set
back to zero.

5.4.4.4 Restart Timers

The restart timers register is a 32-bit write only register. The value written to this register is a bit
mask of the channels to be restarted. Timer 0 is indicated by the LSB of the value and timer 31 by the
MSB. Writing a 1 to the channel control bit causes the timer to restart its count from zero without
triggering an operation.

5.4.4.5 Combined Operation to Enable and Disable Timer Channels

This function is only available for timer channels 0 to 15.


The timer channels to be enabled are defined by the bits set within the 16 most significant bits of the
32-bit operation parameter value. The timer channels to be disabled are defined by the bits set in the
bottom 16 bits of the 32-bit operation parameter value.

5.4.4.6 Combined Operation to Restart and Reset Timer Channels

This function is only available for timer channels 0 to 15.


The timer channels to be restarted are defined by the bits set within 16 most significant bits of the
32-bit operation parameter value. The timer channels to be reset are defined by the bits set in the
bottom 16 bits of the 32-bit operation parameter value.

5.4.5 Mixed Timer/Alarm Operations

5.4.5.1 Mixed Operation to Enable Timer and Alarm Channels

This function is only available for timer and alarm channels 0 to 15.
The timer channels to be enabled are defined by the bits set within 16 most significant bits of the 32-
bit operation parameter value. The alarm channels to be enabled are defined by the bits set in the
bottom 16 bits of the 32-bit operation parameter value.

5.4.5.2 Mixed Operation to Disable Timer and Alarm Channels

This function is only available for timer and alarm channels 0 to 15.
The timer channels to be disabled are defined by the bits set within 16 most significant bits of the 32-
bit operation parameter value. The alarm channels to be disabled are defined by the bits set in the
bottom 16 bits of the 32-bit operation parameter value.

© Satamatics Ltd Page 27 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.4.5.3 Mixed Operation to Restart Timer and Alarm Channels

This function is only available for timer and alarm channels 0 to 15.
The timer channels to be restarted are defined by the bits set within 16 most significant bits of the 32-
bit operation parameter value. The alarm channels to be restarted are defined by the bits set in the
bottom 16 bits of the 32-bit operation parameter value.

5.4.5.4 Mixed Operation to Reset Timer and Alarm Channels

This function is only available for timer and alarm channels 0 to 15.
The timer channels to be reset are defined by the bits set within 16 most significant bits of the 32-bit
operation parameter value. The alarm channels to be reset are defined by the bits set in the bottom 16
bits of the 32-bit operation parameter value.

5.4.6 Real Time Functionality


There are a number of read only registers within the timer module that contain the current UTC.
These values are maintained by the terminal’s internal real time clock and synchronised with UTC
obtained from either GPS or the Inmarsat-D Bulletin Board whenever these are available.

The internal real time clock continues to operate during sleep mode.

5.4.6.1 Seconds Past Midnight

The seconds past midnight register is a read only register containing the current time represented as a
count of seconds past midnight UTC

5.4.6.2 Time and Date

Time and date information is stored in a set of 6 read only registers. The values read from these
registers is a binary representation of the current UTC time maintained by the terminal. The year
value is stored as the full 4 digit value i.e. year 2003 is returned as 2003 not 3.

© Satamatics Ltd Page 28 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.5 Alarm Module


Module ID = 0x02
Register addresses = Table 4

5.5.1 Alarm Functionality


The alarm module provides a means of triggering the terminal to perform operations based upon the
values held in registers in any of the available modules. There are 32 alarm channels each of which
can be programmed to trigger an operation if the result of a comparison between the value held in one
of the terminal registers and a programmable threshold value is true. If an alarm is triggered then the
value in the terminal register that caused the trigger is stored in Scratchpad register 0. The available
comparison operations are shown in paragraph 5.5.3.5 below.

5.5.1.1 Updating Alarm Threshold Values

The alarm channels in the terminal are divided into two groups that respond to an update of
the threshold value in slightly different ways. If the threshold value on any of the alarm channels 0 to
11 or 16 to 31 is updated as the result of a script operation then, if the terminal is restarted following a
power down, the alarm threshold value will reset to the value defined in the original script. Channels
12 to 15 operate slightly differently following a system reset. These four channels will restart with
the updated threshold value that was set by the script operation.

5.5.2 Alarm Control/Status


There is one alarm control/status register for each of the alarm channels provided by the terminal.
These registers have different functions on read and write. When read, the register contains the
current alarm channel status. When written the register uses the two LSB of the value to control the
alarm channel, as shown in Table 21 below.

Alarm Control Value Action


00 Disable the alarm
01 Enable the alarm
10 Reset the alarm
11 Manually trigger the alarm
Table 21 – Alarm Control Codes

© Satamatics Ltd Page 29 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.5.3 Alarm Configuration


There is one alarm configuration register for each of the alarms provided by the terminal. The register
is a 32-bit value divided up into fields as shown in the table below.

Bits Field Width Function


0 1 Alarm Enable
1 1 Latch Alarm
2 1 Auto Latch Release
7..3 5 Operation Number (Low Part)
11..8 4 Threshold Comparison Mode
14..12 4 Reserved - Leave as Zero
18..15 3 Operation Number (High Part)
19 1 Reserved - Leave as Zero
27..20 8 Target Register Number
31..28 4 Target Module Number
Table 22 – Alarm Configuration Register Field Definitions

5.5.3.1 Enable

When this bit is set the alarm channel is enabled, when cleared the alarm channel is disabled.

5.5.3.2 Latch Mode

In latch mode an alarm will trigger once when the alarm condition is first detected. The alarm will
not be raised again until it has been reset using the reset alarm command in the control register or by
setting the channel bit in the reset register.

5.5.3.3 Auto Latch Release

If the alarm is in latch mode then when the auto latch release bit is set, the latch will be removed
automatically when the alarm condition is removed. As an example, if an alarm is set to trigger when
an I/O line goes high then the alarm will trigger on the first detection of the bit going high. The latch
will be set so that the alarm does not trigger on the next alarm polling cycle. On a later polling cycle
the I/O line is low again and, if the auto release bit is set, the latch will be removed allowing the alarm
to re-trigger the next time that the I/O line goes high. This removes the need to issue a reset alarm
command to clear the latch manually.

5.5.3.4 Operation Number

The operation number field is an 8 bit number indicating the operation number that is to be triggered
when the comparison function raises the alarm. The value is split into two parts in the register; the
original 5 bits (Low Part), used in legacy terminals where only 32 operations were available, has been
extended by 3 bits (High Part) to cater for the 64 operations currently available, and to allow for
possible future expansion to 256 operations.

© Satamatics Ltd Page 30 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.5.3.5 Comparison Mode

Function Comparison Operation Alarm Raised if… TSL Syntax


Code
0x0 Equal Value == Threshold myValue == myThreshold
0x1 Not Equal Value != Threshold myValue != myThreshold
0x2 Less Than Value < Threshold myValue < myThreshold
0x3 Less Than or Equal Value <= Threshold myValue <= myThreshold
0x4 Greater Than Value > Threshold myValue > myThreshold
0x5 Greater Than or Equal Value >= Threshold myValue >= myThreshold
0x6 Bit Set ( Value & Threshold ) == Threshold myValue %1 myThreshold
0x7 Bit Clear ( ~Value & Threshold ) == Threshold myValue %0 myThreshold
0x8 <reserved> <alarm never raised>
0x9 <reserved> <alarm never raised>
0xA <reserved> <alarm never raised>
0xB <reserved> <alarm never raised>
0xC <reserved> <alarm never raised>
0xD <reserved> <alarm never raised>
0xE <reserved> <alarm never raised>
0xF <reserved> <alarm never raised>

Table 23 – Alarm Comparison Mode Codes

5.5.3.6 Target Register ID

The target register for the alarm is defined by a 12-bit address, made up from a 4 bit module ID and
an 8 bit register address. These register addresses are defined in the separate module description
sections within this document.

5.5.4 Alarm Threshold


There is one alarm threshold register for each of the alarm channels in the terminal. These hold the
value used by the alarm channel when it is performing the comparison test on the value held in the
target register. Each register holds a 32-bit value.

5.5.5 Alarm Control


There is a set of 5 registers that allow the alarms to be controlled in groups. These write only registers
allow a defined group of alarms to be disabled, enabled, reset or triggered together.

5.5.5.1 Disable Alarms

The disable alarms register is a 32-bit write only register. The value written to this register is a bit
mask of the channels to be disabled. Alarm 0 is indicated by the LSB of the value and alarm 31 by
the MSB. Writing a 1 to the channel control bit causes the alarm to be disabled.

5.5.5.2 Enable Alarms

The enable alarms register is a 32-bit write only register. The value written to this register is a bit
mask of the channels to be enabled. Alarm 0 is indicated by the LSB of the value and alarm 31 by the
MSB. Writing a 1 to the channel control bit causes the alarm to be enabled.

© Satamatics Ltd Page 31 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.5.5.3 Reset Alarms

The reset alarms register is a 32-bit write only register. The value written is a bit mask of the channels
to have their latches reset. Alarm 0 is indicated by the LSB of the value and alarm 31 by the MSB.
Writing a 1 to the channel control bit causes the alarm latch to be reset.

5.5.5.4 Trigger Alarms

The trigger alarms register is a 32-bit write only register. The value written to this register is a bit
mask of the channels to be triggered. Alarm 0 is indicated by the LSB of the value and alarm 31 by
the MSB. Writing a 1 to the channel control bit causes the alarm to be triggered.

5.5.5.5 Toggle Alarms

The toggle alarms register is a 32-bit write only register. The value written to this register is a bit
mask of the channels for which the enable state is to be toggled. Alarm 0 is indicated by the LSB of
the value and alarm 31 by the MSB. Writing a 1 to the channel control bit causes a disabled alarm to
be enabled and an enabled alarm to be disabled.

5.5.5.6 Restart Alarms

The restart alarms register is a 32-bit write only register. Writing to this register allows a
simultaneous clearing of the alarm latch and enabling the alarm if it was previously disabled. The
value written to this register is a bit mask of the channels to be unlatched and enabled. Alarm 0 is
indicated by the LSB of the value and alarm 31 by the MSB. Writing a 1 to the channel control bit
causes that channel to be affected.

5.5.5.7 Combined Operation to Enable and Disable Alarm Channels

This function is only available for alarm channels 0 to 15.


The alarm channels to be enabled are defined by the bits set within 16 most significant bits of the
32-bit operation parameter value. The alarm channels to be disabled are defined by the bits set in the
bottom 16 bits of the 32 bit operation parameter value.

© Satamatics Ltd Page 32 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.6 Interface Module


Module ID = 0x03
Register addresses = Table 5

IMPORTANT NOTE - The register descriptions in this module contain details of the maximum
number of input and output lines supported by the software. Not all of these lines are available in the
terminal hardware at any one time.

5.6.1 I/O Configuration Register


The I/O configuration register controls the input/output configuration of the eight terminal interface
‘channels’. The interfaces available depend on the hardware configuration as detailed in Table 24
below. Refer to the SAT-200/202 user manual for electrical specifications.

I/O Line Valid Configuration Options Comments


OUT Open Drain Out The user must ensure that the configuration is
(Internal channel 0) set to ‘Open Drain’ for correct operation.
The Open Drain output remains active during
sleep mode.
IO1, IO2, IO3 Analogue Input IO2 corresponds to SAT-201 interface pin IN1
(Internal channels 1,2 & 3 High Volt Digital Input (Polled or Interrupt) IO3 corresponds to SAT-201 interface pin IN2
respectively) Digital Input (Polled or Interrupt) IO1 corresponds to SAT-201 interface pin
Alert Digital Input (Polled or Interrupt) OUT2 (was open drain output on SAT-201)
Digital Output
IO4, IO5 Analogue Input Unprotected. Available on SAT-200 when
(Internal channels 4 & 5) Digital Input (Polled) Module 1, Register 0xFD = 0 (see 5.3.21)
Digital Output
GEM-100 IO4 to IO7 Analogue Input Available with SAT-202/GEM-100
(Internal channels 4 to 7) Digital Input (Polled or Interrupt) combination only, i.e. when Module 1,
Alert Digital Input (Polled or Interrupt) Register 0xFD = 1 and a GEM-100 connection
Digital Output is detected.
(see 5.3.21)

Table 24 – Valid I/O Channel Configurations

The register contains eight 4-bit fields, one for each channel. The pin mode is defined by the code
written in the field associated with that pin. The codes are described in Table 25 below.

Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16

Channel 7 Mode Channel 6 Mode Channel 5 Mode Channel 4 Mode


Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit Bit
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

Channel 3 Mode Channel 2 Mode Channel 1 Mode Channel 0 Mode

Figure 1 – Configuration Register Bit Functions

© Satamatics Ltd Page 33 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Pin Mode Number I/O Pin Configuration


0 Analogue Input
1 High Volt Digital Input
2 Digital Input
3 Alert Digital Input
5 High Volt Digital Input Interrupt
6 Digital Input Interrupt
7 Alert Digital Input Interrupt
8 Digital Output
9 Open Drain Out
10 4-20mA Current Loop
11 Analogue Output
Table 25 – I/O Pin Mode Configuration Codes

5.6.2 Analogue Inputs


Channels configured to be analogue inputs have an input voltage range of between 0 and 2.5 volts and
provide a 12-bit conversion result according to the following formula:
4096
Value = Voltage ×
2 .5
Channels not configured as analogue inputs will always return a conversion result of 0.

Important: There is a short delay between setting an I/O to an analogue input, and the associated
register being updated with the first valid conversion result. Scripts that compare analogue input
values with a threshold should therefore allow 10 seconds, following I/O configuration (i.e. normally
only after initial power on), for the first conversion to complete.

5.6.3 Digital Inputs


The input state register provides the input state of channels configured as digital inputs. A state value
of 0 will be returned for those channels not configured as digital inputs.
Bit Bit BitBit Bit Bit Bit Bit
7 6 5 4 3 2 1 0
Input Channel State
(1 = Logic High, 0 = Logic Low)
Chan Chan Chan Chan Chan Chan Chan Chan
7 6 5 4 3 2 1 0

Figure 2 - Digital Input State Register Bit Functions

© Satamatics Ltd Page 34 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.6.4 Digital Outputs


The logic state for channels configured as digital outputs is set by the value written to the digital
output register.
Bit Bit Bit Bit Bit Bit Bit Bit
7 6 5 4 3 2 1 0
Output Channel State
(1 = Logic High, 0 = Logic Low)
Chan Chan Chan Chan Chan Chan Chan Chan
7 6 5 4 3 2 1 0

Figure 3 - Digital Output State Register Bit Functions

5.6.5 Processor Supply Voltage


The processor supply voltage is continuously measured using the on-chip ADC. The result from this
conversion is stored in a 16-bit wide, unsigned integer format. The value stored is the measured
voltage in mV. This rail is regulated on the terminal board to a nominal 3.3V.

5.6.6 External Supply Voltage


The external supply voltage (9.6V to 32V) is measured using the on-chip ADC, when ADC
conversions are enabled. The result from this conversion is stored in a 16-bit wide, unsigned integer
format. The value stored is the measured external supply voltage in mV.

5.6.7 GEM-100 Battery Supply Voltage


When a GEM-100 is utilised, its battery supply voltage is stored in a 16-bit wide, unsigned integer
format. The value stored is the measured battery supply voltage in mV.

If a GEM-100 is not used the battery supply voltage register will always return a value of zero.

There are a number GEM-100 battery voltages that trigger events in the battery charging cycle and
terminal operation:

• The terminal will shut down if the GEM-100 reports that its battery voltage is less than 10.2V
and there is no external power supply (not solar panel input.)
• If the terminal has shut down due to a low battery voltage then it will not restart until the
GEM-100 reports that its battery voltage has recovered to 13.1V. If the battery has not
recovered to this level then there will be insufficient energy available to perform any
transmissions.
• Once the battery has been fast charged from an external supply then the battery will be held in
trickle charge until its voltage falls to 12.5V when the fast charge will re-enable.
• When the terminal is operating with a solar panel providing the battery charger source the
battery will charge fully and then the solar charger will be turned off. The solar charger will be
turned back on when the battery voltage falls to 13.4V.

A fully charged battery pack generally has a voltage of around 14.2V

© Satamatics Ltd Page 35 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.6.8 Device Temperature


The terminal contains a temperature sensor. When the ADC is enabled it is monitored by the software
and the result stored in the device temperature register. The value stored is a signed 16 bit value
representing the temperature in degrees Celsius.

5.6.9 Calibrated Temperature


The internal temperature sensor is for indication only. To obtain a more accurate reading a single
point calibration can be entered.

Writing the current ambient temperature into the calibrated temperature register causes the terminal to
calculate the offset from the internally derived value. The terminal will then use this offset to adjust
all subsequent temperature readings. The value stored is a signed 16 bit value representing the
temperature in degrees Celsius. The state of this register is stored in non volatile memory and is not
erased when the processor firmware is updated

5.6.10 GEM-100 Battery Temperature


When a GEM-100 is utilised, its battery pack temperature is stored in a 16-bit wide, signed integer
format. The value is the temperature x 10. (i.e. steps of 0.1 degree Celsius) except; a value of 2550
indicates battery pack not fitted, and a value of 0 is always returned if a non-rechargeable battery is
fitted.

If a GEM-100 is not used, this register will always return the value 2550 (decimal) indicating battery
pack not fitted.

5.6.11 GEM-100 Battery Power Output


The GEM-100 can output its battery supply voltage on I/O pin 7. This is controlled by a 1-bit value in
the battery output enable state register. Writing a 1 to this register enables the battery output, zero
returns the I/O line to its normal use as defined by the I/O configuration register.

5.6.12 GEM-100 User LED State


The GEM-100 unit has a second, user programmable LED indicator. The state of this LED is
controlled by a two bit value written to this register. The LED colours displayed are shown in Table
26 below.

Value Colour
0 Off
1 Red
2 Green
3 Orange
Table 26 – User LED Colour Codes

© Satamatics Ltd Page 36 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.7 GPS Module


Module ID = 0x04
Register addresses = Table 6

5.7.1 Current Position

5.7.1.1 Status

The GPS status register is a read only register. The value returned from this register can be either 0 or
1. If it is 0 then the last GPS position fix was invalid, if it is a 1 then the position data is valid. An
invalid GPS fix will be indicated if:

1. The GPS engine determines that it does not have a valid fix. (Note that even if the GPS
reports a valid fix, the accuracy might be severely degraded in poor sky view conditions, in
particular where direct line of sight to GPS satellites is blocked but the reflected signals are
strong enough to be accepted for location determination.)
2. The terminal operating mode is changed so that the GPS is turned off
3. The MSP does not receive a message from the GPS for 4 seconds.

5.7.1.2 Latitude

The GPS latitude register contains the last value for the terminal position as read from the GPS
receiver. The format of the value is shown in Table 27

Bits Function
31 Sign (0 = +ve, 1 = -ve)
23..30 Degrees
17..22 Minutes
11..16 Seconds
4..10 Hundredths of a second
0..3 Unused
Table 27 – Latitude/Longitude Data Format

5.7.1.3 Longitude

The GPS longitude register contains the last value for the terminal position as read from the GPS
receiver. The format of the value is shown in Table 27.

5.7.1.4 Speed

The GPS speed register contains the last value for terminal unit speed as read from the GPS receiver.
The speed is stored as a value in the range 0..32767 with a resolution of 0.1 m/s.

5.7.1.5 Heading

The GPS heading register contains the last value for the terminal heading as read from the GPS
receiver. The heading is stored as a value in the range 0..3599 and with a resolution of 0.1 degrees.

© Satamatics Ltd Page 37 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.7.1.6 Altitude

The GPS Altitude register contains the last value for the terminal altitude as read from the GPS
receiver. The altitude is stored as a value in metres.

5.7.1.7 Horizontal Dilution of Precision (HDOP)

The HDOP provides an indication of positional accuracy; the lower the HDOP the better. The HDOP
register provides an integer value which is the HDOP * 100. The 16 bit register is set to 0xFFFF if the
GPS reading is invalid. For example a register value of 0x00FA would indicate a HDOP of 2.5.

5.7.2 Reference Position


The reference position is a single location defined by its lat/long held in the ‘Reference Latitude’ and
‘Reference Longitude’ registers. The reference position may be updated to the current position by
writing to the ‘Store Current as Reference’ register. Updating to any other value is only possible via
the GR serial command (paragraph 7.8.4.2).

5.7.2.1 Store Current Position as Reference

This is a write only register that stores the current GPS location as the reference.

5.7.2.2 Reference Latitude

This register contains the latitude value of the reference position. The format is defined in Table 27.

5.7.2.3 Reference Longitude

This register contains the longitude value of the reference position. The format is defined in Table 27.

5.7.2.4 Distance from Reference

The distance from reference contains the calculated distance between the reference position and the
current GPS position. The distance is calculated in metres and assumes a spherical earth with a radius
of 6371km.

5.7.3 Target Positions


Trigger events can be generated dependent upon the relative position of the terminal and one or more
target positions. Up to 8 target positions can be defined and stored in the terminal non-volatile
memory. These target positions may be updated either by operator command over the serial link, or
using a forward channel message (see paragraph 6.4) over the satellite to the terminal. It is not
possible to update the target positions using the script functions.

5.7.3.1 Distance from Target

There are 8 independent read only ‘distance from target’ registers. These contain the calculated
distance, in metres, between the relevant target position and the current GPS position. These registers
may be used by the alarms module to generate an event based on the terminals position relative to the
target. If the target definition has not been initialised then the register cannot generate an alarm.

© Satamatics Ltd Page 38 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.7.3.2 Distance to Closest Target

This register contains the distance, in metres, from the current position to the closest valid target
position. If there are no valid targets defined then the value returned will be 0xFFFFFFFF.

5.7.3.3 Distance to the Farthest Away Target

This register contains the distance, in metres, from the current position to the farthest away valid
target position. If there are no valid targets defined in the terminal then the value returned will be 0.

5.7.3.4 Target Latitude

There are 8 independent read only registers each of which contain the latitude value of one of the
target positions. The value is stored in the format defined in Table 27.

5.7.3.5 Target Longitude

There are 8 independent read only registers each of which contain the longitude value of one of the
target positions. The value is stored in the format defined in Table 27.

5.7.4 NMEA registers


Refer to paragraph 7.15.

5.7.5 Last GPS fix


Two registers provide information on when the last valid GPS position was obtained. The ‘number of
hours since last fix’ register provides a 3 bit number indicating the number of hours since the last fix.
A value of 7 indicates that it has been greater than or equal to 7 hours since the last fix.

The ‘time at last fix’ register gives the number of seconds past midnight that the last valid fix was
obtained.

5.7.6 Geofence
The terminal allows for the definition of two geofence areas. These areas are each defined by a
sequence of up to 40 points. These areas are used to determine whether or not the terminal location is
within the selected global regions. Geofence definition and configuration uses the operator
commands defined in section 7.8.3. An example of Geofence definition is described in APPENDIX
A – Example Geofence Definition.

5.7.6.1 Geofence Status

The geofence status registers 1 and 2 contain the result of comparing the current GPS position with
geofences 1 and 2 respectively. The values read from these registers are defined in Table 28.

Register Value Meaning


0x00 Point Outside the defined area
0x01 Point inside defined area
0xFF Area not defined
Table 28 – Geofence Status Register

© Satamatics Ltd Page 39 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.8 Messaging Module


Module ID = 0x05
Register addresses = Table 7

The messaging module provides the interface to the Inmarsat-D messages received and transmitted by
the terminal.

5.8.1 Return Burst Message ID Register


The return burst ID register is a write only register into which is written the ID code of the return
burst message to be sent. Writing to this register causes the message to be queued for transmission.

The ID codes for pre-defined messages are listed in Table 29. The formats of the return messages are
defined in reference [2]. The message ID code may also refer to one of the user-defined formats
programmed into the terminal.

No transmission will occur if an undefined or reserved message code is used.

Message ID Code Message Data


0x01 GPS Position Report
0x02 Digital I/O Status
0x03 All Analogue Inputs – 8 bit result
0x04 <reserved>
0x05 Processor Environment
0x06 Analogue Input channel 0 – 12 bit result
0x07 Analogue Input channel 1 – 12 bit result
0x08 Analogue Input channel 2 – 12 bit result
0x09 Analogue Input channel 3 – 12 bit result
0x0A Analogue Input channel 4 – 12 bit result
0x0B Analogue Input channel 5 – 12 bit result
0x0C Analogue Input channel 6 – 12 bit result [GEM-100 Only]
0x0D Analogue Input channel 7 – 12 bit result [GEM-100 Only]
0x0E <reserved>
0x0F <reserved>
0x10 <reserved>
0x11 <reserved>
0x12 <reserved>
0x13 <reserved>
0x14 <reserved>
0x15 <reserved>
0x16 Report Scratchpad 1 Register
0x17 Report contents of Scratchpad 1 and 2 Registers
0x18 Aeronautical Position Report
0x19 Terrestrial Position Report
0x20 Target Point 0 Report
0x21 Target Point 1 Report
0x22 Target Point 2 Report
0x23 Target Point 3 Report
0x24 Target Point 4 Report
0x25 Target Point 5 Report
0x26 Target Point 6 Report
0x27 Target Point 7 Report
0x28 Terminal Software Version Report

© Satamatics Ltd Page 40 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Message ID Code Message Data


0x29 Terminal Script Version Report
0x2A Stored Terminal Script Checksum Report
0x40 Double Burst: GPS Position and terminal status
0x7F Alternative Maritime Position Report
Table 29 – Return Message Type Numbers

5.8.1.1 Creating User Defined Messages

In addition to the standard messages that may be transmitted by the terminal it is possible to define
custom message formats that are built up from data values extracted from the terminals internal
registers. User message definition uses the operator commands defined in section 7.12.

Details of how to construct a user-defined message is provided in Appendix B – Example User


Message Definition.

5.8.2 Return Burst Destination Address Register


This register contains the destination address field to be used in the return messages.

5.8.3 Combined Control Word and Destination Address


A special register has been included in the messaging register set that allows both the destination
address and control word fields to be set in one operation. This has been provided to allow a single
operation to be used to set a code value into the header of a return message. The Control word is a 4
bit value that is sent at the start of a long data message. It is set to contain bits 19..16 of the value
written to this register. The destination address field is set with the 8 LSB of this combined register
value (bits 7..0). Bits 15..8 are ignored.

5.8.4 Return Burst Acknowledge Flags


The return burst acknowledge flags set the type of acknowledgement that is to be provided to the
return burst from the terminal. There are two types of acknowledgement: application acknowledge
and LES acknowledge. These two acknowledgement methods are requested by bit 0 (application) and
bit 1 (LES acknowledge). If an LES acknowledge is requested for a return burst then the terminal will
wait for the forward channel acknowledgement message from the LES. If after 10 minutes the
terminal has not received an acknowledgement the terminal will re-send the burst.

5.8.5 Return Burst Control Flags


This register contains the control flags field to be used in the return bursts.

5.8.6 Return Channel Message Scrambling Vector


Data transmitted by the terminal in long data bursts can be scrambled using a combination of the
unique terminal ISN value and the user provided value stored in this register. Writing a value of zero
to this data register turns off the message scrambling feature. Contact Satamatics for more details on
message scrambling.

© Satamatics Ltd Page 41 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.8.7 Terminal Receiver Status Registers

5.8.7.1 Receiver Channel Number

This register contains the Inmarsat satellite channel number on which the terminal is expecting to
receive its signal, either the bulletin board or the traffic channel.

5.8.7.2 Receiver Signal Quality

This register contains the received signal C/N0. The value in this register is given by:
Signal (in dB ) × 4096
Value =
10

5.8.7.3 Receiver Status

This register contains the receiver status byte as returned by the terminal. The fields within the byte
are shown in Table 30 below.

Bits Meaning
0 Condition (0 = Normal, 1 = Abnormal)
1 BB Alarm (0 = Normal, 1 = Alarm)
2 BB/Traffic Indicator (0 = BB, 1 = TC)
3 Reserved
4..6 Receiver Status Code:
0 = DSP Reset
1 = Configuring
2 = Wideband Acquisition
3 = Narrowband BB
4 = BB Tracking and Demodulation
5 = Narrowband Traffic
6 = Traffic Tracking and Demodulation
7 = Reserved
7 Reserved
Table 30 – Receiver Status Byte Fields

An abnormal condition on the bulletin board can be one of the following:

• Bulletin board does not contain an entry for the configured terminal service ID.
• Bulletin board does not contain an entry for the configured terminal Beam Number.
• Bulletin board does not contain an entry for the configured terminal pager subset number.

5.8.8 Terminal Transmitter Status Register


The terminal transmitter status register contains the 32-bit status information returned by the terminal.
The format of the fields in this register is as shown in Table 31 below.

© Satamatics Ltd Page 42 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Bits Meaning
0..2 Transmission state
0 = Reserved
1 = Tx Acceptance
2 = Waiting to Transmit
3 = Transmitting
4 = Transmission complete
3 PLL Unlocked
4 Transmission Waiting
5..7 Transmit Inhibit Reason
0 = Transmission enabled
1 = TX Inhibit by PLL unlock
2 = TX Inhibit by RX condition
3 = TX Inhibit by System Message
4 = TX Inhibit by Waiting for ACK
8..9 Traffic Control
10..11 Burst Type
0 = ACK burst
2 = Long Burst
(or part of Double Burst)
12..15 Reserved
16..19 Minutes(1)
20..23 Minutes(10)
24..27 Hours(1)
28..31 Hours(10)
Table 31 – Transmitter Status Register Fields
The time value reported is the time of last message transmission or 00:00 if the terminal has not sent a
message. The time is reset each time that the terminal is powered down or enters sleep mode.

5.8.9 Transmit Randomisation Period


This register contains the period over which the return burst transmission may be randomised. The
value written to this register contains the number of transmission frames from which the transmission
slot is chosen. If the value is zero then the message is transmitted in the next available return channel
slot. This mode of operation should only be used for transmissions where the timing of the trigger
event is inherently random, e.g. manual panic alarms. Messages generated as a result of events
triggering at a given time of day require larger randomisation values so that there will not be a large
population of terminals trying to transmit in the same time slots.

5.8.9.1.1 Reasons for Randomising Message Transmission

Messages sent by a terminal are normally generated in response to an event. This may be a periodic
report, an external exception condition or an event that happens at a specific time of day. The timing
of some of these may be random, for example the time at which a monitored device generates an
exception report will normally be random, but many events happen at a specific time of day. If there
is a population of terminals that all generate and transmit their messages at the same time then there is
a higher probability of collisions between terminal transmissions and hence data loss. Collisions can
be minimised by ensuring an even spread (in time) of transmissions from the terminal population.
This can be achieved by specifying a larger number for the slot randomisation.

© Satamatics Ltd Page 43 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

If an application has a large number of terminals configured to transmit at a single time of day then
that application might suffer a high message loss, but because the transmissions generated by this
application occur over a small period of time the effect upon other applications, that spread their
transmissions more evenly, is negligible.

5.8.10 Transmit Retries


For messages transmitted with a request for an LES acknowledgement, the terminal can be configured
to re-send the message if an LES acknowledgement is not received. The Transmit Retries register sets
the number of retries (0 to 15) to be attempted. There will be at least 90 seconds (three frames)
between each retransmission to allow time for an LES acknowledgement to be received.

5.8.11 Receive Signal Level


Inmarsat-D received signal level multiplied by -100. E.g. a value of 0x109E (=decimal 4254) would
equate to a signal level of -42.54dBm.

5.8.12 Receive Frequency Offset


Inmarsat-D received signal frequency offset, in Hz, from the nominal channel frequency.

5.8.13 Receive Rate of Change Frequency


Rate of change of frequency, in Hz/s, on received Inmarsat-D signal.

5.8.14 Receive Symbol Errors


Provides the number of corrected errors in the data portion of the most recently received Inmarsat-D
frame. As the data portion of the frame is variable in size, depending on the amount of data traffic,
this parameter should be used for indication purposes only if used to gauge quality of service.

5.8.15 Number of Messages in the Transmit Queue


This is a read only register that contains the number of return channel messages that are awaiting
transmission that was reported by the DSP at the last update. The value reported is that received from
the DSP as the transmit messages pending parameter in the TT message report.

5.8.16 Transmit Queue Configuration


This is a read only register that contains, in the bottom 4 bits, the length of the return channel transmit
message queue and, in the next bit the queue message insertion mode as these were reported by the
DSP at the last update. The values reported are those received from the DSP in the TW message
report.

5.8.17 Poll Message Control Registers


These two registers are used to control the regular reporting capability of the terminal. The terminal
can produce regularly timed return message bursts containing any of the standard format messages
defined in paragraph 5.8.1.

© Satamatics Ltd Page 44 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.8.17.1 Poll Message ID

The poll message ID register contains the message number to be transmitted in the regular return burst
from the terminal. This may be one of the standard message ID numbers as defined in Table 29 or the
number of one of the user defined message formats programmed into the terminal.

5.8.17.2 Poll Message Repeat Rate

The poll message repeat rate defines the interval between message transmissions in seconds. The
message transmission interval will not take place at the exact second spacing defined by this message
due to space network limitations and the protocol for transmissions used by the terminal. The interval
specified is the time between the requests to the terminal transmitter to send the message.
There are a number of limitations to the values that can be written to this register.
• 0 Disables Poll messages
• 1 .. 60 Transmits a single poll report
• 61..599 Transmits messages at 600 second (10 minute) intervals, the value written to the
register is automatically rounded up to 600.
• 600 up Transmits messages at the requested intervals

5.8.18 Tone Only Message Response Registers


These four registers contain the return burst numbers to be transmitted by the terminal in response to a
tone only forward channel message. This message number may be one of the standard messages or a
valid user defined message number. If the value stored is zero then the terminal will not respond to
the tone only message but will output the message data over the serial port in the normal way using
the unsolicited ‘mf’ message or the user polled ‘mc’ and ‘mn’ messages.

5.8.19 Forward Channel Message Output Mode Register


The forward channel message output control register controls whether or not messages received over
the satellite by the terminal are output as unsolicited ‘mf’ messages. If the LSB of the register is clear
(default) then the terminal will pass any user forward channel messages received out of the serial port
as an ‘mf’ message paragraph 7.9.1.3). If the bit is set then the message output is disabled and the
messages must be read out by polling the terminal using the MC and MN commands (paragraphs
7.9.1.2 and 7.9.1.4 respectively).

© Satamatics Ltd Page 45 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.9 Scratchpad Module


Module ID = 0x06
Register addresses = Table 8

The scratchpad module provides 16 general-purpose 32 bit wide registers that may be used by the
operations.

5.9.1 Scratchpad Register Special Functions


The first three scratchpad registers have special functions assigned to them.

5.9.1.1 Scratchpad Register 0

Scratchpad register 0 contains the result value from the last operation performed or the value that
caused the alarm to trigger. Any value written to this register will be overwritten by the next active
alarm or operation performed.

5.9.1.2 Scratchpad Registers 1 and 2

These two registers are used as a data source for the return message types 0x16 and 0x17. The data
values held in these registers can be sent in a return burst message from the terminal.

© Satamatics Ltd Page 46 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.10 Operations Module


Module ID = 0x07
Register addresses = Table 9

5.10.1 Operation Definitions


An operation within the terminal takes a pre-programmed value and applies it to one of the registers
available in the functional module. An operation is triggered by an alarm, a timer or another
operation (a ‘chained’ operation).

Each operation is defined by two registers; the configuration register and the value register. The first
of these defines the target of the operation and the operation to be performed on that target register. It
also defines whether or not another operation is to be performed after this one, whether the operation
is part of a chain. The second, or value register, contains the value that is to be used in calculating the
value to be written to the target register. This may be a value to be written directly to the target, an up
or down increment to be applied to the current value or it may be a binary bit mask to be applied to
the target register value.

5.10.2 Operation Configuration Register


There is one operation configuration register for each of the 64 operations provided by the terminal.
The register is a 32-bit value divided up into fields as shown in the table below.
Bits Field Width Function
0 1 Operation Enable
1 1 Operation Chaining Enable
7..3 5 Chained Operation (Low Part)
11..8 4 Operation Function
12 1 Update Stored Script
13 1 Do Not Update Running Script
15..12 4 Reserved – leave as zero
18..16 3 Chained Operation (High Part)
19 1 Reserved – Leave as zero
27..20 8 Target Register Number
31..28 4 Target Module Number
Table 32 – Operation Configuration Register Field Definitions

5.10.2.1 Operation Enable

Operations are enabled by setting the Operation Enable bit of the relevant operation configuration
register. (Also see paragraph 5.10.5.

5.10.2.2 Operation Chaining

Operations may be configured so that they operate in a sequence. This is called a chain and is enabled
by setting the Operation Chaining Enable bit of the relevant operation configuration register. If
chaining is enabled then once an operation is complete the next operation in the chain will be
performed. The next operation in the chain is defined in the Chained Operation field (split into a Low
part and High part).

© Satamatics Ltd Page 47 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.10.2.3 Operation Function Codes

The 4 bit operation function code defines the operation to be performed on the target register. The
codes used to define the operations are listed in Table 33.

Function Operation Result of Operation TSL Syntax


Code
0x0 No Operation Target not written myTarget NOP
0x1 Store Value Target = Value myTarget = myValue
0x2 Bitwise And Target = Target & Value myTarget AND myValue
0x3 Bitwise Invert And Target = Target & ~Value myTarget AND NOT myValue
0x4 Bitwise Or Target = Target | Value myTarget OR myValue
0x5 Bitwise Invert Or Target = Target | ~Value myTarget OR NOT myValue
0x6 Bitwise Exclusive-Or Target = Target ^ Value myTarget XOR myValue
0x7 Unsigned Add Target = Target + Value myTarget += myValue
0x8 <reserved> <undefined>
0x9 Unsigned Subtract Target = Target - Value myTarget -= myValue
0xA <reserved> <undefined>
0xB Last Operation Target = Trigger Value (1st operation in chain) myTarget LASTOP
or
Result of last operation
0xC Shift N bits Left Target = Target << Value myTarget << n
0xD Shift N bits Right Target = Target >> Value myTarget >> n
0xE <reserved> <undefined>
0xF <reserved> <undefined>

Table 33 – Operation Function Codes

If an operation is performed on a write only register then the value of the target register before the
operation is performed will always be zero. This means that operations 2, 3 and 9 will always write 0
to the target register, 1, 4 and 7 will write value to the target, 5 and 6 will write the complement of
value to the target. The result value for each operation performed is written to Scratchpad register 0
as well as the target specified in the operation. Performing a NOP on a register reads its value into
scratchpad register 0 so that its value can be used by the LASTOP function.

5.10.2.4 Update Stored Script

Scripts are stored in non-volatile memory within the terminal and copied into and run from RAM
following power on. Operations can be configured such that any modifications to scripting registers
(e.g. timer value changes) either:

1. Survive a power cycle or;


2. Be lost on a power cycle or reset, with the script reverting to its originally uploaded state.

If the Update Stored Script bit in the operation control word is set then the value written to the Target
register will also be stored to non volatile memory so that the changes to the script will survive a
power cycle or reset. This is primarily intended to allow the updating of timer and alarm trigger
values but may be used to set other terminal configuration values.

5.10.2.5 Do Not Update Running Script

(See also 5.10.2.4.) When this bit is set the value written by the operation is not written to the active
Target register. But, if the Update Stored Script bit is set then the copy of the Target register stored in
non volatile memory will be updated, causing the operation of the script to be modified from the next
terminal power cycle or reset.

© Satamatics Ltd Page 48 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.10.2.6 Target Register ID

The target register for the operation is defined by a 12 bit address, made up from a 4 bit module ID
and an 8 bit register address. These addresses are defined in the separate module description sections
within this document.

5.10.3 Operation Value Register


The operation value register contains a 32 bit unsigned integer value that is used by the function
defined in the operation configuration register to modify the value stored in the operation’s target
register.

5.10.4 Disable Operations


Two 32-bit write only registers provide the ability to disable multiple operations. One register affects
operations 0 (LSB) to 31 (MSB), the other affects operations 32 (LSB) to 63 (MSB). Writing a 1 to
the relevant bit causes the operation to be disabled.
On being disabled, the values stored in the operation registers are held at their current state until the
operation is re-enabled.

5.10.5 Enable Operations


Two 32-bit write only registers provide the ability to enable multiple operations. One register affects
operations 0 (LSB) to 31 (MSB), the other affects operations 32 (LSB) to 63 (MSB). Writing a 1 to
the relevant bit causes the operation to be enabled.

5.10.6 Reset Operations


Two 32-bit write only registers provide the ability to reset multiple operations. One register affects
operations 0 (LSB) to 31 (MSB), the other affects operations 32 (LSB) to 63 (MSB). Writing a 1 to
the relevant bit causes the operation to be reset.

A reset causes the operation configuration and value registers to be cleared and these must be
reconfigured before they can be re-enabled.

5.10.7 Trigger Operations


Two 32-bit write only registers provide the ability to trigger multiple operations. One register affects
operations 0 (LSB) to 31 (MSB), the other affects operations 32 (LSB) to 63 (MSB). Writing a 1 to
the relevant bit causes the operation to be triggered.

When an operation is triggered any other operations that are chained after the triggered operation will
also be triggered. If more than one operation is triggered then the lowest numbered operation (or
operation chain) will be triggered first

© Satamatics Ltd Page 49 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

5.11 Constant Generator Module


Module ID = 0x0F
Register addresses = Table 10

The constant generator module is provided primarily to allow the insertion of constant data into the
user defined return burst formats, see Appendix B – Example User Message Definition. The module
provides 256 read only registers each of which returns a different 32 bit constant value. The values
returned by each of the registers are shown in Table 10.

© Satamatics Ltd Page 50 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

6 OVER AIR REMOTE CONTROL


The terminal uses transparent data messages with information type E to provide remote control of its
operation. These message formats are defined in the Satamatics message registry document, ref. [2].
Unrecognised type E messages will be ignored.

6.1 Trigger Operation Message


The trigger operation message causes the terminal to activate a script operation using the information
in the message to indicate the operation to be performed and providing a parameter value that may be
used by the operation. The data packet transmitted to the terminal has a length of either 8 or 40 bits as
defined below.

Bits Function Value


1..3 Command ID 3 bits (value 0x8)
4..8 Operation Number 5 bits
9..40 Parameter (Optional) 32 bits
Table 34 – Trigger Operation Forward Channel Message

The 32-bit parameter value is written into scratchpad register 0 from where it may be used by the first
operation in the programmed chain. If the parameter value is omitted then a value of zero is assumed
by the terminal.
NOTE – Operations that have to be triggered over the air must be defined within the first 32 of the
64 available. It is not possible to trigger operations 32 to 63 directly using a trigger
operation forward channel message.

6.2 Remote Terminal Poll


The remote terminal poll function allows the terminal to be interrogated remotely. The terminal will
respond to this message by sending return burst messages as requested by the two parameter fields in
the message.
The first parameter is a 16-bit value containing the message repeat interval. If this value is zero then
the terminal will stop generating messages. If the value is 1 then a single return burst will be
transmitted. For all other values the message will continue to be sent at the interval requested except
that the minimum gap between messages is 10 minutes, so values from 2 to 9 are increased internally
to 10.
The second parameter is the return burst message type. This is the code number for the message type
as listed in Table 29 or the message number for a user defined message (see section 5.8)

Bits Function Value


1..8 Command ID 8 bits (value 0xC0)
9..24 Message repeat interval 16 bits
25..32 Return Message type 8 bits
Table 35 – Remote Poll Forward Channel Message

© Satamatics Ltd Page 51 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

6.3 Remote Digital Output Control


This message sets the values seen on the digital output lines directly. The value sent in this message
will overwrite any calculated value written to the outputs using a script or local external controller.

Bits Function Value


1..8 Command ID 8 bits (value 0xC1)
9..16 Digital output value 8 bits
Table 36 - Remote Digital Output Control Forward Channel Message

6.4 Set Target Position


This message sets the latitude and longitude value to be used for one of the GPS target points.

Bits Function Value


1..8 Command ID 8 bits (value 0xC3)
9..16 Target ID 8 bits
17 Response Request 1
18..20 Unused 3
21 Hemisphere (0 = N, 1 = S) 1
22..40 Latitude in seconds 19
41..43 Unused 3
44 Hemisphere (0 = E, 1 = W) 1
45..64 Longitude in seconds 20 bits
Table 37 – Target Position Definition Message

© Satamatics Ltd Page 52 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

6.5 Read/Write Terminal Register


This message allows the value of any of the terminal scripting/configuration registers listed in section
5 to be polled and/or modified remotely using a forward channel message. The changes may be made
to the running script, to the stored initialisation script or to both. It is possible to modify multiple
registers with a single forward channel message and to receive a return message from the terminal
containing the data written to the modified register.

Bits Function Value


1..8 Command ID 8 bits
value 0xC4 – No return message confirmation
value 0xC5 – Return message confirmation required
9..12 Module ID 4 bits
13..20 Register Address 8 bits
21 Do Not Update Running Script 1 – Do not update running script
0 – Update running script register
22 Update Stored Script 1 – Write value to stored script
0 – Do not update the stored script value
23..24 Number of Data Bytes 0 – No data, use zero
1 – 8 bits of data, higher bits assumed zero
2 – 16 bits of data, higher bits assumed zero
3 – 32 bits of data in the message
Variable Data Value written to the scripting register
Table 38 – Remote Register Read/Write Message

To reduce the amount of data that is transmitted to the terminal the message contains a ‘number of
data bytes’ field that allows the data to be sent as zero, one, two or four bytes depending upon the size
of the target register or the data value to be written. Any bits not included in the data value sent are
assumed by the terminal to be zero. If the ‘number of data bytes’ is set to zero then no data field is
required and, if a write function has been selected, a value of zero will be written to the target
scripting register.
If the message command ID is 0xC5 then the terminal will transmit a return channel message for each
target register. If the ‘Do Not Update Running Script’ bit is set then the value returned will be the
unmodified contents of the running script register. If the ‘Do Not Update Running Script’ bit is clear
the value returned will be the updated running script copy of the register, providing confirmation that
the change has occurred.
Multiple register updates are performed by repeating the ‘Module ID’ to ‘Data’ fields for each of the
registers to be updated. This is demonstrated by the example below which writes to three registers
using a single forward channel message:

© Satamatics Ltd Page 53 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Field Data Value Description


Command ID 0xC4 0xC4 Write Register
Module 0x1 Timer module number
Register 0x43 Register address being accessed within the module
RAM 0 Update value in RAM
EEPROM 0 Not update EEPROM store
Payload Size 1 8 bit payload data
Payload Data 0x64 Data value written to the script register
Module 0x2 Alarm module number
Register 0x24 Register address being accessed within the module
RAM 1 Not update value in RAM
EEPROM 1 Update EEPROM store
Payload Size 2 16 bit payload data
Payload Data 0x2317 Data value written to the script register
Module 0x7 Operation module number
Register 0x26 Register address being accessed within the module
RAM 0 Update value in RAM
EEPROM 1 Update EEPROM store
Payload Size 0 0 bit payload data
Table 39 – Example of Multiple Register Update Message Data Structure
The data structure shown in Table 39 is then built into the message payload:
c4 1 43 1 64 2 24 E 2317 7 26 4

6.6 Return ‘Read Register’ Message Format


The return message sent by the terminal in response to a read register command is identified by a
message descriptor field value of 0x2B. The control flags, destination address and acknowledge flags
are all set to the values held by the terminal at the time that the message is sent.
Field Size Description
Control Flags 4 bits From Script
Destination Address 8 bits From Script
Message Descriptor 8 bits 0x2B
Module ID 4 bits Module address
Register Number 8 bits Register address being reported
Register Contents 32 bits Value read from the script register
Zero data 20 bits Zero data
Ack Flags 2 bits From Script
Table 40 – Return Burst Message Format

© Satamatics Ltd Page 54 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7 SERIAL COMMAND INTERFACE

7.1 Command & Response Formats

7.1.1 Command format


The commands on this interface have a format as shown below.

<char><char><optional_space><parameter_list><carriage_return>
where:
<char> is a single upper case ASCII character.
<optional_space> is one or more ASCII space characters that may be inserted between the
command header and the parameter list.
<parameter_list> is a command specific sequence of ASCII characters defining the
parameters to the command.
<carriage_return> is the ASCII code for carriage return (0x0D).

The <carriage_return> character on a command may be followed by a <line-feed> character.

In the following Command description sections the following conventions apply


<SP> is the ASCII code for a space character (0x20)
<CR> is the ASCII code for a carriage return (0x0D)
<LF> is the ASCII code for a line feed character (0x0A)
Note: The maximum number of characters in any command, from the first <char> to the
<carriage_return> is 39. If this length is exceeded, for example by adding extra
<optional_space> characters then an error message will be generated and the command will
be ignored.

7.1.2 Response Format


The response to each command mirrors the command format with the two command characters
returned in lower case. The exact response returned for each command is detailed in its command
description in sections 7.3 to 7.14.

© Satamatics Ltd Page 55 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.2 Command Availability


The terminal may be configured to operate in one of 5 power modes (see paragraph 5.3.4) one of
which is ‘Sleep’ mode. In sleep mode as much of the terminal hardware as possible is turned off to
reduce power consumption. In this mode the serial port output drivers are disabled and the majority
of the commands available to the terminal are not recognised. The commands that are recognised are:

• CE - Get/Set Terminal Power Control State


• CU - Get/Set Terminal User Power Mode
• PI - Terminal Reset
• PS - Enable/Disable Scripting
These commands allow the user to put the terminal into another mode where the required command is
active, to reset the terminal operation to a default state and to turn off the script operation within the
terminal to allow recovery from a scripting fault when the terminal is continuously being switched
back into sleep mode.

© Satamatics Ltd Page 56 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.3 Terminal Configuration Module Commands

7.3.1 CA – Get/Set the Terminal Satellite Selection Mode


Get/set the auto satellite selection mode for the Terminal.

Command Format CA<mode>


CA?<CR>

Response Format ca<SP><mode><CR><LF>

<mode> 4 character ASCII hex representation of a 16 bit number. The value is


stored in the Satellite Selection Mode register (module 0x0, register
0x02) - see paragraph 5.3.3

7.3.2 CB – Select Ocean Region


Get/set the ocean region in use by the terminal.

Command Format CB<ocean_region><CR>


CB?<CR>

Response Format cb<SP><ocean_region><CR><LF>

<ocean_region> 2 character ASCII hex representation of a byte. The value is stored in


the Ocean Region Selection register (module 0x0, register 0x01) - see
paragraph 5.3.1.

7.3.3 CE – Get/Set the Terminal Power Control State


Get/set the power control state for the Terminal.

Command Format CE<power_ctrl>


CE?<CR>

Response Format ce<SP><power_ctrl ><CR><LF>

<power_ctrl> 2 digit ASCII hex representation of a byte value. The value is stored
in the Power Control register (module 0x0, register 0x03) – see
paragraph 5.3.4.

© Satamatics Ltd Page 57 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.3.4 CF –Set the Terminal to Factory Defaults


The CF command sets the terminal configuration to a known default state (see Ref.[1]). The script
timer, alarm, operation and target point definitions are cleared; the terminal is then configured such
that on power-up it will acquire GPS, tune to the best ocean region for the terminal location and
transmit a single position report. The transmission function can be reset by issuing a valid MP
command (paragraph 7.9.2.6) or by changing the terminal remote polling configuration using a
forward satellite channel message.

Command Format CF 1600CDA<CR>

Response Format cf<SP>01600CDA<CR><LF>

The CF? command is used to determine whether the terminal has been configured to transmit its
position report message on power up:

Command Format CF?<CR>

Response Format cf<SP><state><CR><LF>

<state> single ASCII digit; 1 if the terminal is configured to transmit on


power up and 0 if it is not.

7.3.5 CI – Get/Set the Service ID Selection


Get/set the Service ID Selection number. The 5 pre-programmed service IDs held within the terminal
can be read using the ‘DS TJ?’ command (section 7.14.7). This command selects one of these service
ID configurations to be active.

Command Format CI<service><CR>


CI?<CR>

Response Format ci<SP><service><CR><LF>

<service> single ASCII digit representation of a 4 bit number (valid values 0 to


4). The value is stored in the Service ID Selection register (module
0x0, register 0x01) – see paragraph 5.3.2

7.3.6 CN – NMEA Message Output Control


Enable the output of one or more NMEA format messages.

Command Format CN<control_flags><CR>


CN?<CR>

Response Format cn<SP><control_flags><CR><LF>

<control_flags> 2 digit ASCII hex representation of a byte value. The value is stored
in the NMEA output control register (module 0x0, register 0x20) –
see paragraph 5.3.11.

© Satamatics Ltd Page 58 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.3.7 CP – Get MSP Firmware Version


Get the version number of the MSP processor firmware.

Command Format CP?<CR>


Response Format cp<SP><MSP_version ><CR><LF>

<MSP_version> 4 ASCII characters comprising the MSP version string. The value is
read from the MSP firmware version register (module 0x0, register
0x06) – see paragraph 5.3.6.

7.3.8 CR – Reload Terminal Application Script


Reload the application script from non-volatile memory store. This resets the timers, alarms,
operations and terminal configuration to the state that is set following a power on of the terminal.

Command Format CR<CR>

Response Format cr<CR><LF>

7.3.9 CS – Get/Set Application Script Software Version


Get or set the version number of the application script in use within the terminal.

Command Format CS<script_version><CR>


CS?<CR>

Response Format cs<SP><script_version><CR><LF>

<script_version> 4 ASCII characters comprising the script version string. The


meaning of the 4 characters is defined by the user. The version string
is stored in the Script application version register (module 0x0,
register 0x07) – see paragraph 5.3.7.

7.3.10 CU – Get/Set Operating Power Mode


The CU command provides a shorthand method of setting the operating power mode. Bits within the
Power Control register (module 0x0, register 0x03) are set/cleared according to the power mode
selected (see paragraph 5.3.4). This will therefore affect the value returned by the CE? command.
Similarly, using the CE command to set/clear bits in the Power Control register can change the
operating power mode and therefore the value returned by the CU? command.

Command Format CU<power_mode><CR>


CU?<CR>

Response Format cu<SP><power_mode><CR><LF>

<power_mode> single ASCII digit string containing the operating power mode. Valid
values are shown in Table 41 below.

© Satamatics Ltd Page 59 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Value Mode
0 Sleep – Minimum power consumption mode
1 Standby – GPS off, Inmarsat-D off
2 GPS Tracking – GPS on, Inmarsat-D off
3 Static – GPS off, Inmarsat-D on
4 Mobile – GPS on, Inmarsat-D on
Table 41 – Operating Power Modes

7.3.11 CV – Get DSP Software Version


The CV command is used to get the DSP software version number.

Command Format CV?<CR>

Response Format cv<SP><DSP_version><CR><LF>

<DSP_version> 4 ASCII characters comprising the DSP version string. The value is
read from the DSP firmware version register (module 0x0, register
0x05) – see paragraph 5.3.5.

7.3.12 CW – Wipe Script Software


The CW command is used to wipe the terminal script. The script is cleared from the RAM and all
timers, alarms and operations are reset. If a script has been stored in the non-volatile memory then
this is NOT cleared and will be reloaded if the processor is reset or a CR command is issued. The
version string set for the script via the CS command is used as a password to prevent inadvertent
program erasure. If the password is entered incorrectly then the stored script is not overwritten and
the version string returned will be set to ‘****’.

Command Format CW<script_version><CR>

Response Format cw<SP><script_version><CR><LF>

<script_version> 4 ASCII characters comprising the script version string.

7.3.13 CZ – Store Script in Non-Volatile Memory


This command writes the current script application to non-volatile memory and has the equivalent
effect as writing to the ‘Store Application Script’ scripting register – see paragraph 5.3.8. The script
version string is used as a password to prevent inadvertent overwriting of the stored script. If the
password is entered incorrectly then the stored script is not overwritten and the version string returned
will be set to ‘****’.

Command Format CZ<script_version><CR>

Response Format cz<SP><script_version><CR><LF>

<script_version> 4 ASCII characters comprising the script version string. The first two
characters are the major version and the second two characters the
minor version number.

© Satamatics Ltd Page 60 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.4 Interface Module Commands

7.4.1 IA – Get Analogue Input


The IA command is used to read the value measured by one of the A/D converter channels. These
values are held in the Interface Module registers (module 0x03, registers 0x10 to 0x17) – see
paragraph 5.6.2.

Command Format IA<channel>?<CR>

Response Format ia<SP><channel><SP><value><CR><LF>

<channel> 2 digit ASCII hex value indicating the channel number being read.
There are eight interface ‘channels’ but the interfaces available
depend on the hardware configuration as detailed in Table 24.

<value> 3 digit ASCII hex number containing the result of the A/D
conversion. If the channel being read is not configured as an
analogue input then the result returned will be 0.

7.4.2 IC – Configure Inputs/Outputs


The IC command is used to configure the eight I/O channels.

Command Format IC<configuration><CR>


IC?<CR>

Response Format ic<SP><configuration><CR><LF>

<configuration> 8 ASCII hex characters representing a 32-bit word value. The value
is stored in the I/O Configuration register (module 0x03, register
0x02) – see paragraph 5.6.1 for valid i/o configurations. If an invalid
configuration is entered for any of the channels, no change in any of
the channel configurations will occur, and an error will be reported,

© Satamatics Ltd Page 61 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.4.3 ID – Get Digital Inputs


The ID command is used to read the states of those interface channels configured as digital inputs.

Command Format ID?<CR>

Response Format id<SP><value><CR><LF>

<value> 2 character ASCII hex value containing the digital input states of the
eight interface channels. The input state will be returned as 0 for
interface channels not configured as digital inputs. The value is read
from the Digital Input States register (module 0x03, register 0x00) –
see paragraph 5.6.3.

7.4.4 IE – Get/Set Digital Outputs


The IE command is used to set or read back the states of those interface channels configured as digital
outputs.

Command Format IE<value><CR>


IE?<CR>

Response Format ie<SP><value><CR><LF>

<value> 2 character ASCII hex value containing the digital output states of
the eight interface channels. The output state will be returned as 0 for
interface channels not configured as digital outputs. The value is
stored in the Digital Output States register (module 0x03, register
0x01) – see paragraph 5.6.4.

7.4.5 II – Get GEM-100 External Power Supply Status


This command is used to get the status of the power supplies connected to the GEM-100. The status is
stored in the Power Supply Status register (module 0x00 register 0x0A) – see paragraph 5.3.10.

Command Format II?<CR>

Response Format ii<SP><status><CR><LF>

<status> single character number representing the two status bits. The
GEM-100 external power supply is present when the LSB is set, the
GEM-100 solar supply is present when the MSB (of 2) is set.

If no GEM-100 unit is connected, this command will always reply with the response ‘ii 1’ indicating
that the external supply is present and that there is no solar panel supply.

© Satamatics Ltd Page 62 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.4.6 IP – Get MSP Power Supply Level


The IP command is used to read the measured supply voltage rail used by the MSP processor. The
associated scripting register is module 0x03, register 0x18 – see paragraph 5.6.5.

Command Format IP?<CR>

Response Format ip<SP><value><CR><LF>

<value> 4 character decimal number representing the MSP supply voltage in


mV. Typically this value will be around 325.

7.4.7 IO – Configure GEM-100 Battery Power Output


The IO command is used to set/get the state of the GEM-100 battery power output line. (This
command is not available if the GEM-100 is not utilised.) The associated scripting register is module
0x03, register 0x03 – see paragraph 5.6.11.

Command Format IO<value><CR>


IO?<CR>

Response Format io<SP><value><CR><LF>

<value> single ASCII character indicating the state of the battery power
output line.
0 = I/O line 7 is configured as a normal I/O line
1 = I/O line 7 is connected through a 50mA fuse to the
GEM-100 battery pack (Nominal output voltage 12V).

7.4.8 IQ – Get GEM-100 Battery Temperature


The IQ command is used read the measured temperature value from GEM-100 battery pack sensor.
The value returned is the battery temperature in Celsius. A value of 255 is returned if a battery pack is
not fitted, and a value of 0 is always returned if a non rechargeable battery pack is fitted. The
associated scripting register is module 0x03, register 0x1C – see paragraph 5.6.10. The scripting
register holds the temperature to a 0.1 degree resolution and the value held in the register is therefore
10 times the value returned by the IQ command.

Command Format IQ?<CR>

Response Format iq<SP><value><CR><LF>

<value> 3 character decimal number representing the GEM-100 battery


temperature in degrees Celsius.

If no GEM-100 is connected, this command will always reply with the response ‘iq 255’ indicating
that no battery is fitted.

7.4.9 IS – Get External Power Supply Level


The IS command is used to read the measured value of the external power supply. The associated
scripting register is module 0x03, register 0x19 – see paragraph 5.6.6.

© Satamatics Ltd Page 63 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Command Format IS?<CR>

Response Format is<SP><value><CR><LF>

<value> 5 character decimal number representing the external supply voltage


in mV.

If a GEM-100 is used the value returned is the external supply voltage applied to the GEM-100.

7.4.10 IT – Get Terminal Temperature


The IT command is used to read the temperature sensor in the terminal. The value returned is for
indication only. The associated scripting registers are module 0x03, registers 0x1A and 0x1F – see
paragraphs 5.6.8 and 5.6.9.

Command Format IT?<CR>

Response Format it<SP><temp_value><CR><LF>

<temp_value> signed ASCII string containing the measured temperature value in


Celsius. The format of the temperature value is +dd

7.4.11 IU – Get/SET GEM-100 User LED State


The IU command is only available if a GEM-100 is utilised and is used to set or read the state of the
user LED on the GEM front panel.

Command Format IU<SP><colour><CR>


IU?<CR>

Response Format IU<SP><colour><CR>

<colour> single decimal number (0 to 3) representing the colour of the user


LED. The value is stored in the User LED state register (module
0x03, register 0x30) - see paragraph 5.6.12.

7.4.12 IX – Get GEM-100 Battery Power Supply Level


The IX command is used to read the measured battery supply voltage of the GEM-100. The associated
scripting register is module 0x03, register 0x1B – see paragraph 5.6.7

Command Format IX?<CR>

Response Format ix<SP><value><CR><LF>

<value> 5 character decimal number representing the battery supply voltage


in mV.

If a GEM-100 is not utilised this command will always respond with ‘ix 00000’.

© Satamatics Ltd Page 64 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.5 Timer Module Commands


All of the commands in this section, with the exception of TT (section 7.5.7) are used to configure and
monitor the timers for use in scripting. Each command is associated with a Timer module (module
0x01) register – see section 5.4 for details.

7.5.1 TC – Configure Timer


The TC command is used to configure timer channels. Timers can be programmed to trigger script
operation(s) after a delay or at a time of day.

Command Format TC<timer_number><SP><config_value><CR>


TC<timer_number>?<CR>

Response Format tc<SP><timer_number><SP><config_value><CR><LF>

<timer_number> 2 character ASCII hex representation of the timer channel number


(00..1F)

<config_value> 8 character ASCII hex representation of the 32 bit configuration


value.

7.5.2 TD – Disable Timers


The TD command is used to disable the selected timer channels. The values stored in the timer
registers are held at their current state and operation may be resumed with a TE command.

Command Format TD<timer_mask><CR>

Response Format td<SP><timer_mask><CR><LF>

<timer_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 31 (MSB) represent timer channels 0 to 31 respectively. If a
bit is set, the corresponding timer channel is disabled.

7.5.3 TE – Enable Timers


The TE command is used to enable all of the selected timer channels.

Command Format TE<timer_mask><CR>

Response Format te<SP><timer_mask><CR><LF>

<timer_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 31 (MSB) represent timer channels 0 to 31 respectively. If a
bit is set, the corresponding timer channel is enabled.

7.5.4 TM – Get/Set Timer Trigger Value


The TM command is used to read or set the trigger value for a timer channel. This command allows
the terminal count value to be modified without modifying the timer operating mode. If the trigger

© Satamatics Ltd Page 65 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

value is modified for a timer configured as an interval (delay) timer then the count value will be set
back to zero, restarting the delay.

Command Format TM<timer_number><SP><trigger_value><CR>


TM<timer_number>?<CR>

Response Format tm<SP><timer_number><SP><trigger_value><CR> <LF>

<timer_number> 2 character ASCII hex representation of the timer channel number


(00..1F)

<trigger_value> 6 character ASCII hex representation of the 24 bit timer trigger value.

7.5.5 TR – Reset Timers


The TR command is used to reset the selected timer channels. The timer configuration and count
registers are cleared. The timers must be reconfigured before they can be re-enabled.

Command Format TR<timer_mask><CR>

Response Format tr<SP><timer_mask><CR><LF>

<timer_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 31 (MSB) represent timer channels 0 to 31 respectively. If a
bit is set, the corresponding timer channel is reset.

7.5.6 TS – Restart Timers


The TS command is used to restart the selected timer channels. The count register is cleared and the
timer is enabled.

Command Format TS<timer_mask><CR>

Response Format ts<SP><timer_mask><CR><LF>

<timer_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 31 (MSB) represent timer channels 0 to 31 respectively. If a
bit is set, the corresponding timer channel is restarted.

7.5.7 TT – Get Current Time and Date (UTC)


The TT command is used to get the current time and date from the terminal.

Command Format TT?<CR>

Response Format tt<SP><time_string><CR><LF>

<time_string> ASCII string containing the current time and date. The format of this
string is hh:mm:ss dd/mm/yyyy.

© Satamatics Ltd Page 66 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.5.8 TV – Get Current Timer Value


The TV command is used to get the current count value of one of the 32 timer channels.

Command Format TV<timer_number>?<CR>

Response Format tv<SP><timer_number><SP><timer_value><CR><LF>

<timer_number> 2 character ASCII hex representation of the timer channel number


(00..1F).

<timer_value> 8 character ASCII hex representation of the 32 bit value held in the
timer channel count register.

© Satamatics Ltd Page 67 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.6 Alarm Module Commands


All of the commands in this section are used to configure and monitor the alarms for use in scripting.
Each command is associated with an Alarm module (module 0x02) register – see section 5.5 for
details.

7.6.1 AC – Configure Alarms


The AC command is used to configure the alarm channel.

Command Format AC<alarm_number><SP><config_value><CR>


AC<alarm_number>?<CR?

Response Format ac<SP><alarm_number><SP><config_value><CR><LF>

<alarm_number> 2 character ASCII hex representation of the alarm channel number


(00..1F).

<config_value> 8 character ASCII hex representation of a 32 bit value. The value is


written to the appropriate Alarm Configuration Register

7.6.2 AD – Disable Alarms


The AD command is used to disable the alarm channels. The values stored in the alarm registers are
held at their current state and operation may be resumed with an AE command.

Command Format AD<alarm_mask><CR>

Response Format ad<SP><alarm_mask><CR><LF>

<alarm_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 31 (MSB) represent alarm channels 0 to 31 respectively. If
a bit is set, the corresponding alarm channel is disabled.

7.6.3 AE – Enable Alarms


The AE command is used to enable the alarm channels indicated by the mask value.

Command Format AE<alarm_mask><CR>

Response Format ae<SP><alarm_mask><CR><LF>

<alarm_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 31 (MSB) represent alarm channels 0 to 31 respectively. If
a bit is set, the corresponding alarm channel is enabled.

© Satamatics Ltd Page 68 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.6.4 AF – Trigger Alarms


The AF command is used to trigger (fire) the alarm channels.

Command Format AF<alarm_mask><CR>

Response Format af<SP><alarm_mask><CR><LF>

<alarm_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 31 (MSB) represent alarm channels 0 to 31 respectively. If
a bit is set, the corresponding alarm channel is triggered.

7.6.5 AR – Reset Alarms


The AR command is used to reset the latch on one or more of the alarm channels. This re-enables an
alarm that has been configured as a latching alarm and has been triggered once already. Resetting an
alarm that has either not triggered or is not configured as a latching alarm will have no effect.

Command Format AR<alarm_mask><CR>

Response Format ar<SP><alarm_mask><CR><LF>

<alarm_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 31 (MSB) represent alarm channels 0 to 31 respectively. If
a bit is set, the corresponding alarm channel is reset.

7.6.6 AT – Alarm Threshold


The AT command is used to set the threshold value used by the alarm channel.

Command Format AT<alarm_number><SP><threshold_value><CR>


AT<alarm_number>?<CR>

Response Format at<SP><alarm_number><SP><threshold_value><CR><LF>

<alarm_number> 2 character ASCII hex representation of the alarm channel number


(00..1F).

<threshold_value> 8 character ASCII hex representation of the 32 bit value to be stored


in the alarm channel threshold register.

© Satamatics Ltd Page 69 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.7 Operation Module Commands


All of the commands in this section are used to configure and monitor the operations for use in
scripting. Each command is associated with an Operations module (module 0x07) register – see
section 5.10 for details.

7.7.1 OC – Configure Operation


The OC command is used to configure an operation to be taken in response to a timer event or alarm
condition. It may also be used to read back the current configuration of an operation.

Command Format OC<operation><SP><configuration><SP><value><CR>


OC<operation>?<CR>

Response Format oc<SP><operation><SP><configuration><SP><value><CR><LF>

<operation> 2 digit hex number in the range 0x00..0x3F

<configuration> 8 digit ASCII hex number representing a 32 bit configuration value


for the operation number.

<value> 8 character ASCII hex number value that is used in performing the
operation.

7.7.2 OD – Disable Operations


The OD command is used to disable the operation channels. On being disabled, the values stored in
the operation registers are held at their current state and operation may be resumed with an OE
command. This command operates on the first 32 operation channels only. The second 32 channels
can be disabled by using the RW command to write a mask value to module 7 register 0x44.

Command Format OD<operation_mask><CR>

Response Format od<SP><operation_mask><CR><LF>

<operation_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 32 (MSB) represent operation channels 0 to 32 respectively.
If a bit is set, the corresponding operation channel is disabled.

© Satamatics Ltd Page 70 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.7.3 OE – Enable Operations


The OE command is used to enable the operation channels. The operations indicated by the bits set in
the mask value will be enabled. This command operates on the first 32 operation channels only. The
second 32 channels can be enabled by using the RW command to write a mask value to module 7
register 0x45.

Command Format OE<operation_mask><CR>

Response Format oe<SP><operation_mask><CR><LF>

<operation_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 32 (MSB) represent operation channels 0 to 32 respectively.
If a bit is set, the corresponding operation channel is enabled.

7.7.4 OR – Reset Operations


The OT command is used to reset operation channels. A reset causes the operation configuration and
value registers to be cleared and these must be reconfigured before they can be re-enabled. This
command operates on the first 32 operation channels only. The second 32 channels can be reset by
using the RW command to write a mask value to module 7 register 0x46.

Command Format OR<operation_mask><CR>

Response Format or<SP><operation_mask><CR><LF>

<operation_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 32 (MSB) represent operation channels 0 to 32 respectively.
If a bit is set, the corresponding operation channel is reset.

7.7.5 OT – Trigger Operations


The OT command is used to trigger the operation channels. When an operation is triggered using this
command any other operations that are chained after the triggered operation will also be triggered. If
more than one operation is triggered in the single command then the lowest numbered operation (or
operation chain) will be triggered first. This command operates on the first 32 operation channels
only. The second 32 channels can be triggered by using the RW command to write a mask value to
module 7 register 0x47.

Command Format OT<operation_mask><CR>

Response Format ot<SP><operation_mask><CR><LF>

<operation_mask> 8 character ASCII hex representation of a 32 bit mask value. Bits 0


(LSB) to 32 (MSB) represent operation channels 0 to 32 respectively.
If a bit is set, the corresponding operation channel is triggered.

© Satamatics Ltd Page 71 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.8 GPS Module Commands

7.8.1 GPS Status and Configuration Commands

7.8.1.1 GM – Get GPS Satellite Signal Strengths

The GM command requests the satellite C/N0 (level of signal strength) for the satellites in view by the
GPS. The command returns values for each channel processed by the GPS. Unused channels have a
satellite ID of zero.

Command Format GM?<CR>

Response Format gm<SP><satellite_data><CR><LF>

<satellite_data> set of 16 groups of the form ss-nn each separated by a space.


ss – Satellite ID number in hexadecimal.
xx – Signal C/N0 (dBHz) in hexadecimal.

For an initial position fix the GPS needs to acquire and track 5 satellites. Once the position fix has
been obtained the GPS can maintain a latitude/longitude position with just 3 satellites visible. The
satellites will normally track with a C/N0 value of 1E (30 decimal) or higher. Strong satellites have
C/N0 values above 28 (40 decimal).

7.8.1.2 GS – Get GPS Status

The GS command is used to get the validity of the GPS position report data.

Command Format GS?<CR>

Response Format gs<SP><valid_flag><CR><LF>

<valid_flag> 2 character ASCII hex representation of a byte.


0x00 – GPS data invalid
0x01 – GPS data valid.
The value is obtained from the GPS Status register (module 0x04,
register 0x00) – see paragraph 5.7.1.1.

7.8.1.3 GE – Get GPS Software Version Number

The ‘GE’ Command requests the firmware version report message from the GPS unit.

Command Format GE?<CR>

Response Format ge<SP><version_string><CR><LF>

<version_string> ASCII character string containing the GPS chip set version identifier.
The following is an example:

4.00 (25682)

© Satamatics Ltd Page 72 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.8.2 GPS Position Commands


GPS position values are read from the appropriate GPS module registers (module 0x04) – see section
5.7.1

7.8.2.1 GA – Get Current GPS Altitude

The GA command is used to read the current altitude as reported by the GPS.

Command Format GA?<CR>

Response Format ga<SP><altitude_value ><CR><LF>

<altitude_value> 5 character ASCII decimal number giving the altitude in metres. The
value reported is based on the WGS-84 datum.

7.8.2.2 GH – Get Current GPS Heading

The GH command is used to read the current course over the ground as reported by the GPS.

Command Format GH?<CR>

Response Format gh<SP><heading_value><CR><LF>

<heading_value> 4 character ASCII decimal number giving the heading in 0.1 degree
steps.

The heading value reported is calculated by the GPS based on the motion seen during the fix
calculation and from the last position fix. The specification for the heading accuracy is:

< 0.5 degree of error (User velocity=30m/s [60 mph], 50% probability, open sky)

Note that with speed over ground <0.75m/s or where the terminal is stationary, the heading value
returned will be random due to the very small difference between position samples.

7.8.2.3 GP – Get Current GPS Position

The GP command is used to read the current position reported by the terminal GPS unit.

Command Format GP?<CR>

Response Format gp<SP><latitude><SP><longitude><CR><LF>

<latitude> 13 character ASCII string reporting the latitude value to 0.01


seconds. The format of the string is:
+DDD MM SS.SS
<longitude> 13 character ASCII string reporting the longitude value to 0.01
seconds. The format of the string is:
+DDD MM SS.SS

© Satamatics Ltd Page 73 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.8.2.4 GV – Get Current GPS Speed

The GV command is used to read the current speed reported by the terminal GPS unit.

Command Format GV?<CR>

Response Format gv<SP>< speed_value ><CR><LF>

<speed_value> 4 character ASCII decimal number giving speed in units of 0.1m/s.

The speed value reported is calculated by the GPS chipset based on the motion seen during the fix
calculation and from the last position fix.

7.8.3 Geofence Commands


An example of Geofence definition is provided in APPENDIX A – Example Geofence Definition.

7.8.3.1 GD – Define Geofence

The GD command initialises the Geofence definition procedure. It sets the number of points and
zones that are used in the definition of the specified the fence number.

If the number of points is set to zero for a fence then the geofence data in the terminal is deleted for
the selected fence.

Command Format GD<fence><SP><points><SP><zones><CR>


GD<fence>?<CR>

Response Format gd<SP><fence><SP><points><SP><zones><CR><LF>

<fence> single ASCII digit, either 1 or 2 indicating the fence number to be


defined.

<points> 2 character ASCII decimal number indicating the number of points in


the geofence being defined.

<zones> 2 character ASCII decimal number indicating the number of zones in


the geofence being defined.

7.8.3.2 GF – Define Geofence Point

The GF command is used to define a single point that forms a corner of the geofence being defined.

Command Format GF<fence><SP><point><SP><latitude><SP><longitude><CR>


GF<fence><SP><point>?<CR>

Response Format gf<SP><fence><SP><point><SP><latitude><SP><longitude><CR><LF>

<fence> single ASCII digit, either 1 or 2 indicating the fence number to be


defined.

<point> 2 character ASCII decimal number indicating the number of the point
in the geofence being defined.

© Satamatics Ltd Page 74 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

<latitude> 13 character ASCII string reporting the latitude value to 0.01


seconds. The format of the string is:
+DDD MM SS.SS
<longitude> 13 character ASCII string reporting the longitude value to 0.01
seconds. The format of the string is:
+DDD MM SS.SS

7.8.3.3 GW – Store Geofence Data

The GW command validates the geofence data that has been defined using the GF, GD and GZ
commands and if it is complete, enables the fence for use.

Command Format GW<fence><SP><points><SP><zones><CR>

Response Format gw<SP><fence><SP><points><SP><zones><CR><LF>

<fence> single ASCII digit (1 or 2) indicating the fence number to be defined.

<points> 2 character ASCII decimal number indicating the number of points in


the geofence being defined.

<zones> 2 character ASCII decimal number indicating the number of zones in


the geofence being defined.

7.8.3.4 GZ – Define Geofence Zone

The GZ command defines the zones available within the overall fenced area. Each zone definition
has at least 3 point numbers indicating the co-ordinate sets that are used as the corners of the zone.
The points used to define the zone must run in an anti-clockwise direction around the zone with the
internal angle at each corner being less than 180°. It is the responsibility of the programmer to check
that the zone definition is valid. The terminal does not validate the zone definition against these rules.

Command Format GZ<fence><SP><zone><SP><num_points><SP>


<point_1><SP><point_2>…<SP><point_n><CR>

GZ<fence><SP><zone>?<CR>

Response Format gz<SP><fence><SP><zone><SP><num_points><SP>


<point_1><SP><point_2>…<SP><point_n><CR><LF>

<fence> single ASCII digit (1 or 2) indicating the fence number to be defined.

<zone> 2 character ASCII decimal number indicating the zone number in the
geofence being defined.

<num_points> 2 character ASCII decimal number indicating the number of points in


the zone being defined

<point_1><point_n> n x 2 character ASCII decimal numbers indicating the number of the


point to be included in the geofence zone being defined.

© Satamatics Ltd Page 75 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.8.4 Reference Position Commands

7.8.4.1 GL – Distance to Reference

The GL command returns the distance between the stored reference point and the current position as
reported to the terminal by the GPS receiver in the terminal. The distance is calculated assuming that
the Earth is a sphere with a radius of 6371km.

Command Format GL?<CR>

Response Format gl <SP><distance><CR><LF>

<distance> 8 character ASCII decimal representation of the calculated distance


in metres. The returned value is derived from the Distance to
Reference register (module 0xx04, register 0x20) – paragraph 5.7.2.4

7.8.4.2 GR – Define Reference Point

The GR command is used to set or interrogate the reference point stored in the terminal. Associated
scripting registers are module 0x04, registers 0x11 and 0x12 – see paragraphs 5.7.2.2 and 5.7.2.3.

Command Format GR<latitude><SP><longitude><CR>


GR?<CR>

Response Format gr<SP><latitude><SP><longitude><CR><LF>

<latitude> 13 character ASCII string reporting the latitude value to 0.01


seconds. The format of the string is:
+DDD MM SS.SS
<longitude> 13 character ASCII string reporting the longitude value to 0.01
seconds. The format of the string is:
+DDD MM SS.SS

7.8.4.3 GX – Store Current Position as Reference

The GX command takes the current position as read from the terminal GPS receiver and stores it as
the terminal reference position.

Command Format GX<CR>

Response Format gx<SP><latitude><SP><longitude><CR><LF>

<latitude> 13 character ASCII string reporting the latitude value to 0.01


seconds. The format of the string is:
+DDD MM SS.SS
<longitude> 13 character ASCII string reporting the longitude value to 0.01
seconds. The format of the string is:
+DDD MM SS.SS

© Satamatics Ltd Page 76 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.8.5 Target Position Commands


Associated scripting registers are module 0x04, registers 0x40 to 0x5F – see section 5.7.3.

7.8.5.1 GK – Distance to Target Position

The GK command returns the distance between one of the stored target points and the current position
as reported to the terminal by the GPS receiver in the terminal. The distance is calculated assuming
that the Earth is a sphere with a radius of 6371km.

Command Format GK<point_id>?<CR>

Response Format gl<SP><point_id><SP><distance><CR><LF>

er<SP><target_not_defined><CR><LF>

<point_id> single ASCII decimal number in the range 0..7 identifying the target
point required.

<distance> 8 character ASCII decimal representation of the calculated distance


in metres.

<target_not_defined> 2 digit ASCII hex error code for a target point not defined.

7.8.5.2 GT – Define Target Position

The GT command is used to set or interrogate one of the target points stored in the terminal.

Command Format GT<point_id><SP><latitude><SP><longitude><CR>


GT<point_id>?<CR>

Response Format gt<SP><point_id><SP><latitude><SP><longitude><CR><LF>

er<SP><target_not_defined><CR><LF>

<point_id> single ASCII decimal number in the range 0..7 identifying the target
point required.

<latitude> 13 character ASCII string reporting the latitude value to 0.01


seconds. The format of the string is:
+DDD MM SS.SS
<longitude> 13 character ASCII string reporting the longitude value to 0.01
seconds. The format of the string is:
+DDD MM SS.SS
<target_not_defined> 2 digit ASCII hex error code for a target point not defined.

© Satamatics Ltd Page 77 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.8.6 Logging Commands


The terminal performs logging of GPS positions, Transmissions and Data. The log allows storage for
over 6500 entries. Entries hold the following information:

Type Date Time Transmit time Data CRC


4 bits 16 bits 16 bits 16 bits 88 bits 16 bits

These fields are defined as follows:

Type:
Defines the type of entry:
1 = Acknowledgement burst (Transmitted and logged)
2 = Long burst (Transmitted and logged)
3 = Double Burst part 1 (Transmitted and logged)
4 = Double Burst part 2 (Transmitted and logged)
5 = Long Burst (Log only record)
6 = Double Burst part 1 (Log only record)
7 = Double Burst part 2 (Log only record)
8 = GPS record. (Log only record)

Date:
Defines the day/year that the data record was created.

The day of the year is stored in the lower 9 bits (1 – 356/366) and the Year since 2000 is
stored in the top 7 bits (0 to 127). For example a value of 0x102b would be 12th Feb 2008.

Time:
Defines the time of day that the data record was created.

The time after 00:00 is stored with 2s resolution. For example, a value of 0x176E (decimal
5,998) represents a time of 5,998 x 2 seconds after 00:00, i.e. 3:19:56.

Transmit time:
Defines the frame and slot in which the transmission occurred.

The bottom 4 bits (1 to 12) define the ‘slot’ number and the top 12bits (1 to 2880) the ‘frame’
number. Frames are 30s long and numbered from midnight. Frame number 1 indicates the
frame starting at 00:00:00 hrs; frame number 2880 indicates the frame starting at 23:59:30
hrs. Frames are divided into 2.5s slots. The slot number is the slot in which the transmission
began.

The transmit ‘frame’ and ‘slot’ can be converted to seconds past midnight as follows.
Seconds past Midnight = ((frame-1)*30) + ((Slot-1)*2.5)

The value is only valid for transmit log records where the message is transmitted. If a
message is not transmitted this field will contain 0xffff.

Data (type = 1, Acknowledgement burst):


For acknowledgement burst records, the data field will be zero.

© Satamatics Ltd Page 78 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Data (types = 2 to 7, Message data):


For message data records, only the most significant 86 bits of the data field are used. The data
(whether transmitted or just logged) corresponds to the transmit data message format. The
format for pre-defined messages (listed in Table 29, paragraph 5.8.1) is defined in the
Message Registry Document, ref.[2]. The creation of user defined messages is described in
paragraph 5.8.1.1.

Data (type = 8, GPS):


For GPS data records, only the most significant 84 bits of the data field are used. The format
is shown in Table 42. No logging of GPS data will occur if the GPS is turned off.

Bits (Size) Name Details


0..19 (20) Latitude 0: Hemisphere N|S (0 = North; 1 = South)
1..19: Latitude in seconds
20..40 (21) Longitude 20: Hemisphere E|W (0 = East; 1 = West)
21..40: Longitude in seconds
41..49 (9) Heading Degrees
50..59 (10) Speed 0.1 m/s
60..75 (16) Altitude Signed 2’s Complement value in metres
76 (1) GPS Status 0 = Invalid; 1 = Valid
77..83 (7) HDOP Geometric Dilution of Precision

Table 42 - GPS data log record format

CRC:
A Checksum used internally by the terminal to validate the logged records

7.8.6.1 GI – Set GPS Logging Interval

The GI command sets the interval between logged GPS positions stored in non-volatile memory. If
the interval is set to 0 then GPS positions will not be logged. If the logging interval is set to a value
between 1 and 10080 minutes (the maximum allowed) then GPS information (position, course, speed,
altitude and status) will be logged in non-volatile memory after the defined number of minutes.

Command Format GI<interval><CR>


GI?<CR>

Response Format gi<SP><interval><CR><LF>

<interval> 4 character ASCII hex value containing the time between logged
positions in minutes. A value of zero turns logging off.

© Satamatics Ltd Page 79 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.8.6.2 LN – Get Number of Logged Positions

The LN command requests the number of logged entries or ‘records’ in the terminal.

Command Format LN?<CR>

Response Format ln<SP><records><CR><LF>

<records> 4 character ASCII hex value containing the number of logged records
stored in the terminal.

7.8.6.3 LR – Get Logged Record

The LR command is used to interrogate the logged records stored in the terminal and can be used
with or without the index parameter. Multiple LR? commands without an index will return
consecutive records starting with the most recent. To restart interrogating from the most recent record,
an LN? command should be issued. Sending a LR <index>? command will return the log entry for
the specified index.

Command Format LR?<CR>


LR<index>?<CR>

Response Format lr<SP><index><SP><type><SP><date><SP>< time>


<SP><transmit_time><SP><data> <CR><LF>

<index> 4 character ASCII hex value. The index of the record stored. A value
of 1 represents the oldest record in the log. The index of the newest
record in the log is found using the LN? command.

Note that the index is NOT unique to each record. It is simply an


indication of the relative position of each record in the log file. As
records are added to the log and older records removed the index of
the records will change periodically. It is advised that GPS logging
and Script operation is halted when reading large numbers of records.
See sections 7.8.6.1 and 7.13.4 for use of the ‘GI 0’ and the ‘PS 0’
commands.

The time stamp stored with the logged data (described below) should
be used to uniquely identify records.

For more details on the following fields see paragraph 7.8.6:

<type> single ASCII hex character defining the record type stored:

<date> 4 character ASCII hex value of the date that the entry was recorded
in the log.

<time> 4 character ASCII hex value of the time past midnight, with 2s
resolution, that the entry was recorded in the log.

© Satamatics Ltd Page 80 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

<transmit_time> 4 character ASCII hex value. The value contains the slot and frame
number in which the transmission occurred. If a message is not
transmitted this field will contain 0xffff.

<data> 22 character ASCII hex value representing the logged data.

© Satamatics Ltd Page 81 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.9 Messaging Module Commands

7.9.1 Forward Channel Message Handling

7.9.1.1 Forward Channel Message Buffering

When the terminal receives a forward channel message the data is stored in a 10 message buffer.
Messages within the buffer will be lost if power to the terminal is removed or the terminal is placed
into sleep mode (paragraph 5.3.4).

Some message formats are reserved to allow control and status report enquiries to be sent to the
terminal. These messages are not made available to the user. They are processed within the terminal
and then deleted.

All other messages received by the terminal are available to the user over the serial port. The message
output method can be configured by the user so that the message data can be output in an unsolicited
message as soon as it has been received, or these unsolicited messages can be disabled. This is
controlled by the ‘MO’ command (section 7.9.1.5). The message data is also stored in a 10 message
buffer and may be read out using the ‘MN’ command (Section 7.9.1.4). The terminal can be
interrogated for the number of buffered messages using the ‘MC’ command (section 7.9.1.1). If the
message buffer becomes full, i.e. the incoming messages are not read and deleted with the ‘MN’
command, then the terminal will output an error message each time that a message is received
indicating that the buffer has overflowed and the oldest message in the buffer has been deleted.

7.9.1.2 MC–Get Number of Forward Messages Buffered

The MC command returns the number of buffered forward channel messages held within the terminal.

Command Format MC?<CR>

Response Format mc<SP><number><CR><LF>

<number> single ASCII decimal number representing the number of forward


channel messages buffered in the terminal.

7.9.1.3 mf – Forward Channel Message Data

The mf data message is the only message that is not generated in response to a message received over
the serial port. The mf message is generated in response to an incoming forward channel, user
message being received over the satellite. The format of the message depends upon the type of
forward channel message received by the terminal.

Message Format mf<SP><header><data_block><CR><LF>

<header> 22 character ASCII string containing the burst header information


reported by the terminal.

<data_block> The format and length of the data_block field will vary depending
upon the message type.

© Satamatics Ltd Page 82 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Character Field Format


1..2 Flags 2 hex digits
3..4 Year 2 decimal digits
5..6 Month 2 decimal digits
7..8 Day 2 decimal digits
9..10 Hour 2 decimal digits
11..12 Minute 2 decimal digits
13..15 Transmitting Earth Station ID 3 decimal digits
16..17 Message Number 2 decimal digits
18 Category T, N, A or D
19 Tone Number 1, 2, 3 or 4
20..21 Service ID 2 decimal digits
22 Information type Hex digit
Table 43 - Forward Channel Message Header Format
The format of the data_block field will vary depending upon the message category field in the header
record. If the category is T (tone only) then the data_block field is empty. If the category is N
(numeric data) or A (alphanumeric data) then the data_block field contains the message data as an
ASCII character string. If the category is D (transparent binary data) then the data_block field
contains the message data as a sequence of ASCII hex byte values.

7.9.1.4 MN – Get Next Forward Message from the Buffer

The MN command returns the earliest forward channel message held within the terminal. Once the
data has been output it is deleted from the database in the terminal. If the forward channel message
buffer is empty no parameters are returned

Command Format MN?<CR>

Response Format mn<SP><header><data_block><CR><LF>

<header> same format as header field in the mf response (paragraph 7.9.1.3)

<data_block> same format as data_block field in mf response (paragraph 7.9.1.3)

7.9.1.5 MO – Configure Forward Channel Message Output

The MO command enables or disables the output of unsolicited mf report messages in response to the
reception of forward channel messages by the terminal. When mf messages are disabled the forward
channel messages can be read by interrogating the terminal for the number of received messages using
the ‘MC?’ command and reading them using the ‘MN?’

Command Format MO<mode><CR>


MO?<CR>

Response Format mo<SP><mode><CR><LF>

<mode> single ASCII character either 0 or 1. A ‘0’ enables the output of the
mf messages and a 1 disables their output. The mode is stored in the
Forward Channel Message Output Mode register (module 0x05,
register 0x40) – paragraph 5.8.19.

© Satamatics Ltd Page 83 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.9.2 Return Channel Messaging

7.9.2.1 MA – Get/Set Return Message Destination Address

The MA command sets the value to be used in the destination address field of any subsequent bursts
to be transmitted in response to MB commands.

Command Format MA<dest_addr><CR>


MA?<CR>

Response Format ma<SP><dest_addr><CR><LF>

<dest_addr> 2 character ASCII hex representation of the 8 bit contents of the


message destination address field (module 0x05, register 0x11) – see
paragraph 5.8.2.

7.9.2.2 MB – Transmit a Return Message

The MB command instructs the terminal to transmit a pre-defined or user defined return burst. The
pre-defined message codes are listed in Table 29, paragraph 5.8.1, and details of their format is
described in the Message Registry Document, ref.[2]. User defined messages use codes 0x80 to 0xBF
for 64 bit messages, and codes 0xC0 to 0xFE for 80 bit messages. The creation of user defined
messages is described in paragraph 5.8.1.1.

Command Format MB<msg_code><CR>

Response Format mb<SP><msg_code><CR><LF>

<msg_code> 2 character ASCII hex representation of message identifier number.

If the message code is not defined then no message will be transmitted. This command is equivalent
to writing the message code to the Return Burst Message ID code register (module 0x05, register
0x10) – see paragraph 5.8.1.

7.9.2.3 MK – Get/Set Return Message Acknowledge Flags

The MK command sets the value to be used in the message acknowledgement flags field of any
subsequent bursts to be transmitted in response to MB commands. The flags field is a 2 bit value. Bit
0 (LSB) requests an application acknowledge and Bit 1 requests an automatic LES acknowledge.

Command Format MK<ack_flags><CR>


MK?<CR>

Response Format mk<SP><ack_flags><CR><LF>

<ack_flags> single character ASCII hex representation of the 2 bit acknowledge


flags value (module 0x05, register 0x14) – see paragraph 5.8.4.

© Satamatics Ltd Page 84 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.9.2.4 ML – Get/Set Return Message Control Flags Field

The ML command sets the value to be used in the message control flags field of any subsequent
bursts to be transmitted in response to MB commands. The flags field is a 4 bit value.

Command Format ML<message_flags><CR>


ML?<CR>

Response Format ml<SP><control_flags><CR><LF>

<control_flags> single character ASCII hex representation of the 4 bit control flags
value (module 0x05, register 0x15) – see paragraph 5.8.5.

7.9.2.5 MM – Transmit Return Message

The MM command causes the terminal to transmit a return burst message using the message data
contained in the command.

Command Format MM<SP><length><SP><data_block><CR>

Response Format mm<SP><length><SP><data_block><CR><LF>

<length> single ASCII character defining the message length being defined: L
for a long or D for double (IsatM2M)

<data_block> ASCII hex representation of payload data to be transmitted.


Long message: 22 character field. Bits 0 (LSB) and 1 of the last
character are the application and LES acknowledgement request bits
respectively.
Double message (IsatM2M only): 43 character field. Bits 0 (LSB)
and 1 of the last character are the application acknowledge bits for
the first part and second part of the message respectively. Bit 2 of the
last character is the LES acknowledge request bit. Note that
confirmation of receipt of an LES acknowledgement by the terminal
is confirmation that both parts of the Double message were received
at the LES.

7.9.2.6 MP – Configure Automatic Poll

The MP command configures the automatic return message generation by the terminal. The message
takes two parameters. The first is a message repeat rate in minutes. If set to zero then the terminal
will stop sending messages. If set to 1 then a single message is transmitted. All other values are
treated as repeat rates and the messages will be sent out at the intervals requested except that values
from 2 to 9 are rounded up to 10.

Command Format MP<SP><period><SP><msg_code><CR>


MP?<CR>

Response Format mp<SP><period><SP><msg_code><CR><LF>

<period> 4 character ASCII hex number containing the time between message
transmission in minutes.

© Satamatics Ltd Page 85 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

<msg_code> 2 character ASCII hex number containing the message type to be sent
in the poll transmission. The msg_code is stored in the Poll Message
ID code register (module 0x05, register 0x30) – paragraph 5.8.17.1.

The message code used may be one of the values for a standard return message format listed in Table
29 or it may be a user defined 64 or 80 bit message. If the message code is not defined in the terminal
then no message will be transmitted.

7.9.2.7 MQ – Get/Set Response to a Tone only Message

The MQ command is used to set the response of a terminal to a tone only type forward channel
message. There are four tone only messages that may be sent to a terminal and, using this command, it
is possible to configure the terminal to use these messages as remote poll requests.

Command Format MQ<tone><SP><msg_code><CR>


MQ <tone>?<CR>

Response Format mq<SP><tone><SP><msg_code><CR><LF>

<tone> single character ASCII hex representation of the tone number (0..3).

<msg_code> 2 character ASCII hex representation of the message number to be


returned by the terminal. If the value is zero, subsequent tone only
forward messages will be treated as normal, i.e. the terminal will not
respond with a return channel message.

The message code used may be one of the values for a standard return message format listed in Table
29 or it may be a user defined message. The message code is stored in the appropriate messaging
module register – module 0x05, registers 0x38 to 0x3B – see paragraph 5.8.18.

7.9.2.8 MR – Report Receiver Status

The MR command reports the latest receiver status values as reported by the terminal.

Command Format MR?<CR>

Response Format mr<SP><channel><SP><quality><SP><status><CR><LF>

<channel> 4 character ASCII hex representation of the receiver channel number.

<quality> 4 character ASCII hex representation of the receive signal quality.


The value returned is the Receive Signal Quality register (module
0x05, register 0x21) - see paragraph 5.8.7.2

<status> 2 character ASCII hex representation of the receiver status code


returned by the terminal. The value returned is the Receive Status
register (module 0x05, register 0x22) - see paragraph 5.8.7.3.

7.9.2.9 MS – Get/Set Return Message Transmission Slot Randomisation

The value set by the MS command sets the number of traffic channel frames over which slot
randomisation occurs, e.g. if a value of 3 is used then the transmission will occur in a return channel

© Satamatics Ltd Page 86 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

slot some time in the next 3 traffic frames. If a value of zero is used then the message will be
transmitted in the next available slot.

Command Format MS<slot_randomisation><CR>


MS?<CR>

Response Format ms<SP><slot_randomisation><CR><LF>

<slot_randomisation> 2 character ASCII hex representation of the number of traffic frames


to be used in the range 0 to 0x1F. The value is stored in the Transmit
Randomisation Period register (module 0x05, register 0x24) – see
paragraph 5.8.9.

7.9.2.10 MT – Report Transmitter Status

The MT command reports the latest terminal transmitter status as reported to the terminal.

Command Format MT?<CR>

Response Format mt<SP><status><CR><LF>

<status> 8 character ASCII hex representation of the transmitter status. The


value returned is the Transmit Status register (module 0x05, register
0x23) - see paragraph 5.8.8.

7.10 Scratchpad Module Commands


The scratchpad registers are available for the script to use for storing values during operation. Three
of the registers have special functions; registers 1 and 2 can be used as the source data for some of the
return channel message formats and register 0 is used to hold the result of the last operation or alarm
trigger value.

7.10.1 SR – Read/Set Register


The SR command is used to set or read one of the scratchpad registers (module 0x06) – see section
5.9.

Command Format SR<register><SP><value><CR>


SR<register>?<CR>

Response Format sr<SP><register><SP><value><CR><LF>

<register> single character ASCII hex representation of the scratchpad register


number (0..F).

<value> 8 character ASCII hex representation of the 32 bit value to be stored


in the register.

© Satamatics Ltd Page 87 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.11 Register Direct Access Commands


The RR and RW commands allow direct access to the scripting module registers (see section 5). They
can be used as an alternative to those more concise serial interface commands that also access one of
the scripting module registers. For example, the following commands are equivalent:

CA 6
RW 0 2 6

7.11.1 RR – Read Register


The RR command allows the value of one of the scripting module registers (see section 5) to be read
directly.

Command Format RR<module><SP><register>?<CR>

Response Format rr<SP><module><SP><register><SP><value><CR><LF>

<module> single character ASCII hex representation of the module number.

<register> 2 character ASCII hex representation of the register number.

7.11.2 RW – Write Register


The RW command allows the value of one of the scripting module registers (see section 5) to be
written to directly.

Command Format RW<module><SP><register><SP><value> <CR>

Response Format rw<SP><module><SP><register><SP><value><CR><LF>

<module> single character ASCII hex representation of the module number.

<register> 2 character ASCII hex representation of the register number.

<value> 8 character ASCII hex representation of the 32 bit value to be stored


in the register.

© Satamatics Ltd Page 88 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.12 User Return Message Definition Commands

7.12.1 BD – Define Message Number


Add a message number definition to the user message database.

Command Format BD<message_ID><SP><field_count><CR>

Response Format rw<SP><message_ID><SP><field_count><CR>LF>

<message_ID> 2 character ASCII hex representation of the message number being


defined. This must have a value in the range 0x80 to 0xFE. Message
ID of 0xFF is not allowed

<field_count> 2 character ASCII hex representation of the number of field


definitions used to produce the message.

7.12.2 BF – Define Field Contents


Add a message data field definition to the user message database.

Command Format BF<register><SP><mask> <CR>

Response Format bf<SP><register><SP> <mask><CR><LF>


<register> 3 character ASCII hex representation of the register address
including its module number.

<mask> 8 character ASCII hex representation of the 32 bit mask value to be


used to extract the data bits from the register.

7.12.3 BI – Initialise User Message Database


Erases any existing message definitions from the user message database and prepares the terminal to
receive new message definitions in the form of BD and BF commands.

Command Format BI<CR>

Response Format bi<CR><LF>

7.12.4 BN – Get Number of Message Definitions


Reports the number of user message definitions that have been programmed into the terminal.

Command Format BN?<CR>

Response Format bn<SP><message_count><CR><LF>

<message_count> 2 character ASCII hex representation of the number of message


definitions programmed into the terminal.

© Satamatics Ltd Page 89 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.12.5 BQ – Get Message Definition


Returns one of the user message definitions that have been programmed into the terminal.

Command Format BQ<message_number>?<CR>

Response Format bq<SP><message_number><SP><message_ID><SP>


<field_definition>[..<SP><field_definition>]<CR><LF>

<message_number> 2 character ASCII hex representation of the message definition


number in the user message database.

<message_ID> 2 character ASCII hex representation of the message number to be


used to identify this message format, as programmed by the BD
command.

<field_definition> 3 character ASCII hex representation of the register address


including its module number followed by a space and an 8 character
ASCII hex representation of the 32 bit mask value to be used to
extract the data bits from the register. These values are as used in
the BF command sequence to define the message. The response
contains one field_definition pair for each BF command used in the
message generation.

7.12.6 BW – Close Message Database


The BW command closes the message database so that no further message definitions can be written.

Command Format BW<CR>

Response Format bw<CR><LF>

© Satamatics Ltd Page 90 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.13 Terminal System Commands

7.13.1 Firmware Upload


The firmware to be loaded into the terminal is delivered as an XML format file. This is read by the
Satamatics supplied uploader software and the required images extracted for transfer to the terminal.
To prevent upload of incompatible firmware, the terminal rejects any attempt to upload firmware that
it does not recognise as being compatible.

The file upload into the MSP is initiated by a PD command. The program image is then transferred in
Motorola S-record format, one record at a time, over the serial link. Each record is acknowledged
with either a ‘pa’ (success) or ‘pn’ (failure) response. Once the last record has been sent to the
terminal the MSP calculates and stores a checksum value for its internal image.

7.13.1.1 PD – Program Upload

The PD command is used to upload a new version of the terminal application firmware into the
processor memory over the serial port. The PD command is followed by the program data file in
Motorola S-Record format. Each record of the program file is acknowledged by a pa<LF><CR>
response. The first record of the program file must not be sent until the pd acknowledge has been
returned. Subsequent records must wait until the previous record has been acknowledged with a pa.

Command Format PD[<rate_select>]<CR>

Response Format pd<LF><CR>

<rate_select> Optional parameter, selecting the upload speed:


1 = 9600 baud
2 = 19200 baud
3 = 38400 baud
4 = 57600 baud
5 = 115200 baud
If the parameter is omitted then the upload will continue at the
normal serial port rate of 9600 baud.

The baud rate change occurs once the ‘pd’ response has been sent out of the terminal. All further
communications following receipt of the ‘pd’ command must be performed at the new baud rate.
Following an upload to the MSP the terminal will automatically return to the default baud rate of
9600. Following an upload to the DSP the terminal can be set back to the default baud rate by sending
command ‘PR9600’ to the unit

7.13.1.2 pa – Program Record Acknowledge

The pa response is sent from the terminal in response to a valid S-record during the upload process.
The response is sent by the terminal when it has received the record, decoded it and stored the
contents in the program FLASH memory. It indicates that it is ready to receive another record.

© Satamatics Ltd Page 91 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.13.1.3 pn – Program Record NAK

The terminal responds with a pn message when it detects an error in the received S-record. Errors
may include an invalid character in the record or an invalid checksum. If the error is detected in the
file header (S0) record then the unit returns a ‘pn 0’ response, otherwise it returns ‘pn 1’.

7.13.2 PI – Reset
The PI command is used to reset the terminal application firmware or to get the results of the terminal
self tests. The command sends its response before performing the processor reset.

Command Format PI<CR> (Reset command)


PI?<CR> (Test result request)

Response Format pi<CR><LF> (Reset command)


pi<SP><test_result><CR><LF> (Test result request)

<test_result> 4 digit ASCII hex representation of a 16 bit value containing the self
test result code.

This command causes the reset of the GPS processor and Inmarsat-D modem, and the terminal
configuration and script are reloaded with their restart state from the non volatile data store. The GPS
and Inmarsat-D functions will be restarted as required by the terminal configuration, and the script
operation (timers and alarms) subsequently started. (Note that if the GEM-100 is utilised there will be
a 32 second delay before the script operation starts.)

7.13.3 PR – Configure Serial Port Baud Rate


The PR command selects the baud rate to be used by the terminal for serial communications. There
are two options; 9600 or 4800 baud. The 4800 baud option is provided so that the NMEA format
output data can be passed to external devices at a standard NMEA data rate.

Command Format PR<rate><CR>

Response Format pr<SP><rate><CR><LF>

<rate> 4 digit ASCII decimal value. If the value supplied is 4800 then the
serial port will be configured to operate at 4800 baud. Any other
value will set the port to 9600 baud.

Note: Following a firmware upload (paragraph 7.13.1.1) the terminal will return to the default baud
rate of 9600.

© Satamatics Ltd Page 92 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.13.4 PS – Scripting Enable/Disable


The PS command is used to enable or disable scripting functions. This command is required when
programming the script functions so that the initial values for any of the function registers do not
become corrupted during the load as a result of part of the script operating during the load. The
command also switches on and off the script debugging output messages.

Command Format PS<enable><CR>


PS?<CR>

Response Format ps<SP><enable><CR><LF>

<enable> single ASCII character:


0 or 2 = disable
1 = enable
3 = enable with debug messages

7.13.5 PT – Run Production Tests


THIS COMMAND IS FOR FACTORY USE ONLY AND MUST NOT BE ISSUED WHEN THE
I/O LINES ARE CONNECTED TO ANY EXTERNAL DEVICE.

7.13.6 PV – Report Bootloader Version


The PV command is used to read the version ID for the Bootloader code held in the terminal. The
Bootloader code is a separate piece of software that is loaded into the terminal at manufacture and is
used to update the main software contained in the MSP.

Command Format PV?<CR>

Response Format pv<SP><version_string><CR><LF>

<version_string> 4 character ASCII string containing the software version. The first
two characters are the major version and the second two characters
the minor version number.

7.13.7 PY – Report MSP Software Information


The PY command returns MSP software information such as software number, version, date and time
of build etc..

Command Format PY?<CR>

Response Format py<SP><date_string><SP><hardware><SP><variant><CR><LF>

<date_string> ASCII string containing the date and time of compilation of the code.
The format of the string is hh:mm:ss Mmm dd yyyy

<hardware> ASCII string containing the hardware revision that the MSP software
was built to support.

© Satamatics Ltd Page 93 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

<variant> ASCII string containing the variant description for the software build.

Extended information is returned through use of the following PY command format:

Command Format PY <report_type>?<CR>

Response Format py<SP><report_type><SP><version_info><CR><LF>

<report_type> single ASCII character specifying the report type as follows:


1 = full MSP code version information
2 = Bootloader version information
3 = MSP code, version and build numbers only

<version_info> ASCII string containing version information.

Examples of responses from the PY?, PY1?, PY2? and PY3? Commands are:
py 13:28:51 Feb 2 2009 P042_G01 Rev A GEM-100 Build. Build 647
py 1 SWN-0091-20 SAT-200 MSP Application Software - Version 01.00
py 2 SWN-0091-21 SAT-200 MSP Bootloader Software - Version 01.95
py 3 01.00 00647

7.13.8 PZ – Report Unit Serial Number


The PZ command is used to read the production serial number of the unit.

Command Format PZ?<CR>

Response Format pz<SP><serial_no><CR><LF>

<serial_no> 5 character serial number. (The serial number is also labelled the
unit.)

© Satamatics Ltd Page 94 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.14 Inmarsat-D Network Configuration Commands

7.14.1 DS PY – Report DSP Software Information


This command is the DSP equivalent of the PY command – see paragraph 7.13.7 for command and
response formats.

7.14.2 DS PW – Enter Access Password


The DS PW command is used to enter the access control password. This password allows write access
to specific configuration parameters not available to the end user. Password protected parameters can
normally still be read back without the need for a password.

Command Format DS<SP>PW<SP><access_level><SP><password><CR>

Response Format ds<SP>pw<access_level><SP><response><CR><LF>

<access_level> single ASCII character defining the access level required.

<password> ASCII string containing the password for the access level.

<response> ASCII sting returning the result of the password access request. This
is either ‘GRANTED’ or DENIED’.

7.14.3 DS TA – Get/Set Service ID (SID)


Set/Get one of the 5 stored Service IDs (SIDs). The terminal has 5 pre-programmed SIDs each with a
corresponding Beam ID (BID). The SID and BID are the primary parameters that the terminal uses to
connect to the Inmarsat-D network. Use the DS TE command to set the corresponding BID and the
DS TJ command to read back the SID/BID pairs.

If this value is changed the service provider must be informed to ensure that forward channel
messages are delivered to the correct channel.

Command Format DS<SP>TA<SP><service><SP><service_ID><CR>


DSTA<service>?<CR>

Response Format ds<SP>ta<service><SP><service_ID><CR><LF>

<service> single ASCII digit in the range 0..4 representing the pre-programmed
service number.

<service_ID> 2 digit ASCII hex number of the stored Service ID corresponding to


the specified service.

© Satamatics Ltd Page 95 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.14.4 DS TC – Get/Set Pager Subset Number (PSN)


The DS TC command is used to get or set the terminal ‘Pager Subset Number’ (PSN). A particular
service may utilise a number of Traffic channels and the PSN provides a method of distributing the
terminal population associated with this service over these Traffic channels. By default the PSN of
every terminal is set to the last character of the terminal ISN (see command TN in section 7.14.10)
giving the terminal population an even distribution of PSN’s between 0 and F.

If this value is changed from the default setting the service provider must be informed to ensure that
forward channel messages are delivered to the correct channel.

Command Format DS<SP>TC<SP><PSN><CR>


DSTC?<CR>

Response Format ds<SP>tc<PSN><CR><LF>

<PSN> single ASCII hex character 0 to F

7.14.5 DS TE – Get/Set Beam ID


Set/Get one of the 5 stored Beam ID’s (BIDs). Also refer to the DS TA command, paragraph 7.14.3.

If the BID is changed the service provider must be informed to ensure that forward channel messages
are delivered to the correct channel

Command Format DS<SP>TE<SP><service><SP><beam_ID><CR>


DSTE<service>?<CR>

Response Format ds<SP>te<service><beam_ID><CR><LF>

<service> single ASCII digit in the range 0..4 representing the pre-programmed
service number.

<beam_ID> 2 digit ASCII hex number of the stored Beam ID corresponding to


the specified service.

7.14.6 DS TG – Get/Set the Group PID’s


The DS TG command is used to get or set up to 5 group PIDs for the terminal. GPIDs provide the
ability for service providers to broadcast forward channel messages to multiple terminals. Contact
your service provider for more information.

Command Format DS<SP>TG<SP><gpid_no><SP><gpid><CR>


DSTG?<CR>

Response Format ds<SP>tg<SP><gpid0><SP><gpid1><SP><gpid2><SP>


<gpid3><SP><gpid4><CR><LF>

<gpid_no> single character ASCII hex value in the range 0..4 representing the 5
stored GPID’s

<gpid> 5 character ASCII hex value of the 20bit GPID

© Satamatics Ltd Page 96 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.14.7 DS TJ – Get Configured Service IDs


The DS TJ command is a read only command used to get the 5 stored “Services” with a “Service ID”
and “Beam ID” held in the terminal. The terminal has 5 pre-programmed Service IDs each with a
corresponding Beam ID. The service ID and Beam ID are the primary parameters that the terminal
uses to connect to the Inmarsat-D network.

Command Format DSTJ?<CR>

Response Format ds<SP>tj<SP><service_ID0><SP><beam_ID0><SP>,


<service_ID1><SP><beam_ID1><SP>,
<service_ID2><SP><beam_ID2><SP>,
<service_ID3><SP><beam_ID3><SP>,
<service_ID4><SP><beam_ID4><CR><LF>

<service_ID> 2 digit hexadecimal number representing the stored Service ID to be


used with the specified service.

<beam_ID> 2 digit decimal number reporting the stored beam ID to be used with
the specified service.

7.14.8 DS TK – Get/Set the Number of RC Transmission Retries


The DS TK command is used to set the number of transmission retries for messages that have been
configured to request an LES acknowledge but where no acknowledgement has been received. Each
retry occurs if the expected acknowledgement has not been received within 3 frames of the
transmission. The message remains at the top of the transmit queue until either an acknowledgment is
received or the re-try count has expired. By default the number of re-tries is set to 1.

Command Format DS<SP>TK<SP><retries><CR>


DSTK?<CR>

Response Format ds<SP>tk<SP><retries><CR><LF>

<retries> single ASCII hex character (0 to F) representing the number of retries

7.14.9 DS TM – Get/Set the Terminal Mobility


Get/set the mobility of the terminal. If the terminal is expected to be used in aircraft this value should
be set to 1. If it is to be used in a static or vehicular installation then it should be set to zero.

Command Format DS<SP>TM<SP><mobility><CR>


DSTM?<CR>

Response Format ds<SP>tm<SP><mobility><CR><LF>

<mobility> single ASCII digit, either 0 or1.

© Satamatics Ltd Page 97 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.14.10 DS TN – Get the Terminal ISN


Get the terminals unique Inmarsat Serial Number (ISN) identifier.

Command Format DSTN?<CR>

Response Format ds<SP>tn<SP><ISN><CR><LF>

<ISN> 12 ASCII character representation of the ISN

7.14.11 DS TO – Get/Set the Operational Flags


Get/set the state of 24 SET ONLY flags. These flags are set to enable or disable additional
functionality within the terminal.

WARNING: These flags should only be set following consultation with Satamatics. Once these flags
are set they cannot be cleared. The unit must be returned to Satamatics to clear the flags.

Bit Number Function


Enable terminal for use in (USA) FCC controlled areas. All units
0
deployed in (USA) FCC controlled areas should have this flag set
1 Set to 1 indicating IsatM2M operation
2-23 Reserved
Table 44 – DS TO Operational Flags

Command Format DS<SP>TO<SP><flags><CR>


DSTO?<CR>

Response Format ds<SP>to<SP><flags><CR><LF>

<flags> 6 ASCII hex character representing the 24bit flags thus command
“DS TO 01” would set bit zero

7.14.12 DS TR – Report Receiver Status


The DS TR command reports the latest receiver status values from the terminal.

Command Format DSTR?<CR>

Response Format ds<SP>tr<SP><channel><SP><rx_Inhibit_status><SP>


<rx_progress><SP><errors><CR><LF>

<channel> 4 character ASCII hex representation of the receiver channel number.

<rx_Inhibit_status> 4 character ASCII hex representation of any receiver inhibiting


factors as described in Table 45. If the inhibiting factor is cleared
then the status will return to “Receive OK”

© Satamatics Ltd Page 98 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Value Usage
0 Receive OK
Forward channel has a low signal quality. Check the positioning of the
1
antenna
BB Allocation Table not matched. The SID, BID, PSN in the terminal
2
are not setup correctly. Contact your service provider
3 HW failure. Contact your service provider
Table 45 – DS TR Receiver Inhibit Status Codes

<rx_progress> 2 character ASCII hex representation of the receiver progress


returned by the terminal as described in Table 46

Valid Values Status


00 Config
01 BB Wide band
02 BB Narrow Band
03 BB Track and Demod
04 BB Track and Demod – No Match Found
0A TC Narrow Band
0B TC Track and Demod
0C TC RF Off
TC Rx Errors (TC could not be decoded correctly due to poor signal
0D
quality)
Table 46 – DS TR Receiver Progress Codes
<errors> 4 character ASCII hex representation of 16 error flags (see Table 47).
These error bits are only cleared on a power cycle.

Bit Usage
0 HW Error
1 Internal non-volatile memory CRC failure
2 Forward Channel Ack not received
3 Rx message buffer overflow
5 Rx message buffer error
6 Tx message buffer overflow
7 Tx message buffer error
Table 47 – DS TR Terminal Error Codes

7.14.13 DS TS – Report Signal Status


The DS TS command reports the latest receiver status from the DSP.

Command Format DSTS?<CR>

Response Format ds<SP>ts<SP><SNR><SP><level><SP><freq><SP>


<doppler><SP><symbol_errors><SP><rx_progress><CR><LF>

© Satamatics Ltd Page 99 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

<SNR> 4 character ASCII hex representation of received Signal to Noise


Ratio multiplied by 10dBHz.

<level> 4 character ASCII hex representation of received signal level at the


ADC input multiplied by –100dBm.

<freq> 6 character ASCII hex representation of received signal frequency.

<doppler> 4 character ASCII hex representation of received signal rate of


change of frequency

<symbol errors> 4 character ASCII hex representation of the number of corrected


symbol errors this frame.

<rx progress> 2 character ASCII hex representation of the receiver progress


returned by the terminal as described in Table 46

7.14.14 DS TT – Report Transmitter Status


The DS TT command requests the latest transmitter status from the DSP.

Command Format DSTT?<CR>

Response Format ds<SP>tt<SP><msg_buf><SP><tx_progress><SP>


<tx_inhibit_status><SP><last_tx_type><SP>
<last_tx_time><SP>0<CR><LF>

<msg_buf> 2 character ASCII hex representation of the number of return channel


messages waiting to be transmitted.

<tx_progress> 2 character ASCII hex representation of the progress of the current


message being transmitted. The progress is described in Table 48.

Value Usage
0 Message buffer empty
1 Waiting for a FC acknowledgement (Tx inhibited)
2 Waiting for FC frame header
3 Waiting for Transmit slot
4,5 or 6 Transmitting
Table 48 – DS TT Transmit Progress
<tx_inhibit_status> 4 character ASCII hex representation of the status of any inhibiting
factors to the current burst being transmitted. The status is described
in Table 49. If the inhibiting factor is cleared then the status will
return to “Transmit OK”

© Satamatics Ltd Page 100 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Value Usage
0 Transmit OK
1 Hardware Error. Contact your service provider
System Message. The unit has been stopped from transmitting by a system
2
message. Contact your service provider
Waiting for a Forward Channel (FC) Acknowledgment. While waiting for a FC
3
Ack no further transmissions will be made to ensure that the FC Ack is received
Poor signal quality on FC. Before every transmission the terminal determines
4 whether a transmission is likely to be successful by monitoring the FC signal
quality. While signal quality is poor transmissions will be inhibited.
Receiving a FC message. A transmission was due to go out in a frame that
5 contained a forward channel message for the terminal. The transmission has been
re-scheduled
Table 49 – DS TT Transmit inhibit status

<last_tx_typet> single character ASCII representation of the last message type


transmitted ‘L’ – Long, ‘D’ – Double, ‘A’ – Acknowledgement.

<last_tx_time> 4 character ASCII decimal representation of the UTC time of the last
transmission. The first two characters are the hours the second two
characters are the minutes. A value of ‘9999’ indicates that no
transmission has taken place since the terminal was last turned on or
came out of sleep mode

7.14.15 DS TW – Return Channel Transmission Queue Write Function


The DS TW command is used to setup the way that return messages are written to the return channel
transmission queue. By default these values are set to size=9 and write=0. Further information on the
return channel queue can be found in reference [1].

Command Format DS<SP>TW<SP><size><SP><write><CR>


DSTW?<CR>

Response Format ds<SP>tw<SP><size><SP><write><CR><LF>

<size> single digit ASCII hex character in the range 2 to 9 that represents
the maximum number of messages that can be stored in the return
channel transmit queue at any time.

<write> single digit ASCII hex flag that describes the way messages are
handled when the transmit queue is full. If the flag is set to zero no
messages can be added to the transmit queue when it is full. If the
flag is set to 1 a new messages will overwrite the oldest message in
the transmit queue when it is added.

7.14.16 DS TZ –Write/Restore Configuration to/from Non-Volatile Memory


The DS TZ command is used write specific configuration values to non-volatile memory or to restore
their default settings from non-volatile memory. The configuration values to which this command
applies are indicated in Table 54. In order to restore the default settings of these configuration values,

© Satamatics Ltd Page 101 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

the command “DS TZ D” (Defaults loaded into RAM) must be followed by the command “DS TZ S”
(Save the RAM values to non-volatile memory).

Note: Power management within the terminal may cause the RAM settings of the configuration
values, to which this command applies, to be lost. The settings must therefore be saved to non-volatile
memory to avoid unexpected results.

Command Format DS<SP>TZ<SP><action><CR>


DSTZ?

Response Format ds<SP>tz<SP><success><CR><LF>

<action> S - Save the current configuration in RAM to non-volatile memory


D - Load the Default configuration to RAM (This would normally be
followed by a command to write to non-volatile memory)

<success> single ASCII digit, 0(failure) or 1(successful).

© Satamatics Ltd Page 102 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.15 NMEA Input/Output Messages


The terminal can receive and decode NMEA format RMC and GGA sentences from an external
position data source. The position data from these sentences is stored in the NMEA input registers in
the terminal GPS scripting module (module 0x04 registers 0x80 to 0x85). It is available for use by
scripting functions and as the source data for the user defined return messages, but it is not used by
any of the internal geographic processing (geofences or target point distances).

The terminal will accept sentences that begin either $G or $A and with any letter in the next position
so that the data may be provided by systems based on any navigational data source (for example GPS,
GLONASS or terrestrial radio).

The terminal can also be configured to output NMEA RMC, GGA and GSV sentences.

RMC sentences are of the form:

$GPRMC,141050,A,5159.23,N,00209.87,W,0.1,174.5,030904,,*0B
Where the message fields, separated by commas, have the following functions.

Field Number Contents Meaning


1 GPRMC Message header/identifier
2 141050 Time hhmmss
3 A Data Validity. A = Valid, V = Invalid
4 5159.23 Latitude value DDMM.MM
5 N Hemisphere N = North, S = South
6 00209.87 Longitude Value DDDMM.MM
7 W Hemisphere E = East, W = West
8 0.1 Speed in knots
9 174.5 Heading in degrees
10 030904 Date ddmmyy
11 (On output this field is always empty, on input it is ignored)
12 *0B Message Checksum. 2 hex digits after the * character.
Table 50 – NMEA RMC Sentence Format

© Satamatics Ltd Page 103 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

GGA sentences are of the form:

$GPGGA,110039,5200.28,N,00207.48,W,1,,,64.00,M,,,,,*0D

Where the message fields, separated by commas, have the following functions.

Field Number Contents Meaning


1 GPGGA Message header/identifier
2 123519 Time hhmmss
3 5200.28 Latitude value DDMM.MM
4 N Hemisphere N = North, S = South
5 00207.48 Longitude Value DDDMM.MM
6 W Hemisphere E = East, W = West
7 1 Fix quality
8 Number of satellites being trackedNote 1
9 Horizontal Dilution of Precision Note 1
10 64.00 Altitude (WGS-84 ellipsoid)
11 M Altitude units - Metres
12 Geoid separation Note 1
13 Separation units - Metres Note 1
14 Time since last DGPS update Note 1
15 DGPS station ID number Note 1
16 *0B Message Checksum. 2 hex digits after the * character.
Note 1: The terminal does not use these fields. On output they are always empty, on input they are ignored
Table 51 – NMEA GGA Sentence Format

GSV sentences (output only) are of the form:

$GPGSV,4,1,14,03,84,155,23,06,72,118,16,07,17,280,25,08,16,320,19*70

Where the message fields, separated by commas, have the following functions.

Field Number Contents Meaning


1 GPGSV Message header/identifier
2 4 Number of sentences for full data
3 1 Sentence 1 of 4 (in this example)
4 14 Number of satellites in view
Then, the following information is provided for up to 4 satellites per sentence:
5 03 Satellite PRN number
6 84 Elevation, degrees
7 155 Azimuth, degrees
8 23 SNR
.
.
.
21 (max) *0B Message Checksum. 2 hex digits after the * character.
Table 52 – NMEA GSV Sentence Format

© Satamatics Ltd Page 104 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.16 Script Debugging Messages


The terminal can be configured to output messages to aid in the debugging of scripts. These messages
take the form of one unsolicited output message each time that an operation chain is called and a
message for each timer or alarm that is triggered. The message output starts with a message
containing a list of each of the operations that are performed in the process chain, followed by either a
timer or alarm message showing the trigger event for the operation chain. Script debugging messages
can be switched on with a ‘PS 3’ and off with a ‘PS 1’ command, section 7.13.4. Script debugging
messages must not be enabled when a GEM-100 is used.

7.16.1 za - Alarm Trigger Message


The za message is output each time that an alarm triggers. The message identifies the alarm channel
that has been triggered. The message follows the operation chain message that was triggered by the
alarm.

Message Format za<SP><alarm><CR><LF>

<alarm> single ASCII hex character identifying the alarm channel that was
triggered.

7.16.2 zo – Operation Chain Message


A zo message is output each time that an operation chain is triggered. The message contains a list of
all of the operations that have been triggered in the chain.

Message Format zo<SP><Op_1><SP><Op_2>…<SP><Op_N><CR><LF>

<Op_X> 2 digit ASCII hex number identifying the operation step that has been
performed.

7.16.3 zt – Timer Trigger Message


The zt message is output each time that a timer triggers. The message identifies the timer channel that
has been triggered. The message follows the operation chain message that was triggered by the timer.

Message Format zt<SP><timer><CR><LF>

<timer> single ASCII hex character identifying the timer channel that was
triggered.

© Satamatics Ltd Page 105 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.17 Error Messages


When the processor detects an error in the command it responds with an error report. Error codes
above 0x80 indicate that the DSP has detected an error in a command sent to it by the MSP.

The error report message is of the form

Response Format er<SP><error_code><CR><LF>

<error_code> 2 digit ASCII hex number indicating the error detected.

Error Code Meaning


10 Invalid Command, Command not recognised
11 Response from the DSP not recognised

20 Bad Parameter entered for command, unable to decode the parameter value or
the parameter outside the legal range
21 An invalid ocean region selected
22 An invalid Service ID selected
28 Bad Serial Number (corrupted memory)
29 Stored script error (corrupted EEROM)

30 Error defining a Geofence


31 Invalid Geofence point entered
32 The requested target position has not been defined
38 The message database is not open for new message definitions
39 Bad message number definition supplied (BD Command)
3A Bad message field definition supplied (BF Command)

40 Unable to communicate with the GPS module


41 MSP clock failure
42 Timeout on heartbeat message from the DSP. The terminal will go into sleep
mode before trying to restart the terminal operation.
48 GPS Communications error

90 DSP Invalid Command, Command not recognised


91 DSP Bad Arguments, The number of arguments given with the command was
not as expected
98 Out of range update to the DSP Real Time Clock
99 The DSP has not received a heartbeat message from the MSP in the last 3
seconds. The DSP peripherals will be held low and this error message sent out
every second. MSP will attempt a terminal reboot.

A0 DSP Bad Parameter entered for command. The value of one or more of the
arguments was out of range
A1 DSP invalid ocean region selected
A2 DSP invalid Service ID selected
A3 Invalid command used
A4 DSP invalid satellite selection mode selected

© Satamatics Ltd Page 106 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Error Code Meaning


A5 Invalid Tx Frequency
A6 Invalid Rx Frequency

C0 Access to command denied. Password required.


C1 FLASH read error
C2 FLASH write error
C3 PID corrupted – Contact Satamatics

D0 Transmit Queue error


D1 Transmit queue full
D2 Transmit Acknowledgement error
D3 Unexpected forward channel acknowledgement received
D4 Transmit inhibit message received from the LES – Contact Satamatics
D5 Data Log is empty
D6 Data Log Error
D7 Cannot transmit as no valid UTC time has been set

E0 Forward channel message buffer overflow


E1 Forward channel message buffer empty
E2 Forward channel message buffer no more data

F0 Hardware RF failure
F1 Hardware RF OK
F2 Hardware RF failure switching Inmarsat-D off
F3 DSP Task scheduler overflow – contact Satamatics
F4 DSP Task scheduler error – contact Satamatics

Table 53 – Terminal Error Report Codes

© Satamatics Ltd Page 107 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

7.18 Command Summary


The serial interface commands are summarised in this section, for details on ‘over the air’ remote
control of the terminal Sse section 6 or contact your service provider.

Table 54 provides a summary of the terminal commands. Commands are available on all SAT-200
based terminals apart from those whose description refers to [GEM-100] or [MODBUS]:

[GEM-100] = Only available or applicable if terminal used with GEM-100


[MODBUS] = Only available on MODBUS enabled terminals

Some explanation of the columns in Table 54 is provided below:

Command:
The serial command without parameters

Associated Scripting Register Address(es):


The scripting registers that are associated with or modified by the serial command. The
registers are indicated by their hexadecimal module and register numbers. Where possible
direct access of the scripting registers using the RR/RW command should be used in
preference to the indirect serial command access. Where no scripting register is provided, the
function cannot be accessed via a script.

Description:
A brief description of the command function

R/W:
Indicates whether the command is Read only, Write only or Read/Write. (Also see note 1 at
the end of the table.)

Non-volatile:
- = Not applicable or not stored in non-volatile memory
1 = Parameters stored to non-volatile memory, or their default values restored from
non-volatile memory, through the DS TZ command. See paragraph 7.14.16.
2 = Parameters stored to non-volatile memory by the CZ command (paragraph 7.3.13)
3 = Parameters stored to non-volatile memory by the GW command (paragraph 0)
4 = Parameters stored to non-volatile memory by the BW command (paragraph 7.12.6)
Auto = Automatically stored to non-volatile memory

Default Value:
Factory/Operational default values as applicable.

Password (See paragraph 7.14.2):


- = No password required
1 = Application Service Provider (ASP) level.
2 = Service ID Level
** = Local (serial port) access to these commands (includes all DS prefixed commands)
can be disabled by an ‘Over the air’ password command.

© Satamatics Ltd Page 108 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Command Associated Scripting Description R/W Non- Default value Pass-


Register Address(es) volatile word
(Hexadecimal)
DS -- All DS prefixed commands **
DS PW Enter access password W - -
DS TA 0 57 to 0 5B Note 1 Service ID R/W 1 2,22,23,24,25 2
DS TC 0 50 Note 1 PSN R/W 1 Last Char ISN 1
DS TE 0 57 to 0 5B Note 1 Beam ID R/W 1 0,0,0,0,0 1
DS TG 0 52 to 0 56 Note 1 Group ID’s R/W 1 All zero 1
DS TK 5 28 Transmission retries R/W 1 1 -
DS TM 0 5D Mobility R/W 1 Non-Aero 1
DS TN 0 50 ISN R - See unit base -
DS TO 0 5C Note 1 Operational Flags R/W Auto 0 1
set only
DS TR 5 22 Receiver status R - -
DS TS 5 21 and Signal status R - -
5 29 to 5 2C
DS TT 5 23 Transmitter status R - -
DS TW 5 2E Note 1 Tx Queue Configuration R/W 1 9,0 1
DS TZ Write or restore configuration to/from W - 1
non-volatile memory

CA 0 02 Satellite selection mode R/W 2 Disabled **


CB 0 00 Ocean Region R/W 2 AORE **
CE 0 03 Power control state R/W 2 0xDF **
CF Factory defaults W Auto **
CI 0 01 Service ID index R/W 2 0 **
CN 0 20 NMEA output control R/W 2 Disabled **
CP 0 06 Firmware version (MSP) R - -
CR Reload script from FLASH W - **
CS 0 07 Script Application version R/W 2 -
CU 0 03 Operating power mode R/W 2 Mobile **
CV 0 05 Firmware version (DSP) R - -
CW Erase script from RAM W - **
CZ Store script to FLASH W - **

IA 3 10 to 3 17 Analog input R - -
IC 3 02 Configure inputs/outputs R/W 2 SAT-202 I/O: **
HV digital in
SAT-202 Output:
Disabled
SAT-200 extended I/O:
Digital out
ID 3 00 Digital inputs R - -
IE 3 01 Digital outputs R/W 2 0 **
II 0 0A [GEM-100] Ext power supply status R -
IO 3 03 [GEM-100] Battery power output - IO7 R/W 2 0 **
IP 3 18 MSP supply voltage level R - -
IQ 3 1C [GEM-100] Battery pack temperature R - -
IS 3 19 External power supply voltage level R - -
IT 3 1A MSP temperature R - -
IU 3 30 [GEM-100] User LED Control R/W - 0 **
IX 3 1B [GEM-100] Battery voltage level R - -

TC 1 10 to 1 1F and Configure timer R/W 2 Stopped **


1 90 to 1 9F
TD 1 28 Disable timers W - **
TE 1 28 Enable timers W - **
TM 1 40 to 1 4B and Timer trigger value R/W 2 **
1 A0 to 1 AF (timers 0 to 11 and 16 to 31)
1 4C to 1 4F Timer trigger value R/W Auto **
(timers 12 to 15)
TR 1 22 Reset timers W - **
TS 1 23 Restart timers W - **

© Satamatics Ltd Page 109 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Command Associated Scripting Description R/W Non- Default value Pass-


Register Address(es) volatile word
(Hexadecimal)
TT 1 30 and Current time and date (UTC) R 12:00:00 -
1 32 to 1 37 23/07/04
TV 1 00 to 1 0F and Current timer value R - **
1 80 to 1 8F

AC 2 10 to 2 1F and Configure alarms R/W 2 Clear **


2 50 to 2 5F
AD 2 30 Disable alarms W - **
AE 2 31 Enable alarms W - **
AF 2 33 Trigger alarms W - **
AR 2 32 Reset alarms W - **
AT 2 20 to 2 2B and Alarm threshold R/W 2 **
2 60 to 2 6F (alarms 0 to 11 and 16 to 31)
2 2C to 2 2F Alarm threshold R/W Auto **
(alarms 12 to 15)

OC 7 00 to 7 1F and Configure operation R/W 2 Reset **


7 80 to 7 9F
OD 7 40 and 7 44 Disable operations W - **
OE 7 41 and 7 45 Enable operations W - **
OR 7 42 and 7 36 Reset operations W - **
OT 7 43 and 7 47 Trigger operations W - **

GM GPS satellites signal strengths R - **


GS 4 01 GPS status R - Invalid -

GA 4 05 GPS altitude R - -
GH 4 04 GPS heading R - -
GP 4 01 and 4 02 GPS position R - -
GV 4 03 GPS speed R - -

GD Define Geofence initialisation R/W 3 Invalid **


GF Define Geofence point R/W 3 **
GW Store Geofence to FLASH W - **
GZ Define Geofence Zone R/W 3 **

GK 4 40 to 4 47 Distance to Target position R - **


GL 4 20 Distance to Reference point R - **
GR 4 11 and 4 12 Define Reference point R/W - 0:0:0 0:0:0 **
GT 4 50 to 4 5F Define Target position R/W Auto Invalid **
GX 4 10 Set Reference point to current position W - **

GE GPS Software version R - **


GI GPS Position logging rate R/W Auto 0 **
LN Number of logged records R - **
LR Get log record R - **

MA 5 11 and 5 13 Tx message – destination address field R/W 2 0 **


MB 5 10 Transmit a predefined message W - **
MC Number of messages in receive buffer R - -
MK 5 14 Tx message – acknowledge flags field R/W 2 0 **
ML 5 13 and 5 15 Tx message – Control flags field R/W 2 9 **
MM Transmit a message W - -
MN Get received message R - -
MO 5 40 Enable/disable unsolicited output of R/W 2 **
received messages
MP 5 31 Configure automatic transmit R/W Auto **
MQ 5 38 to 5 3B Response to ‘tone only’ message R/W 2 0 **

© Satamatics Ltd Page 110 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

Command Associated Scripting Description R/W Non- Default value Pass-


Register Address(es) volatile word
(Hexadecimal)
MR 5 20 to 5 22 and Receiver status R - -
5 29 to 5 2C
MS 5 24 Transmit slot randomisation R/W 2 1 **
MT 5 23 Transmitter status R - -

SR 6 00 to 6 0F Scratchpad registers R/W 2 0 **

RR All scripting registers Read Register R **


RW All scripting registers Write register W - **

BD Define user message number W 4 No messages **


BF Define user message field contents W 4 **
BI Initialise user message database W 4 **
BN Number of user message definitions R - **
BQ User message definition R - **
BW Close the user message database W Auto **

PD Program upload W - -
PI 0 FE Reset W - -
PR Serial baud rate W Auto 9600 **
PS Enable/disable scripting R/W - 1 **
PT Run production tests - **
PV Bootloader version number R - -
PY Date/time of software build R - -
PZ Serial Number R - -

XC [MODBUS] configuration register R/W 2 **


XD [MODBUS] slave data register R/W 2 **
XE [MODBUS] Error counter R/W 2 **
XM [MODBUS] slave message register R/W 2 **
XT [MODBUS] Target Action Register R/W 2 **

mf Inmarsat-D received message - - -


pa Program record acknowledge - - -
pn Program record NAK - - -
za Script debug – alarm triggered - - -
zo Script debug – timer triggered - - -
zt Script debug – operation performed - - -

$A NMEA input - - -
$G NMEA input - - -
Note 1: Write access to these scripting register parameters is only available through the use of the password protected DS prefixed command.

Table 54 - Command Summary

© Satamatics Ltd Page 111 of 111


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

A APPENDIX A – EXAMPLE GEOFENCE DEFINITION

A.1 Introduction
The terminal allows for the definition of two complex geofenced areas. A geofence is an area defined
by a number of points on the earth’s surface joined together by straight lines. The terminal tests the
current position returned by the GPS module in the terminal against these defined areas and reports
whether the terminal is currently inside or outside the fenced area.

A.2 Definition
The geofence algorithm used in the terminal divides the complex fenced area up into a number of
zones. The testing algorithm then checks each of the zones in turn.

A
X
D

C
B

Figure 4 - Zoned Geofence

In Figure 4 the fenced area ABCDEF is split into two zones ABEF and BCDE. The point X will be
detected in the first of these zones.

The geofence definition method uses a two-stage definition process. The first stage is to have a table
of all of the corner positions. This table is defined to have 40 entries. These table entries may be in
any order, and need not all be used. The second stage is to have a zone definition table. This starts
with the number of zone definition entries there are. Each entry in the zone definition table has the
following structure:

Number of points in zone definition


Point ID 1
Point ID 2
:
:
Point ID n
The Point ID values indicate which of the entries in the corner position table are used to define the
zone. There may be a total of 188 values stored in this table.

© Satamatics Ltd Page A-1 of 4


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

The definition for the fence shown in Figure 4 would be as follows:


Latitude A Longitude A
Latitude B Longitude B
Latitude C Longitude C
Latitude D Longitude D
Latitude E Longitude E
Latitude F Longitude F
Co-ordinate Table

Number of zones = 2
Number of points in zone = 4
Point ID = A
Point ID = B
Point ID = E
Point ID = F
Number of points in zone = 4
Point ID = B
Point ID = C
Point ID = D
Point ID = E
Zone Definition Table

A.3 Geofence Constraints


There are two constraints that must be observed when defining a geofence:

1. The points must be defined in an anti-clockwise (counter-clockwise) direction going around


each of the zones in the fence
2. The internal angle at each of the zone corners must be less than 180°.

A.4 Geofence Definition Sequence


Once the points that make up the fence have been selected, the geofence is defined using 4 different
commands issued in sequence:

1. The GD command (para. 7.8.3.1) initiates the fence definition process by specifying the fence
number, and defining the number of points and zones that it contains.
2. The GF command (para. 7.8.3.2) is then used to define each point in the fence. A sequence of
GF commands is require, one for each point.
3. Once all of the points have been defined the zones within the fence have to be defined. This
involves a sequence of GZ commands (para. 7.8.3.4), one for each zone.
4. Finally a GW command (para. 7.8.3.3) is issued to verify that all of the points referenced in
the zone definitions exist in the list of points and that the correct number of points and zones
have been defined. If these criteria are met then the fence is enabled for use by the scripting
functions.

© Satamatics Ltd Page A-2 of 4


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

A.5 Example Geofence Definition


This example shows a fence that is made up of two disjoint areas, encircling the two towns. It is
made up from 8 points and 2 zones. The boundary of the fence can be seen on the map screenshot
and the defining command sequence is listed out below.

The command sequence for this example fences is:


GD 1 8 2
GF 1 1 +052 05 19.00 -002 17 10.00
GF 1 2 +052 05 28.99 -002 21 40.00
GF 1 3 +052 01 57.99 -002 22 20.00
GF 1 4 +052 01 31.99 -002 17 10.00
GF 1 5 +051 55 52.99 -002 06 02.00
GF 1 6 +051 55 16.00 -002 09 36.00
GF 1 7 +051 52 21.00 -002 09 51.00
GF 1 8 +051 52 16.00 -002 05 52.00
GZ 1 1 4 01 02 03 04
GZ 1 2 4 05 06 07 08
GW 1

© Satamatics Ltd Page A-3 of 4


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

The same fence definition written in TSL is:

// Define the 8 point locations at the corners


// of the fence zones

DECLARE Point_1 AS POSITION


{
LATITUDE = +052 05 19.00
LONGITUDE = -002 17 10.00
}
DECLARE Point_2 AS POSITION
{
LATITUDE = +052 05 28.99
LONGITUDE = -002 21 40.00
}
DECLARE Point_3 AS POSITION
{
LATITUDE = +052 01 57.99
LONGITUDE = -002 22 20.00
}
DECLARE Point_4 AS POSITION
{
LATITUDE = +052 01 31.99
LONGITUDE = -002 17 10.00
}
DECLARE Point_5 AS POSITION
{
LATITUDE = +051 55 52.99
LONGITUDE = -002 06 02.00
}
DECLARE Point_6 AS POSITION
{
LATITUDE = +051 55 16.00
LONGITUDE = -002 09 36.00
}
DECLARE Point_7 AS POSITION
{
LATITUDE = +051 52 21.00
LONGITUDE = -002 09 51.00
}
DECLARE Point_8 AS POSITION
{
LATITUDE = +051 52 16.00
LONGITUDE = -002 05 52.00
}

// Declare the Geofence to have two zones defined by the


// Locations already defined.

DECLARE Fence AS GEOFENCE USE 1


{
ZONE
{
POINT Point_1
POINT Point_2
POINT Point_3
POINT Point_4
}
ZONE
{
POINT Point_5
POINT Point_6
POINT Point_7
POINT Point_8
}

© Satamatics Ltd Page A-4 of 4


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

B APPENDIX B – EXAMPLE USER MESSAGE DEFINITION


The terminal allows the user to define the contents of the user data field in a return channel message
by taking blocks of one or more bits from its internal registers and concatenating these into the data
block to be transmitted. This allows, for example, the data block being transmitted in a single
message to contain the states of selected digital input lines, a timestamp, the top N bits of one of the
analogue input values and the external supply voltage. This is all defined by the user in a set of
message configuration commands and stored in non-volatile memory so that the message format is
not lost if the terminal power is removed.
The message definition procedure starts by defining the identifier number to be used for the message
and the number of field definitions to be used in generating the user data block. The message data
fields are then defined in terms of the data source register and the bits to be extracted from that
register.

B.1 Message Number Definition


Each message to be defined in a terminal must have a unique message number assigned to it. User
message formats defined using the scheme detailed in this document can have message numbers in the
range 0x80 to 0xFE inclusive, message numbers 0x00 to 0x7F are reserved for the standard message
definitions built in to the terminal. This message number identifies the message data format to the
receiving application allowing the data contained by the message to be decoded and displayed to the
end user. The message number definition also includes the number of data field definitions used to
generate the user data payload.
User message numbers in the range 0x80 to 0xBF are for 64-bit payload messages. Message ID
numbers in the range 0xC0 to 0xFE define messages with 80-bit payloads. A double length message
(IsatM2M service) can be defined for a message number in the range 0x80 to 0xBF and defining 148
payload data bits

B.2 Message Field Data Selection


A message data field is a number of bits extracted from one of the scripting module registers listed in
section 5. The bits to be extracted from the register are defined by a bit mask. If a bit in the mask is
set then the corresponding bit from the data source register is included in the transmitted data block.
The bits from the source register will be included in order from most significant to least significant.
The bits included do not have to be consecutive, i.e. it is possible to extract bits 7, 4, 3, 1 and 0 in that
order using a single field definition (in this case the bit mask would be 0x9B [1001 1011 binary]).
This allows the message to contain, for example, selected digital input bits.

B.3 Message Definition Rules


The user message database can contain a maximum of 16 message number definitions and 72 data
field definitions. The maximum number of field definitions that may be used to generate a message is
64, in the case where each bit is defined to be from a separate data register. The minimum number of
field definitions is two, in the case where the full 32 bits are used from the two data source registers.
The message database is full when either the maximum number of message numbers or message
fields have been defined.
Message numbers must be between 0x80 and 0xFE (128 and 254). Message numbers below 128 are
reserved for the built in message formats used by the terminal.

© Satamatics Ltd Page B-1 of 4


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

The message field definitions for a message must define exactly 64, 80 or 148 bits. If an incorrect
number of bits are defined then the message will not be generated for transmission.

It is not possible to reduce the number of field definitions used by sharing individual data field
definitions between messages. It is possible to have multiple message numbers sharing the same
payload definition. This is done by issuing a number of message number definition commands before
the first field definition command.

The data field definitions for a message are packed into the user data block in the order that their
definitions are sent to the terminal.
The fields used to define the message block are the N field definitions sent after the message number
definition command. If less than N field definitions are sent then the results are undefined. The
terminal does not check this condition.

B.4 Message Definition Commands


The commands used to program the message database and reading back message definitions are
detailed in section 7.12. In summary they are:

BI - Initialise the database


BD - Define the message number
BF - Define the user data block
BW - Close the database

BN - Reports the number of messages in the database


BQ - Reports message formats from the database

B.5 Programming Command Sequence


A typical programming command sequence will be.
1. Issue a BI command to initialise the database
2. BD command to define the user message number
3. Sequence of BF commands to define the user data block for the message
4. Repeat steps 2 and 3 for all the messages to be defined
5. Issue a BW command to close the database.

If it is required to have more than one message number with the same data format then step 2 should
be repeated for all of the message number definitions before moving on to step 3.

B.6 Example - Time Stamped Analogue Input Report


There are a number of ways that a message may be time stamped, each providing different
resolutions. In this message the time stamp is taken from the real time clock minutes and seconds
registers with the remote application being left to deduce the hours field from the time of arrival of the
message. An alternative would be to use all or part of the UTC time in seconds past midnight register.
The number of bits used from this register only needs to be sufficient for the end application to
deduce the actual time of message generation from the value and the time of delivery of the message.
The analogue values being transmitted are three analogue input channels – each limited to 10-bit
resolution. The resolution is selected by the mask value used. In this case the mask value has bits set

© Satamatics Ltd Page B-2 of 4


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

for the 10 most significant bits of the 12-bit analogue conversion result. This has the effect of
discarding the two least significant data bits, performing a truncation operation on the data value.
The remaining bits in the message are transmitted as zeros.
The field definitions for the message format are shown in Table 55.
Field No Field Data Module ID Register ID Mask Value Bits Used
1 UTC Minutes 0x1 0x36 0x3F 6 (6)
2 UTC Seconds 0x1 0x37 0x3F 6 (12)
3 Analogue Input 2 0x3 0x12 0xFFC 10 (22)
4 Analogue Input 5 0x3 0x15 0xFFC 10 (32)
5 Analogue Input 7 0x3 0x17 0xFFC 10 (42)
6 Constant Zeros 0xF 0x00 0x3FFFFF 22 (64)
Table 55 – Example Message Definition

This message definition uses 6 field definitions and is being allocated a message number of 160
(0xA0). The command sequence used to define this message is shown below.
BI
BD A0 06
BF 136 0000003F
BF 137 0000003F
BF 312 00000FFC
BF 315 00000FFC
BF 317 00000FFC
BF F00 003FFFFF
BW

The BQ response for the message format defined in this example is shown below (assuming that this
is the first message stored in the message database):
bq 1 A0 136 0000003F 137 0000003F 312 00000FFC 315 00000FFC
317 00000FFC F00 003FFFFF

© Satamatics Ltd Page B-3 of 4


Commercial In Confidence
SAT-200/202 SCRIPTING API AND COMMAND INTERFACE
GDN-0559 Issue 1

C APPENDIX C – NOTES FOR USERS MIGRATING FROM


THE SAT-201 SERIES.

The following differences between the SAT-202 and SAT-201/201i series should be noted:

SAT-201/201i SAT-202
Inmarsat-D modes of operation D+ & IsatM2M IsatM2M only
General Purpose Inputs/Outputs 2 3
Open Drain Outputs 2 1

Important: When configuring the I/O via a


script, RW command or IC command, this
output must be configured as Open Drain
(mode 9 – see 5.6.1). Any SAT-201/201i
script that configures this output as mode 1
must be changed such that the output is
configured to mode 9.
Temperature sensor ±2°C Indication only
Firmware upgrade speed 9600 baud Selectable up to 115 kbaud
GPS engine 20 channel SiRF Star III 50 Channel uBlox
Data logger Separate GPS & Transmission logs Single, integrated log for GPS,
Transmissions and Data
Additional scripting registers Module 0x0 Registers 0x50 to 0xFE
(Accessible via script and RR/RW Module 0x3 Register 0x1F
command) Module 0x5 Registers 0x28 to 0x2E
See 5.2.1 and 5.2.6 for details
Script register changes:
Module 0x4 Register 0x08 GDOP HDOP
Commands no longer available or DS DO Get Tx log size
supported DS DR Get Tx log record
DS TJ Get SIDs and BIDs
IB Set Analog outputs
GU GPS update rate
GY UTC synchronisation period
GN Get GPS log size
GO Get GPS log record – position
GQ Get GPS log record - motion
PG GPS Boot control
New commands LN Get number of logged records
LR Get log record
PZ Get Serial Number
Command execution differences PY PY? (requires question mark)
RR 4 15? RW 4 15 0 (write instead of read function)

GEM-100 operation Any script that uses a GEM-100 will need


to be modified to include the following
configuration command;

RW 0 FD 1

See 5.3.21

© Satamatics Ltd Page C-4 of 4


Commercial In Confidence