0% found this document useful (0 votes)
603 views64 pages

OpenAMIP Standard Version 1 17 Revision F

Uploaded by

Rega Primasta
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
603 views64 pages

OpenAMIP Standard Version 1 17 Revision F

Uploaded by

Rega Primasta
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 64

OpenAMIP Standard

Version 1.17

Revision F

October 30, 2020


© 2020 ST Engineering iDirect, Inc. dba iDirect and/or its affiliates. All rights reserved.

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.

Company Website: www.idirect.net | Main Phone: 703.648.8000


TAC Contact Information: Phone: 703.648.8151 | Email: [email protected] | Website: www.support.idirect.net

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.

Company Website: www.idirectgov.com | Main Phone: 703.648.8118


TAC Contact Information: Phone: 703.648.8111 | Email: [email protected] | Website: partnerportal.idirectgov.com

Document Name: OpenAMIP_Standard_T0000682_RevF_10302020.pdf


Document Part Number: T0000682

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.

Revision Date Updates


A August 4, 2015 • First release of the OpenAMIP Standard (version 1.8) document
in iDirect Technical Publications template. For changes from
version 1.7 to 1.8, see Modified OpenAMIP on page 44.
• The time parameter of the w command is now made mandatory.
See Message Types, Sender (M) on page 5.
B October 12, 2016 Updated to OpenAMIP Standard version 1.9 to 1.12.
C November 1, 2016 Updated “w, W, H, and C” type message descriptions.
D September 8, 2017 Here are the changes from version 1.12 to 1.16:
• Time is now always accepted as float.
• New reserved parameters in "N" and "s" messages.
• New parameter in "s" message for detailed enumerated status
code.
• New reserved parameter in "F" message and new reserved "f"
message.
• Reason Code = 0 should be used when the modem may transmit.
• Added a note about optional parameters in 2.1.
• Added an example of 's' in a blockage zone in 2.6.2.
• Deleted Section 3.1.1; it was redundant with the Revision
History.
E September 27, 2018 Updated the F message to remove unsupported descriptions.

OpenAMIP™ Standard Version 1.17 iii


T0000682 | Rev F
Revision History

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

iv OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Contents

Contents

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii

About . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Certification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viii
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .viii

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2 Protocol Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3


2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 Message Types, Sender (M) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4 Message Types, Sender (A). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.5 Antenna Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.6 Physical Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.6.1 TCP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.6.2 UDP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.6.3 Asynchronous Serial Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.7 Semantics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.8 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.8.1 Messages from Modem to Antenna Controller . . . . . . . . . . . . . . . . . . . . . 39
2.8.2 Messages from Antenna Controller to Modem . . . . . . . . . . . . . . . . . . . . . 41

OpenAMIP™ Standard Version 1.17 v


T0000682 | Rev F
Contents

Chapter 3 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.1 Version Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.2 Modified OpenAMIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.3 Hardware Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Appendix A Extended Antenna Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45


A.1 getExtAntStatus Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
A.1.1 Hardware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
A.1.2 Dynamic Operating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
A.1.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
A.1.4 Geolocation, Movement, Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
A.2 getExtTransceiverStatus Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
A.2.1 Transceiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

vi OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
About

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

OpenAMIP™ Standard Version 1.17 vii


T0000682 | Rev F
About

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.

NOTE: iDirect provides reference implementations in C. No representations are


made that these are suitable for use in any product. Semantics may be validated
by executing a script that emulates a controller or a modem. The scripts are
written in POSIX-compliant C. Code for the test suite was developed from the
reference implementation. The source code for the reference implementations
and the test scripts is copyrighted by iDirect but is licensed at no cost for use for
any purpose.

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.

viii OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
1 Introduction

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.

OpenAMIP™ Standard Version 1.17 1


T0000682 | Rev F
2 OpenAMIP™ Standard Version 1.17
T0000682 | Rev F
Introduction

2 Protocol Specification

This chapter contains the following sections:


• Introduction on page 3
• Syntax on page 4
• Message Types, Sender (M) on page 5
• Message Types, Sender (A) on page 22
• Antenna Status Codes on page 34
• Physical Layer on page 36
• Semantics on page 37
• Examples on page 39

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.

OpenAMIP™ Standard Version 1.17 3


T0000682 | Rev F
Syntax

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'

4 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

2.3 Message Types, Sender (M)


Table 2-1. Message Types, Sender (M)

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.

B Beat frequency oscillator (local oscillator) frequencies; 2 float Rx LO frequency, MHz


effective amount of down-conversion (Rx) or up-conversion (minimum) float Tx LO frequency, MHz
(Tx).

(Optional key-value format parameters)


(Optional)

Multiband Rx or Tx LO Frequencies (rx(N), tx(N))

LO frequencies for additional devices (LNBs) may be rx2=<float Rx2 LO


specified. Each additional Rx is identified by an index frequency MHz>
number, starting with index ‘2’ (that is, rx2, rx3, rx4, and
so on.) There is no maximum number of receivers
rx3=<float Rx3 LO
specified.
frequency MHz>
(…)
LO frequencies for additional devices (BUCs) may be
tx2=<float Tx2 LO
specified. Each additional Tx is identified by an index
frequency MHz>
number, starting with index ‘2’ (that is, tx2, tx3, tx4, and
so on). There is no maximum number of transmitters
specified. tx3=<float Tx3 LO
frequency MHz>

Command format with minimum set of parameters: (…)

B <Rx LO freq> <Tx LO freq>


Command format with 6 additional optional parameters:
B <Rx LO freq> <Tx LO freq> rx2=<rx2 LO freq>
rx3=<rx3 LO freq> rx4=<rx4 LO freq> tx2=<tx2 LO
freq> tx3=<tx3 LO freq> tx4=<tx4 LO freq>

Example: B 18000.500 28000.500 rx2=18200


rx3=18500.750 tx2=28000.625 tx3=28000.750

To query the capabilities of the available oscillators which


may be configured, see the ‘Y extCmd=getConfigB’
command and corresponding ‘y’ response.

OpenAMIP™ Standard Version 1.17 5


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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

float time in seconds.


This free running counter
may wrap around through
zero periodically; it is
recommended to use enough
resolution for at least an
hour between wrap events.

received carrier lock state


where 0 means invalid, 1
means not locked, 7 means
fully locked, and values in
between are intermediate
states of lock (intermediate
state details are product-
specific).

float composite power, dBm,


measured at the IF input to
the modem.

D Reserved

6 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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.

The power specified could be for signals at I/Q, L-band (or


any IF), or RF, depending on system implementation.

