From 24913be3ad10155ae8ee0d953736ce5dfbda55c9 Mon Sep 17 00:00:00 2001 From: Timo Lappalainen Date: Sun, 21 Jan 2024 09:23:46 +0200 Subject: [PATCH] Pure documentation update --- Documents/src/1_mainpage.md | 25 +- Documents/src/2_libRef.md | 624 ++++++++-------- Documents/src/3_hwSetup.md | 22 +- Documents/src/4_gettingStarted.md | 87 ++- Documents/src/5_supportedMsg.md | 123 +-- Documents/src/7_glossary.md | 317 +++++++- Documents/src/DoxyConf | 699 ++++++++++++------ Documents/src/changes.md | 4 + Documents/src/groupdef.dox | 7 +- Examples/DeviceAnalyzer/DeviceAnalyzer.ino | 11 + .../TemperatureMonitor/TemperatureMonitor.ino | 14 +- Examples/WindMonitor/WindMonitor.ino | 12 +- README.adoc | 11 +- src/ActisenseReader.h | 64 +- src/N2kCANMsg.h | 7 +- src/N2kDeviceList.h | 29 +- src/N2kGroupFunction.cpp | 6 +- src/N2kGroupFunction.h | 506 ++++++++----- src/N2kMaretron.h | 45 +- src/N2kMessages.h | 471 +++++------- src/N2kTimer.cpp | 2 +- src/NMEA2000.h | 528 +++++++------ src/NMEA2000StdTypes.h | 5 +- 23 files changed, 2122 insertions(+), 1497 deletions(-) diff --git a/Documents/src/1_mainpage.md b/Documents/src/1_mainpage.md index 5fd572d3..ba62473a 100644 --- a/Documents/src/1_mainpage.md +++ b/Documents/src/1_mainpage.md @@ -1,27 +1,21 @@ # NMEA2000 library for C++ {#mainpage} - -Object oriented NMEA2000 library for Teensy, ESP, Arduino, MBED and Rasberry type Boards. -These board types has been tested, but library can be used also in other systems by writing -compatible CAN driver and wrapper for other hw specific functions. -Library gives you easy way to make different kind of NMEA2000 bus devices like -sensor transducers (battery, temperature, wind, engine, etc.), NMEA2000 information displays, -NMEA2000->PC interface (like Actisense NGT1), NMEA0183->NMEA2000 or NMEA2000->NMEA0183 converter. +NMEA2000 library is object oriented C++ library for developing NMEA2000 bus devices. Library fulfills automatically NMEA 2000 mandatory requirements (see \ref secRefNMEA2000Certification) leaving only interesting data handling for developer. **Library has been used in several commercial certified NMEA2000 devices.** -Library fulfills NMEA 2000 mandatory functions and behavior. Devices using library can pass NMEA2000 -certification tests. Library has been used in several commercial certified products. +Library provides you easy way to make different kind of NMEA2000 bus devices like sensor transducers (battery, temperature, wind, engine, etc.), NMEA2000 information displays,NMEA2000->PC interface (like Actisense NGT1), NMEA0183->NMEA2000 or NMEA2000->NMEA0183 converter. + +I started library development on 2015 for Arduino based boards. Since that as far as I know it has been used and tested with Teensy, ESP, some Arduino, MBED and Rasberry Boards, but library can be used also in other systems by writing compatible CAN "driver" and necessary classes for other hw specific functions. If you are familiar with library, here is quick link to \ref changes. \warning -First of all - as normal - you can use library but there is not any guarantee and you use it with your own risk! -You connect your hardware always with your own risk. I wrote this documentation to help to -connect own hardware to NMEA2000 bus. I do not take any responsible of any errors in document -or any possible damages caused to your devices. +First of all - as normal - you can use library but there is not any guarantee and you use it with your own risk! You connect your hardware always with your own risk. I wrote this documentation to help to connect own hardware to NMEA2000 bus. I do not take any responsible of any errors in document or any possible damages caused to your devices. **About library documentation** -This is a new doxygen generated documentation designed by Matthias Werner - great thanks to him for excellent work. Many parts are still based on my original documentation, which I created at beginning of the library. After several years experience I see a need for several updates. So the documentation project will continue with checking and updating. For more details see \ref libDocuGen +Great thanks to Matthias Werner for excellent original library documentation work. As my knowledge of NMEA2000 has been improved a lot since 2015, boards and breakboards has been changed I'll try to update document as necessary and keep it up to date. Also I hope that other developers will inform me errors, bad language, ununderstandable text, better links etc. to keep document usable. + +Document will be automatically created in combination of document sources and code sources. For more details see \ref libDocuGen . ## Recommended hardware @@ -29,12 +23,11 @@ See this for \ref secTRecHW and please read document \ref pageHWSetUp before pur ## Hardware depended libraries -each hardware setup need a specific \ref secHWlib +Each hardware setup need a specific \ref secHWlib \section secRef References - [NMEA2000 Standard](https://www.nmea.org/nmea-2000.html) -- [List of NMEA 2000 registered devices](https://web.nmea.org/products/search) - [List of NMEA 2000 registrated companies](https://web.archive.org/web/20190529161431/http://www.nmea.org/Assets/20121020%20nmea%202000%20registration%20list.pdf) - [Device class and function codes](https://web.archive.org/web/20190531120557/https://www.nmea.org/Assets/20120726%20nmea%202000%20class%20&%20function%20codes%20v%202.00.pdf) - [ISO address claim](https://web.archive.org/web/20150910070107/http://www.nmea.org/Assets/20140710%20nmea-2000-060928%20iso%20address%20claim%20pgn%20corrigendum.pdf) diff --git a/Documents/src/2_libRef.md b/Documents/src/2_libRef.md index af4224aa..d2cae358 100644 --- a/Documents/src/2_libRef.md +++ b/Documents/src/2_libRef.md @@ -4,21 +4,25 @@ ## Introduction -NMEA2000 is object oriented C++ library, which should make it simple to develop own NMEA2000 -based devices. I created it because I wanted to get rid of limitations of expensive devices -on market. With my first own device on my yacht, I could replace three devices – NMEA0183 -combiner, NMEA0183->NMEA2000 Converter, NMEA2000->PC converter - with single Arduino Due -board and few extra chips. -To use NMEA2000 library you need basic skills for programming. I also try to write simple -instructions to start from scratch. Even I have been doing sw and hw development for years, -it took some time to dig information from internet to get started with Arduino and do -simple tasks like installing library. -For using NMEA2000 library I prefer Teensy 3.2, 3.5, 4.0, 4.1 or ESP32 with MCP2562 chip. +NMEA2000 library is object oriented C++ library for developing NMEA2000 bus devices. Library fulfills automatically NMEA 2000 mandatory requirements (see \ref secRefNMEA2000Certification) leaving only interesting data handling for developer. **Library has been used in several commercial certified NMEA2000 devices.** + +To use NMEA2000 library you need basic skills for programming. For beginners I have tried to write simple instructions to start from scratch with Arduino IDE. When I started library development and even I had been doing sw and hw development for years, it took some time to dig information from internet to get started with Arduino based boards and do even simple tasks like installing library. + +For using NMEA2000 library I prefer Teensy 4.0, 4.1, (or 3.2, 3.5, 3.6 which are end of life) or ESP32 with isolated ISO1050 or unisolated MCP2562 chip. For experienced users and big projects RPi can be also used. + For simple things Arduino Mega with CANBUS shield or schematics found under [documents](https://github.com/ttlappalainen/NMEA2000/tree/master/Documents) is ok. I have not tested smaller boards and I prefer to forget any board less than 8 kB RAM. -## Start from scratch and make your first NMEA2000 device +## History + +I started library development 2015 because I wanted to get rid of limitations of expensive devices on market. Also those did not had features I wanted. With my first own device for my yacht, I replaced three devices – NMEA0183 combiner, NMEA0183->NMEA2000 Converter, NMEA2000->PC converter - with single Arduino Due board and few extra chips. + +On 2017 library was chosen for first commercial certified device. Later there has been several other commercial devices using my library. That has also made it important to keep it combatible and ready for certificated devices. + +Since 2015 my personal work has moved more and more towards NMEA2000. I do commercially different NMEA2000 projects and consulting. + +## Start from scratch and make your first NMEA2000 device with Arduino IDE Lets think you have temperature sensor and you like to have it visible on NMEA2000 bus. Here I expect that: @@ -45,7 +49,7 @@ If you want to read or decode NMEA2000 messages, you can download and install Now we are ready to try sample without N2k bus connection. So you need only Arduino board and PC. No CANBUS shield or extra chips yet! -- Open Example TemperatureMonitor sketch, which came with NMEA2000 library. Select from +- Open example TemperatureMonitor.ino sketch, which came with NMEA2000 library. Select from IDE “Open…”-libraries/NMEA2000-master/Example/TemperatureMonitor/TemperatureMonitor.ino - uncomment lines @@ -127,17 +131,16 @@ Now just upload sketch and open right port to “NMEA Reader” and you should s only "ISO address claim" (PGN 60928) and "Environmental parameters" (PGN 130311) on “NMEA Reader”. -#### Change the device information +#### Change the device and product information -On NMEA2000 bus each device will tell to the bus what it is. This can be found -on sample under setup() function. Call SetDeviceInformation is important for right +On NMEA2000 bus each device will tell to the bus what it is (see also \ref secRefTermNAME). This can be found on sample under setup() function. Call SetDeviceInformation is important for right functionality on the bus. If you have only this own device on the bus, you can leave it like it is. In other case take deeper look in to the explanation for the function. Note that if you add several own devices to the bus, you have to configure parameters -for this function so that each device will get unic “name” as a combination of -these parameters. -Call SetProductInformation is not so important, but defines nice to know information. -If you have some “Multi Function Display” (MFD) on the bus, it will show on the +for this function so that each device will get unique \ref secRefTermNAME as a combination of +these parameters. + +Call SetProductInformation is not so important for own boat, but defines nice to know information. If you have some “Multi Function Display” (MFD) on the bus, it will show on the device list information set by this function. So you can e.g. set the “Manufacturer's Model ID” to “Jack’s temperature monitor” and version code and model version as you like, so on your MFD you can see that and choose right device. @@ -172,8 +175,8 @@ code, you have to disable message forwarding by uncommenting line: ### Try NMEA2000 library with WindMonitor example -This is exactly same as TemperatureMonitor, but sends wind data to the bus. Only necessary -function names has been changed. So follow the “ Try NMEA2000 library with +WindMonitor.ino is similar as TemperatureMonitor, but sends wind data to the bus. Only necessary +function names has been changed. So follow the “Try NMEA2000 library with TemperatureMonitor example”. ## Arduino Programming IDE @@ -251,9 +254,7 @@ to make it simple to use, but still giving “NMEA2000 compatibility”. #### Abstract base class tNMEA2000 -The tNMEA2000 class contains functions for NMEA2000 handling like e.g. sending and reading messages. -This is purely an abstract class and to use a real device you must use an appropriate inherited class. -Normally you use functions within this class. +The tNMEA2000 class contains functions for NMEA2000 handling like e.g. sending and reading messages. This is purely an abstract class and to use a real device you must use an appropriate inherited class. Normally you use functions within this class. #### Abstract base class tNMEA2000::tMsgHandler @@ -270,21 +271,18 @@ within other headers, so to use any of currently tested board you can simply add ```cpp #include - #include "NMEA2000_CAN.h" + #include ``` -So the "#include " will then automatically select right library according to the board -you have selected on IDE (see \ref USE_N2K_CAN). If you want strictly control includes or the board will -not be right selected by NMEA2000_CAN.h, use includes described on each inherited class or force -selection with define before include. E.g. +"#include " will then automatically select right library according to the board you have selected on IDE (see \ref USE_N2K_CAN). If you want strictly control includes or the board will not be selected right by NMEA2000_CAN.h, use includes described on each inherited class or force selection with define before include. E.g. ```cpp #include #define USE_N2K_CAN 1 // Force mcp_can - #include "NMEA2000_CAN.h" + #include ``` -\note Alle the inherit classes come along with the library according to your hardware setup. see \ref secHWlib +\note You need to download hardware specific inherit classes separately. See \ref secHWlib ##### Inherited class tNMEA2000_mcp @@ -295,11 +293,19 @@ To use this class, you need to include in your project beginning: ```cpp #include #include - #include "NMEA2000_mcp.h" + #include #define N2k_SPI_CS_PIN 53 // Pin for SPI Can Select #define N2k_CAN_INT_PIN 21 // Use interrupt and it is connected to pin 21 tNMEA2000_mcp NMEA2000(N2k_SPI_CS_PIN); ``` +If you use automatic library selection, you need to any define CS pin (default 53) and interrupt pin (default 21), if they differ from defaults. + +```cpp + #include + #define N2k_SPI_CS_PIN 52 // Pin for SPI Can Select + #define N2k_CAN_INT_PIN 10 // Use interrupt and it is connected to pin 21 + #include +``` You can find the mcp_can library from Originally it was developed by SeedStudio . That library was @@ -315,7 +321,7 @@ To use this class, you need to include in your project beginning: ```cpp #include - #include "NMEA2000_due.h" + #include tNMEA2000_due NMEA2000; ``` @@ -330,10 +336,31 @@ can bus controller. Physical interface is similar as with Arduino Due. To use this class, you need to include in your project beginning: ```cpp - #include "NMEA2000_teensy.h" + #include + tNMEA2000_teensy NMEA2000; +``` + +##### Inherited class tNMEA2000_Teensyx + +The tNMEA2000_Teensyx class is for using library with Teensy 3.2, 3.5, 3.6, 4.0, 4.1 boards, which has internal +can bus controller. Physical interface is similar as with Arduino Due. +To use this class, you need to include in your project beginning: + +```cpp + #include tNMEA2000_teensy NMEA2000; ``` +At the moment automatic automatic library selection uses as default NMEA2000_teensy.h for +Teensy 3.2, 3.5, 3.6. NMEA2000_Teensyx works reliably with old boards too so you can force +it for automatic library selection + +```cpp + #include + #define USE_NMEA2000_TEENSYX_FOR_TEENSY_3X // Force NMEA2000_TEENSYX also for Teensy 3.x boards + #include +``` + ##### Inherited class tNMEA2000_esp32 The tNMEA2000_esp32 class is for using library with ESP32 based boards, which has internal can bus @@ -389,58 +416,43 @@ NMEA 2000 definition requires than devices should respond group function message class is default handler, which simply responds “unsupported” for all queries. see \ref tN2kGroupFunctionHandler -\todo More Details in documentation needed here .... +#### Device list collector class tN2kDeviceList -#### Inherited group function handler tN2kGroupFunctionHandlerForPGN60928 +This class can be used to read devices on the connected NMEA 2000 bus. When class has been attached to tNMEA2000 object, it will automatically collect and update information of devices on the bus. On the NMEA 2000 bus all devices (also called nodes) has own source address. The source addressmay be changed due to \ref secRefTermAddressClaiming "address claiming" on power up or when new device will be added to the bus. For this reason source address can not be used as only filter for similar messages like position data. By using tN2kDeviceList source address related to \ref secRefTermNAME can be easily found at any time with tN2kDeviceList functions. -This class handles mandatory group function requests and commands for PGN 60928. -see \ref tN2kGroupFunctionHandlerForPGN60928 -#### Device list collector class tN2kDeviceList +In principle on steady system source will stay unchanged. The safer way is to use device \ref secRefTermNAME which should be unique. So if you e.g., have two speed logs and you want to specify the one you want to use, you can use tN2kDeviceList class to search source address for specified NAME and then read log messages from that source. -This class can be used to read devices on the connected NMEA 2000 bus. When class has been -attached to tNMEA2000 object, it will automatically collect and update information of devices on the bus. -On the NMEA 2000 bus all devices (also called nodes) has own source address. This source can -change e.g. when new devices will be added. In principle on steady system also source will be -same. The safer way is to use device “Name” which should be unique. So if you e.g. have two -speed logs and you want to specify the one you want to use, you can use tN2kDeviceList class -to search source address for specified name and then read log messages from that source. +See also example DeviceAnalyzer.ino. ### Using tNMEA2000 There are several examples for using library with different functions like for only listen bus data (ActisenseListener.ino), sending temperature (TemperatureMonitor.ino) or wind data (WindMonitor.ino) from your own sources or displaying bus data somehow (DisplayData.ino -and DisplayData2.ino). With combination of those or adding NMEA0183 library functions, you -can have full control for your N2k bus information. -I have already own device, which reads data from old NMEA0183 devices and forwards it to the -N2k bus, but same device also forwards data from bus to the PC. It also listens on input -pin – MOB and when that is activated, it will start to send route information back to -the activation position. I have also temperature and fuel consumption monitors to the N2k bus. -So below is short description of member functions, which hopefully gives you better knowledge +and DisplayData2.ino). + +Library core has all functionalities to communicate with NMEA2000 bus and N2kMessages.h has simple functions to read and set most common messages. And you can add own modules to support missing messages. Rest is up to your imagination. + +Below is short description of member functions, which hopefully gives you better knowledge why something has been used on samples. #### Device modes -In principle all devices should act as node on N2k bus. But if you are only reading messages +NMEA2000 defines that all devices should act as node on N2k bus. But if you are only reading messages on bus, why to tell anybody. So I have defined different modes how tNMEA2000 class behaves. - ##### tNMEA2000::N2km_ListenOnly This is default mode. The device simply listens data from bus and forwards it to the forward stream. Look example ActisenseListener, you need only 20 line for making device to read data on N2k bus. Also if you like to make a device, which displays some data on bus on e.g. TFT display, you can -use this mode. There is simple example DataDisplay for that. +use this mode. There is simple example DataDisplay.ino for that. ##### tNMEA2000::N2km_NodeOnly -In this mode device will only send data to the N2k bus. I also automatically informs itself -to other devices on the bus and does required address claiming automatically. The device does not -send as default anything to any forward stream. -Use this mode for device, which simply e.g. reads data from analog or digital input or -NMEA0183 bus and sends it to the N2k bus. Look example TemperatureMonitor. +In this mode device will only send data to the N2k bus. I also automatically informs itself to other devices on the bus and does required operations automatically. The device does not send as default anything to any forward stream. Use this mode for device, which simply e.g. reads data from analog or digital input or NMEA0183 bus and sends it to the N2k bus. Look example TemperatureMonitor.ino. ##### tNMEA2000::N2km_ListenAndNode @@ -466,12 +478,12 @@ read and send messages in Actisense format to serial port. I have used this mode with example TeensyActisenseListenerSender and Actisense NMEA Reader and NMEA Simulator. -#### Message forwarding +#### Message forwarding {#secMessageforwarding} Normally on N2k bus a device either shows data from bus (MFD devices) or sends data to the bus (wind, GPS, temperature etc.). With this library you can also get messages forwarded to the stream. In listen mode, the device will read all messages from N2k bus -and forwards all messages to the ForwardStream. For forwarding you have to define a +and forwards them to the ForwardStream. For forwarding you have to define a forward stream with function \ref tNMEA2000::SetForwardStream. Of course you also need to open a stream first e.g. with Serial.begin(115200); Messages will be forwarded as default in Actisense format. This is supported by at least @@ -479,19 +491,23 @@ some PC chart plotter applications. With default format Actisence “NMEA Reader we used on sample, you can show message data. A better visualizer is OpenSkipper, on which you can tailor your own displays. -\note Default own messages send with tNMEA2000.SendMsg will be forwarded even when your +\note As default own messages send with tNMEA2000::SendMsg will be forwarded even when your device has been set to node only mode. This may disturb your developing, if you e.g. want to write own clear text messages within your code. You can disable that by either: -- tNMEA2000::EnableForward(false) to disable forwarding totally -- tNMEA2000::SetForwardOwnMessages(false) to disable own messages. But then, if your device +- \ref tNMEA2000::EnableForward(false) to disable forwarding totally +- \ref tNMEA2000::SetForwardOwnMessages(false) to disable own messages. But then, if your device is in listen mode, it will still forward messages from bus. -- tNMEA2000::SetForwardOnlyKnownMessages(true) to define that only known messages will be +- \ref tNMEA2000::SetForwardOnlyKnownMessages(true) to define that only known messages will be forwarded. The known messages are system messages and listed single frame or fast packet - messages. See also \ref tNMEA2000::SetSingleFrameMessages, \ref tNMEA2000::SetFastPacketMessages, - \ref tNMEA2000::ExtendSingleFrameMessages and \ref tNMEA2000::ExtendFastPacketMessages. + messages. + \sa + - \ref tNMEA2000::SetSingleFrameMessages + - \ref tNMEA2000::SetFastPacketMessages + - \ref tNMEA2000::ExtendSingleFrameMessages + - \ref tNMEA2000::ExtendFastPacketMessages. -#### Debug mode +#### Debug mode {#descDebugMode} Debug mode is as default set to tNMEA2000::dm_None. In other debug modes device will not send anything to the N2k bus. @@ -510,344 +526,350 @@ In NMEA 2000 bus you have devices or also called nodes. Normally each physical d device on the bus. I have not seen any requirement that a device could not serve as engine information (device class 50 – propulsion) or sensor information (device class 75 - Sensor Communication Interface) interface at same time and just use device class 25 (Inter/Intranetwork -Device) and function 132 (Analog to NMEA 2000 Gateway). Anyway I just noticed that e.g. +Device) and function 132 (Analog to NMEA 2000 Gateway). Anyway I have found that e.g. B&G Vulcan 7 chartplotter acts as multi device. I do not know are these devices different chips inside Vulcan or are they within same code as my multi device. If you like show different functions as own device on the bus, you can do that with multi -device support. All you need to do is to first set device count (see SetDeviceCount), set +device support. All you need to do is to first set device count (see tNMEA2000::SetDeviceCount), set device and product information for each device and on sending messages use right device index. See example MultiDevice. -#### Member functions - -##### SetDeviceCount - -With this function you can enable multi device support. As default there is only one device. - -\note To enable multi device support, you need to call this before any other tNMEA2000 class function. +#### Running library {#descRunningLibrary} -##### SetN2kCANMsgBufSize +Library has been designed to work without need for multitasking system. After setup it is critical to call tNMEA2000::ParseMessages in loop as fast as possible. By that call library handles many basic required features like address claiming, responding to system requests, heartbeat sending etc. -With this function you can set size of buffer, where system stores incoming messages. The default -size is 5 messages. -Some messages are just single frame messages and they will be read in and handled immediately on -call to ParseMessages. For multi framed fast packet messages there is no guarantee that all frames -will arrive in order. So these messages will be buffered and saved until all frames has been received. -If it is not critical to handle all fast packet messages like with N2km_NodeOnly, you can set buffer -size smaller like 3 or 2 by calling this before open. +Fast loop requirement means that you are not allowed to use any delay on your loop or any other library using delay or blocking read. Delays withing loop in worst case causes that other devices on your NMEA2000 bus drops your device from the list and then pops it up again. If you have e.g., configured your MFD to show temperature from your device, it may appear and disappear on the screen. -##### SetN2kCANSendFrameBufSize +A practice has shown that random 10-50 ms delay is acceptable. In average loop time should be +less than 2 ms. Also it is important that if you can have up 50 ms random delay, you may get in burst up to 90 frames (=1800 frames/s *0.05 s) during that time. This means that if your receive frame buffer is smaller, your device may loose some critical system messages. In small boat this amount is a bit theory, but anyway there are a lot of large messages just from GPS system so that they may occur time to time at same time. So it is better to prepare your device work in nearly any condition. -With this function you can set size of buffer, where system saves frames of messages to be sent. -The default size is 40 frames so totally 320 bytes. Call this before any device related function -like SetProductInformation. -When sending long messages like ProductInformation or GNSS data, there may not be enough low level -buffers for sending data successfully. This depends of your hw and device source. Device source -has an effect due to priority of getting sending slot on low level device. If your data is critical, -use a buffer size, which is large enough. -E.g. Product information takes totally 134 bytes. This needs 20 frames. GNSS contains 47 bytes, -which needs 7 frames. If you want to be sure that both will be sent on any situation, you need -at least 27 frame buffer size. +##### Some timing examples -##### SetProductInformation +If you use DallasTemperature library as default you may block loop up to 700 ms. By using it "asynchronously", delays are smaller and may be acceptable. Best solution would be to use some kind of hardware based library like esp32-owb for ESP32. -If you are using device modes tNMEA2000::N2km_NodeOnly or tNMEA2000::N2km_ListenAndNode, it would -be good that you set this information. With this you can set how e.g. Multi Function Displays -(MFD) will show your device information. This is not critical, but nice to have it right. -See example TemperatureMonitor.ino. +Some ADC libraries blocks loop during conversion, which may be 200-400 ms for high resolution ADC with averaging. ADC:s should be always used so that conversion will be started and then quickly checked, when conversion is ready. Even better if you know conversion time and check it after you expect it should be ready. -##### SetDeviceInformation +Some displays are very slow for writing. Writing some text may take 100 ms causing too long delay and problems with bus. Depending of library, it may also have some kind of buffering to get write request and flag, when it has been finished without blocking call. If there is not, it is often possible write own higher level buffering, which finally writes to display letter by letter and so spent only short time on each call. -If you are using device modes tNMEA2000::N2km_NodeOnly or tNMEA2000::N2km_ListenAndNode, it is -critical that you set this information. +With serial line use always available and availableForWrite features to avoid blocking. Also it helps if you can define bigger harware buffers. -\note You should set information so that it is unique over the world! Well if -you are making device only for your own yacht N2k bus, it is enough to be -unique there. So e.g. if you have two temperature monitors made by this library, you have to set at -least first parameter UniqueNumber different for both of them. +In multitasking system someone had defined tNMEA2000::ParseMessages task time to 100 ms. I do not wonder, if there will random strange problems with that device. 1 ms task time would be acceptable. -Device information will be used to choose right address for your device (also called node) on -the bus. Each device must have an own address. Library will do this automatically, so it is enough -that you call this function on setup to define your device. +##### System messages and library internal functionality {#descSystemMessages} -##### SetDeviceInformationInstances +Library has been designed to do automatically as many required features as possible. In this way user can concentrate to his own code and does not need to know everything about NMEA2000 low level. There is several system messages, which are handled automatically and user does not need to take care of. -With this function you can set device instance lower, device instance upper and system instance values. +- PGN 59392 ISO Acknowledgement. + + Library responds with NAK for unhandled requests. + . +- PGN 59904 ISO Request. + + Library handles ISO request for system messages. + + For other messages library calls ISORequestHandler. See tNMEA2000::SetISORqstHandler. + . +- PGN 60928 ISO Address Claim. + + Library starts address claiming procedure automatically and handles it completely. + + Library responds as required to others address claiming, if necessary. See also tNMEA2000::ReadResetAddressChanged. + + Library handles normal requests and group function requests to change device or system instances. See also tNMEA2000::ReadResetDeviceInformationChanged. + + If you need to track devices on the bus e.g., to tie some message to specific device there is automatic module tN2kDeviceList to do work for you. + . +- PGN 60416 and PGN 60160 ISO Transport Protocol messages. + + Library hadles automatically message sending and receiving with ISO TP. + . +- PGN 126208 Group Function message. + + Library does default handling for system messages. + + For other messages library forwards handling to class inherited from tN2kGroupFunctionHandler. See tNMEA2000::AddGroupFunctionHandler. +- PGN 126464 Receive/Transmit PGN list. + + Library responds automatically for requested PGN lists. User has to take care that own PGNs has been declared at startup with tNMEA2000::SendTxPGNList and tNMEA2000::SendRxPGNList. +- PGN 126993 Heartbeat. + + Library takes care of heartbeat sending. + + Library also takes care of heartbeat offset/period change requests. +- PGN 126996 Product information. + + Library responds automatically to product information requests. User has to setup product information at device start with tNMEA2000::SetProductInformation. +- PGN 126998 Configuration information. + + Library responds automatically to configuration information requests. User has to setup configuration information at device start with tNMEA2000::SetConfigurationInformation. + + Library also updates Installation Description 1 and 2 on request. See also tNMEA2000::ReadResetInstallationDescriptionChanged. -##### GetDeviceInformation +#### Member functions -With this function you can read current device information. Normally device information contains -what you have set during initializing with SetDeviceInformation and SetDeviceInformationInstances -functions. +======================================= +##### tNMEA2000::SetProductInformation -\note device information instances can be changed by the NMEA 2000 group function by -e.g. using system configuration device. So you should time to time check if they have changed and -save changed data to e.g. EEPROM for use on startup. +\copybrief tNMEA2000::SetProductInformation +\copydetails tNMEA2000::SetProductInformation -See \ref tNMEA2000::ReadResetDeviceInformationChanged +======================================= +##### tNMEA2000::SetDeviceInformation -##### SetConfigurationInformation +\copybrief tNMEA2000::SetDeviceInformation +\copydetails tNMEA2000::SetDeviceInformation -With this function you can set configuration information, which will be saved on device RAM. -As an alternative you can set configuration information saved on progmem with -\ref tNMEA2000::SetProgmemConfigurationInformation -Configuration information is just some extra information about device and manufacturer. Some -MFDs shows it, some does not. E.g. NMEA Reader can show configuration information. +======================================= +##### tNMEA2000::SetDeviceInformationInstances -##### SetProgmemConfigurationInformation +\copybrief tNMEA2000::SetDeviceInformationInstances +\copydetails tNMEA2000::SetDeviceInformationInstances -With this function you can set configuration information, which will be saved on device program memory. -See example BatteryMonitor.ino. -As default system has build in configuration information on progmem. If you do not want to have -configuration information at all, you can disable it by calling SetConfigurationInformation(0); +======================================= +##### tNMEA2000::GetDeviceInformation -##### SetSingleFrameMessages +\copybrief tNMEA2000::GetDeviceInformation +\copydetails tNMEA2000::GetDeviceInformation -As a default library has a list of known messages. With this function user can override default -list of single frame messages. See also \ref tNMEA2000::ExtendSingleFrameMessages. +======================================= +##### tNMEA2000::SetConfigurationInformation -##### SetFastPacketMessages +\copybrief tNMEA2000::SetConfigurationInformation +\copydetails tNMEA2000::SetConfigurationInformation -As a default library has a list of known messages. With this function user can override default -list of fast packet messages. See also \ref tNMEA2000::ExtendFastPacketMessages. +======================================= +##### tNMEA2000::SetProgmemConfigurationInformation -\note If an incoming fast packet message is not known, it will be treated as single frame -message. So if you want to handle unknown fast packet message, you need to duplicate frame -collection logic from library to your code. So it is easier to have fast packet messages listed -on library, if you want to handle them. +\copybrief tNMEA2000::SetProgmemConfigurationInformation +\copydetails tNMEA2000::SetProgmemConfigurationInformation -##### ExtendSingleFrameMessages +======================================= +##### tNMEA2000::SetMode -As a default library has a list of known messages. With this function user can add own list of -known single frame messages. +\copybrief tNMEA2000::SetMode +\copydetails tNMEA2000::SetMode -\note Subsequent calls will overwrite the previously set list +Example how to init and save device source address. -##### ExtendFastPacketMessages +```cpp + void setup() { + ... + NMEA2000.SetMode(tNMEA2000::N2km_NodeOnly,GetLastSavedN2kAddressFromEEPROM()); + ... + } -As a default library has a list of known messages. With this function user can add own list of -known fast packet messages. + ... + void loop() { + SendN2kTemperature(); + NMEA2000.ParseMessages(); + if (NMEA2000.ReadResetAddressChanged() ) { + SaveN2kAddressToEEPROM(GetN2kSource()); + } + } +``` -\note Currently subsequent calls will override previously set list. +======================================= +##### tNMEA2000::ExtendTransmitMessages -\note If an incoming fast packet message is not known, it will be treated as single frame -message. So if you want to handle unknown fast packet message, you need to duplicate frame collection -logic from library to your code. So it is easier to have fast packet messages listed on library, -if you want to handle them. +\copybrief tNMEA2000::ExtendTransmitMessages +\copydetails tNMEA2000::ExtendTransmitMessages -##### ExtendTransmitMessages +======================================= +##### tNMEA2000::ExtendReceiveMessages -System should respond to PGN 126464 request with messages the system transmits and receives. The -library will automatically respond with system the messages it uses. With this method you can -add messages, which your own code sends +\copybrief tNMEA2000::ExtendReceiveMessages +\copydetails tNMEA2000::ExtendReceiveMessages -\note that this is valid only for device modes \ref tNMEA2000::N2km_NodeOnly and \ref tNMEA2000::N2km_ListenAndNode. +======================================= +##### tNMEA2000::SetOnOpen -##### ExtendReceiveMessages +\copybrief tNMEA2000::SetOnOpen +\copydetails tNMEA2000::SetOnOpen -Method is like \ref tNMEA2000::ExtendTransmitMessages, but extends messages you code handles. +======================================= +##### tNMEA2000::SendMsg -##### SendIsoAddressClaim +\copybrief tNMEA2000::SendMsg +\copydetails tNMEA2000::SendMsg -This is automatically used by class. You only need to use this, if you want to write your own -behavior for address claiming. +======================================= +##### tNMEA2000::ParseMessages -##### SendProductInformation +\copybrief tNMEA2000::ParseMessages +\copydetails tNMEA2000::ParseMessages -This is automatically used by class. You only need to use this, if you want to write your own -behavior for providing product information. +======================================= +##### tNMEA2000::SetMsgHandler -##### SendConfigurationInformation +\copybrief tNMEA2000::SetMsgHandler +\copydetails tNMEA2000::SetMsgHandler -This is automatically used by class. You only need to use this, if you want to write your own -behavior for providing configuration information. +======================================= +##### tNMEA2000::AttachMsgHandler -##### SetHeartbeatInterval +\copybrief tNMEA2000::AttachMsgHandler +\copydetails tNMEA2000::AttachMsgHandler -According to document [20140102 nmea-2000-126993 heartbeat pgn corrigendum.pdf](https://web.archive.org/web/20170609023206/https://www.nmea.org/Assets/20140102%20nmea-2000-126993%20heartbeat%20pgn%20corrigendum.pdf) all NMEA devices shall -transmit heartbeat PGN 126993. With this function you can set transmission interval in ms -(range 1000-655320 ms, default 60000). Set <1000 to disable it. You can temporary change -interval by setting SetAsDefault parameter to false. Then you can restore default interval -with interval parameter value 0xfffffffe +======================================= +##### tNMEA2000::DetachMsgHandler -##### GetHeartbeatInterval +\copybrief tNMEA2000::DetachMsgHandler +\copydetails tNMEA2000::DetachMsgHandler -Heartbeat interval may be changed by e.g. MFD by group function. I have not yet found if a -changed value should be saved for next startup or not like address. +======================================= +##### tNMEA2000::SetISORqstHandler -##### SendHeartbeat +\copybrief tNMEA2000::SetISORqstHandler +\copydetails tNMEA2000::SetISORqstHandler -Library will automatically send heartbeat, if interval is >0. You can also manually send it -any time or force sent, if interval=0; +======================================= +##### tNMEA2000::GetN2kSource -##### SetMode +\copybrief tNMEA2000::GetN2kSource +\copydetails tNMEA2000::GetN2kSource -With SetMode you can define how your node acts on N2k bus. See \ref tNMEA2000::Devices modes. -With this function you can also set default address for your device. It is mandatory -that once your device has been connected to the bus, it tries always use last used address. -Due to address claiming, your device may change its address, when you add new devices to the bus. -So you should save last used address to the e.g. EEPROM and on startup read it there and use -it as parameter for SetMode. You can check if your address you set originally by SetMode -has changed by using function \ref tNMEA2000::SetN2kSource and you can read current address by -function \ref tNMEA2000::GetN2kSource. +======================================= +##### tNMEA2000::SetN2kSource -So you could do next: +\copybrief tNMEA2000::SetN2kSource +\copydetails tNMEA2000::SetN2kSource -```cpp - void setup() { - ... - NMEA2000.SetMode(tNMEA2000::N2km_NodeOnly,GetLastSavedN2kAddressFromEEPROM()); - ... - } +======================================= +##### tNMEA2000::ReadResetAddressChanged - ... - void loop() { - SendN2kTemperature(); - NMEA2000.ParseMessages(); - if (NMEA2000.ReadResetAddressChanged() ) { - SaveN2kAddressToEEPROM(GetN2kSource()); - } - } -``` +\copybrief tNMEA2000::ReadResetAddressChanged +\copydetails tNMEA2000::ReadResetAddressChanged -See example TemperatureMonitor.ino. +======================================= +##### tNMEA2000::ReadResetDeviceInformationChanged -##### SetForwardType +\copybrief tNMEA2000::ReadResetDeviceInformationChanged +\copydetails tNMEA2000::ReadResetDeviceInformationChanged -With this function user can set how messages will be forwarded to the stream. Possible values are: +======================================= +##### tNMEA2000::ReadResetInstallationDescriptionChanged -- tNMEA2000::fwdt_Actisense (default) forwards messages is Actisense format. Some navigation softwares - can read this format. -- tNMEA2000::fwdt_Text forwards messages to output port in clear text. I see this useful only for testing - with normal serial monitors. +\copybrief tNMEA2000::ReadResetInstallationDescriptionChanged +\copydetails tNMEA2000::ReadResetInstallationDescriptionChanged -##### SetForwardStream +======================================= +##### tNMEA2000::SetDeviceCount -As default, forward stream has been set to null. For e.g. Arduino Due you can set it to SerialUSB, -so you can use Serial for other things. You can of coarse use any stream available on your device. -See example ActisenseListenerSender.ino. +\copybrief tNMEA2000::SetDeviceCount +\copydetails tNMEA2000::SetDeviceCount -##### Open +======================================= +##### tNMEA2000::SetN2kCANMsgBufSize -You can call this on Setup(). It will be called anyway automatically by first call of ParseMessages(). +\copybrief tNMEA2000::SetN2kCANMsgBufSize +\copydetails tNMEA2000::SetN2kCANMsgBufSize -##### SendMsg +======================================= +##### tNMEA2000::SetN2kCANSendFrameBufSize -When you want to send some message to the N2k bus, you call this. Before calling you have to prepare -tN2kMsg type of message e.g. by using some function in N2kMessages. +\copybrief tNMEA2000::SetN2kCANSendFrameBufSize +\copydetails tNMEA2000::SetN2kCANSendFrameBufSize -\note As default tNMEA2000 object is as default in tNMEA2000::N2km_ListenOnly mode. So if -you want to send messages, you have to set right mode in Setup(). +======================================= +##### tNMEA2000::SetN2kCANReceiveFrameBufSize -The function returns true, if the message was sent successfully, otherwise it return false. SendMsg may fail, -if there is not room for message frames on sending buffer or device is not open. -SendMsg does not always send message immediately. If lower level sending function fails, SendMsg -will buffer message frames and try to send them on next call to SendMsg or ParseMessages. So -to have reliable sending, you need a sending buffer, which is large enough. -See example TemperatureMonitor.ino. +\copybrief tNMEA2000::SetN2kCANReceiveFrameBufSize +\copydetails tNMEA2000::SetN2kCANReceiveFrameBufSize -##### ParseMessages +======================================= +##### tNMEA2000::SetSingleFrameMessages -You have to call this periodically on loop(), otherwise tNMEA2000 object will not work at all. +\copybrief tNMEA2000::SetSingleFrameMessages +\copydetails tNMEA2000::SetSingleFrameMessages -\note It is not good practice to have any delay() on your loop(), since then also handling of -this will be delayed. +======================================= +##### tNMEA2000::SetFastPacketMessages -See example TemperatureMonitor.ino. +\copybrief tNMEA2000::SetFastPacketMessages +\copydetails tNMEA2000::SetFastPacketMessages -##### SetMsgHandler +======================================= +##### tNMEA2000::ExtendSingleFrameMessages -If you want to do something with messages read from N2k bus, easiest is to set message handler, -which will be then called by ParseMessages, if there are new messages. This is the case e.g. if -you have LCD display on your Arduino and you want to show some fluid level on it. -See example DataDisplay.ino or DataDisplay2.ino +\copybrief tNMEA2000::ExtendSingleFrameMessages +\copydetails tNMEA2000::ExtendSingleFrameMessages -##### AttachMsgHandler +======================================= +##### tNMEA2000::ExtendFastPacketMessages -SetMsgHandler allows you to define only one handler to your system. If you like to do it by -using classes, I prefer to use AttachMsgHandler. In this way you can e.g. define own class for -each PGN and attach/detach them within your program. Example NMEA2000ToNMEA0183 uses AttachMsgHandler. -Due to logic it still has single class and so handles all PGNs. +\copybrief tNMEA2000::ExtendFastPacketMessages +\copydetails tNMEA2000::ExtendFastPacketMessages -##### DetachMsgHandler +======================================= +##### tNMEA2000::SendIsoAddressClaim -With DetachMsgHandler you can remove your handler from the handler stack. This is useful, -if you do not want to handle some messages anymore. +This is automatically used by class. You only need to use this, if you want to write your own +behavior for address claiming. -##### SetISORqstHandler +======================================= +##### tNMEA2000::SendProductInformation -Devices on N2k bus may request from your device if it can handle requested PGN. If you want to -respond for ISO request, you should set this handler. The handler will be called by ParseMessages, -if there is ISO request. +This is automatically used by class. You only need to use this, if you want to write your own +behavior for providing product information. -\note When you send request message with SendMsg and it fails, it is your responsibility -to take care of sending response again later. If your sending buffer is large enough, it -is very uncommon that SendMsg fails. +======================================= +##### tNMEA2000::SendConfigurationInformation -##### GetN2kSource +This is automatically used by class. You only need to use this, if you want to write your own +behavior for providing configuration information. -With this function you can get you device current address on the N2k bus. -See \ref tNMEA2000::SetMode and \ref tNMEA2000::SetN2kSource +======================================= +##### tNMEA2000::SetHeartbeatIntervalAndOffset -##### SetN2kSource +\copybrief tNMEA2000::SetHeartbeatIntervalAndOffset +\copydetails tNMEA2000::SetHeartbeatIntervalAndOffset -With this function you can set you device current address on the N2k bus. This is meant to be -use for multi device on basic configuration to restore source address changed by address claiming. -See \ref tNMEA2000::SetMode and \ref tNMEA2000::SetN2kSource +======================================= +##### tNMEA2000::GetHeartbeatInterval -##### ReadResetAddressChanged +\copybrief tNMEA2000::GetHeartbeatInterval +\copydetails tNMEA2000::GetHeartbeatInterval -With this function you can check has your device address you initiated with SetMode been -changed after last call. For certified NMEA 2000 devices it is mandatory save changed address -to e.g. EEPROM, for use in next startup. -See \ref tNMEA2000::SetMode and \ref tNMEA2000::SetN2kSource +======================================= +##### tNMEA2000::SendHeartbeat -##### ReadResetDeviceInformationChanged +Library will automatically send heartbeat, if interval is >0. You can also manually send it +any time or force sent, if interval=0; -With this function you can check has your device device instances or system instances changed. -For certified NMEA 2000 devices it is mandatory save changed info to e.g. EEPROM, for -initialize them in next startup. +======================================= +##### tNMEA2000::SetForwardType -See \ref tNMEA2000::SetDeviceInformationInstances and \ref tNMEA2000::GetDeviceInformation +\copybrief tNMEA2000::SetForwardType +\copydetails tNMEA2000::SetForwardType -##### EnableForward +======================================= +##### tNMEA2000::SetForwardStream -Set true as default. With this you can control if bus messages will be forwarded to forward -stream. +\copybrief tNMEA2000::SetForwardStream +\copydetails tNMEA2000::SetForwardStream -see \sa Message forwarding. +======================================= +##### tNMEA2000::Open -##### SetForwardSystemMessages +\copybrief tNMEA2000::Open +\copydetails tNMEA2000::Open -Set true as default. With this you can control if system messages like address -claiming, device information will be forwarded to forward stream. -If you set this false, system messages will not be forwarded to the stream. +======================================= +##### tNMEA2000::EnableForward -##### SetForwardOnlyKnownMessages +\copybrief tNMEA2000::EnableForward +\copydetails tNMEA2000::EnableForward -Set false as default. With this you can control if unknown messages will be forwarded to -forward stream. If you set this true, all unknown message will not be forwarded to the stream. +======================================= +##### tNMEA2000::SetForwardSystemMessages -\note This does not effect for own messages. Known messages are listed on library. +\copybrief tNMEA2000::SetForwardSystemMessages +\copydetails tNMEA2000::SetForwardSystemMessages -See \ref tNMEA2000::SetSingleFrameMessages, \ref tNMEA2000::SetFastPacketMessages, -\ref tNMEA2000::ExtendSingleFrameMessages and \ref tNMEA2000::ExtendFastPacketMessages. +======================================= +##### tNMEA2000::SetForwardOnlyKnownMessages -##### SetForwardOwnMessages +\copybrief tNMEA2000::SetForwardOnlyKnownMessages +\copydetails tNMEA2000::SetForwardOnlyKnownMessages -Set true as default. With this you can control if messages your device sends to bus will be -forwarded to forward stream. +======================================= +##### tNMEA2000::SetForwardOwnMessages -##### SetHandleOnlyKnownMessages +\copybrief tNMEA2000::SetForwardOwnMessages +\copydetails tNMEA2000::SetForwardOwnMessages -Set false as default. With this you can control if unknown messages will be handled at all. -Known messages are listed on library. +======================================= +##### tNMEA2000::SetHandleOnlyKnownMessages -See \ref tNMEA2000::SetSingleFrameMessages, \ref tNMEA2000::SetFastPacketMessages, -\ref tNMEA2000::ExtendSingleFrameMessages and \ref tNMEA2000::ExtendFastPacketMessages. +\copybrief tNMEA2000::SetHandleOnlyKnownMessages +\copydetails tNMEA2000::SetHandleOnlyKnownMessages -##### SetDebugMode +======================================= +##### tNMEA2000::SetDebugMode -If you do not have physical N2k bus connection and you like to test your board without -even CAN controller, you can use this function. -see \sa Debug mode. +\copybrief tNMEA2000::SetDebugMode +\copydetails tNMEA2000::SetDebugMode diff --git a/Documents/src/3_hwSetup.md b/Documents/src/3_hwSetup.md index 08004eca..9e59e2e8 100644 --- a/Documents/src/3_hwSetup.md +++ b/Documents/src/3_hwSetup.md @@ -26,10 +26,8 @@ of any errors in the document or any possible damages caused to your devices. ## Recommended hardware {#secTRecHW} -I personally prefer to use Teensy 3.2, 3.5, 3.6, 4.0, 4.1 or ESP32 board. Those boards -have internal CAN controller and require only either unisolated MCP2562 or isolated ISO1050 -transceiver for NMEA2000 connection. -With default settings library requires **about 23 kB rom and 3.3 kB RAM in normal operation**. +I personally prefer to use Teensy 4.0, 4.1 (or 3.2, 3.5, 3.6 which are at end of life) or ESP32 board. Those boards have internal CAN controller and require only either isolated ISO1050 or unisolated MCP2562 transceiver for NMEA2000 connection. +With default settings library requires roughly **about 30 kB rom and 4 kB RAM in normal operation**. So you should have **at least 8 kB RAM in your processor**. If you have Arduino Mega board, it is OK for testing and for small projects, but I do not prefer to buy one for new project. Arduino Due is better, but it is physically bigger and eats more power than Teensies or ESP32. @@ -41,7 +39,7 @@ and you have trouble to get it working, please do not set any issues. Some boards (or processors) have internal CAN controller. In board there will be simply CAN Tx/CAN Rx pins, which often works with 3.3 V levels. Good examples of this kind of boards -are recommended Teensy 3.2, 3.5, 3.6, 4.0, 4.1 or ESP32 boards. +are recommended Teensy 4.0, 4.1 (or 3.2, 3.5, 3.6 which are at end of life) or ESP32 boards. Arduino DUE has also internal CAN controller. Never connect CAN Tx/CAN Rx pins directly to NMEA2000 bus. If you use board without internal CAN controller or you want to have second CAN controller e.g., for Teensy 3.2 or ESP32, you can use external one. Currently only supported is @@ -65,10 +63,7 @@ controller to CAN bus levels. #### Recommended transceiver {#subsubRecTra} -I recommend either unisolated MCP2562 or isolated ISO1050 transceiver. MCP2562 operates -with 5 V and it has own pin to define Tx/Rx logic levels for 3.3 V devices. ISO1050 has own -power pin for both sides so it also works with any logic levels. There is lot of issues with -SN65HVD230 transceiver. If you use that, please do not open issue – it is not library problem. +I recommend either isolated ISO1050 or unisolated MCP2562 transceiver. ISO1050 has own power pin for both sides so it also works with any logic levels. MCP2562 operates with 5 V and it has own pin to define Tx/Rx logic levels for 3.3 V devices. There is lot of issues with SN65HVD230 transceiver. If you use that, please do not open issue – it is not library problem. I do not know why there has been so much problems with SN65HVD230 - according datasheet it should be fine. I have had problems with MCP2562 only twice. Once I mixed Vdd and Vcc - worked @@ -76,10 +71,7 @@ fine after connected them right. Another time I connected STBY pin to Vdd, which \note **This is very important.** -If you use unisolated tranceiver like MCP2562, you may cause -ground loop in your boat. Ground loops may generate other weird problems. You can read more -about it e.g., from Ground loop in Wikipedia -. +If you use unisolated tranceiver like MCP2562, you may cause ground loop in your boat. Ground loops may generate other weird problems. You can read more about it e.g., from Ground loop in Wikipedia . If you e.g.,feed NMEA2000 bus on center of the boat and you have unisolated device, which also has ground by sensor on front of the boat, you have created ground loop. It may work without problems or may not. You may have communication errors etc. @@ -126,7 +118,7 @@ outside sources (EMI, ESD, electrical transients, etc.). [MCHP 2562 Datasheet](http://ww1.microchip.com/downloads/en/devicedoc/20005167c.pdf) -#### Isolated transceiver {subsubIso} +#### Isolated transceiver {#subsubIso} Isolated tranceiver has either optical or galvanic (ISO1050) isolation. Those has to be powered from both sides with isolated power, so you need also at least two power supplies. @@ -246,7 +238,7 @@ even variable. If you are interested, dig more information from internet. NMEA2000 bus is like ethernet so that you can have multiple devices on same bus, they all can send information to the bus and there is no bus master device. The biggest difference to traditional NMEA0183 connection -is that only one device can send data. +is that on NMEA0183 only one device can send data. - [NMEA_2000](https://en.wikipedia.org/wiki/NMEA_2000) - [SAE_J1939](https://en.wikipedia.org/wiki/SAE_J1939) diff --git a/Documents/src/4_gettingStarted.md b/Documents/src/4_gettingStarted.md index 9f08f86e..9100eb70 100644 --- a/Documents/src/4_gettingStarted.md +++ b/Documents/src/4_gettingStarted.md @@ -1,69 +1,79 @@ # Get your Project Started {#getStarted} \tableofcontents - @brief A short introduction how to get started \section secMem Memory requirements -I have tried to measure memory used by library, but it is not so simple, since -there are some automated operations. With version 11.06.2017 I got results: +Roughly you need at last 8 kB ram and 40 kB ROM to fullfill all required NMEA2000 features with your own logic. Even requirements can be squeezed I do not prefer to do that to avoid unnecessary issues. + +With version 11.06.2017 I measured and got results: - Approximate ROM 26.9 kB - Approximate RAM 3.4 kB -This is with simple TemperatureMonitor example. This can be squeezed by +This was with simple TemperatureMonitor example. This can be squeezed by setting: - Add below to setup() before NMEA2000.Open(); -.... - NMEA2000.SetN2kCANMsgBufSize(2); - NMEA2000.SetN2kCANSendFrameBufSize(15); -.... +```shell + NMEA2000.SetN2kCANMsgBufSize(2); // This may cause loss of received fast packet messages. + NMEA2000.SetN2kCANSendFrameBufSize(15); // This may cause loss of important information to other bus devices. +``` - Defining ProductInformation to PROGMEM as in BatteryMonitor example. - Disabling all extra features. See NMEA2000_CompilerDefns.h - Disable interrupt receiving. With those setting you can go down to appr. 19 kB ROM and 1.9 kB RAM. So for 2 -kB devices like Arduino Uno, there is not much for your own code. +kB RAM devices like Arduino Uno, there is not much for your own code. \warning By squeezing memory, library can not fulfill certification requirements anymore. \section secHWSet Hardware setup -NMEA2000 is inherited from CAN. Many MCUs like Teensy >3.1, ESP32, Arduino Due has already -CAN controller inside. If your MCU does not have CAN controller inside or you need second +NMEA2000 is inherited from CAN. Many MCUs like Teensy >3.1, ESP32, Arduino Due has internal +CAN controller. If your MCU does not have internal CAN controller or you need second external CAN controller, you can use e.g. MCP2515 CAN controller, which is supported by library (mcp_can). For final connection to the bus you need CAN bus_transceiver chip. Devices on NMEA2000 -bus should be isolated to avoid ground loops. So if you take power from NMEA2000 -bus and your device is not connected to ground enywhere else, you can use unisolated tranceiver +bus should be isolated to avoid ground loops. If you take power from NMEA2000 +bus and your device is not connected to ground anywhere else, you can use unisolated tranceiver like MCP2551, MCP2562 or SN65HVD234. If you instead feed power to your device directly or e.g. use engine own sensors for measuring, -you have to use isolated tranceivers like ISO1050. Remember also use isolated power supply, if you take power -from bus and have any unisolated connection to anywhere on your whole system. +you have to use isolated tranceivers like ISO1050. Remember also use isolated power supply, if you take power from bus and have any unisolated connection to anywhere on your whole system. Easiest for connecting to NMEA2000 bus is to use some ready shield. For more information on how to wire everything to the bus please see \ref pageHWSetUp ## Breakout Boards -### Teensy 3.2 +I prefer isolated connection NMEA2000 bus. See more \ref subsubIso. + +For beginner simplest board would be board with MCU (like ESP32 or Teensy 4.0) with isolated transceiver. Unfortunately I have found only one Teensy 4.0 board with unisolated tranceiver. Next simplest is breakout board that fits directly to main board pins, but even those does not exist isolated. But it is not much work to connect 4 wires and use existing isolated board. + + +### Isolated breakout board -- +This can be used with any main board having internal CAN controller like Teensy 4.0, 4.1 (or 3.2, 3.5, 3.6 which are at end of life), ESP32 Arduino DUE boards. -### ESP32 +- **isolated** -- +### Teensy 4.0, 4.1 + +- **unisolated** + +### Teensy 4.0 + +- **unisolated** ### Arduino Due -- +- **unisolated** ### Arduino Mega -- +- **unisolated** Note that there are several different shields for CAN bus available and others may use 8 MHz chrystal instead of **default 16 MHz chrystal**. This must be set before including NMEA2000_CAN.h @@ -71,30 +81,31 @@ Note that there are several different shields for CAN bus available and others m ## Schematics for standalone CAN transceiver In case you build your tranceiver connection by yourself there are some connection examples -under [documents](https://github.com/ttlappalainen/NMEA2000/tree/master/Documents). +under [documents](https://github.com/ttlappalainen/NMEA2000/tree/master/Documents/Schematics). ### Teensy 3.2 -- [Teensy_Actisense_listener_sender_schematics.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Examples/TeensyActisenseListenerSender/Documents/Teensy_Actisense_listener_sender_schematics.pdf) +- \ref subTEiso +- \ref subTEunIso **unisolated** ### Arduino Due -- [ArduinoDUE_CAN_with_MCP2562.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/ArduinoDUE_CAN_with_MCP2562.pdf) -- [ArduinoDue_CAN_with_SN65HVD234.jpg](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/ArduinoDue_CAN_with_SN65HVD234.jpg) +- [ArduinoDUE_CAN_with_MCP2562.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/Schematics/ArduinoDUE_CAN_with_MCP2562.pdf) **unisolated** +- [ArduinoDue_CAN_with_SN65HVD234.jpg](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/Schematics/ArduinoDue_CAN_with_SN65HVD234.jpg) **unisolated** ### Arduino Mega -- [ArduinoMega_CAN_with_MCP2515_MCP2551.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/ArduinoMega_CAN_with_MCP2515_MCP2551.pdf) +- [ArduinoMega_CAN_with_MCP2515_MCP2551.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/Schematics/ArduinoMega_CAN_with_MCP2515_MCP2551.pdf) **unisolated** ### ATmegaxxM1 -- [ATmegaxxM1 CAN example.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/ATmegaxxM1%20CAN%20example.pdf) +- [ATmegaxxM1 CAN example.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/Schematics/ATmegaxxM1%20CAN%20example.pdf) **unisolated** Library has been also used with Maple Mini board. \section secHWlib Hardware depended libraries -You need at least Arduino Software 1.6.6 for this sample. I'll expect you are +You need at least Arduino Software 1.8.19 for this sample. I'll expect you are familiar with Arduino and using libraries. When your Arduino environment is ready. @@ -104,18 +115,19 @@ ready. @note Take care that you use libraries under my Github, when available! Others may not work right with NMEA2000! -### Teensy 4.0/4.1 boards with internal CAN +### Teensy 4.0/4.1 boards with internal CAN {#subT4Libraries} - [NMEA2000_Teensyx](https://github.com/ttlappalainen/NMEA2000_Teensyx) library. - Remember also install [Teensyduino](https://www.pjrc.com/teensy/td_download.html) ! CAN library is included to the code so you do not need any extra CAN library with this. NMEA2000_Teensyx library will replace NMEA2000_teensy library in future. You can already start to use it with -all Teensy boards by forcing it with define (see NMEA2000_CAN.h comment). For critical -projects I prefer to use old library until this has been running under tests for a while. +all Teensy boards by forcing it with define (see NMEA2000_CAN.h comment). ### Teensy 3.1/3.2 or 3.5/3.6 board with internal CAN +I prefer to move to use libraries as \ref subT4Libraries and force it by define. Old libraries are still as default. + - [NMEA2000_teensy](https://github.com/ttlappalainen/NMEA2000_teensy) library. - [FlexCAN](https://github.com/ttlappalainen/FlexCAN_Library) library. - Remember also install [Teensyduino](https://www.pjrc.com/teensy/td_download.html) ! @@ -171,7 +183,7 @@ other related libraries. See origin for MBED port on -There is a document [Preparing your Raspberry Pi for the NMEA2000 library.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/Preparing%20your%20Raspberry%20Pi%20for%20the%20NMEA2000%20library.pdf) for starting up with RPi. +There is a document [Preparing your Raspberry Pi for the NMEA2000 library.pdf](https://github.com/ttlappalainen/NMEA2000/blob/master/Documents/Pdf/Preparing%20your%20Raspberry%20Pi%20for%20the%20NMEA2000%20library.pdf) for starting up with RPi. Hopefully I have time to write more complete document. There is example NMEA2000ToNMEA0183, which has been tested with RPi 3B. @@ -193,9 +205,7 @@ sends it to PC. `NMEA2000/Examples/ArduinoGateway` allows you to mimic Actisense NGT-1 and connect e.g. a Raspberry Pi running Signal-K to the NMEA2000 bus with an Arduino or Teensy. -# Forcing CAN "driver" - -was using Arduino Software older than 1.6.6) +# Forcing CAN board dependent "driver" In examples there are simple includes: @@ -204,10 +214,9 @@ In examples there are simple includes: #include // This will automatically choose right CAN library and create suitable NMEA2000 object ``` -If that can not be used (like with Arduino IDE older than 1.6.6) or you would like to control naming and used "driver", -you can manually include necessary files. Specially if you want to use secondary CAN bus on your system. +If above can not be used (like with Arduino IDE older than 1.6.6) or you would like to control naming and used "driver", you can manually include necessary files. Specially you need that, if you want to use secondary CAN bus on your system. -## For use with Teensy 4.x (also with 3.1/3.2/3.5/3.6) +## For use with Teensy 4.x (also with end of life boards 3.1/3.2/3.5/3.6) Your file should start with: @@ -239,6 +248,8 @@ Your file should start with: ```cpp #include #include + #define ESP32_CAN_TX_PIN GPIO_NUM_16 + #define ESP32_CAN_RX_PIN GPIO_NUM_4 #include // https://github.com/ttlappalainen/NMEA2000_esp32 // tNMEA2000_esp32 NMEA2000; diff --git a/Documents/src/5_supportedMsg.md b/Documents/src/5_supportedMsg.md index e3fcba68..f75c567c 100644 --- a/Documents/src/5_supportedMsg.md +++ b/Documents/src/5_supportedMsg.md @@ -1,68 +1,69 @@ # List of supported NMEA2000 PGNs {#listMsg} -This list gives a short overview of all supported NMEA2000 PGNs. The most of these functions are provided in ef N2kMessages.h . +This list gives a short overview of all supported NMEA2000 PGNs. The most of these functions are provided in +ef N2kMessages.h . E.g., functions for Maretron proprietary messages has been declared in N2kMaretron.h . If message you need is not listed and not in N2kMessages.h, you can create your own module and write setter/parser functions. Please do not try to do PR, before you have tested your functions with orther device supporting those functions. -| PGN | Set | Parse |: Description of the PGN | +| PGN | Set | Parse | Description of the PGN | |--------|:-----:|:-----:|----------| -| 59392 | x | | ISO Acknowledgment | -| 59904 | x | x | ISO Request | -| 60928 | x | | ISO Address Claim | -| 126464 | x | | PGN List - Received PGNs group function | -| 126992 | x | x | System Time | -| 126993 | x | | Heartbeat | -| 126996 | x | x | Product Information | -| 126998 | x | x | Configuration Information | -| 127233 | x | x | Man Overboard Notification(MOB) | -| 127237 | x | x | Heading/Track Control | -| 127245 | x | x | Rudder | -| 127250 | x | x | Vessel Heading | -| 127251 | x | x | Rate of Turn | -| 127252 | x | x | Heave | -| 127257 | x | x | Attitude | -| 127258 | x | x | Magnetic Variation | -| 127488 | x | x | Engine Parameters, Rapid Update | -| 127489 | x | x | Engine Parameters, Dynamic | -| 127493 | x | x | Transmission Parameters, Dynamic | -| 127497 | x | x | Trip Fuel Consumption, Engine | -| 127501 | x | x | Binary Status Report | -| 127505 | x | x | Fluid Level | -| 127506 | x | x | DC Detailed Status | -| 127507 | x | x | Charger Status- DEPRECATED | -| 127508 | x | x | Battery Status | -| 127513 | x | x | Battery Configuration Status | -| 128000 | x | x | Nautical Leeway Angle PGN: | -| 128259 | x | x | Speed, Water Referenced | -| 128267 | x | x | Water Depth | -| 128275 | x | x | Distance Log | -| 128776 | x | x | Windlass Control Status PGN: | -| 128777 | x | x | Anchor Windlass Operating Status PGN: | -| 128778 | x | x | Anchor Windlass Monitoring Status PGN: | -| 129025 | x | x | Position, Rapid Update | -| 129026 | x | x | COG & SOG, Rapid Update | -| 129029 | x | x | GNSS Position Data | -| 129033 | x | x | Local Time Offset | -| 129038 | x | x | AIS Class A Position Report | -| 129039 | x | x | AIS Class B Position Report | -| 129041 | x | x | AIS Aids to Navigation (AtoN) Report | -| 129283 | x | x | Cross Track Error | -| 129284 | x | x | Navigation Data | +| 59392 | \ref SetN2kPGN59392 "x" | | ISO Acknowledgment. See \ref descSystemMessages. | +| 59904 | \ref SetN2kPGN59904 "x" | \ref ParseN2kPGN59904 "x" | ISO Request. See \ref descSystemMessages. | +| 60928 | \ref SetN2kPGN60928 "x" | | ISO Address Claim. See \ref descSystemMessages. | +| 126464 | \ref SetN2kPGN126464 "x" | | Transmit/Receive PGN List. See \ref descSystemMessages. | +| 126992 | \ref SetN2kPGN126992 "x" | \ref ParseN2kPGN126992 "x" | System Time | +| 126993 | \ref SetN2kPGN126993 "x" | | Heartbeat. See \ref descSystemMessages. | +| 126996 | \ref SetN2kPGN126996 "x" | \ref ParseN2kPGN126996 "x" | Product Information. See \ref descSystemMessages. | +| 126998 | \ref SetN2kPGN126998 "x" | \ref ParseN2kPGN126998 "x" | Configuration Information. See \ref descSystemMessages. | +| 127233 | \ref SetN2kPGN127233 "x" | \ref ParseN2kPGN127233 "x" | Man Overboard Notification(MOB) | +| 127237 | \ref SetN2kPGN127237 "x" | \ref ParseN2kPGN127237 "x" | Heading/Track Control | +| 127245 | \ref SetN2kPGN127245 "x" | \ref ParseN2kPGN127245 "x" | Rudder | +| 127250 | \ref SetN2kPGN127250 "x" | \ref ParseN2kPGN127250 "x" | Vessel Heading | +| 127251 | \ref SetN2kPGN127251 "x" | \ref ParseN2kPGN127251 "x" | Rate of Turn | +| 127252 | \ref SetN2kPGN127252 "x" | \ref ParseN2kPGN127252 "x" | Heave | +| 127257 | \ref SetN2kPGN127257 "x" | \ref ParseN2kPGN127257 "x" | Attitude | +| 127258 | \ref SetN2kPGN127258 "x" | \ref ParseN2kPGN127258 "x" | Magnetic Variation | +| 127488 | \ref SetN2kPGN127488 "x" | \ref ParseN2kPGN127488 "x" | Engine Parameters, Rapid Update | +| 127489 | \ref SetN2kPGN127489 "x" | \ref ParseN2kPGN127489 "x" | Engine Parameters, Dynamic | +| 127493 | \ref SetN2kPGN127493 "x" | \ref ParseN2kPGN127493 "x" | Transmission Parameters, Dynamic | +| 127497 | \ref SetN2kPGN127497 "x" | \ref ParseN2kPGN127497 "x" | Trip Fuel Consumption, Engine | +| 127501 | \ref SetN2kPGN127501 "x" | \ref ParseN2kPGN127501 "x" | Binary Status Report | +| 127505 | \ref SetN2kPGN127505 "x" | \ref ParseN2kPGN127505 "x" | Fluid Level | +| 127506 | \ref SetN2kPGN127506 "x" | \ref ParseN2kPGN127506 "x" | DC Detailed Status | +| 127507 | \ref SetN2kPGN127507 "x" | \ref ParseN2kPGN127507 "x" | Charger Status- DEPRECATED | +| 127508 | \ref SetN2kPGN127508 "x" | \ref ParseN2kPGN127508 "x" | Battery Status | +| 127513 | \ref SetN2kPGN127513 "x" | \ref ParseN2kPGN127513 "x" | Battery Configuration Status | +| 128000 | \ref SetN2kPGN128000 "x" | \ref ParseN2kPGN128000 "x" | Nautical Leeway Angle PGN: | +| 128259 | \ref SetN2kPGN128259 "x" | \ref ParseN2kPGN128259 "x" | Speed, Water Referenced | +| 128267 | \ref SetN2kPGN128267 "x" | \ref ParseN2kPGN128267 "x" | Water Depth | +| 128275 | \ref SetN2kPGN128275 "x" | \ref ParseN2kPGN128275 "x" | Distance Log | +| 128776 | \ref SetN2kPGN128776 "x" | \ref ParseN2kPGN128776 "x" | Windlass Control Status PGN: | +| 128777 | \ref SetN2kPGN128777 "x" | \ref ParseN2kPGN128777 "x" | Anchor Windlass Operating Status PGN: | +| 128778 | \ref SetN2kPGN128778 "x" | \ref ParseN2kPGN128778 "x" | Anchor Windlass Monitoring Status PGN: | +| 129025 | \ref SetN2kPGN129025 "x" | \ref ParseN2kPGN129025 "x" | Position, Rapid Update | +| 129026 | \ref SetN2kPGN129026 "x" | \ref ParseN2kPGN129026 "x" | COG & SOG, Rapid Update | +| 129029 | \ref SetN2kPGN129029 "x" | \ref ParseN2kPGN129029 "x" | GNSS Position Data | +| 129033 | \ref SetN2kPGN129033 "x" | \ref ParseN2kPGN129033 "x" | Local Time Offset | +| 129038 | \ref SetN2kPGN129038 "x" | \ref ParseN2kPGN129038 "x" | AIS Class A Position Report | +| 129039 | \ref SetN2kPGN129039 "x" | \ref ParseN2kPGN129039 "x" | AIS Class B Position Report | +| 129041 | \ref SetN2kPGN129041 "x" | \ref ParseN2kPGN129041 "x" | AIS Aids to Navigation (AtoN) Report | +| 129283 | \ref SetN2kPGN129283 "x" | \ref ParseN2kPGN129283 "x" | Cross Track Error | +| 129284 | \ref SetN2kPGN129284 "x" | \ref ParseN2kPGN129284 "x" | Navigation Data | | 129285 | x | | Navigation - Route/WP information | -| 129539 | x | x | GNSS DOPs | -| 129540 | x | x | GNSS Sats in View | -| 129794 | x | x | AIS Class A Static and Voyage Related Data | -| 129802 | x | x | AIS Safety Related Broadcast Message | -| 129809 | x | x | AIS Class B "CS" Static Data Report, Part A | -| 129810 | x | x | AIS Class B "CS" Static Data Report, Part B | +| 129539 | \ref SetN2kPGN129539 "x" | \ref ParseN2kPGN129539 "x" | GNSS DOPs | +| 129540 | \ref SetN2kPGN129540 "x" | \ref ParseN2kPGN129540 "x" | GNSS Sats in View | +| 129794 | \ref SetN2kPGN129794 "x" | \ref ParseN2kPGN129794 "x" | AIS Class A Static and Voyage Related Data | +| 129802 | \ref SetN2kPGN129802 "x" | \ref ParseN2kPGN129802 "x" | AIS Safety Related Broadcast Message | +| 129809 | \ref SetN2kPGN129809 "x" | \ref ParseN2kPGN129809 "x" | AIS Class B "CS" Static Data Report, Part A | +| 129810 | \ref SetN2kPGN129810 "x" | \ref ParseN2kPGN129810 "x" | AIS Class B "CS" Static Data Report, Part B | | 130074 | x | | Route and WP Service - WP List - WP Name & Position | -| 130306 | x | x | Wind Data | -| 130310 | x | x | Environmental Parameters - DEPRECATED | -| 130311 | x | x | Environmental Parameters- DEPRECATED | -| 130312 | x | x | Temperature - DEPRECATED | -| 130313 | x | x | Humidity | -| 130314 | x | x | Actual Pressure | +| 130306 | \ref SetN2kPGN130306 "x" | \ref ParseN2kPGN130306 "x" | Wind Data | +| 130310 | \ref SetN2kPGN130310 "x" | \ref ParseN2kPGN130310 "x" | Environmental Parameters - DEPRECATED | +| 130311 | \ref SetN2kPGN130311 "x" | \ref ParseN2kPGN130311 "x" | Environmental Parameters- DEPRECATED | +| 130312 | \ref SetN2kPGN130312 "x" | \ref ParseN2kPGN130312 "x" | Temperature - DEPRECATED | +| 130313 | \ref SetN2kPGN130313 "x" | \ref ParseN2kPGN130313 "x" | Humidity | +| 130314 | \ref SetN2kPGN130314 "x" | \ref ParseN2kPGN130314 "x" | Actual Pressure | | 130315 | x | | Set Pressure | -| 130316 | x | x | Temperature, Extended Range | -| 130323 | x | x | Meteorological Station Data | -| 130576 | x | x | Trim Tab Status | -| 130577 | x | x | Direction Data | -| 130823 | x | | - | +| 130316 | \ref SetN2kPGN130316 "x" | \ref ParseN2kPGN130316 "x" | Temperature, Extended Range | +| 130323 | \ref SetN2kPGN130323 "x" | \ref ParseN2kPGN130323 "x" | Meteorological Station Data | +| 130576 | \ref SetN2kPGN130576 "x" | \ref ParseN2kPGN130576 "x" | Trim Tab Status | +| 130577 | \ref SetN2kPGN130577 "x" | \ref ParseN2kPGN130577 "x" | Direction Data | +| 130823 | \ref SetN2kMaretronPGN130823 "x" | \ref ParseN2kMaretronPGN130823 "x" | Maretron Temperature High Range | diff --git a/Documents/src/7_glossary.md b/Documents/src/7_glossary.md index 89071fad..f523b1dd 100644 --- a/Documents/src/7_glossary.md +++ b/Documents/src/7_glossary.md @@ -2,6 +2,29 @@ \tableofcontents +## NAME {#secRefTermNAME} + +On NMEA2000 NAME (written all capital) means data defined by device information. Since device information will be sent by PGN 60928, NAME is also 8 byte content of than message. NAME can be used to identify devices sending some information. For this reason it is important that NAME is unique for all devices on the bus. + +Normally unique number and manufacturer code within device information should be enough to define unique device. Some manufactures does not do that and their devices may require modification for device instance when same devices appears on the bus. + +Safest way to fullfill unique NAME requirement is to keep unique number unique. For commercial production that requires some kind of register for manufactured devices. + +On library you set device information by using function tNMEA2000::SetDeviceInformation and if necessary with function tNMEA2000::SetDeviceInformationInstances. + +## Address claiming {#secRefTermAddressClaiming} + +NMEA2000 bus can have maximum 252 devices. Each device will get device source address (0-251), which +can be predefined on device start, but may be changed by address claiming at any time. + +On start device starts address claiming using previously saved source address by sending its \ref secRefTermNAME to the bus by using message ISO address claim PGN 60928. If there is no other device using same source address, device can start normal operation after 250 ms delay. If there is another device using same address there are two possible cases. +1. Other device NAME has lower priority, so it will increment its own address and start address claiming. This device can keep its source address. +2. Other device NAME has higher priority and responds with ISO address claim. This device will increment its source address and start address claiming again with new address. + +If bus is full of devices, devices with lowest priority will get source address 254 and they can not send anything to bus. + +Library takes care of address claiming and required silence delay automatically. To get information possible source address changes, use funtion tNMEA2000::ReadResetAddressChanged(). + ## NMEA2000 instances Instances are used in an NMEA 2000 network to identify multiple similar products connected on the same network. @@ -10,33 +33,104 @@ As an example, take a system with two battery monitors (one for the main battery ### Different types of instances -There various types of instances, and for marine systems are two that matter: the **Device instance**, **Data instance** and **System instance**. Device and System instance is stored in tNMEA2000::tDeviceInformation. +There are various types of instances: **Device instance**, **Data instance** and **System instance**. Device and System instance is stored in tNMEA2000::tDeviceInformation and so they are also part of \ref secRefTermNAME. See also tNMEA2000::SetDeviceInformationInstances. #### Device instance -The device instance is sent in PGN 60928, ISO Address Claim, as a combined field of Device Instance Lower (ISO ECU Instance) and Device Instance Upper (ISO Function Instance). The Device instance is e.G used by Victron chargers (Skylla-i/-IP44, VE.Can MPPTs) to configure them in the same group and synchronize them. +The device instance is sent in PGN 60928, ISO Address Claim, as a combined field of Device Instance Lower (ISO ECU Instance) and Device Instance Upper (ISO Function Instance). The Device instance is e.g., used by Victron chargers (Skylla-i/-IP44, VE.Can MPPTs) to configure them in the same group and synchronize them. #### Data instances -These instances belong to data on the bus (e.G. Battery Instance, DC Detailed Instance, Switch bank instance, etc.) and are embedded in the different PGN’s. For changing these instances through a complex write, PGN 126208, Complex Request Group Function Code 5, write fields. +These instances belong to data on the bus (e.g., Battery Instance, DC Detailed Instance, Switch bank instance, etc.) and are embedded in the different PGN’s. For changing these instances through a complex write, PGN 126208, Complex Request Group Function Code 5, write fields. #### System instance -The system instance is also sent in PGN 60928, field 8. +The system instance is also sent in PGN 60928, field 8. System instance indicates device occurence in other like redundant or parallel NMEA2000 networks. For small and simple vessels this is always 0. \sa - [Victron Technical-Information-Data-communication](https://www.victronenergy.com/upload/documents/Technical-Information-Data-communication-with-Victron-Energy-products_EN.pdf) - [Victron changing NMEA2000 Instances](https://www.victronenergy.com/live/ve.can:changing_nmea2000_instances) -## Sequence ID +## SID {#secRefTermSID} + +The sequence identifier field is used to tie different PGNs data together to same sampling or calculation time. In other words same SID in different PGNs sent by same device defines that values on PGN:s has been sampled or calculated at same time. Devices reading those messages can use in calculations PGNs data provided with same SID and get more accurate results. + +For example, the GPS200 will transmit identical SIDs for 126992 (System Time), 128259 (Speed), 129026 (COG and SOG, Rapid Update), 129029 (GNSS Position Data), 129539 (GNSS DOPs), and 129540 (GNSS Satellites in View) to indicate that the readings are linked together (i.e., the data from each PGN was taken at the same time although they are reported at slightly different times). + +E.g., with temperature data I do not see any use for SID. Temperature changes are +normally anyway slow and 1.5-2 s difference on sampling does not have meaningfull effect. +I would also think that there is no device using SID for temperature, pressure and humidity data. + +On sending in most cases you can use just 0xff for SID. On receiving you can normally just forget it. -SID – The sequence identifier field is used to tie related PGNs together. For example, the GPS200 will transmit identical SIDs for 126992 (System Time), 128259 (Speed), 129026 (COG and SOG, Rapid Update), 129029 (GNSS Position Data), 129539 (GNSS DOPs), and 129540 (GNSS Satellites in View) to indicate that the readings are linked together (i.e., the data from each PGN was taken at the same time although they are reported at slightly different times). +If you like to use SID, you have to increase value synchronized with sampling and sending. SID value +has to be on range 0-252. 255 (0xff) means data not available and 253-254 are reserved. +So use it e.g., with code +``` SensorSID++; if ( SensorSID>252) SensorSID=0;``` +If you e.g., sample your multisensor every 2 s, +but PGNs will be sent every 1 s you can increase SID after each sampling and there would be +2 sends having same SID indicating that they have been sampled at same time. +If you instead sample faster than send, you have to increase SID after all related messages +has been sent. It would be even more complex if your devices a lot different messages and their +sampling is grouped and requires different SID. Then you have to also take care that messages +which are not linked to each other never has same SID. -## Manufacturer Code +If you use multitasking system, you should also lock data +during sampling and sending so that they would not change during task. If you e.g., +have task sending sensor values from some kind of globals, both task should use some +data locking system: -The Manufacturer Code is part of the tNMEA2000::tDeviceInformation which is mandatory for each NMEA2000 device. -[List of all Manufacturer Codes](https://www.nmea.org/Assets/20190623%20manu%20code%20and%20product%20code.pdf) +Sampling task: + +```shell +SampleSensors(Sensor1,Sensor2); +LockSend(); +Sensor1Out=Sensor1; +Sensor2Out=Sensor2; +SensorsSID++; if ( SensorsSID>252 ) SensorsSID=0; +ReleaseSend(); +``` + +Sending task: + +```shell +LockSend(); +double S1=Sensor1Out; +double S2=Sensor2Out; +SID=SensorsSID; +ReleaseSend(); +SendSensorsData(SID,S1,S2); +``` + +## Manufacturer Code {#secRefTermManufacturerCode} + +The Manufacturer Code is part of the \ref secRefTermNAME (see tNMEA2000::tDeviceInformation). Manufacturer code is mandatory for each NMEA2000 device and it has to be requested from NMEA organization. + +Note that NMEA2000 devices does not have way to request manufacturer name. Manufacturer code is link to hardcoded name. So if you have old MFD and sersor from new manufacturer, sensor will be listed with name "unknown manufacturer". + +Some manufacturers hardcodes which manufacturer sensors they accept. So in case e.g., MFD document claims to support e.g., PGN 130316, but sensor data will not be shown or not shown properly, check your MFD manufacturer that your sensor manufacturer is listed in their database. As opposite if you make device for your own vessel only, you can setup your device to use accepted manufacturer code. + +\ref secRefMfgCodes + +## NMEA2000 certification {#secRefNMEA2000Certification} + +I have advertised library to be certification ready. There are some functionalities left for developer, since there is no common way do that. Good example is saving possibly changed source address or device/system instances. It is developer responsibility to choose method for saving. It can be e.g., EEPROM, file, flash. To fullfill all certification requirements you have to add some functionality. +- Your device has to be electrically isolated as I have descibed on \ref pageHWSetUp. +- Save device source address and restore it on startup by using saved value on tNMEA2000::SetMode(). Track possible changes by using function tNMEA2000::ReadResetAddressChanged(). +- Save device and system instances and restore them on startup with function tNMEA2000::SetDeviceInformationInstances().Track possible changes by using function tNMEA2000::ReadResetDeviceInformationChanged(). +- Write ISO request handler to respond requests for all PGNs you are transmitting. Register handler with tNMEA2000::SetISORqstHandler(). +- Inherit tN2kGroupFunctionHandler and write handler, which responds all messages your device is transmitting. You can write own handler for all your messages or write common handler. See N2kGroupFunction.h. Note that if you accept message period or offset change, you should also save them and restore them on startup. Also if you handle PGN data instance change, you need to save that too. +- Save both installation descriptions and restore them on startup with function tNMEA2000::SetConfigurationInformation(). Track possible changes by using function tNMEA2000::ReadResetInstallationDescriptionChanged(). + +For commercial certified devices you need also (prices at 2024 are for members): +- Join as member to NMEA organization - new member 475 $, yearly renewal 300 $. +- Request \ref secRefTermManufacturerCode from NMEA organization - 1200 $. +- Request ProductCode from NMEA organization - 450 $. +- Run certification tests for you device. For that you need specific certification tool. You can ask help from me. Costs depends of certification test provider - I know some providers. Costs 500 $ - 2000 $. +- Certification verification - 850 $. + +So total costs for certified device for new member is about 4000 $. ## Relation between CAN ID and NMEA2000 @@ -53,3 +147,208 @@ The SAE J1939 protocol requires a specific format for the CAN message’s identi \sa [J1939 PGN vs. 29-Bit CAN ID - Online Converter](https://www.csselectronics.com/pages/j1939-pgn-conversion-tool) + +## List of registered manufacturer codes {#secRefMfgCodes} + +| Code | Manufacturer name | +|--------|--------| +| 78 | Fw Murphy | +| 80 | Twin Disc | +| 85 | Kohler Power Systems | +| 88 | Hemisphere | +| 116 | BEP Marine | +| 135 | Airmar | +| 137 | Maretron | +| 140 | Lowrance | +| 144 | Mercury Marine | +| 147 | Nautibus Electronic Gmbh | +| 148 | Blue Water Data | +| 154 | Westerbeke | +| 161 | Offshore Systems UK | +| 163 | Evinrude/Brp Bombardier | +| 165 | CPAC Systems Ab | +| 168 | Xantrex Technology | +| 172 | Yanmar Marine | +| 174 | Ab Volvo/Volvo Penta | +| 176 | Carling Technologies | +| 185 | Beede Electrical | +| 192 | Floscan Instrument Co., Inc. | +| 193 | Nobeltec | +| 198 | Mystic Valley Communications | +| 199 | Actia Corporation | +| 201 | Disenos Y Technologia | +| 211 | Digital Switching Systems | +| 215 | Xintex/Atena | +| 224 | Emmi Network | +| 228 | Zf Marine Electronics | +| 229 | Garmin | +| 233 | Yacht Monitoring Solutions | +| 235 | Sailormade Marine Telemetry | +| 243 | Eride | +| 257 | Honda Motor Company | +| 272 | Groco | +| 273 | Actisense | +| 274 | Amphenol Ltw Technology | +| 275 | Navico | +| 283 | Hamilton Jet | +| 285 | Sea Recovery | +| 286 | Coelmo Srl Italy | +| 295 | BEP Marine | +| 299 | Garmin | +| 304 | Trigentic/EmpirBus | +| 305 | Novatel | +| 306 | Sleipner Motor As | +| 307 | Mbw Technologies | +| 315 | ICOM | +| 328 | Qwerty | +| 329 | Dief | +| 341 | Böning Automationstechnologie GmbH | +| 345 | Korea Maritime University | +| 351 | Thrane And Thrane | +| 355 | Mastervolt | +| 356 | Fischer Panda Generators | +| 358 | Victron Energy | +| 370 | Rolls Royce Marine | +| 373 | Electronic Design | +| 374 | Northern Lights | +| 378 | Glendinning | +| 381 | B&G | +| 384 | Rose Point Navigation Systems | +| 385 | Johnson Outdoors Marine Electronics | +| 394 | Capi 2 | +| 396 | Beyond Measure | +| 400 | Livorsi Marine | +| 404 | ComNav | +| 419 | Fusion Electronics | +| 421 | Standard Horizon | +| 422 | True Heading | +| 426 | Egersund Marine Electronics As | +| 427 | Em-Trak Marine Electronics Ltd | +| 431 | Tohatsu Co Jp | +| 437 | Digital Yacht | +| 438 | Comar Systems Limited | +| 440 | Cummins | +| 443 | VDO | +| 451 | Parker Hannifin | +| 459 | Alltek Marine Electronics Corp | +| 460 | San Giorgio S.E.I.N. | +| 466 | Veethree Electronics | +| 467 | Humminbird Marine Electronics | +| 470 | SI-TEX Marine Electronics | +| 471 | Sea Cross Marine Ab | +| 475 | GME/Standard Communications | +| 476 | Humminbird Marine Electronics | +| 478 | Ocean Sat Bv | +| 481 | Chetco Digitial Instruments | +| 493 | Watcheye | +| 499 | Lcj Capteurs | +| 502 | Attwood Marine | +| 503 | Naviop S.R.L. | +| 504 | Vesper Marine | +| 510 | Marinesoft Co. LTD | +| 517 | NoLand Engineering | +| 518 | Transas USA | +| 529 | National Instruments Korea | +| 532 | Onwa Marine | +| 540 | Webasto | +| 571 | Marinecraft Co. | +| 573 | McMurdo Group | +| 578 | Advansea | +| 579 | KVH | +| 580 | San Jose Technology | +| 583 | Yacht Control | +| 586 | Suzuki Motor Corporation | +| 591 | USCG | +| 595 | ShipModul | +| 600 | Aquatic AV | +| 605 | Aventics GmbH | +| 606 | Intellian | +| 612 | SamwonIT | +| 614 | Arlt Tecnologies | +| 637 | Bavaria Yacts | +| 641 | Diverse Yacht Services | +| 644 | KUS Manufacturer | +| 645 | Garmin | +| 658 | Shenzhen Jiuzhou Himunication | +| 688 | Rockford Corporation | +| 704 | JL Audio | +| 715 | Autonnic | +| 717 | Yacht Devices | +| 734 | REAP Systems | +| 735 | Au Electronics Group | +| 739 | LxNav | +| 740 | JL Audio | +| 743 | DaeMyung Elevator | +| 744 | Woosung | +| 773 | Clarion US | +| 776 | HMI Systems | +| 777 | Ocean Signal | +| 778 | Seekeeper | +| 781 | Poly Planar | +| 785 | Fischer Panda DE | +| 795 | Broyda Industries | +| 796 | Canadian Automotive | +| 797 | Tides Marine | +| 798 | Lumishore | +| 799 | Still Water Designs and Audto | +| 802 | SPBI SA Ets BJTechnologie | +| 803 | Gill Sensors | +| 811 | Blue Water Desalination | +| 815 | Flir Systems | +| 824 | Undheim Systems | +| 838 | TeamSurv | +| 844 | Fell Marine | +| 847 | Oceanvolt | +| 862 | Prospec | +| 868 | Data Panel Corp | +| 890 | L3 Technologies Maritime Systems | +| 894 | Rhodan Marine Systems | +| 896 | Nexfour Solutions | +| 905 | ASA Electronics | +| 909 | Marines Co (South Korea) | +| 911 | Nautic-On, A Brunswick Company | +| 930 | Ecotronix Corp | +| 944 | Zonisa Marine | +| 951 | Exor International S.p.A. | +| 962 | Timbolier Industries | +| 968 | Cox Powertrain | +| 969 | Blue Sea | +| 981 | Kobelt | +| 1008 | Lintest SmartBoat | +| 1011 | Soundmax | +| 1020 | Onyx Marine Automation s.r.l | +| 1021 | Entratech | +| 1022 | ITC Inc. | +| 1023 | PEAK-System Technik GmbH | +| 1029 | The Marine Guardian LLC | +| 1034 | Siren Marine | +| 1047 | Sonic Corporation | +| 1051 | ProNav | +| 1053 | Stillwater Designs / Kicker | +| 1059 | Boatrax | +| 1062 | ComNav | +| 1065 | CALYPSO Instruments | +| 1066 | Spot Zero Water | +| 1070 | Quick-teck Electronics Ltd | +| 1075 | Uniden America | +| 1083 | Nauticoncept | +| 1084 | Shadow-Caster LED lighting LLC | +| 1088 | E-T-A Circuit Breakers | +| 1092 | Scheiber | +| 1095 | Wetsounds | +| 1140 | Across Ocean Systems Ltd. | +| 1305 | Dragonfly Energy | +| 1850 | Teleflex | +| 1851 | Raymarine | +| 1852 | Navionics | +| 1853 | Japan Radio Co | +| 1854 | Northstar Technologies | +| 1855 | Furuno | +| 1856 | Trimble | +| 1857 | Simrad - Navico | +| 1858 | Litton | +| 1859 | Kvasar Ab | +| 1860 | Mmp | +| 1861 | Vector Cantech | +| 1862 | Sanshin Industries/Yamaha Marine | +| 1863 | Faria Instruments | diff --git a/Documents/src/DoxyConf b/Documents/src/DoxyConf index 4ed9a54a..fb549936 100644 --- a/Documents/src/DoxyConf +++ b/Documents/src/DoxyConf @@ -1,4 +1,4 @@ -# Doxyfile 1.9.1 +# Doxyfile 1.10.0 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -12,6 +12,16 @@ # For lists, items can also be appended using: # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (\" \"). +# +# Note: +# +# Use doxygen to compare the used configuration file with the template +# configuration file: +# doxygen -x [configFile] +# Use doxygen to compare the used configuration file with the template +# configuration file without replacing the environment variables or CMake type +# replacement variables: +# doxygen -x_noenv [configFile] #--------------------------------------------------------------------------- # Project related configuration options @@ -53,6 +63,12 @@ PROJECT_BRIEF = "Library to handle NMEA 2000 Communication written in C PROJECT_LOGO = ./images/logo_s.png +# With the PROJECT_ICON tag one can specify an icon that is included in the tabs +# when the HTML document is shown. Doxygen will copy the logo to the output +# directory. + +PROJECT_ICON = + # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is # entered, it will be relative to the location where doxygen was started. If @@ -60,16 +76,28 @@ PROJECT_LOGO = ./images/logo_s.png OUTPUT_DIRECTORY = ../../build/docs -# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- -# directories (in 2 levels) under the output directory of each output format and -# will distribute the generated files over these directories. Enabling this +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 +# sub-directories (in 2 levels) under the output directory of each output format +# and will distribute the generated files over these directories. Enabling this # option can be useful when feeding doxygen a huge amount of source files, where # putting all generated files in the same directory would otherwise causes -# performance problems for the file system. +# performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to +# control the number of sub-directories. # The default value is: NO. CREATE_SUBDIRS = NO +# Controls the number of sub-directories that will be created when +# CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every +# level increment doubles the number of directories, resulting in 4096 +# directories at level 8 which is the default and also the maximum value. The +# sub-directories are organized in 2 levels, the first level always has a fixed +# number of 16 directories. +# Minimum value: 0, maximum value: 8, default value: 8. +# This tag requires that the tag CREATE_SUBDIRS is set to YES. + +CREATE_SUBDIRS_LEVEL = 8 + # If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII # characters to appear in the names of generated files. If set to NO, non-ASCII # characters will be escaped, for example _xE3_x81_x84 will be used for Unicode @@ -81,26 +109,18 @@ ALLOW_UNICODE_NAMES = NO # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. -# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, -# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), -# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, -# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), -# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, -# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, -# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, -# Ukrainian and Vietnamese. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Bulgarian, +# Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English +# (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek, +# Hindi, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with +# English messages), Korean, Korean-en (Korean with English messages), Latvian, +# Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, +# Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, +# Swedish, Turkish, Ukrainian and Vietnamese. # The default value is: English. OUTPUT_LANGUAGE = English -# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all generated output in the proper direction. -# Possible values are: None, LTR, RTL and Context. -# The default value is: None. - -OUTPUT_TEXT_DIRECTION = None - # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. @@ -258,16 +278,16 @@ TAB_SIZE = 4 # the documentation. An alias has the form: # name=value # For example adding -# "sideeffect=@par Side Effects:\n" +# "sideeffect=@par Side Effects:^^" # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading -# "Side Effects:". You can put \n's in the value part of an alias to insert -# newlines (in the resulting output). You can put ^^ in the value part of an -# alias to insert a newline as if a physical newline was in the original file. -# When you need a literal { or } or , in the value part of an alias you have to -# escape them by means of a backslash (\), this can lead to conflicts with the -# commands \{ and \} for these it is advised to use the version @{ and @} or use -# a double escape (\\{ and \\}) +# "Side Effects:". Note that you cannot put \n's in the value part of an alias +# to insert newlines (in the resulting output). You can put ^^ in the value part +# of an alias to insert a newline as if a physical newline was in the original +# file. When you need a literal { or } or , in the value part of an alias you +# have to escape them by means of a backslash (\), this can lead to conflicts +# with the commands \{ and \} for these it is advised to use the version @{ and +# @} or use a double escape (\\{ and \\}) ALIASES = @@ -312,8 +332,8 @@ OPTIMIZE_OUTPUT_SLICE = NO # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and # language is one of the parsers supported by doxygen: IDL, Java, JavaScript, -# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, -# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# Csharp (C#), C, C++, Lex, D, PHP, md (Markdown), Objective-C, Python, Slice, +# VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: # FortranFree, unknown formatted Fortran: Fortran. In the later case the parser # tries to guess whether the code is fixed or free formatted code, this is the # default for Fortran type files). For instance to make doxygen treat .inc files @@ -328,7 +348,7 @@ OPTIMIZE_OUTPUT_SLICE = NO # # Note see also the list of default file extension mappings. -EXTENSION_MAPPING = +EXTENSION_MAPPING = ino=C # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable @@ -349,6 +369,17 @@ MARKDOWN_SUPPORT = YES TOC_INCLUDE_HEADINGS = 5 +# The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to +# generate identifiers for the Markdown headings. Note: Every identifier is +# unique. +# Possible values are: DOXYGEN use a fixed 'autotoc_md' string followed by a +# sequence number starting at 0 and GITHUB use the lower case version of title +# with any whitespace replaced by '-' and punctuation characters removed. +# The default value is: DOXYGEN. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +MARKDOWN_ID_STYLE = DOXYGEN + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or @@ -460,19 +491,27 @@ TYPEDEF_HIDES_STRUCT = NO LOOKUP_CACHE_SIZE = 1 -# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use +# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use # during processing. When set to 0 doxygen will based this on the number of # cores available in the system. You can set it explicitly to a value larger # than 0 to get more control over the balance between CPU load and processing # speed. At this moment only the input processing can be done using multiple # threads. Since this is still an experimental feature the default is set to 1, -# which efficively disables parallel processing. Please report any issues you +# which effectively disables parallel processing. Please report any issues you # encounter. Generating dot graphs in parallel is controlled by the # DOT_NUM_THREADS setting. # Minimum value: 0, maximum value: 32, default value: 1. NUM_PROC_THREADS = 1 +# If the TIMESTAMP tag is set different from NO then each generated page will +# contain the date or date and time when the page was generated. Setting this to +# NO can help when comparing the output of multiple runs. +# Possible values are: YES, NO, DATETIME and DATE. +# The default value is: NO. + +TIMESTAMP = NO + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -554,7 +593,8 @@ HIDE_UNDOC_MEMBERS = NO # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set # to NO, these classes will be included in the various overviews. This option -# has no effect if EXTRACT_ALL is enabled. +# will also hide undocumented C++ concepts if enabled. This option has no effect +# if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = NO @@ -585,14 +625,15 @@ INTERNAL_DOCS = NO # filesystem is case sensitive (i.e. it supports files in the same directory # whose names only differ in casing), the option must be set to YES to properly # deal with such files in case they appear in the input. For filesystems that -# are not case sensitive the option should be be set to NO to properly deal with +# are not case sensitive the option should be set to NO to properly deal with # output files written for symbols that only differ in casing, such as for two # classes, one named CLASS and the other named Class, and to also support # references to files without having to specify the exact matching casing. On # Windows (including Cygwin) and MacOS, users should typically set this option # to NO, whereas on Linux or other Unix flavors it should typically be set to # YES. -# The default value is: system dependent. +# Possible values are: SYSTEM, NO and YES. +# The default value is: SYSTEM. CASE_SENSE_NAMES = NO @@ -610,6 +651,12 @@ HIDE_SCOPE_NAMES = NO HIDE_COMPOUND_REFERENCE= NO +# If the SHOW_HEADERFILE tag is set to YES then the documentation for a class +# will show which file needs to be included to use the class. +# The default value is: YES. + +SHOW_HEADERFILE = YES + # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. @@ -767,7 +814,8 @@ FILE_VERSION_FILTER = # output files in an output format independent way. To create the layout file # that represents doxygen's defaults, run doxygen with the -l option. You can # optionally specify a file name after the option, if omitted DoxygenLayout.xml -# will be used as the name of the layout file. +# will be used as the name of the layout file. See also section "Changing the +# layout of pages" for information. # # Note that if you run doxygen from a directory containing a file called # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE @@ -813,27 +861,50 @@ WARNINGS = YES WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some parameters -# in a documented function, or documenting parameters that don't exist or using -# markup commands wrongly. +# potential errors in the documentation, such as documenting some parameters in +# a documented function twice, or documenting parameters that don't exist or +# using markup commands wrongly. # The default value is: YES. WARN_IF_DOC_ERROR = YES +# If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete +# function parameter documentation. If set to NO, doxygen will accept that some +# parameters have no documentation without warning. +# The default value is: YES. + +WARN_IF_INCOMPLETE_DOC = YES + # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return -# value. If set to NO, doxygen will only warn about wrong or incomplete -# parameter documentation, but not about the absence of documentation. If -# EXTRACT_ALL is set to YES then this flag will automatically be disabled. +# value. If set to NO, doxygen will only warn about wrong parameter +# documentation, but not about the absence of documentation. If EXTRACT_ALL is +# set to YES then this flag will automatically be disabled. See also +# WARN_IF_INCOMPLETE_DOC # The default value is: NO. WARN_NO_PARAMDOC = NO +# If WARN_IF_UNDOC_ENUM_VAL option is set to YES, doxygen will warn about +# undocumented enumeration values. If set to NO, doxygen will accept +# undocumented enumeration values. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: NO. + +WARN_IF_UNDOC_ENUM_VAL = NO + # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS # then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but # at the end of the doxygen process doxygen will return with a non-zero status. -# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS_PRINT then doxygen behaves +# like FAIL_ON_WARNINGS but in case no WARN_LOGFILE is defined doxygen will not +# write the warning messages in between other messages but write them at the end +# of a run, in case a WARN_LOGFILE is defined the warning messages will be +# besides being in the defined file also be shown at the end of a run, unless +# the WARN_LOGFILE is defined as - i.e. standard output (stdout) in that case +# the behavior will remain as with the setting FAIL_ON_WARNINGS. +# Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. WARN_AS_ERROR = NO @@ -844,13 +915,27 @@ WARN_AS_ERROR = NO # and the warning text. Optionally the format may contain $version, which will # be replaced by the version of the file (if it could be obtained via # FILE_VERSION_FILTER) +# See also: WARN_LINE_FORMAT # The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" +# In the $text part of the WARN_FORMAT command it is possible that a reference +# to a more specific place is given. To make it easier to jump to this place +# (outside of doxygen) the user can define a custom "cut" / "paste" string. +# Example: +# WARN_LINE_FORMAT = "'vi $file +$line'" +# See also: WARN_FORMAT +# The default value is: at line $line of file $file. + +WARN_LINE_FORMAT = "at line $line of file $file" + # The WARN_LOGFILE tag can be used to specify a file to which warning and error # messages should be written. If left blank the output is written to standard -# error (stderr). +# error (stderr). In case the file specified cannot be opened for writing the +# warning and error messages are written to standard error. When as file - is +# specified the warning and error messages are written to standard output +# (stdout). WARN_LOGFILE = ../../build/docs/doxygen_warnings.log @@ -865,18 +950,31 @@ WARN_LOGFILE = ../../build/docs/doxygen_warnings.log # Note: If this tag is empty the current directory is searched. INPUT = . \ - ../../src - + ../../src \ + ../../Examples/TemperatureMonitor \ + ../../Examples/WindMonitor \ + ../../Examples/DeviceAnalyzer # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv # documentation (see: # https://www.gnu.org/software/libiconv/) for the list of possible encodings. +# See also: INPUT_FILE_ENCODING # The default value is: UTF-8. INPUT_ENCODING = UTF-8 +# This tag can be used to specify the character encoding of the source files +# that doxygen parses The INPUT_FILE_ENCODING tag can be used to specify +# character encoding on a per file pattern basis. Doxygen will compare the file +# name with each pattern and apply the encoding instead of the default +# INPUT_ENCODING) if there is a match. The character encodings are a list of the +# form: pattern=encoding (like *.php=ISO-8859-1). See cfg_input_encoding +# "INPUT_ENCODING" for further information on supported encodings. + +INPUT_FILE_ENCODING = + # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and # *.h) to filter out the source-files in the directories. @@ -888,12 +986,12 @@ INPUT_ENCODING = UTF-8 # Note the list of default checked file patterns might differ from the list of # default file extension mappings. # -# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, -# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, -# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, -# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), -# *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, *.vhdl, -# *.ucf, *.qsf and *.ice. +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cxxm, +# *.cpp, *.cppm, *.ccm, *.c++, *.c++m, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, +# *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.ixx, *.l, *.cs, *.d, +# *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to +# be provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.c \ *.cpp \ @@ -905,7 +1003,8 @@ FILE_PATTERNS = *.c \ *.m \ *.markdown \ *.md \ - *.dox + *.dox \ + *.ino # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -942,10 +1041,7 @@ EXCLUDE_PATTERNS = # (namespaces, classes, functions, etc.) that should be excluded from the # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories use the pattern */test/* +# ANamespace::AClass, ANamespace::*Test EXCLUDE_SYMBOLS = @@ -990,6 +1086,11 @@ IMAGE_PATH = images # code is scanned, but not when the output code is generated. If lines are added # or removed, the anchors will not be placed correctly. # +# Note that doxygen will use the data processed and written to standard output +# for further processing, therefore nothing else, like debug statements or used +# commands (so in case of a Windows batch file always use @echo OFF), should be +# written to standard output. +# # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. @@ -1031,6 +1132,15 @@ FILTER_SOURCE_PATTERNS = USE_MDFILE_AS_MAINPAGE = +# The Fortran standard specifies that for fixed formatted Fortran code all +# characters from position 72 are to be considered as comment. A common +# extension is to allow longer lines before the automatic comment starts. The +# setting FORTRAN_COMMENT_AFTER will also make it possible that longer lines can +# be processed before the automatic comment starts. +# Minimum value: 7, maximum value: 10000, default value: 72. + +FORTRAN_COMMENT_AFTER = 72 + #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- @@ -1045,7 +1155,8 @@ USE_MDFILE_AS_MAINPAGE = SOURCE_BROWSER = YES # Setting the INLINE_SOURCES tag to YES will include the body of functions, -# classes and enums directly into the documentation. +# multi-line macros, enums or list initialized variables directly into the +# documentation. # The default value is: NO. INLINE_SOURCES = NO @@ -1128,9 +1239,11 @@ VERBATIM_HEADERS = YES CLANG_ASSISTED_PARSING = NO -# If clang assisted parsing is enabled and the CLANG_ADD_INC_PATHS tag is set to -# YES then doxygen will add the directory of each input to the include path. +# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS +# tag is set to YES then doxygen will add the directory of each input to the +# include path. # The default value is: YES. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. CLANG_ADD_INC_PATHS = YES @@ -1166,10 +1279,11 @@ CLANG_DATABASE_PATH = ALPHABETICAL_INDEX = YES -# In case all classes in a project start with a common prefix, all classes will -# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag -# can be used to specify a prefix (or a list of prefixes) that should be ignored -# while generating the index headers. +# The IGNORE_PREFIX tag can be used to specify a prefix (or a list of prefixes) +# that should be ignored while generating the index headers. The IGNORE_PREFIX +# tag works for classes, function and member names. The entity will be placed in +# the alphabetical list under the first letter of the entity name that remains +# after removing the prefix. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = @@ -1248,7 +1362,12 @@ HTML_STYLESHEET = # Doxygen will copy the style sheet files to the output directory. # Note: The order of the extra style sheet files is of importance (e.g. the last # style sheet in the list overrules the setting of the previous ones in the -# list). For an example see the documentation. +# list). +# Note: Since the styling of scrollbars can currently not be overruled in +# Webkit/Chromium, the styling will be left out of the default doxygen.css if +# one or more extra stylesheets have been specified. So if scrollbar +# customization is desired it has to be added explicitly. For an example see the +# documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_STYLESHEET = doxyStyle/doxygen-awesome-sidebar-only-darkmode-toggle.css \ @@ -1273,9 +1392,22 @@ HTML_EXTRA_FILES = doxyStyle/doxygen-awesome-darkmode-toggle.js \ doxyStyle/toggle-alternative-theme.js \ images/logo_sqare1.svg +# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output +# should be rendered with a dark or light theme. +# Possible values are: LIGHT always generate light mode output, DARK always +# generate dark mode output, AUTO_LIGHT automatically set the mode according to +# the user preference, use light mode if no preference is set (the default), +# AUTO_DARK automatically set the mode according to the user preference, use +# dark mode if no preference is set and TOGGLE allow to user to switch between +# light and dark mode via a button. +# The default value is: AUTO_LIGHT. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE = AUTO_LIGHT + # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to -# this color. Hue is specified as an angle on a colorwheel, see +# this color. Hue is specified as an angle on a color-wheel, see # https://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. @@ -1285,7 +1417,7 @@ HTML_EXTRA_FILES = doxyStyle/doxygen-awesome-darkmode-toggle.js \ HTML_COLORSTYLE_HUE = 209 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors -# in the HTML output. For a value of 0 the output will use grayscales only. A +# in the HTML output. For a value of 0 the output will use gray-scales only. A # value of 255 will produce the most vivid colors. # Minimum value: 0, maximum value: 255, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1303,15 +1435,6 @@ HTML_COLORSTYLE_SAT = 255 HTML_COLORSTYLE_GAMMA = 113 -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that # are dynamically created via JavaScript. If disabled, the navigation index will @@ -1331,6 +1454,33 @@ HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = NO +# If the HTML_CODE_FOLDING tag is set to YES then classes and functions can be +# dynamically folded and expanded in the generated HTML source code. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_CODE_FOLDING = YES + +# If the HTML_COPY_CLIPBOARD tag is set to YES then doxygen will show an icon in +# the top right corner of code and text fragments that allows the user to copy +# its content to the clipboard. Note this only works if supported by the browser +# and the web page is served via a secure context (see: +# https://www.w3.org/TR/secure-contexts/), i.e. using the https: or file: +# protocol. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COPY_CLIPBOARD = YES + +# Doxygen stores a couple of settings persistently in the browser (via e.g. +# cookies). By default these settings apply to all HTML pages generated by +# doxygen across all projects. The HTML_PROJECT_COOKIE tag can be used to store +# the settings under a project specific key, such that the user preferences will +# be stored separately. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_PROJECT_COOKIE = + # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to @@ -1367,6 +1517,13 @@ GENERATE_DOCSET = NO DOCSET_FEEDNAME = "Doxygen generated docs" +# This tag determines the URL of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDURL = + # This tag specifies a string that should uniquely identify the documentation # set bundle. This should be a reverse domain-name style string, e.g. # com.mycompany.MyDocSet. Doxygen will append .docset to the name. @@ -1392,8 +1549,12 @@ DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: -# https://www.microsoft.com/en-us/download/details.aspx?id=21138) on Windows. +# on Windows. In the beginning of 2021 Microsoft took the original page, with +# a.o. the download links, offline the HTML help workshop was already many years +# in maintenance mode). You can download the HTML help workshop from the web +# archives at Installation executable (see: +# http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo +# ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). # # The HTML Help Workshop contains a compiler that can convert all HTML output # generated by doxygen into a single compiled HTML file (.chm). Compiled HTML @@ -1450,6 +1611,16 @@ BINARY_TOC = NO TOC_EXPAND = NO +# The SITEMAP_URL tag is used to specify the full URL of the place where the +# generated documentation will be placed on the server by the user during the +# deployment of the documentation. The generated sitemap is called sitemap.xml +# and placed on the directory specified by HTML_OUTPUT. In case no SITEMAP_URL +# is specified no sitemap is generated. For information about the sitemap +# protocol see https://www.sitemaps.org +# This tag requires that the tag GENERATE_HTML is set to YES. + +SITEMAP_URL = + # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help @@ -1552,16 +1723,28 @@ DISABLE_INDEX = NO # to work a browser that supports JavaScript, DHTML, CSS and frames is required # (i.e. any modern browser). Windows users are probably better off using the # HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can -# further fine-tune the look of the index. As an example, the default style -# sheet generated by doxygen has an example that shows how to put an image at -# the root of the tree instead of the PROJECT_NAME. Since the tree basically has -# the same information as the tab index, you could consider setting -# DISABLE_INDEX to YES when enabling this option. +# further fine tune the look of the index (see "Fine-tuning the output"). As an +# example, the default style sheet generated by doxygen has an example that +# shows how to put an image at the root of the tree instead of the PROJECT_NAME. +# Since the tree basically has the same information as the tab index, you could +# consider setting DISABLE_INDEX to YES when enabling this option. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = YES +# When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the +# FULL_SIDEBAR option determines if the side bar is limited to only the treeview +# area (value NO) or if it should extend to the full height of the window (value +# YES). Setting this to YES gives a layout similar to +# https://docs.readthedocs.io with more room for contents, but less room for the +# project logo, title, and description. If either GENERATE_TREEVIEW or +# DISABLE_INDEX is set to NO, this option has no effect. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FULL_SIDEBAR = NO + # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. # @@ -1586,6 +1769,13 @@ TREEVIEW_WIDTH = 335 EXT_LINKS_IN_WINDOW = NO +# If the OBFUSCATE_EMAILS tag is set to YES, doxygen will obfuscate email +# addresses. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +OBFUSCATE_EMAILS = YES + # If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg # tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see # https://inkscape.org) to generate formulas as SVG images instead of PNGs for @@ -1606,17 +1796,6 @@ HTML_FORMULA_FORMAT = png FORMULA_FONTSIZE = 12 -# Use the FORMULA_TRANSPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_TRANSPARENT = YES - # The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands # to create new LaTeX commands to be used in formulas as building blocks. See # the section "Including formulas" for details. @@ -1634,11 +1813,29 @@ FORMULA_MACROFILE = USE_MATHJAX = NO +# With MATHJAX_VERSION it is possible to specify the MathJax version to be used. +# Note that the different versions of MathJax have different requirements with +# regards to the different settings, so it is possible that also other MathJax +# settings have to be changed when switching between the different MathJax +# versions. +# Possible values are: MathJax_2 and MathJax_3. +# The default value is: MathJax_2. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_VERSION = MathJax_2 + # When MathJax is enabled you can set the default output format to be used for -# the MathJax output. See the MathJax site (see: -# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. +# the MathJax output. For more details about the output format see MathJax +# version 2 (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) and MathJax version 3 +# (see: +# http://docs.mathjax.org/en/latest/web/components/output.html). # Possible values are: HTML-CSS (which is slower, but has the best -# compatibility), NativeMML (i.e. MathML) and SVG. +# compatibility. This is the name for Mathjax version 2, for MathJax version 3 +# this will be translated into chtml), NativeMML (i.e. MathML. Only supported +# for NathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This +# is the name for Mathjax version 3, for MathJax version 2 this will be +# translated into HTML-CSS) and SVG. # The default value is: HTML-CSS. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1651,15 +1848,21 @@ MATHJAX_FORMAT = HTML-CSS # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of -# MathJax from https://www.mathjax.org before deployment. -# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. +# MathJax from https://www.mathjax.org before deployment. The default value is: +# - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2 +# - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3 # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@2 # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example +# for MathJax version 2 (see +# https://docs.mathjax.org/en/v2.7-latest/tex.html#tex-and-latex-extensions): # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# For example for MathJax version 3 (see +# http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): +# MATHJAX_EXTENSIONS = ams # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_EXTENSIONS = @@ -1839,29 +2042,31 @@ PAPER_TYPE = a4 EXTRA_PACKAGES = -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for the -# generated LaTeX document. The header should contain everything until the first -# chapter. If it is left blank doxygen will generate a standard header. See -# section "Doxygen usage" for information on how to let doxygen write the -# default header to a separate file. +# The LATEX_HEADER tag can be used to specify a user-defined LaTeX header for +# the generated LaTeX document. The header should contain everything until the +# first chapter. If it is left blank doxygen will generate a standard header. It +# is highly recommended to start with a default header using +# doxygen -w latex new_header.tex new_footer.tex new_stylesheet.sty +# and then modify the file new_header.tex. See also section "Doxygen usage" for +# information on how to generate the default header that doxygen normally uses. # -# Note: Only use a user-defined header if you know what you are doing! The -# following commands have a special meaning inside the header: $title, -# $datetime, $date, $doxygenversion, $projectname, $projectnumber, -# $projectbrief, $projectlogo. Doxygen will replace $title with the empty -# string, for the replacement values of the other commands the user is referred -# to HTML_HEADER. +# Note: Only use a user-defined header if you know what you are doing! +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. The following +# commands have a special meaning inside the header (and footer): For a +# description of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HEADER = -# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the -# generated LaTeX document. The footer should contain everything after the last -# chapter. If it is left blank doxygen will generate a standard footer. See +# The LATEX_FOOTER tag can be used to specify a user-defined LaTeX footer for +# the generated LaTeX document. The footer should contain everything after the +# last chapter. If it is left blank doxygen will generate a standard footer. See # LATEX_HEADER for more information on how to generate a default footer and what -# special commands can be used inside the footer. -# -# Note: Only use a user-defined footer if you know what you are doing! +# special commands can be used inside the footer. See also section "Doxygen +# usage" for information on how to generate the default footer that doxygen +# normally uses. Note: Only use a user-defined footer if you know what you are +# doing! # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_FOOTER = @@ -1904,10 +2109,16 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode -# command to the generated LaTeX files. This will instruct LaTeX to keep running -# if errors occur, instead of asking the user for help. This option is also used -# when generating formulas in HTML. +# The LATEX_BATCHMODE tag signals the behavior of LaTeX in case of an error. +# Possible values are: NO same as ERROR_STOP, YES same as BATCH, BATCH In batch +# mode nothing is printed on the terminal, errors are scrolled as if is +# hit at every error; missing files that TeX tries to input or request from +# keyboard input (\read on a not open input stream) cause the job to abort, +# NON_STOP In nonstop mode the diagnostic message will appear on the terminal, +# but there is no possibility of user interaction just like in batch mode, +# SCROLL In scroll mode, TeX will stop only for missing files to input or if +# keyboard input is necessary and ERROR_STOP In errorstop mode, TeX will stop at +# each error, asking for user intervention. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1920,16 +2131,6 @@ LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source -# code with syntax highlighting in the LaTeX output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_SOURCE_CODE = NO - # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See # https://en.wikipedia.org/wiki/BibTeX and \cite for more info. @@ -1938,14 +2139,6 @@ LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain -# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_TIMESTAMP = NO - # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) # path from which the emoji images will be read. If a relative path is entered, # it will be relative to the LATEX_OUTPUT directory. If left blank the @@ -2010,16 +2203,6 @@ RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = -# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code -# with syntax highlighting in the RTF output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_RTF is set to YES. - -RTF_SOURCE_CODE = NO - #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- @@ -2116,21 +2299,12 @@ GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the -# program listings (including syntax highlighting and cross-referencing -# information) to the DOCBOOK output. Note that enabling this will significantly -# increase the size of the DOCBOOK output. -# The default value is: NO. -# This tag requires that the tag GENERATE_DOCBOOK is set to YES. - -DOCBOOK_PROGRAMLISTING = NO - #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# AutoGen Definitions (see https://autogen.sourceforge.net/) file that captures # the structure of the code including all documentation. Note that this feature # is still experimental and incomplete at the moment. # The default value is: NO. @@ -2141,6 +2315,28 @@ GENERATE_AUTOGEN_DEF = NO # Configuration options related to Sqlite3 output #--------------------------------------------------------------------------- +# If the GENERATE_SQLITE3 tag is set to YES doxygen will generate a Sqlite3 +# database with symbols found by doxygen stored in tables. +# The default value is: NO. + +GENERATE_SQLITE3 = NO + +# The SQLITE3_OUTPUT tag is used to specify where the Sqlite3 database will be +# put. If a relative path is entered the value of OUTPUT_DIRECTORY will be put +# in front of it. +# The default directory is: sqlite3. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_OUTPUT = sqlite3 + +# The SQLITE3_RECREATE_DB tag is set to YES, the existing doxygen_sqlite3.db +# database file will be recreated with each doxygen run. If set to NO, doxygen +# will warn if a database file is already found and not modify it. +# The default value is: YES. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_RECREATE_DB = YES + #--------------------------------------------------------------------------- # Configuration options related to the Perl module output #--------------------------------------------------------------------------- @@ -2215,7 +2411,8 @@ SEARCH_INCLUDES = YES # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by the -# preprocessor. +# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of +# RECURSIVE has no effect here. # This tag requires that the tag SEARCH_INCLUDES is set to YES. INCLUDE_PATH = @@ -2282,15 +2479,15 @@ TAGFILES = GENERATE_TAGFILE = ../../build/docs/nmea_2000_docs.tag -# If the ALLEXTERNALS tag is set to YES, all external class will be listed in -# the class index. If set to NO, only the inherited external classes will be -# listed. +# If the ALLEXTERNALS tag is set to YES, all external classes and namespaces +# will be listed in the class and namespace index. If set to NO, only the +# inherited external classes will be listed. # The default value is: NO. ALLEXTERNALS = NO # If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will be +# in the topic index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. @@ -2304,25 +2501,9 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to diagram generator tools #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram -# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to -# NO turns the diagrams off. Note that this option also works with HAVE_DOT -# disabled, but it is recommended to install and use dot, since it yields more -# powerful graphs. -# The default value is: YES. - -CLASS_DIAGRAMS = YES - -# You can include diagrams made with dia in doxygen documentation. Doxygen will -# then run dia to produce the diagram and insert it in the documentation. The -# DIA_PATH tag allows you to specify the directory where the dia binary resides. -# If left empty dia is assumed to be found in the default search path. - -DIA_PATH = - # If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. @@ -2331,10 +2512,10 @@ HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz (see: -# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# https://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO -# The default value is: YES. +# The default value is: NO. HAVE_DOT = YES @@ -2348,49 +2529,77 @@ HAVE_DOT = YES DOT_NUM_THREADS = 0 -# When you want a differently looking font in the dot files that doxygen -# generates you can specify the font name using DOT_FONTNAME. You need to make -# sure dot is able to find the font, which can be done by putting it in a -# standard location or by setting the DOTFONTPATH environment variable or by -# setting DOT_FONTPATH to the directory containing the font. -# The default value is: Helvetica. +# DOT_COMMON_ATTR is common attributes for nodes, edges and labels of +# subgraphs. When you want a differently looking font in the dot files that +# doxygen generates you can specify fontname, fontcolor and fontsize attributes. +# For details please see Node, +# Edge and Graph Attributes specification You need to make sure dot is able +# to find the font, which can be done by putting it in a standard location or by +# setting the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the +# directory containing the font. Default graphviz fontsize is 14. +# The default value is: fontname=Helvetica,fontsize=10. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10" + +# DOT_EDGE_ATTR is concatenated with DOT_COMMON_ATTR. For elegant style you can +# add 'arrowhead=open, arrowtail=open, arrowsize=0.5'. Complete documentation about +# arrows shapes. +# The default value is: labelfontname=Helvetica,labelfontsize=10. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTNAME = Helvetica +DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10" -# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of -# dot graphs. -# Minimum value: 4, maximum value: 24, default value: 10. +# DOT_NODE_ATTR is concatenated with DOT_COMMON_ATTR. For view without boxes +# around nodes set 'shape=plain' or 'shape=plaintext' Shapes specification +# The default value is: shape=box,height=0.2,width=0.4. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTSIZE = 10 +DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" -# By default doxygen will tell dot to use the default font as specified with -# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set -# the path where dot can find it using this tag. +# You can set the path where dot can find font specified with fontname in +# DOT_COMMON_ATTR and others dot attributes. # This tag requires that the tag HAVE_DOT is set to YES. DOT_FONTPATH = -# If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for -# each documented class showing the direct and indirect inheritance relations. -# Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO. +# If the CLASS_GRAPH tag is set to YES or GRAPH or BUILTIN then doxygen will +# generate a graph for each documented class showing the direct and indirect +# inheritance relations. In case the CLASS_GRAPH tag is set to YES or GRAPH and +# HAVE_DOT is enabled as well, then dot will be used to draw the graph. In case +# the CLASS_GRAPH tag is set to YES and HAVE_DOT is disabled or if the +# CLASS_GRAPH tag is set to BUILTIN, then the built-in generator will be used. +# If the CLASS_GRAPH tag is set to TEXT the direct and indirect inheritance +# relations will be shown as texts / links. Explicit enabling an inheritance +# graph or choosing a different representation for an inheritance graph of a +# specific class, can be accomplished by means of the command \inheritancegraph. +# Disabling an inheritance graph can be accomplished by means of the command +# \hideinheritancegraph. +# Possible values are: NO, YES, TEXT, GRAPH and BUILTIN. # The default value is: YES. -# This tag requires that the tag HAVE_DOT is set to YES. CLASS_GRAPH = YES # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a # graph for each documented class showing the direct and indirect implementation # dependencies (inheritance, containment, and class references variables) of the -# class with other documented classes. +# class with other documented classes. Explicit enabling a collaboration graph, +# when COLLABORATION_GRAPH is set to NO, can be accomplished by means of the +# command \collaborationgraph. Disabling a collaboration graph can be +# accomplished by means of the command \hidecollaborationgraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. COLLABORATION_GRAPH = YES # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for -# groups, showing the direct groups dependencies. +# groups, showing the direct groups dependencies. Explicit enabling a group +# dependency graph, when GROUP_GRAPHS is set to NO, can be accomplished by means +# of the command \groupgraph. Disabling a directory graph can be accomplished by +# means of the command \hidegroupgraph. See also the chapter Grouping in the +# manual. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2432,8 +2641,8 @@ DOT_UML_DETAILS = NO # The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters # to display on a single line. If the actual line length exceeds this threshold -# significantly it will wrapped across multiple lines. Some heuristics are apply -# to avoid ugly line breaks. +# significantly it will be wrapped across multiple lines. Some heuristics are +# applied to avoid ugly line breaks. # Minimum value: 0, maximum value: 1000, default value: 17. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2450,7 +2659,9 @@ TEMPLATE_RELATIONS = NO # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to # YES then doxygen will generate a graph for each documented file showing the # direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an include graph, when INCLUDE_GRAPH is is set to NO, +# can be accomplished by means of the command \includegraph. Disabling an +# include graph can be accomplished by means of the command \hideincludegraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2459,7 +2670,10 @@ INCLUDE_GRAPH = YES # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing # the direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an included by graph, when INCLUDED_BY_GRAPH is set +# to NO, can be accomplished by means of the command \includedbygraph. Disabling +# an included by graph can be accomplished by means of the command +# \hideincludedbygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2499,22 +2713,30 @@ GRAPHICAL_HIERARCHY = YES # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the # dependencies a directory has on other directories in a graphical way. The # dependency relations are determined by the #include relations between the -# files in the directories. +# files in the directories. Explicit enabling a directory graph, when +# DIRECTORY_GRAPH is set to NO, can be accomplished by means of the command +# \directorygraph. Disabling a directory graph can be accomplished by means of +# the command \hidedirectorygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. DIRECTORY_GRAPH = YES +# The DIR_GRAPH_MAX_DEPTH tag can be used to limit the maximum number of levels +# of child directories generated in directory dependency graphs by dot. +# Minimum value: 1, maximum value: 25, default value: 1. +# This tag requires that the tag DIRECTORY_GRAPH is set to YES. + +DIR_GRAPH_MAX_DEPTH = 1 + # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section # output formats in the documentation of the dot tool (Graphviz (see: -# http://www.graphviz.org/)). +# https://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). -# Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd, -# png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo, -# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo, +# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, # png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and # png:gdiplus:gdiplus. # The default value is: png. @@ -2547,11 +2769,12 @@ DOT_PATH = DOTFILE_DIRS = -# The MSCFILE_DIRS tag can be used to specify one or more directories that -# contain msc files that are included in the documentation (see the \mscfile -# command). +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. -MSCFILE_DIRS = +DIA_PATH = # The DIAFILE_DIRS tag can be used to specify one or more directories that # contain dia files that are included in the documentation (see the \diafile @@ -2560,10 +2783,10 @@ MSCFILE_DIRS = DIAFILE_DIRS = # When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the -# path where java can find the plantuml.jar file. If left blank, it is assumed -# PlantUML is not used or called during a preprocessing step. Doxygen will -# generate a warning when it encounters a \startuml command in this case and -# will not generate output for the diagram. +# path where java can find the plantuml.jar file or to the filename of jar file +# to be used. If left blank, it is assumed PlantUML is not used or called during +# a preprocessing step. Doxygen will generate a warning when it encounters a +# \startuml command in this case and will not generate output for the diagram. PLANTUML_JAR_PATH = @@ -2601,18 +2824,6 @@ DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not seem -# to support this out of the box. -# -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). -# The default value is: NO. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_TRANSPARENT = NO - # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support @@ -2625,6 +2836,8 @@ DOT_MULTI_TARGETS = NO # If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page # explaining the meaning of the various boxes and arrows in the dot generated # graphs. +# Note: This tag requires that UML_LOOK isn't set, i.e. the doxygen internal +# graphical representation for inheritance and collaboration diagrams is used. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2633,8 +2846,24 @@ GENERATE_LEGEND = YES # If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate # files that are used to generate the various graphs. # -# Note: This setting is not only used for dot files but also for msc and -# plantuml temporary files. +# Note: This setting is not only used for dot files but also for msc temporary +# files. # The default value is: YES. DOT_CLEANUP = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. If the MSCGEN_TOOL tag is left empty (the default), then doxygen will +# use a built-in version of mscgen tool to produce the charts. Alternatively, +# the MSCGEN_TOOL tag can also specify the name an external tool. For instance, +# specifying prog as the value, doxygen will call the tool as prog -T +# -o . The external tool should support +# output file formats "png", "eps", "svg", and "ismap". + +MSCGEN_TOOL = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = diff --git a/Documents/src/changes.md b/Documents/src/changes.md index 7509e913..dcaf052c 100644 --- a/Documents/src/changes.md +++ b/Documents/src/changes.md @@ -1,6 +1,10 @@ # Changes to the Library {#changes} \tableofcontents +## 21.01.2024 + +- Document update. Updates on document sources and code sources. + ## 13.01.2024 - Fixed PGN129539 reader and parser. diff --git a/Documents/src/groupdef.dox b/Documents/src/groupdef.dox index 78807872..797bc177 100644 --- a/Documents/src/groupdef.dox +++ b/Documents/src/groupdef.dox @@ -74,4 +74,9 @@ \ref n2kMessages.h */ -/** @} */ \ No newline at end of file +/** @} */ + +/** \defgroup group_examples 5 Examples + \brief Examples how to use library. + +*/ diff --git a/Examples/DeviceAnalyzer/DeviceAnalyzer.ino b/Examples/DeviceAnalyzer/DeviceAnalyzer.ino index f5e92178..3587d2d6 100644 --- a/Examples/DeviceAnalyzer/DeviceAnalyzer.ino +++ b/Examples/DeviceAnalyzer/DeviceAnalyzer.ino @@ -1,3 +1,14 @@ +/***********************************************************************//** + \file DeviceAnalyzer.ino + \brief NMEA2000 library example. Show devices on NMEA2000 bus by using tN2kDeviceList. + \ingroup group_examples + + tN2kDeviceList is helper class, which automatically keeps track of devices on the bus. + This example simplyt lists all devices on the bus and prints their information by using + data collected by tN2kDeviceList. + +*/ + #include #define N2k_CAN_INT_PIN 21 #include // This will automatically choose right CAN library and create suitable NMEA2000 object diff --git a/Examples/TemperatureMonitor/TemperatureMonitor.ino b/Examples/TemperatureMonitor/TemperatureMonitor.ino index 64019741..e37d785d 100644 --- a/Examples/TemperatureMonitor/TemperatureMonitor.ino +++ b/Examples/TemperatureMonitor/TemperatureMonitor.ino @@ -1,4 +1,14 @@ -// Demo: NMEA2000 library. Send main cabin temperature to the bus. +/***********************************************************************//** + \file TemperatureMonitor.ino + \brief NMEA2000 library example. Send main cabin and water temperatures to the bus. + \ingroup group_examples + + This simple example sends hardcoded main cabin and water temperature information + to the NMEA2000 bus. To make it working device you need add functionality, which + reads real temperatures. + + Example does not yet fullfill all NMEA2000 requirements. +*/ #include //#define N2k_SPI_CS_PIN 53 // If you use mcp_can and CS pin is not 53, uncomment this and modify definition to match your CS pin. @@ -56,7 +66,7 @@ void setup() { //NMEA2000.SetForwardType(tNMEA2000::fwdt_Text); // Show in clear text. Leave uncommented for default Actisense format. // If you also want to see all traffic on the bus use N2km_ListenAndNode instead of N2km_NodeOnly below - NMEA2000.SetMode(tNMEA2000::N2km_NodeOnly,22); + NMEA2000.SetMode(tNMEA2000::N2km_ListenAndNode,22); //NMEA2000.SetDebugMode(tNMEA2000::dm_Actisense); // Uncomment this, so you can test code without CAN bus chips on Arduino Mega NMEA2000.EnableForward(false); // Disable all msg forwarding to USB (=Serial) // Here we tell library, which PGNs we transmit diff --git a/Examples/WindMonitor/WindMonitor.ino b/Examples/WindMonitor/WindMonitor.ino index 297b3b46..8c401659 100644 --- a/Examples/WindMonitor/WindMonitor.ino +++ b/Examples/WindMonitor/WindMonitor.ino @@ -1,4 +1,14 @@ -// Demo: NMEA2000 library. Send main wind data to the bus. +/***********************************************************************//** + \file WindMonitor.ino + \brief NMEA2000 library example. Send main wind data to the bus. + \ingroup group_examples + + This simple example sends hardcoded wind angle and speed information + to the NMEA2000 bus. To make it working device you need add functionality, which + reads real values. + + Example does not fullfill all NMEA2000 requirements. +*/ #include //#define N2k_SPI_CS_PIN 53 // If you use mcp_can and CS pin is not 53, uncomment this and modify definition to match your CS pin. diff --git a/README.adoc b/README.adoc index fea45142..6d33d674 100644 --- a/README.adoc +++ b/README.adoc @@ -1,15 +1,10 @@ = NMEA2000 library for C++ = -Object oriented NMEA2000 library for Teensy, ESP, Arduino, MBED and Rasberry type Boards. -These board types has been tested, but library can be used also in other systems by writing -compatible CAN driver and wrapper for other hw specific functions. +NMEA2000 library is object oriented C++ library for developing NMEA2000 bus devices. Library fulfills automatically NMEA 2000 mandatory requirements leaving only interesting data handling for developer. ** Library has been used in several commercial certified NMEA2000 devices. ** -Library gives you easy way to make different kind of NMEA2000 bus devices like -sensor transducers (battery, temperature, wind, engine, etc.), NMEA2000 information displays, -NMEA2000->PC interface (like Actisense NGT1), NMEA0183->NMEA2000 or NMEA2000->NMEA0183 converter. +Library provides you easy way to make different kind of NMEA2000 bus devices like sensor transducers (battery, temperature, wind, engine, etc.), NMEA2000 information displays,NMEA2000->PC interface (like Actisense NGT1), NMEA0183->NMEA2000 or NMEA2000->NMEA0183 converter. -Library fulfills NMEA 2000 mandatory functions and behaviour. Devices using library can pass NMEA2000 -certification tests. Library has been used in several commercial certified products. +Library has been originally (2015) developed for Arduino based boards. As far as I know it has been used and tested with Teensy, ESP, some Arduino, MBED and Rasberry Boards, but library can be used also in other systems by writing compatible CAN "driver" and necessary classes for other hw specific functions. If you are familiar with library, here is quick link to the changes: https://ttlappalainen.github.io/NMEA2000/changes.html diff --git a/src/ActisenseReader.h b/src/ActisenseReader.h index 6effd770..2708d5e7 100644 --- a/src/ActisenseReader.h +++ b/src/ActisenseReader.h @@ -23,9 +23,11 @@ /**************************************************************************//** * \file ActisenseReader.h - * \brief This File contains a class for reading Actisense format messages + * \brief File contains declaration for tActisenseReader class for reading Actisense format messages from stream. * - * This is class for reading Actisense format messages from given stream. + * This is class for reading Actisense format messages from given stream and convert + * it to tN2kMsg. Converted tN2kMsg message can be then sent to the NMEA2000 bus + * with tNMEA2000::SendMsg(); * * \note There is an unresolved problem to use programming port with reading * data. Read works fine for a while, but then stops. With e.g. Arduino Due @@ -43,8 +45,9 @@ * \brief Class for reading Actisense format messages * \ingroup group_helperClass * - * - * This is class for reading Actisense format messages from given stream. + * This is class for reading Actisense format messages from given stream and convert + * it to tN2kMsg. Converted tN2kMsg message can be then sent to the NMEA2000 bus + * with tNMEA2000::SendMsg(); * * \note There is an unresolved problem to use programming port with reading * data. Read works fine for a while, but then stops. With e.g. Arduino Due @@ -82,8 +85,8 @@ class tActisenseReader * \brief Adds a new Byte to the buffer * * \param NewByte new Byte to be added - * \return true -> Success - * \return false -> Buffer is full + * \retval true Success + * \retval false Buffer is full */ bool AddByteToBuffer(char NewByte); /********************************************************************//** @@ -92,13 +95,11 @@ class tActisenseReader void ClearBuffer(); /********************************************************************//** - * \brief Checks if a message is valide + * \brief Checks is Actisense message read from stream valid and builds tN2kMsg message from it. * - * \param N2kMsg Reference to a N2kMsg Object - * \return true - * \return false -> Length does not match. Add type, length and crc - * \return false -> Checksum does not match - * \return false -> data length greater then tN2kMsg::MaxDataLen + * \param N2kMsg Reference to a destination tN2kMsg Object + * \retval true Message is valid. Message has been copied to N2kMsg + * \retval false Length does not match, checksum does not match or data length greater than tN2kMsg::MaxDataLen */ bool CheckMessage(tN2kMsg &N2kMsg); @@ -135,35 +136,41 @@ class tActisenseReader /********************************************************************//** * \brief Read Actisense formatted NMEA2000 message from stream * - * You can either call this or ParseMessages periodically. + * GetMessageFromStream is nonblocking function and returns false, if there is + * no message available. You can either call this or ParseMessages() periodically. * - * Read Actisense formatted NMEA2000 message from stream + * Function reads Actisense formatted NMEA2000 message from stream * Actisense Format: * <10><02><93>