Advantech CANopen Library User Manual

CANopen Library User Manual

V1.04

April 2013

Table of Contents

1. Introduction ......................................................................................................................................... 1

1.1. CANopen architecture ........................................................................................................ 1

1.2. Object Dictionary setting .................................................................................................... 4

1.2.1. Service Data Objects (SDO) ....................................................................................... 4

1.2.2. Process Data Objects (PDO) ....................................................................................... 5

1.2.3. SYNC setting .............................................................................................................. 7

1.2.4. Heartbeat ..................................................................................................................... 7

1.3. Reference ............................................................................................................................ 8

2. Advantech CANopen Protocol Library .............................................................................................. 9

2.1. Overview ............................................................................................................................. 9

2.2. Object Diagram ................................................................................................................. 10

2.3. Runtime Environment ........................................................................................................ 11

2.4. API Functions ................................................................................................................... 12

2.4.1. Overview ................................................................................................................... 12

2.4.2. Flow chart ................................................................................................................. 14

2.4.3. Definition and Structures .......................................................................................... 16

2.4.4. Error codes ................................................................................................................ 18

2.4.5. acoapi Functions ....................................................................................................... 23

3. Advantech CANopen Examples ....................................................................................................... 74

3.1. Overview ........................................................................................................................... 74

3.2. Example usage .................................................................................................................. 74

4. Advantech CANopen Network Utility ............................................................................................. 76

4.1. Overview ........................................................................................................................... 76

4.2. Configure CANopen Network .......................................................................................... 77

4.2.1. Create CANopen Network ........................................................................................ 77

4.2.2. Create slave node ...................................................................................................... 78

4.2.3. Configure Node ......................................................................................................... 79

4.2.4. Import EDS File ........................................................................................................ 79

4.2.5. Create new data type ................................................................................................. 79

4.2.6. Configure the communication parameters ................................................................ 80

4.2.7. Create and configure SDO ........................................................................................ 82

4.2.8. Create and configure PDO ........................................................................................ 82

4.2.9. Create manufacture variable ..................................................................................... 85

4.2.10. Save the configuration .............................................................................................. 86

4.3. Manger CANopen network ............................................................................................... 87

4.3.1. Enter run mode .......................................................................................................... 87

4.3.2. Monitor Node Data ................................................................................................... 88

4.3.3. Control Network ....................................................................................................... 90

4.3.4. Exit Run Mode .......................................................................................................... 92

APPENDIX ............................................................................................................................................... 93

1. Introduction

1.1. CANopen architecture

CANopen, application layer communication protocol based on CAN bus, is widely used in distributed
industrial automation system, medical system, maritime system, etc. CANopen is made up of a
series of sub-protocol sets which can be divided into two parts. The first part is communication
sub-protocol set that defines the basic communication modes and objects of all the devices. This
part consists of DS-301, DS-302, DS-306, etc., among which DS-301 mainly describes
specifications and definitions of CANopen application layer communication objects and other
protocols are supplements to CANopen network on the basis of DS-301. The other part, device
sub-protocol set, defines the function and data definition of standard devices which are of different
types. These sub-protocols contain DS-401, DS-402, etc. Each device of CANopen describes its
property and functions in standard Electronic Data Sheets (EDS) files. CANopen devices must
strictly take the definitions in EDS files as their specifications and support perfect device exchange.

Application Layer

Device Profiles

CiA 401: D evice profile for generic I/O modules
CiA 402: Device profile for drives and motion control (servo controller, stepper
motor controller, frequency inverter)
…

DS-306 EDS spec for CANopen

CANopen DS-301,
DSP-302…

CAN Bus Driver Interface

CAN Bus

Basic communication objects of CANopen are:
OD (Object Dictionary), generated from the devices’ EDS files, and describes all properties and

communication objects of the device. It’s the core definition of CANopen devices. Object

- 1 -

Dictionary is composed of sequential object lists. Each object applies a 16-bit index as its
addressing. Each object can be made up of several elements or a single element uses an 8-bit sub­index as its addressing.

SDO (Service Data Object) can access and configure Object Dictionary in remote nodes via index
and sub-index of Object Dictionary. The object that requests to access is regarded as Client, and
the object which is requested is Server. The length of request messages and response messages
remains 8 bytes, including SDO command (1 byte), index of the object to be accessed (2 bytes),
sub-index of the object to be accessed (1 byte) and 4 bytes of data to be transmitted. The SDO
protocol can transmit data of any size. If the data is over 4 bytes, the message will be segmented
into several parts.

The term SDO Read means SDO upload protocol, the client of a SDO uploads data from the server.
SDO Write means SDO download protocol; the client of a SDO downloads data to the server.

PDO (Process Data Object) is used for high speed data exchange. The length of transmitted data is
limited to 1-8 bytes. PDO contains many transmitting trigger ways, such as cycle transmitting
(synchronized, time driven), triggered by remote frame, triggered by particular events, etc.

NMT (Network Management) belongs to master-slave mode. One NMT master can correspond to
several NMT Slaves. NMT master detects status of each node of the network and completes status
conversion. It supports the function of monitoring the device’s status by heartbeat, Node guarding
or Life guarding. The diagram in Figure 1 illustrates the major states a slave node can be in. Starts
the CANopen network or power on a node, it goes into NMT state Initialisation. At the end of
initialization the slave node tries to transmit its boot-up message to NMT master to report that
boot-up has been finished and has entered pre-operation status. An NMT master can switch
individual slave node or all nodes back and forth between the three major states: Pre-operational,
Operational, and Stopped.

