Plugin Communication

This chapter explains how plugins can communicate with each other and with the OpenCPN core application. Plugin communication allows for sharing data, coordinating actions, and creating plugin ecosystems.

Overview

OpenCPN provides a messaging system that allows plugins to send and receive messages. This system enables:

Communication between plugins
Publishing and subscribing to data streams
Coordinating actions between plugins
Creating extensible plugin ecosystems

Plugin Messaging Capability

To participate in plugin messaging, a plugin must declare the WANTS_PLUGIN_MESSAGING capability:

int MyPlugin::Init(void) {
    // Initialize resources
    // ...

    // Return capabilities
    return WANTS_PLUGIN_MESSAGING;
}

Receiving Messages

To receive messages, your plugin must implement the SetPluginMessage() method:

void MyPlugin::SetPluginMessage(wxString &message_id, wxString &message_body) {
    // Process the message based on its ID
    if (message_id == "OCPN_WPT_ARRIVING") {
        // Handle waypoint arrival message
        // message_body contains waypoint information
        ProcessWaypointArrival(message_body);
    }
    else if (message_id == "OCPN_ROUTE_ACTIVATED") {
        // Handle route activation message
        // message_body contains route information
        ProcessRouteActivation(message_body);
    }
    else if (message_id == "MY_CUSTOM_MESSAGE") {
        // Handle custom message from another plugin
        ProcessCustomMessage(message_body);
    }
}

Sending Messages

To send a message to other plugins, use the SendPluginMessage() function:

void MyPlugin::SendMyMessage() {
    // Create message ID and body
    wxString message_id = "MY_PLUGIN_UPDATE";
    wxString message_body = "{\"status\":\"active\",\"data\":\"42\"}";

    // Send the message
    SendPluginMessage(message_id, message_body);
}

All plugins that have declared the WANTS_PLUGIN_MESSAGING capability will receive this message through their SetPluginMessage() method.

Message Format Conventions

While the plugin messaging system doesn’t enforce a specific format for message bodies, several conventions have emerged:

JSON Format

JSON is a popular format for structured messages:

wxString message_body = "{\"command\":\"update\",\"params\":{\"lat\":47.6,\"lon\":-122.3}}";

Parsing JSON messages:

#include <wx/json_defs.h>
#include <wx/jsonreader.h>
#include <wx/jsonwriter.h>

void MyPlugin::ProcessJsonMessage(const wxString &message_body) {
    wxJSONValue root;
    wxJSONReader reader;

    int errors = reader.Parse(message_body, &root);
    if (errors > 0) {
        // Handle parsing error
        return;
    }

    // Extract data from JSON
    if (root.HasMember("command")) {
        wxString command = root["command"].AsString();

        if (command == "update") {
            // Process update command
            if (root["params")].HasMember(_T("lat") &&
                root["params")].HasMember(_T("lon")) {

                double lat = root["params")][_T("lat"].AsDouble();
                double lon = root["params")][_T("lon"].AsDouble();

                // Process lat/lon
                // ...
            }
        }
    }
}

Simple Key-Value Format

For simpler messages, a key-value format can be used:

wxString message_body = "lat=47.6;lon=-122.3;spd=5.2;cog=120";

Parsing key-value messages:

void MyPlugin::ProcessKeyValueMessage(const wxString &message_body) {
    // Split by semicolons
    wxArrayString pairs = wxStringTokenize(message_body, ";");

    // Initialize variables
    double lat = 0.0, lon = 0.0, spd = 0.0, cog = 0.0;

    // Process each key-value pair
    for (size_t i = 0; i < pairs.GetCount(); i++) {
        wxArrayString pair = wxStringTokenize(pairs[i], "=");

        if (pair.GetCount() == 2) {
            wxString key = pair[0];
            wxString value = pair[1];

            if (key == "lat") value.ToDouble(&lat);
            else if (key == "lon") value.ToDouble(&lon);
            else if (key == "spd") value.ToDouble(&spd);
            else if (key == "cog") value.ToDouble(&cog);
        }
    }

    // Process extracted values
    // ...
}

XML Format

For more complex structured data, XML can be used:

wxString message_body = "<data><position lat=\"47.6\" lon=\"-122.3\"/><speed value=\"5.2\"/></data>";

Parsing XML messages:

#include <wx/xml/xml.h>

void MyPlugin::ProcessXmlMessage(const wxString &message_body) {
    wxStringInputStream stream(message_body);
    wxXmlDocument doc;

    if (!doc.Load(stream)) {
        // Handle parsing error
        return;
    }

    wxXmlNode *root = doc.GetRoot();
    if (root && root->GetName() == "data") {
        // Process data node
        wxXmlNode *child = root->GetChildren();
        while (child) {
            if (child->GetName() == "position") {
                // Get position attributes
                double lat = 0.0, lon = 0.0;
                wxString lat_str = child->GetAttribute("lat"), _T("0");
                wxString lon_str = child->GetAttribute("lon"), _T("0");

                lat_str.ToDouble(&lat);
                lon_str.ToDouble(&lon);

                // Process position
                // ...
            }
            else if (child->GetName() == "speed") {
                // Get speed attribute
                double spd = 0.0;
                wxString spd_str = child->GetAttribute("value"), _T("0");

                spd_str.ToDouble(&spd);

                // Process speed
                // ...
            }

            child = child->GetNext();
        }
    }
}

Standard Message IDs

OpenCPN defines several standard message IDs for common events. Plugins can listen for these messages to be notified of system events.

Core OpenCPN Messages

Message ID Description

Message ID	Description
`OCPN_WPT_ARRIVED`	Sent when the vessel arrives at a waypoint. Message body contains waypoint information.
`OCPN_ROUTE_ACTIVATED`	Sent when a route is activated. Message body contains route information.
`OCPN_ROUTE_DEACTIVATED`	Sent when a route is deactivated. Message body contains route information.

OCPN_WPT_ARRIVED

Sent when the vessel arrives at a waypoint. Message body contains waypoint information.

OCPN_ROUTE_ACTIVATED

Sent when a route is activated. Message body contains route information.

OCPN_ROUTE_DEACTIVATED

Sent when a route is deactivated. Message body contains route information.

Plugin-to-Plugin Communication

When creating messages for plugin-to-plugin communication, follow these naming conventions:

Use a prefix based on your plugin name to avoid conflicts
Make message IDs descriptive of their purpose
Consider versioning for evolving message formats

Example naming scheme:

// Weather plugin messages
wxString MSG_WEATHER_UPDATE = "WEATHER_PLUGIN_UPDATE_V1";
wxString MSG_WEATHER_FORECAST = "WEATHER_PLUGIN_FORECAST_V1";

// Navigation plugin messages
wxString MSG_NAV_POSITION = "NAV_PLUGIN_POSITION_V1";
wxString MSG_NAV_DESTINATION = "NAV_PLUGIN_DESTINATION_V1";

Plugin Communication Patterns

Publisher-Subscriber Pattern

In this pattern, one plugin publishes data that other plugins can subscribe to:

Publisher Plugin:

// Weather plugin publishing forecast data
void WeatherPlugin::PublishForecast() {
    // Create forecast data
    wxString forecast_data = CreateForecastJson();

    // Publish to subscribers
    SendPluginMessage("WEATHER_FORECAST_V1", forecast_data);
}

Subscriber Plugin:

// Navigation plugin subscribing to weather forecasts
void NavigationPlugin::SetPluginMessage(wxString &message_id, wxString &message_body) {
    if (message_id == "WEATHER_FORECAST_V1") {
        // Process weather forecast data
        ProcessWeatherForecast(message_body);
    }
}

Request-Response Pattern

In this pattern, one plugin requests information from another:

Requester Plugin:

// Request current weather data
void NavigationPlugin::RequestWeatherData() {
    // Create a unique request ID
    m_request_id = wxDateTime::Now().GetTicks();

    // Build request message
    wxString request = wxString::Format(
        "{\"request_id\":%ld,\"type\":\"current_weather\",\"lat\":%.6f,\"lon\":%.6f}",
        m_request_id, m_current_lat, m_current_lon);

    // Send request
    SendPluginMessage("WEATHER_DATA_REQUEST", request);
}

