Object Creation
To create a tvcontroller object, load the brightsign/tvcontroller module using the require() method and then create an instance of the tvcontroller:
| Code Block | ||
|---|---|---|
| ||
let tv_controller_class = require("@brightsign/tvcontroller");
let tv_controller = new tv_controller_class(); |
TvController
Use this interface to access a television (for example, to send messages)
send()
| Code Block |
|---|
Promise<void> send(Array data) |
Attribute
onreceiveEventHandler:
ReceiveEvent
Use this interface to get notified with an event when the television sends a message
Attribute
dataArray: This is a read-only attribute
Messages
Messages are defined in the Protobuf format. BrightSign firmware includes the JavaScript bindings of the protocol buffer messages in the firmware image. To load the messages, load the following module:
| Code Block | ||
|---|---|---|
| ||
let messages = require("messages_pb") |
A single Protobuf file is used for both television to BrightSign Built-In and BrightSign Built-In to television messages, because the same messages are used both for verification and update notifications. When BrightSign updates a field (for example, to set up the volume), the television sends the same message back to BrightSign that the volume is updated. The volume can be updated with the television user interface, via remote control. BrightSign also gets that as an event from the television.
There are some exceptions:
Brightsign Built-In doesn’t send messages back to the television to confirm acknowledgement of receipt of the request message, it only sends the requested information.
Both sides can send
PowerSettingsmessage to each other. To prevent confusion with receiving a command and a acknowledgement, we havePowerSettingsandPowerSettingsAckmessage types.PowerSettingsAckis sent when device gets aPowerSettingsmessage and switches to the requested power mode.
This is the Proto file for the communication interface:
| Code Block | ||
|---|---|---|
| ||
syntax = "proto3";
package messages;
message WhiteBalance {
int32 red_gain = 1; // Red channel gain (e.g., 0 to 100)
int32 green_gain = 2; // Green channel gain (e.g., 0 to 100)
int32 blue_gain = 3; // Blue channel gain (e.g., 0 to 100)
}
// Message to set the TV HDMI® input.
message VideoOutputSettings {
enum VideoOutputSelection {
HDMI_1 = 0;
HDMI_2 = 1;
// Add more as needed
}
VideoOutputSelection selected_input = 1;
}
// There may be more PowerStatus modes in the future
enum PowerStatus {
STANDBY = 0;
ON = 1;
}
// Message to set the power status
message PowerSettings {
PowerStatus status = 1;
}
// PowerSettingsAck message is an acknowledgement of the power status
// change request.
// The sender should wait for Ack after changing PowerSettings
// via the PowerSettings message, or via GPIO when waking the device
// up
message PowerSettingsAck {
PowerStatus status = 1;
}
// Message to set or get the USB device connection
message USBConnectionSettings {
enum USBConnection {
CONNECTED_TO_TV = 0;
CONNECTED_TO_SET_TOP_BOX = 1;
}
USBConnection connection = 1;
}
// Message to forward the IR commands received by the TV
message IRCommandMessage {
int32 address = 1;
int32 command = 2;
}
enum Request {
DEVICE_INFO = 0;
}
message WifiInfo {
string mac_address = 1; // "XX:XX:XX:XX:XX:XX"
}
message DeviceInfo {
string mac_address = 1; // "XX:XX:XX:XX:XX:XX"
string serial_no = 2;
string os_version = 3; // "X.X.X.X"
int32 hw_revision = 4; //
WifiInfo wifi_info = 5;
}
// Command message that will be sent from the set top box to the TV
message TvCommand {
oneof command {
VideoOutputSettings video_output_settings = 1;
PowerSettings power_settings = 2;
PowerSettingsAck power_settings_ack = 3;
USBConnectionSettings usb_connection_settings = 4;
IRCommandMessage ir_command = 5;
int32 volume = 6;
float gamma = 7;
int32 brightness = 8;
int32 contrast = 9;
WhiteBalance white_balance = 10;
Request request = 11;
DeviceInfo device_info = 12;
}
} |
Usage Examples
Set the TV Gamma Value
In this one way communication, BrightSign makes the request and the television updates and returns the gamma value.
Send takes a JavaScript array, but serializeBinary returns Uint8Array. Uint8Array should be converted to Array using Array.from() before calling send.
deserializeBinary also expects a Uint8Array, but receive event returns Array. Array should be converted to Uint8Array before calling deserializeBinary using Uint8Array.from().
| Code Block | ||
|---|---|---|
| ||
let tv_controller_class = require("@brightsign/tvcontroller");
let tv_controller = new tv_controller_class();
tv_controller.addEventListener("receive", (event)=>{
// Deserialize the binary data
let tv = messages.TvCommand.deserializeBinary(Uint8Array.from(event.detail));
switch (tv.getCommandCase()) {
case messages.TvCommand.GAMMA:
let gamma = tv.getGamma();
console.log("Gamma value is updated to: " + gamma);
break;
default:
console.log("Unknown command type: " + tv.getCommandCase());
break;
}
});
let messages = require("messages_pb")
let tvCommand = new messages.TvCommand();
tvCommand.setGamma(2.3);
// Serialize to binary
let bytes = tvCommand.serializeBinary();
// Send it as an Array rather than the Uint8Array returned by serializeBinary
tv_controller.send(Array.from(bytes)); |
Send BrightSign Device Information
In the following example, the tv_controller is set up to send a device info, when the television requests it. The application sets up a receive event listener and waits for a request event.
Only one request, DEVICE_INFO, is currently available (anything else will error). A DEVICE_INFO request fills the required fields and sends a message back.
| Code Block | ||
|---|---|---|
| ||
let tv_controller_class = require("@brightsign/tvcontroller");
let tv_controller = new tv_controller_class();
let messages = require("messages_pb")
tv_controller.addEventListener("receive", (event)=>{
// Deserialize the binary data
let tv = messages.TvCommand.deserializeBinary(Uint8Array.from(event.detail));
switch (tv.getCommandCase()) {
case messages.TvCommand.CommandCase.REQUEST:
let request = tv.getRequest();
// We only have DEVICE_INFO request for now
if (request != messages.Request.DEVICE_INFO)
throw new Error("Request is not DEVICE_INFO");
let tvCommand = new messages.TvCommand();
// Create an instance of DeviceInfo
let deviceInfo = new messages.DeviceInfo();
deviceInfo.setMacAddress("XX:XX:XX:XX:XX:XX");
deviceInfo.setSerialNo("1234567890");
deviceInfo.setOsVersion("1.2.3.4");
deviceInfo.setHwRevision(1);
tvCommand.setDeviceInfo(deviceInfo);
// Serialize to binary
let bytes = tvCommand.serializeBinary();
tv_controller.send(Array.from(bytes));
break;
default:
console.log("Unknown command type: " + tv.getCommandCase());
break;
}
}); |