AVS4000 API Version 1.28
The AVS4000 transceiver is controlled by a software application called the AVS4000 Daemon (AVS4000D). AVS4000D manages all of the AVS4000 devices connected to the system. AVS4000D also provides a TCP based control Application Programming Interfaces (API) that can be used to control the AVS4000 devices.
The following diagram describe the different processes that are created by AVS4000D.
Changes since Version 1.27
- Modified RX.Freq and TX.Freq minimum value from 50e6 to 2e6.
- Modified RX.SampleRate and TX.SampleRate minimum value from 100e3 to 50e3.
- Modified RX.SampleRate and TX.SampleRate maximum value from 50e6 to 61.44e6.
- Modified RX.RealSampleRate and TX.RealSampleRate minimum value from 100e3 to 50e3.
- Modified RX.RealSampleRate and TX.RealSampleRate maximum value from 50e6 to 61.44e6.
- Modified RX.RFBW and TX.RFBW minimum value from 100e3 to 200e3.
Changes since Version 1.26
- Modifed GPS.Reset parameter to support a value of ‘hw’ for a hardware reset.
Changes since Version 1.25
- Changed section Example Python Script for Receiving Data to File to include setting the RX.SampleRate parameter.
Changes since Version 1.24
- Changed Ref.Mode parameter value ‘External’ to ‘External10’. Setting the original value of ‘External’ will be interpreted as ‘External10’ in order to maintain backwards compatibility.
- Added new Ref.Mode value of ‘External100’
Changes since Version 1.23
- Changed GPSDO.PhaseDetectError to be a floating point number.
- Added DDC.RealFreq parameter.
- Added DUC.RealFreq parameter.
Changes since Version 1.22
- Changes to RX Group
- Added AutoCorrect parameter.
- Added RealCenterFreq parameter.
- Added RealRFFreq parameter.
- Changes to TX Group
- Added AutoCorrect parameter.
- Added RealCenterFreq parameter.
- Added RealRFFreq parameter.
Changes since Version 1.21
- Fixed GPS-AOP parameter to be RW instead of WO
- Fixed GPS-GNSS parameter to be RW instead of RO
Changes since Version 1.20
- Added present parameter to Device Manager DN# Group
- Added RealSampleRate parameter to RX and TX Groups
Changes since Version 1.19
- Removed unused addr parameter from Device Manager DN# Group
- Added CICOFIQ parameter to DDC and DUC Groups
- Added HWREV parameter to the VER Group
- Updated AVS4000DM API Diagram
- Updated AVS4000DC API Diagram
Changes since Version 1.18
- Changes to GPS Group
- Added GNSS parameter for GNSS System configuration.
- Removed range from Satellites parameter.
- Changes to GPSANT Group
- Modified Detect, Off and OK parameters to have additional possible values.
Changes since Version 1.17
- Changes to GPS Group
- All GPS parameter values are now derived from the UBX NAV-PVT message instead of NMEA messages
- Removed Sep & SepUnits parameters
- Changed Quality to FixType, also the values for FixType have changed.
- Changed Last to LastUpdate
- Changed Auto parameter to default to false.
- Added Clear, LastReset, Reset and Restored parameters
- Added FirstFix, FixCount, LastFix and LostFixCount parameters
- Changes to RXSTAT Group: Added RawRSSI and RSSI parameter
- Added GPSANT Group: Added fields related to GPS Antenna status
- Added GPSPVT Group: Added fields of UBX NAV-PVT message
- Added GPSDO Group: Added status for the GPSDO
Changes since Version 1.16
- Added VER Group to API DM & DS APIs now support a VER group that contains version information.
- Added PPSCount to RX Group: Provides counter for the number of PPS since reset.
Changes since Version 1.15
- Change Sample Rate Minimum TX & RX Sample Rates now have a lower sample rate of 100KS/s instead of 1MS/s.
Changes since Version 1.10
- Added Big Endian Support: TX & RX Data now supports Big Endian format (Most Significant Byte First). This inclucdes both Vita49 data streams as well as non-Vita49 streams.
- Added GPS Support: An API Group was added to provide GPS information and control.
- Added SubHz Support: The realized Sample Rate is now determined and report in the API Master.RealSampleRate.
Avid Control API
The AVS4000 provides Application Programming Interaces (API) that are based on the Avid Control API (AVSAPI). The basics of the AVSAPI is generic to support multiple products.
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.
NDJSON (ndjson.org)
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 AVSAPI provides the ability to control and configure the AVS4000. This is done via a request (REQ) and response (RSP). The REQ consists of a command and parameters. The RSP contains a success boolean, error information and return values.
The REQ is encoded and sent via a transport to the system. The encoding is JSON and the transport used is TCP/IP.
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 to 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 are in the RSP.
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 status, configuration and control of the AVS4000.
- 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.
- Parameter have an access type of: 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 are 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 new parameter 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 AVSAPI 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:
- Group: If the string is a group name, then the entire parameter group will be returned.
- Group.Param: If the string is of the form group.param, then a single parameter will be returned.
- List: List of strings where each string is a group name, returns multiple groups
Return Value: Object with API parameter values
Example:
REQ: ["GET","master"]
RSP: [true,
{"master":{"SampleRate":40000000,
"SampleRateMode":"Manual"}}]
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: The following shows a GETP command following the SETN example listed below.
REQ: ["GETP"]
RSP: [true,
{"ddc":{},"duc":{},
"master":{"SampleRate":42000000},
"ref":{},"rx":{},"rxdata":{},
"tx":{},"txdata":{}}]
GETERR
Command that returns a complete list of possible error code used by the AVSAPI.
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 Invalid Value"],
[8,"Parameter Out of Range"],[9,"Parameter Read Only"],
[10,"Invalid Config Group"],[11,"Invalid Config Parameter"],
[12,"Timeout"],[13,"Failure"],[14,"Partial Commit"]]]
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 parameter changes."],
["DISCARD","Discard pending config changes"],
["GETCMD","Get list of available commands"],
["GETERR","Get list of defined error codes"],
["INFO","Get information about parameters"]]]
INFO
Command that returns a list of descriptions for one or all API parameter groups.
Parameters:
- None: All API groups are returned
- String: Returns information for a single group that matches name
Example: The following example shows information for the parameters in the group Master.
REQ: ["INFO","master"]
RSP: [true,
{"master":{
"SampleRate":"Sample Rate (Hz) [2.5e6 to 61.44e6]",
"SampleRateMode":"Sample Rate Mode (Str) [Auto,Manual]"
}
}]
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, SampleRate in group Master
REQ: ["SET",{"master":{"SampleRate":44e6}}]
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, SampleRate in group Master
REQ: ["SETN",{"master":{"SampleRate":44e6}}]
RSP: [true]
AVS4000DM API Parameters
The AVS4000 DM (Device Manager) API uses the standard AVSAPI design. The following section includes a list of the DM API parameters used to control the AVS DM.
API Group: DM
The following parameters are part of the DM (device manager) group.
| Parameter | Type | Access | Description |
|---|---|---|---|
| DNs | list | RW | List of Active Device Numbers |
API Group: DN#
An API group is created for each active device in the system. The group name for each active device is of the form DN# where # is the device number for the device. For example, for DN=1, the group name would be DN1.
| Parameter | Type | Access | Description |
|---|---|---|---|
| dn | uint | RW | Device number for the device |
| model | string | RO | Model name for the device |
| present | bool | RO | Present state of the device (true=device is present) |
| ready | bool | RO | Ready state of the device (true=device is ready) |
| sn | string | RO | Model specific serial number for the device |
| type | string | RO | Type associated with the device |
API Group: VER
The following parameters contain version information assciated with the DM (device manager).
| Parameter | Type | Access | Description |
|---|---|---|---|
| avs4000d | string | RO | Version & Build information |
| avs4000lib | string | RO | Version & Build information |
| avsapi | string | RO | Version & Build information |
| avscommon | string | RO | Version & Build information |
| qt | string | RO | QT Runtime Version |
AVS4000DC API Parameters
The AVS4000DC (Device Controller) API uses the standard AVSAPI design. The following section includes a list of the API parameters used to control a Specific AVS4000. The TCP port number associated with a specific device is 12900+DN, where DN is the device number for the device.
API Group: DDC
The following parameters are part of the DDC group of API Parameters.
| Parameter | Type | Access | Description |
|---|---|---|---|
| CICGain | float | RW | CIC Gain (dB). The limits of this parameter vary with decimation rate. The user should not adjust this parameter and shall use OutGain to adjust gain within the DDC. |
| CICOFIQ | uint | RO | CIC Output Overflow Count [I=lower 16-bit,Q=upper 16-bit] |
| CICOutMag | uint | RO | CIC Output Average Magnitude (dBFS) |
| Decimation | uint | RO | Decimation [1, 2, 4, [8:2:2048], [2052:4:4096], [4104:8:8192]] |
| Freq | int | RW | Tuning Freq (Hz) [-MSR/2 to MSR/2], where MSR is the master sample rate. |
| InMag | int | RO | Input Average Magnitude (dBFS) |
| Invert | bool | RW | Invert Spectrum. Use this to invert the spectrum of the RX signal. |
| OutGain | float | RW | Output Gain (dB) [-72.2471 to 30.1029] |
| OutMag | float | RO | Output Average Magnitude (dBFS) |
| OutOFIQ | uint | RO | Output Overflow Count [I=lower 16-bit,Q=upper 16-bit] |
| RealFreq | int | RO | Real Tunning Frequency that includes frequency auto correction. (Hz) [-MSR/2 to MSR/2], where MSR is the master sample rate. |
API Group: DUC
The following parameters are part of the DUC group of API Parameters.
| Parameter | Type | Access | Description |
|---|---|---|---|
| CICGain | float | RW | CIC Gain (dB) The limits of this parameter vary with interpolation rate. The user should not adjust this parameter and shall use OutGain to adjust gain within the DUC. |
| CICOFIQ | uint | RO | CIC Output Overflow Count [I=lower 16-bit,Q=upper 16-bit] |
| CICOutMag | uint | RO | CIC Output Average Magnitude (dBFS) |
| Freq | int | RW | Tuning Freq (Hz) [-MSR/2 to MSR/2], where MSR is the master sample rate. |
| InMag | int | RO | Input Average Magnitude (dBFS) |
| Interpolation | uint | RO | Interpolation [1, 2, 4, [8:2:2048], [2052:4:4096], [4104:8:8192]] |
| InvertSpectrum | bool | RW | Invert Spectrum. Use this to invert the spectrum of the TX signal. |
| OutGain | float | RW | Output Gain (dB) [-72.2471 to 30.1029] |
| OutMag | float | RO | Output Average Magnitude (dBFS) |
| OutOFIQ | uint | RO | CIC Output Overflow Count [I=lower 16-bit,Q=upper 16-bit] |
| RealFreq | int | RO | Real Tunning Frequency that includes frequency auto correction. (Hz) [-MSR/2 to MSR/2], where MSR is the master sample rate. |
API Group: GPS
The following parameters are part of the GPS group of API Parameters. Many of the GPS parameters are derived from the u-blox M8 Receiver UBX messages. For further information refer to the u-blox 8 / u-blox M8 Receiver Manual that includes the interface protocol specification. The latest manual can be attained from www.u-blox.com
| Parameter | Type | Access | Description |
|---|---|---|---|
| Alt | float | RO | Altitude above mean sea level (Float). Units defined by the AltUnits parameter. |
| AltUnits | string | RO | Altitude Units. Typically it will be ‘M’ for meters. |
| AOP | bool | RW | GPS Automonous Mode (Bool) |
| Auto | bool | RW | Auto Mode when enabled will automatically disable updates a valid GPS time has been obtained. |
| CfgNav | string | WO | CfgNav is used to clear, load and store NAV settings to flash. (Str) [ ‘clear’, ‘load’, or ‘save’] |
| Clear | bool | WO | Clear Flash Backup Data. The contents of the GPS are cleared when this parameter is set to True. |
| FirstFix | float | RO | Seconds it took to acquire first fix. |
| FixCount | uint | RO | Count of NO Fix to Fix transitions since reset. |
| FixType | uint | RO | Quality for position fix. 0=No Fix 1=Dead Reckoning Only 2=2D Fix 3=3D Fix 4=GNSS + Dead Reckoning |
| Parameter | Type | Access | Description |
|---|---|---|---|
| GNSS | uint | RW | GNSS System Configuration Mask: Each bit when set enables a satellite system Bit 0: GPS Bit 1: SBAS Bit 2: Galileo Bit 3: BeiDou Bit 4: IMES Bit 5: QZSS Bit 6: GLONASS |
| LastFix | float | RO | Seconds it took to acquire the latest fix. |
| LastReset | float | RO | Number of seconds since last GPS Receiver reset. (sec) |
| LastUpdate | float | RO | Number of seconds since last GPS update(sec) |
| LAT | float | RO | Latitude in fractional degrees |
| LONG | float | RO | Longitude in fractional degrees |
| LostFixCount | uint | RO | Count of the Fix to NO Fix transitions since reset. |
| PDOP | float | RO | GPS Position Dilution of Precision |
| Reset | str | WO | GPS Reset ‘cold’: Performs a cold reset ‘warm’: Performs a warm reset ‘hot’: Peforms a hot reset. ‘hw’: Performs a hardware reset. ‘save’: Save GPS battery backed RAM to flash |
| Restored | bool | RO | Indicates of GPS Receiver restored RAM from flash. |
| Satellites | uint | RO | Number of satellites used for solution. |
| Time | uint | RO | GPS UTC number of seconds since the Epoch (Jan 1 1970) |
| Updates | bool | RW | Enable GPS updates. |
By default the system Auto Mode disabled and Updates enabled.
API Group: GPSANT
The following parameters are part of the GPSANT group of API Parameters. The GPSANT parameters are derived from the u-blox M8 Receiver UBX MON-HW and UBX MON-PIO messages. The information in the this message could be stale. If two API GET for teh GPSANT group and performed, the second response should be up to date.
| Parameter | Type | Access | Description |
|---|---|---|---|
| Detect | str | RO | GPS Antenna Detect [low,high,pulled up,pulled down,floating,unknown,invalid] When high, an antenna has been detected. |
| Off | str | RO | GPS Antenna OFF [low,high,pulled up,pulled down,floating,unknown,invalid] When high, the DC power to the GPS antenna is OFF. |
| OK | str | RO | GPS Antenna OK [low,high,pulled up,pulled down,floating,unknown,invalid] When low a short circuit or over current condition exists. When high, the antenna is OK. |
| Power | str | RO | GPS Antenna Power [off,on,unknown] A parameter indicating whether the power to the GPS antenna is on or off. |
| Status | str | RO | GPS Antenna Status [init,ok,short,open] The status parameter reports the current overall status of the GPS antenna. |
API Group: GPSDO
The following parameters are part of the GPSDO group of API Parameters.
| Parameter | Type | Access | Description |
|---|---|---|---|
| AvgError | int | RO | GPSDO Average Error detected in the GPSDO module. Each integer value represents 5ns of skew between the reference PPS rising edge and the trained PPS rising edge. |
| PhaseDetectorError | float | RO | Phase Detector Errors. Raw GPSDO phase detector erorr value. Each integer value represents 5ns of skew between the reference PPS rising edge and the trained PPS rising edge. |
| PPSLOS | bool | RO | PPS Loss of Signal. In GSPDO reference mode, this indicates that the PPS out of the module was lost. In PPS reference mode this indicates the external PPS has not been detected. |
| PWMStatus | uint | RO | PWM Status. This parameter reporst the current PWM increment set by the disciplined oscillator firmware module. |
API Group: GPSPVT
The following parameters are part of the GPSPVT group of API Parameters. These parameters are taken from the U-Blox 8 UBX NAV-PVT Message. For more information, refer to the u-blox8-M8_ReceiverDescrProtSpec document.
| Parameter | Type | Access | Description |
|---|---|---|---|
| Day | uint | RO | UTC Day of the Month [1-31] |
| FixType | uint | RO | GNSS Fix Type |
| Flags | uint | RO | Fix Status Flags |
| Flags2 | uint | RO | Additional flags |
| gSpeed | int | RO | Ground Speed 2-D (mm/s) |
| hAcc | uint | RO | Horizontal accuracy estimate (mm) |
| headAcc | uint | RO | Heading accuracy estimate (deg) |
| headMot | int | RO | Heading of motion 2-D (deg) |
| headVeh | int | RO | Heading of vehicle 2-D (deg) |
| Height | int | RO | Height above ellipsoid (mm) |
| HeightMSL | int | RO | Height above mean sea level (mm) |
| Hour | uint | RO | UTC Hour of the Day [0-23] |
| Lat | int | RO | Latitude scaling 1e-7 (deg) |
| Lon | int | RO | Longitude scaling 1e-7 (deg) |
| Min | uint | RO | UTC Minute of the Hour [0-59] |
| Month | uint | RO | UTC Month [1-12] |
| Nano | int | RO | Fraction of second (ns) [-1e9 - 1e9] |
| NumSV | uint | RO | Number of satellites used in Nav Solution |
| Parameter | Type | Access | Description |
|---|---|---|---|
| PDOP | uint | RO | Position Dilution of Precision |
| sAcc | uint | RO | Speed accuracy estimate (mm/s) |
| Sec | uint | RO | UTC Seconds of minute [0-60] |
| tAcc | uint | RO | Time accuracy estimate (ns) |
| TOW | uint | RO | GPS time of week of the navigation epoch (sec) |
| vAcc | uint | RO | Vertical accuracy estimate (mm) |
| Valid | uint | RO | Validity Flags |
| ve1D | int | RO | NED down velocity (mm/s) |
| ve1E | int | RO | NED east velocity (mm/s) |
| ve1N | int | RO | NED north velocity (mm/s) |
| Year | uint | RO | UTC Year |
API Group: MASTER
The following parameters are part of the Master group of API Parameters.
| Parameter | Type | Access | Description |
|---|---|---|---|
| RealSampleRate | float | RO | Sample Rate (Hz) [2.5e6 to 50e6] This parameter provides the actaul “REAL” master sample rate that was achieved by the radio as a floating point value. |
| SampleRate | uint | RW | Sample Rate (Hz) [2.5e6 to 50e6] This parameter is used to set and report the current master sample rate in integer number of Hz. This parameter can only be changed when all streams are disabled. |
| SampleRateMode | string | RW | Sample Rate Mode [Auto,Manual] This parameter can be used to specify or query the master sample rate mode of the radio. In manual mode, the user must set a valid master sample rate and compatbile RX and TX sample rates. In automatic mode, the daemon sets the master sample rate based on the requested RX and TX sample rates. |
API Group: REF
The following parameters are part of the Ref group of API Parameters for controlling the system reference.
| Parameter | Type | Access | Description |
|---|---|---|---|
| Lock | bool | RO | Reference Lock. Current lock status of the reference. |
| Mode | string | RW | Reference Mode [Internal,InternalStatic,External10,External100,GPSDO,PPS] Internal: Free-running reference oscillator InternalStatic: Free-running local oscillator mode. Allows the PWMInc to be used to adjust the frequency of the reference oscillator. External10: Phase locks the local oscillator to the 10MHz external reference. External100: Phase locks the local oscillator to the 100MHz external reference. GPSDO: Trains the frequency and phase of the local oscillator to the PPS output of hte onboard GPS module. PPS (PPSDO): Trains the frequency and phase of the local oscillator to the PPS input. |
| PPSCount | uint | RO | PPS Count [0 - 0xFFFF] |
| PPSSel | string | RW | PPS Select [Internal,External,GPS] |
| PWMInc | uint | RW | PWM Increment [0 - 0xFFFF] |
| SysSync | bool | WO | System Sync |
| Time | uint | RO | Time since the UTC Epoch (ms) |
| TimeBase | string | RW | Timebase [GPS,Host] Sets the timebase of the radio from the Host or from the time reported by the onboard GPS module. |
API Group: RX
The following parameters are part of the RX group of API Parameters for controlling receive portion of the transceiver.
| Parameter | Type | Access | Description |
|---|---|---|---|
| AutoCorrect | bool | RW | Auto Frequency Correction |
| Freq | uint | RW | Tuning Freq (Hz) [2e6 to 6e9] The RX center frequency of the radio. |
| Gain | int | RW | RF Gain (dB) [-10 to 77] Used to set and query the RF transceiver portion of the RX gain of the radio. |
| GainMode | string | RW | RF Gain Mode [Manual,FastAGC,SlowAGC] |
| LBBW | string | RW | Low Band Bandwidth [Narrow,Wide] This parameter is used to select between a Narrow (10MHz) and a Wide (50MHz) bandwidth SAW filter when the low band converter is engaged. |
| LBMode | string | RW | Low Band Mode [Auto,Enable,Disable] In Auto mode, the daemon determines when to engage the low band converter. The enable and disable modes provide user control. |
| LBThreshold | uint | RW | Low Band Threshold (Hz) [5e6 to 5e9] The frequency threshold used by the daemon to determine when to engage the low band converter. |
| RealCenterFreq | float | RO | Real Base Band Center Frequency in Hz. |
| RealRFFreq | float | RO | Real RF Frequency in Hz. |
| RealSampleRate | uint | RO | Real Sample Rate (Hz) [50e3 to 61.44e6] The real sample rate in integer Hz. |
| RFBW | uint | RW | RF Bandwidth [200e3 to 56e6, 0=auto] Used to control the bandwidth of the analog RF filter at the input of the RF transceiver. |
| SampleRate | uint | RW | Sample Rate (Hz) [50e3 to 61.44e6] The RX sample rate in integer Hz. The RX stream must be disabled to set this parameter. |
| StartDelay | uint | RW | Start Delay (Sec) [1 to 300] Allows the user to specify the number of seconds to wait before starting the RX stream when StartMode is OnPPS or OnFracRoll. |
| StartMode | string | RW | Start Mode [Immediate,OnPPS,OnFracRoll,OnTime] Immediate: Stream starts as soon as the run parameter of the RXDATA group is enabled. OnPPS: Starts of some future PPS after the RXDATA.run paramter is set. Uses StartDelay OnFracRoll: Starts on some future rollover of the fractional timebase after the RXDATA.run parameter is set. Uses StartDelay OnTime: Starts on the time specified by StartUTCInt and StartUTCFrac The TXDATA.run parameter must still be enabled. |
| StartUTCFrac | uint | RW | Start UTC Fracional. Fractional second portion of the start time used for OnTime mode. |
| StartUTCInt | uint | RW | Start UTC Integer (Sec). Integer second portion of the start time used for OnTime mode. |
| UserDelay | uint | RW | User Delay. Timestamp compensation delay that can be used to compensate for group delays outside of the radio. |
API Group: RXDATA
The following parameters are part of the RXDATA group of API Parameters for controlling RX Data stream.
| Parameter | Type | Access | Description |
|---|---|---|---|
| ConEnable | bool | RW | Enable/Disable Conection [true=connect,false=disconnect] |
| ConPort | uint | RW | Connection Port [0 - 0xFFFF] |
| ConType | string | RW | Connection Type [TCP] |
| Run | bool | RW | Enable/Disable RX Data [true=start,false=stop] |
| UseBE | bool | RW | Enable/Disable Big Endian byte ordering for data. (Bool) |
| UseV49 | bool | RW | Enable/Disable Vita 49 Packets |
API Group: RXSTAT
The following parameters are part of the RXSTAT group of API Parameters for status about RX Data stream.
| Parameter | Type | Access | Description |
|---|---|---|---|
| Gain | float | RO | Roll-up Gain for Stream (dB) |
| Overflow | uint | RO | Number of overflow errors for stream |
| Rate | string | RO | Current Transfer Data Rate (MB/s) |
| RawRSSI | float | RO | Raw RSSI (dB) |
| RSSI | float | RO | RSSI (dB) |
| Sample | uint | RO | Current Transfer sample count |
API Group: SYSSTAT
The following parameters are part of the SYSSTAT group of API Parameters for status about the system.
| Parameter | Type | Access | Description |
|---|---|---|---|
| BoardTemp | float | RO | Board Temperature in celsius |
| CommitCount | uint | RO | Number of configuration changes since startup. |
| DN | uint | RO | Device Number assigned by Device Manager |
| SN | string | RO | Serial Number |
| FpgaAmbTemp | float | RO | FPGA ambient temperature in celsius |
| FpgaDieTemp | float | RO | FPGA die temperature in celsius |
| FpgaVccAux | float | RO | FPGA Vcc Aux voltage |
| FpgaVccBRAM | float | RO | FPGA Vcc BRAM voltage |
| FpgaVccInt | float | RO | FPGA Vcc Internal voltage |
API Group: TX
The following parameters are part of the TX group of API Parameters for controlling transmit portion of the transceiver.
| Parameter | Type | Access | Description |
|---|---|---|---|
| AutoCorrect | bool | RW | Auto Frequency Correction |
| AmpEnable | bool | RW | TX Amp Enable. When true the HMC311 amplifier in the TX path is enabled. |
| Freq | uint | RW | Tuning Freq (Hz) [2e6 to 6e9] The TX center frequency of the radio. |
| LBMode | string | RW | Low Band Mode [Auto,Enable,Disable] In Auto mode, the daemon determines when to engage the low band converter. The enable and disable modes provide user control. |
| LBThreshold | uint | RW | Low Band Threshold (Hz) [5e6 to 5e9] The frequency threshold used by the daemon to determine when to engage the low band converter. |
| OutRxEnable | bool | RW | Out RX Enable. Used in TDD or single connector RX/TX mode. When set the TX signal is output the RX/TX connector and the RX path is disconnected. |
| RealCenterFreq | float | RO | Real Base Band Center Frequency in Hz. |
| RealRFFreq | float | RO | Real RF Frequency in Hz. |
| RealSampleRate | uint | RO | Real Sample Rate (Hz) [50e3 to 61.44e6] The real sample rate in integer Hz. |
| RFBW | uint | RW | RF Bandwidth [200e3 to 56e6, 0=auto] Used to control the bandwidth of the analog RF filter at the TX output of the RF transceiver. |
| SampleRate | uint | RW | Sample Rate (Hz) [50e3 to 61.44e6] The TX sample rate in integer Hz. The TX stream must be disabled to set this parameter. |
| StartDelay | uint | RW | Start Delay (Sec) [1 to 300] Allows the user to specify the number of seconds to wait before starting the RX stream when StartMode is OnPPS or OnFracRoll. |
| StartMode | string | RW | Start Mode [Immediate,OnPPS,OnFracRoll,OnTime] Immediate: Stream starts as soon as the run parameter of the TXDATA group is enabled. OnPPS: Starts of some future PPS after the RXDATA.run paramter is set. Uses StartDelay OnFracRoll: Starts on some future rollover of the fractional timebase after the TXDATA.run parameter is set. Uses StartDelay OnTime: Starts on the time specified by StartUTCInt and StartUTCFrac. The TXDATA.run parameter must still be enabled. |
| StartUseV49 | bool | RW | Use Vita49 for Start Time |
| StartUTCFrac | uint | RW | Start UTC Fracional. Fractional second portion of the start time used for OnTime mode. |
| StartUTCInt | uint | RW | Start UTC Integer (Sec). Integer second portion of the start time used for OnTime mode. |
API Group: TXDATA
The following parameters are part of the TXDATA group of API Parameters for controlling TX Data stream.
| Parameter | Type | Access | Description |
|---|---|---|---|
| ConEnable | bool | RW | Enable/Disable Conection [true=connect,false=disconnect] |
| ConPort | uint | RW | Connection Port [0 - 0xFFFF] |
| ConType | string | RW | Connection Type [TCP] |
| Run | bool | RW | Enable/Disable RX Data [true=start,false=stop] |
| UseBE | bool | RW | Enable/Disable Big Endian byte ordering for data. (Bool) |
| UseV49 | bool | RW | Enable/Disable Vita 49 Packets |
API Group: TXSTAT
The following parameters are part of the TXSTAT group of API Parameters for status about TX Data stream.
| Parameter | Type | Access | Description |
|---|---|---|---|
| Gain | float | RO | Roll-up Gain for Stream (dB) |
| Rate | string | RO | Current Transfer Data Rate (MB/s) |
| Sample | uint | RO | Current Transfer sample count |
| Underflow | uint | RO | Number of underflow errors for stream |
API Group: VER
The following parameters contain version information assciated with the DM (device manager).
| Parameter | Type | Access | Description |
|---|---|---|---|
| avs4000d | string | RO | Version & Build information of avs4000d |
| avs4000lib | string | RO | Version & Build information of avs4000lib |
| avsapi | string | RO | Version & Build information of avsapi library |
| avscommon | string | RO | Version & Build information of avscommon library |
| fpga | string | RO | Version & Build information of the FPGA firmware build |
| fx3 | string | RO | Version & Build information of the FX3 firmware. |
| hwrev | string | RO | Revision of the hardware. |
| qt | string | RO | QT Runtime Version of the host computer. |
AVS4000 API Testing
The AVS4000D is the application that implements a test AVS4000 API and controls the AVS4000. In order to use the AVS4000 API the AVS4000D application must be running.
SOCAT
SOCAT is a Linux command line based utility that establishes bi-directional communication between sockets. This simple tool provides a way to test the AVS4000 API implemented in the AVS4000D.
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 AVS4000 API (for DN=1) using the TCP JSON socket implementation. JSON REQ are typed in by the user and the RSP can immediately be seen. In the output below, a number of errors have been intentionally generated.
$ socat - tcp:localhost:12901
abc
[false,1,"Parse Error"]
[[abc
[false,1,"Parse Error"]
get
[false,1,"Parse Error"]
[get]
[false,1,"Parse Error"]
["getcmd"]
[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 parameter changes."],
["DISCARD","Discard pending config changes"],
["GETCMD","Get list of available commands"],
["GETERR","Get list of defined error codes"],
["INFO","Get information about parameters"]]]
In the above output additional line feeds have been inserted to make the output more readable. However, in real tests only a single linefeed is output at the end of each RSP.
Testing: The following is an example of how SOCAT can be used to test the AVS4000 DM API (device manager) using the TCP JSON socket implementation. JSON REQ are typed in by the user and the RSP can immediately be seen.
$ socat - tcp:localhost:12900
["get"]
[true,{
"DN1":{
"addr":259,
"dn":1,
"model":"AVS4000",
"ready":true,
"sn":"SN0008",
"type":"USB"
},
"dm":{
"DNs":[1]
},
"ver":{
"avs4000d":"1.03 (Dec 11 2020 14:39:11)",
"avs4000lib":"1.15 (Dec 11 2020 14:39:09)",
"avsapi":"1.02 (Dec 11 2020 14:05:15)",
"avscommon":"1.45 (Dec 11 2020 14:05:13)",
"qt":"5.09.05"
}
}]
In the above output additional line feeds have been inserted to make the output more readable. However, in real tests only a single linefeed is output at the end of each RSP.
AVS4000 Data Streams
The AVS4000 RX and TX Data streams use TCP sockets. Data is transmitted over the socket as either Raw IQ data or Vita49 packets. In Raw IQ mode, the first 16 bits is I and the second 16-bits is Q. The I & Q are signed 16-bit integers. All data for the data stream is little endian.
Steps for Receiving Data
- Configure RX parameters: tune, sample rate, gain, etc..
- Enable RX Data Connection: Specify TCP type and port.
- Start RX Data
- Connect to TCP RX Data socket
- Receive & process data from socket
- Stop RX Data
Example Python Script for Receiving Data to File
#!/usr/bin/python2
import socket
import json
import os
DN=1
HOST='localhost'
PORT=12900+DN
RX_PORT=12700+DN
# Connect to AVS4000 API socket
sock=socket.socket(socket.AF_INET,socket.SOCK_STREAM);
sock.connect((HOST,PORT));
# Create REQ
P={}; # Set REQ Map
RX={}; # RX Group Map
RXD={}; # RXDATA Group Map
RX["sampleRate"]=20e6 # RX Sample Rate
RXD["conEnable"]=True; # enable RX Data Connection
RXD["conType"]="tcp"; # Specify to use TCP
RXD["conPort"]=RX_PORT; # Specify TCP Port to listen on
RXD["useV49"]=False; # Receive Raw IQ Data
RXD["run"]=True; # Start the stream
P["rx"]=RX; # Add RX Group Map to REQ
P["rxdata"]=RXD; # Add RXDATA Group Map to REQ
REQ=['set',P]; # Create REQ for SET Command
# Convert REQ to JSON and send on socket
sock.send(json.dumps(REQ)+'\n');
str=sock.recv(8192); # Receive the RSP
RSP=json.loads(str); # Parse JSON to Python list
print (RSP); # Print the RSP
# Use SOCAT utitiltiy to connect to TCP RX Data Socket
# save data to a new file 'rx.out'.
os.system("socat -u TCP:localhost:%d CREATE:rx.out &"%(RX_PORT))
Example Python Script to Stop Receiving Data
#!/usr/bin/python
import socket
import json
import os
DN=1
HOST='localhost'
PORT=12900+DN
RX_PORT=12700+DN
# Connect to AVS4000 API socket
sock=socket.socket(socket.AF_INET,socket.SOCK_STREAM);
sock.connect((HOST,PORT));
# Create REQ
P={}; # Set REQ Map
G={}; # RXDATA Group Map
G["conEnable"]=False; # Disable RX Data Connection
G["run"]=False; # Stop the RX Data stream
P["rxdata"]=G; # Add RXDATA Group Map to REQ
REQ=['set',P]; # Create REQ for SET Command
sock.send(json.dumps(REQ)); # Convert REQ to JSON and send on socket
str=sock.recv(8192); # Receive the RSP
RSP=json.loads(str); # Parse JSON to Python list
print (RSP); # Print the RSP
Steps for Transmitting Data
- Configure TX parameters: tune, sample rate, gain, etc..
- Enable TX Data Connection: Specify TCP type and port.
- Start TX Data
- Connect to TCP TX Data socket
- Transmit Data to socket
- Stop TX Data
Example Python Script to Transmit Data from File
#!/usr/bin/python
import socket
import json
import os
DN=1
HOST='localhost'
PORT=12900+DN
TX_PORT=12800+DN
# Connect to AVS4000 API socket
sock=socket.socket(socket.AF_INET,socket.SOCK_STREAM);
sock.connect((HOST,PORT));
# Create REQ
P={}; # Set REQ Map
G={}; # TXDATA Group Map
G["conEnable"]=True; # enable TX Data Connection
G["conType"]="tcp"; # Specify to use TCP
G["conPort"]=TX_PORT; # Specify TCP Port to listen on
G["useV49"]=False; # Send Raw IQ Data
G["run"]=True; # Start the stream
P["txdata"]=G; # Add TXDATA Group Map to REQ
REQ=['set',P]; # Create REQ for SET Command
sock.send(json.dumps(REQ)); # Convert REQ to JSON and send on socket
str=sock.recv(8192); # Receive the RSP
RSP=json.loads(str); # Parse JSON to Python list
print (RSP); # Print the RSP
# Use SOCAT utitiltiy to connect to TCP TX Data Socket
# read data from file 'tx.out'.
os.system("socat -u FILE:tx.out TCP:localhost:12924 &")
Example Python Script to Stop Transmit Data
#!/usr/bin/python
import socket
import json
import os
DN=1
HOST='localhost'
PORT=12900+DN
TX_PORT=12800+DN
# Connect to AVS4000 API socket
sock=socket.socket(socket.AF_INET,socket.SOCK_STREAM);
sock.connect((HOST,PORT));
# Create REQ
P={}; # Set REQ Map
G={}; # TXDATA Group Map
G["conEnable"]=False; # Disable TX Data Connection
G["run"]=False; # Stop the TX Data stream
P["txdata"]=G; # Add TXDATA Group Map to REQ
REQ=['set',P]; # Create REQ for SET Command
sock.send(json.dumps(REQ)); # Convert REQ to JSON and send on socket
str=sock.recv(8192); # Receive the RSP
RSP=json.loads(str); # Parse JSON to Python list
print (RSP); # Print the RSP