CT2KLib Public API

Functions for using the CT2KLibrary. More...

Data Structures

struct  CONFIGURATION_INFORMATION_STRING_T
 Defines the structure of strings used for transmitting and receiving PGN 1F016. More...
 
struct  CAN_FRAME_T
 CAN message structure. More...
 
struct  CAN_DRIVER_FUNCTIONS_T
 Structure used for the CAN Driver. More...
 
struct  PGNDesc
 PGN Description structure. More...
 
struct  PGNDOB
 Data object that contains information about a transmitted or received message. More...
 
struct  DEVICE_NAME_FIELDS
 Structure used for setting the Device Name. More...
 
struct  DEVNAME
 
struct  NETDEVICE
 Device information. More...
 
struct  CTLIB_PROD_INFO
 Product Information Structure. More...
 
struct  NMEA2000SpecVersion
 NMEA library version structure. More...
 
struct  INPUT_PARAMS_T
 Structure of Input Parameters. More...
 
struct  PORTS_CONFIG_T
 Structure Containing the Port Configuration the Library will use. More...
 
struct  NMEA_REQUEST_FAILED_FIELDS_T
 
struct  NAME_CHANGE_COMMAND_RESPONSE_T
 

Macros

#define PGN   int32_t
 Definitions of other types.
 
#define PGNGRPFUNC   uint8_t
 
#define INSTANCE   int8_t
 
#define PARAMETER   int16_t
 
#define CANBUF   int8_t
 
#define NETADDR   uint8_t
 
#define PGN_AddressClaim   60928
 NMEA2000 & J1939 PGN Required and used.
 
#define PGN_CommandedAddress   65240
 
#define PGN_Request   59904
 
#define PGN_Acknowledge   59392
 
#define PGN_NMEARequest   126208
 
#define PGN_Heartbeat   126993
 
#define PGN_ProductInformation   126996
 
#define PGN_ConfigurationInformation   126998
 
#define PGN_NMEAPGNList   126464
 
#define PGN_ISOConnectMgmt   60416
 Multi-Packet Specific PGNS.
 
#define PGN_ISODataTransport   60160
 
#define SINGLE_PKT_SIZE   8
 Packet Sizes.
 
#define FAST_PKT_SIZE   223
 
#define MULTI_PKT_SIZE   1785
 
#define PGN_CONFIGURATIONINFORMATION_SIZE   70
 PGN 1F016.
 
#define BYTES_IN_RAW_FRAME   8
 This is the max number of Bytes in a Raw CAN Frame.
 

Typedefs

typedef uint32_t __BIT
 Type definitions.
 
typedef uint32_t CAN_PORT_T
 
typedef void(* CT2KLibDiagnosticPrint_T) (const char *pFormatStr, va_list args, void *userData)
 Type define for CTKLib's driver level print to console function.
 
typedef int32_t(* CT2KLibCanOpen_T) (CAN_PORT_T canPort, void *userData)
 Type define for CT2KLib to Open the CAN Port.
 
typedef int32_t(* CT2KLibCanClose_T) (CAN_PORT_T canPort, void *userData)
 Type define for CT2KLib to Close the CAN Port.
 
typedef BUS_STATE_T(* CT2KLibGetBusState_T) (CAN_PORT_T canPort, void *userData)
 Type define for CT2KLib to get the current Bus State.
 
typedef int32_t(* CT2KLibTransmitFrame_T) (CAN_PORT_T canPort, CAN_FRAME_T *pFrame, void *userData)
 Type define for CT2KLib to transmit a frame.
 
typedef int32_t(* CT2KLibReceiveFrameWait_T) (CAN_PORT_T *pCanPorts, uint32_t LengthOf_pCanPorts, CAN_FRAME_T *pFrame, CAN_PORT_T *pFromPort, uint32_t timeoutMs, void *userData)
 Type define for CT2KLib to call to receive a Frame.
 
typedef int32_t(* CT2KLibBitRateSet_T) (CAN_PORT_T canPort, uint32_t bitRate, void *userData)
 Type define for CT2KLib to call to set the Bit Rate of the Bus.
 
typedef int(* RCVRCB) (PGNDOB *pDOB, uintptr_t userData)
 Type Definition for Received PGNs Callbacks.
 
typedef int(* ISOCallback_EA00) (PGNDOB *pDOB, uintptr_t userData)
 Type Definition for PGN Request Callbacks.
 
typedef int(* CTLIB_ADDRCLAIM_CB) (CAN_PORT_T i8Port, NETDEVICE *pNetDevice, uintptr_t userData)
 Type Definition for Address Claim Callback.
 
typedef void(* MLTIPCKTSENDCALLBACK) (uintptr_t userData)
 Type Definition for Multi-Packet Send Callback. Is executed after a Multi-Packet has been sent.
 
typedef bool(* COMMANDEDADDRESSCALLBACK) (DEVNAME *devName, NETADDR commandedAddress, uintptr_t userData)
 Type definition for Commanded address callback. Is executed after a commanded address message has been received (PGN 65240).
 
typedef void(* COMMANDCONFIGURATIONINFORMATIONCALLBACK) (const CAN_PORT_T i8Port, const CONFIGURATION_INFORMATION_STRING_T *pString1, GROUP_FUNCTION_PARAMETER_ERROR_CODE_T *pString1ErrCode, const CONFIGURATION_INFORMATION_STRING_T *pString2, GROUP_FUNCTION_PARAMETER_ERROR_CODE_T *pString2ErrCode, uintptr_t userData)
 Type definition for group function command (PGN 1ED00) Configuration information(PGN 1F016) .
 
typedef int(* NMEA2K_RQ_CMD) (PGNDOB *pDOB, uintptr_t userData)
 NMEA2000 Level A Request/Command/Acknowledge PGN Callbacks.
 
typedef NAME_CHANGE_COMMAND_RESPONSE_T(* CommandedNameChangeNotification) (CAN_PORT_T i8Port, DEVNAME commandedNameInformation, uintptr_t userData)
 Type Definition for Name Change Command Notification.
 
typedef GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_T(* RequestedHeartbeatUpdateRateChangeNotification) (CAN_PORT_T i8Port, uint32_t requestedUpdateRate_ms, NETADDR sourceDevice, uintptr_t userData)
 Type definition for Heartbeat update rate notification.
 

Enumerations

enum  STRING_TYPE_T {
  STRING_TYPE_UNICODE = 0x00 ,
  STRING_TYPE_ASCII = 0x01 ,
  STRING_TYPE_UNKNOWN = 0xFF
}
 Defines string types used within PGN 1F016 for configuration information strings. More...
 
enum  BUS_STATE_T {
  BUS_STATE_OK = 0u ,
  BUS_STATE_WARNING = 1u ,
  BUS_STATE_ERROR = 2u
}
 Enum for Possible Bus States. More...
 
enum  CTCAN_STATUS {
  CTCR_OK ,
  CTCR_IDLE ,
  CTCR_UNKNOWN_PGN ,
  CTCR_TABLE_FULL ,
  CTCR_HEAP_ALLOC_FAIL ,
  CTCR_HEAP_DEALLOC_FAIL ,
  CTCR_NOT_FOUND ,
  CTCR_NEW_DATA ,
  CTCR_NO_DATA ,
  CTCR_INVALID_PORT ,
  CTCR_BUS_OFF ,
  CTCR_BUS_WARNING ,
  CTCR_LIB_BUSY ,
  CTCR_LIB_NOT_INIT ,
  CTCR_DRV_RX_FAILURE ,
  CTCR_DRV_TX_FAILURE ,
  CTCR_PGN_DUPLICATE ,
  CTCR_INVALID_CALL ,
  CTCR_COUNT
}
 Return codes that the Library uses. More...
 
enum  PROTOCOL {
  P_SINGLEPACKET = 0u ,
  P_FASTPACKET = 1u ,
  P_MULTIPACKET = 2u
}
 Supported Protocols. More...
 
