Device Troubles

Overview

The Device Troubles viewer is a diagnostic tool in KOS Studio that provides real-time visibility into system issues and errors occurring on your connected device or simulator. In KOS, a “trouble” represents a system issue, error condition, or problem state that needs attention, such as hardware malfunctions, resource depletion, configuration errors, or operational failures. The Device Troubles viewer lets you monitor these issues as they occur, understand their details, and resolve them when possible, even before you have a customer-facing UI to handle them.

This tool is essential during application development and troubleshooting, providing immediate feedback about system health and allowing you to address issues proactively. It bridges the gap between backend system diagnostics and practical problem resolution.

Key Features

Real-time trouble monitoring: Troubles appear in the viewer the moment they are recorded, with no manual refresh required. This lets you see the live state of your device as you exercise different code paths, dramatically reducing the feedback loop during development.

Works on hardware and simulators: You can use Device Troubles whether your application is running on actual device hardware or inside a KOS simulator. This means you can test trouble handling even before you have access to physical devices.

Full trouble details and JSON inspection: Selecting any trouble in the list reveals its complete JSON blob — the raw data payload behind the trouble. This gives you immediate access to all parameters and nested fields without needing to add extra logging or breakpoints, making root-cause analysis much faster. 

Side-by-side comparison: You can select multiple troubles at once and view their JSON blobs in parallel sections. This is especially useful when you need to compare similar conditions or understand how different trouble types relate to each other.

Resolution actions: For resolvable troubles, Device Troubles surfaces the available actions right alongside the trouble details. You can trigger a resolution without needing to know which underlying API to call — the trouble itself handles the action. You can also bulk-resolve all resolvable troubles at once to quickly clear your workspace.

Copy to clipboard: Any trouble’s JSON blob can be copied to your clipboard with a single action and pasted directly into bug reports, documentation, or other tools. The copied data is always properly formatted and preserves all special characters.

Accessing the Device Troubles 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. Ensure the image is in an active state
  4. Find the Active Tools section for that connection
  5. Click + Start New Tool
  6. Select Device Troubles from the dropdown menu

Note: There should only be one Device Troubles viewer open per running device.

Viewing Trouble Details

Opening Trouble Details

To see comprehensive information about a specific trouble:

  1. Click on a trouble from the troubles list
  2. The trouble details expand to show complete information
  3. The trouble metadata remains visible in the table
  4. The whole JSON blob appears, showing all diagnostic data

Trouble Detail Information

When you select a trouble, you see:

Visible Metadata:

  • Trouble ID: The unique identifier
  • Trouble Type: The category or kind of issue
  • Timestamp: When it was recorded
  • Resolvability: Whether the trouble can be resolved through software action
  • Status: Current state (unresolved, resolving, resolved)
  • JSON Blob:The complete trouble data in properly formatted, readable JSON.

Closing Trouble Details

To return to the troubles list view:

  1. Click the close action in the trouble details
  2. The JSON blob view closes
  3. The trouble remains in its original position in the list
  4. Any applied filters are preserved

Working with Multiple Troubles

Selecting Multiple Troubles

To compare or analyze multiple troubles simultaneously:

  1. Select multiple troubles from the list
  2. Each selected trouble is visually indicated
  3. All selected troubles display their details together
  4. You can close individual troubles while keeping others open

Viewing Multiple Trouble Details

When you have multiple troubles selected:

Parallel Display:

  • Each trouble displays in its own section
  • All sections are visible simultaneously
  • You can scroll through the view to see all troubles
  • JSON blobs are displayed in parallel for easy comparison

Individual Control:

  • Each JSON blob is properly formatted and syntax-highlighted
  • Expand and collapse each JSON blob independently
  • Expanding or closing one trouble doesn’t affect others
  • Each trouble maintains its own state

This parallel view makes it easy to:

  • Compare similar troubles to identify patterns
  • See the sequence of related issues
  • Understand cause-and-effect relationships
  • Document multiple issues in a single session

Copying Trouble Data

When you are viewing a trouble’s detail panel, you can copy its entire JSON blob to your clipboard. This is useful for including trouble data in bug reports, sharing details with colleagues, or pasting into external documentation or analysis tools.

