Metering protocol

From SmartSDR Wiki
Jump to: navigation, search

The metering protocol is sent using VTIA-49 extension and context extension packets. The meters that are sent in the extension packets (meter packets) are detailed in the extension context packet. In other words, which meters will be sent, their descriptions, units, etc. are all sent in the context packet. Once the context packet has been received and parsed, your software can understand the format of the meter packets themselves.

Context packets will only be sent periodically or when the number of specifications of meters actually change.

Meter Metadata

Meter metadata contains all of the information about a meter except the actual metered value. The metadata can be requested to determine which meters are available along with all of the information necessary to display meters in a client program. Meter metadata is requested through the meter list command.

METER LIST

Change parameters that affect the panadapter display or underlying hardware

C[D]<seq_number>|meter list

Example:

C12|meter list

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 <meter list> Response with complete list of meters (see below)

Response Example:

R4|0|meter 1.src=COD-#1.num=1#1.nam=MICPEAK#1.low=-150.0#1.hi=20.0#1.desc=Signal strength of MIC output in
CODEC#1.unit=dBFS#1.fps=40#2.src=COD-#2.num=2#2.nam=MIC#2.low=-150.0#2.hi=20.0#2.desc=Average Signal strength of MIC ouput in
CODEC#2.unit=dBFS#2.fps=20#3.src=TX-#3.num=8#3.nam=CODEC#3.low=-150.0#3.hi=20.0#3.desc=Signal strength of CODEC
output#3.unit=dBFS#3.fps=10#4.src=TX-#4.num=8#4.nam=SC_MIC#4.low=-150.0#4.hi=20.0#4.desc=Signal strength of MIC
output#4.unit=dBFS#4.fps=10#5.src=TX-#5.num=8#5.nam=COMPPEAK#5.low=-150.0#5.hi=20.0#5.desc=Signal strength of signals after the
CLIPPER (Compression)      #5.unit=dBFS#5.fps=20#6.src=TX-#6.num=8#6.nam=SC_FILT_1#6.low=-150.0#6.hi=20.0#6.desc=Signal strength
after Filter 1#6.unit=dBFS#6.fps=10#7.src=TX-#7.num=8#7.nam=ALC#7.low=-150.0#7.hi=20.0#7.desc=Signal strength of signals after SW
ALC (SSB Peak)#7.unit=dBFS#7.fps=10#8.src=TX-#8.num=8#8.nam=SC_FILT_2#8.low=-150.0#8.hi=20.0#8.desc=Signal strength after Filter
2#8.unit=dBFS#8.fps=10#9.src=TX-#9.num=8#9.nam=B4RAMP#9.low=-150.0#9.hi=20.0#9.desc=Signal strength of signals before the
ramp#9.unit=dBFS#9.fps=10#10.src=TX-#10.num=8#10.nam=AFRAMP#10.low=-150.0#10.hi=20.0#10.desc=Signal strength of signals after the
ramp#10.unit=dBFS#10.fps=10#11.src=TX-#11.num=8#11.nam=GAIN#11.low=-150.0#11.hi=0.0#11.desc=Signal strength after
Gain#11.unit=dBFS#11.fps=10#12.src=TX-#12.num=5#12.nam=HWALC#12.low=-150.0#12.hi=20.0#12.desc=Voltage present at the Hardware ALC
RCA Plug#12.unit=dBFS#12.fps=20#13.src=RAD#13.num=208#13.nam=+13.8A#13.low=10.5#13.hi=15.0#13.desc=Main radio input voltage before
fuse#13.unit=Volts#13.fps=0#14.src=RAD#14.num=210#14.nam=+13.8B#14.low=10.5#14.hi=15.0#14.desc=Main radio input voltage after
fuse#14.unit=Volts#14.fps=0#15.src=TX-#15.num=1#15.nam=FWDPWR#15.low=0.0#15.hi=53.0#15.desc=RF Power
Forward#15.unit=dBm#15.fps=20#16.src=TX-#16.num=2#16.nam=REFPWR#16.low=0.0#16.hi=53.0#16.desc=RF Power
Reflected#16.unit=dBm#16.fps=20#17.src=TX-#17.num=3#17.nam=SWR#17.low=1.0#17.hi=999.0#17.desc=RF
SWR#17.unit=SWR#17.fps=20#18.src=TX-#18.num=4#18.nam=PATEMP#18.low=0.0#18.hi=100.0#18.desc=PA
Temperature#18.unit=degC#18.fps=0#19.src=SLC#19.num=0#19.nam=24kHz#19.low=-140.0#19.hi=20.0#19.desc=24kHz broadband slice receiver
signal level#19.unit=dBFS#19.fps=10#20.src=SLC#20.num=0#20.nam=OSC#20.low=-140.0#20.hi=20.0#20.desc=Signal Strength after
OSC#20.unit=dBFS#20.fps=10#21.src=SLC#21.num=0#21.nam=LEVEL#21.low=-150.0#21.hi=20.0#21.desc=Signal strength of signals in the
filter passband#21.unit=dBm#21.fps=10#22.src=SLC#22.num=0#22.nam=NR/ANF#22.low=-150.0#22.hi=20.0#22.desc=Signal strength after
NR/ANF#22.unit=dBm#22.fps=10#23.src=SLC#23.num=0#23.nam=AGC+#23.low=-150.0#23.hi=0.0#23.desc=Signal strength after
AGC#23.unit=dBFS#23.fps=10#

Each phrase (dotted variable, equals and a value) of the response is a name-value pair. Each name follows this format:

