Fix for tPriorityRingBuffer and SetN2kPGN129284/ParseN2kPGN129284

- Fix tPriorityRingBuffer. It did not freed values properly. tPriorityRingBuffer is used on tNMEA2000_Teensyx driver. - Ring buffer documentation update. - Fixed SetN2kPGN129284 and ParseN2kPGN129284. Changed OriginWaypointNumber and DestinationWaypointNumber parameter to uint32_t. This causes compatibility issue for users used ParseN2kPGN129284 and they have to update reference parameter type. Also if SetN2kPGN129284 was used with related parameters value N2kUint8NA, they must be updated to use N2kUint32NA - Moved OnOpen call on Open after setting Heartbeat interval and offset. If Heartbeat settings were set on OnOpen, settings were reset. - Added note to documentation for OnOpen about coming change. - Added lightning PGNs to fastpacket list.
ktand · Feb 6, 2024 · 383d7fb · 383d7fb
1 parent dd96be5
commit 383d7fb
Show file tree

Hide file tree

Showing 9 changed files with 292 additions and 115 deletions.
diff --git a/Documents/src/changes.md b/Documents/src/changes.md
@@ -1,6 +1,15 @@
 # Changes to the Library {#changes}
 \tableofcontents
 
+## 06.02.2024
+
+- Fix tPriorityRingBuffer. It did not freed values properly. tPriorityRingBuffer is used on tNMEA2000_Teensyx driver.
+- Ring buffer documentation update.
+- Fixed SetN2kPGN129284 and ParseN2kPGN129284. Changed OriginWaypointNumber and DestinationWaypointNumber parameter to uint32_t. This causes compatibility issue for users used ParseN2kPGN129284 and they have to update reference parameter type. Also if SetN2kPGN129284 was used with related parameters value N2kUint8NA, they must be updated to use N2kUint32NA
+- Moved OnOpen call on Open after setting Heartbeat interval and offset. If Heartbeat settings were set on OnOpen, settings were reset.
+- Added note to documentation for OnOpen about coming change.
+- Added lightning PGNs to fastpacket list.
+
 ## 02.02.2024
 
 - Document update. Updates on document sources and code sources.

diff --git a/library.json b/library.json
@@ -13,7 +13,7 @@
     "url": "http://www.kave.fi",
     "maintainer": true
   },
-  "version": "4.20.2",
+  "version": "4.20.3",
   "license": "MIT",
   "frameworks": "*",
   "platforms": "*"

diff --git a/library.properties b/library.properties
@@ -1,5 +1,5 @@
 name=NMEA2000
-version=4.20.2
+version=4.20.3
 author=Timo Lappalainen
 maintainer=Kave Oy <www.kave.fi>
 sentence=NMEA 2000 library for building compatible devices for NMEA 2000 bus.