- 2 -

Initialisation

Pre-Operational

Stopped

Operational

Figure 1: State diagram of a node

SYNC (Synchronization) makes the devices in the network possess synchronous capability. Only
one node can produces the SYNC signal in a system as SYNC producer, which can be NMT master
or other slave node. It is the time period in microseconds with which the SY NC signal occurs; the
node has this value availa ble in the OD entry [1006h, 0 0h].

Heartbeat or Node Guarding is a method to detect the node is live or not, and retrieves the
status of a node. Recommend using heartbeat instead of node guarding less bandwidth, is more
flexible. The node as heartbeat producer transmits heartbeat message cyclically, consisting of a 1­byte the current NMT state the node is in.

EMCY (Emergency) will be triggered if fatal errors occur inside the device, similar to error interru pt
mode.

The relation between NMT states and communication objects shows in Table 1: NMT states and
communication objects. It defines the communication objects can be serviced in the appropriate
NMT state if the CANopen devices support. For example: the PDO is a critical message can be
transmitted only in NMT state Operational otherwise can not.

Table 1: NMT states and communication objects

Object

State

PDO V

Pre-operational Operational Stopped

- 3 -

SDO V V

SYNC V V

TIME V V

EMCY V V

NMT V V V

1.2. Object Dictionary setting

The object dictionary is generated from the EDS file, describes all properties and communication
object of the CANopen device. It is the core that the behavior of the CANop en device depends on.
Detail information reference CiA DS301 [1] Communication profile. This section describes how to
configure the Object Dictionary for a node to be a SDO client or SDO server, can transmit/receive
PDO message, and send SYNC message and heartbeat.

1.2.1. Service Data Objects (SDO)

Generally in CANopen network, each node implements only one SDO server (object 1200h) that
handles read and write request its object dictionary from other nodes as SDO client. SDO client
defined at object 1280h to 12FFh.

- 4 -

1.2.2. Process Data Objects (PDO)

PDO can be distinguishing between Transmit Process Data Object (TPDO) and Receive P roces s Data
Object (RPDO). One node produces a PDO, which is a TPDO for that node. Other nodes receive the
PDO, which is an RPDO (consumer).

The communication parameters for a TPDO are at object dictionary of index 1800h to 19FFh
(indicating which CAN message is used for the PDO and how is it triggered), but index 1804h –
19FFh default are disabled by CiA DS301 [1]. And the mapping parameters are at index 1A00h to
1BFFh. acoapi library supports above 4 PDOs up to 512 PDOs. The COB-ID of above 4 PDOs can
be self-defined and/or using CAN2.0B CAN message format that means the 29-bit of COB-ID could
be 1, and lower 7 bit is defined as NodeId.

The transmit trigger method is defined in sub-index 02h transmission type. The value is 0-240 and
252 means that the PDO is transferred synchronously and cyclically. The transmission type 254
means that defined by manufacturer specific (manufacturer specific part of the object dictionary),
255 means defined by device profile. In transmission type 254 and 255 that can use event timer
for trigger in an elapsed timer that are in sub-index 05h of the TPDO, and also support Change-Of­State (COS) transmission method simply transmits a TPDO message if the process data is in
changes else not transmits even the event timer or inhibited timer is expired .

PDO Parameters

Sub-index 00h Number of sub-index

01h COB-ID, 180h + NODE-ID
02h Transmission type: 0-255
03h Inhibit time, multiple of 100 μs
04h Reserved

Event timer, multiple of 1 ms

05h

0: disable

For example: A node that node identifier is 2h, another node is 5h. Figure 2: PDO Linking
illustrates the relation of the PDO linking that Node 2h transmits TPDO_1 to Node 5h, Node 5h
receives the PDO as RPDO and update the data to object dictionary of specified index and sub­index.

- 5 -

Node 2h OD

[6000h,03]
[2010h,21]

Node 2h

TPDO_1
TPDO_2
TPDO_3

Figure 2: PDO Linking

Node 5h

RPDO_1
RPDO_2
RPDO_3

Node 5h OD

[6000h,03]
[2010h,21]

Following is the example to describe how to set the value to the PDO in object dictionary.
 TPDO setting example
A node with n ode id ent ifier 0x02, the PDO is transmitted on synchrony. It contains 6 bytes of data:

DataX (2 bytes) and DataY (4 bytes). DataX is defined at index 6000h sub-index 03h. DataY is
defined at index 0x2010 sub-index 21h. The result of object dictionary setting about TPDO1 is
shown in Table 2: TPDO1 setting example.

Table 2: TPDO1 setting example

Index [1800h] value description

Sub-index 00h 2

01h 0x182 180h + Node-ID 0x2
02h 200 the PDO is transmitted every reception of <200> SYNC

Index [1A00h] value description

Sub-index 00h 2 write the number of data embedded in the PDO (1byte)

01h 0x60000308 Where to find of data embedded and the size. (8 bytes)

Format: index(2 bytes) – sub-index(1 byte) – size in bits(1 byte)
DataX is at object [6000h, 03h] with 8 bits

02h 0x20102120 where to find the second data embedded an the size (8bytes)

DataY is at object [2010h, 21h] with 32 bits

 RPDO setting example
Another node 0x05 needs to be configured to directly listen for the TPDO1 transmitted by node