enum  MULTIPKT_TYPE_T {
  MULTIPKT_TYPE_NONE = 0 ,
  MULTIPKT_TYPE_BAM = 1 ,
  MULTIPKT_TYPE_CMDT = 2
}
 Multi-packet types. More...
 
enum  DIRECTION {
  DIRECTION_TX_AND_RX = 0u ,
  DIRECTION_TX_ONLY = 1u ,
  DIRECTION_RX_ONLY = 2u
}
 Direction of the message. More...
 
enum  PGN_LIST_MODE_T {
  PGN_LIST_MODE_J1939 = 0 ,
  PGN_LIST_MODE_NMEA2000 = 10
}
 The list mode for the message. More...
 
enum  CTSTATE {
  CTSTATE_ONLINE ,
  CTSTATE_OFFLINE ,
  CTSTATE_CONFIGURING ,
  CTSTATE_END
}
 CT2KLibrary State. More...
 
enum  DBG_LVL_T {
  DBG_LVL_NORMAL = 0x01 ,
  DBG_LVL_NORMAL_TX = 0x02 ,
  DBG_LVL_NORMAL_RX = 0x04 ,
  DBG_LVL_VERBOSE = 0x08 ,
  DBG_LVL_INFO = 0x10 ,
  DBG_LVL_TEMPORARY_DEBUG = 0x20
}
 Debugging level. More...
 
enum  PORT_MODE_T {
  PORT_MODE_NMEA2000 = 10 ,
  PORT_MODE_J1939 = 20
}
 The mode of the port. More...
 
enum  NMEA_REQUEST_T {
  NMEA_REQUEST_REQUEST = 0 ,
  NMEA_REQUEST_COMMAND ,
  NMEA_REQUEST_ACKNOWLEDGE ,
  NMEA_REQUEST_READ_FIELDS ,
  NMEA_REQUEST_READ_FIELDS_REPLY ,
  NMEA_REQUEST_WRITE_FIELDS ,
  NMEA_REQUEST_WRITE_FIELDS_REPLY
}
 NMEA2000 Level A Request/Command/Acknowledge PGN values. More...
 
enum  GROUP_FUNCTION_PGN_ERROR_CODE_T {
  GROUP_FUNCTION_PGN_ERROR_CODE_NoError ,
  GROUP_FUNCTION_PGN_ERROR_CODE_PGNNotSupported ,
  GROUP_FUNCTION_PGN_ERROR_CODE_PGNTemporarilyNotAvailable ,
  GROUP_FUNCTION_PGN_ERROR_CODE_AccessDenied ,
  GROUP_FUNCTION_PGN_ERROR_CODE_RequestOrCommandNotSupported ,
  GROUP_FUNCTION_PGN_ERROR_CODE_DefinerTagNotSupported ,
  GROUP_FUNCTION_PGN_ERROR_CODE_ReadOrWriteNotSupported
}
 NMEA2000 ACK VALUES. More...
 
enum  GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_T {
  GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_NoError = 0 ,
  GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_TransmitIntervalOrPriorityNotSupported ,
  GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_TransmitIntervalIsLessThanMeasurementCalculationInterval ,
  GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_AccessDenied ,
  GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_RequestNotSupported
}
 
enum  GROUP_FUNCTION_PARAMETER_ERROR_CODE_T {
  GROUP_FUNCTION_PARAMETER_ERROR_CODE_NoError = 0 ,
  GROUP_FUNCTION_PARAMETER_ERROR_CODE_InvalidRequestOrCommandParmeterField ,
  GROUP_FUNCTION_PARAMETER_ERROR_CODE_TemporaryUnableToComply ,
  GROUP_FUNCTION_PARAMETER_ERROR_CODE_RequestOrCommandParameterOutOfRange ,
  GROUP_FUNCTION_PARAMETER_ERROR_CODE_AccessDenied ,
  GROUP_FUNCTION_PARAMETER_ERROR_CODE_RequestOrCommandIsNotSupported ,
  GROUP_FUNCTION_PARAMETER_ERROR_CODE_ReadOrWriteIsNotSupported
}
 

Functions

INPUT_PARAMS_T CT2KLibGetPGNTableRequiredMemorySize (const PGNDesc *pDesc, uint32_t tableSize, uint16_t numberOfPorts)
 Calculate the required size based on the provided PGNDesc Table.
 
void CT2KLibInitEx (INPUT_PARAMS_T *inputParams, PORTS_CONFIG_T *ports, uint32_t numberOfPorts, CAN_DRIVER_FUNCTIONS_T canDriverFunctions)
 Initialises the CT2K Library.
 
void CT2KLibDeinit (void)
 De-initialises the CT2K Library.
 
CTCAN_STATUS CT2KLibStart (void)
 Open the CAN Port and start the Library.
 
bool CT2KLibIsRunning (void)
 Query the State of the Library.
 
void CT2KLibStop (void)
 Stop the Library.
 
CTCAN_STATUS CT2KLibRestartCANPorts (PORTS_CONFIG_T *ports, uint32_t numberOfPorts)
 Restart the CAN Ports with a different configuration.
 
CTCAN_STATUS CT2KLibEnableDebug (uint32_t loggedMessagesBitmask, CT2KLibDiagnosticPrint_T printFunction, void *userData)
 Enable Debug Prints.
 
CTCAN_STATUS CT2KLibInstallPGNTable (CAN_PORT_T portNumber, const PGNDesc *pDesc, uint16_t tableSize)
 Install the PGN Table in the Library Duplicates are not allowed and will trigger an assert and a fail.
 
CTCAN_STATUS CT2KLibUninstallPGNTable (CAN_PORT_T portNumber, const PGNDesc *pDesc)
 Uninstall a PGN Table Installed using CT2KLibInstallPGNTable()
 
CTSTATE CT2KLibGetState (CAN_PORT_T i8Port)
 Get the Library status on the specified Port.
 
CTCAN_STATUS CT2KLibSetAppProductInfo (CAN_PORT_T i8Port, CTLIB_PROD_INFO *pProdInfo)
 Set and the Product Information via the NMEA2000 PGN.
 
CTCAN_STATUS CT2KLibSetConfigurationInformation_1F016 (CAN_PORT_T i8Port, const char *field1, size_t field1_Length, const char *field2, size_t field2_Length, const char *field3, size_t field3_Length)
 Set the information shared with other devices via the Configuration Information PGN (1F016).
 
CTCAN_STATUS CT2KLibSetConfigurationInformation_1F016_EX (CAN_PORT_T i8Port, const CONFIGURATION_INFORMATION_STRING_T *field1, const CONFIGURATION_INFORMATION_STRING_T *field2, const CONFIGURATION_INFORMATION_STRING_T *field3)
 Set the information shared with other devices via the Configuration Information PGN (1F016).
 
CTCAN_STATUS CT2KLibSetAddress (CAN_PORT_T i8Port, DEVNAME *pName, NETADDR u8SeedAddress)
 Assigns the name and address to the device.
 
CTCAN_STATUS CT2KLibAddValidAddressRange (CAN_PORT_T i8Port, uint8_t startAddress, uint8_t endAddress)
 Restricts the addressses that can be assigned to the device.
 
CTCAN_STATUS CT2KLibResetValidAddressRange (CAN_PORT_T i8Port)
 Resets the valid address range, cancelling the effect of any previous calls to CT2KLibAddValidAddressRange.
 
NETADDR CT2KLibGetMyAddress (CAN_PORT_T i8Port)
 Returns the devices CAN Address for the specified port.
 
void CT2KLibPackDeviceNameFields (const DEVICE_NAME_FIELDS *pFields, uint8_t *pPackedFields)
 Pack DEVICE_NAME_FIELDS struct into an 8 byte array.
 
void CT2KLibUnpackDeviceNameFields (const uint8_t *pPackedFields, DEVICE_NAME_FIELDS *pFields)
 Unpack 8 byte array into DEVICE_NAME_FIELDS struct.
 
const NMEA2000SpecVersion * CTLIBGetNMEA2KLibVersion (void)
 Get the NMEA2000 Database Version the library uses.
 
const char * CT2KGetLibVersion (void)
 Get the version number of CT2KLib.
 
