OpenAMIP v1_7_ICD_E0001657 - General Edition v4_4a

Date Rev Revision Record Approved Nov 6, 11 1 Initial Release

Nov. 30, 11 4 Post-CDR Ready

Dec. 1, 11 4.1 Updates

Jan. 31, 12 4.2 Updates

Feb. 10, 12 4.3 Update H command

May 4, 2012 4.4 Prepare for Web

Approvals Date

SW Engineering Approval:

iDirect Supply Chain Approval:

Manufacturer #1 Approval:

Specification: OpenAMIP V1.7 ICD

Manufacturer #2 Approval:

Sheet 1 of 27 SIZE A

No. E0001657

iDirect

Copyright © 2012, iDirect

No. E0001657

Rev. 4.4

Sheet 2 of 27

iDirect

TABLE OF CONTENTS

1.0 INTRODUCTION ........................................................................................................................ 6 1.1 ACRONYMS ............................................................................................................................... 6 2.0 GENERAL NOTICE .................................................................................................................... 9 2.1 DISCLAIMER ............................................................................................................................. 9 3.0 OPENAMIP INTERFACE ......................................................................................................... 10 3.1 SCOPE ..................................................................................................................................... 10 3.2 OVERVIEW .............................................................................................................................. 10 3.2.1 Sample Communication Sequence .................................................................................... 11 3.2.2 Extensions to OpenAMIP v1.7 ............................................................................................ 12 3.2.3 New In OpenAMIP v1.7 ........................................................................................................ 13 3.2.4 New In OpenAMIP v1.7 General Edition ............................................................................. 13 4.0 OPENAMIP V1.7 SPECIFICATION .......................................................................................... 15 4.1 LEGAL MATTERS ................................................................................................................... 15 4.1.1 Certification.......................................................................................................................... 15 4.2 OVERVIEW .............................................................................................................................. 15 4.3 REQUIREMENTS AND EXAMPLES ........................................................................................ 16 4.4 HARDWARE COMPATIBILITY ISSUES .................................................................................. 17 4.5 SEMANTICS ............................................................................................................................. 18 4.6 OPENAMIP VERSION COMPATIBILITY ................................................................................. 20 4.7 FORMAL SYNTAX ................................................................................................................... 20 4.7.1 Specific Messages ............................................................................................................... 21 4.8 SIMULATION AND VALIDATION ............................................................................................ 25 4.9 TCP INTERFACE ..................................................................................................................... 25 4.10 UDP INTERFACE ..................................................................................................................... 26 4.11 ASYNCHRONOUS SERIAL INTERFACE ................................................................................ 26 4.12 REFERENCE IMPLEMENTATIONS ........................................................................................ 26 4.13 TEST SUITE ............................................................................................................................. 26 4.14 SOFTWARE AVAILABILITY .................................................................................................... 26 4.15 MODEM MODULE REFERENCE DESIGN .............................................................................. 26


No. E0001657

Rev. 4.4

Sheet 3 of 27

iDirect

LIST OF TABLES Table 1: Supported OpenAMIP Commands .................................................................................... 12 Table 2: Key/Value Pairs for the Antenna "IDIRECT:ident" Message............................................ 13


No. E0001657

Rev. 4.4

Sheet 4 of 27

iDirect

LIST OF FIGURES

Figure 1: OpenAMIP System Overview ........................................................................................... 11 Figure 2: Sample Communication between Modem & ACS using OpenAMIP .............................. 12 Figure 3: OpenAMIP Commands during Power Calibration .......................................................... 13


No. E0001657

Rev. 4.4

Sheet 5 of 27

iDirect

Revision History

Record of Change

Revision Date Comments 1.0 Nov 17, 2011 Initial Draft Release 4.0 Nov. 30, 2011 Post-CDR Ready 4.1 Dec. 1, 2011 Removed “Draft” 4.2 Jan 31, 2012 Update Table-1, Section 4.2 4.3 Feb 10, 2012 Updated H Command 4.4 May 4, 2012 Prepared for Web Publishing

Sign Off Sheet

Name Title Date Signature

Hai Tang VP, Advanced Development - iDirect 10-Feb-2012 Hai Tang

Ratima Kataria Director, Program Management Office - iDirect 10-Feb-2012 Ratima Kataria


No. E0001657

Rev. 4.4

Sheet 6 of 27

iDirect

1.0 INTRODUCTION