<meter identifier>.<field>=<value>
meter identifier 
The meter identifier is a 16-bit number that is used to tie the meter value to it's context information in this packet. It must be preserved so that it may be matched with the metering data itself. These generally start with 0 and go through the number of meters, but it is possible that numbers could be skipped.
meter field 
the specific metadata field being described (see meter field table below)
value 
the value of this field

Source Identifiers

Source identifiers describe the location in the radio of the meter. The meter could be at the radio level itself if the meter is about a voltage, current or temperature in the radio or they could be describing a software architecture component such as a slice receiver.

Source Identifier Detail
Valid source identifiers
RAD radio-wide details such as temperature and voltage
SLC meters specific to a slice receiver
PAN meters specific to a panadapter

Meter Fields

Meter fields are the specific pieces of information that describes the meter. Most of these will be included for each meter.

Field Detail
Valid meter fields
src the source type of the meter (see the source table above)
num the ordinal number of the source (for example a "1" for slice 1)
unit the units that the meter values will be sent in and how the value is interpreted. See units chart below.
low the theoretical lower bounds of the meter
hi the theoretical upper bounds of the meter
fps the update rate in Hz or frames per second (not typically used at this point)
peak an indication if this is a peak value (will be T or F). Assume "F" or false if not supplied
nam the name of the meter (generally 5 characters or less), enclosed in double quotation marks
desc the text description of the meter, enclosed in double quotation marks

Meter Units

Meter value fields are sent with strict units. The table below describes how each meter will be interpreted

Units Detail
Valid meter units
dbm dBm power, referenced generally to the radio input connector, as described in VITA-49 7.1.5.9. (Two's complement, radix between bits 6/7)
dbfs power, referenced to full scale VITA-49 7.1.5.9. (Two's complement, radix between bits 6/7)
volts voltage in two's complement volts with ten bits to the right of the radix point and six to the left
amps amps in two's complement amps with ten bits to the right of the radix point and six to the left

METER SUBSCRIPTION

Allows the client to specify which meter updates are desired. Meter data is sent in VITA-49 Context packets described in the next section. To subscribe to a single meter, use the following command:

C[D]<seq_number>|sub meter <meter_index>

Example:

C12|sub meter 17

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 subscribed to meter 17

Response Example:

R12|0||


Note that Slice oriented meters are transient and will be removed/added dynamically when Slices are added/removed and on mode changes.


To unsubscribe from a particular meter, use the following command:

C[D]<seq_number>|unsub meter <meter_index>

Example:

C13|unsub meter 17
Responses
Hex Response Message Debug Output / Meaning
00000000 unsubscribed to meter 17

Response Example:

R13|0||


The client may also prefer to subscribe to all meters automatically. This can be accomplished with the following command:

C[D]<seq_number>|sub meter all

Example:

C14|sub meter all
Responses
Hex Response Message Debug Output / Meaning
00000000 subscribed to all meters

Response Example:

R14|0||

Similarly, the client can unsubscribe from all meters using the following command:

C[D]<seq_number>|unsub meter all

Example:

C15|unsub meter all
Responses
Hex Response Message Debug Output / Meaning
00000000 unsubscribed to all meters

Response Example:

R15|0||

Meter Extension Packet

The meter extension packet is sent frequently (typically at a 10Hz rate) and contains all of the meters described in the context packet. Because the context packet and the metering packet can occasionally be out of sync, you should disregard all metering data for identifiers that you have not yet received context data for.

Packet for holding meter values
  • The C field will be set to "1" to indicate that a class identifier will be sent.
  • The R fields are reserved and will contain a "0"
  • The T field will be "0" to indicate that no packet trailer is present
  • The TSI field will contain "00" to indicate that no time data is provided (subject to change)
  • The TSF field will contain "00" to indicate that no time data is provided (subject to change)
  • The count field is an incrementing could to so can know if you have dropped a packet. It can generally be ignored.
  • The stream and class identifiers will contain the values shown in the picture at the right

Details on the VITA-49 standard can be obtained through the VITA Website.

Meters are sent as a 32-bit value with the upper 16-bits being the meter identifier and the lower 16-bits being the meter value. The units field sent with the context packet discusses how each meter value field should be interpreted.


SAVED TEXT --- IGNORE

The basic format for a metering packet is shown below. The meter contextual information is a series of ASCII text assignments holding meter description information.

Packet for holding meter context information
  • The C field will be set to "1" to indicate that a class identifier will be sent.
  • The R fields are reserved and will contain a "0"
  • The T field will be "0" to indicate that no packet trailer is present
  • The TSI field will contain "00" to indicate that no time data is provided (subject to change)
  • The TSF field will contain "00" to indicate that no time data is provided (subject to change)
  • The count field is an incrementing could to so can know if you have dropped a packet. It can generally be ignored.
  • The stream and class identifiers will contain the values shown in the picture at the right

Details on the VITA-49 standard can be obtained through the VITA Website.

Each piece of context information is a name-value pair. The name is in a dotted hierarchal format. The components of the hierarchy are as follows:

  1. The top-level of the hierarchy is always the meter identifier. The meter identifier is a 16-bit number that is used to tie the meter value to it's context information in this packet. It must be preserved so that it may be matched with the metering data itself. These generally start with 0 and go through the number of meters, but it is possible that numbers could be skipped.
  2. The next level is the source identifier (a slice for example).
  3. The next level is the source ordinal (0 for slice 0, for example). The ordinal may be provided in decimal or hexadecimal, but if provided in hexadecimal it will be proceeded with a 0x.
  4. The last level is the meter field that is being described.