OD interface

CANopen Object Dictionary interface. More...

Collaboration diagram for OD interface:

Topics
	Getters and setters
	OD definition objects

Files
file	CO_ODinterface.h
	CANopen Object Dictionary interface.

Data Structures
struct	OD_stream_t
	IO stream structure, used for read/write access to OD variable, part of OD_IO_t. More...
struct	OD_IO_t
	Structure for input / output on the OD variable. More...
struct	OD_extension_t
	Extension of OD object, which can optionally be specified by application in initialization phase with OD_extension_init() function. More...
struct	OD_entry_t
	Object Dictionary entry for one OD object. More...
struct	OD_t
	Object Dictionary. More...

Macros
#define	OD_FLAGS_PDO_SIZE   4U
	Size of of flagsPDO variable inside OD_extension_t, from 0 to 32.
#define	CO_PROGMEM   const
	Modifier for OD objects.

Typedefs
typedef uint32_t	OD_size_t
	Variable of type OD_size_t contains data length in bytes of OD variable.
typedef uint8_t	OD_attr_t
	Type (and size) of Object Dictionary attribute.

Enumerations
enum	OD_ObjDicId_30x_t {   OD_H1000_DEV_TYPE = 0x1000U , OD_H1001_ERR_REG = 0x1001U , OD_H1002_MANUF_STATUS_REG = 0x1002U , OD_H1003_PREDEF_ERR_FIELD = 0x1003U ,   OD_H1004_RSV = 0x1004U , OD_H1005_COBID_SYNC = 0x1005U , OD_H1006_COMM_CYCL_PERIOD = 0x1006U , OD_H1007_SYNC_WINDOW_LEN = 0x1007U ,   OD_H1008_MANUF_DEV_NAME = 0x1008U , OD_H1009_MANUF_HW_VERSION = 0x1009U , OD_H100A_MANUF_SW_VERSION = 0x100AU , OD_H100B_RSV = 0x100BU ,   OD_H100C_GUARD_TIME = 0x100CU , OD_H100D_LIFETIME_FACTOR = 0x100DU , OD_H100E_RSV = 0x100EU , OD_H100F_RSV = 0x100FU ,   OD_H1010_STORE_PARAMETERS = 0x1010U , OD_H1011_RESTORE_DEFAULT = 0x1011U , OD_H1012_COBID_TIME = 0x1012U , OD_H1013_HIGH_RES_TIMESTAMP = 0x1013U ,   OD_H1014_COBID_EMERGENCY = 0x1014U , OD_H1015_INHIBIT_TIME_EMCY = 0x1015U , OD_H1016_CONSUMER_HB_TIME = 0x1016U , OD_H1017_PRODUCER_HB_TIME = 0x1017U ,   OD_H1018_IDENTITY_OBJECT = 0x1018U , OD_H1019_SYNC_CNT_OVERFLOW = 0x1019U , OD_H1020_VERIFY_CONFIG = 0x1020U , OD_H1021_STORE_EDS = 0x1021U ,   OD_H1022_STORE_FORMAT = 0x1022U , OD_H1023_OS_CMD = 0x1023U , OD_H1024_OS_CMD_MODE = 0x1024U , OD_H1025_OS_DBG_INTERFACE = 0x1025U ,   OD_H1026_OS_PROMPT = 0x1026U , OD_H1027_MODULE_LIST = 0x1027U , OD_H1028_EMCY_CONSUMER = 0x1028U , OD_H1029_ERR_BEHAVIOR = 0x1029U ,   OD_H1200_SDO_SERVER_1_PARAM = 0x1200U , OD_H1280_SDO_CLIENT_1_PARAM = 0x1280U , OD_H1300_GFC_PARAM = 0x1300U , OD_H1301_SRDO_1_PARAM = 0x1301U ,   OD_H1381_SRDO_1_MAPPING = 0x1381U , OD_H13FE_SRDO_VALID = 0x13FEU , OD_H13FF_SRDO_CHECKSUM = 0x13FFU , OD_H1400_RXPDO_1_PARAM = 0x1400U ,   OD_H1600_RXPDO_1_MAPPING = 0x1600U , OD_H1800_TXPDO_1_PARAM = 0x1800U , OD_H1A00_TXPDO_1_MAPPING = 0x1A00U }
	Common DS301 object dictionary entries. More...
