================================================================================
  MSI Wireshark Dissector - User Documentation
  Weiss Robotics GmbH & Co. KG
  Lua Dissector for the Motion Stream Interface (MSI)
================================================================================

OVERVIEW
--------
  This Wireshark Lua dissector adds protocol decoding support for the
  Weiss Robotics Motion Stream Interface (MSI).

  It decodes:

    - MSI Command packets (UDP port 5005)
    - MSI Feedback packets (32-byte payload)
    - Command parameters (OPEN, ENABLE, POINT, etc.)
    - Feedback fields (position, speed, force, current, flags, timestamps,
      state, status, buffer fill level)
    - Individual flag bits including buffer underrun
    - Human-readable operating state and status codes

  The dissector is designed for real-time debugging and high-frequency
  streaming scenarios.

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

REQUIREMENTS
------------
  - Wireshark 3.6 or newer (Lua enabled)
  - Lua support enabled in Wireshark (default in standard installations)

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

INSTALLATION
------------
  Copy the file msi.lua to your Wireshark plugins directory:

  Windows:
    %APPDATA%\Wireshark\plugins\

  Linux:
    ~/.local/lib/wireshark/plugins/

  macOS:
    ~/.config/wireshark/plugins/

  Restart Wireshark after copying the file.

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

PROTOCOL REGISTRATION
---------------------
  The dissector automatically:

    - Registers MSI commands on UDP port 5005
    - Uses heuristic detection for MSI feedback packets (32 bytes)

  If feedback packets are not decoded automatically:

    1. Right-click a packet
    2. Select "Decode As..."
    3. Choose "MSI" for the corresponding UDP port

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

DECODED MSI COMMANDS
--------------------
  The following commands are decoded:

    - OPEN
    - ENABLE
    - POINT
    - DISABLE
    - CLOSE

  Info Column Format (Compact Mode):

    OPEN   | period=10 ms | ip=192.168.1.10 | port=5006
    ENABLE | base_period=1 ms
    POINT  | pos=25.000 mm | F=80.000 N | seq=42

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

DECODED MSI FEEDBACK
--------------------
  Feedback packets are 32 bytes long and include:

    - Position
    - Speed
    - Motor current
    - Estimated force
    - Flags (bit-decoded)
    - Acknowledged sequence number
    - Timestamp
    - Operating state (text + numeric)
    - Status code (text + numeric)
    - Interpolation buffer fill level

  Info Column Format:

    pos=97.02 | v=0.00 | F=0.0 | I=0.0 | 0x80000001 | t=13440 | DISABLED | E_SUCCESS | buf=0

  If status != E_SUCCESS, the packet is automatically highlighted in the
  Info column:

    ERROR: pos=...

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

CUSTOM COLUMNS (RECOMMENDED)
-----------------------------
  To add MSI fields as Wireshark columns:

    1. Go to Edit -> Preferences -> Appearance -> Columns
    2. Click "Add"
    3. Set Type to "Custom"
    4. Enter one of the following field names:

  Recommended columns:

    Title       Field
    ----------  ---------------------------
    MSI pos     msi.fb.current_pos
    MSI speed   msi.fb.current_speed
    MSI state   msi.fb.operating_state_str
    MSI status  msi.fb.status_code_str
    MSI buffer  msi.fb.points_buffered
    MSI seq     msi.point.sequence_number

  At least one MSI packet must be decoded before the fields appear in the
  column list.

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

COLORING RULES (OPTIONAL)
--------------------------
  To highlight MSI error feedback packets:

    Open View -> Coloring Rules -> Add and use the filter:

      msi.fb.status_code != 0

  To highlight buffer underruns:

      msi.fb.flags.buffer_underrun == 1

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

TROUBLESHOOTING
---------------
  Feedback not decoded:

    - Verify packet length is 32 bytes
    - Use "Decode As..." if heuristic detection does not trigger
    - Ensure Lua is enabled in Wireshark

  Script not loaded:

    Check Help -> About Wireshark -> Plugins and confirm that msi.lua
    appears in the plugin list.

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

DISCLAIMER
----------
  This dissector is intended for engineering and diagnostic use when
  developing applications based on the Weiss Robotics Motion Stream Interface.

  It is not an official Wireshark plugin and is provided as a development aid.

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

CONTACT
-------
  For MSI protocol questions, refer to the official MSI Reference Manual or
  contact Weiss Robotics technical support.

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


================================================================================

-------------------
License Information
-------------------

Copyright (c) 2026, Weiss Robotics GmbH & Co. KG
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of Weiss Robotics nor the names of its contributors may
   be used to endorse or promote products derived from this software without
   specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

================================================================================
