Websocket Viewer

The WebSocket Viewer is a powerful diagnostic tool in KOS Studio that provides real-time visibility into WebSocket message traffic between your application and the device. When working with KOS applications, understanding the communication flow between the UI/Model layer and the backend is essential for debugging, performance analysis, and troubleshooting. The WebSocket Viewer captures and displays all WebSocket messages traversing through the router, allowing you to see HTTP requests and responses, broker messages (Topics), and asynchronous operation messages as they happen.

This tool is especially valuable when working with physical devices where you don’t have direct access to browser developer tools, or when you need to understand KOS-specific protocols and conventions that standard browser tools don’t recognize. By consolidating all messages in a single interface with intelligent correlation between related messages, the WebSocket Viewer makes it easy to trace complex operations and diagnose issues.

Understanding WebSocket Communication in KOS

KOS applications communicate with devices through WebSocket connections, using a sophisticated protocol that includes several message types:

HTTP Requests and Responses
When your application needs data or wants to perform an operation, it sends HTTP requests through the WebSocket connection. The device responds with corresponding HTTP responses containing status codes and data.

Broker Messages (Topics)
KOS uses a publish-subscribe pattern where the device publishes events to topics, and applications subscribe to receive those events. These broker messages carry real-time state updates from the device.

Asynchronous Operation Messages
Long-running operations generate messages as they progress. The WebSocket Viewer shows these messages, allowing you to see how operations communicate with the backend.

Subscriptions
When your application subscribes to device events or topics, subscription messages are sent to establish these connections. The WebSocket Viewer tracks these subscriptions.

Aliases
KOS uses aliases to simplify addressing and routing. The WebSocket Viewer displays alias-related messages to help you understand message routing.

Why WebSocket Viewer Matters

Real-Time Visibility
See messages as they flow between your application and the device, making it immediately clear what’s happening during any operation.

Message Correlation
Unlike standard network tools, WebSocket Viewer understands KOS protocols and automatically correlates related messages—showing you which response belongs to which request, which operation messages resulted from a specific request, and vice versa.

Device Troubleshooting
When working with physical devices where browser developer tools aren’t available, WebSocket Viewer provides the visibility you need to diagnose issues.

Protocol Understanding
Standard tools like Chrome DevTools don’t understand KOS-specific message formats and conventions. WebSocket Viewer presents this information in a way that makes sense for KOS development.

Consolidated View
As you work across multiple tools (Ingredient Assignment, Configuration Viewer, Future Tracer, etc.), all their WebSocket traffic appears in a single interface, making it easy to understand the complete picture.

Accessing the WebSocket Viewer

Opening the Tool

  1. Log into KOS Studio
  2. In the Connection Manager window, locate your running image (connected to a simulator or device)
  3. Find the Active Tools section for that connection
  4. Click + Start New Tool
  5. Select WebSocket Viewer from the dropdown menu

Note: The WebSocket Viewer is only available for active connections to running images or devices.

Understanding the WebSocket Viewer Interface

When you first open the WebSocket Viewer, you’ll see an empty state with the message “No data is available to be shown.” The tool is ready to capture messages as soon as you perform operations on the device or in other tools.

Viewing WebSocket Messages

Automatic Message Capture

Once the WebSocket Viewer is open, it automatically captures all WebSocket traffic related to your running image. As you work with other tools or perform operations, messages appear in real-time.

Message Information

Each message in the table displays:

Type
The category of WebSocket message:

  • request: HTTP requests sent to the device
  • response: HTTP responses from the device
  • subscription: Topic subscription messages
  • broker: Broker system messages
  • futures: Messages related to asynchronous operations
  • topics: Published topic events from the device
  • aliases: Alias configuration and routing messages

Details
Specific information about the message, such as the request path, topic name, or operation identifier.

Status
HTTP status codes for response messages (200, 400, 500, etc.). This field is blank for message types other than responses, as status codes only apply to HTTP responses.

Source
The source address (Src-addr) where the message originated.

Destination
The destination address (Dst-addr) where the message was sent.

Timestamp
The time when the message was captured, helping you understand the sequence and timing of operations.

Automatic Scrolling

