You are on page 1of 27

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 No. E0001657


A

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

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

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

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

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

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

iDirect
Copyright 2012, iDirect

Figure 1: OpenAMIP System Overview

Remote Terminal
Modem Position System
(GPS, gyro,
ARINC 429)

Location
OpenAMIP Data

Antenna Control System (ACS)

Automatic Beam Switching, Antenna Commands


Position, etc. Antenna Status

Earth Station Antenna


Automatic Beam Switching,
Position, etc.

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 Antenna Controller

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

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

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

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 Version 1.7 STATUS:


iDirect 2011-9-20 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 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 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 # 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 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
Sender Type # Parameters Semantics
parms
M A 1 int seconds Keepalive time. Antenna should send
a status message at least this often.

M B 2 float RX lo frequency "Local oscillator" RX down-


float TX lo frequency 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 Hunt frequency in MHz. Modem
float bw 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 Optional
string: modem model
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) Modem is locked to downstream, or
binary 1 (tx on) or 0 (tx off) 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 21 of 27

iDirect
Copyright 2012, iDirect

Sender Type # Parameters Semantics


parms
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 Modem expects antenna to use this
char L,R,V, or H Rx pol when commanded.
Modem expects antenna to use this
Tx pol when commanded.
M S 3 float longitude (deg) Satellite longitude. Modem expects
float latitude variance Antenna to use this satellite when
float pol skew 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 Modem intends to transmit at this L-
float TX bw 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 22 of 27

iDirect
Copyright 2012, iDirect

Sender Type # Parameters Semantics


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

NEW

A i 2 string: manufacturer Optional


string: model
A r 2 int frequency MHz Reference frequency required for
string R, T, or B BUC and LNB. Frequency is in MHz.
String variable is Ref on Rx (R), Tx
e.g. r 10 B (T) or both (B)

NEW

No. E0001657
Rev.
4.4 Sheet 23 of 27

iDirect
Copyright 2012, iDirect

Sender Type # Parameters Semantics


parms
A s 4 binary (1 or 0) antenna (is, is Antenna sends this immediately in
not) functional response to the "F" command from
binary(1 or 0) modem (may, must not) the modem.
transmit Antenna sends this immediately
int search_count whenever either of the two statuses
binary (1 or 0) antenna (has, has not) changes.
successfully pointed away from the Antenna sends this periodically. The
geosynchronous arc 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 # Parameters Semantics


parms
A w 5 binary (1 or 0) location (is,is not) valid. Antenna sends this to modem
periodically. The period is set by the
float latitude (degrees) negative is W command from the modem.
south If the location is not valid, the
antenna may put 0 in the last three
float longitude (degrees) negative is parameters. If the antenna does not
west of prime meridian know the time, the last parameter
should be 0. the precision of the
int time (GPS seconds) time in seconds floating point numbers should reflect
since the GPS epoch the precision of the location
information. For example, we
float altitude (meters) expect about 3 digits after the
decimal point if the source is GPS.
floating point value for heading The antenna should send a "w"
referenced to true north (degrees) immediately if its internal GPS status
changes from "invalid" to "valid".
floating point value for GPS computed If the altitude parameter is not set, it
speed m/s is assumed to be zero.

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

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 re-
establish 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