Object Dictionary¶

CANopen devices must have an object dictionary, which is used for configuration and communication with the device. An entry in the object dictionary is defined by:

Index, the 16-bit address of the object in the dictionary
Object type, such as an array, record, or simple variable
Name, a string describing the entry
Type, gives the datatype of the variable (or the datatype of all variables of an array)
Attribute, which gives information on the access rights for this entry, this can be read/write (rw), read-only (ro) or write-only (wo)

The basic datatypes for object dictionary values such as booleans, integers and floats are defined in the standard, as well as composite datatypes such as strings, arrays and records. The composite datatypes can be subindexed with an 8-bit index; the value in subindex 0 of an array or record indicates the number of elements in the data structure, and is of type UNSIGNED8.

Supported formats¶

The currently supported file formats for specifying a node’s object dictionary are:

EDS (standardized INI-file like format)
DCF (same as EDS with bitrate and node ID specified)
EPF (proprietary XML-format used by Inmotion Technologies)

Examples¶

The object dictionary file is normally provided when creating a node. Here is an example where the entire object dictionary gets printed out:

node = network.add_node(6, 'od.eds')
for obj in node.object_dictionary.values():
    print(f'0x{obj.index:X}: {obj.name}')
    if isinstance(obj, canopen.objectdictionary.ODRecord):
        for subobj in obj.values():
            print(f'  {subobj.subindex}: {subobj.name}')

You can access the objects using either index/subindex or names:

device_name_obj = node.object_dictionary['ManufacturerDeviceName']
vendor_id_obj = node.object_dictionary[0x1018][1]
actual_speed = node.object_dictionary['ApplicationStatus.ActualSpeed']
command_all = node.object_dictionary['ApplicationCommands.CommandAll']

API¶

canopen.export_od(od, dest=None, doc_type=None)[source]¶

Export an object dictionary.

Parameters:

od (ObjectDictionary) – The object dictionary to be exported.
dest (Union[str, TextIO, None]) – The export destination as a filename, a file-like object, or None. If None, the document is written to sys.stdout.
doc_type (Optional[str]) – The type of document to export. If dest is a file-like object or None, doc_type must be explicitly provided. If dest is a filename and its extension is .eds or .dcf, doc_type defaults to that extension (the preceeding dot excluded); else, it defaults to eds.

Raises:

ValueError – When exporting to an unknown format.

Return type:

None

canopen.import_od(source, node_id=None)[source]¶

Parse an EDS, DCF, or EPF file.

Parameters:

source (Union[str, TextIO, None]) – The path to object dictionary file, a file like object, or an EPF XML tree.
node_id (Optional[int]) – For EDS and DCF files, the node ID to use. For other formats, this parameter is ignored.

Raises:

ObjectDictionaryError – For object dictionary errors and inconsistencies.
ValueError – When passed a file of an unknown format.

Return type:

ObjectDictionary

class canopen.ObjectDictionary[source]¶

Representation of the object dictionary as a Python dictionary.

od[index]: Return the object for the specified index (as int) or name (as string).

iter(od): Return an iterator over the indexes from the object dictionary.

index in od: Return True if the index (as int) or name (as string) exists in the object dictionary.

len(od): Return the number of objects in the object dictionary.

values()¶: Return a list of objects (records, arrays and variables).

add_object(obj)[source]¶

Add object to the object dictionary.

Parameters:: obj (Union[ODArray, ODRecord, ODVariable]) – Should be either one of ODVariable, ODRecord, or ODArray.
Return type:: None

bitrate: Optional[int]¶: Default bitrate if specified by file

device_information¶: Some information about the device

get_variable(index, subindex=0)[source]¶

Get the variable object at specified index (and subindex if applicable).

Return type:: Optional[ODVariable]
Returns:: ODVariable if found, else None

node_id: Optional[int]¶: Node ID if specified by file

class canopen.objectdictionary.ODVariable(name, index, subindex=0)[source]¶

Simple variable.

len(var): Return the length of the variable data type in number of bits.

var == other: Return True if the variables have the same index and subindex.

access_type: str¶: Access type, should be “rw”, “ro”, “wo”, or “const”