1.1 ACRONYMS 16APSK Sixteen Amplitude and Phase Shift Keying 8PSK Eight Phase Shift Keying A/D Analog/Digital A-TDMA Adaptive Time Division Multiple Access ABS Automatic Beam Switching ACM Adaptive Coding and Modulation ACQ ACQusition ACS Antenna Control System AIM Antenna Interface Module BB BaseBand BIM Broadband Interface Module BPN BUC Part Number BPSK Binary Phase Shift Keying BUC Block Up Converter C/IM Carrier to InterModulation ratio C/N Carrier to Noise ratio CA Certificate Authority CG Center of Gravity COTM Comms On The Move COTS Commercial Off The Shelf CW Continuous Wave DAC Digital to Analog Convertor dB deciBel dBi deciBel(isotropic) dBm deciBel-milli-watt dBW DeciBel-Watt DSP Digital Signal Processing DVB-S2 Digital Video Broadcasting over Satellite, second generation Eb/N0 Energy-per Bit to Noise-power-spectral density ratio EEPROM Electrically Erasable Programmable Read-Only Memory EIRP Effective Isotropic Radiated Power EMC ElectroMagnetic Compatibility EMI ElectroMagnetic Interference EMP ElectroMagnetic Pulse EOC Edge of Coverage ETSI European Telecommunications Standards Institute FCC Federal Communication Commission FEC Forward Error Correction FFT Fast Fourier Transform FID BUC Functional ID FLL Frequency-Locked Loop FPGA Field Programmable Gate Array


No. E0001657

Rev. 4.4

Sheet 7 of 27

iDirect

FSK Frequency Shift Keying G/T Gain-to-system noise Temperature ratio GHz GigaHertz GPIO General Purpose Input/Output GPS Global Positioning System GQoS Group Quality of Service GS Global Service GUI Graphical User Interface HPA High Power Amplifier HW HardWare IC Industry Canada ICD Interface Control Document IEC International Electrotechnical Commission IF Intermediate Frequency IFFT Inverse Fast Fourier Transform IFL Inter-Facility Link IP Ingress Protection rating (Ter.3) IP Internet Protocol ITAR International Traffic in Arms Regulations Kbps Kilobits per second KHz KiloHertz Ksps Kilo symbols per second LAN Local Area Network LED Light Emitting Diode LHCP Left Hand Circular Polarization LNA Low Noise Amplifier LNB Low Noise Block converter M&C Monitor & Control Mbps Megabits per second MHz Mega Hertz MID BUC Manufacturer ID MODCOD MODulation and CODing MOP Maximum Operational Power Msps Mega symbols per second MTBF Mean Time Between Failures MTTR Mean Time To Restore NF Noise Figure OBO Output Back Off ODU OutDoor Unit OMT Orthogonal Mode Transducer OOB Out Of Band OpenAMIP Open Antenna Modem Interface Protocol OTA Over The Air


No. E0001657

Rev. 4.4

Sheet 8 of 27

iDirect

OTP One-Time-Programmable PA Power Amplifier PDR Preliminary Design Review PLL Phased Locked Loop QEF Quasi Error Free QPSK Quadrature Phase Shift Keying R&TTE Radio and Telecommunications Terminal Equipment RA Regulatory Agency RCS Return Channel via Satellite RF Radio Frequency RFS Radio Frequency Subsystem RHCP Right Hand Circular Polarization RMS Root Mean Square RoHS Restriction of Hazardous Substances Rx Receive SAC Satellite Access Control SAS Satellite Access Station SATCOM SATellite COMmunications SCPC Single Channel Per Carrier SFD Saturation Flux Density SN BUC Serial Number SNMP Simple Network Management Protocol SNR Signal to Noise Ratio SW SoftWare TBD To Be Defined TCP Transmission Control Protocol TDM Time Division Multiplexing TDMA Time Division Multiple Access TE Terminal Equipment TWTA Travelling Wave Tube Amplifier Tx Transmit UAS Unmanned Aircraft System UAV Unmanned Aerial Vehicle UL Underwriters Laboratories ULPC UpLink Power Control VAC Volts Alternating Current VDC Volts Direct Current VLAN Virtual Local Area Network VSAT Very Small Aperture Terminal W/G WaveGuide WDM Wave Division Multiplexing


No. E0001657

Rev. 4.4

Sheet 9 of 27

iDirect

2.0 GENERAL NOTICE

2.1 DISCLAIMER While iDirect strives to make the information in this document as accurate as possible, iDirect makes no claims, promises, or guarantees about the accuracy, completeness, or adequacy of the contents of this document, and expressly disclaims liability for errors and omissions in the contents of this document. No warranty of any kind, implied, expressed, or statutory, including but not limited to the warranties of non-infringement of third party rights, title, merchantability, fitness for a particular purpose, is given with respect to the contents of this document.


No. E0001657

Rev. 4.4

Sheet 10 of 27

iDirect

3.0 OPENAMIP INTERFACE

3.1 SCOPE This document describes how the OpenAMIP protocol is implemented in a satellite terminal. This document is intended for use with a variety of terminals, whether maritime, aeronautical, land mobile, or fixed installation. As such, wherever possible, it uses terminology which is agnostic to terminal type.

3.2 OVERVIEW OpenAMIP is an IP based protocol that facilitates the exchange of information between an Antenna Control System (ACS) and a satellite modem. OpenAMIP allows the satellite modem to command the antenna and enables the use of Automatic Beam Switching (ABS), which transfers connectivity from one satellite beam to the next as a mobile platform passes through multiple beam footprints. In addition, OpenAMIP and ABS enable service providers and their customers to meet government regulations by commanding the antenna to mute the signal in no transmit zones.

All OpenAMIP commands and responses are exchanged between the modem and ACS alone.