0x02. RPDO1 of node 0x05 should be used to receive TPDO1 of node 0x02.

Table 3: RPDO setting example

Index [1400h] value description

Sub-index 00h 2

01h 0x182 180h + Node-ID 0x2
02h 200 the PDO is transmitted every reception of <200> SYNC

- 6 -

Index [1600h] value description

Sub-index 00h 2 write the number of data embedded in the PDO (1byte)

01h 0x60000308 Where to find of data embedded and the size. (8 bytes)

Format: index(2 bytes) – sub-index(1 byte) – size in bits(1 byte)
DataX is at object [6000h, 03h] with 8 bits

02h 0x20102120 where to find the second data embedded an the size (8bytes)

DataY is at object [2010h, 21h] with 32 bits

1.2.3. SYNC setting

A node as SYNC producer broadcasts the synchronization object periodically, which provides the
basic network synchronization. The time period in μs between SYNC is defined at index 1006h
Communication cycle per iod of object dictionary. And mandatory if the node generates the SYNC
object, the allow bit 30 at object 1005h must to be set.

Table 4: SYNC COB-ID (1005h) setting exam ple

Index [1005h] value description

DefaultValue

0x00000080
or
0x40000080

Example: 11-bit SYNC COB-ID is 80h.
Bit 30 set to 0 means the node does not generate the SYNC object.
Bit 30 set to 1 means the node generates the SYNC object.

Table 5: Communicate Cycle Period (1006h) setting example

Index [1006h] value description

The time period is 0 means do not transmit the SYNC object. Other

DefaultValue 0 or

t

value in μs means the node generate the SYNC object in every <t>
μs if allow bit 30 is set at index 1005h.
Example: DefaultValue=0x001E8480, transmit every 2 seconds

1.2.4. Heartbeat

According to CiA DS301 [1], a CANopen node must support either heartbeat or node guarding
protocol that can be monitoring the node is live or not. The heartbeat protocol is preferred since
with the less bandwidth, so that the producer heartbeat time at index 1017h must be implemented.

Table 6: Producer Heartbeat Time (1017h) setting example

Index [1017h] value description

0

DefaultValue

or

The time period is 0 means disable transmission of heartbeat
message by the node. Other value specifies in milliseconds the time

- 7 -

t between transmissions of heartbeat messages.

Example: DefaultValue=0x1388, the node transmits the heartbeat
message every 5 seconds.

Other nodes (heartbeat consumers) can monitor the node whether the heartbeat is transmitted in
specified time as heartbeat consumer time. If the heartbeat is not received within the heartbeat
consumer time, a heartbeat error event will be trigger. The index 1016h of object dictionary
specifies the maximum time to wait for a heartbeat from a specific node, which maximum 7Fh
nodes. The consumer heartbeat time should be greater than the producer heartbeat time.

Table 7: Consumer Heartbeat Time (1016h) setting example

Index [1016h] value Description

Sub-index 00h 1 Number of entries

01h 0x005A1122 Consumer heartbeat time

The format is: bit 0-15 heartbeat consumer time, bit 16-23

02h – 7Fh

monitored node id, bit 24-31 reserved (set to 0).
Example: DefaultValue=0x00051B58, This node must receives the
heartbeat message from the node 5h within 7 seconds, else trigger
a heartbeat error event for n od e 5.

1.3. Reference

1 [CiADS301] CANopen Application Layer and Communication Profile, CiA Draft Standard Proposal

301 Version 4.2, 7. Dec 2007
2 [CiADS203-1] CAN Application Layer for Industrial Application, CiA/DS203-1, Feb 1996
3 [CiADS306] Electronic data sheet specification for CANopen, CiA Draft Standard 306 Version 1.3,

01 Jan 2005

- 8 -

Advantech CANopen Protocol Library

2. Advantech CANopen Protocol Library

2.1. Overview

Advantech CANopen Protocol Library (acoapi) provides a C application programming interface (API)
for accessing the CANopen network protocol stack of nodes. It is easy to use, configure, start and
monitor the CANopen devices careless CAN bus, developer just focused on CANopen application
functionality. The acoapi library architecture is shown in Figure 3, at present, the library practices
the specification DSP 301 v4.2 [1] defined by CiA, communication profile.

Advantech or vendors CANopen Tool, Utility, Manager

Advantech CANopen C-API DLL

Advantech CAN Bus Driver

CAN Bus

Figure 3: Advantech CANopen Protocol Architecture

Base on the acoapi library to develop a CANopen node as master or slaves, the functionality of
slaves and of a master specified by CANopen can configure and manage remote nodes is covered
by the library:

 Read and write object dictionary (local or by SDO)
 Control or monitor the node NMT state (NMT master)
 PDO transmission mode: on request, by SYNC, time driven, event driven
 Support 512 TPDOs and 512 RPDOs
 SYNC producer and consumer
 Heartbeat producer and consumer

- 9 -

 Emergency objects
The acoapi library uses event-driven to notify the a pplication to complete the tasks, indicate that

an event has occurred. For example: Notify the application when the NMT state of a master/slave
node has changed that can decide to do something in state changing, notify SYNC message
received or transmitted, or PDO frame transmitted, the C ANopen node object dictionary of object
index and sub-index data has changed, etc.

2.2. Object Diagram

The acoapi library references CiA DS203-1 NMT Service Specifica tion [2] to deal with the CANopen
network aspect. Figure 4: The NMT model illustrates the NMT model of a CANopen network the
acoapi library implemented.