diff --git a/src/N2kMessages.cpp b/src/N2kMessages.cpp
@@ -1522,7 +1522,7 @@ bool ParseN2kPGN129283(const tN2kMsg &N2kMsg, unsigned char& SID, tN2kXTEMode& X
 void SetN2kPGN129284(tN2kMsg &N2kMsg, unsigned char SID, double DistanceToWaypoint, tN2kHeadingReference BearingReference,
                       bool PerpendicularCrossed, bool ArrivalCircleEntered, tN2kDistanceCalculationType CalculationType,
                       double ETATime, int16_t ETADate, double BearingOriginToDestinationWaypoint, double BearingPositionToDestinationWaypoint,
-                      uint8_t OriginWaypointNumber, uint8_t DestinationWaypointNumber,
+                      uint32_t OriginWaypointNumber, uint32_t DestinationWaypointNumber,
                       double DestinationLatitude, double DestinationLongitude, double WaypointClosingVelocity) {
     N2kMsg.SetPGN(129284L);
     N2kMsg.Priority=3;
@@ -1543,7 +1543,7 @@ void SetN2kPGN129284(tN2kMsg &N2kMsg, unsigned char SID, double DistanceToWaypoi
 bool ParseN2kPGN129284(const tN2kMsg &N2kMsg, unsigned char& SID, double& DistanceToWaypoint, tN2kHeadingReference& BearingReference,
                       bool& PerpendicularCrossed, bool& ArrivalCircleEntered, tN2kDistanceCalculationType& CalculationType,
                       double& ETATime, int16_t& ETADate, double& BearingOriginToDestinationWaypoint, double& BearingPositionToDestinationWaypoint,
-                      uint8_t& OriginWaypointNumber, uint8_t& DestinationWaypointNumber,
+                      uint32_t& OriginWaypointNumber, uint32_t& DestinationWaypointNumber,
                       double& DestinationLatitude, double& DestinationLongitude, double& WaypointClosingVelocity) {
 
     if(N2kMsg.PGN != 129284L)

diff --git a/src/N2kMessages.h b/src/N2kMessages.h
@@ -3877,7 +3877,7 @@ inline bool ParseN2kXTE(const tN2kMsg &N2kMsg, unsigned char& SID, tN2kXTEMode&
 void SetN2kPGN129284(tN2kMsg &N2kMsg, unsigned char SID, double DistanceToWaypoint, tN2kHeadingReference BearingReference,
                       bool PerpendicularCrossed, bool ArrivalCircleEntered, tN2kDistanceCalculationType CalculationType,
                       double ETATime, int16_t ETADate, double BearingOriginToDestinationWaypoint, double BearingPositionToDestinationWaypoint,
-                      uint8_t OriginWaypointNumber, uint8_t DestinationWaypointNumber,
+                      uint32_t OriginWaypointNumber, uint32_t DestinationWaypointNumber,
                       double DestinationLatitude, double DestinationLongitude, double WaypointClosingVelocity);
 
 /************************************************************************//**
@@ -3890,7 +3890,7 @@ void SetN2kPGN129284(tN2kMsg &N2kMsg, unsigned char SID, double DistanceToWaypoi
 inline void SetN2kNavigationInfo(tN2kMsg &N2kMsg, unsigned char SID, double DistanceToWaypoint, tN2kHeadingReference BearingReference,
                       bool PerpendicularCrossed, bool ArrivalCircleEntered, tN2kDistanceCalculationType CalculationType,
                       double ETATime, int16_t ETADate, double BearingOriginToDestinationWaypoint, double BearingPositionToDestinationWaypoint,
-                      uint8_t OriginWaypointNumber, uint8_t DestinationWaypointNumber,
+                      uint32_t OriginWaypointNumber, uint32_t DestinationWaypointNumber,
                       double DestinationLatitude, double DestinationLongitude, double WaypointClosingVelocity) {
   SetN2kPGN129284(N2kMsg, SID, DistanceToWaypoint, BearingReference,
                       PerpendicularCrossed, ArrivalCircleEntered, CalculationType,
@@ -3937,7 +3937,7 @@ inline void SetN2kNavigationInfo(tN2kMsg &N2kMsg, unsigned char SID, double Dist
 bool ParseN2kPGN129284(const tN2kMsg &N2kMsg, unsigned char& SID, double& DistanceToWaypoint, tN2kHeadingReference& BearingReference,
                       bool& PerpendicularCrossed, bool& ArrivalCircleEntered, tN2kDistanceCalculationType& CalculationType,
                       double& ETATime, int16_t& ETADate, double& BearingOriginToDestinationWaypoint, double& BearingPositionToDestinationWaypoint,
-                      uint8_t& OriginWaypointNumber, uint8_t& DestinationWaypointNumber,
+                      uint32_t& OriginWaypointNumber, uint32_t& DestinationWaypointNumber,
                       double& DestinationLatitude, double& DestinationLongitude, double& WaypointClosingVelocity);
 
 
@@ -3952,7 +3952,7 @@ bool ParseN2kPGN129284(const tN2kMsg &N2kMsg, unsigned char& SID, double& Distan
 inline bool ParseN2kNavigationInfo(const tN2kMsg &N2kMsg, unsigned char& SID, double& DistanceToWaypoint, tN2kHeadingReference& BearingReference,
                       bool& PerpendicularCrossed, bool& ArrivalCircleEntered, tN2kDistanceCalculationType& CalculationType,
                       double& ETATime, int16_t& ETADate, double& BearingOriginToDestinationWaypoint, double& BearingPositionToDestinationWaypoint,
-                      uint8_t& OriginWaypointNumber, uint8_t& DestinationWaypointNumber,
+                      uint32_t& OriginWaypointNumber, uint32_t& DestinationWaypointNumber,
                       double& DestinationLatitude, double& DestinationLongitude, double& WaypointClosingVelocity) {
    return ParseN2kPGN129284(N2kMsg, SID, DistanceToWaypoint, BearingReference, PerpendicularCrossed, ArrivalCircleEntered, CalculationType,
                             ETATime, ETADate, BearingOriginToDestinationWaypoint, BearingPositionToDestinationWaypoint,

diff --git a/src/NMEA2000.cpp b/src/NMEA2000.cpp
@@ -422,20 +422,27 @@ bool IsMandatoryFastPacketMessage(unsigned long PGN) {
  *          - 130322L: Current Station Data, pri=6, period=1000
  *          - 130323L: Meteorological Station Data, pri=6, period=1000
  *          - 130324L: Moored Buoy Station Data, pri=6, period=1000
- *          - 130567L: Watermaker Input Setting and Status, pri=6, period=2500
- *          - 130577L: Direction Data PGN, pri=3, period=1000
- *          - 130578L: Vessel Speed Components, pri=2, period=250
- *          - 130569L: Current File and Status, pri=6, period=500
- *          - 130570L: Library Data File, pri=6, period=NA
- *          - 130571L: Library Data Group, pri=6, period=NA
- *          - 130572L: Library Data Search, pri=6, period=NA
- *          - 130573L: Supported Source Data, pri=6, period=NA
- *          - 130574L: Supported Zone Data, pri=6, period=NA
- *          - 130580L: System Configuration Status, pri=6, period=NA
- *          - 130581L: Zone Configuration Status, pri=6, period=NA
- *          - 130583L: Available Audio EQ Presets, pri=6, period=NA
- *          - 130584L: Bluetooth Devices, pri=6, period=NA
- *          - 130586L: Zone Configuration Status, pri=6, period=NA
+ *          - 130330L: Lighting system settings, pri=7, period=NA
+ *          - 130561L: Lighting zone, pri=7, period=NA
+ *          - 130562L: Lighting scene, pri=7, period=NA
+ *          - 130563L: Lighting device, pri=7, period=NA
+ *          - 130564L: Lighting device enumeration, pri=7, period=NA
+ *          - 130565L: Lighting color sequence, pri=7, period=NA
+ *          - 130566L: Lighting program, pri=7, period=NA
+ *          - 130567L: Watermaker input setting and status, pri=6, period=2500
+ *          - 130577L: Direction data PGN, pri=3, period=1000
+ *          - 130578L: Vessel speed components, pri=2, period=250
+ *          - 130569L: Entertainment current file and status, pri=6, period=500
+ *          - 130570L: Entertainment library data file, pri=6, period=NA
+ *          - 130571L: Entertainment library data group, pri=6, period=NA
+ *          - 130572L: Entertainment library data search, pri=6, period=NA
+ *          - 130573L: Entertainment supported source data, pri=6, period=NA
+ *          - 130574L: Entertainment supported zone data, pri=6, period=NA
+ *          - 130580L: Entertainment system configuration status, pri=6, period=NA
+ *          - 130581L: Entertainment zone configuration status, pri=6, period=NA
+ *          - 130583L: Entertainment available dudio EQ presets, pri=6, period=NA
+ *          - 130584L: Entertainment bluetooth devices, pri=6, period=NA
+ *          - 130586L: Entertainment zone configuration status, pri=6, period=NA
  * \return false 
  */
 bool IsDefaultFastPacketMessage(unsigned long PGN) {
@@ -532,6 +539,13 @@ bool IsDefaultFastPacketMessage(unsigned long PGN) {
                                       case 130322L: // Current Station Data, pri=6, period=1000
                                       case 130323L: // Meteorological Station Data, pri=6, period=1000
                                       case 130324L: // Moored Buoy Station Data, pri=6, period=1000
+                                      case 130330L: // Lighting system settings, pri=7, period=NA
+                                      case 130561L: // Lighting zone, pri=7, period=NA
+                                      case 130562L: // Lighting scene, pri=7, period=NA
+                                      case 130563L: // Lighting device, pri=7, period=NA
+                                      case 130564L: // Lighting device enumeration, pri=7, period=NA
+                                      case 130565L: // Lighting color sequence, pri=7, period=NA
+                                      case 130566L: // Lighting program, pri=7, period=NA
                                       case 130567L: // Watermaker Input Setting and Status, pri=6, period=2500
                                       case 130577L: // Direction Data PGN, pri=3, period=1000
                                       case 130578L: // Vessel Speed Components, pri=2, period=250
@@ -1230,11 +1244,12 @@ bool tNMEA2000::Open() {
     OpenState=os_Open;
     StartAddressClaim();
     tN2kSyncScheduler::SetSyncOffset();
-    if ( OnOpen!=0 ) OnOpen();
     #if !defined(N2K_NO_HEARTBEAT_SUPPORT)
     SetHeartbeatIntervalAndOffset(DefaultHeartbeatInterval,10000); // Init default hearbeat interval and offset.
     #endif
+    if ( OnOpen!=0 ) OnOpen();
   } else {
+    // Read rubbish out from CAN controller
     unsigned long canId;
     unsigned char len = 0;
     unsigned char buf[8];

diff --git a/src/NMEA2000.h b/src/NMEA2000.h
@@ -1066,6 +1066,10 @@ class tNMEA2000
     * address claming and after it has been accepted, other communication can start.
     * OnOpen can be used e.g., for message timing synchronization so that every time device starts
     * messages will have same sent offset. See also SetOnOpen().
+    *
+    * \note In future OnOpen may be called several times, if communication will be reopened
+    * by \ref Restart or driver error. Developer must take care that possible memory
+    * initializations will be handled properly in case OnOpen is called several times.
     */
     void (*OnOpen)();
 
@@ -2480,19 +2484,19 @@ class tNMEA2000
     /*********************************************************************//**
      * \brief Set the Heartbeat Interval and Offset for a device
      * 
+     * Library will automatically start heartbeat with default interval 60 s
+     * and offset 10 s.
+     * 
      * According to document [NMEA Heartbeat Corrigendum](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 
+     * all NMEA devices shall transmit heartbeat PGN 126993. With this
      * function you can set transmission interval in ms (range 1000-655320ms
-     * , default 60000). Set <1000 to disable it.
-     * You can temporally change interval by setting SetAsDefault parameter 
-     * to false. Then you can restore default interval with interval 
-     * parameter value 0xfffffffe
+     * , default 60000). Set interval 0 to disable heartbeat
      *
      * Function allows to set interval over 60 s or 0 to disable sending for test purposes.
      *
-     * \param interval      Heartbeat Interval in ms
-     * \param offset  		Heartbeat Offset in ms
-     * \param iDev          index of the device on \ref Devices
+     * \param interval      Heartbeat Interval in ms. 0xffffffff=keep current, 0xfffffffe=restore default
+     * \param offset  		  Heartbeat Offset in ms. 0xffffffff=keep current, 0xfffffffe=restore default 
+     * \param iDev          Index of the device on \ref Devices or -1 to set for all.
      */
     void SetHeartbeatIntervalAndOffset(uint32_t interval, uint32_t offset=0, int iDev=-1);
 
@@ -2504,7 +2508,7 @@ class tNMEA2000
      * startup or not.
      * 
      * \param iDev          index of the device on \ref Devices
-     * \return uint_32  -> Device heartbeat interval in ms
+     * \retval uint_32      Device heartbeat interval in ms
      */
     uint32_t GetHeartbeatInterval(int iDev=0) { if (iDev<0 || iDev>=DeviceCount) return 60000; return Devices[iDev].HeartbeatScheduler.GetPeriod(); }
     /*********************************************************************//**
@@ -2515,13 +2519,16 @@ class tNMEA2000
      * startup or not.
      * 
      * \param iDev          index of the device on \ref Devices
-     * \return uint_32  -> Device heartbeat Offset in ms
+     * \retval uint_32      Device heartbeat Offset in ms
      */
     uint32_t GetHeartbeatOffset(int iDev=0) { if (iDev<0 || iDev>=DeviceCount) return 0; return Devices[iDev].HeartbeatScheduler.GetOffset(); }
 
     /*********************************************************************//**
      * \brief Send heartbeat for specific device.
      * 
+     * Library will automatically send heartbeat, if interval is >0. You 
+     * can also manually send it any time or force sent, if interval=0;
+     *
      * \param iDev          index of the device on \ref Devices
      */
     void SendHeartbeat(int iDev);
@@ -2536,7 +2543,9 @@ class tNMEA2000
      */
     void SendHeartbeat(bool force=false);
 
-    // deprecated! SetAsDefault has no effect. Use function SetHeartbeatIntervalAndOffset.
+    /*********************************************************************//**
+     * \brief Deprecated. Use function \ref SetHeartbeatIntervalAndOffset
+     */
     void SetHeartbeatInterval(unsigned long interval, bool SetAsDefault=true, int iDev=-1) __attribute__ ((deprecated));
 #endif
 
@@ -2710,6 +2719,10 @@ class tNMEA2000
      * OnOpen will be called, when communication really opens
      * and starts initial address claiming. You can use this to init your message sending
      * to syncronize them with e.g., heartbeat.
+     *
+     * \note In future OnOpen may be called several times, if communication will be reopened
+     * by \ref Restart or driver error. Developer must take care that possible memory
+     * initializations will be handled properly in case OnOpen is called several times.
      */
     void SetOnOpen(void (*_OnOpen)());