CTCAN_STATUS CT2KLibSnoopNetwork (CAN_PORT_T i8Port)
 Sends Global Address Claim request using the Request PGN on the specified port.
 
CTCAN_STATUS CT2KSetPGNReceiveCallback (CAN_PORT_T i8Port, PGN i32PGN, RCVRCB rCB, uintptr_t userdata)
 Register a Callback function when a Message associated with the Specified PGN is received.
 
CTCAN_STATUS CT2KClearPGNReceiveCallback (CAN_PORT_T i8Port, PGN i32PGN)
 Deregister the Callback function that was registered with CT2KSetPGNReceiveCallback()
 
CTCAN_STATUS CT2KSetPGNISORequestReceivedCallback (CAN_PORT_T i8Port, PGN i32PGN, ISOCallback_EA00 regCB, uintptr_t userData)
 Register a Callback function when a Message associated with the Specified PGN is received.
 
CTCAN_STATUS CT2KLibAddrClaimReceiveCallback (CTLIB_ADDRCLAIM_CB AddrClaimCB, uintptr_t userData)
 Register a callback function that will be triggered when an address claim occurs.
 
CTCAN_STATUS CT2KLibSendPGN (CAN_PORT_T i8Port, NETADDR u8DestAddr, PGN i32PGN, void *pData, uint16_t u16DataLen)
 Send a Message using the specified PGN. Valid only for Single and Fast Packets.
 
CTCAN_STATUS CT2KLibSendPGNNow (CAN_PORT_T i8Port, NETADDR u8DestAddr, PGN i32PGN, void *pData, uint16_t u16DataLen)
 Functions the same as CT2KLibSendPGN Except allows you to mark a frame as to be sent immediately.
 
CTCAN_STATUS CT2KLibSendPGNMultiPkt (CAN_PORT_T i8Port, NETADDR u8DestAddr, PGN i32PGN, void *pData, uint16_t u16DataLen, MLTIPCKTSENDCALLBACK multiPktClbk, uintptr_t userdata, bool isBAM)
 Send a Message using the specified PGN.
 
CTCAN_STATUS CT2KSetGroupFunctionCallback (CAN_PORT_T i8Port, PGN i32PGN, NMEA2K_RQ_CMD regCB, uintptr_t userData)
 NMEA 2000 Level A - Request, Command, Acknowledge PGN Functions.
 
CTCAN_STATUS CT2KNMEA2KSendAcknowledge (CAN_PORT_T i8Port, PGN i32PGN, NETADDR u8DestAddr, MULTIPKT_TYPE_T transmitMethod, GROUP_FUNCTION_PGN_ERROR_CODE_T pgnErrorCode, GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_T transmissionErrorCode, uint8_t numberOfRequestedParams, NMEA_REQUEST_FAILED_FIELDS_T *failedFields, uint8_t length)
 Send a NMEA2K Acknowledge Message (PGN 126208)
 
CTCAN_STATUS CT2KRegisterCallbackOnCommandedNameChange (CAN_PORT_T i8Port, CommandedNameChangeNotification callBack, uintptr_t userData)
 NMEA 2000 Level A - Commanded Name (0xEE00) Functionality.
 
CTCAN_STATUS CT2KRegisterCallbackOnRequestedHeartbeatRateChange (CAN_PORT_T i8Port, RequestedHeartbeatUpdateRateChangeNotification callback, uintptr_t userData)
 This allows you to register for a callback from the library if we receive a request to change the update rate of the heartbeat message.
 
CTCAN_STATUS CT2KSetHeartbeatUpdateRate (CAN_PORT_T i8Port, uint32_t updateRate_ms)
 This allows you to set the update rate of the NMEA2000 heartbeat message.
 
CTCAN_STATUS CT2KLibRegisterCommandedAddressCallback (CAN_PORT_T i8Port, COMMANDEDADDRESSCALLBACK callback, uintptr_t userData)
 This allows registration of a callback to check whether or not the device should change to the specified address on receipt of the CommandedAddress PGN.
 
CTCAN_STATUS CT2KLibRegisterCommandedConfigurationInformationCallback (COMMANDCONFIGURATIONINFORMATIONCALLBACK callback, uintptr_t userData)
 This allows registration of a callback to check whether or not the device should change it's configuration information to the specified strings on receipt of the Configuration Information PGN change command.
 

Detailed Description

Functions for using the CT2KLibrary.

Macro Definition Documentation

◆ BYTES_IN_RAW_FRAME

#define BYTES_IN_RAW_FRAME   8

This is the max number of Bytes in a Raw CAN Frame.

Definition at line 111 of file CT2KLib.h.

◆ CANBUF

#define CANBUF   int8_t

Definition at line 40 of file CT2KLib.h.

◆ FAST_PKT_SIZE

#define FAST_PKT_SIZE   223

Definition at line 62 of file CT2KLib.h.

◆ INSTANCE

#define INSTANCE   int8_t

Definition at line 38 of file CT2KLib.h.

◆ MULTI_PKT_SIZE

#define MULTI_PKT_SIZE   1785

Definition at line 63 of file CT2KLib.h.

◆ NETADDR

#define NETADDR   uint8_t

Definition at line 41 of file CT2KLib.h.

◆ PARAMETER

#define PARAMETER   int16_t

Definition at line 39 of file CT2KLib.h.

◆ PGN

#define PGN   int32_t

Definitions of other types.

Definition at line 36 of file CT2KLib.h.

◆ PGN_Acknowledge

#define PGN_Acknowledge   59392

Definition at line 48 of file CT2KLib.h.

◆ PGN_AddressClaim

#define PGN_AddressClaim   60928

NMEA2000 & J1939 PGN Required and used.

Definition at line 45 of file CT2KLib.h.

◆ PGN_CommandedAddress

#define PGN_CommandedAddress   65240

Definition at line 46 of file CT2KLib.h.

◆ PGN_ConfigurationInformation

#define PGN_ConfigurationInformation   126998

Definition at line 52 of file CT2KLib.h.

◆ PGN_CONFIGURATIONINFORMATION_SIZE

#define PGN_CONFIGURATIONINFORMATION_SIZE   70

PGN 1F016.

NMEA spec gives a maximum size of fields as 70 ASCII characters or 35 Unicode utf-16 characters, This constant should be used for manipulation of the strings

Definition at line 71 of file CT2KLib.h.

◆ PGN_Heartbeat

#define PGN_Heartbeat   126993

Definition at line 50 of file CT2KLib.h.

◆ PGN_ISOConnectMgmt

#define PGN_ISOConnectMgmt   60416

Multi-Packet Specific PGNS.

Definition at line 56 of file CT2KLib.h.

◆ PGN_ISODataTransport

#define PGN_ISODataTransport   60160

Definition at line 57 of file CT2KLib.h.

◆ PGN_NMEAPGNList

#define PGN_NMEAPGNList   126464

Definition at line 53 of file CT2KLib.h.

◆ PGN_NMEARequest

#define PGN_NMEARequest   126208

Definition at line 49 of file CT2KLib.h.

◆ PGN_ProductInformation

#define PGN_ProductInformation   126996

Definition at line 51 of file CT2KLib.h.

◆ PGN_Request

#define PGN_Request   59904

Definition at line 47 of file CT2KLib.h.

◆ PGNGRPFUNC

#define PGNGRPFUNC   uint8_t

Definition at line 37 of file CT2KLib.h.

◆ SINGLE_PKT_SIZE

#define SINGLE_PKT_SIZE   8

Packet Sizes.

Definition at line 61 of file CT2KLib.h.

Typedef Documentation

◆ __BIT

typedef uint32_t __BIT

Type definitions.

Parameters
Includes

Definition at line 31 of file CT2KLib.h.

◆ CAN_PORT_T

typedef uint32_t CAN_PORT_T

Definition at line 132 of file CT2KLib.h.

◆ COMMANDCONFIGURATIONINFORMATIONCALLBACK