Figure 4: The NMT model

There are three objects to model a CANopen network:
 The network object

The network object represents the set of all modules in a CANopen network that must include
one node, called master node, and at most 126 node objects specified by CiA DS301 [1]
(totally 127 nodes in CANopen network). It administers whole the life cycle of a CANopen
network through the master. In other word, the network object exists in master side.

- 10 -

 The remote node object

Each slave node is managed by the NMT master is represented by a remote nod e object on
the network object.

 The node object

A CANopen device in the network is considered as a node. The role of node can be master or
slave depended on its capability. Each node has uniquely node identifier in the network
defined in CiA DS301 [1].

For each slave there must exist one remote node object with the same node identifier on the
network object that master node in. A slav e node object and the remote node object that has the
same node identifier are called peers. A unique node identifier is assigned to a slave node object
and its peer by the master (network object). Master in the network object commu nicates w ith each
remote node object via CANopen protocol to its peer slave node.

2.3. Runtime Environment

Windows 2000
Windows xp (32 bit and 64 bit)
Windows 2003 (32 bit and 64 bit)
Windows vista (32 bit and 64 bit)
Window 7 (32 bit and 64 bit)

- 11 -

2.4. API Functions

2.4.1. Overview

The acoapi DLL implements a set of functions which together provide CANopen functionality. Each
function of first parameter is an object handles that pointer to master/slave node, remote node or
network object. Network ob ject is in master side for management the CANopen network; it must
need a master node for creating a CANopen network and at most 126 remote slave nodes includ ed,
totally nodes is 127 in CANopen network. Remote slave node can be inserted to network object
first before starting network, or inserted later if receiving the slave node boot-up message.

Table 8: acoapi function list

Function Description

Network object (Master side)

acoCreateNetwork Create a CANopen network topology, must input a Master Node
acoFreeNetwork Free network object instance and remote n od es
acoStartNetwork Start network, all nodes will be into Operational state
acoStopNetwork Stop network, all nodes will be into Stop state
acoStartRemoteNode Start a remote node by NodeId
acoStopRemoteNode Stop a remote node by NodeId
acoGetRemoteNodeId Get node id of remote object
acoGetRemoteNodeState Get the node state of remote object
acoGetRemoteNodeCount Get remote nodes count
acoGetRemoteNode Get remote node handle by NodeId
acoGetRemoteNodebyPos Get Remote node handle by position
acoRemoteNodeExist Check the Remote node is already exist in network object
acoNetworkAddSlave Add a Remote node into network object
acoNetworkRemoveSlave Remove a Remote node from network object
acoNetworkSetState Send a NMT message to a Slave to change its state
acoReqNodeGuard Request a Slave node the Node Guard message
acoRegBootupEvent Register an event while receiving slave boot-up frame
acoNetworkReadSDO Send SDO frame in async mode to read the object dictionary of remote

slave node, it will call specified callback function after receiving the
remote slave’s response

acoNetworkWriteSDO Send SDO frame in async mode to write the data to the object dictionary

of remote slave node, it will call specified callback function after

- 12 -

completing the process

Node

acoCreateNode Create a node (Master/Slave) according
acoFreeNode Free a node and close the CAN port
acoOpenCANPort open the CAN port
acoCloseCANPort Close the CAN port
acoSetBaudrate Change the CAN port by specified baud rate.
acoNodeImportEDS Import the device profile and assign the node id
acoGetNodeId Get the node Id of the node object
acoSetNodeId Set the node id of the node object
acoGetNodeState Get the state of the node
acoStartNode Start a slave node into Pre-Operational state that waiting NMT message
acoStopNode Stop a slave node into Stop state
acoGetNodeRole Get node role (Master or Slave) by node handle
acoGetODentry Read local object dictionary info (SDO upload) or read remote slave node

of OD by SDO in sync method

acoSetODentry

acoReadSDO A slave node reads other slave node of OD by sending SDO frame in

acoWriteSDO A slave node writes the data to other slave node of OD by sending SDO

acoRegODDataChangedEvent Register an event for the entry [index, subindex] of Object Dictionary

acoUnRegODDataChangedEvent Un-register an event for the entry changed
acoRegGeneralEvent Register a call back function that for a general event
acoRegEmcyEvent Register an event for slave received EMCY message
acoSendEmcy Slave sends emergency message actively

Write data to local object dictionary (SDO download) or write remote
slave node of OD by SDO in sync method

async mode

frame in async mode

changed

acoSendData Transmit a specified data to other nodes
acoRegHeartbeatEvent Registers a callback function that will be called while receiving a

heartbeat message

acoRegHeartbeatErrorEvent Registers a callback function that will be called while detecting a

heartbeat error or node guard error occurs
acoRegRecvPDOEvent Registers an event is for receiving a PDO message.
acoSendPDOwithCOS Send TPDOs if any data has changed (Change-Of-State), only

transmission type 255 (0xFF) is supported yet.

- 13 -

acoCreateNode

acoNodeImportEDS

acoCreateNetwork

acoNetworkAddSlave

Regist Event

acoRegHeartbeatErrorEvent

acoRegBootupEvent

acoRegODDataChangedEvent

acoRegGeneralEvent

acoOpenCANPort

acoStartNetwork

Run state

acoStopNetwork

acoNetworkRemoveSl

ave

acoFreeNetwork

acoCloseCANPort

