Run Your App on Vega Virtual Device or Fire TV

Run your app on Fire TV

Running your Vega app on a Fire TV device is essential for testing real device performance and ensuring compatibility before submitting to the Amazon Appstore. This section walks you through setting up your Fire TV device for development, enabling Developer Mode, and sideloading your Vega app for testing.

Developer Mode allows you to sideload apps and test development builds on your device. All Vega Fire TV devices use the same Developer Mode enablement process.

Prerequisites

1. Install the Vega SDK.
2. Ensure you have the latest SDK Manager installed (run vega update to get the latest version).

3. A Fire TV device running Vega OS (for example, Fire TV Stick HD, Fire TV Stick 4K Select, or Fire TV Streaming Media Player).

   For a full list of supported devices, see Fire TV device specifications.

Step 1: Set up and register your Fire TV device

Before you proceed, ensure you're using the remote that came with your Fire TV device. Remotes from other Fire TV devices cause pairing issues during development and testing.

1. Connect your Fire TV device:

   a. To your development machine using a USB cable.

   b. To a display using the HDMI adapter.

   The remote pairing screen displays.

2. Complete remote pairing:

   a. Press the Home button when prompted.

   b. Follow on-screen instructions.

   c. Wait for the Fire TV logo.

   If the Fire TV logo doesn't appear within a few minutes, see Resolve Fire TV Stick Issues for troubleshooting steps.

3. Configure settings:

   a. Press the Play/Pause button on your remote.

   b. Select your preferred language.

   c. Connect to your network.

   d. Enter your network credentials.

   Warning: The device checks for over-the-air (OTA) updates. Don't power off or restart your device until the updates complete. Interrupting the update might prevent network discovery.

4. Complete device registration:

   a. Sign in to your Amazon account either online or through QR code.

   b. Follow on-screen instructions.

   c. Wait for the "Successfully registered" message.

5. Press OK when you see "Your Fire TV remote is now successfully set up."

Step 2: Configure Developer Mode

Developer Mode requires authentication with your Amazon Developer Account using the Vega CLI. The process involves retrieving an authentication code from your Fire TV device, authenticating through your browser, and completing device enablement from the terminal. Your device reboots automatically after enablement.

1. Access the Fire TV Settings menu:

   Option 1: Using Home button

   a. Press the Home button on your remote to go to the Home screen.

   b. Navigate to the top menu bar.

   c. Scroll right to find and select the Settings icon (gear symbol).

   Option 2: Using Home button shortcut (faster)

   a. Press and hold the Home button on your remote for 3 seconds.

   b. Select Settings from the quick menu that appears.

2. Go to Settings > My Fire TV > About.

   

3. Select your device name (for example, Fire TV Stick HD, Fire TV Stick 4K Select, or Fire TV Streaming Media Player).

   

4. Press the center button on the remote control seven times.

   A brief "You are now a developer" notification appears on screen after the seventh press.

5. Press the Back button to return to My Fire TV.

   Developer options appears in the list.

   

6. Select Developer options.

   Developer Mode (disabled by default) appears in the menu list.

   

7. Select Developer Mode to proceed.

   

8. Select Continue to proceed (or Cancel to abort).

   If you select Cancel, the dialog closes and you return to the Developer Options screen without changes.

   After selecting Continue, the Fire TV screen displays a 6-digit authentication code. You'll enter this code in #11.

   

   Note: The code expires after 5 minutes. If you don't enter the code within the allotted time, select Request a New Code on the same screen, or return to Developer Options and restart the process.

9. To authenticate with your Amazon Developer Account, run the login command:

   Copy code Copied to clipboard.

    vega devmode login
   

   Follow the instructions from the CLI to complete authentication. The CLI automatically opens your default web browser to the Amazon authentication page. If the browser doesn't open automatically, navigate to the URL provided in the terminal.

