Object Dictionary#
The object dictionary component provides the interface to object entries in the object dictionary.
Module Context#
classDiagram
CO_NODE o-- CO_DICT : Node
CO_OBJ o-- CO_DICT : Root
CO_ERR -- CO_DICT
class CO_DICT {
-uint16_t Num
-uint16_t Max
+CODictFind(key) CO_OBJ
+CODictRdBuffer(key, destination, size) CO_ERR
+CODictRdByte(key, destination) CO_ERR
+CODictRdLong(key, destination) CO_ERR
+CODictRdWord(key, destination) CO_ERR
+CODictWrBuffer(key, source, size) CO_ERR
+CODictWrByte(key, value) CO_ERR
+CODictWrLong(key, value) CO_ERR
+CODictWrWord(key, value) CO_ERR
}
class CO_ERR {
<<enumeration>>
}
Structure Data#
The class CO_DICT
is defined within co_dict.h
and is responsible for the object dictionary handling functions. The following data members are allocated in this class:
Data Member | Type | Description |
---|---|---|
Max | uint16_t |
maximum number of objects in dictionary |
Node | CO_NODE* |
pointer to parent node |
Num | uint16_t |
current number of objects in dictionary |
Root | CO_OBJ* |
pointer to the first object in object dictionary |
Info
The data within this structure must never be manipulated without the corresponding class member functions. This can lead to unpredictable behavior of the node.
Member Functions#
Warning
The access with the member functions of this class to an object entry must be done with the correct width. There is no casting of the object entry values to the requested value types.
The following table describes the API functions of the object dictionary module. These functions are implemented within the source file: co_dict.c/h
CODictFind()#
The function is often called from the application to get an object entry. If an object entry is not found, this generates no stack error.
Prototype
CO_OBJ *CODictFind(CO_DICT *cod, uint32_t key);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
Returned Value
>0
: pointer to identified object entry=0
: object entry is not found
Example
The following example checks the existence of the mandatory object entry "[1017:00] - Heartbeat" within the object dictionary of the CANopen node AppNode.
CO_OBJ *obj;
:
obj = CODictFind(&(Appnode.Dict), CO_DEV(0x1017, 0x00));
if (obj == 0) {
/* object [1017:00] is missing */
} else {
/* object [1017:00] is available */
}
:
Note
When using a static object dictionary, you can store and reuse the pointer to the identified object entry with the Object Entry access functions. The pointer to the object entry will NOT change during runtime in a static object dictionary.
Important
The CANopen Stack relies on a binary search algorithm to ensure that object dictionary entries are found quickly. Because of this, you must keep the index / subindex of all entries in the object dictionary sorted in ascending order.
CODictRdBuffer()#
The object entry is addressed with the given key and the bytes will be read from the dictionary and copied to the given destination buffer with the given length.
Prototype
CO_ERR CODictRdBuffer(CO_DICT *cod,
uint32_t key,
uint8_t *buffer,
uint32_t size);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
buffer | pointer to the destination bytes |
size | size of destination buffer in number of bytes |
Returned Value
== CO_ERR_NONE
: successful operation!= CO_ERR_NONE
: an error is detected
Example
The following example reads the value to the hypothetical application-specific object entry "[1234:56]" within the object dictionary of the CANopen node AppNode.
CO_ERR err;
uint8_t buffer[10];
:
err = CODictRdBuffer(&(Appnode.Dict), CO_DEV(0x1234, 0x56), buffer, 10);
if (err != CO_ERR_NONE) {
/* object [1234:56] is missing or error during writing */
}
:
CODictRdByte()#
The object entry is addressed with the given key and the value will be written to the given destination pointer.
Prototype
CO_ERR CODictRdByte(CO_DICT *cod, uint32_t key, uint8_t *value);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
value | pointer to value destination |
Returned Value
== CO_ERR_NONE
: successful operation!= CO_ERR_NONE
: an error is detected
Example
The following example reads the current value of the hypothetical application-specific object entry "[1234:56]" within the object dictionary of the CANopen node AppNode.
CO_ERR err;
uint8_t value;
:
err = CODictRdByte(&(Appnode.Dict), CO_DEV(0x1234, 0x56), &value);
if (err != CO_ERR_NONE) {
/* object [1234:56] is missing or error during reading */
} else {
/* value holds the content of object [1234:56] */
}
:
Note
This function uses CODictFind()
on each function call. To improve access performance for multiple accesses to a single object entry, the application may use CODictFind()
once and COObjRdValue()
multiple times.
CODictRdLong()#
The object entry is addressed with the given key and the value will be written to the given destination pointer.
Prototype
CO_ERR CODictRdLong(CO_DICT *cod, uint32_t key, uint32_t *value);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
value | pointer to value destination |
Returned Value
== CO_ERR_NONE
: successful operation!= CO_ERR_NONE
: an error is detected
Example
The following example reads the current value of the hypothetical application-specific object entry "[1234:56]" within the object dictionary of the CANopen node AppNode.
CO_ERR err;
uint32_t value;
:
err = CODictRdLong(&(Appnode.Dict), CO_DEV(0x1234, 0x56), &value);
if (err != CO_ERR_NONE) {
/* object [1234:56] is missing or error during reading */
} else {
/* value holds the content of object [1234:56] */
}
:
Note
This function uses CODictFind()
on each function call. To improve access performance for multiple accesses to a single object entry, the application may use CODictFind()
once and COObjRdValue()
multiple times.
CODictRdWord()#
The object entry is addressed with the given key and the value will be written to the given destination pointer.
Prototype
CO_ERR CODictRdWord(CO_DICT *cod, uint32_t key, uint16_t *value);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
value | pointer to value destination |
Returned Value
== CO_ERR_NONE
: successful operation!= CO_ERR_NONE
: an error is detected
Example
The following example reads the current value of the hypothetical application-specific object entry "[1234:56]" within the object dictionary of the CANopen node AppNode.
CO_ERR err;
uint16_t value;
:
err = CODictRdWord(&(Appnode.Dict), CO_DEV(0x1234, 0x56), &value);
if (err != CO_ERR_NONE) {
/* object [1234:56] is missing or error during reading */
} else {
/* value holds the content of object [1234:56] */
}
:
Note
This function uses CODictFind()
on each function call. To improve access performance for multiple accesses to a single object entry, the application may use CODictFind()
once and COObjRdValue()
multiple times.
CODictWrBuffer()#
The object entry is addressed with the given key and the bytes will be read from to the given source buffer of the given size.
Prototype
CO_ERR CODictWrBuffer(CO_DICT *cod,
uint32_t key,
uint8_t *buffer,
uint32_t size);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
buffer | pointer to the source bytes |
size | size of source buffer |
Returned Value
== CO_ERR_NONE
: successful operation!= CO_ERR_NONE
: an error is detected
Example
The following example writes the value to the hypothetical application-specific object entry "[1234:56]" within the object dictionary of the CANopen node AppNode.
CO_ERR err;
uint8_t buffer[10] = { 'a','b','c','d','e','f','g','h','i', 0 };
:
err = CODictWrBuffer(&(Appnode.Dict), CO_DEV(0x1234, 0x56), buffer, 10);
if (err != CO_ERR_NONE) {
/* object [1234:56] is missing or error during writing */
}
:
CODictWrByte()#
The object entry is addressed with the given key.
Prototype
CO_ERR CODictWrByte(CO_DICT *cod, uint32_t key, uint8_t value);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
value | the source value |
Returned Value
== CO_ERR_NONE
: successful operation!= CO_ERR_NONE
: an error is detected
Example
The following example writes the value to the hypothetical application-specific object entry "[1234:56]" within the object dictionary of the CANopen node AppNode.
CO_ERR err;
uint8_t value = 0x30;
:
err = CODictWrByte(&(Appnode.Dict), CO_DEV(0x1234, 0x56), value);
if (err != CO_ERR_NONE) {
/* object [1234:56] is missing or error during writing */
}
:
Note
This function uses CODictFind()
on each function call. To improve access performance for multiple accesses to a single object entry, the application may use CODictFind()
once and COObjWrValue()
multiple times.
CODictWrLong()#
The object entry is addressed with the given key.
Prototype
CO_ERR CODictWrLong(CO_DICT *cod, uint32_t key, uint32_t value);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
value | the source value |
Returned Value
== CO_ERR_NONE
: successful operation!= CO_ERR_NONE
: an error is detected
Example
The following example writes the value to the hypothetical application-specific object entry "[1234:56]" within the object dictionary of the CANopen node AppNode.
CO_ERR err;
uint32_t value = 0x30;
:
err = CODictWrLong(&(Appnode.Dict), CO_DEV(0x1234, 0x56), value);
if (err != CO_ERR_NONE) {
/* object [1234:56] is missing or error during writing */
}
:
Note
This function uses CODictFind()
on each function call. To improve access performance for multiple accesses to a single object entry, the application may use CODictFind()
once and COObjWrValue()
multiple times.
CODictWrWord()#
The object entry is addressed with the given key.
Prototype
CO_ERR CODictWrWord(CO_DICT *cod, uint32_t key, uint16_t value);
Arguments
Parameter | Description |
---|---|
cod | pointer to the object dictionary |
key | object entry key; should be generated with CO_DEV |
value | the source value |
Returned Value
== CO_ERR_NONE
: successful operation!= CO_ERR_NONE
: an error is detected
Example
The following example writes the value to the hypothetical application-specific object entry "[1234:56]" within the object dictionary of the CANopen node AppNode.
CO_ERR err;
uint16_t value = 0x30;
:
err = CODictWrWord(&(Appnode.Dict), CO_DEV(0x1234, 0x56), value);
if (err != CO_ERR_NONE) {
/* object [1234:56] is missing or error during writing */
}
:
Note
This function uses CODictFind()
on each function call. To improve access performance for multiple accesses to a single object entry, the application may use CODictFind()
once and COObjWrValue()
multiple times.