F Find the satellite 0


Antenna should now begin using the satellite specified by (minimum)
either {S, P, B, R, X, and H } or { O, P, B, R, X, and
H } commands. This command overrides the N command.

(Optional)
(Optional key-value format parameters)

time=<float time (GPS


Execution time (time) seconds)>
The time when this command is expected to have
completed. Time is specified as (seconds since the GPS
epoch).

When no time tag is added, or the execution time specified


has past, the command will be executed immediately.

OpenAMIP™ Standard Version 1.17 7


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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.

Modem has already sent satellite information to the Antenna


specified by either command.

(Optional key-value format parameters)


(Optional)

Execution time (time)


time=<float time (GPS
If this parameter is specified, the antenna will respond seconds)>
immediately with a ‘g’ message containing the expected
antenna status at the future point in time specified. (Note
that this differs from the ‘F’ command, where the ‘time’
key is used to delay the execution of the ‘F’ command to a
future point in time.)

Time is specified as (seconds since the GPS epoch)

Cache Start Beam (cacheStartBeam) cacheStartBeam=1


This key indicates to the antenna that the configuration
provided prior to the ‘G’ command should be stored
(cached) by the antenna for future use as a default start
beam. If this key is used, the value is always ‘1’.

8 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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

(Optional key-value format parameters) (Optional)

Roll-off Factor (rof)


rof=<float roll-off
Available options are (1.05, 1.1, 1.15, 1.20, 1.25, 1.30, or factor>
1.35), represented as a float. For any receiver, if the roll-
off factor is not provided, it will be assumed to be 1.2. In
cases where there are multiple Rx devices configured (see
'B' command), the roll-off factor will by default apply to
rxDevice =1, unless another rxDevice is specified (see
rxDevice parameter below).

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’

Receive Device (rxDevice)


In cases where there are multiple Rx devices configured rxDevice=<int device>
(see ‘B’ command), the modem may specify which of the
devices to use. If the device is not specified, it is assumed
to be ‘1’.

Example (default device, no roll-off specified):


H 1800.500 2100.500

Example (device 2, with roll-off specified):


H 1800.500 2100.500 rof=1.25 rxDevice=2
carrierType=service

Spectral Inversion specInv=<binary>,


Spectral Inversion is the means of indicating to the 1 = spectrally
antenna whether expected carrier is spectrally inverted or inverted,
not. 0 = no spectral
inversion

OpenAMIP™ Standard Version 1.17 9


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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.

If the ‘I’ command is sent to the antenna without any


parameters, the antenna is expected to respond with an ‘i’
response providing antenna information.
The antenna should respond with its own details, as
described in the ‘i’ command below.

(Optional key-value format parameters) (optional)

Modem Serial Number


A string containing the modem’s manufacture serial number. modemSerialNo=<string>

Modem SW Rev (modemSwRev) modemSwRev=<string>

Example:
I iDirect cx780 modemSerialNo=14758 modemSwRev=2.0

In addition to the keys defined above, vendor specific keys


may be defined, following this syntax:
<vendorname>:<keyname>
The vendor-defined key may be any valid data type (int,
float, string, char, binary).

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.

10 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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’).

NOTE: The Tx Enable parameter can be used to support a


power calibration mode, in which the final power amplifier
is disabled or terminated, but the preamplifier is still
enabled and capable of measuring RF power at the preamp.

(Optional key-value format parameters) (optional)

Network Status (networkStatus) networkStatus=<string


online status>
An indication of terminal’s status in the network
{online, offline}
{online, offline}

faultStatus=<string
Fault Status (faultStatus) fault status>
An indication of modem’s fault status {fault, ready} {fault, ready}

M BUC Mute. 1 txMuteState=<binary state>


Explicit Tx mute enable/disable. This command overrides (minimum)
any action taken by the antenna as a result of the ‘L x 0’ where
command (L command Tx Enable flag). 1 (muted)
or
Mute State (txMuteState) Indicates whether the antenna 0 (unmuted)
should mute (1 = enable) or unmute (0 = disable) the BUC.
{1, 0}
(optional)
(Optional key-value format parameters) muteTime=<float GPS
Execution Time (muteTime) seconds>

Time, in seconds since the GPS epoch, at which the Mute


command is expected to be complete.

When no time tag is added, or the execution time


specified has past, the command will be executed
immediately.

OpenAMIP™ Standard Version 1.17 11


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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

NOTE: The N command is intentionally redundant with the L


command; it is not intended to be the sole means of
preventing interference during tests.

This command overrides the F command, but should not


cause the antenna to lose the parameters previously
specified by { S, P, B, R, X, and H } or { O, P, B, R, X,
and H}.

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.

(Optional key-value format parameters) (optional)

Antenna Test Mode (antennaTestMode)


Used to differentiate between test modes that may be antennaTestMode=<string
mode>,
supported by the antenna. Stow and Park positions are
expected to be statically configured at commissioning. where ‘mode’ may be,
{reserved, stop, park,
stow}
Antenna test modes defined are
• Reserved
• Stop (current location)
• Park (predefined location)
• Stow (predefined location)

12 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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)

OpenAMIP™ Standard Version 1.17 13


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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. (…)

Command format with minimum set of parameters:


P <Rx Pol> <Tx Pol>

Command format with additional parameters:


P <Rx Pol> <Tx Pol> rx2=<Rx2 Pol> rx3=<Rx3 Pol> …
tx2=<Tx2 Pol> tx3=<Tx3 Pol>

Example: P L R rx2=R tx2=L


(Left (Rx), Right (Tx), Right (Rx2), Left (Tx2))

To query the polarization configuration options available,


see the ‘Y extCmd=getConfigP’ command and
corresponding ‘y’ response.

Q Reserved

14 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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.

Each regime name represents a different set of antenna


data.

Regulatory Regime (regulatoryRegime) regulatoryRegime=<string


String defining the regulatory regime to be applied. The name>
names defined below are not considered to be an exhaustive defined names,
list, additional regulatory regime names may be defined at {FCCGEO, FCCNGSO, ETSIGEO,
the discretion of antenna and modem vendors. ETSINGSO}

• FCCGEO
• FCCNGSO
• ETSIGEO
• ETSINGSO
(optional)
(Optional key value pairs)
reportingInterval=<int
Max ESD Reporting Interval (reportingInterval) seconds>

Interval (in seconds) at which the antenna should report


various metrics related to maximum ESD. These metrics are
reported by the antenna with the ‘q’ message. If this
parameter is omitted, the antenna will respond only once.

