N2kGroupFunction.h File Reference

Base and default group function PGN 126208 message handler class. More...

#include <cstring>
#include "NMEA2000_CompilerDefns.h"
#include "N2kMsg.h"

Include dependency graph for N2kGroupFunction.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	tN2kGroupFunctionHandler
	Base handler class for Group Functions. More...

Macros
#define	N2k_KEEP_TRANSMISSION_INTERVAL   0xffffffff
#define	N2k_MAX_TRANSMISSION_INTERVAL   0xfffffff0
#define	N2k_MAX_TRANSMISSION_INTERVAL_OFFSET   0xfffc
#define	N2k_RESTORE_TRANSMISSION_INTERVAL   0xfffffffe

Enumerations
enum	tN2kGroupFunctionCode {   N2kgfc_Request =0 , N2kgfc_Command =1 , N2kgfc_Acknowledge =2 , N2kgfc_Read =3 ,   N2kgfc_ReadReply =4 , N2kgfc_Write =5 , N2kgfc_WriteReply =6 }
	FunctionCode for the group function. More...
enum	tN2kGroupFunctionParameterErrorCode {   N2kgfpec_Acknowledge =0 , N2kgfpec_InvalidRequestOrCommandParameterField =1 , N2kgfpec_TemporarilyUnableToComply =2 , N2kgfpec_RequestOrCommandParameterOutOfRange =3 ,   N2kgfpec_AccessDenied =4 , N2kgfpec_RequestOrCommandNotSupported =5 , N2kgfpec_ReadOrWriteIsNotSupported =6 }
	Error Codes Command used by acknowledge group function. More...
enum	tN2kGroupFunctionPGNErrorCode {   N2kgfPGNec_Acknowledge =0 , N2kgfPGNec_PGNNotSupported =1 , N2kgfPGNec_PGNTemporarilyNotAvailable =2 , N2kgfPGNec_AccessDenied =3 ,   N2kgfPGNec_RequestOrCommandNotSupported =4 , N2kgfPGNec_DefinerTagNotSupported =5 , N2kgfPGNec_ReadOrWriteNotSupported =6 }
	PGN error code used by acknowledge group function. More...
enum	tN2kGroupFunctionTransmissionOrPriorityErrorCode {   N2kgfTPec_Acknowledge =0 , N2kgfTPec_TransmitIntervalOrPriorityNotSupported =1 , N2kgfTPec_TransmitIntervalIsLessThanMeasurementInterval =2 , N2kgfTPec_AccessDenied =3 ,   N2kgfTPec_RequestNotSupported =4 }
	Error codes Transmit interval used by acknowledge group function. More...

Detailed Description

Base and default group function PGN 126208 message handler class.

Group functions can be used for requesting, commanding and configuring other bus devices. Example setting depth sounder offset can be done by command group function. This is standard way and other devices should support it. Other common examples are changing device or system information, setting installation description, changing message period.

There are 7 different group functions defined by first field of PGN 126208

• Request group funtion is used to request specific transmit PGN from device.
• Command group function can be used to command device to change fields.
• Acknowledge group function is respond for for other devices command group function or request, read or write fields group function in case of error.
• Read fields group function is to request specific field from specific PGN from device.
• Read fields reply group function is for responding read fields group function request.
• Write fields group function is to write specific field on specific PGN on device.
• Write fields reply group function is for responding write fields group function.

Request group function is mandatory for all certified devices. The default handler can only respond "unsupported" to requests other than system PGNs. To fulfill certification requirement developer should inherit base class, write supported functions and register handler class to library with tNMEA2000::AddGroupFunctionHandler(). One can find examples for implementation from N2kGroupFunctionDefaultHandlers.h. See e.g., tN2kGroupFunctionHandlerForPGN126998.

Library has inherited default handlers for required system PGNs declared in N2kGroupFunctionDefaultHandlers.h . Those can be used as sample for other PGN group function handlers.

See also

