AVS3022 API Verison 1.01

The AVS3022 Control API would be used by user software to control the AVS-3022 system.

Changes since Version 1.00

Added CH0ECTXT, CH1ECTXT, CH2ECTXT, CH3ECTXT parameter groups or external context packets

Requirements

Simple & Lightweight: The overhead for implementing the protocol should be small.
Human Readable: What goes over the wire doesn’t have to be directly human readable, but there should be a standard human readable representation that can be displayed.
Extendable: Should be able to add new commands or parameters without breaking out of date client or server.
Widely supported: The protocol should use existing facilities available in scripting languages such as Python.
Transport Agnostic: The command and control protocol should be able to use a variety of transports. UDP, TCP, ZeroMQ, Local Sockets/Named Pipes, etc…
Stability: Implementation of the API should be robust and tolerate improperly formatted requests.

JSON (json.org)

Javascript Object Notation (JSON) is a lightweight data-interchange format. The EMCA-404 is a standard that defines JSON.

JSON meets the requirements listed above. JSON is widely supported on in multiple programming and scripting languages.

Data Types

The following are all possible data types in JSON.

String: One or more Unicode characters
Number: Any integer or floating point number
Boolean: true or false
Null: Presents the absence of a value
Array: Ordered collection of values
Map: Unordered name-value pairs, where name is a string.

Newline delimited JSON provides a specification for streaming JSON Objects. The idea is that the JSON of each message is in compact form (no line feeds). Each object is then separated by a LF (new line).

NDJSON could be used for JSON implementation over TCP, named pipes or any streaming interface.

Control API Design

The AVS API provides the ability to control and configure Avid systems. This is done via a request (REQ) and response (RSP). The REQ consists of a command and parameters. The RSP contains whether the REQ succeeded, error information and return values.

The REQ is encoded and sent via a transport to the system. Typically the encoding will be JSON and the transport will be TCP.

The RSP will be received over the same transport as the REQ and encoded in the same manner.

JSON encoded REQ/RSP are encoded in compact JSON, which means there are no line feeds (LF) or carriage returns(CR). For streaming transports such as TCP, line feeds (*LF) are used separate messages as described by NDJSON

REQ

The client creates a JSON message known as a request (REQ). The REQ is a JSON list. The first element in the list is always the command string. Optionally the second element is used as the command parameter(s).

Format:

[ "CMD", ARG ]

CMD: String for REQ command
ARG: Optional command argument (Any valid JSON value)

The following is a list of possible formats used for API requests:

[ "CMD" ]
[ "CMD", {} ]
[ "CMD", { "param1":value1, "param2":value2} ]
[ "CMD", [] ]
[ "CMD", [value1,value2] ]
[ "CMD", value1 ]

CMD: String for REQ command
paramN: String for command parameter name
valueN: JSON value for command parameter

RSP

The response (RSP) message is a JSON message that represents the results of the previous REQ. It is always a JSON list. The first element of the list is always a boolean that indicates if the REQ was successful.

Format:

[ success, rval ]
[ success, errorCode, errorDetails ]

success: The first value in the RSP list is always a boolean that indicates if the REQ was successful. If success is true, it may be followed by a return value (rval). If success is false, an errorCode and errorDetails.
rval: Return value from successful REQ. Can be any valid JSON data type.
errorCode: Integer an enumerated error code returned when REQ was unsuccessful.
errorDetails: String that gives a description of the error.

API Command

The API Command is the equivalent to a function call into a C library.

Commands are always JSON text string.
Commands are sent in the REQ as the first element in the list.
Commands are case insensitive.
Standard commands will be available on all systems.
Product specific commands may also be available.

API Parameters

API parameters are used for configuration and control the operation of the hardware, firmware or software contained in the Avid Product.

Parameters have containers called, API groups.
Each parameter must belong to an API group.
Each parameter has a valid JSON data type.
Parameter names are case insensitive.
Parameters may be read-only, write-only or read-write.
Parameters may be read using a GET command.
Parameters may be changed using a SET command.
Parameters are validated during a SET command.
Multiple parameters can be changed within a single SET command
A SET may be rejected due to one or more parameter’s value being out of range.
A SET will only return an error for 1 parameter per call. The first parameter error detected will be the error returned.
A failed SET command will NOT make any changes to ANY parameters in the command.
Validated parameter changes won’t take effect until a COMMIT is issued.
The SET command does any automatic COMMIT after all parameters have been successfully validated.
The SETN command does NOT do an automatic COMMIT.
The GETP command will get values of parameter that have pending changes (not committed).

