34 lines
4.7 KiB
Markdown
34 lines
4.7 KiB
Markdown
# Samsung TV integration and controller identity
|
|
|
|
Status: researched protocol proposal, no physical validation yet. Date: 2026-09-16.
|
|
|
|
## What "register as a controller" means here
|
|
|
|
The intended app advertises `Wristivo` as its local network controller name during a pairing request. A compatible TV may show the name in its access prompt and device list, then issue a reconnect token after the user allows it. We must verify the exact behavior on the owner's TV. This is not a Bluetooth HID pairing, Smart Remote certification, Samsung partnership, or registration of a Tizen application. No TV application installation is planned.
|
|
|
|
Samsung's official TVInputDevice API lets a TV-side app receive key events. It is not a phone API to inject system-wide keys. Smart View documentation describes connected sender/receiver experiences; do not infer that it guarantees a supported universal remote endpoint. [Samsung TVInputDevice API](https://developer.samsung.com/smarttv/develop/api-references/tizen-web-device-api-references/tvinputdevice-api.html), [Samsung Smart View overview](https://developer.samsung.com/smarttv/develop/extension-libraries/smart-view-sdk/introduction.html).
|
|
|
|
## Compatibility adapter
|
|
|
|
The planned socket endpoint is `wss://<user-selected-TV>:8002/api/v2/channels/samsung.remote.control` with `name` containing Base64 UTF-8 client name and a URL-encoded optional `token`. Use URLComponents, never concatenate token-bearing URLs into logs. The pure package encoder is a unit-testable protocol seam, not an implemented secure transport.
|
|
|
|
Community maintainers describe a TLS port 8002, named clients and token reuse; support differs by TV/firmware. Their project is primary evidence for its own implementation, not an official Samsung API guarantee. Do not vendor or copy its LGPL implementation. [Maintainer project](https://github.com/xchwarze/samsung-tv-ws-api), [maintainer command reference](https://github.com/xchwarze/samsung-tv-ws-api/blob/master/COMMANDS.md). This project's JSON encoding is independently written; protocol strings alone do not establish legal clearance for every distribution market.
|
|
|
|
Typical click frame fields to validate on hardware: method `ms.remote.control`; params Cmd `Click`, DataOfCmd mapped key, Option `false` as string, TypeOfRemote `SendRemoteKey`. Directional keys map to KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT; Select to KEY_ENTER and Back to KEY_RETURN. Validate playback and volume independently; unsupported buttons must be hidden/disabled by capability evidence. No factory or service keys.
|
|
|
|
## Pairing implementation sequence
|
|
|
|
1. User enters an address; validate host-only input (no credentials, path, query or arbitrary scheme). Restrict discovery/connection to the chosen local TV; no subnet brute force. Start with same home network; guest isolation/VLAN routing may block access.
|
|
2. Request iOS Local Network access in context using a meaningful NSLocalNetworkUsageDescription. Denied permission has a recoverable Settings explanation.
|
|
3. Establish a scoped TLS trust policy as specified in SECURITY-PRIVACY. Default trust failure must not be silently ignored. Self-signed TV certs are a hardware investigation item.
|
|
4. Start named pairing only from explicit setup UI. The television must be powered on; keep an existing remote available for the approval prompt. Bound pairing wait to 30 seconds (proposed, configurable).
|
|
5. Parse bounded protocol events. Candidate events to verify: ms.channel.connect, ms.channel.unauthorized, ms.channel.timeOut and ms.error. A socket upgrade is not pairing approval. Do not send keys until authorization is confirmed; token location/format may vary and requires captured redacted fixtures.
|
|
6. Store the token in iPhone Keychain associated with opaque TV identity and its trust record. Reconnect without repeating pairing where supported. Rejected/revoked tokens transition to explicit re-pair UI.
|
|
7. Forget TV deletes token, trust record, selection and active session. Explain separate removal from the TV's device list if the user wants to revoke on the television too; menu labels vary by firmware.
|
|
|
|
## Proof checklist
|
|
|
|
Use Tests/Hardware/session-template.md. Confirm actual model/firmware, pairing label, denial, persistence after app relaunch/phone reboot, token revocation, TLS certificate behavior, every offered key, TV off, network drop, selected-TV switch, and repeated one-gesture-one-key behavior. Raw events must be scrubbed of tokens, IPs, identifiers and client lists before fixtures enter git.
|
|
|
|
Public compatibility starts with only explicitly tested configurations. Do not advertise "all Samsung TVs" or infer working compatibility from Tizen alone. No silent port 8001 plaintext fallback in v1. TV wake is out of scope until network-standby and multicast restrictions are separately tested.
|