Samsung Electronics logo

Smart TV Control

© 2013 Samsung Electronics Co., Ltd. All rightsreserved.

Table of Contents

In Samsung Web API specifications, there is a set of APIs to control Smart TVs. These features work like the remote controller (a.k.a remocon), keyboard, and mouse. TVController represents a set of features that allow you to control your Samsung TV. It can be discovered using APIs provided by the DeviceFinder API. ViewController is provided for expanded control of the Digital Media Renderer (DMR) for images. A ViewController instance can be obtained by invoking getViewController() through an ImageViewer instance.

Control TV Web Browser

Connect to Smart TV

To control the Web browser on a Samsung Smart TV, you must find a TV controller device in the network by invoking getDeviceList('TVCONTROLLER') and establishing a socket connection using connect() in TVController as shown in the sample code below : 

 
/**
* Get a TV controller instance.
*/
var tvController = null;
var sCB = function (serviceProvider) {
	// Get DeviceFinder instance
	var deviceFinder = serviceProvider.getDeviceFinder();

	// Get TV Controller instance.
	var tvControllers = deviceFinder.getDeviceList('TVCONTROLLER');	
	if (tvControllers.length != 0) {
		tvController = tvControllers[0];
	} else {
		return;
	}

	// Define success callback for connecting to TV Controller.
	function connSCB(controllerID) {
		// TV Controller is connected successfully.
	}
	// Define error callback for connecting to TV Controller.
	function connECB(error, controllerID) {
		console.log(“error: “ + error + “, controller id: “ + controllerID);
	}
	tvController.connect(connSCB, connECB);	
};
		
var eCB = function(e, state){
	console.log("createServiceProvider error: " + e + ", state: "+ state);
};

webapis.allshare.serviceconnector.createServiceProvider(sCB, eCB);

Control TV Web Browser

All the TV remote control buttons are stored in RemoteKey enumeration. If it establishes a connection between the mobile device and TV, you can use several commands to control the TV. The remote controller commands can be called through the sendRemoteKey() function, as shown in the sample code below: 

 
/**
* Control web browser.
*/
var tvController = null;
var sCB = function(serviceProvider) {
	// Get DeviceFinder instance
	var deviceFinder = serviceProvider.getDeviceFinder();

	// Get TV Controller instance.
	var tvControllers = deviceFinder.getDeviceList('TVCONTROLLER');	
	if (tvControllers.length != 0) {
		tvController = tvControllers[0];
	} else {
		return;
	}

	// Define success callback for connecting to TV Controller.
	function connSCB(controllerID) {
		// TV Controller is connected successfully.
		// Send remote key to Smart TV.
		tvController. sendRemoteKey('KEY_CH_UP');
	}
	// Define error callback for connecting to TV Controller.
	function connECB(error, controllerID) {
		console.log(“error: “ + error + “, controller id: “ + controllerID);
	}
	tvController.connect(connSCB, connECB);	
};
		
var eCB = function(e, state) {
	console.log("createServiceProvider error: " + e + ", state: "+ state);
};

webapis.allshare.serviceconnector.createServiceProvider(sCB, eCB);

Also, you can send strings to the TV controller when the keyboard is on screen. 

 
/**
* Control web browser.
*/
// It is assumed that you have obtained a TVController instance. 
var tvController;

// Send the TV keyboard string input. 
tvController.sendKeyboardString('TV TEST');

// Send the end of TV keyboard string input. 
tvController.sendKeyboardEnd();

AllShare related APIs in Samsung Web APIs allow you to move the mouse pointer over the controlled TV. It can be invoked with a set of TVController methods: 

 
// It is assumed that you have obtained a TVController instance. 
var tvController;

// Define common success callback to notify the application an operation request is successful.
function commSCB(playerID){
	console.log(“operation success!”);
}

// Define common error callback to notify the application an operation request failed.
function commECB(error, playerID) {
	console.log(“operation failed!”);
}

/*
* To use below APIs, the TV Controller should be in POINT_BROWSING mode.
*/
// Define success callback for getBrowserMode.
function getBroModeSCB(mode, controllerID) {
	if (mode == 'LINK_BROWSING'){
		// Set browse mode to POINT_BROWSING
		tvController.setBrowserMode('POINT_BROWSING', commSCB, commECB); 
	}
}
tvController.getBrowserMode(getBroModeSCB, commECB); 

//Send the touch down of the TV mouse input.
tvControllers.sendTouchDown();

