Open Antenna-Modem Interface Protocol (AMIP) Implementation

Technical Note

January 13, 2014

Copyright © 2014 VT iDirect, Inc. All rights reserved. Reproduction in whole or in part without permission is
prohibited. Information contained herein is subject to change without notice. The specifications and information
regarding the products in this document are subject to change without notice. All statements, information, and
recommendations in this document are believed to be accurate, but are presented without warranty of any kind,
express, or implied. Users must take full responsibility for their application of any products. Trademarks, brand
names and products mentioned in this document are the property of their respective owners. All such references
are used strictly in an editorial fashion with no intent to convey any affiliation with the name or the product's
rightful owner.

Document Name: TN_OpenAMIP_Implementation_RevD_01132014.pdf

Document Part Number: T0000223

ii Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 Revision History

The following table shows all revisions for this document. To determine if this is the latest
revision, check the TAC Web site at http://tac.idirect.net.

Revision Date Released Reason for Change(s) Who Updated?

A July 31, 2009 First release of document. EHoffman
B November 16, 2009 Added configuration information EHoffman/SWasser
for iBuilder and OpenAMIP
message mapping.
C July 21, 2010 Added legal language. EHoffman/SWasser
D January 13, 2014 Removed incorrect statement JVespoli
that K command must be followed
by an F command.

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note iii

iv Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note
 Contents

Contents

About This Guide

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Contents Of This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

1 Implementation
1.1 OpenAMIP Message to Option File Key Mapping . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Sample Options File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 iBuilder Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Appendix A. OpenAMIP Specification (Version 1.6) . . . . . . . . . . . 9

A.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
A.1.1 What Is OpenAMIP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
A.1.2 OpenAMIP Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
A.1.3 Legal Matters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
A.1.4 Certification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
A.2 OpenAMIP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
A.2.1 Standard Message Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Satellite Description Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Modem & Controller Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
A.2.2 Additional Message Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Equipment Identification Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Modem Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Controller Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note v

 Keepalive Timing Interval Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Extended Type Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
A.2.3 Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
A.3 Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
A.3.1 Communication Between Modem and Controller . . . . . . . . . . . . . . . . . . . . . . . . 16
A.3.2 Latitude & Longitude Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
A.3.3 Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
K Message Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Antenna Functional Status Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
A.3.4 Simulation and Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
A.4 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
A.4.1 Abstract Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
A.4.2 Specific Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
A.4.3 OpenAMIP Version Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
A.5 Transport Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
A.5.1 TCP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
A.5.2 UDP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
A.5.3 Asynchronous Serial Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
A.6 Design References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
A.6.1 Reference Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
A.6.2 Test Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
A.6.3 Software Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

vi Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 About This Guide

Purpose
This Technical Note describes the implemenation of the Open Antenna-Modem Interface
Protocol (OpenAMIP) on iDirect systems. Appendix A contains the OpenAMIP specification.

Intended Audience
This Technical Note is intended for network designers, system architects and antenna
manufacturers interested in integrating the OpenAMIP interface with iDirect systems. This
document can also be used by iDirect operators implementing OpenAMIP on iDirect networks.

Contents Of This Guide

This document contains the following chapters and appendixes:
• Implementation
• OpenAMIP Specification (Version 1.6)

Getting Help
The iDirect Technical Assistance Center (TAC) is available 24 hours a day, 365 days a year.
Software user guides, installation procedures, a FAQ page, and other documentation that
supports our products are available on the TAC Web site. Access the TAC Web site at
http://tac.idirect.net.
Additional ways to reach the TAC are:
Telephone: (703) 648-8151
E-mail: [email protected]
To purchase iDirect products, contact iDirect Corporate Sales by telephone or email.
Telephone: (703) 648-8000
E-mail: [email protected]
iDirect strives to produce documentation that is technically accurate, easy to use, and helpful
to our customers. Feedback is welcomed. Send comments to [email protected].

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note vii

Getting Help

viii Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

1 Implementation

OpenAMIP is defined by enumerating a set of messages along with a number of accompanying