typedef void(* COMMANDCONFIGURATIONINFORMATIONCALLBACK) (const CAN_PORT_T i8Port, const CONFIGURATION_INFORMATION_STRING_T *pString1, GROUP_FUNCTION_PARAMETER_ERROR_CODE_T *pString1ErrCode, const CONFIGURATION_INFORMATION_STRING_T *pString2, GROUP_FUNCTION_PARAMETER_ERROR_CODE_T *pString2ErrCode, uintptr_t userData)

Type definition for group function command (PGN 1ED00) Configuration information(PGN 1F016) .

Is executed after a Configuration information command has been received The function should check that the provided strings are acceptable, and alter the states of the error codes pointed to by the error parameters.

See also
CONFIGURATION_INFORMATION_STRING_T

Definition at line 519 of file CT2KLib.h.

◆ COMMANDEDADDRESSCALLBACK

typedef bool(* COMMANDEDADDRESSCALLBACK) (DEVNAME *devName, NETADDR commandedAddress, uintptr_t userData)

Type definition for Commanded address callback. Is executed after a commanded address message has been received (PGN 65240).

Definition at line 514 of file CT2KLib.h.

◆ CommandedNameChangeNotification

typedef NAME_CHANGE_COMMAND_RESPONSE_T(* CommandedNameChangeNotification) (CAN_PORT_T i8Port, DEVNAME commandedNameInformation, uintptr_t userData)

Type Definition for Name Change Command Notification.

Definition at line 530 of file CT2KLib.h.

◆ CT2KLibBitRateSet_T

typedef int32_t(* CT2KLibBitRateSet_T) (CAN_PORT_T canPort, uint32_t bitRate, void *userData)

Type define for CT2KLib to call to set the Bit Rate of the Bus.

If this function is not populated, it will assume the baud rate set failed.

Parameters
canPortis the index of the port, 0 indexed.
bitRateis the bit rate, typically 250000
userDatawill be whatever the userData was set to when it was called (eg this).
Returns
0 if succeeded
-1 if failed

Definition at line 212 of file CT2KLib.h.

◆ CT2KLibCanClose_T

typedef int32_t(* CT2KLibCanClose_T) (CAN_PORT_T canPort, void *userData)

Type define for CT2KLib to Close the CAN Port.

If this function is not populated, it will Return Failure.

Parameters
canPortis the index of the port, 0 indexed.
userDatawill be whatever the userData was set to when it was called (eg this).
Returns
0 if succeeded
-1 if failed

Definition at line 163 of file CT2KLib.h.

◆ CT2KLibCanOpen_T

typedef int32_t(* CT2KLibCanOpen_T) (CAN_PORT_T canPort, void *userData)

Type define for CT2KLib to Open the CAN Port.

If this function is not populated, it will Return Failure.

Parameters
canPortis the index of the port, 0 indexed.
userDatawill be whatever the userData was set to when it was called (eg this).
Returns
0 if succeeded
-1 if failed

Definition at line 152 of file CT2KLib.h.

◆ CT2KLibDiagnosticPrint_T

typedef void(* CT2KLibDiagnosticPrint_T) (const char *pFormatStr, va_list args, void *userData)

Type define for CTKLib's driver level print to console function.

Parameters
pFormatStrthis will be a printf style format string
argswill be the arguments to go with the pFormatStr
userDatawill be whatever the userData was set to when it was called (eg this).
Returns
none

Definition at line 141 of file CT2KLib.h.

◆ CT2KLibGetBusState_T

typedef BUS_STATE_T(* CT2KLibGetBusState_T) (CAN_PORT_T canPort, void *userData)

Type define for CT2KLib to get the current Bus State.

If this function is not populated, it will assume a BUS_STATE_ERROR State.

Parameters
canPortis the index of the port, 0 indexed.
userDatawill be whatever the userData was set to when it was called (eg this).
Returns
BUS_STATE_T

Definition at line 173 of file CT2KLib.h.

◆ CT2KLibReceiveFrameWait_T

typedef int32_t(* CT2KLibReceiveFrameWait_T) (CAN_PORT_T *pCanPorts, uint32_t LengthOf_pCanPorts, CAN_FRAME_T *pFrame, CAN_PORT_T *pFromPort, uint32_t timeoutMs, void *userData)

Type define for CT2KLib to call to receive a Frame.

If this function is not populated, it will assume there are no frames to receive

Parameters
pCanPortsis an array of can ports to wait for a frame on
LengthOf_pCanPortsis the length of the array of CAN_PORT_T that is passed in as pCanPorts
pFrameis a pointer to a frame, if successful, the received frame will be copied here.
pFromPortis a pointer to a port, if successful, will denote which CAN port pFrame was received from.
timeoutMsis the number of milliseconds to wait for a CAN frame to be received.
userDatawill be whatever the userData was set to when it was called (eg this).
Returns
0 if succeeded
-1 if failed

Definition at line 200 of file CT2KLib.h.

◆ CT2KLibTransmitFrame_T

typedef int32_t(* CT2KLibTransmitFrame_T) (CAN_PORT_T canPort, CAN_FRAME_T *pFrame, void *userData)

Type define for CT2KLib to transmit a frame.

If this function is not populated, it will assume the transmit failed.

Parameters
canPortis the index of the port, 0 indexed.
pFrameis a pointer to the Frame that should be transmitted
userDatawill be whatever the userData was set to when it was called (eg this).
Returns
0 if succeeded
-1 if failed

Definition at line 185 of file CT2KLib.h.

◆ CTLIB_ADDRCLAIM_CB

typedef int(* CTLIB_ADDRCLAIM_CB) (CAN_PORT_T i8Port, NETDEVICE *pNetDevice, uintptr_t userData)

Type Definition for Address Claim Callback.

Definition at line 508 of file CT2KLib.h.

◆ ISOCallback_EA00

typedef int(* ISOCallback_EA00) (PGNDOB *pDOB, uintptr_t userData)

Type Definition for PGN Request Callbacks.

If -1 is returned in response to an addressed request, then a NACK will be sent using the ISO Acknowledgement PGN (59392)

Definition at line 505 of file CT2KLib.h.

◆ MLTIPCKTSENDCALLBACK

typedef void(* MLTIPCKTSENDCALLBACK) (uintptr_t userData)

Type Definition for Multi-Packet Send Callback. Is executed after a Multi-Packet has been sent.

Definition at line 511 of file CT2KLib.h.

◆ NMEA2K_RQ_CMD

typedef int(* NMEA2K_RQ_CMD) (PGNDOB *pDOB, uintptr_t userData)

NMEA2000 Level A Request/Command/Acknowledge PGN Callbacks.

Type Definition for NMEA2K Request/Command PGNs Callbacks

Definition at line 527 of file CT2KLib.h.

◆ RCVRCB

typedef int(* RCVRCB) (PGNDOB *pDOB, uintptr_t userData)

Type Definition for Received PGNs Callbacks.

Definition at line 501 of file CT2KLib.h.

◆ RequestedHeartbeatUpdateRateChangeNotification

typedef GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_T(* RequestedHeartbeatUpdateRateChangeNotification) (CAN_PORT_T i8Port, uint32_t requestedUpdateRate_ms, NETADDR sourceDevice, uintptr_t userData)

Type definition for Heartbeat update rate notification.

i8Port is the CAN port; requestedUpdateRate_ms is the requested update rate in milliseconds; sourceDevice is the source address of the device sending the request.

Definition at line 534 of file CT2KLib.h.

Enumeration Type Documentation

◆ BUS_STATE_T

Enum for Possible Bus States.

Enumerator
BUS_STATE_OK 

This represents the bus in an OK state (error count <96)

BUS_STATE_WARNING 

This represents a bus with problems (96< error count <256)

BUS_STATE_ERROR 

This represents a "bus off" (256 < error count)

Definition at line 125 of file CT2KLib.h.

◆ CTCAN_STATUS

Return codes that the Library uses.

Enumerator
CTCR_OK 

Success.

CTCR_IDLE 

internal operation

CTCR_UNKNOWN_PGN 

specified PGN is UNKNOWN

CTCR_TABLE_FULL 

referenced table is full