The ACS also acts as a proxy for location data. The ACS may receive location data from a GPS associated with the antenna, or from another platform-based system such as gyro (NMEA) or ARINC 429. Regardless of source, the ACS translates location data to OpenAMIP format and provides it to the modem over an IP connection.

The modem interacts with the ACS, using OpenAMIP, to retrieve the location information. The modem requires location accuracy of 500 meters or less for beam selection purposes. The antenna controller will typically require additional data such as platform orientation, velocity, and geometric constraints, and will also require location updates at a sufficient rate to accurately position the antenna.


No. E0001657

Rev. 4.4

Sheet 11 of 27

iDirect

Figure 1: OpenAMIP System Overview

3.2.1 Sample Communication Sequence Figure 2 shows a sample communication between the Modem and the ACS using OpenAMIP. This ladder diagram illustrates several important operations:

• Power on, finding the acquisition channel • Switching from one data channel to another • Switching to a new satellite

Remote Terminal

Antenna

Antenna Control System (ACS)

Earth Station

Position System (GPS, gyro,

ARINC 429…)

OpenAMIP

Automatic Beam Switching, Position, etc.

Location Data

Automatic Beam Switching, Position, etc.

Modem

Antenna Commands Antenna Status


No. E0001657

Rev. 4.4

Sheet 12 of 27

iDirect

Figure 2: Sample Communication between Modem & ACS using OpenAMIP Modem Antenna Controller

L 1 0

Set up TCP session

Antenna finds satellite, locks to acquisition channel

H 29751.2 26.6

Modem switches to another downstream (Beam Switch)

Antenna finds satellite

Startup

S -20.1 0.5 0 (satellite longitude)

P L R (RX LHCP, TX RHCP)

H 29600.2 0.120 (Hunt frequency)

B 18250 28050 (LNB & BUC LO frequency)

K 90 (can be ignored by parabolic dishes)

W 30

w 1 23.51231 -22.13212 1320875731 0

Fi

s 1 0 0 0

s 1 1 0 0

L 1 1

Antenna finds correct outbound

Fi

s 1 1 0 0

L 1 0

L 1 1

Modem Decides to Switch Satellites

H 29850.1 26.6

Fi

s 1 1 0 0

H 29800 26.6

S -20.1 0.5 0 (satellite longitude)

Fi

s 1 0 0 0

s 1 1 0 0

L 1 0

L 1 1

(Terminal in normal operation)

(Terminal in normal operation)

Table 1: Supported OpenAMIP Commands

3.2.2 Extensions to OpenAMIP v1.7 The “ident” message is an example of an extension and is not a general purpose OpenAMIP command. It is used to pass information about the antenna components to the modem, for reporting to the hub. This message must be sent upon initial connection between the ACS and the modem. The IDIRECT:ident message must be formatted in the following manner, using keys and values as specified in Table 2:

IDIRECT:ident key1=val1,key2=val2,key3=val3,key4=val4…

As an example, the command may look like this:

IDIRECT:ident termtype=5,acuvendor=AntennaWorld, …


No. E0001657

Rev. 4.4

Sheet 13 of 27

iDirect

Additional key/value pairs may be added without affecting the system operation. The total length of the string must not exceed 500 bytes. If a terminal vendor wishes to include additional key value pairs which may be useful for field troubleshooting or debugging, they may do so. However, such fields should be added sparingly, and in no case shall the message size (including whitespace) exceed 500 bytes.

Table 2: Key/Value Pairs for the Antenna "IDIRECT:ident" Message Key Format Comment rftermtype int This must be the first key, and is required for system

operation. The value used is an integer from 1 to 32767. This value is the terminal type assigned by the Inmarsat type approval process. This field is called the “RF terminal Type”. If this key is not present, the terminal will NOT acquire into the network

acuvendor string Antenna Controller vendor identifier iDirect shall assign the Vendor identifier so that the Terminal can be integrated into the iDirect NMS.

The information sent in this interface is logged in the hub every time the terminal enters the network. Additional parameters are taken from the BUC interface and sent as well.

3.2.3 New In OpenAMIP v1.7 The “N” command is used during the power calibration process, as shown in Figure 3. While the BUC will be muted as part of the calibration process, the N command is used to point the antenna away from the geosynchronous arc as a safety precaution. In some cases, it may not be possible for the terminal to determine which direction is off the geosynchronous arc (for example, near the equator when the terminal orientation is unknown). In that case the terminal shall respond with an “s 1 0 0 0” message. The modem will still run the power calibration in that case.

Figure 3: OpenAMIP Commands during Power Calibration Core Module ACS

Antenna finds satellite

Modem Decides to Initiate BUC Power Calibration

N

Fi

s 1 0 0 0

s 1 1 0 0

Antenna points away from GEO arc

s 1 0 0 1

Modem runs power calibration

3.2.4 New In OpenAMIP v1.7 General Edition

The “c” command supports certain conical scan implementations which may require modem involvement. This command is not supported by iDirect modems.

The “r” command supports implementations where the reference frequency for the BUC and LNB is selectable.


No. E0001657

Rev. 4.4

Sheet 14 of 27

iDirect

The “w” command has additional parameters for altitude, heading, speed, pitch, roll, and yaw.