By default, the WebSocket Viewer automatically scrolls to show the latest messages as they arrive. This keeps the most recent activity visible, which is helpful when monitoring ongoing operations.

Lock Scroll Feature:
When you need to examine specific messages without the view constantly moving, enable the Lock Scroll toggle:

  • Click the “Lock Scroll” toggle button in the header
  • The view will stop automatically scrolling to show new messages
  • New messages continue to be captured and added to the list
  • You can manually scroll to view any part of the message history
  • Disable Lock Scroll to resume automatic scrolling

Understanding Message Relationships

One of the most powerful features of the WebSocket Viewer is its ability to show relationships between messages. This helps you understand the complete flow of an operation.

Request-Response Correlation

When you select a request message, the WebSocket Viewer helps you identify its corresponding response:

  • The message details show the request information
  • Related response messages are clearly indicated
  • You can trace the complete request-response cycle

When you select a response message, you can see:

  • Which request triggered this response
  • The timing between request and response
  • Any other messages related to that request

Operation Message Relationships

Complex operations generate multiple messages as they progress. When you select an operation-related message, you can see:

  • The original request that initiated the operation
  • All subsequent related messages
  • The complete progression of the operation

Conversely, when you select a request that resulted in an async operation, you can see all the messages that followed.

Why Message Correlation Matters

Without correlation, you’d need to manually match request and response IDs or tracker values to understand which messages relate to each other. The WebSocket Viewer does this automatically, saving significant time and reducing errors when troubleshooting complex operations.

Viewing Message Details

To see comprehensive information about any message:

  1. Click on the message in the main table
  2. A sliding drawer appears on the right side of the window
  3. The details panel displays complete information about the selected message

Details Panel Structure

Header Section:

  • Message Type Icon: Visual indicator of the message type
  • Message Name: The full message identifier (e.g., “kos.http.request”)
  • Close Button: Close the details panel

Headers Information (Expandable accordion):

Shows the appropriate key values for selected websocket message.

Body Section:

  • Complete content of the message body
  • Shows the actual payload being sent or received

Working with Details While Browsing

The details panel and main message list work independently:

  • While viewing message details, you can still scroll the main message list
  • You can select a different message to see its details
  • Filtering and searching continue to work
  • New messages continue to appear in the main list
  • All features remain active while the details panel is open

Copying Information

Copy Individual Fields:
Select any individual field in the Headers section and double click copy just that value.

Managing Message Display

Clearing Messages

When you want to focus on new operations without the clutter of previous messages:

  1. Click the Clear List button in the header
  2. All captured messages are immediately removed
  3. The WebSocket Viewer returns to its empty state
  4. New messages are captured as operations occur

This is particularly useful when you want to isolate the messages from a specific operation or test scenario.

Filtering Messages

To focus on specific types of messages:

  1. Click the Filter button in the header
  2. Select which message attributes to filter by:

Type Filters:

  • request
  • response
  • subscription
  • topic
  • future
  • And any other types that appear in your message stream

Status Filters:

  • 200 (Success)
  • 400 (Client Error)
  • 500 (Server Error)
  • And any other status codes that appear

Source Filters:
Filter by source address to see messages from specific origins

Destination Filters:
Filter by destination address to see messages sent to specific targets

  1. Messages that don’t match your filter criteria are hidden
  2. Clear filters to see all messages again

Tips for Effective Use

  • Clear strategically: Clear the message list before performing specific operations you want to isolate
  • Use Lock Scroll when analyzing: Enable Lock Scroll when you need to examine specific messages without the view constantly moving
  • Filter to reduce noise: Apply filters to focus on specific message types or status codes relevant to your investigation
  • Save important captures: Download message captures when you encounter interesting or problematic behavior for future reference
  • Combine with other tools: Use WebSocket Viewer alongside other diagnostic tools for comprehensive troubleshooting
  • Watch for patterns: Look for repeated message patterns that might indicate loops or inefficient communication
  • Correlate timestamps: Use message timestamps to understand the sequence and timing of complex operations
  • Share KAB files: When collaborating with colleagues, share WebSocket KAB files to provide complete context for issues
  • Check status codes: Quickly scan for red flags like 400 and 500 status codes that indicate errors
  • Understand message flow: Watch the source and destination fields to understand how messages route through your system