CTCR_HEAP_ALLOC_FAIL 

a request to allocate heap failed

CTCR_HEAP_DEALLOC_FAIL 

a request to de-allocate heap failed

CTCR_NOT_FOUND 

requested item was not found

CTCR_NEW_DATA 

New Data from routine.

CTCR_NO_DATA 

No Data from routine.

CTCR_INVALID_PORT 

Invalid Comm Port.

CTCR_BUS_OFF 

CAN Bus is in Bus-Off condition (no further transmissions possible)

CTCR_BUS_WARNING 

CAN Bus is at Error Warning Level Status.

CTCR_LIB_BUSY 

tick was called while library was already running

CTCR_LIB_NOT_INIT 

Library not initialised.

CTCR_DRV_RX_FAILURE 

CAN Driver receive failure.

CTCR_DRV_TX_FAILURE 

CAN Driver transmit failure.

CTCR_PGN_DUPLICATE 

PGNs are duplicate.

CTCR_INVALID_CALL 

Invalid parameter or other violation when calling a library API function.

CTCR_COUNT 

Size of CTCAN_STATUS.

Definition at line 251 of file CT2KLib.h.

◆ CTSTATE

enum CTSTATE

CT2KLibrary State.

Enumerator
CTSTATE_ONLINE 

Allows reads/writes of PGNs.

CTSTATE_OFFLINE 

Stop all bus activity.

CTSTATE_CONFIGURING 

Can only receive in this state.

CTSTATE_END 

Invalid State.

Definition at line 382 of file CT2KLib.h.

◆ DBG_LVL_T

enum DBG_LVL_T

Debugging level.

Enumerator
DBG_LVL_NORMAL 

Log contains normal debugging info.

DBG_LVL_NORMAL_TX 

Log contains normal debugging info for Transmit.

DBG_LVL_NORMAL_RX 

Log contains normal debugging info for Receive.

DBG_LVL_VERBOSE 

Log contains extra information including DOB and Pool Allocation.

DBG_LVL_INFO 

Log contains max one line for each Tx/Rx.

DBG_LVL_TEMPORARY_DEBUG 

Log contains temporary information for debugging.

Definition at line 391 of file CT2KLib.h.

◆ DIRECTION

enum DIRECTION

Direction of the message.

Enumerator
DIRECTION_TX_AND_RX 

This indicates that the application/library both transmits AND received this message.

DIRECTION_TX_ONLY 

This indicates that the application/library ONLY transmits this message.

DIRECTION_RX_ONLY 

This indicates that the application/library ONLY receives this message.

Definition at line 291 of file CT2KLib.h.

◆ GROUP_FUNCTION_PARAMETER_ERROR_CODE_T

Enumerator
GROUP_FUNCTION_PARAMETER_ERROR_CODE_NoError 
GROUP_FUNCTION_PARAMETER_ERROR_CODE_InvalidRequestOrCommandParmeterField 
GROUP_FUNCTION_PARAMETER_ERROR_CODE_TemporaryUnableToComply 
GROUP_FUNCTION_PARAMETER_ERROR_CODE_RequestOrCommandParameterOutOfRange 
GROUP_FUNCTION_PARAMETER_ERROR_CODE_AccessDenied 
GROUP_FUNCTION_PARAMETER_ERROR_CODE_RequestOrCommandIsNotSupported 
GROUP_FUNCTION_PARAMETER_ERROR_CODE_ReadOrWriteIsNotSupported 

Definition at line 476 of file CT2KLib.h.

◆ GROUP_FUNCTION_PGN_ERROR_CODE_T

NMEA2000 ACK VALUES.

Enumerator
GROUP_FUNCTION_PGN_ERROR_CODE_NoError 
GROUP_FUNCTION_PGN_ERROR_CODE_PGNNotSupported 
GROUP_FUNCTION_PGN_ERROR_CODE_PGNTemporarilyNotAvailable 
GROUP_FUNCTION_PGN_ERROR_CODE_AccessDenied 
GROUP_FUNCTION_PGN_ERROR_CODE_RequestOrCommandNotSupported 
GROUP_FUNCTION_PGN_ERROR_CODE_DefinerTagNotSupported 
GROUP_FUNCTION_PGN_ERROR_CODE_ReadOrWriteNotSupported 

Definition at line 454 of file CT2KLib.h.

◆ GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_T

Enumerator
GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_NoError 
GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_TransmitIntervalOrPriorityNotSupported 
GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_TransmitIntervalIsLessThanMeasurementCalculationInterval 
GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_AccessDenied 
GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_RequestNotSupported 

Definition at line 466 of file CT2KLib.h.

◆ MULTIPKT_TYPE_T

Multi-packet types.

Enumerator
MULTIPKT_TYPE_NONE 

This indicates it is not a multi-packet message, but is either a Single Packet or Fast packet message.

MULTIPKT_TYPE_BAM 

This is a Broadcast Multi-packet Message format.

MULTIPKT_TYPE_CMDT 

This is a Call/response Multi-packet message format.

Definition at line 283 of file CT2KLib.h.

◆ NMEA_REQUEST_T

NMEA2000 Level A Request/Command/Acknowledge PGN values.

NMEA2000 REQUEST VALUES

Enumerator
NMEA_REQUEST_REQUEST 
NMEA_REQUEST_COMMAND 
NMEA_REQUEST_ACKNOWLEDGE 
NMEA_REQUEST_READ_FIELDS 
NMEA_REQUEST_READ_FIELDS_REPLY 
NMEA_REQUEST_WRITE_FIELDS 
NMEA_REQUEST_WRITE_FIELDS_REPLY 

Definition at line 442 of file CT2KLib.h.

◆ PGN_LIST_MODE_T

The list mode for the message.

Enumerator
PGN_LIST_MODE_J1939 

This controls if the PGN is included in the NMEA PGN that lists what messages the device supports.

PGN_LIST_MODE_NMEA2000 

This controls if the PGN is included in the NMEA PGN that lists what messages the device supports.

Definition at line 299 of file CT2KLib.h.

◆ PORT_MODE_T

The mode of the port.

Enumerator
PORT_MODE_NMEA2000 

Tells CT2KLib that the Port is a NMEA2000 Port (this enables a lot of the extra NMEA Features)

PORT_MODE_J1939 

Tells CT2KLib that the Port is a J1939 Port (a lot of the extra NMEA features wont work in this mode)

Definition at line 422 of file CT2KLib.h.

◆ PROTOCOL

enum PROTOCOL

Supported Protocols.

Enumerator
P_SINGLEPACKET 

This is all frames that are not Fast or Multi.

P_FASTPACKET 

This is a NMEA2000 Fast Pack format, the single frames have been amalgamated into one frame with a longer DLC with a maximum length of 223.

P_MULTIPACKET 

This is a J1939 Multi-packet Format, the transport protocol frames have been amalgamated into one frame with a longer DLC with a maximum length of 1785.

Definition at line 275 of file CT2KLib.h.

◆ STRING_TYPE_T

Defines string types used within PGN 1F016 for configuration information strings.

Defined in the NMEA2000 spec as part of DF50

See also
CONFIGURATION_INFORMATION_STRING_T
Enumerator
STRING_TYPE_UNICODE 
STRING_TYPE_ASCII 
STRING_TYPE_UNKNOWN 

Definition at line 76 of file CT2KLib.h.

Function Documentation

◆ CT2KClearPGNReceiveCallback()

CTCAN_STATUS CT2KClearPGNReceiveCallback ( CAN_PORT_T i8Port,
PGN i32PGN )

Deregister the Callback function that was registered with CT2KSetPGNReceiveCallback()

Parameters
i8PortPort on which the message will be received. (Must match what was passed in via CT2KSetPGNReceiveCallback)
i32PGNThe PGN number on which the message will be received. (Must match what was passed in via CT2KSetPGNReceiveCallback)
Returns
CTCR_OK if the operation was successful (callback was removed) or CTCR_NOT_FOUND if table was not found and thus not removed. (May also return CTCR_BUS_OFF if the library is not initialised)