parameters for each message. This chapter discusses how the OpenAMIP interface is
implemented on iDirect systems.
The iDirect OpenAMIP implementation varies depending on the iDirect iDS/iDX software
version that you are configuring to use this protocol. See the iBuilder User Guide for the
iDS/iDX version you are using. Also see the Technical Reference Guide for more information on
OpenAMIP and Automatic Beam Switching (ABS) within iDirect systems.

Note: Please see Appendix A for a published presentation of the latest OpenAMIP
interface specification.
Depending on the iDirect software release, OpenAMIP message parameters are configured
using two methods:
• iDS 8.3.1
Manually enter specific OpenAMIP keys into the iBuilder Custom tab for each component
you are configuring. Upon applying changes, the key values are inserted as OpenAMIP
parameters into the Options files for the various iDirect components being configured.
• iDX 2.0.x and iDX 1.1
Configure OpenAMIP parameters by setting fields in the iBuilder VSAT tab for each
component being configured. Upon applying changes, the field values are inserted as
OpenAMIP parameters into the Options files for the various iDirect components being
configured.

Note: Regarding quad-band LNB implementations: Since the OpenAMIP specifies LNB
LO frequency per beam, there is no need within the protocol to specify a
combination of voltage/tone indication such as antenna controllers sometimes
require for multi-band operation. It is up to the antenna controller vendor to
take the LNB information and use it to set the LNB LO frequency as required.

1.1 OpenAMIP Message to Option File Key Mapping

Within iDirect systems, the OpenAMIP message values are defined as keys in the Options file
for the remote. Table 1 defines how the OpenAMIP messages parameter values are mapped to
their respective Options file keys. Please see Table A-2 on page 19 for more detailed
definitions of messages.

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 1

OpenAMIP Message to Option File Key Mapping

Table 1. OpenAMIP Message Command to Options File Key Mapping

Messages Sent Messages Sent
from Remote from Antenna

iDS/iDX # Para- Options File # Para-