API Group

An API Group is a collection of API parameters that are related. Typically these will be associated with a hardware/system component. Behind the scenes, the COMMIT is implemented on a per group basis. This means any changes committed to an API Group can perform any special procedures that is needed to make the change to the hardware interface.

API group is a collection related parameters.
API group names are case insensitive.

Process for changing API parameters

One or more settings are changed via SET or SETN command
Each parameter new value is validated.
If ANY parameter values in the SET or SETN command are invalid, then an error will be returned.
If ALL parameter values are valid, then the new values are stored in a temporary cache.
A COMMIT command will write parameters stored in the temporary cache to the hardware.
If the SET command was used, then an automatic COMMIT will be performed.
A DISCARD command will empty the temporary cache, erasing any recent changes performed using SETN commands.

Commands

The following a list of standard AVS API commands.

COMMIT

Command that activates pending changes that have been performed using SETN commands.

Parameters: None
Return Value: None

Example:

        REQ: ["COMMIT",""]
        RSP: [true]

DISCARD

Command that discards pending changes that have been performed using SETN commands.

Parameters: None
Return Value: None

Example:

        REQ: ["DISCARD",""]
        RSP: [true]

GET

Command that gets current values for one or more API parameter groups.

Parameters:

None: All API groups are returned
String: Returns parameters for a single group that matches name
List: List of strings returns multiple groups

Return Value: Object with API parameter values

Example:

        REQ: ["GET",""]
        RSP: [true,{"GEN":{"A":0,"B":false,"C":false,"D":false,"E":false,
             "F":-7,"G":0}}]

GETP

Command that gets pending values for one or more API parameter groups.

Parameters:

None: All API groups are returned
String: Returns parameters for a single group that matches name
List: List of strings returns multiple groups

Return Value: Object with API parameter values

Example:

        REQ: ["GETP",""]
        RSP: [true,{"GEN":{"A":0,"B":false,"C":false,"D":false,"E":false,
             "F":-7,"G":4096}}]

GETERR

Command that returns a complete list of possible error code used by the AVS API.

Parameters: None
Return Value: List of Error Code & Error Description pairs.

Example:

        REQ: [ "GETERR" ]
        RSP: [true,[[0,"Success"],[1,"Syntax Error"],[2,"Invalid Command"],
             [3,"Missing Command"],[4,"Invalid Parameter"],
             [5,"Missing Parameter"],[6,"Parameter Invalid Type"],
             [7,"Parameter Out of Range"],[8,"Parameter Read Only"],
             [9,"Invalid Config Group"],[10,"Invalid Config Parameter"],
             [11,"Timeout"]]]

GETCMD

Command that returns a list of supported commands for the system.

Parameters: None
Return Value: List of commands & description pairs.

Example:

        REQ: [ "GETCMD" ]
        RSP: [true,[["GET","Get values of config parameters"],
             ["SET","Set values of config parameters and commit changes"],
             ["GETP","Get values of pending config parameters"],
             ["SETN","Set values of config parameters (NO Commit)"],
             ["COMMIT","Commit pending config changes."],
             ["DISCARD","Discard pending config changes"],
             ["GETCMD","Get list of available commands"],
             ["GETERR","Get list of defined error codes"]]]

SET

Command that sets the values for one or more API parameter groups. Once each parameter has been successfully validated, then a COMMIT is automatically performed.

Parameters:

Map of group objects: Each group object contains one or more parameter/value pairs of parameters that are to be changed. (required)

Return Value: None

Example: The following example shows changing a parameter, G in group GEN

        REQ: ["SET",{"gen":{"g":4096}}]
        RSP: [true]

SETN

Command that sets the values for one or more API parameter groups. After parameter validation, NO commit is performed. To activate changes, an explicit COMMIT must be performed.

Parameters:

Map of group objects: Each group object contains one or more parameter/value pairs of parameters that are to be changed. (required)

Return Value: None

Example: The following example shows changing a parameter, G in group GEN

        REQ: ["SETN",{"gen":{"f":-1}}]
        RSP: [true]

AVS3022 API

The AVS3022 Control API uses the standard AVSAPI design.

API Parameters

API Group: STATUS

The following parameters are part of the STATUS group of API Parameters. All of the parameters in the STATUS group are read-only.

