Implement various non-gui ocpn_plugin.h methods. More...

#include <memory>
#include <sstream>
#include <vector>
#include <wx/event.h>
#include <wx/fileconf.h>
#include <wx/jsonval.h>
#include <wx/jsonreader.h>
#include <wx/tokenzr.h>
#include "model/base_platform.h"
#include "model/comm_appmsg.h"
#include "model/comm_drv_loopback.h"
#include "model/comm_drv_n0183_net.h"
#include "model/comm_drv_n0183_serial.h"
#include "model/comm_drv_n2k.h"
#include "model/comm_drv_registry.h"
#include "model/comm_navmsg_bus.h"
#include "model/notification_manager.h"
#include "ocpn_plugin.h"
#include "model/comm_drv_factory.h"
#include "model/comm_drv_n2k_net.h"
#include "model/comm_drv_n2k_serial.h"

Functions
vector< uint8_t >	GetN2000Payload (NMEA2000Id id, ObservedEvt ev)
	Return N2K payload for a received n2000 message of type id in ev.

std::string	GetN2000Source (NMEA2000Id id, ObservedEvt ev)
	Return source identifier (iface) of a received n2000 message of type id in ev.

std::string	GetN0183Payload (NMEA0183Id id, ObservedEvt ev)
	Return payload in a received n0183 message of type id in ev.

std::string	GetPluginMsgPayload (PluginMsgId id, ObservedEvt ev)
	Retrieve the string in a plugin message, internal or received on the REST insterface.

std::shared_ptr< void >	GetSignalkPayload (ObservedEvt ev)
	Get SignalK status payload after receiving a message.

std::shared_ptr< PI_Notification >	GetNotificationMsgPayload (NotificationMsgId id, ObservedEvt ev)
	Retrieve the Notification Event in a Notification message.

shared_ptr< ObservableListener >	GetListener (NMEA2000Id id, wxEventType et, wxEvtHandler *eh)
	Gets listener for NMEA 2000 messages.

std::shared_ptr< ObservableListener >	GetListener (NMEA0183Id id, wxEventType et, wxEvtHandler *eh)
	Gets listener for NMEA 0183 messages.

shared_ptr< ObservableListener >	GetListener (SignalkId id, wxEventType et, wxEvtHandler *eh)
	Gets listener for Signal K updates.

shared_ptr< ObservableListener >	GetListener (NavDataId id, wxEventType et, wxEvtHandler *eh)
	Gets listener for navigation data updates.

std::shared_ptr< ObservableListener >	GetListener (PluginMsgId id, wxEventType et, wxEvtHandler *eh)
	Return listener for plugin messages, internal or received on the REST interface.

std::shared_ptr< ObservableListener >	GetListener (NotificationMsgId id, wxEventType et, wxEvtHandler *eh)
	Return listener for Notification Framework messages interface.

PluginNavdata	GetEventNavdata (ObservedEvt ev)
	Return BasicNavDataMsg decoded data available in ev.

std::vector< DriverHandle >	GetActiveDrivers ()
	Comm port plugin TX support methods

const std::unordered_map< std::string, std::string >	GetAttributes (DriverHandle handle)
	Query a specific driver for attributes.

CommDriverResult	WriteCommDriver (DriverHandle handle, const std::shared_ptr< std::vector< uint8_t > > &payload)
	Send a non-NMEA2000 message.

CommDriverResult	WriteCommDriverN2K (DriverHandle handle, int PGN, int destinationCANAddress, int priority, const std::shared_ptr< std::vector< uint8_t > > &payload)
	Send a PGN message to an NMEA2000 address.

CommDriverResult	RegisterTXPGNs (DriverHandle handle, std::vector< int > &pgn_list)
	Register PGNs that this application intends to transmit for some NMEA 2000 adapters like Actisense NGT-1.

wxString *	GetpPrivateApplicationDataLocation ()
	Gets private application data directory.

void	ReloadConfigConnections ()

int	GetActiveNotificationCount ()

PI_NotificationSeverity	GetMaxActiveNotificationLevel ()