Regulatory Offsets (offset1, offset2, and so on). offset1=<float dB>


offset2=<float dB>
offset3=<float dB>
Offset to be applied to the resulting maxESD.
offset4=<float dB>
Multiple offsets (up to 5) are possible and are a way for the offset5=<float dB>
modem to set exclusions or amendments. Offsets are
specified in dB.
Example: R regulatoryRegime=FCCMEO
reportingInterval=2

OpenAMIP™ Standard Version 1.17 15


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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)

Transmit Device (txDevice) txDevice=<int>


In cases where there are multiple Tx devices available, the
modem should specify which one the parameters
commanded here apply to. If the device is not specified, it is
assumed to be ‘1’.

U Reserved

16 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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.

‘Supported commands’ should include both those the


modem may transmit to the antenna, and antenna
commands supported by the modem.

The modem spontaneously sends out the V/v upon


connection to the antenna. Also, after receiving an empty v
command the antenna, the modem sends out all V messages
again. There is no query mechanism for individual
commands.

Per supported command, one V message is sent out:

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

To indicate that the series of commands to the modem has


completed, the antenna sends this final key: end=1
V end=1

Examples:
Modem requests antenna to send commands supported
[Modem] V

Modem indicating commands it supports


[Modem] V A 1
[Modem] V B 2 rx2=1 tx2=1

Modem indicates it has completed sending command list to


antenna
[Modem] V end=1

OpenAMIP™ Standard Version 1.17 17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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.

(Optional key-value format parameters) (optional)

GPS Time (time)


time=<float GPS seconds>
Time in seconds since the GPS epoch.

UTC offset (utcOffset)


utcOffset=<int seconds>
Time difference (in seconds) between UTC time and GPS time.
utc + utcOffset = gps

Leap Second Notify (leapNotify)


Indicates if a leap second is upcoming.
Valid notifications are,
leapNotify=<string
notification>
noLeapSecond = No leap second upcoming

Where ‘notification’ may


lastMinOfDay61Sec = Last minute of day will have 61 seconds
(represented in UTC as 23:59:60) be,
{noLeapSecond,
lastMinOfDay59Sec = Last minute of day will have 59 seconds lastMinOfDay61Sec,
(UTC goes from 23:59:58 to 00:00:00) lastMinOfDay59Sec,
notInSync}
notInSync = Not in sync, indicates receiver did not get leap
second info yet, conversion to UTC is not possible

Clock Stratum (clockStratum) clockStratum=<int>


The number of hops required for the antenna to reach a valid
reference clock. Acceptable range is 1-16 with 1 denoting a direct
connection to a timing source and 16 denoting that the antenna is
not synchronized with a valid timing source.

18 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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.

The antenna vendor specifies the string. If the controller


does not need this command, the modem does not need to
send it, but the modem may send it anyway, in which case
the controller will ignore it.

NOTE: If ARINC 791 is supported, the ‘X’ message is


intended to support transfer of the block zone file.

OpenAMIP™ Standard Version 1.17 19


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

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

Additionally, a number of standard key-value pair commands are


defined below.
(Options)
(Optional key-value format parameters) extCmd=<string cmd>,
extCmd indicates to the antenna that it is to provide the modem
with further information. The type of information requested is where cmd is one of
specified by parameter.
{getConfigB,
getConfigP,
getConfigB. Get Tx/Rx band Information (getConfigB)
getExtAntStatus,
Retrieve the Tx and Rx band capabilities from the Antenna
getExtTransceiverStatus}

getConfigP Get Polarization Information (getConfigP)


Retrieve the Polarization capabilities of the Tx/Rx equipment from
the Antenna.

getExtAntStatus. Get Extended Antenna Status (getExtAntStatus).


Retrieve the extended ACU status string from the antenna.

getExtTransceiverStatus. Get Extended Transceiver status


information from the antenna.

extCmdRepeatInterval indicates the repeat interval at which the extCmdRepeatInterval=<int


antenna is to repeat the information. ‘0’ indicates that the seconds>
information is only to be sent once. If this parameter is not
specified, it is assumed to be ‘0’.

Modem Restart Reason (restartReason)


Inform ACU of a pending reboot (SW updates, config file updates, restartReason=<string
and so on). reason>,
where ‘reason’ may be,
restartReason codes: {noRestart,
{noRestart, modemSwUpdate,
modemSwUpdate, modemConfigUpdate,
modemConfigUpdate, mdoemReboot,
modemReboot, modemSwRestart}
modemSwRestart

maxOutageDuration=<int
Maximum Outage Duration (maxOutageDuration)
seconds>
The maximum duration expected for the reboot outage, specified in
seconds.

20 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (M)

Table 2-1. Message Types, Sender (M) (continued)

No. of
Type Description Name of the Parameters
Parameter(s)
Z Reserved

OpenAMIP™ Standard Version 1.17 21


T0000682 | Rev F
Message Types, Sender (A)

2.4 Message Types, Sender (A)


Table 2-2. Message Types, Sender (A)

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

c conical scan setup (optional) 5 float1 -AZ: see drawing,


Sent when conical scan performed. The four floating float2 +EL: see drawing,
point values represent the times (UTC or GPS epochal) of float3 +AZ: see drawing,
beam steering excursions from the previously steered
float4 -EL: see drawing, and
coordinates.
int reporting rate in Hertz for
“c” message
Azimuth and elevation delta scan excursions are pre-
determined by the antenna manufacturer and would be
on the order of ±0.25°.

The antenna may request periodic carrier-to-noise


estimates ("c" message) by setting the fifth parameter.
Default "C" message rate is zero (if "c" message reporting
rate parameter is not present, the "C" message is
disabled).

NOTE: Some terminal implementations will use only


the fifth parameter of this message; in that case, the
first four parameters may be set to zero, or may
optionally be set to describe the intended scan timing.

d-f Reserved

22 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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

binary Modem May Transmit


“Modem must not transmit" means that the antenna has detected a
condition (loss of lock, blockage, cable unwrap, max skew exceeded) 1 – Modem may transmit
that does not require a reconfiguration, but that does require the 0 – Modem must not transmit
modem to cease transmission.
int Search Count 0
The third parameter should be set to 0. (Search Count is not relevant (Always set to 0)
when validating configuration commands).
binary Tx Disabled: antenna
The fourth parameter ‘Tx Disabled’ should be set to 0. If an F command (1 - has, 0 - has not) successfully disabled
was sent more recently than an N command. If omitted, this parameter is transmission toward the geosynchronous
assumed to be 0. arc (response to N command). If this
parameter is "1" antenna is in a state to
NOTE: If the antenna cannot ensure it is ready for a transmitter test support installation tests such as power
without regulatory violation, the fourth parameter should be set to 0. measurements; any power from the
transmitter test is either terminated in a
dummy load or otherwise prevented from
interfering with satellites.
The optional fifth parameter is an enumerated detailed status of the
current antenna selected. (See Table 2-3, Enumerated Antenna Status
Codes.) int antenna_status 0 to
65535

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)

