Smartskills

  Skill Help


Because LMS is not accessible from outside your LAN, we need to install a so-called proxy to enable secure access to your server from the Amazon cloud.

Our easy-setup[1] procedure deploys a proxy called ngrok to open up a persistent tunnel resulting in a password-protected URL like https://70c663eee228.eu.ngrok.io for your LMS.

Since initializing the tunnel is an outward process originating in your LAN, there's no need to open any ports in your router  — ngrok also takes care of a valid certificate for SSL.

Alexa [443/https] proxy [9000/http] LMS

The skill communicates with your proxy and it is the proxy (perched on the LAN side of your firewall on your local network at home) that actually interacts with LMS.

With this approach, cloud control is password-protected while local control within your LAN remains completely unrestricted. You should therefore not set a password in the LMS settings when using our skills.

There are actually two components to ngrok — a cloud service and an executable running on one of your computers. The ngrok cloud service provides the internet-facing URL that Alexa or a browser 'sees'. Incoming requests to this service are sent down the secure tunnel to your local executable which is always 'listening'. It 'knows' to relay all incoming requests onwards to your LMS server because it's configured accordingly. Responses from LMS simply follow the reverse path back up to the internet-facing ngrok cloud service where Alexa or the browser receives them. It's all lightning fast and adds no perceivable delay to your enjoyment of the skill(s).


[1] You don't have to use this procedure to link the skills. If your LMS is reachable via https due to an existing reverse-proxy running via e.g. nginx or apache in your setup, this can be used as-is. Should you prefer manual setup, see here.

Visit the ngrok.com website (no affiliation) for an explanation of how it works and what plans are available. The free plan[1] works just fine for our purposes so go ahead and Sign Up.

To subsequently authenticate you towards ngrok, you should make a note of your personal authtoken which resides at https://dashboard.ngrok.com/auth/your-authtoken. It will look something like 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p.

Please ignore any download/setup instructions at the ngrok website as they are geared towards setting up access to a web-server on 80 rather than a media server like LMS on 9000. Our installer will automatically download ngrok for you and configure it for LMS.


[1] The easy-setup installer ensures that the skill(s) are updated with the changed tunnel URL whenever you restart ngrok or reboot your machine.

Visit our secure[1] configurator landing page to download your personalized easy-install script. You must provide the following 7 pieces of information:

  •  Target platform / operating system under which ngrok will run.
  •  Region. To minimize latency, ngrok will use a cloud server physically near you. You can choose one of us eu ap au sa jp in.
  •  Authtoken. Paste the personal authtoken you copied after ngrok sign-up (e.g. 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p) or else use the yellow button to visit your ngrok account and retrieve it.
  •  A username to associate with your tunnel to prevent unauthorized access to LMS. It must be at least 4 characters and may not contain spaces or |.
  •  A password to associate with your tunnel to prevent unauthorized access to LMS. It must be at least 8 characters and may not contain spaces or |.
  •  The local fixed IP address used to access LMS inside your LAN. For example, http://192.168.1.10:9000. You may omit the http part but not the 9000.
  •  A nickname[2] by which to refer to the tunnel — defaults to lmstunnel if left blank.

When all the entries are completed, press the yellow Download Script button and the script file will be saved by your browser.

Your browser may warn that script files sourced from the internet are potentially harmful — it does this based on the .sh or .ps1 file extension. In this case, you can safely opt to save the file. Always perform a virus scan if in doubt !


[1] All sensitive data is transported over SSL and AES-256 encrypted at rest. The resulting file is built in RAM on our webserver — it is never saved to the filesystem.

[2] You should only need to specify a non-default nickname if you have multiple LMS servers and therefore multiple tunnels.

First follow the appropriate instructions for your platform or operating system — pCP, Linux, or Windows 10. Then perform account-linking as explained below.


piCorePlayer
Make sure that the LMS server under pCP is already installed and running when you attempt this.

  • Open a terminal. Place[1] the downloaded file setup.sh in your /home/tc directory.
  • Run it using sh setup.sh.

Installs ngrok as a persistent tcz package and adds it to onboot.lst. It also builds a file called ~/.ngrok2/ngrok.yml with your configuration details. An entry in /opt/bootlocal.sh ensures ngrok_startup.sh runs at system boot to continually refresh your tunnel details when you reboot.


Debian Linuxes
Applies to any Debian-based distro which supports systemd services and bash scripting. Examples include Max2Play, Raspberry Pi OS, Ubuntu and Debian.

  • Open a terminal. Place[1] the downloaded file setup.sh in your home directory, e.g. /home/pi.
  • Run it using sudo bash setup.sh.

