Skip to content

Installation Instructions

Jump to bottom
Jeremy edited this page Apr 11, 2018 · 40 revisions

Install

  1. Install Node Version Manager.

    Linux/Mac: nvm

    sudo curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.0/install.sh | bash

    Windows: nvm-windows

    Download and run the installer, accepting the defaults. It will end up under C:\Users\<username>\AppData\Roaming\nvm with a symlink under C:\Program Files\nodejs.

  2. Install Node.js.

    Linux/Mac:

    nvm install v6.9.5
nvm alias default v6.9.5

    Windows:

    nvm install v6.9.5
nvm use 6.9.5

  3. Install alexa-app-server (currently works with 3.0.1).

    Linux/Mac:

    (these instructions assume /usr/local and refer to /usr/local/node_modules/alexa-app-server as $ALEXA_HOME):

    cd /usr/local
npm install alexa-app-server

    Windows:

    (these instructions refer to C:\Program Files\nodejs\node_modules\alexa-app-server as $ALEXA_HOME):

    cd C:\Program Files\nodejs
npm install alexa-app-server

    This command will create a node_modules subdirectory and download the alexa-app-server and its dependencies.

  4. Make any changes to $ALEXA_HOME/examples/server.js to reflect your environment (like the listening port). Refer to the documentation for the available settings. You can also comment out (or delete) the .preRequest and .postRequest lines. Here's a sample server.js:

    var AlexaAppServer = require("../index.js");

AlexaAppServer.start({
   server_root: __dirname,
   app_root: "alexa",
   port: 8080
});

  5. Install alexa-tivo-control.

    Either clone this repository into your alexa-app-server apps directory:

    cd $ALEXA_HOME/examples/apps
git clone https://github.com/jradwan/alexa_tivo_control.git

    or download the current release as a ZIP file and extract it into your alexa-app-server apps directory.

    Either way, you should now have a subdirectory under $ALEXA_HOME/examples/apps containing the skill source code.

  6. Install any missing dependencies (telnet-client, log-timestamp, etc.). This will create another node_modules directory under $ALEXA_HOME/examples/apps/alexa-tivo-control with the prerequisite modules:

    cd $ALEXA_HOME/examples/apps/alexa_tivo_control