// Handle response
void NavigationPlugin::SetPluginMessage(wxString &message_id, wxString &message_body) {
    if (message_id == "WEATHER_DATA_RESPONSE") {
        // Parse response to get request_id
        wxJSONValue root;
        wxJSONReader reader;

        int errors = reader.Parse(message_body, &root);
        if (errors > 0) return;

        // Check if this is our response
        if (root.HasMember("request_id") &&
            root["request_id"].AsLong() == m_request_id) {

            // Process weather data
            ProcessWeatherResponse(root);
        }
    }
}

Responder Plugin:

// Handle request and send response
void WeatherPlugin::SetPluginMessage(wxString &message_id, wxString &message_body) {
    if (message_id == "WEATHER_DATA_REQUEST") {
        // Parse request
        wxJSONValue request_root;
        wxJSONReader reader;

        int errors = reader.Parse(message_body, &request_root);
        if (errors > 0) return;

        // Extract request parameters
        if (request_root.HasMember("request_id") &&
            request_root.HasMember("type") &&
            request_root.HasMember("lat") &&
            request_root.HasMember("lon")) {

            long request_id = request_root["request_id"].AsLong();
            wxString type = request_root["type"].AsString();
            double lat = request_root["lat"].AsDouble();
            double lon = request_root["lon"].AsDouble();

            // Generate weather data for the requested location
            wxString weather_data = GenerateWeatherData(type, lat, lon);

            // Create response
            wxJSONValue response_root;
            response_root["request_id"] = request_id;
            response_root["type"] = type;
            response_root["data"] = weather_data;

            // Serialize to string
            wxJSONWriter writer;
            wxString response;
            writer.Write(response_root, response);

            // Send response
            SendPluginMessage("WEATHER_DATA_RESPONSE", response);
        }
    }
}

Broadcast Pattern

In this pattern, a plugin broadcasts information to all interested plugins without expecting a response:

// Broadcast vessel position
void PositionPlugin::BroadcastPosition() {
    // Create position message
    wxString position = wxString::Format(
        "lat=%.6f;lon=%.6f;cog=%.1f;sog=%.1f;timestamp=%ld",
        m_current_lat, m_current_lon, m_current_cog, m_current_sog,
        wxDateTime::Now().GetTicks());

    // Broadcast to all plugins
    SendPluginMessage("VESSEL_POSITION_BROADCAST", position);
}

Plugin API Extension Pattern

In this pattern, a plugin exposes a rich API through the messaging system, allowing other plugins to interact with its features:

// Plugin exposing API functions
void RoutingPlugin::SetPluginMessage(wxString &message_id, wxString &message_body) {
    if (message_id == "ROUTING_API") {
        // Parse API request
        wxJSONValue request;
        wxJSONReader reader;

        int errors = reader.Parse(message_body, &request);
        if (errors > 0) return;

        // Process API command
        if (request.HasMember("command")) {
            wxString command = request["command"].AsString();

            if (command == "calculate_route") {
                // Extract parameters
                double start_lat = request["start_lat"].AsDouble();
                double start_lon = request["start_lon"].AsDouble();
                double end_lat = request["end_lat"].AsDouble();
                double end_lon = request["end_lon"].AsDouble();

                // Calculate route
                RouteResult result = CalculateRoute(start_lat, start_lon, end_lat, end_lon);

                // Build response
                wxJSONValue response;
                response["success"] = result.success;
                response["message"] = result.message;

                if (result.success) {
                    // Add route points
                    wxJSONValue points;
                    for (size_t i = 0; i < result.points.size(); i++) {
                        wxJSONValue point;
                        point["lat"] = result.points[i].lat;
                        point["lon"] = result.points[i].lon;
                        points.Append(point);
                    }
                    response["points"] = points;
                    response["distance"] = result.total_distance;
                    response["time"] = result.estimated_time;
                }

                // Serialize and send response
                wxJSONWriter writer;
                wxString response_str;
                writer.Write(response, response_str);

                SendPluginMessage("ROUTING_API_RESPONSE", response_str);
            }
            // Other API commands...
        }
    }
}

Plugin Discovery

In some cases, plugins need to discover what other plugins are available and what capabilities they support. This can be done through a discovery protocol:

Plugin Advertising

When a plugin starts, it can advertise its presence and capabilities:

void MyPlugin::Init() {
    // ... other initialization

    // Advertise plugin presence and capabilities
    wxJSONValue capabilities;
    capabilities["name")] = _T("MyPlugin";
    capabilities["version")] = _T("1.2.3";
    capabilities["api_version")] = _T("1.0";

    // List supported features
    wxJSONValue features;
    features.Append("weather_data");
    features.Append("routing");
    capabilities["features"] = features;

    // List supported message types
    wxJSONValue messages;
    messages.Append("WEATHER_DATA_REQUEST");
    messages.Append("WEATHER_FORECAST_V1");
    capabilities["messages"] = messages;

    // Serialize to string
    wxJSONWriter writer;
    wxString advert;
    writer.Write(capabilities, advert);

    // Broadcast capabilities
    SendPluginMessage("PLUGIN_ADVERTISE", advert);
}

Plugin Discovery

Other plugins can listen for these advertisements:

void MyOtherPlugin::SetPluginMessage(wxString &message_id, wxString &message_body) {
    if (message_id == "PLUGIN_ADVERTISE") {
        // Parse advertisement
        wxJSONValue capabilities;
        wxJSONReader reader;

        int errors = reader.Parse(message_body, &capabilities);
        if (errors > 0) return;

        // Check if this plugin has features we need
        if (capabilities.HasMember("features")) {
            bool has_weather = false;
            wxJSONValue features = capabilities["features"];

            for (int i = 0; i < features.Size(); i++) {
                if (features[i].AsString() == "weather_data") {
                    has_weather = true;
                    break;
                }
            }

            if (has_weather) {
                // Found a plugin that provides weather data
                m_weather_plugin_name = capabilities["name"].AsString();
                m_weather_plugin_found = true;

                // Now we know we can use WEATHER_DATA_REQUEST messages
            }
        }
    }
}

REST API Integration

From API version 1.19, the plugin messaging system also integrates with OpenCPN’s REST interface. This means:

Messages from external applications via REST can be received by plugins
Plugins can send messages that will be forwarded to REST clients

This enables integration with web applications, mobile apps, and other external systems.

Receiving REST Messages

REST messages appear as normal plugin messages with special message IDs:

void MyPlugin::SetPluginMessage(wxString &message_id, wxString &message_body) {
    // Check if this is a REST message
    if (message_id.StartsWith("REST.")) {
        // Extract the REST endpoint from the message ID
        wxString endpoint = message_id.Mid(5);  // Skip "REST."

        // Process REST request
        if (endpoint == "myplugin/data") {
            // Handle data request
            ProcessRestDataRequest(message_body);
        }
        else if (endpoint == "myplugin/command") {
            // Handle command
            ProcessRestCommand(message_body);
        }
    }
}

Responding to REST Messages

To send a response back to a REST client, use a corresponding response message ID:

void MyPlugin::ProcessRestDataRequest(const wxString &request_body) {
    // Create response data
    wxJSONValue response;
    response["status")] = _T("ok";
    response["data"] = CreateDataResponse();

    // Serialize to string
    wxJSONWriter writer;
    wxString response_str;
    writer.Write(response, response_str);

    // Send response back to REST client
    SendPluginMessage("REST.myplugin/data", response_str);
}

Best Practices

Performance Considerations

Message Size: Keep messages small when possible
Message Frequency: Avoid sending messages too frequently
Processing Time: Keep message processing fast to avoid delays
Batching: Batch updates when multiple changes occur in quick succession

Error Handling

Validate Input: Always validate incoming message data
Error Responses: Use clear error responses for invalid requests
Timeouts: Implement timeouts for request-response patterns
Versioning: Include version information in messages for compatibility

Message Design

Clear IDs: Use descriptive, namespaced message IDs
Structured Data: Use JSON or XML for complex data
Minimal Data: Only include necessary information
Documentation: Document your message formats for other developers

Security Considerations

Validation: Always validate message data before using it
Sensitive Data: Be careful with sensitive information in messages
Permissions: Consider implementing permission checks for critical operations
Rate Limiting: Protect against message flooding