Detailed Description

With Service Data Objects (SDOs) the access to entries of a device Object Dictionary is provided. As these entries may contain data of arbitrary size and data type SDOs can be used to transfer multiple data sets (each containing an arbitrary large block of data) from a client to a server and vice versa. The client can control via a multiplexor (index and sub-index of the Object Dictionary) which data set is to be transferred. The contents of the data set are defined within the Object Dictionary.

The communication timeout between SDO client request and SDO server response is device/application specific. The initial SDO communication timeout for the client is set to 50 milliseconds. The connection timeout value can be change with the ComSdoSetTimeout() function.

The SDO / USDO communication section explains in detail the usage of the API and provides examples.

Include dependency graph for com_sdo_cln.h:

Enumerations
enum	ComSdoStat_e { eCOM_SDO_STAT_EMPTY = 0 , eCOM_SDO_STAT_EXP_RD = 1 , eCOM_SDO_STAT_SEG_RD = 2 , eCOM_SDO_STAT_BLK_RD = 3 , eCOM_SDO_STAT_EXP_WR = 4 , eCOM_SDO_STAT_SEG_WR = 5 , eCOM_SDO_STAT_BLK_WR = 6 , eCOM_SDO_STAT_SUCCESS = 7 , eCOM_SDO_STAT_ABORT = 8 , eCOM_SDO_STAT_TIMEOUT = 9 , eCOM_SDO_STAT_ERR = 10 , eCOM_SDO_STAT_SIZE = 11 }

enum	ComSdoConfig_e { eCOM_SDO_CONFIG_DEFAULT = 0 , eCOM_SDO_CONFIG_CMD_LEN = 1 , eCOM_SDO_CONFIG_BLOCK = 2 }

Functions
ComStatus_tv	ComSdoGetAbortCode (uint8_t ubNetV, uint8_t ubClientV, uint32_t *pulAbortV)

uint8_t	ComSdoGetClient (uint8_t ubNetV)

ComStatus_tv	ComSdoGetStatus (uint8_t ubNetV, uint8_t ubClientV)

ComStatus_tv	ComSdoReadData (uint8_t ubNetV, uint8_t ubClientV, uint8_t ubNodeIdV, uint16_t uwIndexV, uint8_t ubSubIndexV, void pvdDataV, uint32_t pulDataSizeV, uint32_t *pulErrCodeV)

ComStatus_tv	ComSdoReadObject (uint8_t ubNetV, uint8_t ubClientV, uint8_t ubNodeIdV, CoObject_ts ptsCoObjV, uint32_t pulObjCntV)

ComStatus_tv	ComSdoSetConfiguration (uint8_t ubNetV, uint8_t ubClientV, uint8_t ubConfigV)

ComStatus_tv	ComSdoSetTimeout (uint8_t ubNetV, uint8_t ubClientV, uint16_t uwTimeV)

ComStatus_tv	ComSdoWriteData (uint8_t ubNetV, uint8_t ubClientV, uint8_t ubNodeIdV, uint16_t uwIndexV, uint8_t ubSubIndexV, void pvdDataV, uint32_t pulDataSizeV, uint32_t *pulErrCodeV)

ComStatus_tv	ComSdoWriteObject (uint8_t ubNetV, uint8_t ubClientV, uint8_t ubNodeIdV, CoObject_ts ptsCoObjV, uint32_t pulObjCntV)

Enumeration Type Documentation

◆ ComSdoConfig_e

enum ComSdoConfig_e

SDO client configuration.

The enumeration defines configuration values for the SDO client behaviour, which is set via the function ComSdoSetConfiguration().

Enumerator
eCOM_SDO_CONFIG_DEFAULT	Use SDO client default configuration
eCOM_SDO_CONFIG_CMD_LEN	Set data length for command byte in expedited transfer
eCOM_SDO_CONFIG_BLOCK	Set SDO block transfer for data length > 4 bytes

◆ ComSdoStat_e

enum ComSdoStat_e

SDO transfer status.

The enumeration defines the status of a SDO client connection. It can be requested with the ComSdoGetStatus() function.

Enumerator
eCOM_SDO_STAT_EMPTY	SDO client is free, no SDO communication present
eCOM_SDO_STAT_EXP_RD	Expedited transfer in progress (read)
eCOM_SDO_STAT_SEG_RD	Segmented transfer in progress (read)
eCOM_SDO_STAT_BLK_RD	Block transfer in progress (read)
eCOM_SDO_STAT_EXP_WR	Expedited transfer in progress (write)
eCOM_SDO_STAT_SEG_WR	Segmented transfer in progress (write)
eCOM_SDO_STAT_BLK_WR	Block transfer in progress (write)
eCOM_SDO_STAT_SUCCESS	SDO communication success
eCOM_SDO_STAT_ABORT	SDO communication aborted
eCOM_SDO_STAT_TIMEOUT	SDO communication timeout
eCOM_SDO_STAT_ERR	SDO protocol error
eCOM_SDO_STAT_SIZE	Data size for client/server does not match

