I Open Sourced How to Build Your Own Samsung TV Apps

I’ve put a terminal on my Samsung Frame TV and open sourced the code, along with the instructions for building and installing your own apps. The project is called democratizen. I’m keeping the pun.

If I’ve bought a television with a computer inside it, I should be able to write software for it. A dashboard for the house, a clock that looks the way I want, a terminal across the room. I don’t need Samsung to come up with those ideas for me, and I shouldn’t have to wait for an app in its store to get around to doing them.

I wanted to get something of my own running on the Frame, work out the annoying parts, and leave enough behind that another developer could do it without repeating the whole exercise.

The repo has the TV apps, the Mac host for the terminal and the deployment scripts. I’ve also documented what to install, how to get the TV listening, which certificates you need, and what to check when an install fails. Having it work on my computer isn’t much use to someone cloning the repo for the first time.

My test device is a Samsung Frame QA43LS03DAWXXY, running Tizen 9.0. That’s what I’ve tested. If you’ve got another model or firmware version, I’d like a report of what works on it.

Getting onto the TV starts with Developer Mode. Samsung has an official development workflow, although I doubt many people opening their TV’s Apps screen are going to find it by accident. On this Frame, you open Apps, scroll to App Settings and enter 12345 with the remote. That brings up a Developer Mode popup where you enter your computer’s local IP address.

Then you reboot. In my case, standby wasn’t enough. I had to fully disconnect the power and start the TV again before the development connection opened. That’s a small detail when you know it, and a great way to waste time when you don’t.

The computer connects through Samsung’s Smart Development Bridge, or SDB. From there you can install and launch a signed web app. Tizen Studio supplies the tools, and Samsung’s Certificate Manager creates the signing profile for your TV. You’ll need a Samsung account and the TV’s device ID for that part. I’ve documented the certificate setup, because having the right code doesn’t help much when the TV rejects the package.

A Tizen web app is a fairly familiar thing if you build websites. You’ve got HTML, CSS and JavaScript, plus a config.xml manifest describing the app, its entry page and the permissions it needs. The tools package that into a signed .wgt file for installation.

You can start with plain JavaScript. The small example in the repo is a clock with an OK-button colour change and a Back-button exit. I wanted a boring first test on purpose. Once that shows up on the television, you know the connection, signing and basic remote events are working. After that, change the page and make something more interesting.

Frame Terminal is the more interesting example. It gives me up to eight separate shell sessions on my Mac, with the terminal displayed on the TV. Each session has its own working directory and shell state, so I can leave a command running in one and switch to another. The interface has session names, text-size controls and a strip of useful terminal keys for the remote.

The rendering uses xterm.js, with a Node service on the Mac managing the shell processes. Leaving the TV app doesn’t kill those processes. When I return, the host restores the terminal screen and scrollback. Restarting the host service does end them, so this isn’t a substitute for something like tmux if you need to survive a host restart.

I’ve also added the TV’s own root shell as a second target. I can switch between a Mac session and Bash running on the television, with a TV ROOT label showing where my commands are going. That backend needs the compatible root route enabled first. Its terminal connection goes back to the Mac over pinned TLS, and closing the session checks that its temporary files were removed.

I plugged a USB keyboard into the TV and typed pwd. It ran in the Mac shell. There’s something very satisfying about getting a normal command prompt on a device whose usual interface is a row of streaming apps.

Bluetooth keyboards use the same TV input path, but I haven’t tested a physical Bluetooth keyboard yet. USB typing and Enter are confirmed. The docs keep those results separate, because having code that ought to work and having tried the thing are different claims.

Keyboard handling has a few Samsung-specific wrinkles too. Depending on where focus is, Enter can arrive as the input method’s Done event. Cancelling every keydown event is a good way to stop text appearing altogether. A television also reserves some keys for its own functions, and every button needs a visible focus state if you’re going to reach it with a remote. A desktop browser preview only gets you so far.

The host and TV are paired, and terminal messages are encrypted. I’ve documented that design and its limits as well. A connection that can type commands into my Mac deserves more thought than an open socket on the home network. Built terminal widgets contain their installation’s pairing credentials, so the public repo contains source and build instructions. You build your own paired copy.

There’s also an optional root-access guide. The root implementation comes from chris-ritsen/samsung-tv-root, which deserves the credit for that work. My Frame needed a small runtime-detection patch because its dotnet launcher rejected a command the tooling expected it to support. That patch and the pinned upstream revision are in the repo.

Installing the web apps uses Developer Mode and signing. Root is a separate route, useful for investigating the TV itself, and its compatibility needs checking on the particular device. I don’t want someone thinking they have to start messing with privileged TV commands just to put a clock on the screen.

This is why I wanted to publish the whole setup. I can spend an afternoon getting my own TV doing something useful, but the next person should get to start with a working example and the mistakes already written down. If they’re comfortable with JavaScript, they can spend their time on the app they wanted to build.

I like the idea of a Frame showing a dashboard that talks directly to things on my home network. Someone else might want a photo display using their own folders, a music controller, a build-status screen or a timer they can operate from the sofa. Those are ordinary uses for a computer attached to a large screen. We already paid for the computer and the screen.

democratizen is on GitHub under the MIT licence. Start with the small app, then change it. If you get it running on another Samsung model, open a compatibility report with the model, firmware and what you tested. I’d be interested to see what people put on their TVs once they’ve got their own code on the screen.