No. E0001657

Rev. 4.4

Sheet 15 of 27

iDirect

4.0 OPENAMIP V1.7 SPECIFICATION

Dan Clemmensen iDirect

Version 1.7 2011-9-20

STATUS: Draft

This document specifies a protocol for use between a satellite modem and an antenna controller to permit synchronized switching from one satellite to another.

4.1 LEGAL MATTERS This protocol specification is Copyright© 2007-2012 iDirect. All rights reserved.

The Protocol was invented by iDirect.

The name "OpenAMIP" is a trademark™ of iDirect.

Permission to copy and distribute this document in unmodified form is hereby granted to all without restriction. Modified forms of this document may be distributed, but only if this "legal matters" section is retained intact and provided that any document that describes a modified form of the protocol clearly states that the protocol is modified.

To the extent that iDirect has rights to control the protocol itself, iDirect grants rights to implement the protocol to all, without restriction.

Anyone may use the trademark "OpenAMIP" to describe an unmodified implementation of this protocol. Anyone may use the term "modified OpenAMIP" to describe a variant of this protocol, but only if the document containing the term "modified OpenAMIP" refers to this document.

4.1.1 Certification You may certify your compliance with the test suite yourself. If you do, you are free to use the trademark "OpenAMIP" freely for any product that you have certified. Alternatively, iDirect and other OpenAMIP implementers have certification programs and will certify your interface for a fee.

Your use of the OpenAMIP trademark authorizes any OpenAMIP implementer to validate your implementation and publish the results, referring to your product by company and product name, if the implementer finds your implementation to be non-compliant. A finding of non-compliance will not be published until thirty days after the OpenAMIP member notifies you of the finding. At your option, the implementer’s published finding of non-compliance shall include a reference to a statement in rebuttal by you.

4.2 OVERVIEW OpenAMIP is an ASCII message-based protocol. We considered a WSDL implementation and found it to be too complex for this simple problem.

OpenAMIP is a specification for the interchange of information between an antenna controller and a satellite modem. OpenAMIP allows the modem to command the controller to seek a particular satellite. OpenAMIP also allows the modem and controller to exchange information necessary to permit the modem to initiate and maintain communications via the antenna and the satellite.

OpenAMIP is intended to be simple and flexible. Communications are in the form "messages" of human-readable ASCII characters. The messages may be conveyed via any


No. E0001657

Rev. 4.4

Sheet 16 of 27

iDirect

of several lower-level protocols, such as HTTP, TCP/IP over a LAN, UDP over a LAN, or via a high-speed serial connection.

In a narrow sense the use of human-readable text is inefficient, but the messages flow rarely, and they flow on a high-bandwidth LAN, not on the satellite link.

OpenAMIP is not intended for any purpose except to permit a modem and a controller to perform synchronized automatic beam selection. It is not a status logging system or a diagnostic system. The modem and the controller are free to implement independent monitor and control via proprietary techniques or via open standards such as SNMP or syslog.

There is no explicit provision in OpenAMIP for security or validation. The controller and the modem may choose to use any of several security measures at lower protocol layers.

A message consists of one or more space-separated variable-length fields. The command is terminated by a newline <lf> character or by the <cr><lf> sequence. The first field is a message type. Each type of message requires a specific number of parameters. The last parameter may optionally be separated from the newline by a comment that begins with a #. The # may be followed by a string containing any characters other than a newline.

4.3 REQUIREMENTS AND EXAMPLES This section is explanatory, not "normative." It is intended to describe the purpose of each message. The formal syntax and semantics are described in later sections. Note that the messages here make use of the "comment" syntax. It is unlikely that operational implementations of the protocol will ever transmit messages with comments, but they are useful in descriptive documents such as this one and in human-generated test scripts. Therefore, implementations of the receive side of the protocol should properly detect and ignore comments.

The modem must be able to convey all of the information needed by the controller to describe a satellite. This must be sufficient for the controller to identify the satellite and to command the controller to find the satellite

S -20.1 1.0 3.5 #S: Satellite longitude. 3 params: all floating point degrees, - is West. "wander" in latitude is 1.0. Pol skew 3.5 P L R #P: polarization. Two parameters. parameters are H, V, L or R for Rx and Tx H 1123.321 0.256 #H: hunt frequency: 2 parameters: floating point center frequency and bandwidth in Mhz B 10750.0 #B: downconversion offset: floating point in Mhz. X nid=1234 #X: unformatted string used by the antenna controller. F #F: Find. Use the recent S, P, R, and H parameters The modem expects to receive "keepalive" messages. This is a simple mechanism to ensure that communications connectivity with the controller has not been lost. A 10 # A: Alive: one parameter N. antenna should resend status every N seconds.

The modem must be able to inform the controller when the modem has detected the downstream carrier:

L 1 # Modem lock status: one parameter, 1 is locked, 0 is unlocked.


No. E0001657

Rev. 4.4

Sheet 17 of 27

iDirect

The controller must be able to tell the modem its status: When it is locked onto the satellite:, when it is functional, and when it is unblocked:

s 1 1 # s: two parameters: Functional, OK-to-transmit

