Protocol API CANopen Slave V3.6.x.x Hilscher Gesellschaft für Systemautomation mbH www.hilscher.com DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public Table of Contents 2/191 Table of Contents 1 Introduction.............................................................................................................................................4 1.1 Abstract..........................................................................................................................................4 1.2 List of Revisions.............................................................................................................................4 1.3 System Requirements....................................................................................................................5 1.4 Intended Audience.........................................................................................................................5 1.5 Specifications.................................................................................................................................6 1.5.1 Technical Data..................................................................................................................................6 1.6 Terms, Abbreviations and Definitions..........................................................................................10 1.7 References to Documents............................................................................................................10 1.8 Legal Notes..................................................................................................................................11 1.8.1 Copyright.........................................................................................................................................11 1.8.2 Important Notes...............................................................................................................................11 1.8.3 Exclusion of Liability........................................................................................................................12 1.8.4 Export..............................................................................................................................................12 1.8.5 Registered Trademarks...................................................................................................................12 2 Fundamentals.......................................................................................................................................13 2.1 General Access Mechanisms on netX Systems..........................................................................13 2.2 Accessing the Protocol Stack by Programming the AP Task’s Queue........................................13 2.2.1 Getting the Receiver Task Handle of the Process Queue...............................................................14 2.2.2 Meaning of Source- and Destination-related Parameters................................................................14 2.3 Accessing the Protocol Stack via the Dual Port Memory Interface..............................................15 2.3.1 Communication via Mailboxes.........................................................................................................15 2.3.2 Using Source and Destination Variables correctly...........................................................................16 2.3.3 Obtaining useful Information about the Communication Channel....................................................20 2.4 Client/Server Mechanism.............................................................................................................22 2.4.1 Application as Client........................................................................................................................22 2.4.2 Application as Server......................................................................................................................23 3 Dual-Port-Memory................................................................................................................................24 3.1 Cyclic Data (Input/Output Data)...................................................................................................24 3.1.1 Input Data Image.............................................................................................................................24 3.1.2 Process Data Output.......................................................................................................................26 3.2 Acyclic Data (Mailboxes)..............................................................................................................27 3.2.1 General Structure of Messages or Packets for Non-Cyclic Data Exchange....................................28 3.2.2 Status & Error Codes......................................................................................................................30 3.2.3 Differences between System and Channel Mailboxes....................................................................30 3.2.4 Send Mailbox...................................................................................................................................30 3.2.5 Receive Mailbox..............................................................................................................................30 3.2.6 Channel Mailboxes (Details of Send and Receive Mailboxes)........................................................31 3.3 Status...........................................................................................................................................32 3.3.1 Common Status...............................................................................................................................32 3.3.2 Extended Status..............................................................................................................................37 3.4 Control Block................................................................................................................................41 4 Getting Started......................................................................................................................................42 4.1 Overview about Essential Functionality.......................................................................................42 4.2 Configuration Parameters and Procedures..................................................................................42 4.2.1 Using a Packet (CANOPEN_APS_SET_CONFIGURATION_REQ/CNF)............................................43 4.2.2 Behavior when receiving a Set Configuration Command................................................................45 4.3 Task Structure of the CANopen Slave V3 Stack..........................................................................45 4.4 CANopen – Basic Topics.............................................................................................................47 4.4.1 NMT Slave State Machine...............................................................................................................47 4.4.2 Communication Objects, COB-IDs and Priority of Processing........................................................50 4.4.3 Relation between Communication Objects and NMT States...........................................................52 4.4.4 Events.............................................................................................................................................52 4.4.5 Process Data Objects (PDO)...........................................................................................................61 4.5 Standard Mode vs. Extended Mode.............................................................................................68 4.5.1 How to decide between Operation in Standard Mode and Extended Mode....................................68 4.5.2 Where can I switch between Standard Mode and Extended Mode?...............................................68 4.5.3 Standard Mode................................................................................................................................69 4.5.4 Extended Mode...............................................................................................................................71 4.5.5 Object Dictionary with Firmware Functionality.................................................................................72 CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013 Table of Contents 3/191 5 The Application Interface....................................................................................................................74 5.1 The CANopen-APS-Task.............................................................................................................74 5.1.1 CANOPEN_APS_GET_STATE_REQ/CNF – Get State of AP-Task....................................................75 5.1.2 CANOPEN_APS_SET_CONFIGURATION_REQ/CNF – Set Configuration.........................................77 5.2 The CANopen Slave-Task...........................................................................................................85 5.2.1 CANOPEN_SLAVE_REGISTER_REQ/CNF – Register Application....................................................87 5.2.2 CANOPEN_SLAVE_STARTSTOP_REQ/CNF – Start/Stop CANopen Network...................................90 5.2.3 CANOPEN_SLAVE_INITIALIZE_REQ/CNF – Initialization of CANopen Slave...............................93 5.2.4 CANOPEN_SLAVE_EXCHANGE_DATA_REQ/CNF – Exchange Data.................................................96 5.2.5 CANOPEN_SLAVE_STATE_CHANGE_IND/RES – Change of Task State Indication.......................100 5.2.6 CANOPEN_SLAVE_SEND_EMCY_REQ/CNF – Send Emergency Message.....................................106 5.2.7 CANOPEN_SLAVE_SEND_EMCY_IND/RES – Emergency Message Indication..............................110 5.2.8 CANOPEN_SLAVE_SET_NMT_STATE_REQ/CNF – Set NMT State................................................114 5.2.9 CANOPEN_SLAVE_SET_BUSPARAM_REQ/CNF – Set Bus Parameters.........................................117 5.2.10 CANOPEN_SLAVE_SEND_TIME_STAMP_REQ/CNF – Send Time Stamp......................................122 5.2.11 CANOPEN_SLAVE_RECV_TIME_STAMP_IND/RES – Receive Time Stamp Indication.................125 5.2.12 CANOPEN_SLAVE_SEND_TXPDO_REQ – Send TxPDO Request...................................................128 5.2.13 CANOPEN_SLAVE_RECV_RXPDO_REQ/CNF – Receive RxPDO Request.....................................131 5.2.14 CANOPEN_SLAVE_RECV_RXPDO_IND/RES – Receive RxPDO Indication...................................135 5.2.15 CANOPEN_SLAVE_SET_EVENTS_INDICATED_REQ/CNF – Set Events Indicated Request.........138 5.2.16 CANOPEN_SLAVE_GET_IO_INFO_REQ/CNF – Get I/O Info.........................................................142 5.2.17 CANOPEN_SLAVE_SET_API_PARAM_REQ/CNF – Set API Parameter..........................................144 5.2.18 CANOPEN_SLAVE_NMT_STATE_CHANGE_IND/RES – NMT State Change Indication..................147 5.2.19 CANOPEN_SLAVE_ERR_CTRL_EVENT_IND/RES – Error Control Event Indication......................150 5.2.20 CANOPEN_SLAVE_NMT_COMMAND_IND/RES – NMT Command Indication..................................154 5.2.21 CANOPEN_SLAVE_GET_BUSPARAM_REQ/CNF – Get Bus Parameters.........................................158 5.2.22 CANOPEN_SLAVE_SET_WATCHDOG_FAIL_REQ/CNF – Set Watchdog Fail..................................162 5.2.23 CANOPEN_SLAVE_SETUP_PDO_INDICATION_REQ/CNF – Setup PDO Indication......................164 5.2.24 CANOPEN_SLAVE_RECEIVE_PDO_IND/RES – Receive PDO Indication......................................167 5.3 Hardware Switches for the Adjustment of Slave Address and Baudrate...................................170 5.3.1 RCX_SET_HW_SWITCH_VALUES_REQ/CNF – Set the Values of the Hardware Switch.................172 5.3.2 RCX_SET_FW_PARAMETER_REQ/CNF – Set the Value of the Firmware Parameter.....................175 5.3.3 RCX_GET_FW_PARAMETER_REQ/CNF – Get the Value of the Firmware Parameter.....................179 5.4 CAN-DL Task.............................................................................................................................181 5.5 ODV3 Task.................................................................................................................................181 6 Status/Error Codes Overview............................................................................................................183 6.1.1 Codes of the CANopen-APS-Task................................................................................................183 6.1.2 Error Messages.............................................................................................................................183 6.2 Codes of the CANopen Slave-Task...........................................................................................185 6.2.1 Error Messages.............................................................................................................................185 6.3 Codes of CAN-DL Task..............................................................................................................187 6.4 Codes of ODV3..........................................................................................................................187 7 Appendix.............................................................................................................................................188 7.1 List of Tables..............................................................................................................................188 7.2 List of Figures.............................................................................................................................190 7.3 Contacts.....................................................................................................................................191 CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013 Introduction 4/191 1 Introduction 1.1 Abstract This manual describes the application interface of the CANopen Slave stack, with the aim to support and lead you during the integration process of the given stack into your own application. Base of the development of the stack itself is the Hilscher’s Task Layer Reference Programming Model. It is a description of how to program a Task in general, which is defined as a combination of appropriate functions belonging to the same type of protocol layer. It furthermore defines of how different Tasks have to communicate with each other in order to exchange their layer information in between. The reference model is commonly used by all programmers at Hilscher and shall be used by you as well when writing your Application Task on top of the stack. 1.2 List of Revisions Rev Date Name Revisions 1 2012-03-09 RG/ES Firmware/stack version V3.1.2.x Reference to netX Dual-Port Memory Interface Manual Revision 12. Reference to Object Dictionary V3.2.8.0 First final version 2 2012-07-04 RG/ES Firmware/stack version V3.2.x.x Added description of packet RCX_SET_FW_PARAMETER_REQ/CNF – Set the Value of the Firmware Parameter 3 2013-04-11 RG/ES Firmware/stack version V3.4.3.x Reference to Object Dictionary V3.3.1.x Reference to CAN_DL V2.0.22.0 Added description of packet RCX_GET_FW_PARAMETER_REQ/CNF – Get the Value of the Firmware Parameter Added description of packet CANOPEN_SLAVE_SEND_EMCY_IND/RES – Emergency Message Indication Adapted description of packet CANOPEN_SLAVE_SET_EVENTS_INDICATED_REQ/CNF – Set Events Indicated Request to new Send EMCY Event Adapted Table 51: Packets of CANopen Slave Protocol Stack V3 and Restrictions of Usage for new Send EMCY Event 4 2013-05-22 RG/ES Firmware/stack version V3.5.1.x Reference to Object Dictionary V3.3.1.x Reference to CAN_DL V2.0.23.0 netX52 now supported 5 2013-10-29 RG/ES Firmware/stack version V3.6.2.x Reference to Object Dictionary V3.3.2.x Reference to CAN_DL V2.0.27.0 Technical data updated (number of consumers for netX51/52) Small corrections Table 1: List of Revisions CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013 Introduction 5/191 1.3 System Requirements The software package has the following system requirements to its environment:  netX-Chip as CPU hardware platform  Operating system for task scheduling required 1.4 Intended Audience This manual is suitable for software developers with the following background:  Knowledge of the programming language C  Knowledge of the use of the real-time operating system rcX  Knowledge of the Hilscher Task Layer Reference Model  Knowledge of the CiA Work Draft 301 specification CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013 Introduction 6/191 1.5 Specifications The data below applies to CANopen Slave firmware and stack version 3.6.x. The firmware/stack has been designed in order to meet the CiA Work Draft 301 V4.02 specification (see reference [2]). 1.5.1 Technical Data Technical Data Features Parameter Maximum number of input data Depends on the used mode and settings. See below. Maximum number of output data Depends on the used mode and settings. See below. Maximum number of receive PDOs Depends on the used mode and settings. See below. Maximum number of transmit PDOs Depends on the used mode and settings. See below. Exchange of process data via PDO transfer (synchronized, remotely requested, event driven (change of date)), requested by application (via packet)) Acyclic communication SDO Up- and Download (Server only), Emergency message (producer), Timestamp (producer/consumer) Functions Node guarding / life guarding, heartbeat 1 producer max. 64 consumer (netX 50/51/100/500) max. 32 consumer (netX 52) max. 4 consumer (netX 10) PDO Mapping NMT Slave SYNC protocol (consumer) Error behavior in state operational: change to state pre-operational no state change change to state stopped Baud rates 10 kBit/s to 1 MBit/s Automatic detection Data transport layer CAN Frames can be accessed by programming the CAN DL layer, see reference [5] CAN Frame type 11 Bit 11/29 Bit layer 2 transparent Table 2: Technical Data - Protocol Stack Firmware/stack available for netX netX Available netX 10 yes netX 50 yes netX 51 yes (since stack V3.3.1) netX 52 yes (since stack V3.5.1) netX 100, netX 500 yes Table 3: Technical Data – Available for netX CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013 Introduction 7/191 PCI - DMA Features Parameter DMA Support for PCI targets yes Table 4: Technical Data – PCI-DMA Slot Number Features Devices Slot number supported for CIFX 50-CO, CIFX 50E-CO, CIFX 70E-CO Table 5: Technical Data – Slot Number Configuration For configuration of standard mode with default settings:  by SYCON.net configuration software (Download or exported configuration file named config.nxd),  by netX Configuration tool. For configuration of standard mode with default settings and configured settings and extended mode:  by packet to transfer configuration parameters. Diagnostic Firmware supports common and extended diagnostic in the dual-port-memory for loadable firmware CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013 Introduction 8/191 1.5.1.1 Technical Data (Standard Mode) In standard mode, the following values and limitations apply: Technical Data for default Settings Features Parameter Default number of input data 512 bytes (netX 50/100/500) 64 bytes (netX 10) Default number of output data 512 bytes (netX 50/100/500) 64 bytes (netX 10) Default number of receive PDOs 64 (netX 50/100/500) 8 (netX 10) Default number of transmit PDOs 64 (netX 50/100/500) 8 (netX 10) Table 6: Technical Data - Protocol Stack (Standard Mode – Default Settings) Note: The EDS files for Hilscher standard products contain the functionality that matches the default settings. SYCON.net and the netX Configuration tool only configure the default settings. Technical Data for configured Settings Features Parameter Maximum number of input data 1020 bytes Maximum number of output data 1020 bytes Number of receive PDOs 0 … 255 (netX 50/100/500) for mapping objects 2200 … 2203 0 … 8 (netX 10) for mapping objects 2200 … 2203 Number of transmit PDOs 0 … 255 (netX 50/100/500) for mapping objects 2000 … 2003 0 … 8 (netX 10) for mapping objects 2000 … 2003 Table 7: Technical Data - Protocol Stack (Standard Mode – Configured Settings) Note 1: Using other settings than the default settings requires a suitable EDS file. Note 2: The actual maximum number of IO Data and PDOs depends on the available amount of memory. Note 3: SYCON.net and netX configuration tool do not support the configuration of the extended mode. CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013 Introduction 9/191 1.5.1.2 Technical Data (Extended Mode) In extended mode, the stack offers extended functionality. To use these functions requires an application program that configures and supports these functions, e.g. to create an own object dictionary. In extended mode, more input and output data can be used and transmit and receive PDOs can be used. Note: The actual maximum number of IO Data and PDOs depends on the available amount of memory. To use the extended mode requires creating a suitable EDS file. The knowledge of the EDS specification is required. Features Parameter Maximum number of input data 2048 bytes Maximum number of output data 2048 bytes Maximum number of receive PDOs 256 Maximum number of transmit PDOs 256 Table 8: Technical Data - Protocol Stack (Extended Mode) Other settings than default must be set via “Set Configuration Packet” and object dictionary configuration. Concerning the extended mode, also see section Standard Mode vs. Extended Mode on page 68. Note: SYCON.net and netX configuration tool do not support the configuration of the extended mode. CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013 Introduction 10/191 1.6 Terms, Abbreviations and Definitions Term Description AP Application on top of the Stack Boot up Initial sequence of node during start-up CAN Controller Area Network CAN-DL CAN Data Link Layer CiA CAN in Automation (CAN User Organization located in Erlangen, Germany) COB-ID Communication Object Identifier DPM Dual Port Memory EMCY Emergency Guarding Supervision of node NMT Network Management OD Object Dictionary ODV3 Object Dictionary Version 3 PDO Process Data Object (process data channel) PDO-Mapping Configurable process data per PDO RTR Remote transmission request RxPDO Receive PDO SDO Service Data Object (representing an acyclic data channel) SYNC Synchronization cycle of the CANopen slave TxPDO Transmit PDO Table 9: Terms, Abbreviations and Definitions All variables, parameters and data used in this manual have basically the LSB/MSB (“Intel”) data representation. This corresponds to the convention of the Microsoft C Compiler. 1.7 References to Documents This document refers to the following documents: [1] EN 50325/4 Specification [2] CAN in Automation e.V., Nuremberg: CANopen Application Layer and Communication Profile, CiA Public Specification 301, Version 4.2.0, 2011 [3] Hilscher Gesellschaft für Systemautomation mbH: Dual-Port Memory Interface Manual, netX based products. Revision 12, English, 2008-2012 [4] Hilscher Gesellschaft für Systemautomation mbH: Object Dictionary Version 3 Manual, 2008- 2013 [5] Hilscher Gesellschaft für Systemautomation mbH: CAN Data Link Packet Interface Protocol API Manual 1.0, 2010-2013 Table 10: References CANopen Slave | Protocol API DOC111001API05EN | Revision 5 | English | 2013-10 | Released | Public © Hilscher, 2011-2013