Upload Investigation Report: 2018 Samsung Frame TV

gistfile1.md

Upload Investigation Report: 2018 Samsung Frame TV

Summary

After extensive investigation, we've confirmed that direct API uploads do not work on the 2018 Samsung Frame TV (UE55LS03N) with firmware T-KTM2DEUC-1341.2 and Art API version 0.97. All upload attempts via the samsungtvws library fail with error code -1, while the SmartThings mobile app successfully uploads images.

Environment Details

• TV Model: UE55LS03NXXC (2018 Frame TV, 18_KANTM2_FRAME)
• Firmware: T-KTM2DEUC-1341.2
• Art API Version: 0.97
• Resolution: 3840x2160
• Python Library: samsungtvws 3.0.3 (xchwarze fork)

Symptoms

• All other Art API functions work correctly (list, delete, select, get_current, etc.)
• Upload returns immediate error -1 from TV before any image data is transferred
• SmartThings mobile app successfully uploads images
• TV responds with: {"error_code": "-1"} immediately upon receiving upload request

Investigation Steps

1. Library Version Testing

Tested multiple versions of the samsungtvws library:

• xchwarze 3.0.3 (latest)
• NickWaterton 3.0.5 (Frame-focused fork)
• Standard 2.6.0 (older version)
• Both sync and async APIs

Result: All versions fail with error -1

2. Connection Method Variations

Tried various connection approaches:

• Different connection names ("SmartThings", "Pixel Pro", "DebugUploader")
• Fresh token deletion and re-authentication
• Different matte styles and parameters
• No matte parameter
• Various timeouts and delays

Result: All approaches fail with error -1

3. Network Configuration Testing

Initial Setup

• TV: Ethernet (wired connection)
• Computer: WiFi
• Connection: Same router/subnet

Result: Upload fails

WiFi-Only Setup

Based on community reports suggesting both devices need WiFi, changed to:

• TV: WiFi connection
• Computer: WiFi (same network)
• Connection: Same SSID and subnet

Result: Still fails with error -1

4. Network Traffic Analysis

Captured network traffic during successful SmartThings upload to understand the communication pattern.

Capture Details

• Interface: WiFi (en0)
• Filter: Phone IP and TV IP
• Duration: Complete upload cycle via SmartThings app

Key Findings

Direct Communication Analysis:

TCP packets between phone and TV: 0
UDP packets between phone and TV: 0
Total packets between phone and TV: 0

Traffic Observed:

• mDNS discovery broadcasts (port 5353)
• SSDP/UPnP announcements (port 1900)
• No WebSocket connections (port 8001/8002)
• No HTTP/HTTPS connections between devices
• Zero direct device-to-device communication

Conclusion

SmartThings uses cloud-based upload, not direct local API:

1. Mobile app uploads image to Samsung cloud servers (HTTPS)
2. TV pulls image from Samsung cloud
3. No local network communication for the actual image transfer

This explains why:

• ✅ SmartThings works (uses Samsung's cloud infrastructure)
• ❌ Direct API fails (Samsung has disabled/restricted it on this model)

Root Cause

The 2018 Frame TV firmware (T-KTM2DEUC-1341.2) with Art API 0.97 does not support direct local API uploads, despite supporting other Art API operations. Samsung appears to have:

1. Intentionally restricted direct API uploads on older Frame models
2. Routed all uploads through their cloud infrastructure for SmartThings
3. Maintained other API functions (list, delete, select) for backward compatibility

Community Evidence

GitHub Issue

xchwarze/samsung-tv-ws-api #130 reports the same issue:

• Same TV model (UE55LS03N)
• Same API version (0.97)
• Same firmware (T-KTM2DEUC-1341.2)
• Same error (-1 on upload)

Samsung Community Forums

Multiple users report upload issues with 2018-2019 Frame models, with common themes:

• WiFi-only requirement (both devices on WiFi, not Ethernet)
• Intermittent failures even when requirements met
• USB method recommended as workaround

Workarounds

1. USB Upload (Most Reliable)

Copy images to USB drive and plug into TV's One Connect box:

1. Format USB drive as FAT32 or exFAT
2. Create folder structure (optional)
3. Copy JPEG/PNG files to USB
4. Plug into One Connect box
5. TV will detect and import images

Pros: Works reliably, supports bulk uploads Cons: Requires physical access to One Connect box

2. SmartThings App (Current Working Method)

Continue using the Samsung SmartThings mobile app:

• Works via Samsung's cloud infrastructure
• Supports image upload with matte selection
• No API limitations

Pros: Works reliably, official support Cons: Requires mobile device, cloud-dependent, not scriptable

3. Phone Hotspot Method

Temporary workaround reported by some users:

1. Create WiFi hotspot on phone
2. Connect TV to phone's hotspot
3. Upload via SmartThings on same phone
4. Reconnect both devices to home network

Pros: May work when other methods fail Cons: Complex setup, temporary solution

Recommendations

For This Project

Given the findings, I recommend:

1. Document the limitation in README with clear model/firmware compatibility notes
2. Add USB upload guide as the primary method for 2018 models
3. Keep API code for newer models that may support it
4. Add pre-upload validation that checks API version and warns users of older models

For Users with 2018 Frame TVs

• Use USB upload for reliable bulk uploads
• Use SmartThings app for occasional single images
• Don't expect API uploads to work on firmware 1341 / API 0.97

For Users Considering Purchase

If API/scripted uploads are important:

• Check firmware version and API version before purchase
• Newer models (2020+) appear to have better API support
• Consider this limitation when evaluating the Frame TV

Technical Details for Developers

Error Response

{
  "request": "send_image",
  "file_type": "jpg",
  "connection_id": 486359100,
  "d2d_mode": "socket",
  "image_date": "2026:02:16 22:07:31",
  "matte_id": "modern_warm",
  "portrait_matte_id": "modern_warm",
  "file_size": 3128955
}

TV Response: {"error_code": "-1"} (immediate, before image data transfer)

API Version Check

tv = SamsungTVWS(host='TV_IP')
api_version = tv.art().get_api_version()
# Returns: "0.97" on affected models

Workaround Code (Not Successful)

The following approaches were attempted but did not resolve the issue:

• Checking for successful upload despite error -1
• Pre-setting art mode before upload
• Freeing up storage space
• Longer timeouts and delays
• Different image sizes and formats

Related Issues

• xchwarze/samsung-tv-ws-api #130 - Same TV model with identical symptoms
• Multiple Samsung Community forum threads about upload failures on 2018-2019 models

Conclusion

The 2018 Samsung Frame TV (UE55LS03N) with firmware 1341 and Art API 0.97 does not support direct local API uploads. This is a firmware limitation, not a bug in the samsungtvws library. Users with this model should use USB upload or the SmartThings app for uploading images.

---

Investigation conducted using packet capture analysis, multiple library versions, various configuration approaches, and community research. All sensitive information (IP addresses, device identifiers) should be redacted before posting publicly.