◆ CT2KGetLibVersion()

const char * CT2KGetLibVersion ( void )

Get the version number of CT2KLib.

Returns
The version number of CT2KLib as a null-terminated string

◆ CT2KLibAddrClaimReceiveCallback()

CTCAN_STATUS CT2KLibAddrClaimReceiveCallback ( CTLIB_ADDRCLAIM_CB AddrClaimCB,
uintptr_t userData )

Register a callback function that will be triggered when an address claim occurs.

Parameters
AddrClaimCBCallback Function of CTLIB_ADDRCLAIM_CB type.
userDataAdditional data that will be passed to the callback function
Returns
CTCR_OK if the operation was successful.

◆ CT2KLibAddValidAddressRange()

CTCAN_STATUS CT2KLibAddValidAddressRange ( CAN_PORT_T i8Port,
uint8_t startAddress,
uint8_t endAddress )

Restricts the addressses that can be assigned to the device.

If this is called then only addresses in the specified range can be claimed by the device. This can be called multiple times to allow addresses in multiple ranges. If no addresses are available in the specified ranges, then the device will enter a "cannot claim address" state. Calling this function will cause the device to fail N2K certification.

Parameters
i8PortPort for which the range of addresses will be set
startAddressThe start address of the range of valid addresses
endAddressThe end address of the range of valid addresses

◆ CT2KLibDeinit()

void CT2KLibDeinit ( void )

De-initialises the CT2K Library.

Stops the threads and cleans up the used memory

◆ CT2KLibEnableDebug()

CTCAN_STATUS CT2KLibEnableDebug ( uint32_t loggedMessagesBitmask,
CT2KLibDiagnosticPrint_T printFunction,
void * userData )

Enable Debug Prints.

Parameters
loggedMessagesBitmaskBitMask to control which messages will trigger. Based upon DBG_LVL_T;
printFunctionFunction that will be called when the library wants to do a debug print
userdataThat will be passed to printFunction when it is called.
Returns
CTCR_OK if successful.

◆ CT2KLibGetMyAddress()

NETADDR CT2KLibGetMyAddress ( CAN_PORT_T i8Port)

Returns the devices CAN Address for the specified port.

Parameters
i8PortPort on which the query is done
Returns
The CAN Network Address

◆ CT2KLibGetPGNTableRequiredMemorySize()

INPUT_PARAMS_T CT2KLibGetPGNTableRequiredMemorySize ( const PGNDesc * pDesc,
uint32_t tableSize,
uint16_t numberOfPorts )

Calculate the required size based on the provided PGNDesc Table.

In case multiple PGN tables are installed, this function needs to be run per PGN table. All the results then need adding up into a single INPUT_PARAMS_T structure that is then passed to CT2KLibInit() function.

Parameters
pDescThe Table containing the PGN information
tableSizeThe length of the PGN table Passed in
numberOfPortsNumber of CAN ports this PGN table will be used with
Returns
A structure containing all the required packet and PGN table information. This structure can then be passed in CT2KLibInit

◆ CT2KLibGetState()

CTSTATE CT2KLibGetState ( CAN_PORT_T i8Port)

Get the Library status on the specified Port.

Parameters
i8PortPort on which the query is done
Returns
Either CTSTATE_ONLINE or CTSTATE_OFFLINE or CTSTATE_CONFIGURING.

◆ CT2KLibInitEx()

void CT2KLibInitEx ( INPUT_PARAMS_T * inputParams,
PORTS_CONFIG_T * ports,
uint32_t numberOfPorts,
CAN_DRIVER_FUNCTIONS_T canDriverFunctions )

Initialises the CT2K Library.

IMPORTANT - MEMORY LEAK RISK - If CT2KLibDeinit() is not called this WILL leak memory.

Parameters
inputParamspointer to a INPUT_PARAMS_T structure containing the Packet Definitions. It is recommended to use the "CT2KLibGetPGNTableRequiredMemorySize()" function to get the required size for inputParams.
portsPointer to a PORTS_CONFIG_T structure containing the CAN Ports definitions.
numberOfPortsNumber of CAN Ports to be configured
canDriverFunctionsThe driver callbacks to use. See definition of CAN_DRIVER_FUNCTIONS_T for details

◆ CT2KLibInstallPGNTable()

CTCAN_STATUS CT2KLibInstallPGNTable ( CAN_PORT_T portNumber,
const PGNDesc * pDesc,
uint16_t tableSize )

Install the PGN Table in the Library Duplicates are not allowed and will trigger an assert and a fail.

Parameters
portNumberCan Port for which the Table will be installed.
pDescPointer to the Description table
tableSizeThe total number of PGNS contained in the array pointed by pDesc.
Returns
CTCR_OK if the operation is successful.

◆ CT2KLibIsRunning()

bool CT2KLibIsRunning ( void )

Query the State of the Library.

Returns
TRUE if the library is ONLINE, false otherwise

◆ CT2KLibPackDeviceNameFields()

void CT2KLibPackDeviceNameFields ( const DEVICE_NAME_FIELDS * pFields,
uint8_t * pPackedFields )

Pack DEVICE_NAME_FIELDS struct into an 8 byte array.

Parameters
pFieldsPointer to the fields data that will be packed
pPackedFieldsPointer to the 8 byte array that the data will be packed into

◆ CT2KLibRegisterCommandedAddressCallback()

CTCAN_STATUS CT2KLibRegisterCommandedAddressCallback ( CAN_PORT_T i8Port,
COMMANDEDADDRESSCALLBACK callback,
uintptr_t userData )

This allows registration of a callback to check whether or not the device should change to the specified address on receipt of the CommandedAddress PGN.

If no callback is set then the device will change to the specified address. Callback should return true if address change should happen. Else return false

Parameters
i8PortThe port that the callback should be registered to
callbackThe callback that will be called on receipt of CommandedAddress on the specified port
userDataAdditional data that will be passed to the function
Returns
CTCR_OK if registration of the callback was successful

◆ CT2KLibRegisterCommandedConfigurationInformationCallback()

CTCAN_STATUS CT2KLibRegisterCommandedConfigurationInformationCallback ( COMMANDCONFIGURATIONINFORMATIONCALLBACK callback,
uintptr_t userData )

This allows registration of a callback to check whether or not the device should change it's configuration information to the specified strings on receipt of the Configuration Information PGN change command.

If no callback is set then the device will respond with a NACK of PGN error RequestOrCommand not supported (0x04), Field error Request is not supported (0x04) NOTE that this will fail NMEA certification. (C.3.22.9.1 and C.6.22.9.1) To pass certification, the device is required to accept requests to change fields 1 and 2 of it's configuration information, which are the installation specific fields.

If registered for this callback, the library will automatically NACK any commands that command fields other than 1 or 2, The library will automatically NACK any commands that contain more than 2 parameters The library will automatically NACK any commands that try to change priority (Priority field other than 0x6, 0x8, 0x9 or 0xF)

If only 1 parameter string is given in the command, the other string will be filled with it's existing value.

Once the library has decided that it is a "valid command" it will call the registered callback with the data it has retrieved from the command The application will then need to check it is happy with the new configuration information strings, and use the provided pointers to return error codes back to the library. If either of the error codes are errors, then the library will respond with a NACK containing the error codes (in the same order as they were provided in the command).

Please be aware that if either of the strings are rejected, then the whole command is rejected. If the command is rejected, then neither of the provided strings should be saved/updated.

Please also be aware that strings may not be null terminated, they are given exactly as the library receives them.

The callback function should modify the values of the provided GROUP_FUNCTION_PARAMETER_ERROR_CODE_T pointers, giving them an appropriate value.

