Handling Communications Messages in Plugins

Since 5.8.0 opencpn has a new system for handling messages in plugins.

The new model is based on that a plugin subscribes to the messages it is interested in rather than the old model where plugins get all messages.

The new system is the only way to handle the new NMEA2000 devices. For N0183 devices a compatiblity layer is installed which makes things work as earlier. However, the new system can be used also for nmea0183 where it offers more flexibility and performance.

Handling of messages consists of six steps:

1. Define the type of message to work with
2. Declare a listening object.
3. Declare an event which will carry the message.
4. Declare a method which handles the message.
5. Subscribe to this message i. e., start listening to it
6. Handle the messages as they arrives.

All in all, an example could be like this:

First, declare a listener on the class level, here with the shipdriver plugin ShipDriver_pi.h header as an example:

    class ShipDriver_pi : public opencpn_plugin_118 {
    public:
        ShipDriver_pi(void* ppimgr);
        ~ShipDriver_pi(void);
        ...
    private:
 ②      std::shared_ptr<ObservableListener> listener;
        ...

Then declare a method which handles the message, something like this:

 ④ void HandleGPGA(ObservedEvt ev) {
 ①      NMEA0183 id("GPGGA");
        std::string payload = GetN0183Payload(id, ev)
        ...

Then, in the constructor set up the listening:

     ShipDriver_pi::ShipDriver_pi(void* ppimgr)
     : opencpn_plugin_116(ppimgr)
     {
     ...
 ①   NMEA0183Id id("GPGGA");
 ③   wxDEFINE_EVENT(EVT_SHIPDRIVER, ObservedEvt);
 ⑤   listener.Listen(id.key(), EVT_SHIPDRIVER, this);
 ⑥   Bind(EVT_SHIPDRIVER [](ObservedEvt ev) { HandleGPGA(ev); });

Notes:

① This is the type of message we are listening to. There are similar types Nmea2000Msg, Nmea0183Msg, SignalkMsg and AppMsg for NMEA0183, NMEA2000, SignalK and decoded navigation data (lat, long, etc.)

② Boiler-plate code, makes sure the listener is destroyed together with the plugin. It is important that the listener is declared in the class, a variable defined in a method will not work.

③ This is the event generated for our message which we will listen to. It should have an unique name, including the plugin name is a good habit. However the name, here EVT_SHIPDRIVER, could be anything.

④ The GetN0183Payload() method gets the payload of the message into the payload string. From here it can be processed as required.

⑤ This activates the listener. From this point system sends us an EVT_SHIPDRIVER for each received GPGGA message.

⑥ This is the final piece in the puzzle. It defines what should happen when the EVT_SHIPDRIVER arrives. From this point all incoming GPGGA messages will land in the HandleGPGGA() method and be processed.

Epilog: Using the lambda

The last step above was Bind(EVT_SHIPDRIVER [](wxCommandEvent ev) { HandleGPGA(ev); }). The part between the curly braces is actually a C++ lambda expression. There is no need to dive into this to get something running, but it offers far larger possibilities than to just call a function. Actually, if written like Bind(EVT_SHIPDRIVER, [&](wxCommandEvent ev) { ... }) any code could be written between the braces.

The interesting part here is that the [&] prefix makes this code "see" anything defined in the plugin. This is a convenient way to access plugin variables in the handler, something which otherwise is a problem.

To get the feeling one need to experiment. But then again, C++ lambdas is a complex step which is not necessary to get something running.