Launcher

Launch external programs from within Opencpn.

This document is about Launcher plugin (Launcher)

launcher 01

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

watchdog 19056 001 ocpn 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).

launcher 02

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.

launcher 03

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-.

launcher 04

and then Plugins

launcher 05

Scroll down untill you see the Launcher-pi.

Click “Enable”.

launcher 06

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.

launcher 07

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”.

launcher 08

Clicking “Preferences” will open the menu “Launcher Settings”.

In the menu “Launcher Settings”, Click “Add”.

launcher 09

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.

launcher 10

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

launcher 11

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

launcher 12

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.

launcher 13

Click “OK” to save the Launcher settings.

launcher 14

Click “OK” to exit the “options”-menu and return to the main screen of OpenCPN.

launcher 15

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.

launcher 07

Click the button with the label “Manual of my ship

launcher 16

The WORD-document should open.

launcher 17

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

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.

  1. Click Tools-Plugins-Launcher-Preferences

  2. Click Add

  3. Insert the label (Dutch Coastguard)

  4. Insert (paste) the command C:\Program Files (x86)\Google\Chrome\Application\chrome.exe

  5. 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.

launcher 18

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.