Launcher
Launch external programs from within Opencpn.
What and Why
A. What does Launcher do
The plugin allows the user to define several buttons to launch external
(Standard Actions) or internal commands (Keyboard Events).
It is primarily targetting touchscreen devices but can also be used with
a mouse.
External commands are all the commands you can give to your computer.
Internal commands are used in OpenCPN itself.
B. Why can Launcher be useful
You can use a button in Launcher (while you keep running OpenCPN) to do something else with your computer than just running OpenCPN.
You could for instance:
Open a document with information you find usefull. That can be anything. The manual of your ship’s engine, your favourite recipes for that freshly caught mackerel (or, if you did not catch anything, the book “Fishing for Dummies”), a document with all the facts of interests of the ports you pass, pilotage information, you name it.
When you have access to the Internet you could use Launcher to open a
specific website.
For instance the OpenCPN-website, the Cruisers Forum, Marine-Traffic
(AIS) etc. etc.
In “Standard actions” we will show some examples.
Installation
A. Where to get Launcher
+ *Note*: In this section the instructions are specifically for Launcher, but there is a dedicated page in the manual with information about Downloading, Installing and Enabling Plugins in general. That dedicated page can be found here: link:../install_and_enable.html[Plugins - Install and Enable].
Launcher can be downloaded from http://www.opencpn.org/index.html
Click “Downloads”
Click “Plugins for OpenCPN 4.2 & 4.4”
Scroll down to the “Other”-section and click “Launcher“
B. How to install the plug-in
Make sure you choose the file that is compatible with your
computersystem. In this manual we presume it’s Windows, so we choose the
Windows setup-package.
Download the file (double-click).
B. How to install Launcher
We assume you know where to find the files you download from the
Internet
(if you don’t: quit now and read the manual of your computer before
doing anything else with it)
Double-click the downloaded file (with “launcher_pi” in the name and ”.exe” as extension) and follow the set-up instructions.
That’s it. But before you can actually use Launcher, you first have to enable that plug-in in OpenCPN.
Enabling Launcher in OpenCPN
Open (or restart) OpenCPN.
Click Tools-Options-.
and then Plugins
Scroll down untill you see the Launcher-pi.
Click “Enable”.
Note: If you do not see launcher in the list of plugins, check it was installed in the correct plugings directory of OpenCPN (eg: C:\Program Files (x86)\OpenCPN\plugins)
Now the Launcher icon (it looks like an old fashioned ship’s wheel) should appear somewhere in your OpenCPN Toolbar.
Standard actions
Follow the steps below to launch an external program
Click “Tools” - “Options” - “Plugins” as described before.
Scroll down to “Launcher” and click “Preferences”.
Clicking “Preferences” will open the menu “Launcher Settings”.
In the menu “Launcher Settings”, Click “Add”.
Clicking “Add” will open the menu “Launcher Item”.
In this menu “Launcher Item” you will have to give Launcher some
information.
You want a button in Launcher-pi to launch a program for you, so you
will have to tell Launcher-pi:
1. What label you want on that button and
2. Where Launcher-pi can find the command to launch that specific
program.
EXAMPLE:
you want a button to launch a specific document (let us assume it is a
user manual of your ship) that is made with the program Microsoft
WORD.
You can find the path and file-name to run WORD by a right-hand
mouse-click on the icon (shortcut) for that program.
Choose “Properties” and copy the text that is in the field
“target”.
Let us assume that:
The path and file to execute that program is “C:\Program
Files\Microsoft Office 15\root\office15\WINWORD.EXE”.
The file (document) you want to open is called
“Manual_of_my_ship.docx” and stored in a directory
C:\MyShip\Manuals.
IMPORTANT:
If the pathname\filename consist of several words separated with a
blank space, change that by removing those blank spaces or by replacing
them by underscores. Example: “C:\My ship\Manuals” should be renamed
to “C:\Myship\Manuals” or “C:\My_ship\Manuals” and “Manual of my
ship.docx” should be renamed to “Manual_of_my_ship.docx”.
So to assign a button in Launcher to launch that specific WORD-document, you will have to feed Launcher the following information:
1. The label you want for the button.
In this case: “Manual of my ship”.
2. The path and program-file .
In this case: “C:\Program Files\Microsoft Office
15\root\office15\WINWORD.EXE”.
3. The path and specific file to open with that program.
In this case: “C:\MyShip\Manuals\Manual_of_my_ship.docx”.
This is how you do that:
Insert the label Manual of my ship
Insert the command C:\Program Files\Microsoft Office
15\root\office15\WINWORD.EXE
IMPORTANT: Leave one space after “exe” and add the path and
name of the file you want to open.
In this case: C:\MyShip\Manuals\Manual_of_my_ship.docx
The text in the field “command” should read C:\Program Files\Microsoft
Office 15\root\office15\WINWORD.EXE
C:\MyShip\Manuals\Manual_of_my_ship.docx
Click “OK” to save the Launcher item.
Click “OK” to save the Launcher settings.
Click “OK” to exit the “options”-menu and return to the main screen of OpenCPN.
Now you can execute the command via Launcher-pi.
Executing a command via Launcher
To execute the command via Launcher in OpenCPN, do this:
Click on the Launcher icon in the toolbar.
Click the button with the label “Manual of my ship”
The WORD-document should open.
Note: of course this WORD-document can only be opened if you actually
have the program WORD on your computer in the given directory
(C:\Program Files\Microsoft Office 15\root\office15\WINWORD.EXE) and if
you actually do have a document called “Manual_of_my_ship.docx” in the
given directory (C:\MyShip\Manuals\).
You can repeat this process of adding Launcher items. With every new assignment you will see the number of buttons growing.
Internal OpenCPN Actions
Launcher can be used to issue OpenCPN a command such as change the scale for a chart (F7 or F8 key). To do this you use a keyboard event in the place of the command.
Launcher Variables
Launcher 1.1 has some nice new functionality Readme in github main repository
See Keyboard Events
Variables
You can use several variables in your commands which will be replaced with the actual values at the moment of command invocation.
| Variable | Meaning |
|---|---|
——– |
——- |
%BOAT_LAT% |
Boat Latitude |
%BOAT_LON% |
Boat longitude |
%BOAT_SOG% |
Boat SOG |
%BOAT_COG% |
Boat COG |
%BOAT_VAR% |
Magnetic variation |
%BOAT_FIXTIME% |
The timestamp of the past fix (seconds since 01/01/1970 UTC) |
%BOAT_NSATS% |
Number of satelites “visible” during the last fix |
Keyboard Events
Start the command definition with string KBD: followed by coma separated list of key events to send to the main application. A component starting with ! (explanation mark) represents a key down even, a component without the beginning ! represents a key up event. Example: KBD:!S,S represents a short press of the S key, resulting in turning on/off the soundings.
Special keys may be used if implemented by the plugin. Example:
KBD:!F5,F5 represents a short press of the F5 key, resulting in
switching the color scheme.
Special keys implemented: F1-F12
Example: KBD:!F7,F7 for a change of chart scale
Examples
Here are some examples for use of the Launcher Plugin:
VDRplayer
Launcher can be used to start various nmea VDR files to test plugins. See NMEA-Software towards bottom VDRplayer as Nmea Server
Websites
+ In this example we show how to make a Launcher item to launch a website (in this case the website of the Dutch Coastguard, which is https://www.kustwacht.nl[www.kustwacht.nl]) with Google Chrome. +
To do so, you first have to find and copy the command to launch the
program Google Chrome.
That should be something like C:\Program Files
(x86)\Google\Chrome\Application\chrome.exe.
You can find the path and file-name to run Chrome by a right-hand
mouse-click on the icon (shortcut) for that program, choose
“Properties” and select (all) the text in the field “Target”. Click
“copy”.
Go to OpenCPN.
Edit Launcher.
-
Click Tools-Plugins-Launcher-Preferences
-
Click Add
-
Insert the label (Dutch Coastguard)
-
Insert (paste) the command C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
-
leave one space after “exe” and add the adress of the website (in this case: www.kustwacht.nl)
The text in the field “command”should read:
C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
www.kustwacht.nl
Click “OK” to save the Launcher item.
Click “OK” to save the Launcher settings.
Click “OK” to exit the “options”-menu and return to the main screen of
OpenCPN.
Execute the command via Launcher-pi in OpenCPN as described before.
Click on the Launcher-pi icon in the toolbar.
Click the button with the label “Dutch Coastguard” to open the
website.
One other example you might find useful.
When you are sailing in US waters you might want to consult one of the
“United States Coast Pilots”.
These pilots are published by the NOAA and can be downloaded (free of charge) from https://www.nauticalcharts.noaa.gov/nsd/cpdownload.htm
There are several volumes. In this example we have downloaded “US Coast Pilot nr. 2 (Atlantic Coast: Cape Cod, MA to Sandy Hook, NJ), 207 (46th) Edition”.
It is a PDF-document. So if your computer has a program that can read
PDF-files, you can read that document on your computer-screen.
And with Launcher, you can launch that document directly from within
OpenCPN.
You just have to add a button for it in “Launcher”.
This is what you do:
Download the document and save it on your computer.
Let’s say you save the document as “Pilot_2_Cape_Cod_to_Sandy
Hook.pdf” in a directory “C:\Nautical\US_Coast_Pilots” (remember the
importance of avoiding spaces between the words in the path- and
filename, use underscores instead!)
In OpenCPN, edit Launcher as described before:
click “Tools” - “Options” - “Plugins”.
Scroll down to “Launcher” (make sure the plugin is “Enabled”)
Click “Preferences“
Click “Add“
In the field “Label”: enter the name you want to give to the button.
In this case for instance “US Pilot 2-Cape Cod to Sandy Hook”.
In the field “Command”: enter the path and filename of the program you
use to open PDF-files.
If you use Adobe Reader it might be something like this:“C:\Program
Files (x86)\Adobe\Reader 11.0\Reader\AcroRd32.exe”.
If you use an alternative PDF-reader, like the freeware PDFXchange
Editor, it might be something like this: “C:\Program Files\Tracker
Software\PDF Editor\PDFXEdit.exe”.
Leave a space and enter the path and filename of the document you want
that program to open.
In this case that would be:
“C:\Nautical\US_Coast_Pilots\Pilot_2-Cape_Cod_to_Sandy_Hook.pdf”.
Click “OK” to save the Launcher item.
Click “OK” to save the Launcher settings.
Click “OK” to exit the “options”-menu and return to the main screen of
OpenCPN.
Execute the command via Launcher-pi in OpenCPN as described before.
Click on the Launcher-pi icon in the toolbar.
You should see the button that corresponds with the US Coast Pilot nr.
2.
Click that button and the file will open.
Frequently Asked Questions
Q: I have edited Launcher to execute a command, but it doesn’t work.
What did I do wrong?
A: We don’t know. There’s a lot you might have done wrong.
But check the correct pathnames\filenames. If the pathname\filename
consist of several words separated with a blank space, change that by
removing those blank spaces or by replacing them by underscores.
Example: “C:\My ship\Manuals” should be renamed to
“C:\Myship\Manuals” or “C:\My_ship\Manuals”.
Q: Can I use Launcher to shut down my computer?
A: Yes. It is possible.
Here’s an example how to do it in Windows 7 Home Edition 64 bit.
Add a new launcher item.
Type in the field under “label” the text “Shut down after 10 seconds”
Type in the field under “Command” the text
shutdown -s -t 10 -c “I quit. You’ve got the helm”
This should shut down your computer 10 seconds after launching that
item.
Of course you can alter the text “I quit. You’ve got the helm” in
anything you like.
Just don’t forget to put that text between quotation marks (”).
Note: Windows 7 Pro 64-bit might not accept the ”-s” parameter
from Launcher. Try ”/s“ instead.