The Problem

Home‑owner developers need a reliable, local‑host tool to keep Samsung Tizen TVs in a developer‑mode state, remap remote input, and gain temporary root for diagnostics. Existing vendor tools are closed, fragile, and lack repeatability. This repo supplies a portable, open‑source suite that performs the same volatile‑root workflow on two specific TV models (QN90B and QN90F) and exposes a CLI for day‑to‑day use.

What This Does

The package implements the full root‑chain: it communicates with the TV over the sdb protocol, runs a custom agent that dumps and decrypts firmware, and then launches a small payload that gives the host process root privileges. Files under src/ expose the high‑level API (archive_root.py, remote.py, display.py, qne90f.py, etc.), while tools/ contains the build helpers for payloads. The swu/ folder bundles the code that extracts and verifies SWU firmware keys. The CLI (src/samsung_tv_root/cli.py) stitches these together into user‑friendly commands such as archive-root and remote-control.

How It Is Wired

Entry Point – src/samsung_tv_root/__main__.py imports cli.main from src/samsung_tv_root/cli.py. CLI Flow – cli.main parses arguments, creates a sdb connection (src/samsung_tv_root/sdb.py), and dispatches to sub‑commands. Root Chain – The archive_root command calls archive_root.run, which uses sdb to pull a memory image, then spawns the payload defined in payloads/. The payload, compiled from the C# projects in payloads/common, is launched via a Process created in src/samsung_tv_root/root_agent.py. Remote Handling – remote.py wraps the TV’s remote‑input API; it calls control_api (src/samsung_tv_root/control_api.py) which sends JSON messages over the sdb socket. Display & Volume – display.py and volume.py issue similar control calls through control_api. Firmware Extraction – swu/swu_firmware_decrypt.py runs after a successful root launch; it reads the encrypted SWU file, decrypts it, and writes the keys to ~/.samsung-tv-root/keys. The only external effect is network traffic on the TV’s local IP and file writes in the user’s home directory. The graph is acyclic; the only hub is sdb.py, which all control commands depend on.

How To Use It

Setup

git clone https://github.com/moses-y/samsung-tv-root
cd samsung-tv-root
uv sync   # installs deps from pyproject.toml

uv (or pip install -e .) satisfies the pure‑Python parts; the C# payloads are built automatically by Makefile when make payloads is run.

Configuration No external files are required for the demo. If you want to store extracted SWU keys, create ~/.samsung-tv-root/keys/ and set SDB_KEY_DIR to that path; otherwise the tool writes there automatically.

Running It

# Acquire root on a connected TV
python -m samsung_tv_root archive-root

# Remap remote input
python -m samsung_tv_root remote-control --action remap --target archlinux

# View current volume
python -m samsung_tv_root volume status

The README lists additional flags; for example, --device <ip> can override the default auto‑discovered TV address.

Real‑World Use

A typical home lab runs a nightly script:

#!/usr/bin/env bash
python -m samsung_tv_root archive-root
python -m samsung_tv_root remote-control --action remap --target archlinux

The script starts on boot, keeps the TV in a stable state, and allows the host to control media playback via the Tizen CDP API, all without opening the TV to the internet.

Code Health & Issues

  • Dependency reproducibility – pyproject.toml lists dependencies but no lockfile (uv.lock exists, but not checked into CI).
  • Missing CI coverage – The .github/workflows only runs a generic build; no test matrix or coverage reports.
  • License – LICENSE is MIT; no signs of dual‑licensing complications.
  • Untested paths – The swu helpers are not exercised by the current test suite (tests/test_swu.py covers only interface stubs).

No static‑analysis block is present; deeper tooling would be required to surface additional issues.

The Bottom Line

The repository delivers a functional, open‑source solution for volatile root on two specific Tizen TVs. It is lightweight, with a clear entry point and minimal external dependencies. The code is well‑structured but would benefit from additional CI coverage and a dedicated lockfile for reproducibility. It is best suited for operators who own the exact hardware and wish to automate root acquisition and remote control without maintaining proprietary tools.