Release Message meters Mapped to Options File Keys Group Message meters
iDX 2.0.x A keepalive_interval [ANTENNA] a
Default value of 15 seconds. Will
not appear in Options file unless
overwritten.
B 2 rx_lcl_osc, tx_lcl_osc [SATELLITE]
H 2 hunt_frequency, [SATELLITE]
hunt_bandwidth
K 1 max_skew [SATELLITE]
Maximum skew of the beam
short axis to the geosynchronous
arc.
P 2 polarity, tx_polarity [SATELLITE]
S 3 longitude, max_lat, [SATELLITE] s 2
pol_skew
T 2 tx_frequency, [SATELLITE]
tx_bandwidth
W 1 latlong_interval [MOBILE] w 4
Message contains single value in
seconds. Does not generate
Options file key.
X extras [SATELLITE]
Optional message conveying
configured string containing
"extras." Can only be set as
Custom key.
iDS 8.3.1 A keepalive_interval [ANTENNA] a
& iDX 1.1 Default value of 15 seconds. Will
not appear in Options file unless
overwritten.
H 1 hunt_frequency [SATELLITE]
P 1 polarity [SATELLITE]
S 1 longitude [SATELLITE] s 2
W latlong_interval [MOBILE] w 4
Message contains single value in
seconds. Does not generate
Options file key.
NOTE: The following messages are not reflected by keys in the Options file (or by fields in the iBuilder configuration tabs:
— The F message is an empty message (without parameters).
— The L message represents real time status only.
— The E and I messages are in the specification but not implemented.

2 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 Sample Options File

Note: In iDX 2.0.x and iDX 1.1, the keys as they appear in the Options file are for
reference only since they are configured in iBuilder.
The OpenAMIP interface is designed to be forward and backward compatible. This means that
any subset of OpenAMIP messages and parameters from the specification can be used to
implement the interface, with the meanings for the same message values in different
implementations always remaining the same.
For example, the S message as defined in iDS 8.3.x system contains one parameter
(longitude) only. The definition of the S message longitude parameter is the same in the
OpenAMIP 1.6 specification. The additional two parameters for the S message (as defined in
OpenAMIP 1.6) are simply ignored when using this message in iDS 8.3.x.
See Section A.2, OpenAMIP Messages for further information.

1.2 Sample Options File

This section presents a portion of a sample iDX 2.0.x Options file with OpenAMIP messages and
parameters defined. OpenAMIP keys appear highlighted in blue.
[OPTIONS_FILE]
product_mode = idirect_scpc
modem_sn = 40170
generated_by = NMS-10.0.0
did = 12885226
modem_type = Remote
modem_hardware = 8350
is_mesh = 0
disable_options_flash_command = 0
carrier_type = 0

...

[MOBILE]
is_mobile = 1
tx_handshake_enabled = 0
gps_input = 2
latlong_interval = 300
latlong_fail_interval = 10
init_tx_power_offset = 0.000000
[MAPSERVER_0]
hostname = 172.20.130.3
port = 5003
[BEAMS]
beam_21 = PPS_Perf_Eval
maxbeam = 21
[ANTENNA]
manufacturer = OpenAMIP
model = OpenAMIP
addr = 172.26.81.34
port = 5002
connect_timeout = 30

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 3

Sample Options File

dedicated_interface = ixp1
[SATELLITE]
min_look_angle = 0.000000
tx_frequency = 1200.000000
tx_bandwidth = 36.000000
hunt_bandwidth = 36.000000
rx_lcl_osc = 1450.000000
tx_lcl_osc = 1350.000000
max_skew = 90.000000
name = Bench Test Spacecraft (I/F)
channelname = PPS_Perf_Eval
longitude = 0.000000
max_lat = 0.000000
pol_skew = 0.000000
hunt_frequency = 1075.000000
polarity = H
tx_polarity = H
noise_reference_frequency = 0.000000
OpenAMIP keys are defined under the [SATELLITE] group. In the sample Options file, the
tx_frequency and tx_bandwidth keys are defining both OpenAMIP parameter values
(1200.000000 and 36.000000, respectively) for the T message. While the max_skew key is
defining the single parameter value (90.000000) for the K OpenAMIP message.

4 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 iBuilder Configuration

1.3 iBuilder Configuration

This section presents an example of configuring OpenAMIP in the iDX 2.0 iBuilder client
application. iDX 1.1 software also provides some of the same configuration options in iBuilder,
while all versions of iDS/iDX that support OpenAMIP also support the key implementation
described in Section 1.1, OpenAMIP Message to Option File Key Mapping.

Note: As noted in Table 1, some OpenAMIP parameters can only be configured as

custom keys.
To configure remote OpenAMIP parameters in iBuilder:
1. When you configure your remote for OpenAMIP, you must first configure a Reflector in
iBuilder:

Figure 1. Opening Reflector Configuration Window

a. Open the Reflector configuration window as shown in Figure 1.

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 5

iBuilder Configuration

Figure 2. Information Tab for Reflector

b. On the Information tab, first click the Controllable check box (Figure 2).

CAUTION: You must check the Controllable field before you can configure this
component for other OpenAMIP field selections described later in this example.

c. In the Controller type field, select OpenAMIP or another supported controller type.
You can configure your ABS networks for any of the supported controller types or for
use with OpenAMIP.
d. Click OK to save the Reflector configuration.
2. Now configure your remote for OpenAMIP:
a. Select Modify—>Item for the remote you are configuring.
b. Click the VSAT tab in the Modify Configuration Object window (Figure 3).

6 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 iBuilder Configuration

Figure 3. VSAT Tab with OpenAMIP Parameters

c. Select OpenAMIP in the Reflector field.

Selecting OpenAMIP in the Reflector field displays the additional OpenAMIP fields on
the right of the Remote Antenna pane (Figure 3). If selecting another reflector type,
it must also be configured for OpenAMIP. Reflectors for all supported controllable
antennas are pre-defined in the iBuilder database.

Note: The Reflector Mount field is used for reference only. It can be configured
as OpenAMIP Manufacturer.
In Figure 3 the corresponding OpenAMIP messages (and parameter number) defined in
Table 1 are marked in red letters to the left of the corresponding field selections.
3. Additional OpenAMIP parameters are configured on the Spacecraft Information tab as
shown in Figure 4.

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 7

iBuilder Configuration

Figure 4. Spacecraft Information Tab

In Figure 4 the corresponding OpenAMIP messages (and parameter number) defined in

Table 1 are marked in red letters to the left of the corresponding field selections.
4. The K message (max_skew) is configured from the Spacecraft Information tab (Figure 4),
but can be overridden for each remote:
a. Select the Geo Location tab on the Modify Configuration Object window for the
remote (Figure 5).

Figure 5. Geo Location Tab—Overriding Maximum Skew

b. Click the Override button in the Maximum Skew area, and enter a value in degrees.

Note: For stabilized antennas, the GPS location input should be configured for
“Antenna” as indicated in Figure 5.
See the iBuilder User Guide for additional information on the configuration windows
described in this section.

8 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

Appendix A OpenAMIP
Specification (Version 1.6)

This appendix publishes Version 1.6 of the OpenAMIP specification.

• Overview
• OpenAMIP Messages
• Semantics
• Formal Syntax
• Transport Protocols
• Design References

A.1 Overview
This section introduces the OpenAMIP protocol. The protocol is defined and legal and design
issues are discussed.

A.1.1 What Is OpenAMIP?

OpenAMIP is an ASCII message-based protocol, a specification for the interchange of
information between an antenna controller and a satellite modem. It allows the modem to
command the controller to seek a particular satellite and allows the modem and controller to
exchange information necessary to permit the modem to initiate and maintain
communications through the antenna and the satellite.
OpenAMIP is intended to be simple and flexible. Communications are in the form messages of
human-readable ASCII characters. Infrequent message flows, and the fact that messaging is
confined to high-bandwidth LANs (and not satellite links) mitigates the relative inefficiency of
using human-readable text.
The messages may be conveyed using any of several lower-level protocols including:
• HTTP
• TCP/IP over a LAN
• UDP over a LAN
• High-speed serial connection
OpenAMIP is intended only for the purpose of permitting a modem and a controller to perform
synchronized automatic beam selection. It is not a status logging system or a diagnostic

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 9

 system. The modem and the controller are free to implement independent monitoring and
control using proprietary techniques or open standards (such as SNMP or syslog).
There is no explicit provision in this OpenAMIP protocol for security or validation. The
controller and the modem can 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 new line <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 can optionally be separated from the new line character by a
comment that begins with a # character. The # can be followed by a string containing any
characters (other than a new line character).

Note: Implementations of the receive-side of the protocol must be designed to detect

and ignore comments delineated with the # character.

A.1.2 OpenAMIP Design

The modem implements the protocol as described in this section.
Connecting with Antenna
The modem establishes a connection with an antenna as follows:
1. The modem reads the antenna IP address and TCP port number from a configuration file.
2. The modem attempts to connect to the antenna through TCP. If the connection fails, the
modem attempts to re-establish it.
3. 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.
Communicating with Antenna
The modem then waits for messages from the antenna. The modem sends an L message
whenever the lock state changes. If the modem receives an a message, it also sends an L
message periodically. The modem reacts internally to received s and w messages, which it
expects to see periodically based on its A and W timers. If the modem fails to see an s or a w
message when expected, it clears the TCP connection and attempts to re-establish it; and the
cycle repeats.
If the modem decides to switch to a different satellite, it sends the setup sequence again.

10 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 A.1.3 Legal Matters
This protocol specification is Copyright © 2007, 2008, 2009, and 2010 iDirect Technologies.
All rights reserved.
The protocol was invented and developed by iDirect Technologies.
The name OpenAMIP™ is a trademark of iDirect Technologies.
iDirect grants you permission to copy and distribute this document in unmodified form,
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 Technologies has rights to control the protocol itself, iDirect grants
you rights to implement the protocol within your product offering.
You are given a restricted and revocable right to use the trademark OpenAMIP™ to describe a
successful unmodified implementation of this protocol within your product. You may use the
term "modified OpenAMIP" to describe a product containing a variant of this protocol, but only
if your reference document prominently contains the term "modified OpenAMIP" and refers to
this document.
YOU ACKNOWLEDGE AND AGREE THAT YOU ARE SOLELY RESPONSIBLE FOR THE FEATURES,
FUNCTIONS AND PERFORMANCE OF YOUR PRODUCTS AND OFFERINGS. COMPLIANCE WITH THE
OPENAMIP PROTOCOL DOES NOT IMPLY ANY ENDORSEMENT BY IDIRECT OF YOU OR YOUR
PRODUCTS. IDIRECT DOES NOT MAKE ANY WARRANTIES REGARDING THE PERFORMANCE OR
FUNCTIONALITY THAT MAY BE OBTAINED DUE TO SUCH IMPLEMENTATION, AND EXPRESSLY
DISCLAIMS ANY AND ALL WARRANTIES, INCLUDING, WITHOUT LIMITATION ANY IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-
INFRINGEMENT, DATA ACCURACY, AND QUIET ENJOYMENT.

A.1.4 Certification
You may certify compliance of your interface with the test suite yourself, provided that you
ensure that the product accurately reflects the terms of this document. If you do, you are
free to use the trademark OpenAMIP™ solely for any product that you have properly 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 with the terms of
this document. Implementers are not permitted to publish their findings until thirty (30) days
after the OpenAMIP member notifies you of such findings. At your option, provided you have
notified the OpenAMIP member of your desire, the implementer's published finding of non-
compliance shall include a reference to a publicly available statement in rebuttal by you. You
acknowledge and agree that iDirect is not responsible for the acts and omissions of other
implementers of the OpenAMIP protocol.

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 11

A.2 OpenAMIP Messages
This section defines all message types generated by the OpenAMIP protocol. The formal
syntax and semantics are described in later sections.

A.2.1 Standard Message Types

The standard message set is comprised of the entire minimal set of functionality required for
OpenAMIP protocol operation. Sample messages in various scenarios are shown to illustrate
the purpose and usage of each message.

Satellite Description Messages

Scenario 1: The modem must be able to convey all of the information needed by the
controller to describe a satellite. These messages must be sufficient for the controller to
identify the satellite and to command the controller to find the satellite.
Table A-1 presents the satellite description parameters.

Table A-1 Satellite Description Parameters

Message
Type Message Syntax and Description
S Satellite longitude
[contains 3 parameters in degrees (all floating point values)]
For example:
S -20.1 1.0 3.5
where:
Negative values indicate west (i.e., -20.1)
wander in latitude = 1.0
Pol skew = 3.5
P Polarization
[contains 2 parameters. Parameters can be H, V, L or R for Rx and Tx]
For example:
P L R
H Hunt frequency
[contains 2 parameters: center frequency and bandwidth in Mhz (both floating point
values)]
For example:
H 1123.321 0.256
B Local oscillator Rx down-conversion and Tx up-conversion frequency offsets
[contains 2 parameters: frequencies in Mhz (floating point values)]
For example:
B 10750.0 13050.0

12 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 Table A-1 Satellite Description Parameters

Message
Type Message Syntax and Description
X Unformatted string used by the antenna controller
For example:
X nid=1234
F Find
[Use the recent S, P, R and H parameters]
For example:
F

Modem & Controller Status Messages

Scenario 2: The modem expects to receive keepalive messages. This is a simple mechanism
to ensure that communications connectivity with the controller has not been lost.
“Keep alive” (A) timing interval message (to controller)
[contains single parameter of n seconds]
A n
where:
n = number of seconds until antenna controller resends status
For example:
A 10
Scenario 3: The modem must be able to inform the controller when the modem has detected
the downstream carrier:
“Modem lock status” (L) message
[contains single yes/no parameter n]
L n
where:
n = 1 is locked, and n = 0 is unlocked
For example:
L 1
Scenario 4: 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:
“Controller status” (s) message
[contains 2 yes/no parameters: “functional” and “OK to transmit”]
s l m
where:
l = yes/no parameter (“1” functional, “0” not functional)
m = yes/no parameter (“1” OK to transmit, “0” not OK to transmit)
For example:
s 1 1

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 13

 Scenario 5: The modem must be able to request periodic location information:
“Location query” (W) message
[contains single parameter of n seconds]
W n
where:
n = number of seconds between location updates from controller
For example:
W 60
Scenario 6: The controller must be able to send GPS information to the modem:
“Location information” (w) message
[contains 4 parameters: valid, lat, lon and time]
w o p q r
where:
o = valid (=1) or invalid (=0)
p = latitude in degrees (floating point number, south is negative)
q = longitude in degrees (floating point number, west is negative)
r = GPS time in seconds (if the antenna does not have GPS time, set this to zero)
For example:
w 1 -10.123 20.235 123456789

A.2.2 Additional Message Types

In addition to the standard message types, OpenAMIP also supports several other message
types as described in this section.

Equipment Identification Messages

The messages in this section transmit equipment identification information between modems
and controllers.

Modem Identification
This message identifies the modem manufacturer and equipment model from the modem to
the controller.
“modem identification” (I) message
[contains 2 string parameters: manufacturer and model (no spaces in the strings)]
I s t
where:
s = modem manufacturer
t = modem model
For example:
I iDirect 5100

14 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 Controller Identification
This message identifies the controller manufacturer and equipment model from the controller
to the modem.
“controller identification” (i) message
[contains 2 string parameters: manufacturer and model (no spaces in the strings)]
I u v
where:
u = controller manufacturer
v = controller model
For example:
i YoyoDyne 1234

Keepalive Timing Interval Message

The controller can send a request for keepalive interval to the modem.
“Keep alive” (A) timing interval message (to modem)
[contains single parameter of n seconds]
A n
where:
n = number of seconds between keepalives from the modem
For example:
A 60

Extended Type Messages

Any antenna or modem manufacturer can extend the protocol by creating an extended type
field, which 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 ignores the message.
If an antenna controller receives a message of unknown type, the controller ignores 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.
For example:
Yoyodyne:NID 1132
Additional search parameter for satellite identification from modem to the Yoyodyne
antenna.
iDirect::stow 1
Command specified by iDirect, command from modem to the antenna to direct it to stow
itself.

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 15

 A.2.3 Backward Compatibility
There is also a requirement that newer versions of the protocol be backward compatible with
older versions. OpenAMIP accommodates this requirement by requiring that the meanings of
parameters never change from version to version. New parameters can be added to a
message, and new messages can be added.
The receiver, however, is required to ignore extra parameters and unknown messages,
allowing an older version of the protocol running on a receiver to work with a newer sender.
OpenAMIP also requires 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. The older version will not implement functionality that requires the newer version.
However, the older version will continue to provide the functionality of the older version
when operating with a partner that is using a newer version.

A.3 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. To comply with
certain regulatory constraints, the modem must disable its transmitter within 100ms from
when the antenna loses lock on a satellite, and must also disable the transmitter immediately
when a blockage occurs. Therefore, the antenna minimizes the interval between detecting a
change in condition and sending the status message to the modem. The antenna can choose to
use the modem lock signal as part of its satellite search, and as a result, the modem
minimizes the interval between detecting the condition and sending the message to the
controller. Status changes are reported within 10ms. This is not practical on slow serial links,
as it results in deprecating such links.

A.3.1 Communication Between Modem and Controller

Prior to any communication between the modem and the controller, the OpenAMIP state is
unspecified. The modem initiates communications by sending the commands needed to
deliver the satellite parameters to the controller. It then sends a Find (F) message.
When the controller receives a Find (F) message, it responds immediately with a Controller
status (s) message. The controller also sends a status every keepalive interval each time the
status changes. When the controller responds to an F message, the locked 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 is locked.
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 send
a status of unlocked because it is not locked to the new satellite (it is locked to the old
satellite). After the antenna locks to the new satellite, it sends a new status message
indicating that it is locked.
The modem sends a L 0 or L 1 whenever the modem lock changes. It also sends the locked
status each time its keepalive timer expires.
When the modem issues a Location query (W) message the controller immediately responds
with a Location information (w) message. The controller responds thereafter every w seconds
(zero seconds means never.) If the controller sends a w to the modem that indicates that the

16 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 location information is invalid, then the controller sends a new w message immediately when
it receives valid location information.

A.3.2 Latitude & Longitude Reporting

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, since the sender is free to use 0 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 range.
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 can be specified as an
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, since the
number of digits after the decimal point is arbitrary. However, the sender should provide as
much precision as is actually available. OpenAMIP allows the ability to use this information for
logging and transmission restrictions as mandated by regulatory authorities, so accuracy to
one kilometer is necessary, implying that latitudes and longitudes to a precision of
thousandths of a degree are needed.

A.3.3 Status Messages

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

K Message Usage
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 can be ignored. Otherwise, the antenna must use the current skew
as a factor in computing the “must not transmit” or “may transmit status.” When all other
factors permit transmission, the antenna immediately sends a status message with a status of
“must not transmit” when the angle transitions from below to above the maximum skew.
Likewise, the antenna immediately sends 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 affect immediately and the modem can send a new K message
with a new max skew angle at any time.

Antenna Functional Status Message

The functional status from the antenna indicates that the antenna is currently working. By
contrast, non-functional means that the antenna is not currently 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

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 17

 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 observes this status, it does not attempt to recover by (for example)
switching to a different satellite or clearing and re-establishing the OpenAMIP connection.
The modem waits until the antenna declares itself to be “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.

A.3.4 Simulation and Validation

Implementers can validate their 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.

A.4 Formal Syntax

This section contains the OpenAMIP formal syntax format. Both abstract and specific message
formats are presented, along with some notes on OpenAMIP version compatibility.

A.4.1 Abstract Message

An abstract OpenAMIP message format is specified below in Backus–Naur Form (BNF):
<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>

18 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 | <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'}
<optional whitespace>::=NULL|<whitespace>
<whitespace>::=<whitespace_char>|<whitespace><whitespace_char>
<whitespace_char>::= ' '|'\t'|\'r'

A.4.2 Specific Messages

Table A-2 catalogs all standard OpenAMIP message types.

Table A-2 Open AMIP Messages

Sender Type # Parms Parameters Semantics

Modem A 1 int seconds Keepalive time. Antenna should send a
status message at least this often.
Modem B 2 float RX lo frequency local oscillator RX down-conversion
frequency in MHz
float TX lo frequency local oscillator TX up-conversion
frequency in MHz
Modem E 1 float max power Maximum L-band TX power to be
expected at the Antenna (in dBm)
Modem F 0 Used for finding a satellite or sending a
parameter. The antenna should now
begin using the satellite specified by S,
P, B, X and H.
Modem H 1 float frequency Hunt frequency in MHz. Modem expects
antenna to use this hunt center
frequency when commanded.
float bandwidth Hunt bandwidth in MHz. Modem expects
antenna to use this bandwidth for
hunting when commanded.
Modem I 2 string: modem Optional
manufacturer
string: modem model
Modem K 1 float degrees Maximum skew of the beam short axis to
the geosynchronous arc.

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 19

 Table A-2 Open AMIP Messages

Sender Type # Parms Parameters Semantics

Modem L 2 binary 1 (locked) or Modem is locked to downstream, or not.
0 (unlocked) 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.
binary 1 (tx on) or Modem is free to transmit, or not. This
0 (tx off) signal may be used by the antenna to
remove power from the Tx amplifiers.
Modem P 2 char L, R, V, or H Modem expects antenna to use this Rx
pol when commanded.
char L, R, V, or H Modem expects antenna to use this Tx
pol when commanded.
Modem S 3 float longitude Satellite longitude. Modem expects
(degrees) antenna to use this satellite when
commanded.
float latitude variance Maximum excursion in satellite's latitude
(for inclined-orbit satellites).
float pol skew Satellite's nominal polarization offset in
degrees (for skewed satellites).
Modem T 2 float Tx freq Modem intends to transmit at this L-band
frequency in MHz.
float Tx bandwidth Modem intends to use this range of
frequencies in MHz.
Modem W 1 int seconds Location time. Antenna should send w
message immediately, and then repeat at
least this often. “0” means never repeat.
Modem 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 does not need to
send it. However, the modem may send it
anyway, in which case the controller will
ignore it.
Antenna a 1 int seconds Keepalive time. Antenna expects to see
an L message from the modem at least
this often.
Antenna i 2 string: manufacturer Optional.
string: model

20 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

 Table A-2 Open AMIP Messages

Sender Type # Parms Parameters Semantics

Antenna s 2 binary (1 or 0) antenna Antenna sends this immediately in
(is, is not) functional response to the F command from the
modem.
Antenna sends this immediately
whenever either of the two statuses
changes.
binary(1 or 0) modem Antenna send this periodically. The
(may, must not) period is set by the A command from the
transmit 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.
Antenna w 4 binary (1 or 0) location Antenna sends this to modem
(is, is not) valid. periodically. The period is set by the W
float latitude (degrees) command from the modem.
negative is south If the location is not valid, the antenna
float longitude may put the “0” character in the last
(degrees) negative is three parameters. If the antenna does
west of prime meridian not know the time, the last parameter
should be “0”. The precision of the
int time (GPS seconds) floating point numbers should reflect the
time in seconds since precision of the location information. For
the GPS epoch example, OpenAMIP expects 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.

A.4.3 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 can 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 message type that it receives, and must ignore any unexpected

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 21

 parameters at the end of a message. Furthermore, 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.

A.5 Transport Protocols

This section discusses supported transport protocols and interfaces for OpenAMIP.

A.5.1 TCP Interface

A modem and controller can communicate using TCP. Either the modem or antenna controller
can call the other. The method of discovering the IP address and TCP port is outside the scope
of OpenAMIP. In the reference implementation (see Section A.6, Design References), 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 goes down, the antenna sets its keepalive and GPS time to
infinity. When a new TCP connection is established, the antenna sends one keepalive to the
modem, and the modem sends one keepalive to the antenna. The disconnect timer is set to
15 seconds on each side. If the disconnect timer expires, the TCP connection is terminated.
The disconnect timer is set to 15 seconds whenever a keepalive message is received.
Neither the antenna nor the modem are required to accept more than one TCP connection at
a time, even though multiple connections are allowed. In a system with two modems, one can
function as a backup. In this arrangement, the antenna only honors satellite selection
requests from one modem.
TCP is a stream-oriented protocol, meaning there is no particular mapping of an OpenAMIP
message into an IP packet. A single packet can contain a fragment of a message, a complete
message, or multiple messages. In the reference implementation (see Section A.6, Design
References), 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
results in a single TCP/IP packet. The reference receiver implementation accumulates
characters until a new line is found and then processes the result as an OpenAMIP message.
Accumulation of the next message starts with the first character after the new line.

A.5.2 UDP Interface

Each message fits in a single UDP packet. This packet can 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.

A.5.3 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. Please note
that a checksum should be used in this situation.

22 Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note

A.6 Design References
A.6.1 Reference Implementations
iDirect provides reference implementations in C, and make no representations that these are
actually suitable for use in a product.

A.6.2 Test Suite

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

A.6.3 Software Availability

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

Open Antenna-Modem Interface (OpenAMIP) Implementation Technical Note 23