std::string	RaiseNotification (const PI_NotificationSeverity _severity, const std::string &_message, int timeout_secs)

bool	AcknowledgeNotification (const std::string &guid)

std::vector< std::shared_ptr< PI_Notification > >	GetActiveNotifications ()

PI_Comm_Status	GetConnState (const std::string &iface, PI_Conn_Bus _bus)
	Plugin polled Comm Status support.

Detailed Description

Implement various non-gui ocpn_plugin.h methods.

Definition in file plugin_api.cpp.

Function Documentation

◆ AcknowledgeNotification()

bool AcknowledgeNotification ( const std::string & guid )

Definition at line 360 of file plugin_api.cpp.

◆ GetActiveDrivers()

std::vector< DriverHandle > GetActiveDrivers ( )

Comm port plugin TX support methods

Query OCPN core for a list of active drivers

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 154 of file plugin_api.cpp.

◆ GetActiveNotificationCount()

int GetActiveNotificationCount ( )

Definition at line 339 of file plugin_api.cpp.

◆ GetActiveNotifications()

std::vector< std::shared_ptr< PI_Notification > > GetActiveNotifications ( )

Definition at line 365 of file plugin_api.cpp.

◆ GetAttributes()

const std::unordered_map< std::string, std::string > GetAttributes ( DriverHandle handle )

Query a specific driver for attributes.

Driver attributes are available from OCPN core as a hash map of tag->attribute pairs. There is a defined set of common tags guaranteed for every driver. Both tags and attributes are defined as std::string. Here is the list of common tag-attribute pairs.

Tag Attribute definition

"protocol" Comm bus device protocol, such as "NMEA0183", "NMEA2000"

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 165 of file plugin_api.cpp.

◆ GetConnState()

PI_Comm_Status GetConnState	(	const std::string &	iface,
		PI_Conn_Bus	_bus
	)

Plugin polled Comm Status support.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 381 of file plugin_api.cpp.

◆ GetEventNavdata()

PluginNavdata GetEventNavdata ( ObservedEvt ev )

Return BasicNavDataMsg decoded data available in ev.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 138 of file plugin_api.cpp.

◆ GetListener() [1/6]

shared_ptr< ObservableListener > GetListener	(	NavDataId	id,
		wxEventType	ev,
		wxEvtHandler *	handler
	)

Gets listener for navigation data updates.

Creates a listener to receive basic navigation data updates including position, course, speed etc.

Parameters

id	NavDataId identifying message type to listen for
ev	Event type to generate on updates
handler	Event handler to receive updates

Returns: Shared pointer to listener object

Definition at line 122 of file plugin_api.cpp.

◆ GetListener() [2/6]

std::shared_ptr< ObservableListener > GetListener	(	NMEA0183Id	id,
		wxEventType	ev,
		wxEvtHandler *	handler
	)

Gets listener for NMEA 0183 messages.

Creates a listener to receive NMEA 0183 messages of a specific type.

Parameters

id	Sentence identifier to listen for
ev	Event type to generate on message receipt
handler	Event handler to receive messages

Returns: Shared pointer to listener object

Definition at line 112 of file plugin_api.cpp.

◆ GetListener() [3/6]

shared_ptr< ObservableListener > GetListener	(	NMEA2000Id	id,
		wxEventType	ev,
		wxEvtHandler *	handler
	)

Gets listener for NMEA 2000 messages.

Creates a listener to receive NMEA 2000 messages of a specific type.

Parameters

id	PGN identifier for message type to listen for
ev	Event type to generate on message receipt
handler	Event handler to receive messages

Returns: Shared pointer to listener object

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 107 of file plugin_api.cpp.

◆ GetListener() [4/6]

std::shared_ptr< ObservableListener > GetListener	(	NotificationMsgId	id,
		wxEventType	et,
		wxEvtHandler *	eh
	)

Return listener for Notification Framework messages interface.

Definition at line 132 of file plugin_api.cpp.

◆ GetListener() [5/6]