Time before Blockage (blockTime)


blockTime=<int sec>
This parameter should accompany status message 18, warning of an
impending blockage. blockTime indicates the number of seconds
remaining before the blockage is expected to occur. If the ‘G’ command
was sent with an execution time specified, the blockTime will be
reported relative to that execution time.

Additional Antenna Status (statusCode)


If there are additional status messages from the selected antenna, statusCode=<int 0 to 65535>
beyond that communicated in the fifth parameter above, each additional
status message is transmitted as an individual key-value pair.
Example:
g 1 1 0 0 0 0 0 statusCode=20

h Reserved

OpenAMIP™ Standard Version 1.17 23


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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.

If the ‘i’ command is sent to the modem without any


parameters, the modem is expected to respond with an
‘I’ response providing modem information.

(Optional key value pairs) (Optional)

RF Terminal Type (rfTermType). rfTermType=<int>

An integer identifying the RF Terminal Type assigned by


the network operator’s type approval process.
Range 1 to 32767.

Antenna Serial Number (antennaSerialNo) antennaSerialNo=<string>

Antenna SW Rev (antennaSwRev) antennaSwRev=<string>

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

24 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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

Bandwidth Units (bandUnits)


Units of bandwidth for which the regulatory limit applies, that
is, 40kHz, 400kHz, 1000kHz (1Mhz). If not specified, it is bandUnits=<int kHz>
assumed that units of bandwidth is 1000kHz(1MHz)

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)

Transceiver Temperature (transceiverTemperature) transceiverTemperature=<fl


oat degrees>
Transceiver temperature, required for accurately determining
transceiver gain. Temperature is specified in degrees Celcius.

OpenAMIP™ Standard Version 1.17 25


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

No. of
Type Description Name of the Parameters
Parameter(s)
Transceiver Power (transceiverPower) transceiverPower=<float
Transceiver power detector reading, in dB. dB>

Antenna Azimuth (antennaAz)


Azimuth. Useful for determining the radome loss, if not antennaAz=<float degrees>
constant, in degrees.
Antenna Elevation (antennaEl)
antennaEl=<float degrees>
Elevation. Useful for determining radome loss, if not constant,
in degrees.

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)

26 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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.

"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).
Binary Modem May Transmit
“Modem must not transmit" means that the antenna has
1 – Modem may transmit
detected a condition (loss of lock, blockage, cable unwrap, max
skew exceeded) that does not require a reconfiguration, but 0 – Modem must not transmit
that does require the modem to cease transmission. This flag
should not be set as a result of L (that is, L 0 1 or L 1 1) or M
(that is, M txMuteState=1) or C (4th parameter set to '1',
indicating loss of lock) messages sent from the modem: it
should be solely based on other Antenna considerations.
Int Search Count
The third parameter ‘Search Count’ is the number of full
sweeps the antenna has performed while searching for the
satellite. It should be set to 0 upon receipt of an F command,
and incremented when the antenna has performed a full sweep
for the satellite. If omitted, this parameter is assumed to be 0.
This parameter should be zero if an N command is more recent
binary Tx Disabled: antenna
than an F command.
(1 - has, 0 - has not) successfully
disabled transmission toward the
(Optional)
geosynchronous arc (response to N
The optional fourth parameter ‘Tx Disabled’ should be set to 0
if an F command was sent more recently than an N command. command). If this parameter is "1"
antenna is in a state to support
If omitted, this parameter is assumed to be 0.
installation tests such as power
measurements; any power from the
NOTE: If the antenna cannot ensure it is ready for a transmitter transmitter test is terminated in a
test without regulatory violation, the fourth parameter should dummy load or otherwise prevented
be set to 0. from interfering with satellites.

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)

OpenAMIP™ Standard Version 1.17 27


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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)

(Optional key value pairs)

Time to Blockage (blockTime) blockTime=<int sec>


This parameter should accompany status message 18, warning
of an impending blockage. BlockTime indicates the number of
seconds remaining before the blockage is expected to occur.

Additional Antenna Status (statusCode) statusCode=<int 0 to 65535>


If there are additional status messages from the selected
antenna, beyond that communicated in the fifth parameter
above, each additional status message is transmitted as an
individual key-value pair.

t Reserved

u Reserved

28 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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.

‘Supported commands’ should include both those the


antenna may transmit to the modem, and modem
commands supported by the antenna.

The antenna spontaneously sends out the v upon


connection to the modem. Also, after receiving an
empty V command form the modem, the antenna
sends out all v messages again. There is no query
mechanism for individual commands.

Per supported command, one v message is sent out:


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

To indicate that the series of commands to the modem


has completed, the antenna sends this final key:
end=1
v end=1

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

OpenAMIP™ Standard Version 1.17 29


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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)

Clock Stratum (clockStratum) (optional)


The number of hops required for the antenna to reach a valid clockStratum=<int 1-16>
reference clock. Acceptable range is 1-16 with 1 denoting a
direct connection to a timing source and 16 denoting that the
antenna is not synchronized with a valid timing source.
UTC offset (utcOffset)
Time difference (in seconds) between UTC time and GPS time. utcOffset=<int seconds>
UTC + UTCOffset = GPS

Leap Second Notify (leapNotify)


leapNotify=<string
Indicates if a leap second is upcoming.
notification>
Valid notifications are,
noLeapSecond = No leap second upcoming
where ‘notification’ may be,
lastMinOfDay61Sec = Last minute of day will have 61 {noLeapSecond,
seconds (represented in UTC as 23:59:60) lastMinOfDay61Sec,
lastMinOfDay59Sec,
lastMinOfDay59Sec = Last minute of day will have 59 notInSync}
seconds (UTC goes from 23:59:58 to 00:00:00)

notInSync = Not in sync, indicates receiver did not get leap


second info yet, conversion to UTC is not possible

30 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

No. of
Type Description Name of the Parameters
Parameter(s)
x Reserved

y Key, value pair formatted string used to respond to ‘Y’ 1 String