Parameter|Type|Description :-------:|:–:|:------------------------------------------------| BuildDate|string|FPGA Build Date in YYMMDD format BuildSeq|uint|FPGA Build sequence number PhyStatus0|uint|PHY PMA/PCS status for port 0 MacStatus0|uint|MAC status for port 0 PhyStatus1|uint|PHY PMA/PCS status for port 1 MacStatus1|uint|MAC status for port 1 PhyClockRate|uint|Measured PHY reference and process clock (Hz)

API Group: FP0, FP1

The Fiber Port parameters are accessed via port specific group, FP0,FP1. All of the parameters in this group are read-write.

Parameter|Type|Description :-------:|:–:|:------------------------------------------------| DstIp|string|Destination IP address (e.g. “0.0.0.0”) DstMac|string|Destination MAC address (e.g. “00:00:00:00:00:00”) DstPort|uint|Destination Port (16-bit number) DstIpEnable|bool|Enable for destination IP address filter DstMacEnable|bool|Enable for Destination MAC address filter DstPortEnable|bool|Enable for destination UDP port filter SrcIp|string|Source IP address (e.g. “0.0.0.0”) SrcMac|string|Source MAC address (e.g. “00:00:00:00:00:00”) SrcPort|uint|Source Port (16-bit number) SrcIpEnable|bool|Enable for source IP address filter SrcMacEnable|bool|Enable for source MAC address filter SrcPortEnable|bool|Enable for source UDP port filter

API Group: CH0STAT, CH1STAT, CH2STAT, CH3STAT

The channel status parameters are accessed via channel specific groups, CH0STAT,CH1STAT,CH2STAT,CH3STAT. All of the parameters in this group are read-only.

Parameter|Type|Description :-------:|:–:|:------------------------------------------------| InputLoading|uint|Is the average of the absolute value of the input. InputOverload|uint|How many times in a second the amplitude of the input waveform has come within 0.5 dB of full scale. DecimatedActivity|uint|The decimated activity indicates which upper bytes show activity based on sign bit variation. DecimatedLoading|uint|This is the average of the absolute value of the selected decimator output slice. DecimatedOverload|uint|Value counts how many times in a second the amplitude of the output of the post-decimation gain control module has saturated. Complete|bool|Snapshot complete indication DropCount|uint|Number of bytes that have been dropped on the incoming stream.

API Group: CH0CTXT, CH1CTXT, CH2CTXT, CH3CTXT

The channel context packet value are accessed via channel specific groups, CH0CTXT,CH1CTXT,CH2CTXT,CH3CTXT. All of the parameters in this group are read-only.

Parameter|Type|Description :-------:|:–:|:------------------------------------------------| StreamId|uint|Stream ID associated with Context Packet RefPointId|uint|32-bit value Bandwidth|float|Floating point value in HZ IFRefFreq|float|Floating point value in HZ RFRefFreq|float|Floating point value in HZ RFRefFreqOff|float|Floating point value in HZ IFBandOff|float|Floating point value in HZ RefLevel|float|Floating point value in dBm Gain1|float|Floating point value in dBm Gain2|float|Floating point value in dBm OverRangeCount|uint|32-bit value SampleRate|float|Floating point value in HZ

API Group: CH0CTRL, CH1CTRL, CH2CTRL, CH3CTRL

The channel control parameters are accessed via channel specific groups, CH0CTRL,CH1CTRL,CH2CTRL,CH3CTRL. All of the parameters in this group are read-write.

Parameter|Type|Description :-------:|:–:|:------------------------------------------------| NCOIncrement|uint|NCO increment is calculated as (2^32) tuning_frequency / sample_rate (32-bit) ResamplerDecimation|uint|Following the tuner there is a resampler, which changes the rate as a ration of 128/N, where N is the Resampler Decimation Parameter. UseResampler|bool|Enable/Disable resampler. UseCIC|bool|Enable/Disable CIC CICDecimationRate|uint|The combined decimation rate R is specified by the CIC Decimation Rate. If neither decimators are used, they are bypassed and tuned, wide-band samples are forwarded. GainControl|float|Should have a single value that software can program into the register*
HTL Max Exponent defines the upper expected signal level from the receiver. The post-decimation gain control values consists of an integer and fractional bit shift down a 80-bit word. Snapshot|bool|Enable/Disable Snapshot mode for the channel SFPInput|uint|Select SFP Input for channel (0 or 1)

