USER MANUAL BASIC

[rgleason]

This is for discussion about the Opencpn User Manual Basic DocuWiki

Please see Editor 2024 Status & Progress Page Which will be kept current. Updated 5/22/2024

Please this Editing Left to Do List

We have many pages in Toobar > Manage Routes, and Chart Panel that need work. We need to focus on getting these pages done.

Nine User Volunteers (Now 10), will be updating all of TOOLBAR and CHART PANEL
Starting with the screenshots and checking and editing DOWN the text. Lets hope this goes well as they are all new volunteer Editors, but seem to be capable.

User Manual - Documentation needed #2967

[leamas]

Here is a screenshot from Linux/Flatpak when finding a dongle which cannot be accessed and thus requires a udev rule. It's not that hard.

[leamas]

You might note that the beginning of the page states that there is interactive support for this since 5.6.0. Maybe we should put some more emphasis on this and move the whole page to a a troubleshooting section.

[Hakansv]

About this Connections-AutoPilots
I would have expected a simple description how to setup a NME0183 baude rate 4800 serial output to be connected to a common auto pilot.
The section above "Raymarine EV1..." is obviously about something special. I can't say I understand what it describes. Anyone else?
If we agree that the first section is not relevant I could change it to describe a basic serial N0183 output connection with a appropriate filter to not choke the 4800 baude rate and still send appropriate auto pilot sentences.
Thoughts?

[rgleason]

@Hakansv The url has changed to https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections:autopilot
How does it look now?

[Hakansv]

The NMEA0183 part is fine. I made a minor edit adding RMC to the list of messages generated by OCPN "update autopilot" function.
N2k AP I've not used so others may check that.

[Hakansv]

The ECRMB, ECRMC, ECAPB are very important to list in the sentence selection window. These are the ones to use for an AP. They are produced from the activated track in routeman.cpp. The e.g. xxRMB from a GNSS receiver is not what we want.
The RMB, APB without talker may be interesting for other purposes so I think they also fit in the list. The XTE can be there without talker. The only one normally producing TXT is routeman.cpp. But since ECTXT is also produced it may be in the list for consistency reasons? It's though easily added by the user. We can't list all possible sentences, can we? The "Add" function is there for enlargements.

Issue 3801: It can be the control to change from "EC" to something else for the AP-sentences may not work. I'll check as well. I can see it's not reflected in routeman but I thought the muiltiplexer would take care of that. Likely seldom used since no complains have been seen?

[TwoCanPlugIn]

I just find it confusing.

1. Changing the talker ID doesn't work. It's not persisted and it doesn't work. It shouldn't be hardcoded in case a user has an autopilot that doesn't support/recognize the EC talker id.
2. It's confusing to have both ECRMB, ECAPB and APB and RMB filters. The only way for there to be both ECRMB and RMB sentences present is if OpenCPN has a route activated and there is either another chartplotter (with a route activated) also sending RMB, APB & XTE sentences or a plugin generating and pushing navigation sentences.

Likely seldom used since no complains have been seen

Quite possibly, but there are far too many features that have been implemented that do not work. Changing AIS sounds was a good example.

[Hakansv]

1. Could be. I haven't checked yet. I don't remember why it was implemented. Certainly some need for specific APs. Like Furuno? The "EC" talker need to be there to serve these that don't wont to read to much and use a common filter. If any AP really read the talker we may need to be able to change it. But I think most don't use the talker.

2. Don't understand. You select to use the sentence you need for the filter. I agree a filter including both ECRMB and RMB is to overdo it. In that case it's enough if you use only RMB. But we never know what a user may need. There will nearly never be "to much" choices. But the "Add" functions solves the rest.

I think the AIS sound trouble was introduced when the "Sounds" handling was implemented in the "User" tab. Some years ago now. Maybe a effect of this kind of projects where several people most kindly contributes and every new function is not enough carefully tested. Not enough tested by the coder or anyone else. "That's life"? And very good you reported it so it finally was solved.

