Skip to main content

​
System requirements

The Makefile build and deploy targets require the following tools on your development machine:
ToolMinimumPurpose
makeAnyRuns zip, install, pkg, check, and clean targets
zipAnyCreates out/GlobalTV.zip from project sources
curlAnyUploads the ZIP to the Roku device via HTTP multipart POST
rmAnyUsed by make clean to remove the out/ directory
grepAnyUsed by make check and make install to parse responses
sedAnyUsed by make install to display error output on failure
make, zip, curl, rm, grep, and sed are available by default on most macOS and Linux systems. No additional setup is needed.
make --version
zip --version
curl --version

​
Roku device requirements

​
Developer mode

Sideloading requires your Roku device to be in developer mode. Activate it with this remote sequence: Home × 3 → Up × 2 → Right → Left → Right → Left → Right This opens the Developer Settings screen where you enable the installer and set a password. That password is the ROKU_PASS value you pass to make install.
Developer mode persists across reboots but is cleared if you factory-reset the device or perform certain firmware updates. Re-enable it using the same key sequence if it stops working.

​
Firmware and resolution

RequirementValue
SceneGraph versionrsg_version=1.3 (declared in manifest)
Supported resolutionsFHD (1920×1080) and HD (1280×720) — ui_resolutions=fhd,hd
supports_input_launch1 — required for deep link support
The app targets FHD as the primary design resolution and scales down to HD automatically at runtime using roDeviceInfo.GetDisplayMode().

​
Backend requirements

GlobalTV Roku communicates with a configurable backend server. The server list in AppConstants.brs defines the endpoints the app will try: 
http://172.17.11.2:3333       ← LAN / development server
https://admin.globaltv.lat    ← Production server
The app probes each server in order and uses the first one that responds to the health check. You can configure the server list in source/AppConstants.brs.

​
Required endpoints

All paths below are relative to the selected backend base URL.
Purpose: Server reachability probe. The app sends this request before every major operation to confirm the backend is up.Timeout: 2500 ms (TIMEOUT_HEALTH)Expected response: Any HTTP 2xx response is treated as healthy.
Purpose: Device registration handshake. Called at startup to register the Roku device with the backend and retrieve device-specific configuration.Timeout: 12000 ms (TIMEOUT_HTTP)
Purpose: User authentication. The app substitutes the actual username and password into the path template.Path template: /auth/{user}/{pass}Timeout: 15000 ms (TIMEOUT_AUTH)Auth failure codes handled:
CodeMeaning
401Invalid credentials
403Access forbidden
404User not found
460Network down
470Account inactive
471Password changed
Purpose: Fetches the authenticated M3U8/HLS playlist for the logged-in user. The app parses this playlist to build the channel list and category grid.Path template: /auth/{user}/{pass}/playlist/m3u8/hlsTimeout: 12000 ms (TIMEOUT_HTTP)
Purpose: Returns the currently active ad snapshot. Polled every 10 seconds (ADS_POLL_MS=10000) while the app is running.Timeout: 12000 ms (TIMEOUT_HTTP)
Purpose: Metrics and usage event tracking.Timeout: 12000 ms (TIMEOUT_HTTP)

​
Ads backend

The app uses a dedicated ads service separate from the main backend. The base URL is configured in AppConstants.brs: 
https://ads.globaltv.lat/api/v1
PathPurpose
/app/devices/handshakeAds service device registration
/app/ads/activeActive ad snapshot poll
/app/impressions/events/batchBatch impression event reporting
The ads backend can be toggled via ADS_USE_DEDICATED=true and ADS_HANDSHAKE_ENABLED=true in AppConstants.brs. When disabled, the app falls back to the main backend for ad data.

​
Retry behavior

ConstantValueDescription
RETRY_MAX3Maximum HTTP retry attempts per request
SERVER_LAN_FORCE_RETRIES3Extra retries forced for the LAN server
NET_RETRY_MS30000Wait time before retrying after a network failure

​
Network requirements

RequirementDetails
LAN connectivityThe Roku device and your development machine must be on the same local network for sideloading via make install
Internet accessRequired to reach https://admin.globaltv.lat and https://ads.globaltv.lat in production
Port 80 (HTTP)Used by the Roku Developer Application Installer at http://<ROKU_IP>/plugin_install
Port 8080Used by the Roku telnet interface for genkey when generating signing keys for make pkg
Firewalls or network isolation (e.g., guest Wi-Fi networks that block device-to-device traffic) will prevent sideloading. Make sure your machine and Roku are on the same unrestricted LAN segment.

Build docs developers (and LLMs) love

Get started for freeTalk to us