acoFreeNode

acoGetNodeId

acoGetNodeState

acoGetNodeRole

acoReadSDO

acoWriteSDO
acoGetODentry
acoSetODentry

acoSendData

acoReqNodeGuard

acoStartRemoteNode

acoStopRemoteNode

acoRemoteNodeExist

acoGetRemoteNodebyPos

acoGetRemoteNode

acoGetRemoteNodeCount

acoSetNodeId

2.4.2. Flow chart

 Master side

- 14 -

acoCreateNode

acoNodeImportEDS

Regist Event

acoRegHeartbeatErrorEvent

acoRegODDataChangedEvent

acoRegGeneralEvent

acoOpenCANPort

acoStartNode

Run state

acoStopNode

acoCloseCANPort

acoFreeNode

acoGetNodeId
acoSetNodeId

acoGetNodeState

acoGetNodeRole

acoGetODentry
acoSetODentry

acoSendData

acoSetNodeId

 Slave side

- 15 -

2.4.3. Definition and Structures

Definition Description
UNS8 A 8-bit unsigned char
UNS16 A 16-bit unsigned short integer
UNS32 A 32-bit unsigned long integer
NODEID_t Type definition of node identifier
HACONODE Pointer to slave node object
HACOMASTER Pointer to master node object
HACOREMOTE Pointer to remote node object
HACONODEOBJ Pointer to a node object, may be slave node object, master node object or remote

node object
HACONETWORK Pointer to network object
CBROADCAST_NODEID Node identifier is 0 for broadcast CANopen message
CINVALID_NODEID -1 indicates invalid node identifier
MAX_PORTNAME Maximum length of CAN port name

Object Dictionary Data Types
ACODT_BOOLEAN 0x01, Boolean
ACODT_INT8 0x02, a 8-bit integer
ACODT_INT16 0x03, a 16-bit integer
ACODT_INT32 0x04, a 32-bit integer
ACODT_UINT8 0x05, a 8-bit unsigned integer
ACODT_UINT16 0x06, a 16-bit unsigned integer
ACODT_UINT32 0x07, a 32-bit unsigned integer
ACODT_REAL32 0x08, a 32-bit real
ACODT_VISIBLE_STRING 0x09, visible string
ACODT_OCTET_STRING 0x0A, octet string
ACODT_UNICODE_STRING 0x0B, Unicode string
ACODT_TIME_OF_DAY 0x0C, TIME_OF_DAY structure
ACODT_TIME_DIFFERENCE 0x0D, TIM E_DIFFERENCE structure
ACODT_DOMAIN 0x0F, domain, an arbitrary large block of data
ACODT_INT24 0x10, a 24-bit integer
ACODT_REAL64 0x11, a 64-bit real
ACODT_INT40 0x12, a 40-bit integer
ACODT_INT48 0x13, a 48-bit integer

- 16 -

ACODT_INT56 0x14, a 56-bit integer
ACODT_INT64 0x15, a 64-bit integer
ACODT_UINT24 0x16, a 24-bit unsigned integer
ACODT_UINT40 0x18, a 40-bit unsigned integer
ACODT_UINT48 0x19, a 48-bit unsigned integer
ACODT_UINT56 0x1A, a 56-bit unsigned integer
ACODT_UINT64 0x1B, a 64-bit unsigned integer

Enumerate and structures
enum enum_nodeRole {
Slave = 0x00,
Master = 0x01,
RemoteNode = 0x02,
UnknownRole = 0x0F,
};
typedef enum enum_node R o le e_ no d e Ro le;
enum enum_acoNodeState {
ns_Initialisation = 0x00,
ns_Stopped = 0x04,
ns_Operational = 0x05,
ns_Pre_operational = 0x7F,
ns_Unknown_state = 0x0F
};
typedef enum enum_acoNodeState e_acoNodeState;
enum enum_GeneralEventType {

The role of a node object:
Slave node object
Master node object
Remote node object
Unknown node object

The NMT state of a node:
NMT state Initialisation,
NMT state Stoppped,
NMT state Operational,
NMT state Pre-operational,
Unknown state

Identity a general event that with the same

function definition:
et_STATE_INITIALIZE = 0x00,
et_STATE_PREOPERATIONAL = 0x01,
et_STATE_OPERATIONAL = 0X02,
et_STATE_STOPPED = 0x03,
et_POST_SYNC = 0x04,
et_POST_PDO = 0x05,
};
typedef enum enum_GeneralEventType
e_GeneralEventType;

Application-defined callback function
Notify application-defined when a special event has occurs

- 17 -

the node enter NMT state Initialisation,

the node enter NMT state Pre-operational,

the node enter NMT state Operational,

the node enter NMT state Stopped,

the node transmitted or received a sync frame,

the node transmitted a PDO frame

typedef void (*TCOnGeneralEvent)( HACONODE hNode , LPVOID pvArg );
Notify if the value with specified object index and sub-index of object dictionary has changed
typedef UNS32 (*TCOnODDataChangedEvent)

(HACONODE hNode, UNS16 wIndex, UNS8 SubIndex, UNS8 DataType, UNS32 DataLen, void * pData ,

LPVOID pvArg);
Notify if SDO READ request is responded or timeout o ccurs.
Typedef void (*TCOnReadSDOResult)