Function Documentation

◆ ComSdoGetAbortCode()

ComStatus_tv ComSdoGetAbortCode	(	uint8_t	ubNetV,
		uint8_t	ubClientV,
		uint32_t *	pulAbortV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubClientV	SDO client index
[in]	pulAbortV	Pointer to variable for abort code

Returns: Value of enumeration ComErr_e

This function returns the last SDO abort code, if any occurred. The SDO client connection is selected by the index ubClientV. A negative return value indicates an error. The error values are taken from the ComErr_e enumeration. The return value eCOM_ERR_NONE indicates that there was a SDO abort on the selected SDO client, which is copied to the variable pointed by pulAbortV.

Positive return values indicate the status of a SDO client in use.

◆ ComSdoGetClient()

uint8_t ComSdoGetClient ( uint8_t ubNetV )

Parameters

[in] ubNetV CANopen Network channel

Returns: SDO client index

This function returns the index of an available SDO client. If no SDO client is free, the function will return the value COM_SDO_CLIENT_MAX.

◆ ComSdoGetStatus()

ComStatus_tv ComSdoGetStatus	(	uint8_t	ubNetV,
		uint8_t	ubClientV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubClientV	SDO client index

Returns: Value of enumeration ComErr_e

This function returns the status of a SDO transmission for the SDO client connection given by its index ubClientV. A negative return value indicates an error. The error values are taken from the ComErr_e enumeration. The return value eCOM_SDO_STAT_EMPTY indicates that the SDO client is available for a read/write operation. Positive return values (see ComSdoStat_e) indicate the status of a SDO client in use.

◆ ComSdoReadData()

ComStatus_tv ComSdoReadData	(	uint8_t	ubNetV,
		uint8_t	ubClientV,
		uint8_t	ubNodeIdV,
		uint16_t	uwIndexV,
		uint8_t	ubSubIndexV,
		void *	pvdDataV,
		uint32_t *	pulDataSizeV,
		uint32_t *	pulErrCodeV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubClientV	SDO client index
[in]	ubNodeIdV	Node-ID value
[in]	uwIndexV	Index of object
[in]	ubSubIndexV	Sub-Index of object
[in]	pvdDataV	Pointer to data
[in]	pulDataSizeV	Pointer to data size variable (bytes)
[in]	pulErrCodeV	Pointer to variable for SDO abort code

Returns: Value of enumeration ComErr_e

See also: ComSdoWriteData()

Deprecated:: This function will not be supported in future versions of the CANopen protocol stack. Use ComSdoReadObject() instead.

This function will start the read request for an object that is defined by the parameters uwIndexV and ubSubIndexV for the Node-ID ubNodeIdV. The SDO client can be selected via the parameter ubClientV by the application in the range from 0 to COM_SDO_CLIENT_MAX - 1.

The function is non-blocking, i.e. it returns immediately after the CAN message transmission is requested. In order to check if data has been transferred by the SDO server the ComSdoGetStatus() function should be used. The pointer to the data size variable pulDataSizeV is used to indicate the size of the read buffer. If the buffer size is too small for the read operation the SDO connection will be terminated and the SDO status is set to eCOM_SDO_STAT_SIZE. The number of bytes read from the SDO server is copied in the data size variable on operation success.

The parameter pulErrCodeV points to a variable for the possible SDO abort code. If the abort code is not required by the application, the pointer can be set to 0L.

◆ ComSdoReadObject()

ComStatus_tv ComSdoReadObject	(	uint8_t	ubNetV,
		uint8_t	ubClientV,
		uint8_t	ubNodeIdV,
		CoObject_ts *	ptsCoObjV,
		uint32_t *	pulObjCntV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubClientV	SDO client index
[in]	ubNodeIdV	Node-ID value
[in]	ptsCoObjV	Pointer to CANopen object entry
[in,out]	pulObjCntV	Pointer to variable for object count

Returns: Value of enumeration ComErr_e

See also: ComSdoWriteObject()

This function will start the read request for one or more entries inside the object dictionary of a CANopen device defined by node-ID ubNodeIdV residing inside the CANopen network defined by parameter ubNetV.

The SDO client can be selected via the parameter ubClientV by the application in the range from 0 to COM_SDO_CLIENT_MAX - 1. If multiple SDO clients are supported by the protocol stack, use the ComSdoGetClient() function call to retrieve an available SDO client.

The function is non-blocking, i.e. it returns immediately after the first CAN message transmission is requested. In order to check if data has been transferred by the SDO server the ComSdoGetStatus() function may be used. However, it is advised to use the event handling mechanism which is described in the SDO / USDO communication section.

The parameter ptsCoObjV is a pointer to a CoObject_ts structure. The number of object entries to be read is defined by parameter pulObjCntV. The value of pulObjCntV is altered by the function, make sure that the variable is not local (i.e. not on the stack). After the read operation is accomplished, the value of pulObjCntV will show the number of entries which have been read.

◆ ComSdoSetConfiguration()

ComStatus_tv ComSdoSetConfiguration	(	uint8_t	ubNetV,
		uint8_t	ubClientV,
		uint8_t	ubConfigV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubClientV	SDO client index
[in]	ubConfigV	SDO client configuration value

Returns: Value of enumeration ComErr_e

This function is used to change the behaviour of the SDO client. The possible configuration values are defined via the ComSdoConfig_e enumeration.

◆ ComSdoSetTimeout()

ComStatus_tv ComSdoSetTimeout	(	uint8_t	ubNetV,
		uint8_t	ubClientV,
		uint16_t	uwTimeV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubClientV	SDO client index
[in]	uwTimeV	timeout value in milliseconds

Returns: Value of enumeration ComErr_e

This function sets a timeout value for a SDO communication. If the response to a SDO request by the master takes longer than this timeout value, the state of the communication will be changed to eCOM_SDO_STAT_TIMEOUT. The state of the SDO communication can be evaluated by calling ComSdoGetStatus(). Please note that the timeout value is passed in multiples of 1 millisecond. The timeout value supplied to this function will be rounded towards the next lower value if necessary (depends on timer granularity).

◆ ComSdoWriteData()

ComStatus_tv ComSdoWriteData	(	uint8_t	ubNetV,
		uint8_t	ubClientV,
		uint8_t	ubNodeIdV,
		uint16_t	uwIndexV,
		uint8_t	ubSubIndexV,
		void *	pvdDataV,
		uint32_t *	pulDataSizeV,
		uint32_t *	pulErrCodeV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubClientV	SDO client index
[in]	ubNodeIdV	Node-ID value
[in]	uwIndexV	Index of object
[in]	ubSubIndexV	Sub-Index of object
[in]	pvdDataV	Pointer to data
[in]	pulDataSizeV	Pointer to data size variable (bytes)
[in]	pulErrCodeV	Pointer to variable for SDO abort code

Returns: Value of enumeration ComErr_e

See also: ComSdoReadData()

Deprecated:: This function will not be supported in future versions of the CANopen protocol stack. Use ComSdoWriteObject() instead.

This function will start the write request for an object that is defined by the parameters uwIndexV and ubSubIndexV for the Node-ID ubNodeIdV. The SDO client can be selected via the parameter ubClientV by the application in the range from 0 to COM_SDO_CLIENT_MAX - 1.

The function is non-blocking, i.e. it returns immediately after the CAN message transmission is requested. In order to check if data has been transferred by the SDO server the ComSdoGetStatus() function should be used. The pointer to the data size variable pulDataSizeV is used to indicate the size of the data to be written. If the data size does not match in the SDO server, the write operation will be terminated and the SDO status is set to eCOM_SDO_STAT_SIZE.

The parameter pulErrCodeV points to a variable for the possible SDO abort code. If the abort code is not required by the application, the pointer can be set to 0L.

◆ ComSdoWriteObject()

ComStatus_tv ComSdoWriteObject	(	uint8_t	ubNetV,
		uint8_t	ubClientV,
		uint8_t	ubNodeIdV,
		CoObject_ts *	ptsCoObjV,
		uint32_t *	pulObjCntV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubClientV	SDO client index
[in]	ubNodeIdV	Node-ID value
[in]	ptsCoObjV	Pointer to CANopen object entry
[in,out]	pulObjCntV	Pointer to variable for object count

Returns: Value of enumeration ComErr_e

See also: ComSdoReadObject()

This function will start the write request for one or more entries inside the object dictionary of a CANopen device defined by node-ID ubNodeIdV residing inside the CANopen network defined by parameter ubNetV.

The SDO client can be selected via the parameter ubClientV by the application in the range from 0 to COM_SDO_CLIENT_MAX - 1. If multiple SDO clients are supported by the protocol stack, use the ComSdoGetClient() function call to retrieve an available SDO client.

The function is non-blocking, i.e. it returns immediately after the first CAN message transmission is requested. In order to check if data has been transferred by the SDO server the ComSdoGetStatus() function may be used. However, it is advised to use the event handling mechanism which is described in the SDO / USDO communication section.

The parameter ptsCoObjV is a pointer to a CoObject_ts structure. The number of object entries to be written is defined by parameter pulObjCntV. The value of pulObjCntV is altered by the function, make sure that the variable is not local (i.e. not on the stack). After the write operation is accomplished, the value of pulObjCntV will show the number of entries which have been written.

Detailed Description

Enumerations

Functions

Enumeration Type Documentation

◆ ComSdoConfig_e

◆ ComSdoStat_e

Function Documentation

◆ ComSdoGetAbortCode()

◆ ComSdoGetClient()

◆ ComSdoGetStatus()

◆ ComSdoReadData()

◆ ComSdoReadObject()

◆ ComSdoSetConfiguration()

◆ ComSdoSetTimeout()

◆ ComSdoWriteData()

◆ ComSdoWriteObject()