OpenAMIP Standard Version 1 17 Revision F
OpenAMIP Standard Version 1 17 Revision F
Version 1.17
Revision F
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. While every effort has been made to ensure the accuracy of the statements,
information and recommendations in this document, they are provided 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.
ST Engineering iDirect is a global leader in satellite communications (satcom) providing technology and solutions
that enable its customers to expand their business, differentiate their services and optimize their satcom networks.
Through the merger with Newtec, a recognized industry pioneer, the combined business unites over 35 years of
innovation focused on solving satellite’s most critical economic and technology challenges, and expands a shared
commitment to shaping the future of how the world connects. The product portfolio, branded under the names iDirect
and Newtec, represents the highest standards in performance, efficiency and reliability, making it possible for its
customers to deliver the best satcom connectivity experience anywhere in the world. ST Engineering iDirect is the
world’s largest TDMA enterprise VSAT manufacturer and is the leader in key industries including broadcast, mobility
and military/government.
iDirect Government created in 2007, is a wholly owned subsidiary of ST Engineering iDirect and was formed to better
serve the U.S. government and defense communities. In 2019, iDirect Government acquired Glowlink
Communications Technology, Inc.
ii OpenAMIP Standard
T0000682 | Revision F
Revision History
Revision History
The following table shows all revisions for this document. To determine if this is the latest
revision, check the Technical Assistance Center (TAC) Web site. Refer to on page viii for TAC
access information.
F October 30, 2020 OpenAMIP Standard version 1.17 release, with the following
enhancements:
• Significant new commands and modifications to existing
commands
• Modem commands extended with new parameters: B, F, H, I, L,
M, N, P, S, T, V, W, Y
• New Modem commands: G, O, R
• Message Types, Sender (M) on page 5
• Antenna commands extended with new parameters: i, s, v, w, y
• New Antenna commands: g
• Message Types, Sender (A) on page 22
• Added new status codes:
• Antenna Status Codes on page 34
Contents
About . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Certification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viii
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viii
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 3 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.1 Version Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.2 Modified OpenAMIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.3 Hardware Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
About
Purpose
This document describes the Open Antenna Modem Interface Protocol (OpenAMIP™) for
satellite terminals. OpenAMIP is an ASCII message-based protocol 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 initiate and maintain
communications through the satellite.
OpenAMIP is a command set which can be used for various satellite terminal implementations.
Not all commands are required for a given implementation and the subset of commands
required for a given implementation will be modem/ACU integration specific and will need to
be validated for proper functionality at the terminal level. OpenAMIP is designed to be
extensible for vendor-specific enhancements.
Disclaimer
This protocol specification is Copyright© 2006-2013 iDirect. All rights reserved.
The Protocol was developed 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.
Use of the trademark "OpenAMIP" to describe an unmodified implementation of this protocol
is unrestricted. Use the term "modified OpenAMIP" to describe a variant of this protocol, is
also unrestricted; however the document containing the term "modified OpenAMIP" refers to
this document.
While iDirect, Inc. 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, and expressly disclaims liability for errors and omissions. No
warranty of any kind, whether implied, expressed, or statutory, including but not limited to
the warranties of non-infringement of third party rights, title, merchantability, or fitness for a
particular purpose, is given with respect to the contents of this document.
iDirect, Inc. reserves the right to change or update this document at any time.
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.
Your use of the OpenAMIP™ trademark authorizes any OpenAMIP™ implementer to validate
your implementation and publish the results, referring to your product by company and
product name, if the implementer finds your implementation to be non-compliant. A finding
of non-compliance will not be published until thirty days after the OpenAMIP™ member
notifies you of the finding. At your option, the implementer's published finding of non-
compliance will include a reference to a statement in rebuttal by you.
Audience
The intended audience for this document is an engineering team responsible for integrating a
satellite terminal.
This document describes the Open Antenna Modem Interface Protocol (OpenAMIP™) for
satellite terminals. OpenAMIP is an ASCII message-based protocol to exchange 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 initiate and maintain communications
through the satellite.
OpenAMIP is primarily intended to permit a modem and a controller to perform synchronized
automatic beam selection, with status logging and diagnostic functions in support of that
main goal. 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.
2 Protocol Specification
2.1 Introduction
OpenAMIP is intended to be simple and flexible. Communications are in the form of messages
that are readable ASCII characters. 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, a single alphabetic character in the standard command set.
Each type of message requires a minimum number of parameters. The last parameter may
optionally be separated from the new line by a comment that begins with a #. The # can be
followed by a string containing any characters other than a new line.
The OpenAMIP protocol is a peer protocol: neither side is the master. The messages are sent
through any of the several lower-level protocols, such as HTTP, TCP/IP over a LAN, UDP over a
LAN, or using a high-speed serial connection.
For broadest compatibility, most parameters, and the ability to use the parameters, is
optional. Naturally, any unsupported parameter may result in an unsupported result, but basic
operation should function. Owing to the evolution of the standard, mandatory and optional
legacy parameters are not named, whereas more recently defined parameters are in key-
value pair format. When transmitting a parameter list, no mandatory parameters may be
omitted from the beginning or the middle of the list, although optional unnamed parameters
or key-value parameters may be omitted.
Because the unnamed parameters are not named, the receiving device can only distinguish
parameters from each other by their sequence. This requirement does not apply to
parameters specified as key-value pairs: for these, parameters are named, and may be
selectively excluded.
2.2 Syntax
The OpenAMIP format specified here is in Backus-Naur form (BNF). The format specification
below accommodates both legacy commands and key-values introduced in the OpenAMIP
Standard version 1.17 release.
Key value names are lower camel case (initial letter lower case, subsequent words first letter
capitalized).
<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>::=<o_message>|<normal_message>
<o_message>::=O' '{line1, 69 times any char}' '{line 2, 69 times any
char}<satname>
<satname>::''|' '{satname, at most 24 times any char}
<normal_message>::=<msg_type><param_list><kv_list>
<msg_type>::=<string>
<param_list>::=''|<whitespace><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'}
<kv_list>::=''|<whitespace><kv_pair><kv_list>
<kv_pair>::=<string>'='<param>
<optional_whitespace>::=''|<whitespace>
<whitespace>::=<whitespace_char>|<whitespace><whitespace_char>
<whitespace_char>::=' '|'\t'|'\r'
No. of
Type Description Name of the Parameters
Parameter(s)
A Alive interval 1 int interval, seconds
Antenna should send a status message at least this often. 0
means never repeat.
No. of
Type Description Name of the Parameters
Parameter(s)
C Carrier to Noise Ratio for Conical Scan 5 float CNR (SNR) in dB,
Reporting rate is configured by "c" message. Default "C" measured on headers and
message rate is zero (if "c" message reporting rate pilots
parameter is not present, the "C" message is disabled). It is
recommended to provide this message by UDP as a separate
stream. float CNR (SNR) in dB,
measured on data
D Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
E Expected power 1 float max power
Maximum Tx power to be expected at input to the antenna
(BUC), the output of the modem minus cable loss, in dBm.
(Optional)
(Optional key-value format parameters)
No. of
Type Description Name of the Parameters
Parameter(s)
G Check the satellite 0
(minimum)
This command is similar to ‘F’ command, except that ACU
does not act (that is, repoint the antenna, select new bands,
change polarization) on the information. ACU will only
respond to whether new proposed antenna pointing is valid
(that is, non-blocked, and so on). The antenna responds
immediately to each ‘G’ command with a single ‘g’
response.
No. of
Type Description Name of the Parameters
Parameter(s)
H Hunt frequency in MHz. Modem expects antenna to use 2 float frequency,
this receive hunt center frequency when commanded. (minimum)
float bandwidth
Bandwidth in MHz (should be specified down to 1 Hz
resolution) Receive RF frequency can be determined
through combination of RX LO (LNB) frequency in the “B”
message and the center IF frequency specified here in the
“H” message
Carrier Type
carrierType=<string>,
Identify Carrier Type antenna is being commanded to hunt.
{service, signaling}
Defined types = {service, signaling} If the carrier type
is not defined, it is assumed to be ‘service’
No. of
Type Description Name of the Parameters
Parameter(s)
I ID of the modem type (optional) 2 string: modem manufacturer
(minimum) and string: modem model
Upon initial connection with the antenna, the modem is
expected to transmit this information without being
solicited (that is, ‘i’ command) by the antenna.
Example:
I iDirect cx780 modemSerialNo=14758 modemSwRev=2.0
Example:
Where Manufacturer is iDirect, the model is Yoyo1, and
there is a specific opid key they have defined;
I iDirect Yoyo1 iDirect:opid=123
J Reserved
K Maximum and minimum sKew of the beam short axis to the 2 float max skew
geosynchronous arc, in degrees. Transmitter should be float min skew
disabled when these limits are exceeded. Minimum skew
defaults to zero if absent.
No. of
Type Description Name of the Parameters
Parameter(s)
L Lock status of receiver 2 RX Lock State: binary
The modem should send this message immediately when (minimum) 1 (locked)
the status changes. The modem should send this message or
periodically at intervals specified by the antenna in the "a" 0 (unlocked)
message.
binary TX Enable:
Antenna is free to transmit, or not. This command may be
1 (Tx on)
used by the antenna to remove power from the Tx
amplifiers. (Note, if ‘M’ command is used, it will take or
precedence over any action expected by setting Tx Enable 0 (Tx off)
flag to 0 ‘Tx off’).
faultStatus=<string
Fault Status (faultStatus) fault status>
An indication of modem’s fault status {fault, ready} {fault, ready}
No. of
Type Description Name of the Parameters
Parameter(s)
N Not Track-test mode 0
The antenna should be aimed in a non-interfering (minimum)
direction, away from any satellites offering active service.
This is intended to support installation tests such as power
measurements
Optional
antenna_number parameter indicates the 'requested (optional) int antenna number
antenna number'. This parameter is an integer type with a
range of [0 – n], where n is the number of antennas
connected. For single antenna use cases, the value reported
should be '1'. If this parameter is set to '0' or not present, the
ACU will infer that single antenna is connected.
No. of
Type Description Name of the Parameters
Parameter(s)
O Ephemeris (Orbit) information. 1 TLE string (139 characters):
Where the string must contain,
The O command parameter is a string containing lines 1 and TLE Line 1 (69 char) +
2 of a standard Two Line Element (TLE) string at fixed space separator (1 char) +
positions separated by a space character.
TLE Line 2 (69 char)
(https://en.wikipedia.org/wiki/Two-line_element_set).
or
The optional Title Line (satellite name) may be appended
after lines 1 and 2, after a space separator.
TLE string (164 characters):
Once sent to the antenna, the tracking of the satellite Where the string must contain
defined in the TLE string is activated by sending the ‘F’ TLE Line 1 (69 char) +
command space separator (1 char) +
TLE Line 2 (69 char) +
Example space separator (1 char) +
O 1 25544U 98067A 08264.51782528 -.00002182 00000-0
TLE Title Line (24 char)
-11606-4 0 2927 2 25544 51.6416 247.4627 0006703
130.5360 325.0288 15.72125391563537 ISS (ZARYA)
No. of
Type Description Name of the Parameters
Parameter(s)
P Polarization 2 char Rx Polarization:
Modem commands antenna to use these polarizations. (minimum) L, R, V, or H
Command must contain minimum of 2 parameters for
primary Rx and Tx. Additional polarizations are optional.
char Tx Polarization:
L, R, V, or H
(Optional key-value format parameters)
(optional)
Additional Rx and/or Tx polarizations may be specified. No
rx2=<char L, R, V, or H >
upper limit on the number of Rx and Tx polarizations is
rx3=<char L, R, V, or H >
defined, but these should match the number of Rx and Tx
configured in ‘B’. (…)
tx2=<char L, R, V, or H >
tx3=<char L, R, V, or H >
Additional polarizations beyond the first Rx and first Tx are
specified in key,value pair format. (…)
Q Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
R Regulation Type Selection 1
Identification of the Regulatory Regime to be applied. It is (minimum)
expected that this command will be sent as part of
configuration commands prior to an ‘F’ command, to occur
at beam-switch. The antenna will report back with
information in the ‘q’ message. If no reporting interval
(reportingInterval) is specified, the antenna will report
back only once.
• FCCGEO
• FCCNGSO
• ETSIGEO
• ETSINGSO
(optional)
(Optional key value pairs)
reportingInterval=<int
Max ESD Reporting Interval (reportingInterval) seconds>
No. of
Type Description Name of the Parameters
Parameter(s)
S GEO Satellite longitude 3 float longitude (degrees)
Modem expects antenna to use this satellite when (minimum)
commanded. Maximum excursion in satellite’s latitude (for float latitude variance (degrees)
inclined- orbit satellites) Satellite’s nominal polarization
offset in degrees (for skewed satellites) float polarization skew (degrees)
From behind the dish, facing
towards the satellite; clockwise
is positive.
(Optional key value pairs)
Name (name)
String defining the name of the GEO satellite. name=<string>
T Transmit frequency. 2 float Tx frequency, MHz
Modem intends to transmit at this frequency (MHz) and (minimum) and
bandwidth (MHz) float Tx bandwidth, MHz
Transmit RF frequency can be determined through
combination of TX LO (BUC) frequency in the “B” message
and the center IF frequency specified here in the “T”
message.
(Optional)
(Optional key value pairs)
U Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
V Supported OpenAMIP Commands. 0 char command
Supported commands are explicitly communicated from (minimum)
Modem to Antenna: the Modem indicates by a series of key int parameters supported
value pairs which commands are supported, and up to how
many parameters are supported by the command.
V <command> <nof_unnamed_parameters>
<kv_list_supported_keys>
where,
<command>: the command which is supported by the sender
<nof_unnamed_parameters>: the number of unnamed
parameters the sender supports
<kv_list_supported_keys>: the list of keys the sender
supports, all values will be 1
Examples:
Modem requests antenna to send commands supported
[Modem] V
No. of
Type Description Name of the Parameters
Parameter(s)
W Where (location) Interval 1 int repeat interval, seconds.
Antenna should send w message immediately, and then repeat at (minimum)
least this often. 0 means "never repeat"
Should be float, if the
modem requests antenna to
NOTE: integer is a valid subset of the float type. Non-integer time is
transmit "w" at rates higher
used only for specialized highly dynamic terminals, by agreement
between modem and antenna vendor. The modem shall not request
than 1 Hz
non-integer time unless the antenna is known to support it. Decimal
point and digits after decimal may be omitted, unless modem and
antenna both support high-rate reporting for highly dynamic
terminals, and modem has requested rate > 1Hz.
No. of
Type Description Name of the Parameters
Parameter(s)
X eXtra hunt parameters 1 string
This is a fixed string to be configured by the operator and
sent as part of the lookup. Note that the contents of this
message are processed on receipt of an F.
No. of
Type Description Name of the Parameters
Parameter(s)
Y Miscellaneous and Custom Commands. ‘Y’ command may to be used 1 String
to send custom asynchronous messages to the antenna in a key-
(minimum)
value pair formatted string. Vendor specific commands may be used
here, as long as they are prefixed with a vendor key (as described in
the ‘I’/’i’ commands) according to the following this syntax:
<vendorname>:<keyname>
The vendor-defined key may be any valid data type (int,
float, string, char, binary). Example:
Y iDirect:specialCmd=123
maxOutageDuration=<int
Maximum Outage Duration (maxOutageDuration)
seconds>
The maximum duration expected for the reboot outage, specified in
seconds.
No. of
Type Description Name of the Parameters
Parameter(s)
Z Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
a alive interval 1 int repeat interval, seconds
Antenna requests to see an L message from the modem
at least this often. 0 means "never repeat".
b Reserved
d-f Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
g Status of the antenna. Antenna sends this immediately in response to the 4 binary Antenna Functional:
G command from the modem. The format of this response is meant to
mirror that of the ‘s’ response, although not all parameters are (minimum) 1 – antenna functional
relevant.
0 - antenna not functional
"Not functional" means that the antenna cannot currently operate
and will never operate with this configuration. This can be temporary
(for example, an illegal configuration) or permanent (for example, motor
frozen).
The optional sixth parameter indicates to the modem the number of int RF_chains
RF chains supported by the terminal. For single RF Chain (antenna) use
cases, the value reported should be '1'. This parameter is an integer int active_RF_chain_index
type with a range of [0 - n], where n is the number of RF chains
antennas connected. (If this parameter is set to '0' the modem will
infer that single antenna is connected)
The optional seventh parameter indicates to the modem the index of the
active RF chain. For single antenna use cases, the value reported should
be '1'. This parameter is an integer type with a range of [0 - n],
where n is the number of antennas connected. (If this parameter is set to
'0' the modem will infer that single antenna is connected)
h Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
i ID of the antenna type 2 string: manufacturer and
(minimum) string: model
Upon initial connection with the modem, the antenna is
expected to transmit this information without being
solicited (that is, ‘I’ command) by the modem.
In addition to the keys defined above, vendor specific Vendor specific key
keys may be defined, following this syntax: <vendorname>:keyname>=<int,
float,string,char, or
<vendorname>:<keyname>
binary>
The vendor-defined key may be any valid data type (int,
float, string,char, binary).
Example:
Where Manufacturer is Yoyodyne, the model is Yoyo1,
and there is a specific opid key they have defined;
i Yoyodyne Yoyo1 Yoyodyne:opid=123
j-p Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
q EIRP Spectral Density (ESD) calcuation information. 2
(minimum)
The reporting interval of this message from the Antenna is
configured with the ‘reportingInterval’ parameter of the
‘R’ message. This message from the antenna includes the data
the modem needs for performing the calculation. The modem is
expected to enforce the ESD limit at the antenna/radome
output based on the ESDMax limit (esdMax), the symbol rate
(Rs), modem output power, and RF chain gain information:
esdMax = eirp – 10log(Rs / bandUnits)
The calculated EIRP Spectral Density (ESD) is compared with
ESD limit and modem transmission power is set accordingly.
(optional)
(Optional key value pairs)
EIRP Spectral Density Maximum (esdMax) esdMax=<float dBW/bandUnits>
The current peak ESD of the antenna based on current skew
angle, scan angle and so on. ESD maximum is the peak EIRP
spectral density while in compliance with off-axis regulations
such as FCC 25.218 and ETSI EN 303 978.
Units are dBW/bandUnits, where bandUnits is itself specified
below. If bandUnits is not specified, the bandwidth units are
assumed to be 1Mhz.
G/T (gt)
The current value of G/T in dB/K based on pointing angle. For gt=<float dB/K>
mechanically steered antennas, this will usually be a constant.
For Electronically steered arrays, it will vary with scan angle.
EIRP (eirp)
The current maximum value of EIRP in dBW based on pointing eirp=<float dBW>
angle. For mechanically steered antennas, this will usually be a
constant. For Electronically steered arrays, it will vary with
scan angle. This may not be the EIRP that is currently being
transmitted due to modem backoff and other factors
Examples,
to select units of 400Khz, set bandUnits=400
to select units of 1Mhz, set bandUnits=1000
skewAngle=<float degrees>
Skew Angle (skewAngle)
(float degrees)
No. of
Type Description Name of the Parameters
Parameter(s)
Transceiver Power (transceiverPower) transceiverPower=<float
Transceiver power detector reading, in dB. dB>
r Reference frequency required for BUC and LNB. 2 int frequency MHz
Frequency is in MHz.
string Reference Used By: R, T,
Reference required to be present on Rx (R), Tx (T) or or B (for example,"r 10 B")
both (B)
No. of
Type Description Name of the Parameters
Parameter(s)
s Status of the antenna. 3 binary Antenna Functional:
Antenna sends this immediately in response to the F (minimum) 1 – antenna functional
command from the modem, or immediately when any of the 0 - antenna not functional
two statuses changes, or periodically. The period is set by the
A command from the modem.
int antenna_status 0 to
The optional fifth parameter is an enumerated detailed status 65535
of the current antenna selected. (See Table 2-3, Enumerated
Antenna Status Codes.)
int RF_chain
The optional sixth parameter indicates to the modem the
number of RF chains supported by the terminal. For single RF
Chain (antenna) use cases, the value reported should be '1'. This
parameter is an integer type with a range of [0 - n], where n is
the number of RF chains antennas connected. (If this parameter
is set to '0' the modem will infer that single antenna is
connected)
No. of
Type Description Name of the Parameters
Parameter(s)
The seventh parameter indicates to the modem the index of the int active_RF_chain_index
active RF chain. For single antenna use cases, the value
reported should be '1'. This parameter is an integer type with a
range of [0 - n], where n is the number of antennas connected.
(If this parameter is set to '0' the modem will infer that single
antenna is connected)
t Reserved
u Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
v Supported OpenAMIP commands are explicitly 0 char command
communicated from Antenna to the Modem: the Antenna (minimum)
indicates by a series of key, value pairs which commands
int parameters supported
are supported, and up to how many parameters are
supported by the command.
Examples:
Antenna requests modem to send commands
[Antenna] v
Antenna indicating commands it supports
[Antenna] v a 1
Antenna indicates it has completed sending command
list to the modem
[Antenna] v end=1
No. of
Type Description Name of the Parameters
Parameter(s)
w Where the platform is located. Antenna sends this to modem 4 binary Location Valid:
periodically. The period is set by the W command from the 1 – valid
(minimum)
modem. If the location is not valid, the antenna may put 0 in
0 – invalid
the remaining parameters. The precision of the floating point
numbers should reflect the precision of the location
information. Typically six to eight digits is desirable for lat/lon float latitude (degrees) negative is south
values. The antenna should send a w immediately if its internal
float longitude (degrees) negative is west
GPS status changes from "invalid" to "valid". of prime meridian
If the antenna does not know the time, the time parameter float time (GPS seconds) time in seconds
should be set to 0. since the GPS epoch.
The time parameter is mandatory if Doppler compensation is to
float altitude (meters)
be applied.
float heading referenced to true north
NOTE: integer is a valid subset of the float type. Non-integer (degrees)
time is used only for specialized highly dynamic terminals, by
agreement between modem and antenna vendor. The modem float GPS computed speed (m/s)
shall not request non-integer time unless the antenna is known
float pitch angle (degrees).
to support it. Decimal point and digits after decimal may be
Positive is up, negative is down.
omitted, unless modem and antenna both support high-rate
reporting for highly dynamic terminals, and modem has float roll angle (degrees). Positive is rolled
requested rate > 1Hz. If provided, timestamp must correspond to starboard, negative is rolled to port.
to the latitude/longitude values. If omitted, all following values
must also be omitted, and Doppler compensation is not float yaw angle (degrees). Positive is
inclined to starboard. Negative is inclined
possible.
to port.
If the altitude parameter is not known, then it is set to zero. float skew angle (degrees). Positive is CW
when facing satellite from ground.
Negative is CCW when facing satellite.
(Optional key-value format parameters)
No. of
Type Description Name of the Parameters
Parameter(s)
x Reserved
No. of
Type Description Name of the Parameters
Parameter(s)
rx(N)Band(M)Active: binary,
1 = band is active (in use)
0 = band is inactive (not in use)
Example:
[Modem] Y extCmd=getConfigB
[Antenna] y replyTo=getConfigB
rx1Band1LO=17300.000 rx1Band1Start=18250.000
rx1Band1Stop=18750.000 rx1Band1Inv=0
rx1Band1Active=1 tx1Band1LO=28500.000
tx1Band1Start=29000.000 tx1Band1Stop=29500.000
tx1Band1Inv=0 tx1Active=1
rx(N)PolOpts
tx(N)PolOpts
No. of
Type Description Name of the Parameters
Parameter(s)
For Example:
[Modem] Y extCmd=getConfigP
[Antenna] y replyTo=getConfigP rx1PolOpts=LRHV
rx1PolActive=L tx1PolOpts=LRHV tx1PolActive=L
rx2PolOpts=LRHV rx2PolActive=R tx2PolOpts=LRHV
tx2PolActive=L
For Example:
[Modem] Y extCmd=getExtAntStatus
[Antenna] y replyTo=getExtAntStatus metric=2
metric3=3.456 metric4=enabled metric5=32.4
sigCarriersEnable=<string
status>
Signal Carrier Enable/Disable (sigCarriersEnable)
z Reserved
Code Description
0 Modem May Transmit - No problems detected.
1 Cable Unwrap - Antenna has reached its Azimuth motion limit and is performing an azimuth
move away from the limit; no longer tracking the satellite.
2 Blockage Zone - The Antenna is tracking in a Blockage Zone defined for the vessel where
obstructions can inhibit or degrade satellite communication.
3 RF Hazard Zone - The Antenna is tracking in a No Transmit area defined for the vessel for RF
radiation hazard reasons.
4 Sidelobe Check - The Antenna is performing a search pattern to determine if it is has
peaked the RF signal on the main beam or the sidelobe.
5 Elevation Limit - The Antenna is tracking above or below the specified elevation limits for
the system.
6 AZ/SKEW Limit - The Antenna is tracking and the Azimuth or Skew Pointing Error exceeds
the transmit limit indicating it may be mispointed (primarily for keyhole tracking).
7 Gyro Cap - The Antenna is tracking and the Azimuth or Elevation acceleration exceeds the
transmit limit indicating it may be mispointed.
8 Ant Search State - The Antenna is commanded to go to a new satellite and is searching for
that satellite.
9 RSSI Below Threshold - The Antenna is tracking and it detects that the RSSI has fallen below
RSSI valid threshold for a duration of time as dictated by FCC regulations.
10 Initializing - The Antenna boots up or gets restarted and is in its initialization process.
11 LNB Voltage Error
12 BUC Voltage Error
13 RF Configuration Error
14 RF Communication Error
15 On Ground (aircraft is prohibited from transmitting)
16 Geographic Restriction for regulatory reasons
17 HW Mute Switch (for example, for safety interlock).
18 Blockage Warning – based on ephemeris of current NGSO satellite being tracked
and Blockage zones defined, a blockage is anticipated in XX seconds (where XX is
communicated to the modem as a key-value parameter).
19 RF antenna resources are busy
20 Antenna Muted by Modem
21 Peaking
22 Pending Operator Authorization
Code Description
23 Solar Outage
24 Stabilisation Error
25 Motor Error/Failure
26 Encoder Error/Failure
27 Sensor Error/Failure
28 ACU Communications Error/Failure
29 Power Error
30 Antenna Out of Calibration
2.7 Semantics
The protocol is primarily intended to convey state change information based on external
events. The following notes are intended to provide functional guidance for various common
events and message sequences. It is not intended to be a comprehensive list of messages nor
a syntax dictionary.
To comply with 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. The antenna must 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. The modem must also minimize
the interval between detecting the condition and sending the message to the controller.
Status changes should be reported within 10ms. However, since this will not be practical on a
slow serial link, the links are 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 within 10 milliseconds with an
"s" message. This is necessary to ensure regulatory compliance in the case when the modem
needs to mute. The controller must 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 is 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 an "L" message whenever the modem lock changes. It should also
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 "repeat interval" seconds (zero seconds means never). If the
controller sends a "w" to the modem which indicates that the location information is invalid,
the controller should send a new "w" message immediately as soon as 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 an integer (that
is, 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 one thousandth 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" in the 's' response.
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. 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 "K" message also includes a minimum skew parameter, to
support protection of non-geostationary satellites. The minimum skew parameter operates
analogously to the maximum skew parameter; the antenna controller should send a status of
"must not transmit" when the skew is less than this value.
When the antenna reports with an "s" message that the antenna is functional, it indicates that
the antenna should currently be working. "Non-functional" means that the antenna is not
currently 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 detects this status, it will 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 sends a "functional" message. The antenna provides a "may transmit"
when it is locked on the satellite and ready to 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, and so on.
2.8 Examples
This section 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 test scripts. Typically, implementations of the receive side of the protocol will
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.
The modem informs the controller when the modem has detected the downstream carrier:
I iDirect 5100 # ID: modem manufacturer and type strings.
K 45 15 # sKew: maximum and minimum skew. The antenna controller must
disable transmission when outside these angles (in degrees). This is
typically used with non-circular apertures.
L 1 1 networkStatus=online # Lock status: Rx locked (1 is locked, 0 is
unlocked), Tx OK (1 means antenna MAY transmit; 0 means antenna MUST
NOT transmit). Modem may optionally indicate its network status.
M txMuteState=enable # Modem explicitly commands antenna to MUTE
transmit. This takes precedence over any default action taken as a
result of L x 0 command.
The “y” command can be used to asynchronously send information to the modem, and is also
used to respond to specific modem requests for information: getConfigB, getConfigP, and
getExtAntStatus. The example below shows a sample response to a request for BUC and LNB
information in a system with a multiband LNB and a single-band BUC:
y replyTo=getConfigB rx1Band1LO=17300.000 rx1Band1Start=18250.000
rx1Band1Stop=18750.000 rx1Band1Inv=0 rx1Band1Active=1
rx1Band2LO=19300.000 rx1Band2Start=20250.000 rx1Band2Stop=20750.000
rx1Band2Inv=0 rx1Band2Active=0 tx1Band1LO=28500.000
tx1Band1Start=29000.000 tx1Band1Stop=29500.000 tx1Band1Inv=0
tx1Active=1
A further example of the ‘y’ response for command ‘getExtAntStatus’ is provided in Extended
Antenna Status on page 45.
3 Compatibility
In some deployments, the modem may request additional detailed status from the antenna
for the purposes of system logging. The request and response are as follows:
[Modem] Y extCmd=getExtAntStatus
[Antenna] y replyTo=getExtAntStatus <sequence of k-v defined parameters>
or,
[Modem] Y extCmd=getExtTransceiverStatus
[Antenna] y replyTo=getExtTransceiverStatus <sequence of k-v defined
parameters>
Implementations will vary widely between antenna manufacturers, so it is not the intention
to codify these response parameters in the standard, nor is it the intention that the modem
should parse this string and take action upon values within it. The modem is simply expected
to forward this set of logging information.
Since the modem is not expected to act on any of the values contained in the dictionary
below, the proposed extended Antenna or Transceiver status parameters below are not to be
reported to the modem as part of the ‘V’/’v’ supported commands.
Nonetheless, there are many features common to antennas that can be reported on, the table
below proposes names and descriptions for commonly monitored metrics. This list is not
meant to be prescriptive or comprehensive.
Example,
[Modem] Y extCmd=getExtAntStatus
[Antenna] y replyTo=getExtAntStatus antAbsAz=87.50 antAbsEl=52.00
antAbsCL=12.00 antRltAz=30.50 antTrgAz=10.25 antTrgEl=8.25
antErrAz=5.00 antErrEl=2.00 feedSkew=20.0 antMD=manual trkMD=stepTrack
stOffset={-25.0,15.0,30.0,-20.5} antStats=motorError orbitType=meo
feedSkew=25.0 lnbLOSetting=18100 trkFreq=3333.2500 trkBw=100.00
rfband=Ka lat=10 long=10 alt=10000 speed=550.50 heading=30.25
time=12345678 roll=10.10 pitch=4.0 yaw=25.0 bucFwdPower=30.00
bucInputPower=15.50
Example,
[Modem] Y extCmd=getExtTransceiverStatus
[Antenna] y replyTo=getExtTransceiverStatus txState=ok
bucLatchedFault={externalReferenceFault} bucTemp=55.50 bucLOSetting=27500
lnbState=OK
A.1.1 Hardware
Table A-1. Antenna: Hardware
Defined options:
{ok,
blocked,
solarOutage,
stabilisationError,
motorError,
encoderError,
sensorError,
acuCommsError,
powerError,
antennaOutOfCalibration,
bucError,
lnbError}
or custom string
A.1.3 Configuration
Table A-3. Antenna: Configuration
A.2.1 Transceiver
Table A-5. Transceiver
Defined options:
{externalReferenceFault,
highForwardPowerFault,
lowForwardPowerFault,
internalFault,
overTemperatureFault,
fanFault,
noConnection}
or custom string
bucFwdPower BUC / Transmitter forward power dBm (float, nn.nn)
00.00 to 99.99
Defined options:
{ok,
externalReferenceError,
voltageFault,
toneFault,
overCurrentFault,
internalFault,
overTemperatureFault,
noConnection}
or custom string
lnbLatchedfault Latched faults within the LNB list {string} ({fault-1,fault-2, …
fault-n})
Defined options:
{externalReferenceError,
voltageFault,
toneFault,
overCurrentFault,
internalFault,
overTemperatureFault,
noConnection}
or custom string