( HACONODEOBJ hNode, NODEID_t NodeId, UNS16 wIndex, UNS8 SubIndex,

UNS8 dataType, UNS32 dataLen, void* pData, UNS32 abortCode , LPVOID pvArg);
Notify if SDO WRITE request is responded or timeout occurs.
Typedef void (*TCOnWriteSDOResult)

( HACONODEOBJ hNode, NODEID_t NodeId, UNS16 wIndex, UNS8 SubIndex, UNS32 abortCode ,

LPVOID pvArg);
Notify if the slave node receives the emergency message from other nodes
typedef void (*TCOnPostEmcyEvent)

(HACONODE hNode, NODEID_t NodeID, UNS16 errCode, UNS8 errReg, UNS8 errManufacField[5],

LPVOID pvArg);
Notify while not receive heartbeat message wit hin the consumer heartbeat time.
Typedef void (*TCOnHeartbeatErrorEvent)(HACONODE hNode, NODEID_t NodeId , LPVOID pvArg);

Notify while receiving a heartbeat message from heartbeat producer (remote slave nodes.)

typedef void (*TCOnHeartbeatEvent)

(HACONODE hNode, NODEID_t NodeId, e_acoNodeState currState , LPVOID pvArg);

Notify while master receiving a slave boot up m essage.

Typedef void (*TCOnBootupEvent)(HACONODE hNode, NODEID_t NodeId , LPV OID pv A rg );

Notify while receiving a PDO message from another node.

typedef void (*TCOnRecvPDOEvent)

(HACONODE hNode, int rpdoIndex, UNS32 cobId, UNS8 bRTR, UNS8 size, void *pData, LPVOID
pvArg);

2.4.4. Error codes

acoapi error codes

Table 9: acoapi error codes
Definition Value Description
ACOERR_SUCCESS 0 Success

- 18 -

ERROR_INVALID_DATA 13 The data or input parameter is invalid or NULL
ERROR_OUTOFMEMORY 14 Not enough memory to allocate
ACOERR_INVALID_EDS_CONTENT 0x25100001 Wrong EDS file content
ACOERR_SDO_READ_FAILED 0x25100002 SDO read operation failed. Ex: no SDO entry in EDS
ACOERR_SDO_WRITE_FAILED 0x25100003 SDO write operation failed
ACOERR_STATE_CHANGED_FAILED 0x25100004 Fail to change node state
ACOERR_INVALID_MASTER 0x25100005 Master node is not exist
ACOERR_INVALID_NODEID 0x25100006 Invalid node id, for example: node id is over

NMT_MAX_NODE_ID
ACOERR_INVALID_NODE 0x25100007 Invalid node object handle
ACOERR_REMOTE_NODEID_EXIST 0x25100008 The ID of remote node is exist
ACOERR_REMOTE_STATE_OPER 0x25100009 Remote node is in operational state that can not do this

operation
ACOERR_CANPORT_NOT_OPEN 0x2510000A CAN port can not open
ACOERR_NOT_SUPPORT 0x2510000B Do not support the function
ACOERR_REMOTE_NODES_OVER 0x2510000C Remote nodes count is over the limit in list, maximum

nodes are 127
ACOERR_NODEID_EXIST 0x2510000D The node id is exist in list
ACOERR_EMCY_FAILED 0x2510000E Generate a emergency code failed
ACOERR_LICENSE_INVALID 0x2510000F License failed. The acoapi library only supports

Advantech allowed products
ACOERR_TIMER_FULL 0x25100010 The timer is full that can not set alarm.
ACOERR_PDO_IN_INHIBIT_TIME 0x25100011 The TPDO exist inhibit time that can not transmit PDO

immediately.
ACOERR_PDO_COBID_29BIT 0x25100012 The 29-bit COB-ID should be 1.
ACOERR_PDO_TRANS_EVENT_INVALID 0x25100013 The transmission type of PDO is invalid to send. It

should be 255 for COS.
ACCERR_EXCEPTION 0x25100014 Exception occurs.
ACCERR_PDO_TRANS_FAILED 0x25100015 Can not transmit PDO, the node could be not in

Operational state, PDO offset invalid, or the object

SDO abort codes

SDO abort codes please see DS 301 v4.02 p.48.

- 19 -

dictionary of PDO data invalid.

Table 10: SDO abort codes

Definition Value Description
ACOOD_SUCCESSFUL 0x00000000 Success
ACOOD_UNSUPPORT_OBJECT 0x06010000 Unsupported access to an object
ACOOD_READ_NOT_ALLOWED 0x06010001 Attempt to read a write-only object
ACOOD_WRITE_NOT_ALLOWED 0x06010002 Attempt to write a read-only object
ACOOD_NO_SUCH_OBJECT 0x06020000 Object does not exist in the Object Dictionary
ACOOD_NOT_MAPPABLE 0x06040041 Object cannot be mapped to the PDO
ACOOD_LENGTH_EXCEED 0x06040042 The number and length of the objects to be mapped

would exceed PDO length
ACOOD_PARAM_INCOMPATIBILITY 0x06040043 General parameter incompatibility
ACOOD_INTERNAL_INCOMPATIBILITY 0x06040047 General internal incompatibility in the device
ACOOD_HW_ERROR 0x06060000 Access failed d ue to h ar d w a re er ror
ACOOD_LENGTH_DATA_INVALID 0x06070010 Data type does not match. Length of service

parameter does not match
ACOOD_LENGTH_DATA_TOO_HIGH 0x06070012 Data type does not match. Length of service

