Last modified: 8 October 2002
for version 3.5.0.0
The API description is also available in the CanoCom.h file.
A description of the things to do when using the DLL can be found here.
Create a CANopen network connection.
CANOPEN_NETWORK CreateCanOpenNetwork( IN WORD wCanOpenInterface, IN DWORD dwCanBusBaudrate, IN const char* lpszInterfaceConfig, IN DWORD dwRxBufferSize );
wCanOpenInterface
Specifies the CAN interface
value meaning CAN_INTERFACE_6390 Start communication via the 6390 RS232 interface CAN_INTERFACE_ESD Start communication via the ESD board interface CAN_INTERFACE_NICAN Start communication via a National Instruments NI-CAN interface
dwCanBusBaudrate
Specfies the Baudrate at which the interface must communicate on the CAN bus. Valid Baudrates are: 10, 20, 50, 125, 250, 500 and 1000.
lpszInterfaceConfig:
Pointer to a NULL-terinated string describing the configuration of the CAN Interface. (See the remarks below.)
dwRxBufferSize:
Specifies the number of received CAN messages the FIFO receive buffer can hold.
The format of the string lpszInterfaceConfig points to varies with the interface.If the value of wCanInterface is CAN_INTERFACE_6390, the string must be of the following form:
"[serial port name] b:[serial port baudrate]"
The string starts with the name of the serial port to which the 6390 is connected, followed by whitespace and "b:" and ends with the baudrate at which communication between the serial port and the 6390 must take place. So, if the 6390 is connected to COM1 and the baudrate must be 9600, the string will be "COM1 b:9600". Traditionally, the name of serial ports are "COM1", "COM2", "COM3"..., but since hardware manufacturers can call serial port whatever they want, this can be any other name. Valid baudrates are 300, 600, 1200, 2400, 4800, 9600, 19200 and 38400.
If the value of wCanInterface is CAN_INTERFACE_ESD, the string must be of the following form:
"n:[logical net]"
The string starts with "n:" followed by the logical net of the ESD CAN interface the CAN network is connected to. So, if the CAN network is connected to logical net 0, the string will be: "n:0"
If the value of wCanInterface is CAN_INTERFACE_NICAN, the string must be the CAN Network Interface object (e.g. "CAN0", "CAN1" ...) at which the communication must take place. See the documentation of the NI-CAN interface for more information.
- If function succeeds, return value is is a CANOPEN_NETWORK variable that can be used at other functions from this DLL.
- If function fails, return value is NULL. To get extended error information, call GetLastError.
Close a CANopen network connection.
BOOL CloseCanOpenNetwork( IN CANOPEN_NETWORK CanOpenNetwork );
CanOpenNetwork:
The CANopen network connection this function is called for.
- If function succeeds, return value is TRUE.
- If function fails, return value is FALSE. To get extended error information, call GetLastError.
Sets a new CAN-bus Baudrate at the interface of a CANopen network connection. Function does nothing when communicating via NI-CAN.
BOOL SetCanOpenBusBaudrate( IN CANOPEN_NETWORK CanOpenNetwork, IN DWORD dwBaudrate );
CanOpenNetwork:
The CANopen network connection this function is called for.
dwBaudrate:
Specifies a new interface CAN-bus baudrate. Valid baudrates are: 10, 20, 50, 125, 250, 500 and 1000.
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Tells the DLL to put received messages with the given COB-ID in the received messages buffer of a CANopen network connection.
BOOL AcceptCanOpenMessages( IN CANOPEN_NETWORK CanOpenNetwork, IN WORD wCobId );
CanOpenNetwork
The CANopen network connection this function is called for.
wCobId
min: 0, max: 0x7FF (2047)
specifies a COB-ID of CANopen messages to be put in the buffer.
When this function is used to accept messages with the given COB-ID, such a message will yield COB_TYPE_UNKNOWN as the COB type and NODE_ID_UNKNOWN as the node ID by which it was sent, when it is taken from the buffer by GetCanOpenMessage.
- Function returns TRUE on success.
- Function returns FALSE on failure. To get extended error information, call GetLastError.
Tells the DLL to further ignore messages with the given COB-ID at a CANopen network connection.
BOOL IgnoreCanOpenMessages( IN CANOPEN_NETWORK CanOpenNetwork, IN WORD wCobId );
CanOpenNetwork
The CANopen network connection this function is called for.
wCobId
min: 0, max: 0x7FF (2047)
Specifies the ID of the messages that the DLL must ignore.
- If function succeeds, return value is TRUE, and the messages with the given ID will be ignored.
- If function fails, return value is FALSE. To get extended error information, call GetLastError.
Define one or more COB-ID's as an Emergency or PDO COB of the given node ID. COB types transmitted by the node will be received and stored in the message buffer.
BOOL DefineEmergencyAndPdoCobs( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN WORD wCobType, IN WORD wCobId );
CanOpenNetwork
The CANopen network connection this function is called for.
bNodeId
The node ID that transmits or receives the given COB types.
wCobType
The COB type(s) to define
value meaning COB_EMERGENCY Emergency COB, transmitted by node COB_TX_PDO1 PDO 1 COB, transmitted by node COB_RX_PDO1 PDO 1 COB, received by node COB_TX_PDO2 PDO 2 COB, transmitted by node COB_RX_PDO2 PDO 2 COB, received by node COB_TX_PDO3 PDO 3 COB, transmitted by node COB_RX_PDO3 PDO 3 COB, received by node COB_TX_PDO4 PDO 4 COB, transmitted by node COB_RX_PDO4 PDO 4 COB, received by node When the wCobId parameter is DEFAULT_COB_ID, wCobType can be any combination of these values. Otherwise only one of these values can be passed.
wCobId
min 1, max 0x7FF (2047) or DEFAULT_COB_ID
Specifies the COB-ID(s) for the given COB types. Pass DEFAULT_COB_ID to specify the default CANopen COB-ID for the given types of the given node ID.
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information
Configures the SDO communication for the given node ID at a CANopen network. This function must proceed calls to RequestDictionaryObject and WriteDictionaryObject for the given node ID.
BOOL ConfigSdoComm( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN WORD wTxSdoCobId, IN WORD wRxSdoCobId, IN DWORD dwMaxDataSize );
CanOpenNetwork
The CANopen network connection this function is called for.
bNodeId
Specifies the node ID for which the function is called.
wTxSdoCobId
The COB-ID of the SDOs transmitted by the given node ID. Pass DEFAULT_COB_ID to specify the default CANopen COB-ID for the given node ID.
wRxSdoCobId
The COB-ID of the SDOs received by the given node ID. Pass DEFAULT_COB_ID to specify the default CANopen COB-ID for the given node ID.
dwMaxDataSize
The maximum size in bytes of an object dictionary entry for the given node ID.
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Detach COB types and node ID from the COB-ID's previously specified at DefineEmergencyAndPdoCobs or ConfigSdoComm. COB types transmitted by the node will no longer be stored in the message buffer.
BOOL UndefineCobs( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN WORD wCobType );
The CANopen network connection this function is called for.
bNodeId
Specifies the node ID for the given COB(s).
wCobType
The COB type(s) to undefine. This can be any combination of the following values
value meaning COB_EMERGENCY Emergency COB, transmitted by node COB_TX_PDO1 PDO 1 COB, transmitted by node COB_RX_PDO1 PDO 1 COB, received by node COB_TX_PDO2 PDO 2 COB, transmitted by node COB_RX_PDO2 PDO 2 COB, received by node COB_TX_PDO3 PDO 3 COB, transmitted by node COB_RX_PDO3 PDO 3 COB, received by node COB_TX_PDO4 PDO 4 COB, transmitted by node COB_RX_PDO4 PDO 4 COB, received by node COB_TX_SDO SDO COB, transmitted by node COB_RX_SDO SDO COB, received by node When COB_TX_SDO and/or COB_RX_SDO is specified, calls to RequestDictionaryObject and WriteDictionaryObject are no longer possible for the given node ID.
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Defines that the function pointed to by pCallback must be called when a message of the wCobType COB type is received from the node ID bNodeId.
BOOL DefineCanOpenMsgCallback( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN WORD wCobType, IN LPCANOPENMSG_CALLBACK lpCallback, IN LPVOID lpCallbackParam );
The CANopen network connection this function is called for.
bNodeId
The Node ID that must send the messages of the COB type defined at wCobType.
wCobType
The COB type of the messages the node ID at bNodeId must send for the function to be called.
value meaning COB_EMERGENCY Emergency COB, transmitted by node COB_TX_PDO1 PDO 1 COB, transmitted by node COB_TX_PDO2 PDO 2 COB, transmitted by node COB_TX_PDO3 PDO 3 COB, transmitted by node COB_TX_PDO4 PDO 4 COB, transmitted by node COB_NODEGUARD Nodeguarding COB
pCallback
Pointer to the application-defined function that must be called when a message of the type defined at wCobType is received from the node ID defined at bNodeId. The function must be of the type Pointer to the application-defined function of type LPCANOPENMSG_CALLBACK.
lpCallbackParam
Specifies a single 32-bit parameter value passed to the callback function.
LRESULT CALLBACK MessageReceivedCallback( IN BYTE bNodeId, IN WORD wCobType, IN WORD wCobId, IN BYTE bDataLen, IN const BYTE* const pbData, IN void* lpCallbackParam )Parameters
bNodeId
The node ID that sent the message.
wCobType
The type of the message.
wCobId
The message ID of the message.
bDataLen
The number of data bytes the message contains.
bData
The buffer containing the data of the message.
lpCallbackParam
The value of lpCallbackParam defined at DefineCanopenMsgCallback
If the callback function is defined for nodeguarding, the callback will only be called when a nodeguarding error occurs (i.e. node in wrong operational state or no answer from the node).
The value returned by the callback function must be non-zero when the callback function is no longer to be called for the node ID, zero otherwise. If the callback is defined for nodeguarding, this is of no importance, since the callback is called when a nodeguarding error occurs, and such an error will stop nodeguarding for the node.
-DefineCanOpenMsgCallback returns TRUE on success, FALSE on failure. Call GetLastError to get extended error information.
Retreives the COB-ID that is defined as a certain COB type of the given node ID at earlier calls to DefineEmergencyAndPdoCobs, ConfigSdoComm or StartNodeguarding.
WORD GetCobId( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN WORD wCobType );
The CANopen network connection this function is called for.
bNodeId
The node ID.
wCobType
The COB type. This must be one of the following values
value meaning COB_EMERGENCY Emergency COB, transmitted by node COB_TX_PDO1 PDO 1 COB, transmitted by node COB_RX_PDO1 PDO 1 COB, received by node COB_TX_PDO2 PDO 2 COB, transmitted by node COB_RX_PDO2 PDO 2 COB, received by node COB_TX_PDO3 PDO 3 COB, transmitted by node COB_RX_PDO3 PDO 3 COB, received by node COB_TX_PDO4 PDO 4 COB, transmitted by node COB_RX_PDO4 PDO 4 COB, received by node COB_TX_SDO SDO COB, transmitted by node COB_RX_SDO SDO COB, received by node COB_NODEGUARD Nodeguarding COB
- Function returns the COB-ID that is defined as the given COB type of the given node ID. When the COB is not yet defined, function returns COB_ID_NONE.
- Function returns 0 on failure. Call GetLastError to get extended error information.
Get the COB's that are defined for a node ID at previous calls to DefineEmergencyAndPdoCobs, ConfigSdoComm, or StartNodeguarding.
WORD GetNodeIdCobs( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId );
CanOpenNetwork
The CANopen network connection this function is called for.
bNodeId
The node ID that the COB's have been defined for.
- Function returns a bitmask containing the COB types that have been defined for the given node ID, zero when no COB's have been defined.
Determine how a COB-ID is defined at previous calls to AcceptCanOpenMessages, DefineEmergencyAndPdoCobs, ConfigSdoComm, or StartNodeguarding.
BOOL GetCobTypeAndNode( IN CANOPEN_NETWORK CanOpenNetwork, IN WORD wCobId, OUT BYTE* pbNodeId, OUT WORD* pwCobType );
The CANopen network connection this function is called for.
wCobId
The COB-ID wherefrom the COB type and node ID must be determined.
pbNodeId
Pointer to a BYTE variable that will receive the node ID attached to the given COB-ID. Will receive NODE_ID_NONE if the COB-ID is not yet defined.
pwCobType
Pointer to a WORD variable that will receive the COB type attached to the given COB-ID. Will receive COB_TYPE_NONE if the COB-ID is not yet defined.
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Retreive number of messages in message buffer, and get information on the next message that can be taken from the message buffer. If buffer is empty, wait for a message to be put in the buffer.
LONG IsCanOpenMsgReceived( IN CANOPEN_NETWORK CanOpenNetwork, IN DWORD dwMilliseconds, OUT WORD* pwCobType, OUT BYTE* pbNodeId, OUT WORD* pwCobId, OUT DWORD* pdwDataLength );
The CANopen network connection this function is called for.
dwMilliseconds
Specifies the time-out interval, in milliseconds. When no messages are in the message buffer at the time of calling, the function waits until the specified time-out has passed or if a message was received before it has passed. If dwMilliseconds is zero, the function checks the buffer's state and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.
pwCobType
Pointer to a WORD variable that will receive the COB type of the next message to be taken from the message buffer, or NULL.
pbNodeId
Pointer to a BYTE variable that will receive the node ID that sent the next message to be taken from the message buffer, or NULL.
pwCobId
Pointer to a WORD variable that will receive the COB-ID of the next message to be taken from the message buffer, or NULL.
pdwDataLength
Pointer to a DWORD variable that will receive the length, in bytes, of the next message to be taken from the message buffer, or NULL.
- Function returns the number of messages in the buffer, zero if the buffer is empty and no messages were received during the time-out.
- Function returns -1 on failure. Call GetLastError to get extended error information.
Get the next message from the message buffer. If buffer is empty, wait for a message to be put in the buffer.
CHAR GetCanOpenMessage( IN CANOPEN_NETWORK CanOpenNetwork, IN DWORD dwMilliseconds, OUT WORD* pwCobType, OUT BYTE* pbNodeId, OUT WORD* pwCobId, OUT DWORD* pdwDataLength, OUT void* pvData, OUT DWORD* pdwNumOfRemainingMsg );
The CANopen network connection this function is called for.
dwMilliseconds
Specifies the time-out interval, in milliseconds. When no messages are in the buffer at the time of calling, the function waits until the specified time-out has passed or if a message was received before it has passed. If dwMilliseconds is zero, the function returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.
pwCobType
Pointer to a WORD varaible that receives the COB type of the message taken from the message buffer, or NULL. See the remarks below for more information.
pbNodeId
Pointer to a BYTE variable that receives the node ID that sent the message taken from the message buffer, or NULL.
pdwDataLength
Pointer to a DWORD varaible that receives the length, in bytes, of the message's data taken from the message buffer, or NULL.
pvData
Pointer to the buffer that will receive the message's data taken from the message buffer.
pdwNumOfRemainingMsg
Pointer to a DWORD variable that receives the number of message left in the message buffer, or NULL.
When the COB type of the received message is COB_NODEGUARD, a nodeguarding error has occurred for the node ID returned in pbNodeId, and nodeguarding is stopped for that node. When the one byte of the message's data is zero, the node did not respond on a nodeguarding request. When this byte is non-zero, the node's operational state changed to another state than specified at StartNodeguarding.
The other COB types remain unchanged when they are received and put in the message buffer.
- Function returns 1 if a message is taken from the buffer before the specified time-out has passed.
- Function returns 0 if no message could be taken from the buffer before the time-out has passed.
- Function returns -1 on failure. Call GetLastError to get extended error information.
Clear the message buffer.
BOOL FlushCanOpenBuffer( IN CANOPEN_NETWORK CanOpenNetwork );
The CANopen network connection this function is called for.
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Send a NMT command to a node or to all nodes on the CAN network.
BOOL SendNmtCommand( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN BYTE bNmtCommand );
The CANopen network connection this function is called for.
bNodeId
Node ID to send the command to, or zero to select al node ID's on the connected CAN network.
bNmtCommand
The NMT command to send. This must be one of the following
value meaning NMT_START_REMOTE_NODE set node in operational state NMT_STOP_REMOTE_NODE set node in prepared state NMT_ENTER_PRE_OPERATIONAL_STATE set node in pre-operational state NMT_RESET_NODE reset the node NMT_RESET_COMMUNICATION reset the node's communication
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Request the data of a dictionary object of the given node ID. Response will be put in the message buffer from where it can be taken by GetCanOpenMessage. This function must be proceeded by a call to ConfigSdoComm with the given node ID.
BOOL RequestDictionaryObject( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN WORD wObjectIndex, IN BYTE bObjectSubindex );
The CANopen network connection this function is called for.
bNodeId
Specifies the node ID of which an object must be read.
wObjectIndex
The object's index.
bObjectSubindex
The object's subindex.
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Write data to a dictionary object of the given node ID. Response will be put in the message buffer from where it can be taken by GetCanOpenMessage. This function must be proceeded by a call to ConfigSdoComm with the given node ID.
BOOL WriteDictionaryObject( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN WORD wObjectIndex, IN BYTE bObjectSubIndex, IN DWORD dwDataLen, IN const void* pvData );
The CANopen network connection this function is called for.
bNodeId
Specifies the node ID of which an object must be written.
wObjectIndex
The object's index.
bObjectSubindex
The object's subindex.
dwDataLen
The size in bytes of the data to write.
pvData
Pointer to a buffer containing the data to write to the object. The data must be in little endian format (LSB first) for numeric data.
- Function returns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Start nodeguarding for the given node ID. Nodeguarding requests will be done every wGuardTime milliseconds. When no response is received, a message of the type COB_NODEGUARD and a null char as data will be put in the message buffer. If the node is in a different state than bExpectedState, nodeguarding will be stopped and the last received nodeguarding response will be put in the buffer.
BOOL StartNodeguarding( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN WORD wCobId, IN WORD wGuardTime, IN BYTE bExpectedState );
The CANopen network connection this function is called for.
bNodeId
Node ID to start nodeguarding for.
wCobId
The COB-ID at which nodeguarding requests and responses take place. Specify DEFAULT_COB_ID to use the default CANopen nodeguarding COB-ID for this node.
wGuardTime
Specifies the millisecond interval at which the nodeguarding requests are sent to the given node ID.
bExpectedState
Determines in which state the node is expected to be. This must be one of the following
value meaning NODE_PRE_OPERATIONAL Node must be in pre-operational state NODE_PREPARED Node must be in prepared state NODE_OPERATIONAL Node must be in operational state NODE_ANY_STATE Node must respond
- Function retunrns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Stop nodeguarding for the given node ID.
BOOL StopNodeguarding( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId );
The CANopen network connection this function is called for.
bNodeId
Node ID for which the nodeguarding must be ended.
- Function retunrns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Send a remote request for a PDO previously defined at DefineEmergencyAndPdoCobs.
BOOL SendTxPdoRemoteRequest( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN BYTE bTxPdoNumber );
The CANopen network connection this function is called for.
bNodeId
The node ID to send the request to.
bTxPdoNumber
The requested transmit PDO (1, 2, 3 or 4).
- Function retunrns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Send a PDO previously defined at DefineEmergencyAndPdoCobs to a node ID.
BOOL SendRxPdo( IN CANOPEN_NETWORK CanOpenNetwork, IN BYTE bNodeId, IN BYTE bRxPdoNumber, IN BYTE bDataLength, IN const void* pvData );
The CANopen network connection this function is called for.
bNodeId
The node ID to send the PDO to.
bRxPdoNumber
The number of the receive PDO (1, 2, 3 or 4).
bDataLength
The number of data bytes to send (1..8).
pvData
Pointer to a buffer containing the data to send, numeric data in little endian format (LSB first).
- Function retunrns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Send a SYNC pulse over the CAN bus (COB-ID 128).
BOOL SendCanOpenSync( IN CANOPEN_NETWORK CanOpenNetwork );
The CANopen network connection this function is called for.
- Function retunrns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Send a message
BOOL SendCanOpenMessage( IN CANOPEN_NETWORK CanOpenNetwork, IN WORD wCobId, IN BOOL fRtr, IN BYTE bLen, IN const void* pvData );
The CANopen network connection this function is called for.
wCobId
The COB-ID of the message to send.
fRtr
The Remote Transmit Request flag of the message to send.
bLen
The number of bytes to send (1..8).
pvData
Pointer to a buffer containing the data to send.
- Function retunrns TRUE on success.
- Function returns FALSE on failure. Call GetLastError to get extended error information.
Get information on the CANopen communication settings.
WORD GetCanoComSettings( IN CANOPEN_NETWORK CanOpenNetwork, OUT char* pszInterfaceConfig, OUT DWORD* pdwCanBusBaudrate, OUT DWORD* pdwBufferSize );
The CANopen network connection this function is called for.
pszInterfaceConfig
Pointer to the location that will receive the interface configuration string as it is passed to CreateCanOpenNetwork, or NULL.
pdwCanBusBaudrate
Pointer to a DWORD variable that will receive the CAN bus Baudrate at the interface, or NULL.
pdwBufferSize
Pointer to a DWORD variable that will receive the size of the received messages buffer in number of CAN messages, or NULL.
- Function returns the interface that is used for communication (CAN_INTERFACE_6390, CAN_INTERFACE_ESD or CAN_INTERFACE_NICAN), zero on error. To get extended error information, call GetLastError.