void CommandedConfigurationInformationCallback(CAN_PORT_T i8Port,
const CONFIGURATION_INFORMATION_STRING_T* pString2, GROUP_FUNCTION_PARAMETER_ERROR_CODE_T* pString2ErrCode, uintptr_t userData)
{
// Some processing to decide whether the changes should be accepted
...
// Set the error codes for each string
//Save the changes to non-volatile memory
}
uint32_t CAN_PORT_T
Definition CT2KLib.h:132
GROUP_FUNCTION_PARAMETER_ERROR_CODE_T
Definition CT2KLib.h:477
@ GROUP_FUNCTION_PARAMETER_ERROR_CODE_NoError
Definition CT2KLib.h:479
Defines the structure of strings used for transmitting and receiving PGN 1F016.
Definition CT2KLib.h:88
Parameters
callbackThe callback that will be called on receipt of group function command(1ED00) Configuration Information (1F016) on the specified port
userDataadditional data that will be passed to the function
Returns
CTCR_OK if the registration of the callback was successful

◆ CT2KLibResetValidAddressRange()

CTCAN_STATUS CT2KLibResetValidAddressRange ( CAN_PORT_T i8Port)

Resets the valid address range, cancelling the effect of any previous calls to CT2KLibAddValidAddressRange.

This will allow the device to claim any valid J1939 or NMEA2000 CAN address, depending on the port mode.

Parameters
i8PortPort for which the range of addresses will be reset

◆ CT2KLibRestartCANPorts()

CTCAN_STATUS CT2KLibRestartCANPorts ( PORTS_CONFIG_T * ports,
uint32_t numberOfPorts )

Restart the CAN Ports with a different configuration.

Parameters
portsPointer to the new PORTS_CONFIG_T structure to initialise the library with
numberOfPortsNumber of CAN Ports to be configured
Returns
CTCR_OK if it is successful or the error message otherwise.

◆ CT2KLibSendPGN()

CTCAN_STATUS CT2KLibSendPGN ( CAN_PORT_T i8Port,
NETADDR u8DestAddr,
PGN i32PGN,
void * pData,
uint16_t u16DataLen )

Send a Message using the specified PGN. Valid only for Single and Fast Packets.

Parameters
i8PortPort on which the message will be sent
u8DestAddrDestination address of the CAN Node to whom the message is intended
i32PGNPGN Number on which the DLC will be sent
pDataPointer to the memory location where the DLC bytes are located
u16DataLenLength of the DLC
Returns
CTCR_OK if the operation was successful, i.e. the message was queued for sending.

◆ CT2KLibSendPGNMultiPkt()

CTCAN_STATUS CT2KLibSendPGNMultiPkt ( CAN_PORT_T i8Port,
NETADDR u8DestAddr,
PGN i32PGN,
void * pData,
uint16_t u16DataLen,
MLTIPCKTSENDCALLBACK multiPktClbk,
uintptr_t userdata,
bool isBAM )

Send a Message using the specified PGN.

Valid only for Multi-Packets. This function can be used to queue BAM / CMDT messages. Maximum number of messages that can be queued is defined in INPUT_PARAMS_T

Parameters
i8PortPort on which the message will be sent
u8DestAddrDestination address of the CAN Node to whom the message is intended
i32PGNPGN Number on which the DLC will be sent
pDataPointer to the memory location where the DLC bytes are located
u16DataLenLength of the DLC
multiPktClbkCallback function. This function is automatically called when a Multi-Packet send is finished
userDataUser Data that can be passed inside the Callback function
isBAMSpecifies if the Message will be sent using BAM or CMDT Protocol
Returns
CTCR_OK if the operation was successful.

◆ CT2KLibSendPGNNow()

CTCAN_STATUS CT2KLibSendPGNNow ( CAN_PORT_T i8Port,
NETADDR u8DestAddr,
PGN i32PGN,
void * pData,
uint16_t u16DataLen )

Functions the same as CT2KLibSendPGN Except allows you to mark a frame as to be sent immediately.

Parameters
i8PortPort on which the message will be sent
u8DestAddrDestination address of the CAN Node to whom the message is intended
i32PGNPGN Number on which the DLC will be sent
pDataPointer to the memory location where the DLC bytes are located
u16DataLenLength of the DLC
Returns
CTCR_OK if the operation was successful.

◆ CT2KLibSetAddress()

CTCAN_STATUS CT2KLibSetAddress ( CAN_PORT_T i8Port,
DEVNAME * pName,
NETADDR u8SeedAddress )

Assigns the name and address to the device.

Set the Network CAN Address on the specified port. If the name contains values which are too big for the relevant field of the DEVICE_NAME_FIELDS structure, only the lower bits of the supplied value will be used.

Parameters
i8PortPort for which the network address is set
pNamePointer to the structure containing the Device Name definition
u8SeedAddressDesired network address.
Returns
CTCR_OK if operation is successful.

◆ CT2KLibSetAppProductInfo()

CTCAN_STATUS CT2KLibSetAppProductInfo ( CAN_PORT_T i8Port,
CTLIB_PROD_INFO * pProdInfo )

Set and the Product Information via the NMEA2000 PGN.

Parameters
i8PortPort on which the transmission will be done
pProdInfoPointer to the structure containing the Product Information.

◆ CT2KLibSetConfigurationInformation_1F016()

CTCAN_STATUS CT2KLibSetConfigurationInformation_1F016 ( CAN_PORT_T i8Port,
const char * field1,
size_t field1_Length,
const char * field2,
size_t field2_Length,
const char * field3,
size_t field3_Length )

Set the information shared with other devices via the Configuration Information PGN (1F016).

Deprecated
Please use the _EX version of this function instead. This version is just a wrapper around the new one.

It is assumed that all strings are ASCII Strings. ASCII Strings have a Max String Length of 70 (including the null terminator), this is defined in the NMEA2000 Specification.

If you do not call this function to set this up, the library will respond to all requests for this information with "", "", ""

Parameters
i8PortPort on which the transmission will be done
field1Pointer to the first char in the string for Installation Description Field 1
field1_LengthLength of the string in field1
field2Pointer to the first char in the string for Installation Description Field 2
field2_LengthLength of the string in field2
field3Pointer to the first char in the string for Manufacturer Information
field3_LengthLength of the string in field3
Returns
CTCR_OK if operation is successful, CTCR_INVALID_PORT if the CAN Port is Invalid, CTCR_NO_DATA if it has issue with any of the data.
See also
CT2KLibSetConfigurationInformation_1F016_EX

◆ CT2KLibSetConfigurationInformation_1F016_EX()

CTCAN_STATUS CT2KLibSetConfigurationInformation_1F016_EX ( CAN_PORT_T i8Port,
const CONFIGURATION_INFORMATION_STRING_T * field1,
const CONFIGURATION_INFORMATION_STRING_T * field2,
const CONFIGURATION_INFORMATION_STRING_T * field3 )

Set the information shared with other devices via the Configuration Information PGN (1F016).

ASCII Strings have a Max String Length of 70 (including the null terminator), this is defined in the NMEA2000 Specification. UNICODE Strings have a Max String Length of 35 (including the null terminator), this is defined in the NMEA2000 Specification. If you do not call this function to set this up, the library will respond to all requests for this information with "", "", ""

Parameters
i8PortPort on which the transmission will be done
field1Pointer to the CONFIGURATION_INFORMATION_STRING_T for installation Description Field 1
field2Pointer to the CONFIGURATION_INFORMATION_STRING_T for Installation Description Field 2
field3Pointer to the CONFIGURATION_INFORMATION_STRING_T for Manufacturer Information
Returns
CTCR_OK if operation is successful, CTCR_INVALID_PORT if the CAN Port is Invalid, CTCR_NO_DATA if it has issue with any of the data.
See also
CONFIGURATION_INFORMATION_STRING_T

◆ CT2KLibSnoopNetwork()

CTCAN_STATUS CT2KLibSnoopNetwork ( CAN_PORT_T i8Port)

Sends Global Address Claim request using the Request PGN on the specified port.

The callback registered by CT2KLibAddrClaimReceiveCallback will be triggered for each device on the network as it sends its name information.

Parameters
i8PortPort on which the query is done
Returns
CTCR_OK is the operation was successful.

◆ CT2KLibStart()

CTCAN_STATUS CT2KLibStart ( void )

Open the CAN Port and start the Library.

Returns
CTCR_OK if it is successful or the error message otherwise.

◆ CT2KLibStop()