Installs ngrok to /usr/local/bin/ngrok and creates a service file /etc/systemd/system/ngrok.service to run ngrok as a daemon at boot. It also builds a file called ~/.ngrok2/ngrok.yml with your configuration. Finally, it creates the ~/ngrok_updater.sh auto-updater file that refreshes your tunnel details when you reboot.


Windows 10
This is perhaps the easiest install, so you could consider using it temporarily when evaluating a skill. Remember, ngrok does not have to run on the LMS machine itself — it can happily proxy from a running PC to an LMS server on a NAS or pi.

  • Right-click on the downloaded PowerShell file setup.ps1 in your downloads folder and select the option to Run with PowerShell. If that is not allowed on your PC, see the comments in the file for a simple fix.

Installs ngrok to c:\ngrok and creates a config file called c:\ngrok\ngrok_config.yml. In the same directory, you'll see ngrok_autostart.ps1 and a wrapper ngrok_autostart.cmd. A shortcut to ngrok_autostart.cmd is added to Windows' startup apps folder.


Account Linking
When the setup script finishes, you will be told[2] that ngrok is now running a tunnel through a URL like https://70c663eee228.eu.ngrok.io[3]

  • Enable/Link the skill(s) from here: [ → MediaServer | LMS-lite | Playground | Squeeze ]. You will be redirected to log in to your Amazon account and authorize/allow Alexa access to the skill in question. The correct language version for your locale will be automatically selected.
  • If you prefer to link the skill(s) manually from the Alexa portal, in the field you will enter the assigned ngrok URL, adding your credentials in the and fields. See here.
If you installed LMS-lite, you can now say "Alexa, discover devices". In the case of MediaServer, say "Alexa, open MediaServer". That's it — enjoy the skill(s)!


[1] If the target system is headless, use ssh or scp via e.g. filezilla, winscp or putty to transfer the script file across.

[2] On the free plan, ngrok can only be run on a single machine in your local LAN so if it's already running you will receive an error. If you run ngrok with the same authtoken in a different (remote) LAN, you must select a different region code for the second instance or it won't work. If you need multiple tunnels in the same LAN, up to 4 can all be run from the same proxying-machine by adding extra tunnel entries to the .yml file. Do it this way rather than trying to run multiple instances of ngrok itself. The legacy help has an example.

[3] If you like, you can verify that the tunnel works by visiting this URL from a browser (enter your chosen credentials in the popup). You'll see the familiar 9000 LMS GUI (notice the ).

Setup help for MediaServer and LMS-lite is available at different subdomains of the smartskills.tech website. Because your uuid is stored in the browser's localStorage and that is always (sub)domain-specific, you may be told that you have not yet set things up if you alternate between help-file source locations on our server. If this happens, switch to the help subdomain you originally used and your localStorage should still be there. Same is true if you use different browsers or alternate between incognito and regular browsing.


The golden rule is — think before you re-link! It's almost never necessary.

When you're on the free ngrok plan, a machine reboot causes the ngrok cloud service to issue a new URL to you. When that happens, Alexa cannot reach your LMS server because it has 'moved'. Same story if you restart the ngrok daemon, or  — perhaps unexpectedly — if the link between the ngrok cloud service and your machine momentarily drops. That can happen e.g. because:

  • WiFi reception is poor or a microwave caused brief interference.
  • You put a laptop in flight mode.
  • You pulled a network cable without thinking of the consequences.
  • You rebooted your router.

Machine-reboot on all systems (plus daemon-restart on Debian Linuxes) runs the update script to push your new tunnel details off to the skill(s). That does not happen, however, when the drop was an unexpected/spurious one.

If Alexa tells you your ngrok tunnel no longer exists, manually running the updater script should get you back online again immediately. If it happens regularly, consider using Ethernet rather than WiFi or move the machine closer to your router. Remember, ngrok can run on any machine in your network and happily proxy to LMS on a different machine. If you're running e.g. pCP on a wireless-pi, you can run ngrok on a different/wired machine no problem.


If Alexa tells you that ngrok returned an authorization failure, unless you deliberately changed the username and password in your .yml file, the only plausible explanation is that you dropped a tunnel without yet updating. In the meanwhile, your old URL was randomly allocated to some other ngrok user (by ngrok, not us) who of course has different credentials to you. So the previously-known tunnel 'exists' but the authorization fails (for you). The cure is to manually restart ngrok on your machine — that way, you will get a new URL without conflict. If you really did change your .yml credentials then you have no option other than to re-link the skill(s). The tunnel credentials are immutable in the Alexa cloud and not pushed as part of updating (for security reasons).


If for whatever reason you want to reset your uuid to start an install with a clean slate, click on the tiny symbol in the info-banner on the configuration page.