enum	OD_attributes_t {   ODA_SDO_R = 0x01U , ODA_SDO_W = 0x02U , ODA_SDO_RW = 0x03U , ODA_TPDO = 0x04U ,   ODA_RPDO = 0x08U , ODA_TRPDO = 0x0CU , ODA_TSRDO = 0x10U , ODA_RSRDO = 0x20U ,   ODA_TRSRDO = 0x30U , ODA_MB = 0x40U , ODA_STR = 0x80U }
	Attributes (bit masks) for OD sub-object. More...
enum	ODR_t {   ODR_PARTIAL = -1 , ODR_OK = 0 , ODR_OUT_OF_MEM = 1 , ODR_UNSUPP_ACCESS = 2 ,   ODR_WRITEONLY = 3 , ODR_READONLY = 4 , ODR_IDX_NOT_EXIST = 5 , ODR_NO_MAP = 6 ,   ODR_MAP_LEN = 7 , ODR_PAR_INCOMPAT = 8 , ODR_DEV_INCOMPAT = 9 , ODR_HW = 10 ,   ODR_TYPE_MISMATCH = 11 , ODR_DATA_LONG = 12 , ODR_DATA_SHORT = 13 , ODR_SUB_NOT_EXIST = 14 ,   ODR_INVALID_VALUE = 15 , ODR_VALUE_HIGH = 16 , ODR_VALUE_LOW = 17 , ODR_MAX_LESS_MIN = 18 ,   ODR_NO_RESOURCE = 19 , ODR_GENERAL = 20 , ODR_DATA_TRANSF = 21 , ODR_DATA_LOC_CTRL = 22 ,   ODR_DATA_DEV_STATE = 23 , ODR_OD_MISSING = 24 , ODR_NO_DATA = 25 , ODR_COUNT = 26 }
	Return codes from OD access functions. More...

Functions
ODR_t	OD_readOriginal (OD_stream_t *stream, void *buf, OD_size_t count, OD_size_t *countRead)
	Read value from original OD location.
ODR_t	OD_writeOriginal (OD_stream_t *stream, const void *buf, OD_size_t count, OD_size_t *countWritten)
	Write value to original OD location.
OD_entry_t *	OD_find (OD_t *od, uint16_t index)
	Find OD entry in Object Dictionary.
ODR_t	OD_getSub (const OD_entry_t *entry, uint8_t subIndex, OD_IO_t *io, bool_t odOrig)
	Find sub-object with specified sub-index on OD entry returned by OD_find.
static uint16_t	OD_getIndex (const OD_entry_t *entry)
	Return index from OD entry.
static bool_t	OD_mappable (OD_stream_t *stream)
	Check, if OD variable is mappable to PDO or SRDO.
static void	OD_rwRestart (OD_stream_t *stream)
	Restart read or write operation on OD variable.
static void	OD_requestTPDO (OD_entry_t *entry, uint8_t subIndex)
	Request TPDO, to which OD variable is mapped.
static bool_t	OD_TPDOtransmitted (OD_entry_t *entry, uint8_t subIndex)
	Check if requested TPDO was transmitted.
uint32_t	OD_getSDOabCode (ODR_t returnCode)
	Get SDO abort code from returnCode.
static ODR_t	OD_extension_init (OD_entry_t *entry, OD_extension_t *extension)
	Extend OD object with own read/write functions and/or flagsPDO.

Detailed Description

CANopen Object Dictionary interface.

See Object Dictionary

Macro Definition Documentation

CO_PROGMEM

#define CO_PROGMEM   const

Modifier for OD objects.

This is large amount of data and is specified in Object Dictionary (OD.c file usually)

Enumeration Type Documentation

OD_ObjDicId_30x_t

enum OD_ObjDicId_30x_t

Common DS301 object dictionary entries.

