08-MAY-2020 Matthew J. Wolf <matthew.wolf.hpsdr@speciosus.net>

The OpenHPSDR-USB Plug-in for Wireshark is written to disassemble the 
OpenHPSDR USB frames over IP protocol. The protocol is also is 
referred to as "Protocol 1".

The protocol is definded in the documents and web page cited below.
 
[1] Harman, Phil. and Martin, Joe. HPSDR - USB Protocol V1.60. 2019. [Online]. 
    Available at: 
    https://github.com/TAPR/OpenHPSDR-SVN/blob/master/Documentation/USB_protocol_V1.60.doc
    [Accessed: 4 March 2020].

[2] Harman, Phil. Metis - How it Works V1.33. 2015. [Online].
    Available at:
    https://github.com/TAPR/OpenHPSDR-SVN/blob/master/Metis/Documentation/Metis-%20How%20it%20works_V1.33.pdf
    [Accessed 3 May 2019].

[3] Softerhardware. "softerhardware/Hermes-Lite". GitHub. [Online].
    Available: 
    https://github.com/softerhardware/Hermes-Lite/wiki/Protocol-Coverage
    [Accessed: 6 May 2019].

[4] Softerhardware. "softerhardware/Hermes-Lite2". GitHub. [Online].
    Available: 
    https://github.com/softerhardware/Hermes-Lite2/wiki/Protocol
    [Accessed: 06 June 2019].

Version 0.4.1
 - First version that is a candidate for release.
 - No changes from version 0.4.0
 - Binaries compiled with Wireshark 3.2.3 

Version 0.4.0
  - Protocol version 1.60 changes.
   -- Added "C0 Type" for "2ND Alex, Firmware Envelope Gain"
  - Renamed preference for Hermes-Lite to a preference for Hermes-Lite1
  - Added a preference to display the Hermes-Lite2 additions and changes to the
    protocol.
  - Added support for undefined "C0 Types".
  - Length of "C0 Types" corrected. The way the "C0 Types" are listed in the
    protocol document was the source of my confusion.
    -- End point 2 changed from 8 bit numbers to 7 bit numbers.
    -- End point 4 changed from 8 bit numbers to 5 bit numbers.
  - Included decimal number in the display of "C0 Types".
  - Added a preference to display the Hermes-Lite2 additions and changes to the
    protocol.
  - Opinion: Hermes-Lite2 addition of RQST and ACK creates a new protocol that
             is not compatible with the "standard" protocol. The length of
             critical fields are changed. It is bad practice of have a
             field have multiple lengths. End point 2 "C0 type" is changed
             to 6 bits. End point 6 "C0 type" is changed to 4 bits. When ACK
             is high end point 6 "C0 type" is 6 bits because the "Dot" and
             "Dash" bits are removed and reassigned to "C0 Type". The
             Hermes-Lite2 protocol specification refers to the "C0 Type" as the
             word memory map and or addresses. The standard protocol
             specification refers to the "C0 Type" as bits in
             "the first C&C byte(C0)".

-------------------------------------------------------------------------------

General Notes
-------------

Only use the plug-in disassembly of the protocol as tool. Do not rely on it to
tell you exactly what is happening with the SDR or the host application. This 
plug-in calculates numbers for some objects. One example is the TX forward 
power. Only use the calculated number if you know for a fact that the SDR is 
truly transmitting. If the SDR is not transmitting and the plug-in reports a 
positive value for the forward power. Disregard the calculated power.


The disassembler in the plug-in attempts to identify which IQ bits belong to 
which receiver when there are multiple receivers. It will also identify the pad
bits. The disassembler only records the number of receivers when it believes the 
SDR is not sending IQ data. I had add this limitation because some of the host 
applications stop sending the correct number of receivers in the USB end point 2 
frames after it sends the start command to the SDR.

The disassembler believes the SDR is not sending IQ data when it first starts to 
disassemble the datagrams. If the disassembly is started after
the IQ start command is sent, the number of receivers in the USB end point 2 C&C 
C0=0x00 USB frame will be used for the number of receivers. This also means when
the host application does not report the correct number receivers. The 
disassembler will not be able to correctly identify which IQ bits go with which 
receivers.       

