Date Nov 6, 11 Nov. 30, 11 Dec. 1, 11 Jan. 31, 12 Feb.

10, 12 May 4, 2012

Rev 1 4 4.1 4.2 4.3 4.4

Revision Record Initial Release Post-CDR Ready Updates Updates Update H command Prepare for Web

Approved

Approvals
SW Engineering Approval: iDirect Supply Chain Approval: Manufacturer #1 Approval: Manufacturer #2 Approval:

Date

Specification: OpenAMIP V1.7 ICD

Sheet 1 of 27

SIZE A

No.

E0001657

iDirect

Copyright 2012, iDirect

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

No. E0001657 Rev. 4.4

Sheet 2 of 27

iDirect

Copyright 2012, 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 3 of 27

iDirect

Copyright 2012, 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 4 of 27

iDirect

Copyright 2012, iDirect

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

Sign Off Sheet

Name Hai Tang Ratima Kataria Title VP, Advanced Development - iDirect Director, Program Management Office - iDirect Date 10-Feb-2012 10-Feb-2012 Signature Hai Tang Ratima Kataria

No. E0001657 Rev. 4.4

Sheet 5 of 27

iDirect

Copyright 2012, iDirect

1.0 1.1

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

Sheet 6 of 27

iDirect

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

Sheet 7 of 27

iDirect

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

No. E0001657 Rev. 4.4

Sheet 8 of 27

iDirect

Copyright 2012, iDirect

2.0 2.1

GENERAL NOTICE 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 9 of 27

iDirect

Copyright 2012, iDirect

3.0
3.1

OPENAMIP INTERFACE
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 10 of 27

iDirect

Copyright 2012, iDirect

Figure 1: OpenAMIP System Overview Remote Terminal Modem Position System (GPS, gyro, ARINC 429)
Location Data

OpenAMIP

Antenna Control System (ACS)

Automatic Beam Switching, Position, etc.

Antenna Commands Antenna Status

Earth Station

Automatic Beam Switching, Position, etc.

Antenna

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

No. E0001657 Rev. 4.4

Sheet 11 of 27

iDirect

Copyright 2012, iDirect

Figure 2: Sample Communication between Modem & ACS using OpenAMIP

Modem
Startup Set up TCP session 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 s1000 Antenna finds satellite, locks to acquisition channel s1100 L10 L11 Antenna finds correct outbound H 29751.2 26.6 Fi s1100 L10 L11 (Terminal in normal operation) Modem switches to another downstream (Beam Switch) H 29850.1 26.6 Fi s1100 (Terminal in normal operation) Modem Decides to Switch Satellites H 29800 26.6 S -20.1 0.5 0 (satellite longitude) Fi s1000 Antenna finds satellite s1100 L10 L11

Antenna Controller

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 12 of 27

iDirect

Copyright 2012, 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 rftermtype Format int Comment 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 Antenna Controller vendor identifier iDirect shall assign the Vendor identifier so that the Terminal can be integrated into the iDirect NMS.

acuvendor

string

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
Modem Decides to Initiate BUC Power Calibration N Antenna points away from GEO arc s1001 Modem runs power calibration Fi s1000 Antenna finds satellite s1100

ACS

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 13 of 27

iDirect

Copyright 2012, iDirect

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

No. E0001657 Rev. 4.4

Sheet 14 of 27

iDirect

Copyright 2012, 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 implementers published finding of noncompliance 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 15 of 27

iDirect

Copyright 2012, 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 PLR #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 16 of 27

iDirect

Copyright 2012, 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: s11 W 60 # s: two parameters: Functional, OK-to-transmit #W: one parameter. Seconds between location updates from controller The modem must be able to request periodic location information: 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 17 of 27

iDirect

Copyright 2012, 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 18 of 27

iDirect

Copyright 2012, 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 19 of 27

iDirect

Copyright 2012, 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 (BackusNaur 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'}
No. E0001657 Rev. 4.4

Sheet 20 of 27

iDirect

Copyright 2012, iDirect

<optional whitespace>::=NULL|<whitespace> <whitespace>::=<whitespace_char>|<whitespace><whitespace_char> <whitespace_char>::= ' '|'\t'|\'r' 4.7.1 Specific Messages # Parameters parms 1 int seconds Semantics Keepalive time. Antenna should send a status message at least this often. "Local oscillator" RX downconversion frequency in Mhz. "Local oscillator" TX up-conversion frequency in Mhz. Maximum L-band TX power to be expected at the Antenna, in dBm. Find the satellite. Antenna should now begin using the satellite specified by S, P, B,X,and H. This command overrides the N command. 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. Optional Max skew of the beam short axis to the geosynchronous arc. 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. Sender Type M A

float RX lo frequency float TX lo frequency

M M

E F

1 0

float max power

M M M

I K L

2 1 2

string: modem manufacturer string: modem model float degrees binary 1 (locked) or 0 (unlocked) binary 1 (tx on) or 0 (tx off)

No. E0001657 Rev. 4.4

Sheet 21 of 27

iDirect

Copyright 2012, iDirect

Sender Type M N

# Parameters parms 0

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

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. 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). Modem intends to transmit at this LBand frequency in Mhz. modem intends to use this range of frequencies in Mhz. Location time. Antenna should send "w" message immediately, and then repeat at least this often. 0 means "never repeat." 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. Antenna expects to see an 'L' message from the modem at least this often.

float longitude (deg) float latitude variance float pol skew

float TX freq float TX bw

int seconds

string

int seconds. keepalive time

No. E0001657 Rev. 4.4

Sheet 22 of 27

iDirect

Copyright 2012, iDirect

Sender Type A c

# Parameters parms 4 float1, float2, float3, float4

Semantics

Optional Sent when conical scan performed. The four floating point values +VE ELEVATION represent the times (UTC or GPS EXCURSION (float2) epochal) of beam steering excursions -VE AZIMUTH +VE AZIMUTH EXCURSION from the previously steered EXCURSION (float1) (float3) coordinates. CURRENTLY STEERED -VE ELEVATION Azimuth and elevation delta scan ANTENNA POSITION EXCURSION excursions are pre-determined by the (float4) antenna manufacturer and would be VIEW IS IN LOOK DIRECTION OF ANTENNA SYSTEM on the order of 0.25.
NEW

A A

i r

2 2

string: manufacturer string: model int frequency MHz string R, T, or B e.g. r 10 B

Optional 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 23 of 27

iDirect

Copyright 2012, iDirect

Sender Type A s

# Parameters parms 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

Semantics 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 24 of 27

iDirect

Copyright 2012, iDirect

Sender Type A w

# Parameters parms 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

Semantics 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 25 of 27

iDirect

Copyright 2012, 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 26 of 27

iDirect

Copyright 2012, iDirect

see an "s" or a "w" when we expect it, we clear the TCP connection and attempt to reestablish it, and the cycle repeats. If we decide to switch to a different satellite, we send the setup sequence again.

No. E0001657 Rev. 4.4

Sheet 27 of 27

iDirect