Enumerator
OD_H1000_DEV_TYPE	Device type.
OD_H1001_ERR_REG	Error register.
OD_H1002_MANUF_STATUS_REG	Manufacturer status register.
OD_H1003_PREDEF_ERR_FIELD	Predefined error field.
OD_H1004_RSV	Reserved.
OD_H1005_COBID_SYNC	Sync message cob-id.
OD_H1006_COMM_CYCL_PERIOD	Communication cycle period.
OD_H1007_SYNC_WINDOW_LEN	Sync windows length.
OD_H1008_MANUF_DEV_NAME	Manufacturer device name.
OD_H1009_MANUF_HW_VERSION	Manufacturer hardware version.
OD_H100A_MANUF_SW_VERSION	Manufacturer software version.
OD_H100B_RSV	Reserved.
OD_H100C_GUARD_TIME	Guard time.
OD_H100D_LIFETIME_FACTOR	Life time factor.
OD_H100E_RSV	Reserved.
OD_H100F_RSV	Reserved.
OD_H1010_STORE_PARAMETERS	Store params in persistent mem.
OD_H1011_RESTORE_DEFAULT	Restore default parameters.
OD_H1012_COBID_TIME	Timestamp message cob-id.
OD_H1013_HIGH_RES_TIMESTAMP	High resolution timestamp.
OD_H1014_COBID_EMERGENCY	Emergency message cob-id.
OD_H1015_INHIBIT_TIME_EMCY	Inhibit time emergency message.
OD_H1016_CONSUMER_HB_TIME	Consumer heartbeat time.
OD_H1017_PRODUCER_HB_TIME	Producer heartbeat time.
OD_H1018_IDENTITY_OBJECT	Identity object.
OD_H1019_SYNC_CNT_OVERFLOW	Sync counter overflow value.
OD_H1020_VERIFY_CONFIG	Verify configuration.
OD_H1021_STORE_EDS	Store EDS.
OD_H1022_STORE_FORMAT	Store format.
OD_H1023_OS_CMD	OS command.
OD_H1024_OS_CMD_MODE	OS command mode.
OD_H1025_OS_DBG_INTERFACE	OS debug interface.
OD_H1026_OS_PROMPT	OS prompt.
OD_H1027_MODULE_LIST	Module list.
OD_H1028_EMCY_CONSUMER	Emergency consumer object.
OD_H1029_ERR_BEHAVIOR	Error behaviour.
OD_H1200_SDO_SERVER_1_PARAM	SDO server parameter.
OD_H1280_SDO_CLIENT_1_PARAM	SDO client parameter.
OD_H1300_GFC_PARAM	Global fail-safe command param.
OD_H1301_SRDO_1_PARAM	SRDO communication parameter.
OD_H1381_SRDO_1_MAPPING	SRDO mapping parameter.
OD_H13FE_SRDO_VALID	SRDO Configuration valid.
OD_H13FF_SRDO_CHECKSUM	SRDO configuration checksum.
OD_H1400_RXPDO_1_PARAM	RXPDO communication parameter.
OD_H1600_RXPDO_1_MAPPING	RXPDO mapping parameters.
OD_H1800_TXPDO_1_PARAM	TXPDO communication parameter.
OD_H1A00_TXPDO_1_MAPPING	TXPDO mapping parameters.

OD_attributes_t

enum OD_attributes_t

Attributes (bit masks) for OD sub-object.

Enumerator
ODA_SDO_R	SDO server may read from the variable.
ODA_SDO_W	SDO server may write to the variable.
ODA_SDO_RW	SDO server may read from or write to the variable.
ODA_TPDO	Variable is mappable into TPDO (can be read)
ODA_RPDO	Variable is mappable into RPDO (can be written)
ODA_TRPDO	Variable is mappable into TPDO or RPDO.
ODA_TSRDO	Variable is mappable into transmitting SRDO.
ODA_RSRDO	Variable is mappable into receiving SRDO.
ODA_TRSRDO	Variable is mappable into tx or rx SRDO.
ODA_MB	Variable is multi-byte ((u)int16_t to (u)int64_t)
ODA_STR	Shorter value, than specified variable size, may be written to the variable. SDO write will fill remaining memory with zeroes. Attribute is used for VISIBLE_STRING and UNICODE_STRING.

ODR_t