Copy JSON Blob:

  1. View the trouble details to see the JSON blob
  2. Click the copy action for the JSON blob
  3. The entire JSON blob is copied to your clipboard
  4. The JSON is properly formatted and valid
  5. You receive a confirmation message

Copy Action Visibility:

  • The copy action is clearly visible when viewing the JSON blob
  • The action is consistently positioned across all troubles
  • Confirmation appears briefly after successful copy

Using Copied Data:

  • Paste the JSON into external applications
  • The content matches the original value exactly
  • Format is preserved and usable
  • Special characters are properly maintained

This feature is particularly valuable for:

  • Creating detailed bug reports
  • Sharing diagnostic information with colleagues
  • Documenting issues for future reference
  • Analyzing trouble patterns offline

Resolving Troubles

Available Resolution Actions

When viewing a trouble:

  • Available resolution actions are displayed clearly
  • The primary action is “Resolve”
  • Unavailable actions are hidden
  • Non-resolvable troubles don’t show resolution options

Initiating Resolution

To resolve a trouble:

  1. Single Trouble Resolution:
    • View an unresolved trouble with resolution action available
    • Click “Resolve”
    • A clear visual indicator shows the resolve action has begun
    • The trouble status changes to show resolution is in progress
    • The resolving trouble remains in the list but is visually distinguished
  2. Bulk Resolution:
    • Trigger a bulk resolve action for multiple troubles
    • All resolvable troubles are processed simultaneously
    • You see individual progress for each trouble
    • Successfully resolved troubles are indicated

Resolution Progress and Completion

During Resolution:

  • The trouble status updates to show “Resolving”
  • The trouble is visually distinguished from unresolved troubles
  • The trouble remains in the list so you can monitor progress

After Successful Resolution:

  • The trouble status changes to “Resolved”
  • The resolved trouble remains visible for 1.5 seconds
  • The trouble automatically disappears from the list
  • This brief persistence lets you confirm the resolution before it clears

Resolution Errors: If a trouble cannot be resolved successfully:

  • You receive appropriate error feedback
  • The trouble returns to an unresolved state
  • Error information helps you understand why the resolution failed
  • You can address the underlying issue and try again

Understanding Resolution Failures

When troubles cannot be resolved:

  • Review the error information to understand why
  • Check if physical intervention is needed
  • Verify system conditions meet resolution requirements
  • Use the diagnostic information to change code or configuration
  • Document issues to prevent end users from experiencing them

Real-Time Updates

The Device Troubles viewer provides live updates as troubles are recorded:

Automatic Updates:

  • New troubles appear automatically in the list
  • New troubles are positioned at the top (most recent first)
  • You don’t need to manually refresh the view
  • The list updates in real-time as your system operates

Session Persistence:

  • Troubles persist even if you navigate away from the viewer
  • When you return, all previously recorded troubles are still visible
  • Troubles maintain their chronological order
  • Unresolved troubles remain visible across sessions

This real-time visibility allows you to:

  • See issues as soon as they occur
  • Correlate troubles with specific actions or operations
  • Identify cascading failures or related issues
  • Respond immediately to critical problems

Offline Behavior

The Device Troubles viewer’s behavior depends on what type of connection is lost:

KOS Studio Server Offline (Device Still Connected)

When KOS Studio loses connection to the KOS Server but you still have a device connection:

Available:

  • View all loaded troubles
  • Receive new real-time troubles from the device
  • Execute resolution actions
  • Full functionality continues

Indicators:

  • Standard offline indicators appear per KOS Studio conventions
  • Tool operates normally despite server disconnection

Tips for Effective Use

  • Keep it open during development: The real-time updates make it invaluable for immediate feedback
  • Use multiple trouble selection: Compare related troubles to identify patterns
  • Copy JSON for documentation: Detailed trouble data makes better bug reports
  • Test resolution actions early: Verify your resolution logic works before deployment
  • Watch for cascading failures: Multiple troubles in quick succession may indicate a root cause
  • Note non-resolvable troubles: These indicate areas needing physical intervention or code changes
  • Correlate with other tools: Use alongside WebSocket Viewer or Analytics Viewer for complete picture
  • Document patterns: Track recurring troubles to identify systemic issues