LUMOplay remote control API

This article is for LUMOplay v4.0.7+2 or later

LUMOplay features a new remote control system that allows you to write BAT files to control games using a second screen or tablet.  Using this scripting system you can control what game LUMOplay is running, skip between games in a playlist, install new games, or change the current playlist.

We're planning on releasing a remote control app for iPhone and Android in the new year -- stay tuned for an announcement about that!  But for now, this article will teach you how to use the MotionPlayer.Scripting.exe program included in your LUMOplay installation.  This article is written assuming you have little-to-no experience using the Windows Command Prompt or writing BAT files.  If you are familiar with these pieces of the Windows operating system then you may find it helpful to skip straight to step 2.

 

New Feature

We have recently added a new feature that allows you to set the desired IP address to use to listen for commands. This is specifically useful for machines with multiple connections available. Simply enter the desired IP address in the textbox, and click save. Saving this will restart the remote server using the desired IP as well as using that IP for subsequent runs. You can find this under Preferences in the Remote Control section.

Step 1: BAT File Basics

BAT files -- or batch files -- are executable text files used by Windows to run commands.  If any of you remember the movie WarGames you may be familiar with the pre-graphics days of computing in which you had to type the name of every program you wanted to run.  Fortunately, we've come a long way since then, but the old systems are still there and are sometimes useful.

Before we start creating our BAT file, first we're going to run some commands directly from the terminal. Open a Windows Command Prompt from the start menu:

A window that looks like this should appear:

Now type the following into the window and press Enter:

"C:\Program Files\Lumo Play\MotionPlayer.Scripting.exe" --help

Note: if you installed LUMOplay to a different directory than C:\Program Files\Lumo Play you will need to modify the path to the appropriate location on your system.

After you press Enter the following text should appear in the command prompt:

Usage: MotionPlayer.Scripting.exe -a ADDRESS -k KEY Command1 [Command2] [Command3] [...]
 Command* may be any one of: -i, -g, -l, -n, -p, -s, -N, -L -P
 Multiple commands may be specified. They will be executed in the same order as presented
 -a, --address=IP_ADDRESS The IP_ADDRESS of the installation to control
 -k, --key=CRYPTO_KEY The CRYPTO_KEY used to encrypt communication with
 the target installation
 -i, --install=ID Install the game with the specified ID
 -g, --game=ID Play the game with the specified ID. This will
 change the current playlist so that it contains
 just a single game
 -l, --playlist=PLAYLIST_ID:INDEX
 Change the playlist to the one with the given
 PLAYLIST_ID, and start playing at position INDEX
 -n, --skip-next Skip to the next game in the current playlist
 -p, --skip-prev Skip to the previous game in the current playlist
 -s, --stop Stop the current game and playlist
 -N, --now-playing Get the current playlist and game
 -P, --get-playlists Get all available playlists
 -L, --get-library Get all games in the user's library
 -t, --timeout Set the maximum allowed time for the remote
 installation to respond in seconds. Default: 10
 -v, --version Print version information
 -h, --help Show this message

This lists all of the commands the MotionPlayer.Scripting.exe program can send to LUMOplay.  Now, let's try telling LUMOplay to play a game.

 

Step 2: Enable Remote Control

The first thing to do before you can control LUMOplay from the command-line is to enable remote control in LUMOplay.  The image above shows the remote control preferences panel, which you can locate by clicking on the Preferences item in the main menu.

When you first enable remote control in LUMOplay you will probably a Windows Firewall warning, as shown below:

The LUMOplay remote control needs permission to open a network socket to allow other PCs and devices to send it commands.  The exact port used is undefined; Windows will assign a random TCP port to LUMOplay for use every time it launches with remote-control enabled.  Additionally, LUMOplay will open a UDP socket on port 64404* in order to announce its availability to be remote-controlled.

Enabling remote control will generate a random, strong password.  This password is used to secure communication between LUMOplay and the device sending it commands.  To reveal the password press the eyeball button beside the password.  You can generate a new password by pressing the reset button beside the eyeball.

Make a note of this password; you will need it later.  The password is case-sensitive.

_____________________________

*If port 64404 is already in use by another application, LUMOplay will increment the port to 64405, 64406, etc... until it finds an open UDP port it can use.  It will only attempt to open ports in the range 64404-64414.  If none of these ten ports are available the remote control feature may not work properly on your system until you close some other applications

 

Step 3: Controlling LUMOplay

The MotionPlayer.Scripting.exe program requires 3 parameters to control LUMOplay:

• The IP address of the computer that is running LUMOplay. To control LUMOplay on the same machine, use 127.0.0.1
• The Remote Control key/password generated in step 2 (see above)
• One or more commands to send to LUMOplay.  Certain commands may require additional parameters