The modem must be able to request periodic location information:

W 60 #W: one parameter. Seconds between location updates from controller

The controller must be able to send GPS information to the modem: w 1 -10.123 20.235 123456789 #w: location info. Four parameters: valid, lat, lon, time

The "w" message parameters require more explanation:

valid (1) or invalid (0) latitude in floating point degrees (South is negative) longitude in floating point degrees. (West is negative) GPS time in seconds. If the antenna does not have GPS time, set this to zero.

This is the entire minimal set of functionality required for operation. OpenAMIP also specifies the following message types:

I iDirect 5100 #modem manufacturer and type strings i YoyoDyne 1234 # antenna controller manufacturer and type strings

The controller may send a request for keepalive:

a 60 #a: one parameter: number of seconds between keepalives from the modem

Any antenna or modem manufacturer can extend the protocol by creating an extended type field. The extended type field consists of the manufacturer's name (with no spaces) followed by a colon, followed by a type (with no spaces). If a modem receives a message of unknown type, the modem shall ignore the message. If an antenna controller receives a message of unknown type, the controller will ignore the message. If the messages are optional for operation of the equipment, then the protocol still qualifies as "unmodified" OpenAMIP. If the messages must be used for a particular antenna or modem, then the resulting implementation must be called "modified OpenAMIP."

Examples: Yoyodyne:NID 1132 # additional search parameter iDirect:stow 1 # command specified by idirect

There is also a requirement that newer versions of the protocol be backward-compatible with older versions. We handle this by requiring that the meanings of parameters never change from version to version . New parameters may be added to a message, and new messages may be added. The receiver is required to ignore extra parameters and unknown messages: this allows an older receiver version to work with a newer sender. We also require the receiver to operate properly when it receives a message that does not have enough parameters: this allows a newer receiver version to work with an older sender. Of course, the older version will not in general implement functionality that requires the newer version, but the older version will continue to provide the functionality of the older version when operating with a partner that is using a newer version.

4.4 HARDWARE COMPATIBILITY ISSUES OpenAMIP is intended for a typical installation whereby a specific modem and a specific antenna are installed and configured to work together. The protocol does not make specific provision for


No. E0001657

Rev. 4.4

Sheet 18 of 27

iDirect

auto-discovery or parameter negotiation, since these are installation issues and the protocol is oriented solely toward operations. It is the responsibility of the installer to assure that the parameters are actually compatible. We take this approach because essentially all incompatibilities will cause loss of service and the need for human intervention anyway, so the elaborate mechanisms needed for auto-negotiation have no practical benefit. The obvious examples of incompatibilities occur in the P,H, and B commands. Clearly, an antenna that is mechanically configured for LHCP and that has no pol switch hardware will not operate correctly for RHCP or linear polarization. Similarly, an antenna with a mechanical polarizer will not be able to select Tx pol independently from Rx pol. Similarly, an antenna whose downconversion offset frequency ("LNB local oscillator") is fixed cannot implement an R command to change to another frequency, and more generally an antenna with a selectable downconversion frequency can only change to one of a small set of downconversion frequencies. Finally, an antenna whose tracking receiver has a specific set of (one or more) bandwidths cannot select an arbitrary hunt bandwidth. It is the responsibility of the installer to ensure that the modem does not send parameters that the antenna does not support. For the hunt bandwidth, the antenna MAY choose to operate with a different hunt bandwidth. For other unsupported P, B, and H parameters, the antenna should not attempt to operate. When the antenna does not have a controllable downconversion frequency, the antenna MAY choose to ignore the R command. The modem MAY choose to not send the B command.

4.5 SEMANTICS The OpenAMIP protocol is a peer protocol: Neither side is the master. The protocol is primarily intended to convey state change information based on external events. In particular, to comply with certain regulatory constraints, the modem must disable its transmitter within 100ms when the antenna loses lock on a satellite, and must also disable the transmitter immediately when a blockage occurs. Therefore, the antenna should minimize the interval between detecting a change in condition and sending the status message to the modem. Similarly, the antenna may choose to use the modem lock signal as part of its satellite search. Therefore, the modem should minimize the interval between detecting the condition and sending the message to the controller. Status changes "should" be reported within 10ms. This will not be practical on a slow serial link: such links are therefore deprecated.

Prior to any communication between the modem and the controller, the OpenAMIP state is unspecified. The timers are all set to "infinite." The modem initiates communications by sending the commands needed to deliver the satellite parameters to the controller. It then sends an "F" message.