parameter is too high
ACOOD_LENGTH_DATA_TOO_LOW 0x06070013 Data type does not match. Length of service

parameter is too low.
ACOOD_NO_SUCH_SUBINDEX 0x06090011 Subindex does not exist
ACOOD_VALUE_RANGE_EXCEED 0x06090030 Value range of parameter exceeded (write access

only)
ACOOD_VALUE_TOO_HIGH 0x06090031 Value of parameter written is too high
ACOOD_VALUE_TOO_LOW 0x06090032 Value of parameter written is too low
ACOOD_INVALID_MAX_VALUE 0x06090036 Maximum value is less than the minimum value.
ACOSDOABT_TOGGLE_NOT_ALTERNED 0x05030000
ACOSDOABT_TIMED_OUT 0x05040000
ACOSDOABT_UNKNOW_COMMAND 0x05040001 Client/Server command specifier not valid or unknown
ACOSDOABT_INVALID_BLOCK_SIZE 0x05040002 Invalid block size (block mode)
ACOSDOABT_INVALIC_SEQ_NUM 0x05040003 Invalid sequence number (block mode)
ACOSDOABT_CRC_ERROR 0x05040004 CRC error (block mode)
ACOSDOABT_OUT_OF_MEMORY 0x05040005 Size data exceed SDO_MAX_LENGTH_TRANSFERT
ACOSDOABT_GENERAL_ERROR 0x08000000 Error size of SDO message
ACOSDOABT_DATA_TRANS_STORE_ERROR 0x08000020 Data cannot be transferred or stored to the

application.
ACOSDOABT_LOCAL_CTRL_ERROR 0x08000021 Data cannot be transferred or stored to the

application because of local control

- 20 -

Emergency error codes

Emergency error codes please see DS 301 v4.02 p.60.

Table 11: Emergency error codes
Definition Value Description
ACOEMCYERR_RESEST 0x0000 Error reset or No error
ACOEMCYERR_GENERIC 0x1000 Start code of Generic error
ACOEMCYERR_CURRENT 0x2000 Start code of Current
ACOEMCYERR_CURRENT_DEVICE_INPUT 0x2100 Current, device input side
ACOEMCYERR_CURRENT_DEVICE_INSIDE 0x2200 Current inside the device
ACOEMCYERR_CURRENT_DEVICE_OUTPUT 0x2300 Current, device output side
ACOEMCYERR_VOLTAGE 0x3000 Start code of Voltage
ACOEMCYERR_VOLTAGE_MAINS 0x3100 Main Voltage
ACOEMCYERR_VOLTAGE_INSIDE_DEVICE 0x3200 Voltage inside the device
ACOEMCYERR_VOLTAGE_OUTPUT 0x3300 Output voltage
ACOEMCYERR_TEMPERATURE 0x4000 Temperature
ACOEMCYERR_TEMPERATURE_AMBIENT 0x4100 Ambient temperature
ACOEMCYERR_TEMPERATURE_DEVICE 0x4200 Device temperature
ACOEMCYERR_DEVICE_HW 0x5000 Device hardware
ACOEMCYERR_DEVICE_SW 0x6000 Device software
ACOEMCYERR_DEVICE_SW_INTERNAL 0x6100 Internal software
ACOEMCYERR_DEVICE_SW_USER 0x6200 User software
ACOEMCYERR_DEVICE_SW_DATA 0x6300 Data set
ACOEMCYERR_ADDITIONAL_MODULES 0x7000 Additional modules
ACOEMCYERR_MONITOR 0x8000 Monitoring
ACOEMCYERR_MONITOR_COMMUN 0x8100 Start code of Monitoring Communication
ACOEMCYERR_MONITOR_CAN_OVERRUN 0x8110 CAN Overrun (Objects lost)
ACOEMCYERR_MONITOR_PASSIVE_MODE 0x8120 CAN in Error Passive Mode
ACOEMCYERR_MONITOR_GUARD 0x8130 Life guard error or heartbeat error
ACOEMCYERR_MONITOR_RECOVER_BUSOFF 0x8140 Recovered from bus off
ACOEMCYERR_MONITOR_COBID_COLLISION 0x8150 Transmit COB-ID collision
ACOEMCYERR_PROTOCOL 0x8200 Start code of Protocol error
ACOEMCYERR_PDO_LENGTH_INVALID 0x8210 PDO not processed due to length error
ACOEMCYERR_PDO_LENGTH_EXCEEDED 0x8220 PDO length exceeded
ACOEMCYERR_EXTERNAL 0x9000 External error

- 21 -

ACOEMCYERR_ADDITIONAL_FUNC 0xF000 Additional functions
ACOEMCYERR_DEVICE_SPECIFIC 0xFF00 Device specific

- 22 -

2.4.5. acoapi Functions

acoCreateNode

Create Master or Slave CANopen node.

HACONODE acoCreateNode(

char *pCANDriverName

);

Parameters

pCANDriverName

[in] Input the CAN driver dll path and name. (Ignore)

Return Values

If the function succeeds, the return value is the master or slave node object handle. If the function fails, the
return value is NULL. The generality of failed reason could be allocating memory failed. Could call GetLastError()
to get the error code.

Remarks

Use the acoFreeNode() function to close an node object handle.

Example

HACONODE hSlaveNode = NULL;
hSlaveNode = acoCreateNode(NULL);
if (hSlaveNode)
printf(“Create Node SUCCESS.”);
else
printf(“Create Node failed: %x”, GetLastError());

