Javascript Plugin
Aim
To provide a plugin that allows users to write scripts that extend the functioning of OpenCPN without getting into the complexity of writing a plugin.
How does it work?
The plugin provides one or more console windows comprising a script pane, a results pane and some buttons. You enter your JavaScript in the script pane (or load it from a file) and click on the Run button. The script is compiled into byte code and executed and any result is displayed. At its simplest, enter, say
print("Hello from OpenCPN\n");
When you click on the Run button, the message will be displayed. (The \n bit adds a new line to the end of the message.)
The plugin extends JavaScript to add many interfaces to OpenCPN and it is here that the fun starts. As an example, the following statement takes the supplied NMEA sentence, adds a checksum (replacing any existing one) and pushes it out over the OpenCPN connections:
OCPNpushNMEA(“$OCRMB,A,0.000,L,,Yarmouth,5030.530,N,00120.030,W,
15.386,82.924,0.000,5030.530,S,00120.030,E,V");
It is also possible to arrrange for a JavaScript function to be executed on certain OpenCPN events. For example, this script listens for an NMEA sentence and, if it the checksum is correct, displays it.
OCPNonNMEAsentence(handleNMEA);
function handleNMEA(result){
if(result.OK){
print(“Received: “, result.value, “\n”);
}
else print(“Bad checksum\n”);
}
Example application
The following script examines all waypoints. If the icon name is circle, it sets the waypoint to display at all chart scales. Otherwise it set it to display on large scale charts only. Thus anchorage waypoints, docks and the like will not clutter small scale charts.
You can easily adopt this to your own criteria.
scaled = unscaled = 0; // counters
guids = OCPNgetWaypointGUIDs(); // get all waypoint GUIDs
for (g = 0; g < guids.length; g++){ // for each waypoint
waypoint = OCPNgetSingleWaypoint(guids[g]); // get the waypoint
if (!waypoint.isFreeStanding) continue; // skip routepoints
if (waypoint.iconName == "circle") {
waypoint.useMinScale = false;
unscaled++;}
else {
waypoint.minScale = 52000;
waypoint.useMinScale = true;
scaled++;
}
OCPNupdateSingleWaypoint(waypoint); // update in OCPN
}
scriptResult("scaled: " + scaled + " unscaled: " + unscaled);
Script library
There is a library of useful scripts which you can use as they are or modify for your own purposes. Contributions to this are welcome.
Resources
A comprehensive user guide is available as a .pdf and also in .epub format, which may be more convenient for mobile devices. They can be down-loaded from here:
There is also a technical guide for those wanting to undestand the internal functioning of the plugin or maintain it. This is not relevant for plugin users.
Support
For discussion on applications of the plugin, use the forum thread.
For problems with the plugin or feature requests, please raise an issue here.
FAQs
How do I learn JavaScript programming?
Start with a simple example and build up by trying things. Have a look at the examples in the script library.
There is a good reference guide here. JavaScript is much used in programming web sites and many of the examples in the tutorials assume that. Ignore examples accessing the document object, such as document.getElementById("demo").innerHTML The reference material is very good but some of the latest JavaScript constructs are not supported by the plugin. See the plugin user guide.
Can it do this or that?
Read the user guide which documents the APIs that allow a script to interact with OpenCPN. Have a look at the library of sample scripts, which may help you see how to do what you want. If you cannot find what you need, ask in the plugin forum.
It cannot do what I need - can that be added?
If you have confirmed the plugin cannot do something you would like it to, submit an enhancement request here.