std::shared_ptr< ObservableListener > GetListener	(	PluginMsgId	id,
		wxEventType	et,
		wxEvtHandler *	eh
	)

Return listener for plugin messages, internal or received on the REST interface.

Definition at line 127 of file plugin_api.cpp.

◆ GetListener() [6/6]

shared_ptr< ObservableListener > GetListener	(	SignalkId	id,
		wxEventType	ev,
		wxEvtHandler *	handler
	)

Gets listener for Signal K updates.

Creates a listener to receive Signal K updates for a specific path.

Parameters

id	Signal K path to listen for
ev	Event type to generate on updates
handler	Event handler to receive updates

Returns: Shared pointer to listener object

Definition at line 117 of file plugin_api.cpp.

◆ GetMaxActiveNotificationLevel()

PI_NotificationSeverity GetMaxActiveNotificationLevel ( )

Definition at line 344 of file plugin_api.cpp.

◆ GetN0183Payload()

std::string GetN0183Payload	(	NMEA0183Id	id,
		ObservedEvt	ev
	)

Return payload in a received n0183 message of type id in ev.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 61 of file plugin_api.cpp.

◆ GetN2000Payload()

vector< uint8_t > GetN2000Payload	(	NMEA2000Id	id,
		ObservedEvt	ev
	)

Return N2K payload for a received n2000 message of type id in ev.

The vector returned is described in the following example

 [147,19,                     // Header bytes, unused
  3,                          // N2K priority
  16,240,1,                   // example pgn 126992 encoded little endian
  255,                        // N2K destination address
  1,                          // N2K origin address
  255,255,255,255,            // timestamp, unused
  8,                          // count of following NMEA2000 data
  13,240,207,76,208,3,94,40,  // NMEA2000 data
  85                          // CRC byte, unused,not included in count
 ];

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 51 of file plugin_api.cpp.

◆ GetN2000Source()

std::string GetN2000Source	(	NMEA2000Id	id,
		ObservedEvt	ev
	)

Return source identifier (iface) of a received n2000 message of type id in ev.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 56 of file plugin_api.cpp.

◆ GetNotificationMsgPayload()

std::shared_ptr< PI_Notification > GetNotificationMsgPayload	(	NotificationMsgId	id,
		ObservedEvt	ev
	)

Retrieve the Notification Event in a Notification message.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 96 of file plugin_api.cpp.

◆ GetPluginMsgPayload()

std::string GetPluginMsgPayload	(	PluginMsgId	id,
		ObservedEvt	ev
	)

Retrieve the string in a plugin message, internal or received on the REST insterface.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 66 of file plugin_api.cpp.

◆ GetpPrivateApplicationDataLocation()

wxString * GetpPrivateApplicationDataLocation ( )

Gets private application data directory.

Returns path to OpenCPN's private data directory for storing settings.

Returns: Pointer to wxString containing data path

Note: Do not delete the returned pointer; Path includes trailing separator

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 288 of file plugin_api.cpp.

◆ GetSignalkPayload()

std::shared_ptr< void > GetSignalkPayload ( ObservedEvt ev )

Get SignalK status payload after receiving a message.

Returns

pointer to a wxJSONValue map object. Typical usage:

auto ptr = GetSignalkPayload(ev);
const auto msg = *std::static_pointer_cast<const wxJSONValue>(payload);

The map contains the following entries:

"Data": the parsed json message
"ErrorCount": int, the number of parsing errors
"WarningCount": int, the number of parsing warnings
"Errors": list of strings, error messages.
"Warnings": list of strings, warning messages..
"Context": string, message context
"ContextSelf": string, own ship context.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 71 of file plugin_api.cpp.

◆ RaiseNotification()

std::string RaiseNotification	(	const PI_NotificationSeverity	_severity,
		const std::string &	_message,
		int	timeout_secs
	)

Definition at line 352 of file plugin_api.cpp.

◆ RegisterTXPGNs()

CommDriverResult RegisterTXPGNs	(	DriverHandle	handle,
		std::vector< int > &	pgn_list
	)

