Wednesday, August 2, 2017

Simulate Instrument Data with OpenCPN's NMEA Converter Plugin

Our main goal was to investigate how various navigation programs treat the effect of leeway on true wind angle (TWA) referenced to the boat's track through the water. This is a subtle computation that not many ECS perform. OpenCPN's Tactics plugin does a correction for this, as do premier racing programs like Expedition. This correction can be a notable influence on a proper comparison of sailing performance with polar diagrams as well as on accurate optimum routing. We come back to this topic in another post; for now we just show one way to simulate the instrument signals, which is easy to reproduce for individual study.

There are other ways to do this. Our own enav simulator generates the proper NMEA sentences within any user selected ground wind and current, for example, and there are programs that will play back a list of NMEA sentences, but treating the checksums properly can be an issue in some navigation programs when using a list. Once you have a source of the sentences you want, you can apply them to any program for testing and learning how they make specific corrections.

The method described here uses the OpenCPN plugin called NMEA Converter. This plugin was not intended for this application, but with a couple extra steps it does it nicely. It was actually designed to read in one sentence and then create another one by redefining the fields in it. The topic of this post is how to use that plugin for an extension of that idea to create the needed sentences to test TWA computations. 

Although leeway can in principle be measured, it remains an elusive number. The typical solution is to approximate the leeway from the measured Heel angle, which can be measured accurately. Leeway = K*Heel/BSP^2, where K is a constant between 9 and 13, depending on the boat. (BSP = boat speed, STW in OpenCPN). With this approximation (using K=12.4), a vessel moving at 5.7 kts, with a heel of 23º will slip downwind by 8.8º. Then we can ask our navigation program to take this into account when figuring True wind, relative to the centerline of the boat, and Ground Wind, relative to the fixed earth. The latter is what we care about for weather work, in which case it is called the "true wind," but performance sailors have used the term "true wind" for many decades as being relative to the water, and it not worth arguing the terminology.

(Looking ahead, however, the main issue is not just correcting for the boat track vs boat heading, but rather correcting the measured apparent wind angle (AWA) and apparent wind speed (AWS) reported by the instruments for the effect of the heel of instruments relative to vertical. In other words, if you have your boat side tied to the end of the dock and read AWS and AWA, and then use a halyard to pull the boat over 20º or so, how much does AWA and AWS change. There are geometrical computations of this effect, which can be applied within the wind instruments themselves (high end instruments) or by the navigation program itself for more common instruments that do not make this correction.)


Step (1). Install the PC version of the NMEA Converter plugin to OpenCPN. This works in the same way as all of their plugins—it seems there is not a Mac version. The operation of the plugin, however, is a bit special, as there is no on-screen icon as with other plugins. 

Step (2). From the plugin link in the settings (wrench icon), first enable the NMEA Converter (button far right, sometimes hidden by horizontal scroll), then under preferences, choose New, and type in the sentence you want to export. 

Step (3). In this case we put the heel (called roll) in an XDR sentence, used for general sensor input. The official sentence for heel-roll is HRM, which allows for peak values, period, and other specs, but not many programs read this one, so the XDR is safer.  It is defined as: 

$--XDR,A,x.x,D,c—c, ..... *hh

The first two letters after the $ do not matter. We use the recommended II for Integrated Instrumentation. 

A means the following value is an angle
+x.x roll to right (port tack)
-x.x roll to left (starboard tack) 
D means angle is in degrees
C-C is sensor name, Roll. 
*hh is the check sum.

Thus we have this sentence for heel:  $IIXDR,A,23.0,D,ROLL*49

This includes the correct checksum, but we do not need to know that for the simulation. The plugin will add the correct one when we change the heel value. If needed, here is a place to check the checksum.

We can leave the top box unchecked as we are not importing data. Choose send every second, which is fine for testing. In practice heel is transmitted at a higher rate than that. Heel changes at each wave.

The sentence you want to transmit is typed over the $dummy format line, as indicated without a checksum, then press OK. Note the needed OK and Cancel buttons are typically hidden from view, so you have to manually expand that window with the tab marked by red circle in the picture above. 

We can check that the sentence has been accepted two ways. First, heel will show up in the OpenCPN Tactics dashboard, or we can use the Show NMEA Debug Window in the Connections link in Setup, as shown below. (Leeway will not show up till we have other data coming in.)

Since you might be using the Show NMEA Debug Window from the Connections page a lot in this exercise, note that it requires an uncheck and then check again after you close it, and it typically comes up behind the connections page, but can then be moved—we have to learn how our friends behave and adapt to them for a happy life.

Figure 2

Notice that our artificial sentence is there and it is green, meaning accepted, but we need to turn it blue, meaning it is being sent out so we can use it in other programs. 