// Move the mouse pointer.
tvController.sendTouchMove(230,480);

//send the touch up of the TV mouse input.
tvController.sendTouchUp();

//Send the touch click of the TV mouse input which the cursor points.
tvControllers.sendTouchClick();

The TVController interface has some methods for Web browsing, which allow sharing a Web page between the mobile device and TV. You can send the web address from the mobile browser to the TV. Below sample code shows some functions that support Web browsing activities: 

 
//It is assumed that you have obtained a TVController instance.
var tvController;

// Define common success callback to notify the application an operation request is successful.
function commSCB(playerID) {
	console.log(“operation success!”);
}
// Define common error callback to notify the application an operation request failed.
function commECB(error, playerID){
	console.log(“operation failed!”);
}
// Attach the event handlers when user select browser's button remotely
function onClickBrowserButtons(buttonType) {

    switch (buttonType) {

        case 'OPEN' :  
            // Open a web site
            tvController.openWebPage(“http://www.google.com”, commSCB, commECB);
            break;

        case 'CLOSE' : 
            // Close the web page
            tvController.closeWebPage(commSCB, commECB);
            break;

        case 'REFLESH' : 
           // Refresh the web page
           tvController.refreshWebPage(commSCB, commECB);
            break;           
        case 'STOP' : 
            // Stop the current web page on loading
            tvController.stopWebPageLoading(commSCB, commECB);
            break;

        case 'HOME' : 
            // Go home page
            tvController.goHomePage(commSCB, commECB);
            break;

        case 'NEXT' : 
            // Go next web page
            tvController.goNextWebPage(commSCB, commECB);
            break;

        case 'PREVIOUS' : 
            // Go previous web page
            tvController.goPreviousWebPage(commSCB, commECB);
            break;
        }
}  

// Define success callback for getBrowserUrl.
function getBroUrlSCB(url, controllerID) {
	console.log(“Current web site url: “ + url);
}

// Get current web page url.
tvController.getBrowserUrl(getBroUrlSCB, commECB);

// Attach event handlers when user scrolls or zooms the web page remotely.
function onControlPage(controlType) { 
    switch (controlType) {
        case 'SCROLL_UP' :
            // Scroll web page
            tvController.scrollWebPage (“SCROLL_UP”, commSCB, commECB);
            break; 
        case 'ZOOM_IN' : 
            //Zoom web page
            tvController.zoomWebPage(“ZOOM_IN”, commSCB, commECB);
            break; 
    }
}

Scroll direction in a browser is defined in the following table:

Scroll Direction Enumeration Description
SCROLL_UP Scroll up
SCROLL_DOWN Scroll down

Zoom mode in a browser is defined in the following table:

Zoom Mode Enumeration Description
ZOOM_IN Set zoom in
ZOOM_OUT Set zoom out
ZOOM_DEFAULT Set the zoom ratio as default value, i.e 1.0x

Retrieve TV Web Browser Status

To receive notification from the TV Web browser, the application must register an event listener as follows: 

 
// It is assumed that you have obtained a TVController instance.
var tvController;

var tvEventListener = {
	onauthenticationfailed: function(controllerId) {
	    console.log(“Authentication failed!”);
	},
	onconnected: function(controllerId) {
	    console.log(“Connected!”);
	},
	ondisconnected: function(controllerId) {
	    console.log(“Disconnected!”);
	},
	onstringchanged: function(text, controllerId) {
	    console.log(“String changed!”);
	}
};	
var listenerID = tvController.addTVControllerEventListener(tvEventListener);

// Remote listener
tvControllers.removeTVControllerEventListener(listenerID);

To set the input mode of the web browser, you can use setBrowserMode(). setBrowserMode() requires TVControllerBrowserMode as input parameter. The sample code is as follows: 

 
var controller; // it is assumed that a TV controller object is obtained.
function successCB(controllerId) {
     console.log("TV browser mode is successfully set.");
}
function errorCB(error, controllerId) {
     console.log(error.name);
}
try {
     if (controller.isConnected) {
         controller.setBrowserMode("LINK_BROWSING", successCB, errorCB);
     }
} catch (e) {
	console.log(e.name);
}

If you want to get the input mode of the Web browser, you can use getBrowserMode() of the TVController. TVControllBrowserMode can be retrieved in TVControllGetBrowserModeSuccessCallback. The sample code is as follows: 

 
var controller; // it is assumed that a TV controller object is obtained.
function successCB(mode, controllerId) {
     console.log("TV browser mode is " + mode);
}
function errorCB(error, controllerId) {
     console.log(error.name);
}
try {
     if (controller.isConnected) {
         var mode = controller.getBrowserMode(successCB, errorCB);
     }
} catch (e) {
console.log(e.name);
}

setBrowserMode() and getBrowserMode() are valid under the condition when a controlled TV launched a TV browser. Otherwise, it is ignored. Possible values of TVControllerBrowserMode are listed below:

Browse Mode Enumeration Description
POINT_BROWSING Input mode using the mouse cursor
LINK_BROWSING Input mode using the arrow keys
UNKNOWN The unknown mode

Control TV Image Player

Connect to TV Image Player

To control the image player on Samsung Smart TVs, you must find a TV controller device in the network by invoking getDeviceList(“IMAGEVIEWER”) and establishing a persistent connection using connect() in ViewController. Below is a sample code showing the use of the connect() method: 

 
var serviceProvider; // it is assumed that you obtained serviceProvider.
try {
	var imageViewer = serviceProvider.getDeviceFinder().getDeviceList("IMAGEVIEWER");
	var viewController = null;
	if (imageViewer.length > 0) {
		viewController = imageViewer[0].getViewController();
	}

	if (viewController != null) {
		// Developer can control view controller
		// Define a success callback.
		function viewControllerSCB(controllerId) {
			console.log("connection is made properly.");
		}
		// Define an error callback
		function viewControllerECB(error, controllerId) {
			console.log(error.message);
		}
		try {
			viewController.connect(viewControllerSCB, viewControllerECB);
		} catch (e) {
			console.log(e.name);
		}
	}
} catch (e) {
	console.log(e.name);
}

An application can receive ViewController event by registering the listener as follows: 

 
var handle = null;
var eventListener = {
	onauthenticationfailed: function(viewControllerId) { 
		console.log("failed to authentication."); 
	},
    onconnected: function(viewControllerId) { 
		console.log("connected."); 
	},
    ondisconnected(viewControllerId) {
		console.log("disconnected.");  
	}
 };
try {
	if (viewController.isConnected) {
	    handle = viewController.addViewControllerEventListener(eventListener);
    }
} catch (e) {
	console.log(e.name);
}
// Remote listener
var eventListenerId; // it is assumed that an eventListenerId which is registered.
if (handle != null) {
	if (viewController.isConnected) {
		viewController.removeViewControllerEventListener(handle);
	}
}

Control TV Image Player

ViewController is used for controlling the view. You can use ViewController for moving, rotating, and zooming the photo view. To get the ViewController instance, call the getViewController() method in ImageViewer. ViewController requires continuous network communication. If the connection between a device and a TV is successful, you can use three methods to the control TV image viewer:

  • move() to move the center of the view
  • setViewAngle() to rotate the image view
  • zoom() to pinch or stretch the view.

For move(), you must specify new horizontal and vertical coordinates for the view center. Invoke the move() method as follows: 

 
var viewController; // it is assumed that a proper view controller object which has connected;
// Define a success callback.
function moveSCB(controller) {
	console.log("moveSCB");
}
// Define an error callback
function moveECB(error, controller) {
	console.log(“move failed: “+error.message);
}
try {
	if (viewController.isConnected) {
		viewController.move(18, 18, true, moveSCB, moveECB);
	}
} catch (e) {
	console.log(e.name);
}

Also, you can rotate the image using setViewAngle(). Below is sample code showing the use of the setViewAngle() method. 

 
var viewController; // it is assumed that a proper view controller object has connected;
// Define a success callback.
function setViewAngleSCB(controller) {
	console.log("setViewAngleSCB.");
}
// Define an error callback
function setViewAngleECB(error, controller) {
	console.log(“setViewAngle failed: “+error.message);
}

try {
	if (viewController.isConnected) {
		viewController.setViewAngle("90", setViewAngleSCB, setViewAngleECB);
	}
} catch (e) {
	console.log(e.name);
}

For zoom(), you must specify the position of the zoom center, zoom scale in percentage units, view angle, and image resolution. Invoke the zoom() method as follows: 

 
var viewController; // It is assumed that a proper view controller object has connected;
var zoomRatio = 100;
var originalWidth, originalHeight; // It is assumed that original size of an image stored.

try {
	if (viewController.isConnected) {
		viewController.zoom(8, 8, zoomRatio * 1, "180", orginalWidth, orginalHeight);
	}
} catch (e) {
	console.log(e.name);
}