For this first try, let's just tell LUMOplay to play a single game.  Looking at the list of parameters from Step 1, we see the

-g, --game=ID

parameter is used to play a game with a specific ID.  To find the ID of a game, simply right-click on it in LUMOplay and select "Details..."

 

The game's ID number is displayed in the window.

Finally, we can run the following command to make LUMOplay run the game:

"C:\Program Files\Lumo Play\MotionPlayer.Scripting.exe" -a 127.0.0.1 -k "bn-Dps*K" -g 80

Note that you will have to change the remote control key to whatever password you created in step 2.

 If the game is not already installed, you will need to install it first.  Fortunately, you can do this with a similar command:

"C:\Program Files\Lumo Play\MotionPlayer.Scripting.exe" -a 127.0.0.1 -k "bn-Dps*K" -i 80

 

Part 4: Creating a BAT File

To create a BAT file, simply create a new document in Notepad and save it with a .bat extension (instead of .txt).  Note that many email systems do not allow sending files with a .bat extension as attachments, so if you need to send your file to someone else you may need to change the file extension.

Every line in a BAT file represents a single program you want the computer to run.  For this example, we'll be taking the command to play Free Dance Floor Retro and turning it into a BAT file.  Open Notepad and type (or copy-and-paste) the following, making sure to change the key as needed:

"C:\Program Files\Lumo Play\MotionPlayer.Scripting.exe" -a 127.0.0.1 -k "bn-Dps*K" -g 80

Save the file as LUMOplay-Disco.bat and close notepad.

Now, with LUMOplay running, double-click on the BAT file you just created.  The Disco Floor game should start playing right away!

 

Part 5: Running From Different Computers

So far all of our examples have been running the BAT file from the same computer that LUMOplay is running from.  But using the BAT files you can control LUMOplay on one computer from a different one!

The first thing you'll need to do is copy two files from your LUMOplay installation directory:

• MotionPlayer.Scripting.exe
• Prism.RemoteControl.dll

You can find both of these files in C:\Program Files\Lumo Play

Once you've copied these files to your other computer, you can change the IP address in your BAT files to the address of the computer that is running LUMOplay.  On most home networks the address will probably start with 192.168.  Check your Windows Network settings to figure out what your IP address is:

 

 

Part 6: Playing Playlists

So far all of our examples have played an individual game.  But you can also play an entire playlist.  To play a playlist, simply replace the "-g <gameID>" parameters with "-l <playlistID> <startIndex":

"C:\Program Files\Lumo Play\MotionPlayer.Scripting.exe" -a 127.0.0.1 -k "bn-Dps*K" -l -39476576 0

To get the ID of a playlist, right-click on it in the sidebar on the left side of LUMOplay. The playlist's ID will be shown on the bottom row of the pop-up menu.

Note: local playlists have negative IDs, and remote playlists have positive ones. Make sure to include the minus sign if necessary!

 

Troubleshooting Tips

If you have problems running your BAT files (or commands directly from the command prompt), the first thing to do is to make sure you're using the correct IP address and password.  Open LUMOplay and double-check that the password you're entering matches what's displayed in the Remote Control preferences.

If you are trying to run a BAT file, try copying the command and pasting it directly into the command prompt. Sometimes certain characters are treated differently in the BAT file than they are in the command prompt.  For example, the % symbol needs to be doubled-up if it's used in a BAT file:

"C:\Program Files\Lumo Play\MotionPlayer.Scripting.exe" -a 127.0.0.1 -k "aDd%147" --now-playing

will work properly when run from the command prompt, but if you copy this command into a BAT file, you need to replace the % character with %%:

"C:\Program Files\Lumo Play\MotionPlayer.Scripting.exe" -a 127.0.0.1 -k "aDd%%147" --now-playing

The password is still technically the same, but BAT files process the % character differently than most other characters, which can cause issues.

Finally, if you are running your BAT file on one machine, and LUMOplay on a different one, make sure that the Windows Firewall is configured to allow both MotionPlayer.exe and MotionPlayer.Scripting.exe to access the network.

Both computers need to be operating on the same subnet.  At home, this means making sure they're both connected to the same router.  In a commercial installation, make sure your IT department sets up both computers to operate on the same subnet, and make sure there isn't a firewall between them that will block communication.

 

Next Steps

Using the steps we've shown here, you can write batch files to remotely tell your LUMOplay installation to play specific games and playlists.  Try using some of the other commands supported by MotionPlayer.Scripting.exe to create BAT files to do other things.  For example, use the --stop parameter to make LUMOplay stop all games.  Or use the --skip-next parameter to cycle through games in a playlist.