enum ODR_t

Return codes from OD access functions.

OD_getSDOabCode() can be used to retrieve corresponding SDO abort code.

Enumerator
ODR_PARTIAL	Read/write is only partial, make more calls.
ODR_OK	SDO abort 0x00000000 - Read/write successfully finished.
ODR_OUT_OF_MEM	SDO abort 0x05040005 - Out of memory.
ODR_UNSUPP_ACCESS	SDO abort 0x06010000 - Unsupported access to an object.
ODR_WRITEONLY	SDO abort 0x06010001 - Attempt to read a write only object.
ODR_READONLY	SDO abort 0x06010002 - Attempt to write a read only object.
ODR_IDX_NOT_EXIST	SDO abort 0x06020000 - Object does not exist in the object dict.
ODR_NO_MAP	SDO abort 0x06040041 - Object cannot be mapped to the PDO.
ODR_MAP_LEN	SDO abort 0x06040042 - PDO length exceeded.
ODR_PAR_INCOMPAT	SDO abort 0x06040043 - General parameter incompatibility reasons.
ODR_DEV_INCOMPAT	SDO abort 0x06040047 - General internal incompatibility in device.
ODR_HW	SDO abort 0x06060000 - Access failed due to hardware error.
ODR_TYPE_MISMATCH	SDO abort 0x06070010 - Data type does not match.
ODR_DATA_LONG	SDO abort 0x06070012 - Data type does not match, length too high.
ODR_DATA_SHORT	SDO abort 0x06070013 - Data type does not match, length too short.
ODR_SUB_NOT_EXIST	SDO abort 0x06090011 - Sub index does not exist.
ODR_INVALID_VALUE	SDO abort 0x06090030 - Invalid value for parameter (download only)
ODR_VALUE_HIGH	SDO abort 0x06090031 - Value range of parameter written too high.
ODR_VALUE_LOW	SDO abort 0x06090032 - Value range of parameter written too low.
ODR_MAX_LESS_MIN	SDO abort 0x06090036 - Maximum value is less than minimum value.
ODR_NO_RESOURCE	SDO abort 0x060A0023 - Resource not available: SDO connection.
ODR_GENERAL	SDO abort 0x08000000 - General error.
ODR_DATA_TRANSF	SDO abort 0x08000020 - Data cannot be transferred or stored to app.
ODR_DATA_LOC_CTRL	SDO abort 0x08000021 - Data can't be transferred (local control)
ODR_DATA_DEV_STATE	SDO abort 0x08000022 - Data can't be transf. (present device state)
ODR_OD_MISSING	SDO abort 0x08000023 - Object dictionary not present.
ODR_NO_DATA	SDO abort 0x08000024 - No data available.
ODR_COUNT	Last element, number of responses.

Function Documentation

OD_readOriginal()

ODR_t OD_readOriginal	(	OD_stream_t *	stream,
		void *	buf,
		OD_size_t	count,
		OD_size_t *	countRead )

Read value from original OD location.

This function can be used inside read / write functions, specified by OD_extension_init(). It reads data directly from memory location specified by Object dictionary. If no IO extension is used on OD entry, then io->read returned by OD_getSub() equals to this function. See also OD_IO_t.

OD_writeOriginal()

ODR_t OD_writeOriginal	(	OD_stream_t *	stream,
		const void *	buf,
		OD_size_t	count,
		OD_size_t *	countWritten )

Write value to original OD location.

This function can be used inside read / write functions, specified by OD_extension_init(). It writes data directly to memory location specified by Object dictionary. If no IO extension is used on OD entry, then io->write returned by OD_getSub() equals to this function. See also OD_IO_t.

OD_find()

OD_entry_t * OD_find	(	OD_t *	od,
		uint16_t	index )

Find OD entry in Object Dictionary.

Parameters

od	Object Dictionary
index	CANopen Object Dictionary index of object in Object Dictionary

Returns

Pointer to OD entry or NULL if not found

OD_getSub()

ODR_t OD_getSub	(	const OD_entry_t *	entry,
		uint8_t	subIndex,
		OD_IO_t *	io,
		bool_t	odOrig )

