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. | |
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. | |
Functions for using the CT2KLibrary.
| #define BYTES_IN_RAW_FRAME 8 |
| #define PGN_AddressClaim 60928 |
| #define PGN_CONFIGURATIONINFORMATION_SIZE 70 |
| #define PGN_ISOConnectMgmt 60416 |
| typedef uint32_t __BIT |
| typedef uint32_t CAN_PORT_T |
| 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.
| typedef NAME_CHANGE_COMMAND_RESPONSE_T(* CommandedNameChangeNotification) (CAN_PORT_T i8Port, DEVNAME commandedNameInformation, uintptr_t userData) |
| 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.
| canPort | is the index of the port, 0 indexed. |
| bitRate | is the bit rate, typically 250000 |
| userData | will be whatever the userData was set to when it was called (eg this). |
| 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.
| canPort | is the index of the port, 0 indexed. |
| userData | will be whatever the userData was set to when it was called (eg this). |
| 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.
| canPort | is the index of the port, 0 indexed. |
| userData | will be whatever the userData was set to when it was called (eg this). |
| typedef void(* CT2KLibDiagnosticPrint_T) (const char *pFormatStr, va_list args, void *userData) |
Type define for CTKLib's driver level print to console function.
| pFormatStr | this will be a printf style format string |
| args | will be the arguments to go with the pFormatStr |
| userData | will be whatever the userData was set to when it was called (eg this). |
| 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.
| canPort | is the index of the port, 0 indexed. |
| userData | will be whatever the userData was set to when it was called (eg this). |
| 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
| pCanPorts | is an array of can ports to wait for a frame on |
| LengthOf_pCanPorts | is the length of the array of CAN_PORT_T that is passed in as pCanPorts |
| pFrame | is a pointer to a frame, if successful, the received frame will be copied here. |
| pFromPort | is a pointer to a port, if successful, will denote which CAN port pFrame was received from. |
| timeoutMs | is the number of milliseconds to wait for a CAN frame to be received. |
| userData | will be whatever the userData was set to when it was called (eg this). |
| 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.
| canPort | is the index of the port, 0 indexed. |
| pFrame | is a pointer to the Frame that should be transmitted |
| userData | will be whatever the userData was set to when it was called (eg this). |
| typedef int(* CTLIB_ADDRCLAIM_CB) (CAN_PORT_T i8Port, NETDEVICE *pNetDevice, uintptr_t userData) |
| typedef int(* ISOCallback_EA00) (PGNDOB *pDOB, uintptr_t userData) |
| typedef void(* MLTIPCKTSENDCALLBACK) (uintptr_t userData) |
| typedef int(* NMEA2K_RQ_CMD) (PGNDOB *pDOB, uintptr_t userData) |
| typedef int(* RCVRCB) (PGNDOB *pDOB, uintptr_t userData) |
| typedef GROUP_FUNCTION_TRANSMIT_INTERVAL_ERROR_CODE_T(* RequestedHeartbeatUpdateRateChangeNotification) (CAN_PORT_T i8Port, uint32_t requestedUpdateRate_ms, NETADDR sourceDevice, uintptr_t userData) |
| enum BUS_STATE_T |
| enum 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. |
| enum CTSTATE |
| enum DBG_LVL_T |
Debugging level.
| enum DIRECTION |
Direction of the message.
NMEA2000 ACK VALUES.
| enum MULTIPKT_TYPE_T |
| enum NMEA_REQUEST_T |
| enum PGN_LIST_MODE_T |
| enum PORT_MODE_T |
| enum PROTOCOL |
Supported Protocols.
| enum STRING_TYPE_T |
| CTCAN_STATUS CT2KClearPGNReceiveCallback | ( | CAN_PORT_T | i8Port, |
| PGN | i32PGN ) |
Deregister the Callback function that was registered with CT2KSetPGNReceiveCallback()
| i8Port | Port on which the message will be received. (Must match what was passed in via CT2KSetPGNReceiveCallback) |
| i32PGN | The PGN number on which the message will be received. (Must match what was passed in via CT2KSetPGNReceiveCallback) |
| const char * CT2KGetLibVersion | ( | void | ) |
Get the version number of CT2KLib.
| CTCAN_STATUS CT2KLibAddrClaimReceiveCallback | ( | CTLIB_ADDRCLAIM_CB | AddrClaimCB, |
| uintptr_t | userData ) |
Register a callback function that will be triggered when an address claim occurs.
| AddrClaimCB | Callback Function of CTLIB_ADDRCLAIM_CB type. |
| userData | Additional data that will be passed to the callback function |
| 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.
| i8Port | Port for which the range of addresses will be set |
| startAddress | The start address of the range of valid addresses |
| endAddress | The end address of the range of valid addresses |
| void CT2KLibDeinit | ( | void | ) |
De-initialises the CT2K Library.
Stops the threads and cleans up the used memory
| CTCAN_STATUS CT2KLibEnableDebug | ( | uint32_t | loggedMessagesBitmask, |
| CT2KLibDiagnosticPrint_T | printFunction, | ||
| void * | userData ) |
Enable Debug Prints.
| loggedMessagesBitmask | BitMask to control which messages will trigger. Based upon DBG_LVL_T; |
| printFunction | Function that will be called when the library wants to do a debug print |
| userdata | That will be passed to printFunction when it is called. |
| NETADDR CT2KLibGetMyAddress | ( | CAN_PORT_T | i8Port | ) |
Returns the devices CAN Address for the specified port.
| i8Port | Port on which the query is done |
| 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.
| pDesc | The Table containing the PGN information |
| tableSize | The length of the PGN table Passed in |
| numberOfPorts | Number of CAN ports this PGN table will be used with |
| CTSTATE CT2KLibGetState | ( | CAN_PORT_T | i8Port | ) |
Get the Library status on the specified Port.
| i8Port | Port on which the query is done |
| 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.
| inputParams | pointer 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. |
| ports | Pointer to a PORTS_CONFIG_T structure containing the CAN Ports definitions. |
| numberOfPorts | Number of CAN Ports to be configured |
| canDriverFunctions | The driver callbacks to use. See definition of CAN_DRIVER_FUNCTIONS_T for details |
| 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.
| portNumber | Can Port for which the Table will be installed. |
| pDesc | Pointer to the Description table |
| tableSize | The total number of PGNS contained in the array pointed by pDesc. |
| bool CT2KLibIsRunning | ( | void | ) |
Query the State of the Library.
| void CT2KLibPackDeviceNameFields | ( | const DEVICE_NAME_FIELDS * | pFields, |
| uint8_t * | pPackedFields ) |
Pack DEVICE_NAME_FIELDS struct into an 8 byte array.
| pFields | Pointer to the fields data that will be packed |
| pPackedFields | Pointer to the 8 byte array that the data will be packed into |
| 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
| i8Port | The port that the callback should be registered to |
| callback | The callback that will be called on receipt of CommandedAddress on the specified port |
| userData | Additional data that will be passed to the function |
| 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.
| callback | The callback that will be called on receipt of group function command(1ED00) Configuration Information (1F016) on the specified port |
| userData | additional data that will be passed to the function |
| 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.
| i8Port | Port for which the range of addresses will be reset |
| CTCAN_STATUS CT2KLibRestartCANPorts | ( | PORTS_CONFIG_T * | ports, |
| uint32_t | numberOfPorts ) |
Restart the CAN Ports with a different configuration.
| ports | Pointer to the new PORTS_CONFIG_T structure to initialise the library with |
| numberOfPorts | Number of CAN Ports to be configured |
| 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.
| i8Port | Port on which the message will be sent |
| u8DestAddr | Destination address of the CAN Node to whom the message is intended |
| i32PGN | PGN Number on which the DLC will be sent |
| pData | Pointer to the memory location where the DLC bytes are located |
| u16DataLen | Length of the DLC |
| 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
| i8Port | Port on which the message will be sent |
| u8DestAddr | Destination address of the CAN Node to whom the message is intended |
| i32PGN | PGN Number on which the DLC will be sent |
| pData | Pointer to the memory location where the DLC bytes are located |
| u16DataLen | Length of the DLC |
| multiPktClbk | Callback function. This function is automatically called when a Multi-Packet send is finished |
| userData | User Data that can be passed inside the Callback function |
| isBAM | Specifies if the Message will be sent using BAM or CMDT Protocol |
| 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.
| i8Port | Port on which the message will be sent |
| u8DestAddr | Destination address of the CAN Node to whom the message is intended |
| i32PGN | PGN Number on which the DLC will be sent |
| pData | Pointer to the memory location where the DLC bytes are located |
| u16DataLen | Length of the DLC |
| 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.
| i8Port | Port for which the network address is set |
| pName | Pointer to the structure containing the Device Name definition |
| u8SeedAddress | Desired network address. |
| CTCAN_STATUS CT2KLibSetAppProductInfo | ( | CAN_PORT_T | i8Port, |
| CTLIB_PROD_INFO * | pProdInfo ) |
Set and the Product Information via the NMEA2000 PGN.
| i8Port | Port on which the transmission will be done |
| pProdInfo | Pointer to the structure containing the Product Information. |
| 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).
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 "", "", ""
| i8Port | Port on which the transmission will be done |
| field1 | Pointer to the first char in the string for Installation Description Field 1 |
| field1_Length | Length of the string in field1 |
| field2 | Pointer to the first char in the string for Installation Description Field 2 |
| field2_Length | Length of the string in field2 |
| field3 | Pointer to the first char in the string for Manufacturer Information |
| field3_Length | Length of the string in field3 |
| 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 "", "", ""
| i8Port | Port on which the transmission will be done |
| field1 | Pointer to the CONFIGURATION_INFORMATION_STRING_T for installation Description Field 1 |
| field2 | Pointer to the CONFIGURATION_INFORMATION_STRING_T for Installation Description Field 2 |
| field3 | Pointer to the CONFIGURATION_INFORMATION_STRING_T for Manufacturer Information |
| 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.
| i8Port | Port on which the query is done |
| CTCAN_STATUS CT2KLibStart | ( | void | ) |
Open the CAN Port and start the Library.
| void CT2KLibStop | ( | void | ) |
Stop the Library.
| CTCAN_STATUS CT2KLibUninstallPGNTable | ( | CAN_PORT_T | portNumber, |
| const PGNDesc * | pDesc ) |
Uninstall a PGN Table Installed using CT2KLibInstallPGNTable()
| portNumber | Can Port for which the Table will be uninstalled. |
| pDesc | Pointer to the Description table. (Must match what was passed in via CT2KLibInstallPGNTable) |
| void CT2KLibUnpackDeviceNameFields | ( | const uint8_t * | pPackedFields, |
| DEVICE_NAME_FIELDS * | pFields ) |
Unpack 8 byte array into DEVICE_NAME_FIELDS struct.
| pPackedFields | The packed 8 byte array that will be unpacked |
| pFields | The fields struct that the packed data will be unpacked into |
| 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)
| i8Port | Port on which the message will be sent |
| i32PGN | The PGN number for which the Acknowledge will be send |
| u8DestAddr | Destination address of the CAN Node to whom the message is intended |
| transmitMethod | This is the Transport Protocol that is used to send the Ack (Either Fast Packet or Multi-Packet BAM or Multi-Packet CMDT) |
| pgnErrorCode | The standard NMEA2K PGN Error Code. |
| transmissionErrorCode | The standard NMEA2K Time transmission Error Code. |
| numberOfRequestedParams | The total number of Requested parameters (from Req/Cmd PGN) |
| failedFields | Array containing the ERROR codes for the requested/commanded parameters |
| length | Length of the failedFields array. |
| 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.
| i8Port | Port on which the message will be sent |
| callBack | This 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 |
| userData | Additional data that will be passed to the function |
| 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).
| i8Port | Port on which the message will be sent |
| callback | The 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) |
| userData | Additional data that will be passed to the function |
| 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
| i8Port | Port on which the message was received |
| i32PGN | The PGN number mentioned in the Group Function |
| regCB | Callback Function |
| userData | Additional data passed to the function |
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.
| 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.
| i8Port | Port which the update rate will be set for |
| updateRate_ms | The update rate in milliseconds |
| 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.
| i8Port | Port on which the message will be received |
| i32PGN | The PGN number of the message to be received |
| regCB | Callback Function |
| userData | Additional data to be passed to the callback function |
| 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.
| i8Port | Port on which the message will be received |
| i32PGN | The PGN number of the message to be received |
| rCB | Callback Function |
| userdata | Additional data to be passed to the callback function |
| const NMEA2000SpecVersion * CTLIBGetNMEA2KLibVersion | ( | void | ) |
Get the NMEA2000 Database Version the library uses.