[NMEA2000 Documentation PGN 126208 ] (https://web.archive.org/web/20170609033039/http://www.nmea.org/Assets/20140109%20nmea-2000-corrigendum-tc201401031%20pgn%20126208.pdf)

Definition in file N2kGroupFunction.h.

Macro Definition Documentation

N2k_KEEP_TRANSMISSION_INTERVAL

#define N2k_KEEP_TRANSMISSION_INTERVAL   0xffffffff

Definition at line 68 of file N2kGroupFunction.h.

N2k_MAX_TRANSMISSION_INTERVAL

#define N2k_MAX_TRANSMISSION_INTERVAL   0xfffffff0

Definition at line 70 of file N2kGroupFunction.h.

N2k_MAX_TRANSMISSION_INTERVAL_OFFSET

#define N2k_MAX_TRANSMISSION_INTERVAL_OFFSET   0xfffc

Definition at line 71 of file N2kGroupFunction.h.

N2k_RESTORE_TRANSMISSION_INTERVAL

#define N2k_RESTORE_TRANSMISSION_INTERVAL   0xfffffffe

Definition at line 69 of file N2kGroupFunction.h.

Enumeration Type Documentation

tN2kGroupFunctionCode

enum tN2kGroupFunctionCode

FunctionCode for the group function.

There are seven group functions associated with PGN 126208.
The Write Fields group function may be used to modify a device’s factory default PGN instances to create a unique device with unique PGN instance numbers.
The Read Fields group function can be similarly used to interrogate the current PGN instance values of any PGNs not being sent periodically.

Enumerator
N2kgfc_Request	This message requests the transmission of a specific set of data in a Parameter Group by setting variable parameters within theParameter Group specified by the field number. Field number and parameter value may appear in any order in this message. When multiple fields and parameters are specified the request is treated as an "AND" function. This PGN may be used to set the transmission interval and the delay before the first transmission.
N2kgfc_Command	The Command Group Function message is directed to a specific address, the Global Address (255) shall not be used. This command sets the value of one, some or all parameters in a Parameter Group. The number of parameters to set is in field 5, then follows the field number and the new value repeated for each of them. A Parameter Group may contain one group of parameters out of multiple instances where the instance number of the group is given in one field. A command to set any parameter of such a group must contain the field number and value of the group instance number.
N2kgfc_Acknowledge	The Acknowledgement reply is transmitted in response to a Request, Command, Read or Write Group Function Message. The Acknowledge Group Function shall be transmitted in response to every Command Message received, indicating acknowledgement or containing the appropriate Error Code. The Acknowledge Group Function is only required in response to a Request, Read fields or Write fields Group Function that cannot be satisfied. The Acknowledge Group function shall transmit all fields applicable to the Group Function being acknowledged, fields where the error does not exist are set to 0x0 (No Error/Acknowledge).
N2kgfc_Read	This Read Fields Group Function provides a means to read specific fields in a PGN. When Field 2 (PGN number) contains a non-proprietary PGN number, field 3, field 4 and field 5 are not included in this message. If the receiver of this message can comply, the receiver will send to the transmitter a Read Fields Reply Group Function. If the receiver cannot comply, an Acknowledge Group Function shall be sent.
N2kgfc_ReadReply	The Read Fields Reply Group Function is a reply to the Read Fields Group Function. When the Read Fields Group Function is received, if the receiver can comply, the Read Fields Reply Group Function will be transmitted with the resulting read values.
N2kgfc_Write	This Write Group Function is especially useful when configuring an instance or reference to be used by a node when transmitting a PGN such as PGN 127508. Use Fields 7, 9 and 10 to identify the currently assigned instance value. Use Fields 8, 13 and 14 to identify the new assigned instance value. When Field 2 (PGN number) contains a non-proprietary PGN number, field 3, field 4 and field 5 are not included in this message. If the receiver of this message can comply, the receiver will send to the transmitter a Write Fields Reply Group Function. If the receiver cannot comply, an Acknowledge Group Function shall be sent.
N2kgfc_WriteReply	The Write Fields Reply Group Function is a reply to the Write Fields Group Function. When the Write Fields Group Function is received, if the receiver can comply, the Write Fields Reply Group Function will be transmitted with the resulting values. If a parameter value is accepted then the modified value will be returned. If a parameter value is not accepted, the original value will be returned.

Definition at line 85 of file N2kGroupFunction.h.

tN2kGroupFunctionParameterErrorCode

enum tN2kGroupFunctionParameterErrorCode

Error Codes Command used by acknowledge group function.

This error code carried inside the acknowledge group function gives information, if the Request, Command, Read or Write Group Function Message can be satisfied by the receiving device.

Enumerator
N2kgfpec_Acknowledge	Acknowledge positive, no error
N2kgfpec_InvalidRequestOrCommandParameterField	Invalid request or command parameter field
N2kgfpec_TemporarilyUnableToComply	Temporarily unable to comply
N2kgfpec_RequestOrCommandParameterOutOfRange	Request or command parameter out-of-range
N2kgfpec_AccessDenied	Access denied
N2kgfpec_RequestOrCommandNotSupported	Request or Command is not supported
N2kgfpec_ReadOrWriteIsNotSupported	Read or Write is not supported

Definition at line 216 of file N2kGroupFunction.h.

tN2kGroupFunctionPGNErrorCode

enum tN2kGroupFunctionPGNErrorCode

PGN error code used by acknowledge group function.

This error code carried inside the acknowledge group function gives information, if the Request, Command, Read or Write Group Function Message can be satisfied by the receiving device.

Enumerator
N2kgfPGNec_Acknowledge	Acknowledge positive, no error
N2kgfPGNec_PGNNotSupported	PGN is not supported
N2kgfPGNec_PGNTemporarilyNotAvailable	PGN is temporarily not available
N2kgfPGNec_AccessDenied	Access denied
N2kgfPGNec_RequestOrCommandNotSupported	Request or Command is not supported
N2kgfPGNec_DefinerTagNotSupported	Definer Tag is not supported
N2kgfPGNec_ReadOrWriteNotSupported	Read or Write is not supported

Definition at line 169 of file N2kGroupFunction.h.

tN2kGroupFunctionTransmissionOrPriorityErrorCode

enum tN2kGroupFunctionTransmissionOrPriorityErrorCode

Error codes Transmit interval used by acknowledge group function.

This error code carried inside the acknowledge group function gives information, if the Request, Command, Read or Write Group Function Message can be satisfied by the receiving device.

Enumerator
N2kgfTPec_Acknowledge	Acknowledge positive, no error
N2kgfTPec_TransmitIntervalOrPriorityNotSupported	Transmit Interval /Priority not supported
N2kgfTPec_TransmitIntervalIsLessThanMeasurementInterval	Transmit interval is less than measurement/ calculation interval
N2kgfTPec_AccessDenied	Access denied
N2kgfTPec_RequestNotSupported	Request is not supported

Definition at line 194 of file N2kGroupFunction.h.