messages sent to the modem, or to asynchronously send
(minimum)
message to the modem.
replyTo=<string extCmd>,
where cmd is one of
Vendor specific commands may be used here, as long as they
are prefixed with a vendor key (as described in the ‘I’/’i’ {getConfigB,
commands). getConfigP,
getExtAntStatus,
(Optional key-value format parameters) getExtTransceiverStatus}
replyTo is the response to information requests sent with ‘Y
extCmd’ key. It identifies the request being responded to, and
subsequent expected key-value pairs.

The set of valid responses matches the set of requests


specified in the ‘YextCmd’ key, namely
{getConfigB, getConfigP, getExtAntStatus
getExtTransceiverStatus}

getConfigB response rx1Band1LO=<float freq MHz>


In response to ‘Y’ command with the request getConfigB, the
rx1Band1Start=<float freq MHz>
antenna will respond with information about available Tx and
Rx bands. rx1Band1Stop=<float freq MHz>
rx1Band1Inv=<binary>
rx1Band1Active=<binary>
The prefixes (that is, rx2, rx3, tx2, and so on) used in the ‘y’
response should be used when the modem later specifies a (…)
configuration with ‘B’ command. rx1Band2LO=<float freq MHz>
rx1Band2Start=<float freq MHz>
rx1Band2Stop=<float freq MHz>
For each band, the following parameters are provided:
rx1Band2Inv=<binary>
rx1Band2Active=<binary>
rx(N)Band(M)LO: float LO frequency MHz
(…)
tx1Band1LO=<float freq MHz>
rx(N)Band(M)Start: float, Band Start frequency MHz tx1Band1Start=<float freq MHz>
tx1Band1Stop=<float freq MHz>
rx(N)Band(M)Stop: float, Band Stop frequency Mhz tx1Band1Inv=<binary>
tx1Band1Active=<binary>

rx(N)Band(M)Inv: binary, Spectral Inversion flag (…)

1 = LO is above the Tx or Rx (inverted), or


0 = LO is below the Tx or Rx (not-inverted)
If the inversion key is omitted, the spectrum is assumed to not
be inverted (0).

OpenAMIP™ Standard Version 1.17 31


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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)

Response format with minimum set of parameters:


y replyTo=getConfigB rx1Band1LO=<float freq MHz>
rx1Band1Start=<float freq MHz> rx1Band1Stop=<float freq MHz>
tx1Band1LO=<float freq MHz> tx1Band1Start=<float freq MHz>
tx1Band1Stop=<float freq MHz>

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

getConfigP response rx1PolOpts=


In response to ‘Y’ command with the request getConfigP, the <string L, R, H, V, and/or
Antenna will respond with a string indicating the supported X | C>
polarization settings for TX and RX (L,R,H,V). tx1PolOpts=
<string L, R, H, V, and/or
The ‘X’ setting indicates that only cross-pol configurations are X | C>
supported (Rx and Tx must be opposite polarities). (…)

The ‘C’ setting indicates that only co-pol configuarions are


supported (Rx and Tx must be the same polarity).

Note that ‘X’ and ‘C’ settings are mutually exclusive.

rx(N) applies to receiver N.


tx(N) applies to transmitter N.

rx(N)PolOpts
tx(N)PolOpts

String describing which polarization options are available on


this band: (L,R,H, V, and/or X)
rx(N)PolActive
tx(N)PolActive

String describing which polarization is active (L, R, H or V) rx1PolActive=<string L. R. H


The response p provides the information in the following form: or V>
[Modem] Y tx1PolActive=<string L, R, H
[Antenna] y rx1PolOpts=LRHV rx1PolActive=V or V>
tx1PolOpts=LR tx1PolActive=R (…)

32 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Message Types, Sender (A)

Table 2-2. Message Types, Sender (A) (continued)

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

See Appendix A, Extended Antenna


Extended Antenna Status (extAntStatus) response Status on page 45
Extended Transceiver Status (extTransceiverStatus) response
When requested by the Modem with Y command
(‘Y extCmd=getExtAntStatus’ or
‘extCmd=getExtTransceiverStatus’), the antenna may respond
with a set of vendor specific metrics providing additional
antenna status metrics.

These metrics are reported in key-value pair format.The


information is provided for logging purposes, and the modem is
not expected to act on this information.
A dictionary of suggested parameters are provided in Appendix
A, but ultimately the reported metrics are left to the antenna
vendor.

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)

Add ability for ACU to instruct modem to enable/disable use of


signaling carriers. where ‘status’ may be,
{disable, enable}
sigCarriersEnable=<string>
{disable, enable}

z Reserved

OpenAMIP™ Standard Version 1.17 33


T0000682 | Rev F
Antenna Status Codes

2.5 Antenna Status Codes


This displays the enumerated antenna status codes.

Table 2-3. Enumerated Antenna Status Codes

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

34 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Antenna Status Codes

Table 2-3. Enumerated Antenna Status Codes

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

OpenAMIP™ Standard Version 1.17 35


T0000682 | Rev F
Physical Layer

2.6 Physical Layer


2.6.1 TCP Interface
A modem and controller may communicate using TCP. The method of discovering the IP
address and TCP port is outside the scope of OpenAMIP. In the reference implementation, the
antenna listens on a configured TCP port and accepts calls from a configured (range of)
modem IP addresses. The modem initiates a TCP connection to a configured antenna IP
address and TCP port.
Whenever the TCP connection is disconnected, the antenna sets its keep-alive timers to
infinity. When a new TCP connection is established, the modem will send an ‘A’ to the
antenna, and the antenna will send an 'a' to the modem. Typically each side will then set a
disconnect timer to three times the requested interval. For example, the modem might send
"A 3" and set its disconnect timer to 9 seconds. If at any time after that, the modem waits
more than 9 seconds to receive an "s" message, the modem will break the TCP connection. It
may then choose to periodically (or at random intervals) attempt to make a new TCP
connection. Similarly, the antenna might send "a 2" and then break the connection if it must
wait more than 6 seconds between received "L" messages.
Neither the antenna nor the modem is obliged to accept more than one TCP connection at a
time, but this is not prohibited. In a system with two modems, one may be acting as a backup.
In this arrangement, the antenna should only honor satellite selection requests from one
modem.
TCP is a "stream-oriented" protocol: there is no particular mapping of an OpenAMIP message
into an IP packet. A single packet may contain a fragment of a message, a complete message,
or multiple messages. In the reference implementation, the modem sends an entire initial set
of seven messages in a single POSIX "write" command immediately after opening the
connection. On most POSIX systems, this will result in a single TCP/IP packet. The reference
receiver implementation accumulates characters until a 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.