[rgleason]

@Hakansv @TwoCanPlugIn Can we hide this part of the discussion now? Is the Autopilot page ok now?
https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections:autopilot

[rgleason]

Also How was this resolved?

[torrmundi]

I'm missing a Linux screenshot, and I haven't got a Linux setup. Can someone provide the proper screenshot for Linux Serial Connections Groups? This is the manual's section:

Linux Serial Connections
Make sure that you belong to the “dialout” group. To find out, run the “$groups” command. If you're not in “dialout”, add yourself with the command “$sudo usermod -a -G dialout $USER”. Logout of your current session for group changes to take effect. Check this straight away, it will save you from frustration later on. If there is a problem connecting the GPS to a physical port, such as /dev/ttyS0, the reason is probably that you don't belong to “dialout”. OpenCPN will display a warning, once per session, if you try to configure a serial connection, or starts the program with an active serial connection, and don't belong to the right group.

FIXME : missing image (torrmundi) group.jpeg

Red Hat based Linux versions are using the “uucp” group. Check what applies to your version of Linux, by using the return from the command stat -c %G `ls /dev/*|grep -m1 tty[A-Z,a-z][0]. If the return is “root”, upgrade to a contemporary Linux version.

[leamas]

Make sure that you belong to the “dialout” group... This is outdated and not longer useful (the default setup uses udev rules to make the permissiions more permissive)

It's kind of boring to have to remove this stuff again and again. Third time now, IIRC.

[leamas]

We might want to add some type of troubleshooting or FAQ section for more esoteric things like manual creation of stable links, more on permissions, etc. But this should be kept away even from the advanced sections which needs to focus on more high level stuff. And this is not now

[torrmundi]

Rick, I see in https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections#input_filtering this content, that I cannot understand:
Some examples:
Accepting the filter above leads to this in the filter column on the connection line:
<image of "in: all but AIVDM, AIVDO out: none">

What filter column? I never see that text in the image, nor do I see a filter column.

[rgleason]

I have been asking questions about this page for quite some time, including that screenshot. So don't pile on, please. The entire Connections page needs new screenshots to conform with the work that Steve, Warren, Dave and others have done to the UI in an effort to simplify it for Users. We also need review and editing down of some of the other connection pages which are improving. Thanks.

[rgleason]

I have updated the links in this post #3776 (comment) and added one link to the Editor Manual STAGING PAGE > GNSS. Please see the FIXME comments at the top of that page.

[rgleason]

Rick, I see in https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections#input_filtering this content, that I cannot understand:
Some examples:
Accepting the filter above leads to this in the filter column on the connection line:
<image of "in: all but AIVDM, AIVDO out: none">

Agreed, Tormundi, I think that is wrong and needs to be fixed, but see what bcn2 suggests .....!

[bcn2]

Another scenario where output filtering is required is forwarding AIS messages to different networks or to other consumers like AIShub.
One will just send the AIS messages and not the complete data stream.

[torrmundi]

I saw that this morning and did some editing. Thanks! I wanted a Linux groups screenshot, but maybe it’s overkill (Linux users are more capable anyway 😆). I eliminated output filter example 4 (temperamental Icom radio) as too confusing. If you want it back, just revert the last edit. Will you be able to make some connection diagrams? If not, I can take a stab at it. I’ve been editing advanced, as well. John

…

On Sat, May 11, 2024 at 9:45 AM Rick Gleason ***@***.***> wrote: John @torrmundi <https://github.com/torrmundi> Found the group.jpeg file in the unused_media_file directory and inserted it. — Reply to this email directly, view it on GitHub <#3776 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU7AEMG4NUBIOEJOCSAIWYTZBYOJJAVCNFSM6AAAAABFTWIZY2VHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TGOJVGY2DM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[rgleason]

John that would be great if you could make those connection diagrams as I right now I am focused on cleaning up the tangled mess from our old manual. I found 2000+ unlinked and unused screenshots and images and have moved them all to a folder "unused_media_files" which can be accessed and "Searched" for any missing screenshots when using Media Manager. Just a hit for you on how to run this jalopy.

You're doing a great job. Thank you.

I notice that we have two bodies of information about Networking going, one in
"Connections" Networking: TCP, UDP or GPSD https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections#networking__tcp__udp_or_gpsd
This page has grown considerably and has other duplicate information above this too. I am afraid I have not been much help in that respect.

The Old Connections page used to look like this in that area, just for reference.

The other page is "Advanced" Network Notes https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections:advanced#network_notes

We should figure out how to simplify and resolve this.

[torrmundi]

Yes, I realized that when you said you had “found” the image.

…

On Sat, May 11, 2024 at 10:23 AM Rick Gleason ***@***.***> wrote: John that would be great if you could make those connection diagrams as I right now I am focused on cleaning up the tangled mess from our old manual. I found 2000+ unlinked and unused screenshots and images and have moved them all to a folder "unused_media_files" which can be accessed and "Searched" for any missing screenshots when using Media Manager. Just a hit for you on how to run this jalopy. — Reply to this email directly, view it on GitHub <#3776 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU7AEMGO4YA3JIR2O6M6XZDZBYSVHAVCNFSM6AAAAABFTWIZY2VHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TGOJVHA4TE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[torrmundi]

Rick, is there any diagram example I should emulate for style?

…

On Sat, May 11, 2024 at 1:57 PM John Morfit ***@***.***> wrote: Yes, I realized that when you said you had “found” the image. On Sat, May 11, 2024 at 10:23 AM Rick Gleason ***@***.***> wrote: > John that would be great if you could make those connection diagrams as I > right now I am focused on cleaning up the tangled mess from our old manual. > I found 2000+ unlinked and unused screenshots and images and have moved > them all to a folder "unused_media_files" which can be accessed and > "Searched" for any missing screenshots when using Media Manager. Just a hit > for you on how to run this jalopy. > > — > Reply to this email directly, view it on GitHub > <#3776 (reply in thread)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AU7AEMGO4YA3JIR2O6M6XZDZBYSVHAVCNFSM6AAAAABFTWIZY2VHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TGOJVHA4TE> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

[rgleason]

Well, there are Steve Adler's diagrams here in this style
https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:quick_start_guide:connect_to:wifi_network
which is quite nice.

Also there are some diagrams I made some time ago using my CAD software which could be done too, they are the five diagrams here
https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_advanced:features:route_autopilot

I think whatever you need to show it will be good. If you have some ideas you want to sketch up and take a picture, I can also draw it up for you. Whatever you'd like....

[rgleason]

@TwoCanPlugIn @Hakansv @wholybee
We need your review and comments.
We've been working on Connections , Advanced and have made some small changes to Quick Start Connect to pages.

We need some help to clean up the Linux part of Connect to Serial + USB

[TwoCanPlugIn]

Linux Serial & USB looks OK to me. I would just change Selecting a Device in Linux (Outdate CLI way) to Selecting a Device in Linux using the command line interface.

Anyway some comments:

On https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections

Technically incorrect

Data sources can be connected using different types of physical connections, including serial buses (USB, RS232) and networks (WiFi, Ethernet, CanBus). Network connection protocols include TCP, UDP, GPSD (Linux only) and SignalK.

Each data source can use different types of standards to transmit information. OpenCPN supports receiving data according to the following standards:

NMEA 0183
NMEA 2000
SignalK

Should be corrected so as to describe the following:

Network communication protocols are TCP and UDP.

GPSD & SignalK are applications that run over TCP & UDP. In fact to be totally correct, GPSD runs over TCP, Signalk runs over TCP and Web Sockets (Web Sockets is a higher level protocol that runs over TCP). And OpenCPN only supports SignalK over Web Sockets.

Delete "(john) how does OpenCPN know which port is autopilot?
Here is an example from Simrad https://www.bruksanvisni.ng/simrad/ap20/bruksanvisning?p=95 See Finding Your Platform Private IP Address Use “ipconfig” from the command prompt.

FIXME (John) So you're saying it's up to the user to obtain the IP address of the autopilot, then connect an output port to that. So OpenCPN has no knowledge of where to send AP messages. Look at this next sentence about “automatically sent to the autopilot” - that cannot be true. "

The above two sentences should be deleted together with the link to the simrad manual.

NO autopilots connect to Ethernet or WiFi neworks using TCP. Do not confuse the configuration options described in the link to the Simrad manual which describes what physical ports on the autopilot are for NMEA 0183 connections.
What you are trying to say is that the user needs to determine the IP address of the gateway or multiplexer that OpenCPN is connected to. Presumably the autopilot is also connected to the same gateway & multiplexer ! This has been described in the Quick Start section.

Remember, Less is more. Far too often I read sections that have been copied from the forum, that are far too complex, poorly written and not necessarily relevant. Or there are sections that are repeating information from other sections. A simple suggestion for the future, or for whomever takes on the onerous task of editing next versions of the manual, is to read the installation and operator manuals for some of the commercial chartplotters. Admittedly OpenCPN running on PC's is more configurable and potentially more complex, but hopefully you will get the drift.

PS,
What have you done to https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections:autopilot

Delete
"(John) how does OpenCPN not conflict with an autopilot controller that also issues APB, RMB, RMC and XTE? Since Seatalk1 (NMEA-1083) uses proprietary sentences, this is not an issue. But what about SeatalkNG and B&G/Simrad NMEA 2000? OK, they use PGNs, not APB, RMB, etc. The gateway will convert. Maybe the answer is, that if a chartplotter has an active route or waypoint, and OpenCPN also has an active route or waypoint, there will be a conflict! Do we need a warning? FIXME End"

If the user is so dumb to control the autopilot from both OpenCPN and their MFD.....

Delete
"(Rick) From the Connections AP at the bottom of the page (Is this germaine now?) Should it be deleted?

FIXME (John) No idea. I looked in the Simrad manuals for AP44, AC42, NAC-3 and only found this: “Note: If the chartplotter does not transmit a message with bearing to next waypoint, the autopilot will steer using Cross Track Error (XTE) only. In that case you must revert to AUTO mode at each waypoint and manually change set course to equal bearing to next waypoint and then select NAV mode again.” RMB contains “Bearing to destination, degrees True”. APB contains “Bearing origin to destination, Mag”.

Compatibility with respect to heading From OpenCPN's point of view, the basic sentence the autopilot needs is the RMB sentence (it already contains the XTE information). Most autopilots work with just this single sentence being output. If this is not enough, and especially if the autopilot is Simrad/B&G, the APB sentence must be added so that the gateway adds the PGN “heading/track control”.

Note: Cruiser's Forum has an excellent thread discussion testing a NMEA 2000 autopilot, using various devices. See a summary at post #106, but the entire thread is informative. FIXME Rick (If it is so informative, why isn't there a link? I am not going to search for it, nor is anyone else)

FIXME End"

The basic NMEA 0183 sentences that most autopilots require from a chartplotter is XTE and either APB or RMB (or both) .
The cruisers forum post might be informative to some, but it is more like an experimenters notebook. Nothing substantive or useful.

Who changed the SignalK Server section by adding stuff about iKommunicate ?
https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections:singnalk

The discussion about Bonjour makes little sense, it's not installed by default on Windows (nor do I think is avahi-browser installed by default on Linux). There is better information on how to "discover" iKommunicate in the Digital Yacht manual. And the configuration of IKommunicate over port 80, confuses readers later who are connecting to SignalK Server.

My suggestion would be to create another section for iKommunicate, similar to that for SignalK Server, that describs how to connect to iKommunicate using SignalK Data Format over HTTP Web Socket, NMEA -183 over UDP and NMEA 0183 over TCP.

Keep in mind the previous paragraph states "The next section describes how to use any of the three supported protocols to connect OpenCPN to a SignalK Server." so that would need to be updated to reflect there are sections for both SignalK Server and iKommunicate.

BTW, Updated the GPSD section in https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:set_options:connections:advanced

It does look like there is some repetitive information about networking. And again some technical innaccuracies.

Eg. "For UDP output, if you make the last octet of the IP address 255"
That only applies for Class C addresses (eg. 192.168.xxx.xxx). Makes no sense if the user has configured a private Class B address ?

BTW Completed the outbound TCP connection section in https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:quick_start_guide:connect_to:wifi_network

[leamas]

@TwoCanPlugIn

Selecting a Device in Linux using the command line interface.

I don't see any need whatsoever for this. Using the GUI is far simpler and needs much less documentation. Just remove it.

See Finding Your Platform Private IP Address Use “ipconfig” from the command prompt.

ipconfig is deprecated in all modern distros and in many cases not available by default. The successor is the ip command, in particular ip address

[rgleason]

Please note, this is not my interest or strong suit, and I declared that early in the process. John has been very diligent and helpful, and many times I have said that Connections and Advanced pages will have to be completed by someone else!!

Well, nobody completed them and John and I have cleaned up a mess and then been chidded for asking for a little help in the form of review. That response is not fair and I am done with this BS

PS Don't piss me of any more or you won't have a completed Manual

[rgleason]

PSS: You can make the changes yourself. I am not touching Connections or Advanced again. These pages have been a PITA.

[leamas]

Moved to thread above.

[torrmundi]

The old stable links section was deemed incorrect and we took it out. I’m not sure what is correct…

…

On Sat, May 25, 2024 at 12:52 PM leamas ***@***.***> wrote: We might want to add some type of troubleshooting or FAQ section for more esoteric things like manual creation of stable links, more on permissions, etc. But this should be kept away even from the advanced sections which needs to focus on more high level stuff. And this is not now — Reply to this email directly, view it on GitHub <#3776 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU7AEMFC5L3U44SZEMYKXBDZEC6TFAVCNFSM6AAAAABFTWIZY2VHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TKNJWHE2TA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[leamas]

it was. As of today, stable links are basically created automatically

[torrmundi]

Ok, we can say that, and say what the stable link names actually are. Then we say that serial connections in Linux *should* use these name in preference over the unstable names, yes? How will the user know to use which name for which port?

…

On Sat, May 25, 2024 at 1:13 PM leamas ***@***.***> wrote: it was. As of today, stable links are basically created automatically — Reply to this email directly, view it on GitHub <#3776 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU7AEMAJ5RC3SGRFGOTS2CLZEDBEFAVCNFSM6AAAAABFTWIZY2VHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TKNJXGEZDO> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[leamas]

How will the user know to use which name for which port?

If you look at the linked screenshot it's pretty obvious

Links are preferred when they exist (they don't always do).

[torrmundi]

Thanks Rick. As you’ve said, it’s not been an easy task. We all have our knowledge limits, and it’s not good to have them thrown back at you. We’ve made some errors, but I believe the result is a better manual. The next editors will make it better yet. John

…

On Sat, May 25, 2024 at 8:01 PM Rick Gleason ***@***.***> wrote: PSS: You can make the changes yourself. I am not touching Connections or Advanced again. These pages have been a PITA. — Reply to this email directly, view it on GitHub <#3776 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU7AEMFE3G2W6PZLP72IY2LZEEQ4PAVCNFSM6AAAAABFTWIZY2VHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TKNJYGY2DK> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[rgleason]

John, thanks for all your help on these pages. I really appreciate it. Perhaps someone with more knowledge will actually review them and address the issues themselves, rather than making piecemeal comments.