Register PGNs that this application intends to transmit for some NMEA 2000 adapters like Actisense NGT-1.

This function is required specifically for NMEA 2000 adapters like the Actisense NGT-1. For these devices, registration of transmit PGNs is required before sending any messages. This is an adapter-specific requirement, not a requirement of the NMEA 2000 standard itself.

This function is only implemented for serial NMEA 2000 adapters (specifically the Actisense NGT-1). For other connection types (TCP, UDP), the function will return success and perform no registration.

Parameters

handle	The driver handle obtained from GetActiveDrivers()
pgn_list	List of PGNs this application will transmit

Returns: RESULT_COMM_NO_ERROR if registration successful RESULT_COMM_INVALID_PARMS if pgn_list is empty RESULT_COMM_INVALID_HANDLE if handle is invalid RESULT_COMM_REGISTER_PGN_ERROR if PGN registration failed

Example usage:

// Register to transmit wind data and rudder commands
std::vector<int> pgns = {130306,  // Wind Data
                        127245};  // Rudder
auto result = RegisterTXPGNs(driver_handle, pgns);
if (result != RESULT_COMM_NO_ERROR) {
    // Handle error
}

Note

For Actisense NGT-1 adapters, this registration must be done before transmitting any NMEA 2000 messages. The registration remains in effect until the application closes or explicitly registers a new list. Before any device can transmit messages on an NMEA 2000 network, it must first announce which message types (PGNs) it will transmit. This allows other devices on the network to:

Know what data is available.
Request specific data from the transmitting device.
Properly handle network address claims.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 255 of file plugin_api.cpp.

◆ ReloadConfigConnections()

void ReloadConfigConnections ( )

Definition at line 292 of file plugin_api.cpp.

◆ WriteCommDriver()

CommDriverResult WriteCommDriver	(	DriverHandle	handle,
		const std::shared_ptr< std::vector< uint8_t > > &	payload
	)

Send a non-NMEA2000 message.

The call is not blocking.

Parameters

handle Obtained from GetActiveDrivers()

payload

Message data, for example a complete Nmea0183 message.
From 1.19: if the handle "protocol" attribute is "internal" it is parsed as <id><space><message> where the id is used when listening/ subscribing to message.
From 5.12.4: if handle "protocol" attribute is "loopback" it is parsed as one of

"signalk" <source> <context_self> <json payload>
"nmea0183" <source> <0183id> <n0183 sentence>
"nmea2000" <source> <PGN> <hex encoded 2000 payload>

<source> is the interface which is tagged as receiving interface. must not contain spaces
<hex encoded payload> is bytes separated by space e.g. "0f ff 8 3e"

Returns: value number of bytes queued for transmission.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 179 of file plugin_api.cpp.

◆ WriteCommDriverN2K()

CommDriverResult WriteCommDriverN2K	(	DriverHandle	handle,
		int	PGN,
		int	destinationCANAddress,
		int	priority,
		const std::shared_ptr< std::vector< uint8_t > > &	payload
	)

Send a PGN message to an NMEA2000 address.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 230 of file plugin_api.cpp.

Functions

Detailed Description

Function Documentation

◆ AcknowledgeNotification()

◆ GetActiveDrivers()

◆ GetActiveNotificationCount()

◆ GetActiveNotifications()

◆ GetAttributes()

◆ GetConnState()

◆ GetEventNavdata()

◆ GetListener() [1/6]

◆ GetListener() [2/6]

◆ GetListener() [3/6]

◆ GetListener() [4/6]

◆ GetListener() [5/6]

◆ GetListener() [6/6]

◆ GetMaxActiveNotificationLevel()

◆ GetN0183Payload()

◆ GetN2000Payload()

◆ GetN2000Source()

◆ GetNotificationMsgPayload()

◆ GetPluginMsgPayload()

◆ GetpPrivateApplicationDataLocation()

◆ GetSignalkPayload()

◆ RaiseNotification()

◆ RegisterTXPGNs()

◆ ReloadConfigConnections()

◆ WriteCommDriver()

◆ WriteCommDriverN2K()