2.6.2 UDP Interface


Each message fits in a single UDP packet. A packet may contain more than one message, but
any given message must be fully contained within one packet. The antenna has a configured
IP address and well-known port, as does the modem. The initial state of the OpenAMIP
interface is "idle" (that is, no keepalive) until the partner sends a keepalive timer. The
interface reverts to the "idle" state if three keepalives are missed.
In Version 1.9, the modem may create a UDP stream for the "C" message, alongside the
primary TCP connection for all other OpenAMIP messages. Because the "C" message will be
sent at a relatively high rate (tens of Hertz), the UDP stream is more practical; it avoids TCP
handshaking overhead. It is recommended that the modem and antenna use the same IP
address and port for both TCP and UDP connections, although this is not mandatory. Because
TCP and UDP use separate address spaces, this does not cause any conflict.

36 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Semantics

2.6.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. (Note that a
checksum should be used here.)

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.

OpenAMIP™ Standard Version 1.17 37


T0000682 | Rev F
Semantics

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.

38 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Examples

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.

2.8.1 Messages from Modem to Antenna Controller


"Keepalive" messages are sent to the modem regularly to ensure that communications
connectivity with the controller are not lost.
A 10 # Alive: Antenna should resend status "s" every N seconds.
B 18000.500 28000.500 rx2=18200 rx3=18500.750 tx2=28000.625
tx3=28000.750 # “Beat Frequency” for installation with 3 LNBs and 3
BUCs
E 0.5 # Expected power: Maximum L-band Tx power to be expected at the
antenna, in dBm.
F time=1293537618 # execute F on Jan 1 2021 12:00 AM UTC
G # Use the recent S/O, P, B, R, X and H parameters to indicate whether
blockage will result. Expect ‘g’ response from antenna with result.
G time=1293537618 # Same as above, except antenna will report on whether
antenna will be blocked at time=1293537618. Expect ‘g’ response with result.
H 1123.321 0.256 rof=1.05# Hunt: floating point center frequency and
bandwidth in MHz.

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.

OpenAMIP™ Standard Version 1.17 39


T0000682 | Rev F
Examples

N antennaTestMode=stow # Non Track Test mode.. No transmission. The


antenna should be placed in a state to aimed away from the
geosynchronous arc. This is intended to support installation tests such
as power measurements. An optional antennaTestMode may be specified.
O 1 25544U 98067A 08264.51782528 -.00002182 00000-0 -11606-4 0 2927 2
25544 51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537 ISS
(ZARYA) #TLE string including the Title Line (Satellite Name)
P L R #Polarization: H, V, L or R for Rx and Tx, respectively.
P L R rx2=R tx2=L #Polarization: system with multiple Rx and/or Tx
devices.
R regulatoryRegime=FCCMEO reportingInterval=2 #Regulatory Regime:
Modem informs antenna that FCC MEO Tx ESD limits apply, requests
antenna to report values required to adjust power every 2 seconds.
Antenna reports those values back via the ‘q’ message.
S -20.1 1.0 3.5 # GEO Satellite longitude: All parameters are floating
point degrees, "-" is West. Wander in latitude is 1.0. Polarization
skew 3.5.
T 1450 4.5 # Transmit frequency: The modem intends to transmit at this
L-Band frequency and bandwidth.
V B 2 rx2=1 tx2=1 # Command supported: Modem indicates to Antenna that
it supports the ‘B’ command, with two unnamed parameters along with the
keys identified, rx2 and tx2.

The modem requests periodic location information:


W 1 # Where: Antenna should send "w" location report every N seconds.
X nid=1234 # Xtra string: vendor-specific string for antenna
controller.
Y extCmd=getConfigB #Modem requests the Antenna send BUC and LNB
configuration options. Antenna responds with ‘y replyTo=getConfigB’,
followed by configuration information.
Y extCmd=getConfigP #Modem requests the Antenna send Polarization
configuration options. Antenna responds with ‘y replyTo=getConfigP’,
followed by configuration information.

40 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Examples

2.8.2 Messages from Antenna Controller to Modem


The controller must be able to provide status information to the modem such as, when it is
locked onto the satellite, when it is functional and unblocked, how many attempts has it
made to search for the satellite and (for installation support) when it is in a safe state for
dummy transmission measurements. The controller sends an "s" message immediately after
receiving an "F" message, and periodically at the interval defined by the "A" message:
a 60 # alive: modem should send keepalive messages every N seconds.
c 0.25 0.25 0.33 0.33 # conical scan setup: not supported by iDirect;
included as a placeholder for compatibility with other vendors'
systems.
g 1 1 0 0 18 blockTime=120 #In response to a configuration check
specified by ‘G’ command, the antenna responds that in 120 seconds it
will be in blockage. In this example, only the optional 5th parameter
is used.
i YoyoDyne 1234 antennaSerialNo=13478 # ID command: antenna controller
manufacturer, type, and serial number strings
q esdMax=23.1 gt=4.6 eirp=17.0 bandUnits=400 skewAngle=15.0
transceiverTemperature=45.3 transceiverPower=14.2 antennaAz=30.2
antennaEl=50.3 #Response from antenna to information requested in ‘R’
message, to be used by the modem in properly adjusting its output power
to remain within regulatory compliance
r 10 B # reference frequency required for BUC and LNB.
s 1 1 1 0 # s: four parameters: functional, OK-to-transmit, searched
once, not in transmitter test mode.

s 1 1 1 0 18 blockTime=45 # s: functional (1), OK-to-transmit (1),


searched once (1), not in test mode (0), but a blockage is imminent
(18) in 45 seconds (blockTime=45)

s 0 0 1 0 11 statusCode=12 StatusCode=25 # s with multiple errors


detected: antenna not functional (0), modem transmit is not permitted
(0), searched once (1), not in test mode (0), LNB Voltage Error (11),
BUC Voltage Error (statusCode=12), and Motor Error (statusCode=25)
detected.

The antenna controller sends GPS information to the modem:


w 1 -10.123 20.235 123456789 10000 91.0 223.52 0.10 -0.51 91.0 # where:
location report. valid, lat, lon, time, altitude, heading, speed,
pitch, roll, yaw.

OpenAMIP™ Standard Version 1.17 41


T0000682 | Rev F
Examples

The "w" message parameters require more explanation:


• Valid (1) or invalid (0)
• Latitude in floating point degrees (South is negative)
• Longitude in floating point degrees (West is negative)
• GPS time in seconds; if the antenna does not have GPS time, set this to zero
• Altitude, heading, speed, pitch, roll, yaw are not physically required for system
operation, but support logging for regulatory compliance and system performance
management

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.

42 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Version Compatibility

3 Compatibility

This chapter contains the following sections:


• Version Compatibility on page 43
• Modified OpenAMIP on page 44
• Hardware Compatibility on page 44

3.1 Version Compatibility


New versions of the OpenAMIP protocol may be published. New versions will be strict
supersets of older versions and may extend the protocol in only two ways:
• A new version may add new message types
• A new version may add new parameters to the end of an existing message type
Do not use any other syntactic extensions. 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. A compliant implementation of OpenAMIP must
ignore any unexpected message type that it receives, and must ignore any unexpected
parameters at the end of a message. 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 will use if a
message does not provide the parameter.
New versions of the protocol are required to be backward-compatible with older versions.
This is ensured by requiring that the meanings of parameters never change from version to
version. New parameters may be added to a message, and new messages may be added. The
receiver is required to ignore extra parameters and unknown messages; this allows an older
receiver version to work with a newer sender. The receiver is required 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), but the older version will continue to provide
its functionality when operating with a partner that is using a newer version.

OpenAMIP™ Standard Version 1.17 43


T0000682 | Rev F
Modified OpenAMIP

3.2 Modified OpenAMIP


Any antenna or modem manufacturer can extend the protocol by creating an extended type
field. The extended type field consists of the manufacturer's name (with no spaces) followed
by a colon, followed by a type (with no spaces). If a modem or antenna controller receives a
message of unknown type, the modem or antenna controller will ignore the message. If the
messages are optional for operation of the equipment, then the protocol still qualifies as
"unmodified" OpenAMIP. If the messages must be used for a particular antenna or modem,
then the resulting implementation must be called "modified OpenAMIP".
Examples:
Yoyodyne:NID 1132 # additional search parameter
iDirect:stow 1 # command specified by iDirect

3.3 Hardware Compatibility