In short, we are next going beyond just using this in OpenCPN, that is already working, but we want to test other programs as well. In short we are using OpenCPN as a tool to generate the signals for other applications. 

Step. (4) To do this, we need to set up a network to export the sentence. From Setup wrench, choose Connections to get the screen below.

Figure 3.

Add a new network connection. In this one we use the localhost; the port number does not matter; we used 44444. Choose UDP, and in the bottom line type XDR, and then apply, and check the NMEA Debug Window again and you should see the following.

In the Transmit sentences, click ... on the right, and find or add as needed XDR. Then apply and check the Debug window.

Figure 4.

The sentences are blue, meaning they are being exported to the localhost. 

To import these to Expedition, for example, we set up a new network there for this input. This usually calls for adding a new network, then configuring it as seen below.

Figure 5

Again, two ways to check this. The heel should show up in a number box, and when we set up the Exp Calculations the leeway will show as well. We can also check the Raw Data view shown above as an insert, which is perfectly uninteresting, as hoped.

So far so good. But to make this more general and not have be on the water or using a full simulator, we can go back to the NMEA Converter and generate all the sentences we need. Note, too, that if you are running the Tactics plug in while underway you do not need this operation, because it lets you input heel values manually based on TWS and TWA. (I will add another note on that useful plugin later on.)  Still, however, if you want to make static tests of any program to see how they treat TWA corrections, we need to generate all required sentences so we can vary them and watch the response.

Here are the minimum sentences we need:



The top line gives a time and position (we don't care about) then SOG, COG, and a date we don't care about. Next we have a HDG of 40.0 True, and a BSP of 5.7. We can do all this study later in the presence of current, but for now we consider no current and just leeway, which is (in an idealized setting) SOG = BSP and COG = HDG ± leeway. 

The above sentences will generate apparent wind angle (AWA) of 29.3º on the Right side of the boat, with an apparent wind speed (AWS) of 15.6 kts. The other numbers are just different speed units. And finally we have the heel described above.

These are shown without the checksums, because the plugin will generate them for us, which is very handy once we start changing the values—final sentences will end with *hh, the checksum.

So back to NMEA Converter. As far as I can tell, this plugin only lets us generate two sentences. You can keep adding them, but it only accepts the last two you put in. We have to go into the back door (opencpn.ini) and ask this plugin to do more. It is very nicely programmed so we can do that. I am not sure if the up-front limit was intentional, or a bug, or maybe I am not doing it properly. Someone will let us know, and then this can be rewritten. The primary intention of the plugin does not need more than two, so this is no surprise.

In any event, once we have successfully added and exported one sentence, it is easy to add more, which in turn gives an easy way to change all the variables.  

Step (5). Close OpenCPN, then find the ini file at C:\ProgramData\opencpn\opencpn.ini.  Then duplicate the file, just in case, so you have a back up. Open it in Notepad and scroll down to the NMEAConverter section, as seen below, starting with the blue lines.


The first red 4 will be 2 (change to 4) and you will see below that just the two that you tried. Then duplicate and insert the two object entries (red) and name them 3 and 4, and insert the four sentences we need as shown.  Then save and close the ini file. Then open OpenCPN and these sentences will all show up as well as being exported to any other program you have set up to receive UDP network connections.

In Win 10, once you have accessed a file, it stays in a recent list, so it is easy to go back and change the variables. If you want an AWA of 33.0 just change the 29.3 to 33.0 and save. Instantly all the running programs will show a new AWA and resulting TWA computations.

Below is the input to OpenCPN using these data alone. If the new ones are not blue, go  back to the Connections pages and add these sentences to be transmitted: RMC,XDR,VWR,VHW

Important note: This input will stay in place and come back after closing and opening OpenCPN. So if you want to shut it off, disable the plugin, and then close and reopen OpenCPN. If you enable the plugin again, the signals come back. However... is seems when doing this that Tactics does not compute TW when we reinitialize the NMEA Converter. Close OpenCPN, then re-open, and all works fine. Recall we are using this for purposes well outside any intention, so not to be surprised by special behavior we have to work around. 

The image below shows how these data import to Expedition, or any other echart program that accepts network connections.

Remember when using other programs, you must keep OpenCPN running, as it is the workhorse generating all the simulated signals.

Now we are ready to start testing various features of the wind displays in Tactics plugin and other programs. There are many interesting things to learn with this simulation in place, not just in OpenCPN but in other programs as well.  More on that in a forthcoming post.

I will add a video illustration of the above procedure as soon as possible.

1 comment:

Maddox said...

Great post - thanks for documenting how to do this so thoroughly.