API Group: CH0ECTXT, CH1ECTXT, CH2ECTXT, CH3ECTXT

The channel external context packet values (when enabled) are used to generate context packets for radios that do not support context packets, In order for the external context packet values to be used, the Enable parameter must be set to true.

Parameter|Type|Description :-------:|:–:|:------------------------------------------------| Bandwidth|float|Floating point value in HZ Enable|bool|Enable/Disable of External Context Packets RFRefFreq|float|Floating point value in HZ SampleRate|float|Floating point value in HZ

Examples

SOCAT is a Linux command line based utility establishes bi-directional between sockets. This simple tool provides a way to test the AVSAPI implemented in the AVS3020.

Install: The following can be used to install SOCAT on Ubuntu.

$ sudo apt-get install socat

Testing: The following is an example of how SOCAT can be used to test the AVS3020 using the Local Unix Domain JSON socket implementation. JSON REQ are typed in by the user and the RSP can immediately be seen. In the output before, a number of errors have been intentionally generated.

GET

The following example shows the output from a GET command. The output will contain all API parameters from all API groups.

$ sudo socat - tcp:localhost:12904
["get"]
[true,{
"FP0":{"DstIp":"0.0.0.0","DstIpEnable":false,"DstMac":"00:00:00:00:00:00",
"DstMacEnable":false,"DstPort"0,"DstPortEnable":false,"SrcIp":"0.0.0.0",
"SrcIpEnable":false,"SrcMac":"00:00:00:00:00:00","SrcMacEnable":false,
"SrcPort":0,"SrcPortEnable":false},
"FP1":{"DstIp":"0.0.0.0","DstIpEnable":false,"DstMac":"00:00:00:00:00:00",
"DstMacEnable":false,"DstPort":0,"DstPortEnable":false,"SrcIp":"0.0.0.0",
"SrcIpEnable":false,"SrcMac":"00:00:00:00:00:00","SrcMacEnable":false,
"SrcPort":0,"SrcPortEnable":false},
"STATUS":{"BuildDate":"200916","BuildSeq":0,"MacStatus0":0,"MacStatus1":0,
"PhyClockRate":156249478,"PhyStatus0":1,"PhyStatus1":0},
"CH0CTRL":{"CICDecimationRate":0,"GainControl":0,"NCOIncrement":0,
"ResamplerDecimation":1,"ResamplerFilterSelect":0,"SFPInput":0,
"Snapshot":false,"StreamId":0,"UseCIC":false,"UseResampler":false},
"CH0CTXT":{"Bandwidth":40000000,"Gain1":0,"Gain2":-47.8359375,"IFBandOff":0,"IFRefFreq":0,
"OverRangeCount":0,"RFRefFreq":890000000,"RFRefFreqOff":0,"RefLevel":25.5,"RefPointId":0,
"SampleRate":80000000,"StreamId":2130706456},
"CH0STAT":{"Complete":false,"DecimatedActivity":7,"DecimatedLoading":0,"DecimatedOverload":0,
"DropCount":0,"InputLoading":0,"InputOverload":0},
"CH1CTRL":{"CICDecimationRate":0,"GainControl":0,"NCOIncrement":0,
"ResamplerDecimation":1,"ResamplerFilterSelect":0,"SFPInput":0,
"Snapshot":false,"StreamId":0,"UseCIC":false,"UseResampler":false},
"CH1CTXT":{"Bandwidth":40000000,"Gain1":0,"Gain2":-47.8359375,"IFBandOff":0,"IFRefFreq":0,
"OverRangeCount":0,"RFRefFreq":890000000,"RFRefFreqOff":0,"RefLevel":25.5,"RefPointId":0,
"SampleRate":80000000,"StreamId":2130706456},
"CH1STAT":{"Complete":false,"DecimatedActivity":7,"DecimatedLoading":0,"DecimatedOverload":0,
"DropCount":0,"InputLoading":0,"InputOverload":0},
"CH2CTRL":{"CICDecimationRate":0,"GainControl":0,"NCOIncrement":0,
"ResamplerDecimation":1,"ResamplerFilterSelect":0,"SFPInput":0,
"Snapshot":false,"StreamId":0,"UseCIC":false,"UseResampler":false},
"CH2CTXT":{"Bandwidth":40000000,"Gain1":0,"Gain2":-47.8359375,"IFBandOff":0,"IFRefFreq":0,
"OverRangeCount":0,"RFRefFreq":890000000,"RFRefFreqOff":0,"RefLevel":25.5,"RefPointId":0,
"SampleRate":80000000,"StreamId":2130706456},
"CH2STAT":{"Complete":false,"DecimatedActivity":7,"DecimatedLoading":0,"DecimatedOverload":0,
"DropCount":0,"InputLoading":0,"InputOverload":0},
"CH3CTRL":{"CICDecimationRate":0,"GainControl":0,"NCOIncrement":0,
"ResamplerDecimation":1,"ResamplerFilterSelect":0,"SFPInput":0,
"Snapshot":false,"StreamId":0,"UseCIC":false,"UseResampler":false},
"CH3CTXT":{"Bandwidth":40000000,"Gain1":0,"Gain2":-47.8359375,"IFBandOff":0,"IFRefFreq":0,
"OverRangeCount":0,"RFRefFreq":890000000,"RFRefFreqOff":0,"RefLevel":25.5,"RefPointId":0,
"SampleRate":80000000,"StreamId":2130706456},
"CH3STAT":{"Complete":false,"DecimatedActivity":7,"DecimatedLoading":0,"DecimatedOverload":0,
"DropCount":0,"InputLoading":0,"InputOverload":0}}]