npm install

    Note: this pull request to alexa-utterances is required to support optional slot types. For now, to make installation easier, a patched copy of the index.js file for alexa-utterances is included in the examples directory. Copy this patched file and overwrite the delivered one (see issue #24 for more details):

    cp examples/alexa-utterances_index.js node_modules/alexa-utterances/index.js

Configure

  1. Copy $ALEXA_HOME/examples/apps/alexa_tivo_control/examples/example_config.json to $ALEXA_HOME/examples/apps/alexa_tivo_control/config.json:

    Linux:

    cp examples/example_config.json config.json

    Windows:

    copy examples\example_config.json config.json

    Edit this new config.json file and make the following changes:

    "name": replace <box name> with the name of your TiVo box (ex. "Family Room" or "Man Cave", in double quotes)
"address": replace <IP address> with the IP address of the TiVo (also in double quotes)
"mini": set this to true if the TiVo is a Mini (no double quotes)
"hydra": set this to true if the TiVo is running the next generation user interface (Hydra)

    If you've hidden unused Video Providers on your TiVo (under Settings & Messages > Settings > Channels > My Video Providers), set the corresponding entries in the file to 'false'. For example:

    "netflix": false,
"amazon": true,
"hbogo": false,
"xfinityondemand": false,
"hulu": false,
"youtube": true,
"mlbtv": false,
"plex": true,
"vudu": true,
"epix": true,
"hsn": false,
"alt": false,
"flixfling": false,
"toongoggles": false,
"wwe": false,
"yahoo": false,
"yupptv": false,
"vewd": false,
"ameba": true,
"tubi": false,
"ign": false,
"tastemade": true,
"baeble": false

    Audio providers are currently not customizable on the TiVo so those settings should be left as 'true'. If for some reason a provider does not appear on your TiVo, you can set the corresponding entry to 'false'.

    "iheartradio": true,
"pandora": true,

    These settings are used to dynamically generate remote key-presses for menu navigation so incorrect settings could cause unexpected navigation.

    Note: if you want to control more than one TiVo box, see the advanced setup instructions here.

    Note #2: if you're using the skill outside of the U.S., set the "language" in config.json to "uk" or "ca" accordingly (see issue #47).

  2. Copy $ALEXA_HOME/examples/apps/alexa_tivo_control/examples/example_channels.json to $ALEXA_HOME/examples/apps/alexa_tivo_control/channels.json:

    Linux/Mac:

    cp examples/example_channels.json channels.json

    Windows:

    copy examples\example_channels.json channels.json

    Edit this new channels.json file and make the appropriate changes (if desired) as documented here.

Test

  1. Start the alexa-app-server:

    cd $ALEXA_HOME/examples
node server.js

    You should see the TiVo Control app registered as an endpoint in the console log:

    Serving static content from: public_html
Loading server-side modules from: server
Loaded /usr/local/alexa-app-server/examples/server/login.js
Loading apps from: apps
[2017-01-02T02:31:49.732Z] Now controlling: Office (192.168.1.73).
[2017-01-02T02:31:49.733Z]    Loaded app [alexa_tivo_control] at endpoint: /alexa/tivo_control
[2017-01-02T02:31:49.735Z]    Loaded app [hello_world] at endpoint: /alexa/helloworld
[2017-01-02T02:31:49.736Z]    Loaded app [number_guessing_game] at endpoint: /alexa/guessinggame
[2017-01-02T02:31:49.738Z] Listening on HTTP port 8080

    Linux Tip: check out this init script if you want to have your alexa-app-server start automatically, run in the background, and log the console output to a file. If you're using systemd, look here for an example startup script.

    Windows Tip: check out the Non-Sucking Service Manager for running the alexa-app-server as a service under Windows.

    General Tip #1: you can delete the helloworld and guessinggame directories (under $ALEXA_HOME/examples/apps) if you don't want those skills to run on your alexa-app-server.

    General Tip #2: you may also want to edit/customize the index.html file in the $ALEXA_HOME/examples/public_html folder.

  2. Enable the network remote control on your TiVo (under Settings & Messages > Remote, CableCARD, & Devices > Network Remote Control. Your TiVo's IP address must be accessible (via telnet on the same local network) from the machine running alexa-app-server.

  3. In a browser, open the TiVo Control endpoint on your alexa-app-server (ex., http://localhost:8080/alexa/tivo_control) and you should see the Alexa Tester page. Here you can set the "Type" field to "IntentRequest", choose an "Intent" (i.e., action) from the dropdown menu, and click "Send Request" to trigger the intent.

    For example: select "Pause" from the dropdown and click "Send Request." If your configuration is correct and working, your TiVo should pause. Select "Play" then "Send Request" and playback should resume. The console log will show debugging information:

    [2016-12-21T19:36:00.238Z] QueuedCommands: PAUSE
[2016-12-21T19:36:00.246Z] Connection Created
[2016-12-21T19:36:00.265Z] RECEIVED: CH_STATUS 1010 LOCAL
[2016-12-21T19:36:00.579Z] Sending Prefixed Command: IRCODE PAUSE
[2016-12-21T19:36:05.864Z] QueuedCommands: PLAY
[2016-12-21T19:36:05.871Z] Connection Created
[2016-12-21T19:36:05.882Z] RECEIVED: CH_STATUS 1010 LOCAL
[2016-12-21T19:36:06.188Z] Sending Prefixed Command: IRCODE PLAY

    You can test the other intents (such as launching the video/audio providers) on this page to confirm your configuration settings.

Link

  1. In order to link TiVo Control to your Alexa device, you'll need an Amazon Developer account and your alexa-app-server must be available over the public internet via SSL (HTTPS). In the Alexa Skills Kit Developer Console, click "Create Skill," name your skill (ex. TiVo Control) and choose the Custom model.

    Note: if you're using the skill outside of the U.S., change the Language accordingly (i.e., to "English (UK)") (see issue #48).

  2. On the Build tab under the Interaction Model section, select the Invocation page and set an invocation name (ex. tivo).

  3. Still on the Build tab, under the Interaction Model section, click on the "JSON Editor" page. Highlight the existing intents and types sections and delete them:

    In a separate browser tab, connect to your alexa-app-server's Alexa Tester endpoint (from step 11) with the "?schema&schemaType=skillBuilder" parameter at the end of the URL (ex. http://localhost:8080/alexa/tivo_control?schema&schemaType=skillBuilder). You should get a page JSON-formatted text containing all of the skill's intents and types (slots):

    {
    "intents": [
       {
          "name": "Help",
          "samples": [
             "for help",
             "help",
             "for assistance",
             "assistance"
          ]
       },

    Copy the contents of that page (except for the first and last lines, the opening and closing braces) and paste them into the JSON editor, after the "invocationName" line. Click "Save Model" and the JSON should be saved and validated. The Intents and Slot Types areas should update to reflect the information you just pasted into the JSON editor.

    Note: if you have not manually applied this pull request to alexa-utterances (or followed the patch instructions in step 6), you'll need to manually replace the + signs in the generated schema with their corresponding curly braces (see issue #24 for more details).

    If you're using the skill outside of the U.S., you'll need to customize the additional custom slot types (TIVOGENRE_SLOT, TIVOROOM_SLOT, TIVOMOVIE_SLOT, TIVOTVSERIES_SLOT, TIVOTVCHANNEL_SLOT) here as well (see issue #47). Remove the defaults from each TIVOxxxx_SLOT and add your own custom values.

    Now click "Build Model" to create the interaction model for the skill.

  4. Still on the Build tab, click on the Endpoint section. You have two Endpoint options for directing the skill to your alexa-app-server:

    HTTPS (recommended): requires an SSL certificate (self-signed, letsencrypt, etc.). Fill in the URL of your alexa-app-server and TiVo Control endpoint (see screenshot above for an example). Remember the URL must be accessible via HTTPS over the public internet (setting that up is outside the scope of this document, but see here for some discussion/tips and check the "Enabling HTTPs" section of the alexa-app-server README).

    Lambda: if you can't (or don't want to) use your own SSL/HTTPS setup, you can follow the instructions here to create a Lambda function that will proxy HTTPS traffic from the skill to your alexa-app-server over plain HTTP, eliminating the need to get a certificate. See here for more details.

    Click "Save Endpoints."

  5. Click on "Your Skills" at the top of the page to go back to your list of Alexa skills. Click on the application ID under your skill's name to copy it to your clipboard. Paste it into the alexaAppId attribute in the config.json file (from step 7 above) and restart your alexa-app-server.

  6. Click "Edit" to go back into the skill editor and then click on the Test tab and turn on the Test switch. Enter a sample utterance (ex. "ask tivo for help") and press Enter. If your setup is correct, the Alexa skill on the Amazon servers will send a JSON request to your endpoint and a response should be received.

  7. (optional) If you want, click on the Launch tab and complete the Skill Preview section (public name, description, sample phrases, icons, etc.). This will give your skill a more polished look when viewed in your Alexa skills list.

  8. The skill should now be active on your developer account (as a skill in test mode). You can confirm this by looking at the "Your Skills" page on your Alexa web page or app.

    Test it out by asking Alexa to control your TiVo and watch the magic happen!

    Alexa, tell TiVo to pause
Alexa, tell TiVo to replay
Alexa, ask TiVo to go to channel one oh oh nine
Alexa, ask TiVo to go to My Shows
Alexa, ask TiVo to turn on captions
Alexa, tell TiVo to launch YouTube
Alexa, tell TiVo to control <box name>
Alexa, tell TiVo to list my boxes
Alexa, ask TiVo to list my providers

    If you don't have a physical Alexa-enabled device (like an Echo, Dot, or Tap), check out echosim.io, the Alexa Skill Testing Tool that simulates an Echo in your browser.

  9. (optional) Having your alexa-app-server available to the public internet means anyone could theoretically control your TiVo through the alexa-app-server's Alexa Tester. Once you have confirmed the skill is working, both via the Test tab in the Developer Console and the Alexa Tester, you should enable verification in alexa-app-server by adding the debug and verify lines shown below to your server.js file:

    var AlexaAppServer = require("../index.js");

AlexaAppServer.start({
   server_root: __dirname,
   app_root: "alexa",
   port: 8080,
   debug: false,
   verify: true
});

    This will enable the alexa-verifier-middleware which will verify that any HTTP requests sent to the skill are coming from Amazon. This also disables the Alexa Tester so if you attempt to access your endpoint from a browser once enabling verification, you'll see this:

    {"status":"failure","reason":"The signaturecertchainurl HTTP request header is invalid!"}

    You can turn the simulator back on when needed by temporarily commenting out the debug and verify lines in server.js:

    var AlexaAppServer = require("../index.js");

AlexaAppServer.start({
   server_root: __dirname,
   app_root: "alexa",
   port: 8080,
   //debug: false,
   //verify: true
});

    Note: If you chose to use the Lambda HTTPS proxy as your endpoint in step 15, you can't use the verifier.

Clone this wiki locally