add_bit_definition(name, bits)[source]¶

Associate bit(s) with a string description.

Parameters:

name (str) – Name of bit(s)
bits (List[int]) – List of bits as integers

Return type:

None

add_value_description(value, descr)[source]¶

Associate a value with a string description.

Parameters:

value (int) – Value to describe
desc – Description of value

Return type:

None

bit_definitions: Dict[str, List[int]]¶: Dictionary of bitfield definitions

data_type: Optional[int]¶: Data type according to the standard as an int

default: Optional[int]¶: Default value at start-up

description: str¶: Description of variable

factor: float¶: Factor between physical unit and integer value

index¶: 16-bit address of the object in the dictionary

max: Optional[int]¶: Maximum allowed value

min: Optional[int]¶: Minimum allowed value

name¶: String representation of the variable

parent¶: The ObjectDictionary, ODRecord or ODArray owning the variable

pdo_mappable¶: Can this variable be mapped to a PDO

property qualname: str¶: Fully qualified name of the variable. If the variable is a subindex of a record or array, the name will be prefixed with the parent’s name.

relative¶: Is the default value relative to the node-ID (only applies to COB-IDs)

storage_location¶: Storage location of index

subindex¶: 8-bit sub-index of the object in the dictionary

unit: str¶: Physical unit

value: Optional[int]¶: The value of this variable stored in the object dictionary

value_descriptions: Dict[int, str]¶: Dictionary of value descriptions

class canopen.objectdictionary.ODRecord(name, index)[source]¶

Groups multiple ODVariable objects using subindices.

record[subindex]: Return the ODVariable for the specified subindex (as int) or name (as string).

iter(record): Return an iterator over the subindexes from the record.

subindex in record: Return True if the subindex (as int) or name (as string) exists in the record.

len(record): Return the number of subindexes in the record.

record == other: Return True if the records have the same index.

values()¶: Return a list of ODVariable in the record.

add_member(variable)[source]¶

Adds a ODVariable to the record.

Return type:: None

description = ''¶: Description for the whole record

index¶: 16-bit address of the record

name¶: Name of record

parent: Optional[ObjectDictionary]¶: The ObjectDictionary owning the record.

storage_location¶: Storage location of index

class canopen.objectdictionary.ODArray(name, index)[source]¶

An array of ODVariable objects using subindices.

Actual length of array must be read from the node using SDO.

array[subindex]: Return the ODVariable for the specified subindex (as int) or name (as string). This will work for all subindexes between 1 and 255. If the requested subindex has not been specified in the object dictionary, it will be created dynamically from the first subindex and suffixing the name with an underscore + the subindex in hex format.

add_member(variable)[source]¶

Adds a ODVariable to the record.

Return type:: None

description = ''¶: Description for the whole array

index¶: 16-bit address of the array

name¶: Name of array

parent¶: The ObjectDictionary owning the record.

storage_location¶: Storage location of index

exception canopen.ObjectDictionaryError[source]¶: Unsupported operation with the current Object Dictionary.

Constants¶

canopen.objectdictionary.UNSIGNED8¶

canopen.objectdictionary.UNSIGNED16¶

canopen.objectdictionary.UNSIGNED32¶

canopen.objectdictionary.UNSIGNED64¶

canopen.objectdictionary.INTEGER8¶

canopen.objectdictionary.INTEGER16¶

canopen.objectdictionary.INTEGER32¶

canopen.objectdictionary.INTEGER64¶

canopen.objectdictionary.BOOLEAN¶

canopen.objectdictionary.REAL32¶

canopen.objectdictionary.REAL64¶

canopen.objectdictionary.VISIBLE_STRING¶

canopen.objectdictionary.OCTET_STRING¶

canopen.objectdictionary.UNICODE_STRING¶

canopen.objectdictionary.DOMAIN¶

canopen.objectdictionary.SIGNED_TYPES¶

canopen.objectdictionary.UNSIGNED_TYPES¶

canopen.objectdictionary.INTEGER_TYPES¶

canopen.objectdictionary.FLOAT_TYPES¶

canopen.objectdictionary.NUMBER_TYPES¶

canopen.objectdictionary.DATA_TYPES¶