10. Authorize Vega CLI access in your browser.

    The Amazon OAuth consent screen displays "Vega Authentication Test would like access to:" along with your basic profile information and name.

    a. Review the requested permissions.

    b. Select Allow to authorize Vega Authentication Test (or Cancel to deny).

    If you select Cancel, the CLI denies authorization and displays an authentication error. Re-run vega devmode login to try again.

    After selecting Allow, a confirmation page appears with a checkmark icon and the message "Device connected to your account." You can close this page.

    Return to your terminal. The CLI displays:

    Login successful! You are now authenticated with Amazon Developer Services.
    

11. Enable the device using the 6-digit code displayed on your Fire TV screen:

    Copy code Copied to clipboard.

    vega devmode enable-device --code <6-digit code>
    

    If your Amazon Developer account has only one vendor, the CLI displays:

    Using vendor: Amazon
    ✓ Device enabled successfully
    

    If your account has multiple vendors, the CLI prompts you to select one:

    Select a vendor:
    1. Amazon (XXXXXXXXXX)
    2. Amazon (XXXXXXXXXX)
    

    Enter the number corresponding to your vendor. The CLI then displays ✓ Device enabled successfully.

    Note: A vendor is a developer account for managing and publishing content through Amazon's developer services. This authentication can take a few seconds to reach the device.

12. Wait for the device to reboot.

    

13. After the device reboots, navigate to Settings > My Fire TV > Developer Options > Developer Mode.

    The Developer Mode status displays Enabled.

    

14. Check device recognition.

    Copy code Copied to clipboard.

    vega device list
    

    Example output with one device connected:

    Found the following device:
    [Serial Number] : [Device Number]
    

    Example output with multiple devices connected:

    Found the following devices:
    [Serial Number] : [Device Number]
    [Serial Number] : [Device Number]
    

15. Connect to the device.

    • If you have one device connected:

      Copy code Copied to clipboard.

      vega device shell
      

    • If you have multiple devices connected, specify the Device Serial Number:

      vega device -d <Device Serial Number> shell
      

      Example output:

       (hostmachine)% vega device -d <Device Serial Number> shell
      
       ##################################################
      
       ##### Welcome to Developer Mode Shell #####
      
       ##################################################
      
       sh(com.amazon.dev.shell):/$
      

Step 3: Load your app on a Fire TV device

After you configure Developer Mode on your Fire TV device, open a new terminal and use the following commands to load your app:

Find your .vpkg file

When you build your app with vega build, the build process generates the .vpkg file in your project's build/ directory. The path follows this pattern:

build/<ARCH>-<BUILD_TYPE>/<APP_NAME>_<ARCH>.vpkg

For Fire TV devices, use the armv7 architecture. For example, if your app is named sampleapp and you built a release variant:

build/armv7-release/sampleapp_armv7.vpkg

One device connected to your computer

Replace <my-package.vpkg> with the path to your .vpkg file.

vega device install-app --packagePath build/armv7-release/sampleapp_armv7.vpkg

Multiple devices connected to your computer

Use the following command to specify the target device. Replace <Device Serial Number> with your device's serial number and <my-package.vpkg> with the path to your .vpkg file.

vega device -d <Device Serial Number> install-app --packagePath build/armv7-release/sampleapp_armv7.vpkg

Example output:

Installing/Updating '/tmp/sampleapp_armv7.vpkg' .. success

Step 4: Run your app on Fire TV

After you load your app on your Fire TV device, use the following commands to run your app.

One device connected to your computer

vega device launch-app --appName <component-id>

Multiple devices connected to your computer

Use the following command to specify the target device. Replace <Device Serial Number> with your device's serial number and <component-id> with your app's component ID.

vega device -d <Device Serial Number> launch-app --appName <component-id>

Example output:

(hostmachine)% vega device -d <Device Serial Number> launch-app --appName com.amazondeveloper.sampleapp
Launching app 'com.amazondeveloper.sampleapp' .. success

Your app launches and appears on the connected Fire TV screen.