void CT2KLibStop ( void )

Stop the Library.

◆ CT2KLibUninstallPGNTable()

CTCAN_STATUS CT2KLibUninstallPGNTable ( CAN_PORT_T portNumber,
const PGNDesc * pDesc )

Uninstall a PGN Table Installed using CT2KLibInstallPGNTable()

Parameters
portNumberCan Port for which the Table will be uninstalled.
pDescPointer to the Description table. (Must match what was passed in via CT2KLibInstallPGNTable)
Returns
CTCR_OK if the operation is successful (table was removed) or CTCR_NOT_FOUND if table was not found and thus not removed.

◆ CT2KLibUnpackDeviceNameFields()

void CT2KLibUnpackDeviceNameFields ( const uint8_t * pPackedFields,
DEVICE_NAME_FIELDS * pFields )

Unpack 8 byte array into DEVICE_NAME_FIELDS struct.

Parameters
pPackedFieldsThe packed 8 byte array that will be unpacked
pFieldsThe fields struct that the packed data will be unpacked into

◆ CT2KNMEA2KSendAcknowledge()

CTCAN_STATUS CT2KNMEA2KSendAcknowledge ( CAN_PORT_T i8Port,
PGN i32PGN,
NETADDR u8DestAddr,
MULTIPKT_TYPE_T transmitMethod,
GROUP_FUNCTION_PGN_ERROR_CODE_T pgnErrorCode,
GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_T transmissionErrorCode,
uint8_t numberOfRequestedParams,
NMEA_REQUEST_FAILED_FIELDS_T * failedFields,
uint8_t length )

Send a NMEA2K Acknowledge Message (PGN 126208)

Parameters
i8PortPort on which the message will be sent
i32PGNThe PGN number for which the Acknowledge will be send
u8DestAddrDestination address of the CAN Node to whom the message is intended
transmitMethodThis is the Transport Protocol that is used to send the Ack (Either Fast Packet or Multi-Packet BAM or Multi-Packet CMDT)
pgnErrorCodeThe standard NMEA2K PGN Error Code.
transmissionErrorCodeThe standard NMEA2K Time transmission Error Code.
numberOfRequestedParamsThe total number of Requested parameters (from Req/Cmd PGN)
failedFieldsArray containing the ERROR codes for the requested/commanded parameters
lengthLength of the failedFields array.
Returns
CTCR_OK if the operation was successful.

◆ CT2KRegisterCallbackOnCommandedNameChange()

CTCAN_STATUS CT2KRegisterCallbackOnCommandedNameChange ( CAN_PORT_T i8Port,
CommandedNameChangeNotification callBack,
uintptr_t userData )

NMEA 2000 Level A - Commanded Name (0xEE00) Functionality.

This allows you to register for a callback from the library if we receive a command from someone else on the bus to change our Name information. If you do not register for this callback, the library will work as it did pre 4.3.0.0 and will send a Nack of PGN Error Access Denied (0x03), with a Field Error of Invalid Request or Command Parameter Field (0x01). If you register for this callback, the library will automatically Nack any commands that are for anything other than Fields 3, 4 or 8 of 0xEE00 (Device Instance Upper, Device Instance Lower and System Instance).

Fields 3 and 4 must be commanded as a pair. otherwise the library will reject it. Field 8 can be commanded on its own.

Any other fields commanded will cause a Nack.

Once the library has decided that it is a "Valid Command" it will update a copy of its structure and trigger the below registered callback. The application will then need to check it is happy with the new Name information and use the provided return to instruct the library as to weather it should accept the Command and Send an Ack, or Reject the command and Send a Nack.

PLEASE be aware, if you reject any part of the message you reject the whole message. If one of the numbers had not changed then your return value in that part of the structure will be ignored. But if both numbers have changed and you reject one, that is still a reject and the other number should not be saved/updated.

Parameters
i8PortPort on which the message will be sent
callBackThis is the function you will get the callback on, the return value of this function will control the library's action/response to the command
userDataAdditional data that will be passed to the function
Returns
CTCR_OK, CTCR_NO_DATA (Missing Callback) or CTCR_INVALID_PORT (Invalid i8Port)

◆ CT2KRegisterCallbackOnRequestedHeartbeatRateChange()

CTCAN_STATUS CT2KRegisterCallbackOnRequestedHeartbeatRateChange ( CAN_PORT_T i8Port,
RequestedHeartbeatUpdateRateChangeNotification callback,
uintptr_t userData )

This allows you to register for a callback from the library if we receive a request to change the update rate of the heartbeat message.

If you do not register for this callback, the library will send a Nack of PGN Error Access Denied (0x03) with a transmit interval error of Not Supported (0x01). If you register for this callback and the request is acceptable then the specified callback function will be called with the specified transmission interval as the parameter. If the callback returns GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_NoError then the request will be accepted and the update rate of the heartbeat message will be accepted. Otherwise the library will send a Nack of PGN Error Access Denied with a transmit interval error of the returned value. Note that requests which contain request parameters, an invalid transmission rate, or no transmission rate are invalid and will always be rejected. Acceptable transmission rates are 1000 to 60000 milliseconds, or 0xFFFFFFFE which sets the transmission interval to the default (60000ms).

Parameters
i8PortPort on which the message will be sent
callbackThe function that will be called if a valid request to change the heartbeat message update rate is received (if NULL then no function will be called)
userDataAdditional data that will be passed to the function
Returns
CTCR_OK or CTCR_INVALID_PORT (Invalid port)

◆ CT2KSetGroupFunctionCallback()

CTCAN_STATUS CT2KSetGroupFunctionCallback ( CAN_PORT_T i8Port,
PGN i32PGN,
NMEA2K_RQ_CMD regCB,
uintptr_t userData )

NMEA 2000 Level A - Request, Command, Acknowledge PGN Functions.

Register a callback function that will be triggered when a Group Function PGN (126208/0x1ED00) is received for the specified PGN

Parameters
i8PortPort on which the message was received
i32PGNThe PGN number mentioned in the Group Function
regCBCallback Function
userDataAdditional data passed to the function
Returns
CTCR_OK if the operation was successful.

When you are finished with your callback, Return -1 if you didnt do anything and want the library to respond with an appropriate Acknowledge PGN.

◆ CT2KSetHeartbeatUpdateRate()

CTCAN_STATUS CT2KSetHeartbeatUpdateRate ( CAN_PORT_T i8Port,
uint32_t updateRate_ms )

This allows you to set the update rate of the NMEA2000 heartbeat message.

The update rate can be from 1000ms to 60000ms.

Parameters
i8PortPort which the update rate will be set for
updateRate_msThe update rate in milliseconds
Returns
CTCR_OK if the operation was successful

◆ CT2KSetPGNISORequestReceivedCallback()

CTCAN_STATUS CT2KSetPGNISORequestReceivedCallback ( CAN_PORT_T i8Port,
PGN i32PGN,
ISOCallback_EA00 regCB,
uintptr_t userData )

Register a Callback function when a Message associated with the Specified PGN is received.

Parameters
i8PortPort on which the message will be received
i32PGNThe PGN number of the message to be received
regCBCallback Function
userDataAdditional data to be passed to the callback function
Returns
CTCR_OK if the operation was successful.

◆ CT2KSetPGNReceiveCallback()

CTCAN_STATUS CT2KSetPGNReceiveCallback ( CAN_PORT_T i8Port,
PGN i32PGN,
RCVRCB rCB,
uintptr_t userdata )

Register a Callback function when a Message associated with the Specified PGN is received.

Callbacks with the same PGN/Port will override previous callbacks.

Parameters
i8PortPort on which the message will be received
i32PGNThe PGN number of the message to be received
rCBCallback Function
userdataAdditional data to be passed to the callback function
Returns
CTCR_OK if the operation was successful.

◆ CTLIBGetNMEA2KLibVersion()

const NMEA2000SpecVersion * CTLIBGetNMEA2KLibVersion ( void )

Get the NMEA2000 Database Version the library uses.

Returns
A pointer to the structure containing the NMEA2000 Database Version