Repository files navigation

TVCommanderKit is a Swift SDK for controlling Samsung Smart TVs over a WebSocket connection. It provides a simple and convenient way to interact with your TV and send remote control commands from your iOS application. This README.md file will guide you through using the TVCommanderKit SDK in your project.

• Usage
• Delegate Methods
• Searching for TVs
• Fetching TV Device Info
• Establishing Connection
• Authorizing Application with TV
• Sending Remote Control Commands
• Disconnecting from TV
• Error Handling
• Text Entry
• Wake on LAN
• Managing TV Apps
• License

1. Import the TVCommanderKit module:

import TVCommanderKit

2. Initialize aTVCommander object with your TV's IP address and application name:

lettvCommander=tryTVCommander(tvIPAddress:"your_tv_ip_address", appName:"your_app_name")

3. Implement the necessary delegate methods to receive updates and handle events (seeDelegate Methods), then set your delegate to receive updates and events from the TVCommander:

tvCommander.delegate=self

4. Connect to your TV (seeEstablishing Connection for further details):

tvCommander.connectToTV()

5. Handle incoming authorization steps to authorize your app to send remote controls (seeAuthorizing Application with TV).

6. Send remote control commands (seeSending Remote Control Commands).

7. Disconnect from your TV when done:

tvCommander.disconnectFromTV()

The TVCommanderDelegate protocol provides methods to receive updates and events from the TVCommanderKit SDK:

• tvCommanderDidConnect(_ tvCommander: TVCommander): Called when the TVCommander successfully connects to the TV.

• tvCommanderDidDisconnect(_ tvCommander: TVCommander): Called when the TVCommander disconnects from the TV.

• tvCommander(_ tvCommander: TVCommander, didUpdateAuthState authStatus: TVAuthStatus): Called when the authorization status is updated.

• tvCommander(_ tvCommander: TVCommander, didWriteRemoteCommand command: TVRemoteCommand): Called when a remote control command is sent to the TV.

• tvCommander(_ tvCommander: TVCommander, didEncounterError error: TVCommanderError): Called when the TVCommander encounters an error.

The TVCommanderKit SDK includes aTVSearcher class that helps you discover Samsung Smart TVs on the network. You can use this class to search for TVs and obtainTV instances for each discovered TV.

lettvSearcher=TVSearcher()tvSearcher.addSearchObserver(self)tvSearcher.startSearch()

You can also specify a TV to search for using its ID. Once theTVSeacher finds a TV with a matching ID, it will automatically stop searching:

tvSearcher.configureTargetTVId("your_tv_id")

To stop searching for TVs, call the stopFindingTVs() method:

tvSearcher.stopSearch()

You need to conform to theTVSearchObserving protocol to receive updates on the search state and discovered TVs.

Upon findingTVs using theTVSearcher class, you can also fetch device info using theTVFetcher.

lettvFetcher=TVFetcher(session:.shared) // use custom URLSession for mocking, etc

Invoking thefetchDevice(for:) method will return either an updatedTV object (with device info injected) or aTVFetcherError.

tvFetcher.fetchDevice(for: tv){ resultinswitch result{case.success(let tvFetched):        // use updated tv    case.failure(let error):        // handle fetch error}}

To establish a connection to your TV, use theconnectToTV() method. This method will create a WebSocket connection to your TV with the provided IP address and application name. If a connection is already established, it will handle the error gracefully.

tvCommander.connectToTV()

If you're worried about man-in-the-middle attacks, it's recommended that you implement a custom cert-pinning type and pass it through the optionalcertPinner parameter to ensure connection to a trusted server (make sure your custom cert-pinning type doesn't also strongly reference theTVCommander, as this will result in a retain cycle).

After establishing a connection to the TV, you'll need to authorize your app for sending remote controls. You can access the authorization status of your application via theauthStatus property. If your TV hasn't already handled your application's authorization, a prompt should appear on your TV for you to choose an authorization option. Once you select an option within the prompt, if the authorization status updated, it will get passed back through the corresponding delegate method:

func tvCommander(_ tvCommander:TVCommander, didUpdateAuthState authStatus:TVAuthStatus){switch authStatus{case.none: // application authorization incomplete    case.allowed: // application allowed to send commands, token stored in tvCommander.tvConfig.tokencase.denied: // application not allowed to send commands}}

You can send remote control commands to your TV using thesendRemoteCommand(key:) method. Ensure that you are connected to the TV and the authorization status is allowed before sending commands.

tvCommander.sendRemoteCommand(key:.enter)

TVCommanderKit provides a convenient text entry feature, allowing you to quickly input text into on-screen keyboards. There are now two ways to send text input to the TV:

1. Direct Text Input
   UsesendText(_:) to send text directly to the TV. This is the preferred method for compatible devices.

   lettextToSend="Hello, World!"tvCommander.sendText(textToSend)

2. Keyboard Navigation (Legacy)
   TheenterText(_:on:) method simulates typing by navigating an on-screen keyboard. This approach will likely be removed in future versions.

   lettextToEnter="Hello, World!"letkeyboardLayout=TVKeyboardLayout.youtubetvCommander.enterText(textToEnter, on: keyboardLayout)

When you're done with the TVCommander, disconnect from your TV using thedisconnectFromTV() method:

tvCommander.disconnectFromTV()

The TVCommanderKit SDK includes error handling for various scenarios, and errors are reported through the delegate methodtvCommander(_ tvCommander: TVCommander, didEncounterError error: TVCommanderError). You should implement this method to handle errors appropriately.

The TVCommanderKit SDK now supports Wake on LAN functionality. You can wake up your TV using thewakeOnLAN method:

letdevice=TVWakeOnLANDevice(mac:"your_tv_mac_address")TVCommander.wakeOnLAN(device: device){ erroriniflet error= error{print("Wake on LAN failed:\(error.localizedDescription)")}else{print("Wake on LAN successful!")}}

TVAppManager allows you to interact with TV applications on Samsung TVs using their IP address and app ID.

1. Initialization:

   lettvAppManager=TVAppManager()lettvApp=TVApp(id:"3201907018807", name:"Netflix")

2. Fetch App Status:

   lettvIPAddress="192.168.1.100"letappStatus=tryawait tvAppManager.fetchStatus(for: tvApp, tvIPAddress: tvIPAddress)print(appStatus)

3. Launch App:

   tryawait tvAppManager.launch(tvApp: tvApp, tvIPAddress: tvIPAddress)

Errors like invalid URLs or app not found are handled byTVAppManagerError andTVAppNetworkError.

The TVCommanderKit SDK is distributed under the MIT license.

Feel free to contribute to this SDK, report issues, or provide feedback. I hope you find TVCommanderKit useful in building your Samsung Smart TV applications!