OpenAMIP is intended for a typical installation with a specific modem and a specific antenna
are installed and configured to work together. These are installation issues and the protocol
was developed to focus on operations. It is the responsibility of the installer to assure that the
parameters are compatible. Essentially all incompatibilities will cause loss of service and the
need for intervention, so the mechanisms needed for auto-negotiation have no practical
benefit. The obvious examples of incompatibilities occur in the "P", "H", and "B" commands.
An antenna that is mechanically configured for LHCP and that has no polarization switch
hardware will not operate correctly for RHCP or linear polarization. Similarly, an antenna with
a mechanical polarizer will not be able to select Tx polarization independently from Rx
polarization. Similarly, an antenna whose downconversion offset frequency ("LNB local
oscillator") is fixed cannot implement a B command to change to another frequency, and more
generally an antenna with a selectable downconversion frequency can only change to one of a
small set of downconversion frequencies. Finally, an antenna whose tracking receiver supports
a specific set of (one or more) bandwidths cannot select an arbitrary hunt bandwidth. It is the
responsibility of the installer to ensure that the modem does not send parameters that the
antenna does not support. For the hunt bandwidth, the antenna may choose to operate with a
different hunt bandwidth. Do not operate the antenna for other unsupported "P", "B", and "H"
parameters. When the antenna does not have a controllable down conversion frequency, the
antenna may choose to ignore the "B" command. The modem may choose to not send the B
command.

44 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
Appendix A Extended
Antenna Status

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

OpenAMIP™ Standard Version 1.17 45


T0000682 | Rev F
getExtAntStatus Responses

Example,
[Modem] Y extCmd=getExtTransceiverStatus
[Antenna] y replyTo=getExtTransceiverStatus txState=ok
bucLatchedFault={externalReferenceFault} bucTemp=55.50 bucLOSetting=27500
lnbState=OK

A.1 getExtAntStatus Responses


Status parameters related to the status of the antenna.

A.1.1 Hardware
Table A-1. Antenna: Hardware

Parameter Description Data Type


antMan Antenna Manufacturer string
antPN Manufacturer Part Number (P/N) string
antSN Manufacturers Serial Number (S/N) string
antID ID / hostname assigned to the antenna string
antSW Software Version of the Antenna string

A.1.2 Dynamic Operating Data


Table A-2. Antenna: Dynamic Operating Data

Parameter Description Units (Type/Format)


trkLevel Tracking receiver level / RSSI / AGC. dBm (float, +/-nnn.nn)
Signal level reported by the ACU tracking receiver -999.99 to +999.99
antAbsAz Antenna Absolute Azimuth Angle. degrees (float, nnn.nn)
Current azimuth angle of the antenna 000.00 to 360.00
antAbsEl Antenna Absolute Elevation Angle. degrees (float, +/-nnn.nn)
Current elevation angle of the antenna -90.00 to +90.00
antAbsCL Antenna Absolute Cross-Level Angle. degrees (float, +/-nnn.nn)
Current cross-level angle of the antenna -90.00 to +90.00
antRltAz Antenna Relative Azimuth Angle. degrees (float, nnn.nn)
Current antenna azimuth angle relative to the vessel 000.00 to 360.00
heading

46 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
getExtAntStatus Responses

Table A-2. Antenna: Dynamic Operating Data

Parameter Description Units (Type/Format)


antTrgAz Antenna Target Azimuth Angle. degrees (float, nnn.nn)
Calculated azimuth target angle 000.00 to 360.00
antTrgEl Antenna Target Elevation Angle. degrees (float, +/-nnn.nn)
The calculated elevation target angle -90.00 to +90.00
antErrAz Antenna Azimuth Error degrees (float +/- nnn.nn)
Error between absolute and target angle -360.00 to +360.00
antErrEl Antenna Elevation Error degrees (float, +/-nnn.nn)
Error between absolute and target angle -90.00 to +90.00
stOffset Step Track Offset. degrees (list {float -Az,
Step-track delta angles (consistent with data from +El, +Az, -El})
conical scan 'c' from antenna) {+/-nn.nn, +/-nn.nn, +/-
nn.nn, +/-nn.nn}
each float: -99.99 to
+99.99

antMD Antenna Mode. string


Operating mode of the antenna
Defined options:
{manual,
search,
acquiring,
peaking,
tracking,
stop,
park,
stow,
standby,
maintenance,
calibrating,
fault}
or custom string

OpenAMIP™ Standard Version 1.17 47


T0000682 | Rev F
getExtAntStatus Responses

Table A-2. Antenna: Dynamic Operating Data

Parameter Description Units (Type/Format)


trkMD Tracking Mode. string
Tracking mode of the antenna
Defined options:
{stepTrack,
programTrack,
autoTrack,
conicalScan}
or custom string
antStatus Antenna Status. list {string}
Any faults or conditions that are present with the ({status-1,status-2, …
antenna. status-n})

Defined options:
{ok,
blocked,
solarOutage,
stabilisationError,
motorError,
encoderError,
sensorError,
acuCommsError,
powerError,
antennaOutOfCalibration,
bucError,
lnbError}
or custom string

48 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
getExtAntStatus Responses

A.1.3 Configuration
Table A-3. Antenna: Configuration

Parameter Description Data Type


trgSatPos Target Satellite Position. degrees (float, +/-nnn.nn)
Longitude of the current target -180.00 to +180.00
orbitType Orbit Type. string
LEO / MEO / GEO Defined orbits:
{leo,
meo,
geo}
or custom string
txFeedPolSetting Transmit Feed Polarization Setting string
Vertical / Horizontal / RHCP /LHCP Defined options {L, R, V, H}
rxFeedPolSetting Receive Feed Polarization Setting string
Vertical / Horizontal / RHCP /LHCP Defined options {L, R, V, H}
satSkew Satellite Skew degrees (float, +/-nnn.nn)
Inherent skew angle of the satellite -180.00 to +180.00

trkFreq Tracking Receiver Frequency MHz (float, nnnn.nnnn)


Receive tracking carrier frequency (L-band) 0000.0000 to 3000.0000

trkBW Tracking Receiver Bandwidth MHz (float, nnn.nn)


Receive tracking carrier bandwidth 000.00 to 999.99
rfBand RF Band string
For multi-band antennas (C/Ku/Ka) Defined options {C, Ku, Ka, X}
or Custom string
tleStatus TLE File Status. String
TLE file / data state (good, bad)
Defined options:
{ok,
invalid,
none}
or custom string
satID Satellite ID. string
Current tracking satellite ID

OpenAMIP™ Standard Version 1.17 49


T0000682 | Rev F
getExtAntStatus Responses

A.1.4 Geolocation, Movement, Time


Table A-4. Antenna: Geolocation, Movement, Time

Parameter Description Data Type


lat Terminal Latitude (-ve is south) degrees (float, +/-nn.nnnn)
-90.0000 to +90.0000
long Terminal Longitude (-ve is west) degrees (float, +/-nnn.nnnn)
-180.0000 to +180.0000
alt Terminal Altitude metres (int, +/-nnnnn)
-99999 to +99999
speed Terminal Speed metres/sec (float, nnn.nn)
000.00 to 999.99
heading Heading degrees (float, nnn.nn)
Terminal movement direction relative to North 0.00 to 360.00
time GPS Time seconds (integer, nnnnnnnnnn)
0 to 9999999999
roll Terminal Roll degrees (float, +/-nn.nn)
-90.00 to +90.00
pitch Terminal Pitch degrees (float, +/-nn.nn)
-90.00 to +90.00
yaw Terminal Yaw degrees (float, +/-nnn.nn)
-180.00 to +180.00

50 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
getExtTransceiverStatus Responses

A.2 getExtTransceiverStatus Responses


Status parameters related to the status of the transceiver.

A.2.1 Transceiver
Table A-5. Transceiver

Parameter Description Data Type


txState BUC / Transmitter status list {string} ({status-1,status-2, …
This should include any faults or conditions status-n})
that are present with the BUC
Defined options:
{ok,
transmitterOn,
externalMute,
mute,
externalReferenceFault,
highForwardPowerFault,
lowForwardPowerFault,
internalFault,
overTemperatureFault,
fanFault,
noConnection}
or custom string
bucLatchedFault BUC / Transmitter Latched Fault list {string} ({fault-1,fault-2, …
Latched faults within the BUC fault-n})

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

OpenAMIP™ Standard Version 1.17 51


T0000682 | Rev F
getExtTransceiverStatus Responses

Table A-5. Transceiver

Parameter Description Data Type


bucInputPower BUC / Transmitter input power (if supported) dBm (float, +/-nn.nn)
-99.99 to +99.99

bucAtt BUC / Transmitter attenuation setting dB (float, nn.nn)


00.00 to 99.99
bucTemp BUC / Transceiver Temperature degrees Celcius (float, +/-nnn.nn)
-999.99 to 999.99

bucFanSpeed BUC / Transceiver Fan Speed Revolutions per minute (integer


nnnnnn)
0 to 999999
lnbState This should include any faults or conditions list {string} ({status-1,status-2, …
that are present with the LNB status-n})

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

52 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
getExtTransceiverStatus Responses

Table A-5. Transceiver

Parameter Description Data Type


lnbLOSetting LNB Local Oscillator Setting MHz (integer, nnnnn)
Receive Local Oscillator frequency 00000 to 99999
configuration
bucLOSetting BUC Local Oscillator Setting MHz (integer, nnnnn)
Transmit Local Oscillator frequency 00000 to 99999
configuration
bucMan Transceiver Manufacturer string
The BUC manufacturer custom string
bucPN BUC/Transceiver Part Number string
The manufacturer part number custom string

bucSN BUC/Transceiver Serial Number string


The manufacturers SN for the BUC custom string

bucID BUC/Transceiver ID string


ID / hostname assigned to the BUC custom string
bucIFFilter BUC IF Lowpass Harmonic filter setting string
get the BUC IF lowpass harmonic filter setting
Defined options:
{lowband,
gpio_0,
serial_0,
tone_1}
bucSW BUC/Transceiver SW Version string
get the current software version
bucADC BUC/Transceiver Forward Power ADC string
Get the ADC reading from the power sensor {string, 3 characters, each 0 to F}
ASCII representation of hex values
from Analog-to-Digital converter
000 to FFF
bucPol Transceiver Tx Polarization. String
Where a BUC / transceiver has an integrated Defined options {L, R, V, H}
transmit polarization switch
lnbPol Transceiver Rx Polarization. String
Where a transceiver has an integrated receive Defined options {L, R, V, H}
polarization switch

OpenAMIP™ Standard Version 1.17 53


T0000682 | Rev F
getExtTransceiverStatus Responses

54 OpenAMIP™ Standard Version 1.17


T0000682 | Rev F
ST Engineering iDirect
13861 Sunrise Valley Drive, Suite 300
Herndon, VA 20171-6126
+1 703.648.8000
+1 866.345.0983
www.idirect.net

You might also like