The following examples shows a GET command that just gets the STATUS group.

$ socat - tcp:localhost:12904
["get","status"]
[true,{"STATUS":{"BuildDate":"200916","BuildSeq":0,"MacStatus0":0,"MacStatus1":0,
"PhyClockRate":156249478,"PhyStatus0":1,"PhyStatus1":0}}]

GETP

The following example shows the output from a GETP command. In the test, a GET command is used to show the current values. A SETN command is used to change a value. Then the GETP command shows pending changes and the GET shows the value hasn’t changed. Next, a COMMIT command is issued to submit the pending changes. Lastly, another GET command shows pending changes have been committed.

For this test, the FP0 group is used.

$ sudo socat - tcp:localhost:12904
["get","fp0"]
[true,{"FP0":{"DstIp":"0.0.0.0","DstIpEnable":false,"DstMac":"00:00:00:00:00:00",
"DstMacEnable":false,"DstPort"0,"DstPortEnable":false,"SrcIp":"0.0.0.0",
"SrcIpEnable":false,"SrcMac":"00:00:00:00:00:00","SrcMacEnable":false,
"SrcPort":0,"SrcPortEnable":false}}]
["setn",{"fp0":{"dstip":"192.168.10.10","dstipenable":true}}]
[true]
["getp","fp0"]
[true,{"FP0":{"DstIp":"192.168.10.10","DstIpEnable":true}}]
["get","fp0"]
[true,{"FP0":{"DstIp":"0.0.0.0","DstIpEnable":false,"DstMac":"00:00:00:00:00:00","DstMacEnable":false,"DstPort":0,"DstPortEnable":false,"SrcIp":"0.0.0.0","SrcIpEnable":false,"SrcMac":"00:00:00:00:00:00","SrcMacEnable":false,"SrcPort":0,"SrcPortEnable":false}}]
["commit"]
[true]
["get","fp0"]
[true,{"FP0":{"DstIp":"192.168.10.10","DstIpEnable":true,"DstMac":"00:00:00:00:00:00",
"DstMacEnable":false,"DstPort":0,"DstPortEnable":false,"SrcIp":"0.0.0.0",
"SrcIpEnable":false,"SrcMac":"00:00:00:00:00:00","SrcMacEnable":false,"SrcPort":0,"SrcPortEnable":false}}]

AVS3022 API Verison 1.01

Changes since Version 1.00

Requirements

JSON (json.org)

Data Types

NDJSON (ndjson.org)

Control API Design

REQ

RSP

API Command

API Parameters

API Group

Process for changing API parameters

Commands

COMMIT

DISCARD

GET

GETP

GETERR

GETCMD

SET

SETN

AVS3022 API

API Parameters

API Group: STATUS

API Group: FP0, FP1

API Group: CH0STAT, CH1STAT, CH2STAT, CH3STAT

API Group: CH0CTXT, CH1CTXT, CH2CTXT, CH3CTXT

API Group: CH0CTRL, CH1CTRL, CH2CTRL, CH3CTRL

API Group: CH0ECTXT, CH1ECTXT, CH2ECTXT, CH3ECTXT

Examples

GET

GETP