acoFreeNode

Free the handle of a node that created by acoCreateNode(), the function will close the CAN port first if it is
opening .

void acoFreeNode(

- 23 -

HACONODE hNode

);

Parameters

hNode

[in] Pointer to the Master or Slave node object handle that returned by acoCreateNode()

Return Values

None

Example

extern HACONODE hSlaveNode;
acoFreeNode(hSlaveNode);
hSlaveNode = NULL;

acoOpenCANPort

Open the CAN port by specified port name and then set the baud rate. Should be open the CAN port first before
start the CANopen network.

UNS32 acoOpenCANPort(

HACONODE hNode,
char *pPortName,
int kbits

);

Parameters

hNode

[in] Pointer to the Master or Slave node object handle that is the returned by acoCreateNode()

pPortName

[in] Specifies the CAN port name that is null-terminated string to open. For example, specify CAN1 , CAN2
as the CAN port.

kbits

[in] The baud rate (Kbits) of the CAN port. According to CiA Draft Standard 301 [1] recommend bit rates are
listed below:

Target value Setting value
10 Kbit/s 10

- 24 -

20 Kbit/s 20
50 Kbit/s 50
125 Kbit/s 125
250 Kbit/s 250
500 Kbit/s 500
800 Kbit/s 800

1000 Kbit/s 1000

Return Values

If the function succeeds, the return value is ACOERR_SUCCESS. If the funct io n fails, please reference acoapi
error codes.

Remarks

Use the acoCloseCANPort() function to close the CAN port.

Example

UNS32 ret;
HACONODE hSlaveNode;
//Use acoOpenCANPort() to set CAN port name and baud rate.
hSlaveNode = acoCreateNode(NULL);
if (hSlaveNode)
{

printf("Create Node SUCCESS.");
if (acoNodeImportEDS(hSlaveNode, “\\slavedict-ok.eds”, 0x02) == ACOERR_SUCCESS)
{

printf("Import EDS file ok.");
// should be ImportEDS first than OpenCANPort
if ((ret = acoOpenCANPort(hSlaveNode, "CAN1:", 1000)) == ACOERR_SUCCESS)

printf("Open CAN1 ok.");

else

printf("Open CAN1 failed. %x", ret);

}else
printf("Import EDS file failed.");
}

- 25 -

acoCloseCANPort

Close the CAN port.

UNS32 acoCloseCANPort(

HACONODE hNode

);

Parameters

hNode

[in] Pointer to the Master or Slave node object handle that is the returned by acoCreateNode()

Return Values

If the function succeeds, the return value is ACOERR_SUCCESS. If the function fails, please reference acoapi
error codes.

Example

extern HACONODE hSlaveNode;
if(hSlaveNode)
{
acoStopNode(hSlaveNode);
acoCloseCANPort(hSlaveNode);
acoFreeNode(hSlaveNode);
hSlaveNode = NULL;
}

acoSetBaudrate

Set the CAN port baud rate.

UNS32 acoSetBaudrate(

HACONODE hNode,
int kbits

);

Parameters

hNode

[in] Pointer to the Master or Slave node object handle that is the returned by acoCreateNode()

- 26 -

kbits

[in] The baud rate (Kbits) of the CAN port. According to CiA Draft Standard 301 [1] recommend bit rates are
listed below:

Target value Setting value
10 Kbit/s 10
20 Kbit/s 20
50 Kbit/s 50
125 Kbit/s 125
250 Kbit/s 250
500 Kbit/s 500
800 Kbit/s 800

1000 Kbit/s 1000

Return Values

If the function succeeds, the return value is ACOERR_SUCCESS. If the function fails, please reference acoapi
error codes.

acoNodeImportEDS

Import the device profile for this node object handle and assig n the node id.

UNS32 acoNodeImportEDS(

HACONODE hNode,
char * pProfile,
NODEID_t * pNodeId

);

Parameters

hNode

[in] Pointer to the Master or Slave node object handle that is the returned by acoCreateNode().

pProfile

[in] Device profile path and file name.

pNodeId

[in, out] Specified the node id, or return the Id if included in Profile. Also can be changed by acoSetNodeId().
Maximum the number of node id is 127.

- 27 -

Return Values

If the function succeeds, the return value is ACOERR_SUCCESS. If the function fails, the returns value is acoapi
error codes.

Remarks

EDS describes the behavior of CANopen device with respect to the contents of object dictionary. Its content
should be conforming to CANopen standard, necessary to avoid incomplete or erroneous data sheets. Else the
working model of the device in CANopen network may not running well as you expected. Use external test tool
called CANchkEDS.exe to check the valid content of EDS first before importing EDS, or use a configuration
utility to modify the content.

Example

Reference acoOpenCANPort() example.

acoGetNodeId

Get node identifier of the Master or Slave node object handle.

NODEID_t acoGetNodeId(

HACONODE hNode

);

Parameters

hNode

[in] Pointer to the Master or Slave node object handle that is the returned by acoCreateNode()

Return Values

Return the node identifier of the node object handle that be set by acoNodeImportEDS() or acoSetNodeId().
Return CINVALID_NODEID if node identifier does not set yet.

Remarks

Use acoGetRemoteNodeId() to get remote slave node identifier.

The node identifier is unique identifier for each CANopen device in the network, a value in the range of [1..127]
specified by CiA DS-301.

Example

extern HACONODE hSlaveNode;

- 28 -