Find sub-object with specified sub-index on OD entry returned by OD_find.

Function populates io structure with sub-object data.

Warning

Read and write functions may be called from different threads, so critical sections in custom functions must be observed, see Critical sections.

Parameters

	entry	Object Dictionary entry.
	subIndex	Sub-index of the variable from the OD object.
[out]	io	Structure will be populated on success.
	odOrig	If true, then potential IO extension on entry will be ignored and access to data entry in the original OD location will be returned

Returns

Value from ODR_t, "ODR_OK" in case of success.

OD_getIndex()

static uint16_t OD_getIndex ( const OD_entry_t * entry )

inlinestatic

Return index from OD entry.

Parameters

entry

Object Dictionary entry.

Returns

OD index

OD_mappable()

static bool_t OD_mappable ( OD_stream_t * stream )

inlinestatic

Check, if OD variable is mappable to PDO or SRDO.

If OD variable is mappable, then it may be necessary to protect read/write access from mainline function. See Critical sections.

Parameters

stream

Object Dictionary stream object.

Returns

true, if OD variable is mappable.

OD_rwRestart()

static void OD_rwRestart ( OD_stream_t * stream )

inlinestatic

Restart read or write operation on OD variable.

It is not necessary to call this function, if stream was initialized by OD_getSub(). It is also not necessary to call this function, if previous read or write was successfully finished.

Parameters

stream

Object Dictionary stream object.

OD_requestTPDO()

static void OD_requestTPDO ( OD_entry_t * entry, uint8_t subIndex )

inlinestatic

Request TPDO, to which OD variable is mapped.

Function clears the flagPDO bit, which corresponds to OD variable at specific OD index and subindex. For this functionality to work, OD_extension_t must be enabled on OD variable. If OD variable is mapped to any TPDO with event driven transmission, then TPDO will be transmitted after this function call. If OD variable is mapped to more than one TPDO with event driven transmission, only the first matched TPDO will be transmitted.

TPDO event driven transmission is enabled, if TPDO communication parameter, transmission type is set to 0, 254 or 255. For other transmission types (synchronous) flagPDO bit is ignored.

Parameters

entry	Object Dictionary entry.
subIndex	subIndex of the OD variable.

OD_TPDOtransmitted()

static bool_t OD_TPDOtransmitted ( OD_entry_t * entry, uint8_t subIndex )

inlinestatic

Check if requested TPDO was transmitted.

Parameters

entry	Object Dictionary entry.
subIndex	subIndex of the OD variable.

Returns

Return true if event driven TPDO with mapping to OD variable, indicated by entry and subIndex, was transmitted since last OD_requestTPDO call. If there was no OD_requestTPDO call yet and TPDO was transmitted by other event, function also returns true.

OD_getSDOabCode()

uint32_t OD_getSDOabCode

(

ODR_t

returnCode

)

Get SDO abort code from returnCode.

Parameters

returnCode

Returned from some OD access functions

Returns

Corresponding CO_SDO_abortCode_t

OD_extension_init()

static ODR_t OD_extension_init ( OD_entry_t * entry, OD_extension_t * extension )

inlinestatic

Extend OD object with own read/write functions and/or flagsPDO.

This function gives application very powerful tool: definition of own IO access on OD object. Structure and attributes are the same as defined in original OD object, but data are read directly from (or written directly to) application specified object via custom function calls.

Before this function specifies extension, OD variables are accessed from original OD location. After this function specifies extension OD variables are accessed from read/write functions specified by extension. (Except when "odOrig" argument to OD_getSub() is set to true.)

This function must also be used, when flagsPDO needs to be enabled for specific entry.

Warning

Object dictionary storage works only directly on OD variables. It does not access read function specified here. So, if extended OD objects needs to be preserved, then OD_writeOriginal can be used inside custom write function.

Read and write functions may be called from different threads, so critical sections in custom functions must be observed, see Critical sections.

Parameters

entry	Object Dictionary entry.
extension	Extension object, which must be initialized externally. Extension object must exist permanently. If NULL, extension will be removed.

Returns

"ODR_OK" on success, "ODR_IDX_NOT_EXIST" if OD object doesn't exist.