When the controller receives an "F" message, it MUST respond immediately with an "s" message. The controller should also send a status every "keepalive" interval, and every time the status changes. When the controller responds to an "F" message, the "may transmit" status MUST reflect the status with respect to the newly-selected satellite parameters. This means that if the modem has just commanded the antenna to "Find" the satellite that it is already tracking and is already locked on, then the immediate status can be "may transmit" However, if the antenna is already tracking a satellite and is successfully locked to it, and the modem then sends new parameters and issues a new "Find" command, the controller MUST immediately send a status of "must not transmit" because it is not locked to the new satellite (it's locked to the old satellite.) After the antenna locks to the new satellite, it will send a new status message indicating that the modem may transmit. The modem should send a (L 0) or (L 1) whenever the modem lock changes. It should also


No. E0001657

Rev. 4.4

Sheet 19 of 27

iDirect

send the "locked" status every time its keepalive timer expires. Whenever the modem sends the L message for any reason, it restarts its keepalive timer.

When the modem issues a W the controller immediately responds with a w. The controller responds thereafter every w seconds (zero seconds means never.) If the controller sends a w to the modem that indicates that the location information is invalid, then the controller should send a new w message immediately when valid location information becomes available.

Latitude and longitude are reported in floating point decimal degrees. The range for latitude is -90.0 to 90.0, where -90.0 is the south pole. The range for longitude is -360.0 to 360.0, where negative is west from the prime meridian and positive is east from the prime meridian. The overlap is intentional: the sender is free to use zero to 360 or -180 to 180 (or even -360 to 0 or a mixed system.) The receiver must be able to handle the full -360 to 360. Leading zeros are optional for the sender, except that the number must have at least one digit before the decimal point. Trailing zeros are optional for the sender, except that the number must have at least one digit after the decimal. The receiver must be able to handle leading and trailing zeros correctly. If the fractional part is zero, the number may be specified as a integer (i.e., without a decimal point.) Note that the syntax does not permit the use of the '+' character.

The precision of the latitude and longitude is not specified by the OpenAMIP syntax: The number of digits after the decimal point is arbitrary. However, The sender should provide as much precision as is actually available. As a practical matter, OpenAMIP contemplates the ability to use this information for logging and transmission restrictions as mandated by regulatory authorities, so accuracy to about one kilometer is needed: This implies that latitudes and longitudes to a precision of thousandths of a degree are needed.

If the modem issues a 'P, B, or F' command that is incompatible with the antenna hardware, the Antenna may either ignore the incompatible parts of the command or may set the "functional" status to "not functional."

The "K" message conveys the maximum skew of the short axis of a non-circular beam to the geosynchronous arc. If the antenna has a beam shape that is radially symmetric about the bore sight, this parameter may be ignored. Otherwise, the antenna must use the current skew as a factor in computing the "must not transmit" or "may transmit" status. Thus, when all other factors permit transmission, the antenna will immediately send a status message with a status of "must not transmit" when the angle transitions from below to above the maximum skew, and will immediately send a status message with a status of "may transmit" when the angle transitions from above to below the maximum skew. In contrast to some other messages, the "K" message takes effect immediately and the modem may send a new K message with a new max skew angle at any time.

The "functional" status from the antenna indicates that the antenna should currently be working. By contrast, "non-functional" means that the antenna should not currently be expected to be in service. This does not include blockage. loss of lock, system initialization, loss of heading information, cable unwrap or any condition that can correct itself without intervention. It does include detection of a fatal mechanical failure, or an operator command to the antenna controller from its front panel or other source, or an illegal configuration.

When the modem sees this status, it "knows" that there is no reason to attempt to recover by e.g. switching to a different satellite or clearing and re-establishing the OpenAMIP connection. The modem will simply wait until the antenna declares itself to be


No. E0001657

Rev. 4.4

Sheet 20 of 27

iDirect

"functional." The antenna asserts "may transmit" when it is locked on the satellite and there is no known reason that the modem should not transmit. The antenna signals "must not transmit" if there is any reason the modem should not transmit: blockage, loss of lock, cable unwrap, sea too rough, etc.

4.6 OPENAMIP VERSION COMPATIBILITY New versions of the OpenAMIP protocol may be published from time to time. New versions shall be strict supersets of older versions and may extend the protocol in only two ways:

• A new version may add new message types • A new version may add new parameters to the end of an existing message type

No other syntactic extensions are acceptable. Any extension to the semantics of the protocol must not affect the semantics of earlier versions. The intent of this specification is that any older implementation of the protocol can interoperate with any newer implementation without loss of any of the older functionality. Therefore, a compliant implementation of OpenAMIP MUST ignore any unexpected message type that it receives, and MUST ignore any unexpected parameters at the end of a message. Furthemore, a compliant implementation MUST operate successfully if it receives a message with too few parameters. Parameters that are added to the protocol in version 1.5 or later will have default values that the receiver shall use if a message does not provide the parameter.

4.7 FORMAL SYNTAX The OpenAMIP format is specified here in BNF (Backus–Naur form).

An abstract message: <msg>::=<msg_body><optional whitespace>'\n' | <msg_body><optional whitespace>'#'<comment_body>'\n' <comment_body>::=<non-newline> |<non-newline><comment_body> <non_newline>::= {any printable character except '\n'} <msg_body>::=<msg_type> | <msg_type> <param_list> <param_list>::= <whitespace> <param> | <param><param_list> <param>::= <binary> |<float> |<int> |<string> <binary>::= '1' |'0' <int>::= '-' <natural> | <natural> <float::=<int>'.'<natural> | <int> <natural>::= <digit> | <digit><natural> <digit::= '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9' <string> ::=<string_char> |<string_char><string> <string_char>::={any printable character except ' ' and '\n'}

http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form


No. E0001657

Rev. 4.4

Sheet 21 of 27

iDirect

<optional whitespace>::=NULL|<whitespace> <whitespace>::=<whitespace_char>|<whitespace><whitespace_char> <whitespace_char>::= ' '|'\t'|\'r'

4.7.1 Specific Messages Sender Type #

parms Parameters Semantics

M A 1 int seconds Keepalive time. Antenna should send a status message at least this often.

M B 2 float RX lo frequency float TX lo frequency

"Local oscillator" RX down-conversion frequency in Mhz. "Local oscillator" TX up-conversion frequency in Mhz.

M E 1 float max power Maximum L-band TX power to be expected at the Antenna, in dBm.

M F 0 Find the satellite. Antenna should now begin using the satellite specified by S, P, B,X,and H. This command overrides the N command.

M H 1 float frequency float bw

Hunt frequency in MHz. Modem expects antenna to use this hunt center frequency when commanded hunt bandwidth in Mhz. Modem expects antenna to use this bandwidth for hunting when commanded.

M I 2 string: modem manufacturer string: modem model

Optional

M K 1 float degrees Max skew of the beam short axis to the geosynchronous arc.

M L 2 binary 1 (locked) or 0 (unlocked) binary 1 (tx on) or 0 (tx off)

Modem is locked to downstream, or not. The modem should send this message immediately when the status changes. The modem should send this message periodically at intervals specified by the antenna in the 'a' message. Modem is free to transmit, or not. This signal may be used by the antenna to remove power from the TX amplifiers.


No. E0001657

Rev. 4.4

Sheet 22 of 27

iDirect

Sender Type # parms

Parameters Semantics

M N 0 When receiving this command, antenna should attempt to point more than 5 degrees away from the geosynchronous arc. This overrides the F command, but should not cause the antenna to lose the parameters previously specified by S, P, B, X and H.

M P 2 char L, R, V, or H char L,R,V, or H

Modem expects antenna to use this Rx pol when commanded. Modem expects antenna to use this Tx pol when commanded.

M S 3 float longitude (deg) float latitude variance float pol skew

Satellite longitude. Modem expects Antenna to use this satellite when commanded. Maximum excursion in satellite's latitude (for inclined-orbit satellites) satellite's nominal polarization offset in degrees (for skewed satellites).

M T 2 float TX freq float TX bw

Modem intends to transmit at this L-Band frequency in Mhz. modem intends to use this range of frequencies in Mhz.

M W 1 int seconds Location time. Antenna should send "w" message immediately, and then repeat at least this often. 0 means "never repeat."

M X 1 string Extra hunt parameters. This is a fixed string to be configured by the operator and sent as part of the lookup. The antenna vendor specifies the string. If the controller does not need this command, the modem dose not need to send it, but the modem may send it anyway, in which case the controller shall ignore it.

A a 1 int seconds. keepalive time Antenna expects to see an 'L' message from the modem at least this often.


No. E0001657

Rev. 4.4

Sheet 23 of 27

iDirect

Sender Type # parms


A c 4 float1, float2, float3, float4

CURRENTLY STEEREDANTENNA POSITION

VIEW IS IN LOOK DIRECTION OF ANTENNA SYSTEM

+VE AZIMUTH EXCURSION

(float3)

-VE AZIMUTH EXCURSION

(float1)

-VE ELEVATION EXCURSION

(float4)

+VE ELEVATION EXCURSION

(float2)

Optional Sent when conical scan performed. The four floating point values represent the times (UTC or GPS epochal) of beam steering excursions from the previously steered coordinates. Azimuth and elevation delta scan excursions are pre-determined by the antenna manufacturer and would be on the order of ±0.25°.

NEW

A i 2 string: manufacturer string: model

Optional

A r 2 int frequency MHz string R, T, or B e.g. “r 10 B”

Reference frequency required for BUC and LNB. Frequency is in MHz. String variable is Ref on Rx (R), Tx (T) or both (B)

NEW


No. E0001657

Rev. 4.4

Sheet 24 of 27

iDirect

Sender Type # parms


A s 4 binary (1 or 0) antenna (is, is not) functional binary(1 or 0) modem (may, must not) transmit int search_count binary (1 or 0) antenna (has, has not) successfully pointed away from the geosynchronous arc

Antenna sends this immediately in response to the "F" command from the modem. Antenna sends this immediately whenever either of the two statuses changes. Antenna sends this periodically. The period is set by the A command from the modem. "Not functional" means that the antenna cannot currently operate and will never operate with this configuration. This can be temporary (e.g., an illegal configuration) or permanent (e.g. motor frozen) "modem must not transmit" means that the antenna has detected a condition (loss of lock, blockage, cable unwrap, max skew exceeded) that does not require a reconfiguration, but that does require the modem to cease transmission. The third parameter is the number of full sweeps the antenna has performed while searching for the satellite. It should be set to 0 upon receipt of an F command, and incremented when the antenna has performed a full sweep for the satellite. If omitted, this parameter is assumed to be 0. This parameter should be zero if an N command is more recent than an F command. The fourth parameter should be set to 0 if an F command was sent more recently than a N command. If omitted, this parameter is assumed to be 0. Note that there may be circumstances in which the antenna cannot ensure it is pointed away from the geosynchronous arc, due to a lack of bearing information. In this case, the third parameter should be set to 0.


No. E0001657

Rev. 4.4

Sheet 25 of 27

iDirect

Sender Type # parms


A w 5 binary (1 or 0) location (is,is not) valid. float latitude (degrees) negative is south float longitude (degrees) negative is west of prime meridian int time (GPS seconds) time in seconds since the GPS epoch float altitude (meters) floating point value for heading referenced to true north (degrees) floating point value for GPS computed speed m/s floating point value for pitch (degrees ) Positive is up, negative is down floating point value for roll angle (degrees) Positive is rolled to starboard, negative is rolled to port floating point value for yaw angle (degrees) Positive is inclined to starboard, negative is inclined to port

Antenna sends this to modem periodically. The period is set by the W command from the modem. If the location is not valid, the antenna may put 0 in the last three parameters. If the antenna does not know the time, the last parameter should be 0. the precision of the floating point numbers should reflect the precision of the location information. For example, we expect about 3 digits after the decimal point if the source is GPS. The antenna should send a "w" immediately if its internal GPS status changes from "invalid" to "valid". If the altitude parameter is not set, it is assumed to be zero.

4.8 SIMULATION AND VALIDATION You may validate your semantics by executing a script that emulates a controller or a modem. The scripts are written in POSIX-compliant C, and are available on request from iDirect.

4.9 TCP INTERFACE A modem and controller may communicate via TCP. Either party may call the other. The method of discovering the IP address and TCP port is outside the scope of OpenAMIP. In the reference implementation, The Antenna listens on a configured TCP port and accepts calls from a configured (range of) modem IP addresses. The modem initiates a TCP connection to a configured antenna IP address and TCP port.

Whenever the TCP connection is disconnected, the antenna sets its keepalive and GPS time to infinity. When a new TCP connection is established, the antenna will send one keepalive to the modem, and the modem will send one keepalive to the antenna. The disconnect timer will be set to 15 seconds on each side. If the disconnect timer expires, the


No. E0001657

Rev. 4.4

Sheet 26 of 27

iDirect

TCP connection will be disconnected. The disconnect timer will be set to 15 seconds whenever a keepalive message is received.

Neither the antenna nor the modem is obliged to accept more than one TCP connection at a time, but this is not prohibited. In a system with two modems, one may be acting as a backup. In this arrangement, the antenna should only honor satellite selection requests from one modem. (TBD)

TCP is a "stream-oriented" protocol: there is no particular mapping of an OpenAMIP message into an IP packet. A single packet may contain a fragment of a message, a complete message, or multiple messages. In the reference implementation, The modem sends an entire initial set of seven messages in a single POSIX "write" command immediately after opening the connection. On most POSIX systems, this will result in a single TCP/IP packet. The reference receiver implementation accumulates characters until a newline is found and then processes the result as an OpenAMIP message. Accumulation of the next message starts with the first character after the newline.

4.10 UDP INTERFACE Each message fits in a single UDP packet. A packet may contain more than one message, but any given message must be fully contained within one packet. The antenna has a configured IP address and well-known port, as does the modem. The initial state of the OpenAMIP interface is "idle" (i.e., no keepalive) until the partner sends a keepalive timer. The interface reverts to the "idle" state if three keepalives are missed.

4.11 ASYNCHRONOUS SERIAL INTERFACE This is beyond the scope of OpenAMIP. However, SLIP can be used to establish an IP connection on the serial link. Alternatively, Any packet-over-serial technique may be used. (Note that a checksum should be used here.)

4.12 REFERENCE IMPLEMENTATIONS iDirect provides reference implementations in C. We make no representations that these are actually suitable for use in a product.

4.13 TEST SUITE Code for the test suite was developed from the reference implementation. It is available from iDirect.

4.14 SOFTWARE AVAILABILITY The source code for the reference implementations and the test suite is copyrighted by iDirect but are licensed at no cost for use for any purpose.

4.15 MODEM MODULE REFERENCE DESIGN The modem implements the protocol as follows: The modem reads the antenna's IP address and TCP port number from a config file. the modem attempts to connect to the antenna via TCP: If the connection fails, the modem attempts to re-establish it. Whenever the modem succeeds in connecting to the antenna, it sends a set of setup commands. These commands are sent "back-to-back" with no intervening commands and without waiting for responses: the commands are S, H, P,B, X, A, F, W and L. We then wait for messages from the antenna. We send an L whenever our lock state changes. If we receive an "a", we will also send an L periodically. We react internally to received "s" and "w" messages, which we expect to see periodically based on our "A" and "W" timers. If we fail to


No. E0001657

Rev. 4.4

Sheet 27 of 27

iDirect

see an "s" or a "w" when we expect it, we clear the TCP connection and attempt to re-establish it, and the cycle repeats.

If we decide to switch to a different satellite, we send the setup sequence again.

Documents

OpenAMIP v1_7_ICD_E0001657 - General Edition v4_4a