OD interface
CANopen_301

## Modules

| Getters and setters
| Getter and setter helper functions for accessing different types of Object Dictionary variables.
| OD definition objects
| Types and functions used only for definition of Object Dictionary.

## Files

file | CO_ODinterface.h
| CANopen Object Dictionary interface.

## Data Structures

struct | OD_subEntry_t
| Structure describing properties of a variable, located in specific index and sub-index inside the Object Dictionary. More...
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_entry_t
| Object Dictionary entry for one OD object. More...
struct | OD_t
| Object Dictionary. More...

## Macros

#define | OD_size_t uint32_t
| Variable of type OD_size_t contains data length in bytes of OD variable.
#define | OD_flagsPDO_t uint32_t
| Type of flagsPDO variable from OD_subEntry_t.
#define | OD_attr_t uint8_t
| 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_PARAM_FUNC = 0x1010U, OD_H1011_REST_PARAM_FUNC = 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 = 0x01, ODA_SDO_W = 0x02, ODA_SDO_RW = 0x03, ODA_TPDO = 0x04, ODA_RPDO = 0x08, ODA_TRPDO = 0x0C, ODA_TSRDO = 0x10, ODA_RSRDO = 0x20, ODA_TRSRDO = 0x30, ODA_MB = 0x40, ODA_STR = 0x80 }
| 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 = 23, ODR_NO_DATA = 25, ODR_COUNT = 26
}

| Return codes from OD access functions. More...

## Functions

OD_size_t | OD_readOriginal (OD_stream_t *stream, uint8_t subIndex, void *buf, OD_size_t count, ODR_t *returnCode)
| Read value from original OD location. More...
OD_size_t | OD_writeOriginal (OD_stream_t *stream, uint8_t subIndex, const void *buf, OD_size_t count, ODR_t *returnCode)
| Write value to original OD location. More...
const OD_entry_t * | OD_find (const OD_t *od, uint16_t index)
| Find OD entry in Object Dictionary. More...
ODR_t | OD_getSub (const OD_entry_t *entry, uint8_t subIndex, OD_subEntry_t *subEntry, OD_IO_t *io, bool_t odOrig)
| Find sub-object with specified sub-index on OD entry returned by OD_find. More...
static uint16_t | OD_getIndex (const OD_entry_t *entry)
| Return index from OD entry. More...
static void | OD_rwRestart (OD_stream_t *stream)
| Restart read or write operation on OD variable. More...
uint32_t | OD_getSDOabCode (ODR_t returnCode)
| Get SDO abort code from returnCode. More...
ODR_t | OD_extensionIO_init (const OD_entry_t *entry, void *object, OD_size_t(*read)(OD_stream_t *stream, uint8_t subIndex, void *buf, OD_size_t count, ODR_t *returnCode), OD_size_t(*write)(OD_stream_t *stream, uint8_t subIndex, const void *buf, OD_size_t count, ODR_t *returnCode))
| Initialise extended OD object with own read/write functions. More...

## Detailed Description

See Object Dictionary

## 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_PARAM_FUNC | Store params in persistent mem.
OD_H1011_REST_PARAM_FUNC | 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()

OD_size_t OD_readOriginal | ( | OD_stream_t * | stream,
|  | uint8_t | subIndex,
|  | void * | buf,
|  | OD_size_t | count,
|  | ODR_t * | returnCode
| ) |  |

Read value from original OD location.

This function can be used inside read / write functions, specified by OD_extensionIO_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()

OD_size_t OD_writeOriginal | ( | OD_stream_t * | stream,
|  | uint8_t | subIndex,
|  | const void * | buf,
|  | OD_size_t | count,
|  | ODR_t * | returnCode
| ) |  |

Write value to original OD location.

This function can be used inside read / write functions, specified by OD_extensionIO_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()

const OD_entry_t* OD_find | ( | const 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_subEntry_t * | subEntry,
|  | OD_IO_t * | io,
|  | bool_t | odOrig
| ) |  |

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

Function populates subEntry and io structures with sub-object data.

Parameters

  | entry | OD entry returned by OD_find().
  | subIndex | Sub-index of the variable from the OD object.
  [out] | subEntry | Structure will be populated on success, may be NULL.
  [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 | OD entry returned by OD_find().

Returns
  OD index

## 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 initialised by OD_getSub(). It is also not necessary to call this function, if prevous read or write was successfully finished.

Parameters

  stream | Object Dictionary stream object.

## 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_extensionIO_init()

ODR_t OD_extensionIO_init | ( | const OD_entry_t * | entry,
|  | void * | object,
|  | OD_size_t(*)(OD_stream_t *stream, uint8_t subIndex, void *buf, OD_size_t count, ODR_t *returnCode) | read,
|  | OD_size_t(*)(OD_stream_t *stream, uint8_t subIndex, const void *buf, OD_size_t count, ODR_t *returnCode) | write
| ) |  |

Initialise extended OD object with own read/write functions.

This function works on OD object, which has IO extension enabled. It gives application very powerful tool: definition of own IO access on own 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.

If this function is not called yet, then normal access ("odOrig" argument is false) to OD entry is disabled.

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 protected with CO_LOCK_OD() and CO_UNLOCK_OD().

Parameters

  entry | OD entry returned by OD_find().
  object | Object, which will be passed to read or write function.
  read | Read function pointer. If NULL, then read will be disabled. OD_readOriginal can be used here to keep original read function. For function description see OD_IO_t.
  write | Write function pointer. If NULL, then write will be disabled. OD_writeOriginal can be used here to keep original write function. For function description see OD_IO_t.

Returns
  "ODR_OK" on success, "ODR_IDX_NOT_EXIST" if OD object doesn't exist, "ODR_PAR_INCOMPAT" if OD object is not extended.