The disassembler will stop recording the number of receivers when it sees a IQ 
start command. It will not record number of receivers again until it sees a stop
command. This is a work round for host applications that stop reporting the 
correct number of receivers. The application has to tell the SDR the correct 
number of receivers before it sends the start command. After the start command, 
I assume the SDR does not need the application to report the correct number of 
receivers.

OK, if you do not care about the last paragraph. What you need to do with 
applications that do not all send the correct number of receivers is:
1. Start the packet capture before the host application sends the start command.
2. You need to make sure that you capture the USB end point 2 frame where the 
    host application tells the SDR then number of receivers right before it sends
    the IQ start command
3. Then make sure you capture the host application sending the start command.
4. More simply start the capture before for start the host application! 


There is one item I had to add for misbehaving host applications. Some 
applications send the first USB end point 2 frame late. They add extra empty 
bytes between the end of the sequence number and the start of the USB frame.
The disassembler searches for the first USB sync bytes. When the sync bytes are
not right after the sequence number the disassembler displays a warring that 
there are extra bits. Once the disassembler finds the sync bytes, it 
disassembles the USB frames.

Plug In Preferences
-------------------

There are three configurable preferences in the Wireshark dissector. 

They are all Boolean (on or off) preferences.

-"Strict Checking of Datagram Size"
  Disable checking for added bytes at the end of the datagrams.
  Turning off disables a warning message.

-"Strict Pad Checking"
  Strict checking of the amount of pad bytes at the end of the datagrams.
  When enabled, Wireshark (not the OpenHPSDR dissector) will display
  a "Malformed Packet" error for a datagram without the correct
  number of pad bytes. 
  When disabled, checking is only for one pad byte instead of checking
  for the correct number of pad bytes.

-"End Point 2 Sync Checking"  
  Some Host applications add extra bytes in front of the USB end point 2
  data. When disabled, there will be no checking for the insertion of extra 
  bytes.       

-"Hermes-Lite Command and Control"
  -- MOX repurposed as PTT.
  -- Random toggles RX ADC AGC.
  -- Dither toggles RX LNA gain.
  -- Input attenuator used for preamp.

-"Hermes-Lite2 Protocol"
  -- Bit 7 of C&C Byte 0: RQST, ACK.
  -- ACK HIGH:
     --- Removes Dot and Dash.
     --- EP6 C0 type is 6 bits.
  -- Random toggles Hardware AGC.
  -- Preamp toggles VNA fixed RX Gain.
  -- Time stamp added to number of recevers.
  -- Apollo filter toggles external PTT.
  -- Apollo tunner toggles onboard PA.
  -- Attenuator toggles LNA Gain.
  -- ADC Input attenuator used for LNA Gain.
  -- Addtional C0 types for:
     --- RX 8 (Conflicts with 2ND Alex, Firmware Envelope Gain)
     --- RX 9 to 12
     --- Predistortion
     --- AD9866 SPI
     --- I2C
     --- Extended Write Data

Display Filters
---------------

In Wireshark you can filter packets by using display filters. The display 
filters use fields that are created when the packets are disassembled. I tried
to add fields for every thing in the protocol. A few examples are below.   

hpsdr-u.status == 0x04
-Display filter that will only display the start stop (status 4) datagrams.
 
hpsdr-u.cc.hpf_6-5 == 1 && hpsdr-u.cc.lpf_60-40 == 1
-A filter that will only display datagrams that tell the SDR hardware to enable
 the 6.5 MHZ HPF and the 60/40 meter LPF on Alex. 


The easiest way to find a field name is to click on a item in Wireshark. The 
field label will appear on the bottom of the Wireshark window. You can also 
click on the bytes in the raw display to get the field labels. When you do a
right mouse click on a field, the menu has a has build-in filter options. The 
menu has a "Copy" function that copies the field name to the clip board.