CANopen Slave Reference Manual

CANopen Slave Reference Manual
Systemhaus fŸr Automatisierung
CANopen Slave Protocol Stack
Version 5.00
Document conventions
For better handling of this manual the following icons and headlines
are used:
This symbol marks a paragraph containing useful information about
the protocol stack operation or giving hints on configuration.
User
This symbol marks a paragraph which describes actions to be executed
by the user of the source code package.
This symbol marks a paragraph which explains possible danger. This
danger might cause a damage to the system or damage to personnel.
Read these sections carefully!
Keywords
Important keywords appear in the border column to help the reader
when browsing through this document.
Syntax, Examples
For function syntax and code examples the font face
Source Code Pro is used.
MicroControl GmbH & Co. KG
Junkersring 23
D-53844 Troisdorf
Fon: +49 / 2241 / 25 65 9 - 0
Fax: +49 / 2241 / 25 65 9 - 11
http://www.microcontrol.net
Contents
1.
2.
3.
4.
5.
6.
7.
8.
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2
Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3
Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.4
Introduction to CAN . . . . . . . . . . . . . . . . . . . . . . 7
1.5
Introduction to CANopen . . . . . . . . . . . . . . . . . . 8
CANopen Slave Overview . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1
Naming Conventions . . . . . . . . . . . . . . . . . . . . . 9
2.2
Message Router . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3
File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4
Initialisation Process . . . . . . . . . . . . . . . . . . . . . . 12
CANopen Slave Manager . . . . . . . . . . . . . . . . . . . . . . . 13
3.1
Initialisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2
Manager Configuration Options . . . . . . . . . . . . 15
3.3
Manager Functions . . . . . . . . . . . . . . . . . . . . . . 16
Service Data Objects - SDO . . . . . . . . . . . . . . . . . . . . . . 21
4.1
SDO Server Configuration Options . . . . . . . . . . 21
4.2
Object Dictionary . . . . . . . . . . . . . . . . . . . . . . . 22
4.3
SDO Client Functions . . . . . . . . . . . . . . . . . . . . 24
Process Data Objects - PDO. . . . . . . . . . . . . . . . . . . . . . 29
5.1
PDO Configuration Options . . . . . . . . . . . . . . . 29
5.2
PDO Functions . . . . . . . . . . . . . . . . . . . . . . . . . 30
Network Management - NMT . . . . . . . . . . . . . . . . . . . . 33
6.1
NMT Configuration Options . . . . . . . . . . . . . . . 33
6.2
NMT Functions . . . . . . . . . . . . . . . . . . . . . . . . . 33
Emergency Service - EMCY . . . . . . . . . . . . . . . . . . . . . . 37
7.1
EMCY Producer Configuration Options . . . . . . . 37
7.2
EMCY Producer Functions . . . . . . . . . . . . . . . . . 38
Synchronisation Service - SYNC . . . . . . . . . . . . . . . . . . 39
8.1
SYNC Configuration Options . . . . . . . . . . . . . . . 39
8.2
SYNC Functions . . . . . . . . . . . . . . . . . . . . . . . . . 40
CANopen Slave Protocol Stack Manual
3
Contents
9.
Time Service - TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9.1
TIME Configuration Options . . . . . . . . . . . . . . . 41
9.2
Timing Functions . . . . . . . . . . . . . . . . . . . . . . . 42
10. Layer Setting Services - LSS . . . . . . . . . . . . . . . . . . . . . 45
10.1
LSS Configuration Options . . . . . . . . . . . . . . . . 45
10.2
LSS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 45
11. Parameter Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
A
11.1
Parameter Storage Configuration Options . . . . 47
11.2
Parameter Storage Functions . . . . . . . . . . . . . . 48
Source Code Agreement . . . . . . . . . . . . . . . . . . . . . . . 51
B. Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4
CANopen Slave Protocol Stack Manual
Scope
1. Scope
The CANopen Slave Protocol Stack manual describes the Application
Programming Interface (API) for access to the CANopen services. The
API provides functionality for the CANopen standards CiA 301, CiA 302
and CiA 305.
The CANopen Slave Protocol Stack is independent from the used CAN
hardware and operating system. Access to the CAN hardware is done
via the CANpie API, which is available for a wide range of CAN controllers. The CANpie API is not subject of this manual.
CANopen Slave Protocol Stack Manual
5
1
Scope
References
1.1 References
1
/1/
CiA 301, CANopen Application Layer and Communication Profile, Version 4.2, CAN in Automation (CiA) e.V.
http://www.can-cia.org
/2/
CiA 302, Additional application layer functions, Part 1 - 7, Version
4.0.2, CAN in Automation (CiA) e.V.
http://www.can-cia.org
/3/
CiA 305, CANopen Layer setting services and protocols, Version
2.2, CAN in Automation (CiA) e.V.
http://www.can-cia.org
/4/
CANpie users guide, Version 2.0, MicroControl GmbH & Co. KG
http://www.microcontrol.net/en/source-code/canpie.html
1.2 Abbreviations
6
API
Application Programming Interface
CAN
Controller area network
CAN-ID
CAN identifier
COB
Communication object
COB-ID
Communication object identifier
CRC
Cyclic redundancy check
LSB
Least significant bit/byte
MSB
Most significant bit/byte
OSI
Open systems interconnection
RTR
Remote transmission request
CANopen Slave Protocol Stack Manual
Definitions
Scope
1.3 Definitions
1
CAN base frame
message that contains up to 8 byte and is identified by 11 bits as
defined in ISO 11898-1
CAN extended frame
message that contains up to 8 byte and is identified by 29 bits as
defined in ISO 11898-1
CAN-ID
identifier for CAN data and remote frames as defined in ISO
11898-1
1.4 Introduction to CAN
CAN (Controller Area Network) is an international standard defined in
the ISO 11898 for high speed and ISO 11519-2 for low speed.
CAN is based on a broadcast communication mechanism. This broadcast communication is achieved by using a message oriented transmission protocol. These messages are identified by using a message
identifier. Such a message identifier has to be unique within the whole
network and it defines not only the content but also the priority of the
message.
The priority at which a message is transmitted compared to another
less urgent message is specified by the identifier of each message. The
priorities are laid down during system design in the form of corresponding binary values and cannot be changed dynamically. The identifier with the lowest binary number has the highest priority. Bus access
conflicts are resolved by bit-wise arbitration on the identifiers involved
by each node observing the bus level bit for bit. This happens in accordance with the "wired and" mechanism, by which the dominant
state overwrites the recessive state. The competition for bus allocation
is lost by all nodes with recessive transmission and dominant observation. All the "losers" automatically become receivers of the message
with the highest priority and do not re-attempt transmission until the
bus is available again.
The CAN protocol supports two message frame formats, the only essential difference being in the length of the identifier. The CAN standard frame, also known as CAN 2.0 A, supports a length of 11 bits for
the identifier, and the CAN extended frame, also known as CAN 2.0 B,
supports a length of 29 bits for the identifier.
CANopen Slave Protocol Stack Manual
7
Scope
Introduction to CANopen
1.5 Introduction to CANopen
1
CANopen is a communication protocol and device profile specification
for embedded systems used in automation. In terms of the OSI model,
CANopen implements the layers above and including the network layer. The CANopen standard consists of an addressing scheme, several
small communication protocols and an application layer defined by a
device profile. The communication protocols have support for network
management, device monitoring and communication between nodes,
including a simple transport layer for message segmentation/desegmentation. The lower level protocol implementing the data link and
physical layers is usually Controller Area Network (CAN), although devices using some other means of communication (such as Ethernet
Powerlink, EtherCAT) can also implement the CANopen device profile.
The basic CANopen device and communication profiles are given in
the CiA 301 specification released by CAN in Automation /1/. Profiles
for more specialized devices are built on top of this basic profile, and
are specified in numerous other standards released by CAN in Automation, such as CiA 401 for I/O-modules and CiA 402 for motion control.
8
CANopen Slave Protocol Stack Manual
Naming Conventions
CANopen Slave Overview
2. CANopen Slave Overview
The following figure shows an overview of the CANopen Slave functionality. Each CANopen service is described in a separate chapter.
Pa
r
a
met
er
St
or
age
L
SSSer
v
i
c
e
Obj
e
c
t
Di
c
t
i
ona
r
y
E
MCYSer
v
i
c
e
SYNCSer
v
i
c
e
SDO Ser
v
er
2
TI
MESe
r
v
i
c
e
PDO Ser
v
i
c
e
NMTSer
v
i
c
e
COSMa
nager
CANpi
e–CAN Dr
i
v
er
Fig. 1: CANopen Slave overview
The CANopen Slave Protocol Stack uses a well-defined CAN API (CANpie) to the CAN interface and thus can be adopted to any kind of CAN
controller. The CANpie API is not described in this manual, for more
information refer to /4/.
2.1 Naming Conventions
All functions, structures, defines and constant value of the CANopen
Bootloader stack have the prefix "Cos". The following table shows the
used nomenclature:
CANopen Slave stack
Prefix
Functions
Cos<service><name>
Enumeration
eCOS_<name>
Structures
Cos<name>_s
Defines
COS_<service>_<name>
Error Codes
eCOS_ERR_<name>
Table 1: Naming conventions
CANopen Slave Protocol Stack Manual
9
CANopen Slave Overview
Message Router
2.2 Message Router
The message router is responsible for reading and writing CAN messages between the CANopen Slave Protocol Stack and the CAN bus. The
CANpie API /4/ and its buffer concept is used to access the CAN interface on the different target platforms.
2
CAN messages are transmitted and received by different CAN message
buffers. Depending on the CANopen service, a specific CAN message
buffer will be selected.
Appl
i
c
at
i
on
CANope
nSl
av
e
eCos
Buf
_NMT
eCos
Buf
_NMT_E
RR
eCos
Buf
_NMT_HBC
eCos
Buf
_SDO_RCV
eCos
Buf
_SDO_TRM
eCos
Buf
_SYNC
eCos
Buf
_L
SS_RCV
eCos
Buf
_L
SS_TRM
e
Cos
Buf
_
E
MCY
eCos
Buf
_PDO1_RCV
eCos
Buf
_PDO1_TRM
eCos
Buf
_TI
ME
CANpi
ebuf
f
e
r
CAN bus
Fig. 2: Detail view of CANpie buffers and associated CANopen services
10
CANopen Slave Protocol Stack Manual
File Structure
CANopen Slave Overview
2.3 File Structure
All header files and implementation files of the CANopen Slave Protocol
Stack package are located in the source directory.
File
Function
cos_conf.h
CANopen Slave configuration file
cos_dict.c / h
Object dictionary access
cos_emcy.c / h
Emergency service
cos_led.c / h
LED support
cos_lss.c / h
Layer Settings Service (LSS)
cos_mgr.c / h
CANopen Slave manager
cos_mobj.c / h
Manufacturer objects
cos_nmt.c / h
Network management (NMT)
cos_pdo.c / h
Process data objects (PDO)
cos_sdo.c / h
Service data objects (SDO) server
cos_sync.c / h
Synchronisation Service (SYNC)
cos_time.c / h
Timer services
cos_user.c
Application functions / event handler
cos301.c / h
Objects of CiA 301
2
Table 2: CANopen Slave Protocol Stack files
The file cos_user.c contains all variables and functions that require
an adoption to the target system.
CANopen Slave Protocol Stack Manual
11
CANopen Slave Overview
Initialisation Process
2.4 Initialisation Process
The CANopen Slave is initialised with CosMgrInit(). This routine will
setup the CAN controller and initialise all necessary services. Afterwards
the stack can be started by calling the CosMgrStart() function.
In summary three steps are necessary to run the CANopen Slave:
 Initialise CANopen Slave Protocol Stack
 Start CANopen Slave Protocol Stack
 Start the timer event function
2
void MyCosInit(void)
{
//-----------------------------------------------------// Initialize the CANopen Slave stack
//
CosMgrInit(eCP_CHANNEL_1, 0);
//-----------------------------------------------------// Start the CANopen Slave,
// bitrate = 500 kBit/s, node-ID = 1,
//
CosMgrStart(eCP_BITRATE_500K, 1);
//-----------------------------------------------------// now the CANopen Slave stack is initialized and
// has to be triggered by calling CosMgrTimerEvent() with
// a cycle time of COS_TIMER_PERIOD
}
Example 1:
Initialization process
The initialisation functions of the CANopen Slave Protocol Stack have
to be executed prior to any other API functions.
12
CANopen Slave Protocol Stack Manual
Initialisation
CANopen Slave Manager
3. CANopen Slave Manager
The CANopen Slave Manager covers the initialization and control of
the protocol stack. It also manages the initialization of the CAN interface via the CANpie driver.
3.1 Initialisation
The CANopen Slave stack is initialized by calling the two functions
CosMgrInit() and CosMgrStart().
//-----------------------------------------------------// Initialize the CANopen Bootloader stack
//
CosMgrInit(eCP_CHANNEL_1, COS_CONF_SLAVE);
//-----------------------------------------------------// initialization for timer and other peripheral
// can be done here
//-----------------------------------------------------// Start the CANopen Slave Protocol Stack,
// bit-rate = 500 kBit/s, node-ID = 1,
//
CosMgrStart(eCP_BITRATE_500K, 1);
Example 2:
Initialization of CANopen Bootloader protocol stack
After calling the CosMgrStart() CANopen Slave stack is running and
a CANopen Boot-up message is send on the CAN bus (i.e. the identifier
700h + node-ID).
The next example shows a complete generic initialisation of the protocol inside the main function. Additional functions for the microcontroller and timer are provided by the MicroControl Library (MCL), they are
shown for a better understanding of the example code.
CANopen Slave Protocol Stack Manual
13
3
CANopen Slave Manager
Initialisation
//-----------------------------------------------------// Initialize the target CPU
//
McCpuInit();
//-----------------------------------------------------// Initialize the CANopen Slave
//
CosMgrInit(eCP_CHANNEL_1, COS_CONF_SLAVE);
//-----------------------------------------------------// Initialize the timer resource on the target CPU
//
McTmrInit();
McTmrFunctionInit(CosTimerEvent,
McTmrTimeToTicks(1000),
eTMR_CTRL_START);
//-----------------------------------------------------// Start the CANopen Slave,
// bitrate = 500 kBit/s, node-ID = 1,
//
CosMgrStart(eCP_BITRATE_500K, 1);
3
//-----------------------------------------------------// this is the main loop of the embedded application
//
while (1)
{
//--------------------------------------------------// check the result of the CANopen manager call
//
if(CosMgrProcess() != eCosErr_NODE_RESET)
{
}
else
{
CosMgrRelease();
}
}
// end while (1)
Example 3:
14
Complete generic initialization of CANopen Slave stack
CANopen Slave Protocol Stack Manual
Manager Configuration Options
CANopen Slave Manager
3.2 Manager Configuration Options
The file cos_conf.h contains definitions for the configuration of the
Manager module. Please set the symbols to an appropriate value in order to achieve a specific CANopen Manager behaviour. For a detailed
specification please refer to the HTML documentation.
3.2.1 COS_MGR_INT
With this symbol it is possible to switch the CAN message handler
(message reception) between Polling- and IRQ-mode. In Polling mode
the messages are read from the buffer during the main loop. The default mode is the IRQ-mode: received CAN messages are processed inside the CAN IRQ-handler.
Prior to changing this symbol make sure that the CANpie driver supports the requested method.
3.2.2 COS_TMR_INT
With this symbol it is possible to switch the timer function between
Polling- and IRQ-mode. In Polling mode the timer value is checked
within the main loop. The default mode is the IRQ-mode: the function
CosTmrEvent()is called within the timer interrupt.
CANopen Slave Protocol Stack Manual
15
3
CANopen Slave Manager
Manager Functions
3.3 Manager Functions
The manager functions (prefix CosMgr) provide general control over
the CANopen Slave protocol stack.
Function name
Description
CosMgrGetBitrate()
Read actual bit-rate setting
CosMgrGetNodeId()
Read actual node-ID setting
3
CosMgrGetSerialNumber() Read serial number of device
CosMgrOnBusOff()
CAN bus status change to Bus-Off,
Callback function (cos_user.c)
CosMgrInit()
Initialise CANopen Slave Protocol Stack
and CAN interface
CosMgrRelease()
Shutdown CANopen Slave Protocol Stack
and CAN interface
CosMgrStart()
Start CANopen Slave Protocol Stack
Table 3: Functions of CANopen Slave Manager
3.3.1 CosMgrGetBitrate
Syntax
uint8_t CosMgrGetBitrate(void)
Function
This function reads the actual bit-rate setting. The code of this function
has to be adopted to the specific target inside the cos_user.c file.
The function returns a constant value for the bit-rate which is defined
by the enumeration CpBitrate_e (file canpie.h).
Parameters
None
Return value
Bit-rate value
16
CANopen Slave Protocol Stack Manual
Manager Functions
CANopen Slave Manager
3.3.2 CosMgrGetNodeId
Syntax
uint8_t CosMgrGetNodeId(void)
Function
This function reads the actual node-ID setting. The code of this function has to be adopted to the specific target inside the cos_user.c
file. The function returns a value in the range from 1 to 127.
Parameters
None
Return value
Node-ID value
3
3.3.3 CosMgrGetSerialNumber
Syntax
uint32_t CosMgrGetSerialNumber(void)
Function
This function returns the Serial Number of the module, which must be
a unique value for a product family. The Serial Number is used within
the Identity Object (Index 1018h).
Parameters
None
Return value
Serial number
3.3.4 CosMgrOnBusOff
Syntax
void CosMgrOnBusOff(void)
Function
This function handles a bus-off condition. The code of this function has
to be adopted to the specific target inside the cos_user.c file.
Parameters
None
Return value
None
CANopen Slave Protocol Stack Manual
17
CANopen Slave Manager
Manager Functions
3.3.5 CosMgrInit
Syntax
uint8_t CosMgrInit(
uint8_t
ubCanIfV,
uint16_t
uwConfigV)
Function
Initialize CANopen Slave Protocol Stack
This function initialises the CANopen Slave Protocol Stack and must be
called prior to any other function. The function assigns the CANopen
Slave Protocol Stack to the CAN interface given by ubCanIfV.
3
The parameter uwConfigV can have the following values:
Value
Description
COS_CONF_SLAVE
Start CANopen Slave Protocol Stack with NMT
slave functionality
COS_CONF_MASTER
Start CANopen Slave Protocol Stack with NMT
slave functionality (package mini-master)
COS_CONF_AUTOSTART
After transmission of the boot-up message, make
an automatic transition of the NMT state
machine to the Operational state
COS_CONF_FD
Start CANopen Slave Protocol Stack in CANopen
FD mode
Table 4: Functions of CANopen Slave Manager
The usage of this function is shown by an example in “Initialisation”
on page 13.
Parameters
ubCanIfV
Return value
On success the value eCOS_ERR_NONE is returned.
18
CAN interface index
CANopen Slave Protocol Stack Manual
Manager Functions
CANopen Slave Manager
3.3.6 CosMgrRelease
Syntax
uint8_t CosMgrRelease(void)
Function
Shut down the CANopen Slave Protocol Stack
This function performs a shut down of the CANopen Slave Protocol
Stack.
3
Parameters
None
Return value
On success the value eCOS_ERR_NONE is returned.
3.3.7 CosMgrStart
Syntax
int8_t CosMgrStart(
uint8_t
ubBitrateV,
uint8_t
ubNodeIdV)
Function
Start the CANopen Slave Protocol Stack
This functions starts the CANopen Slave Protocol Stack. A boot-up message (ID = 700h + node-ID) is generated on the CAN bus.
Parameters
Return value
ubBaudSelV
Initial bit-rate
ubNodeIdV
Device node-ID
On success the value eCOS_ERR_NONE is returned.
CANopen Slave Protocol Stack Manual
19
CANopen Slave Manager
Manager Functions
3
20
CANopen Slave Protocol Stack Manual
SDO Server Configuration Options
Service Data Objects - SDO
4. Service Data Objects - SDO
With Service Data Objects (SDOs) the access to entries of a device Object Dictionary is provided. As these entries may contain data of arbitrary size and data type SDOs can be used to transfer multiple data sets
(each containing an arbitrary large block of data) from a client to a server and vice versa.
The client can control via a multiplexor (index and sub-index of the
Object Dictionary) which data set is to be transferred. The contents of
the data set are defined within the Object Dictionary /1/.
4.1 SDO Server Configuration Options
The file cos_conf.h holds definitions for the configuration of the SDO
server module. Please set the symbols to an appropriate value in order
to achieve a specific SDO server behaviour. For a detailed specification
please refer to the HTML documentation.
4.1.1 COS_DICT_MAN
This symbol defines if manufacturer specific objects are included in the
dictionary. A value of 0 means the manufacturer objects are not included. A value of 1 means they are included.
4.1.2 COS_DICT_SEARCH_FAST
This symbol defines if a fast search algorithm is used for the dictionary.
The fast search algorithm increases the code size. A value of 0 means a
linear search method is used. A value of 1 means the fast search algorithm is used.
4.1.3 SDO_SDO_SEGMENTED
The symbol defines if the segmented SDO transfer is supported. If segmented SDOs are not supported, the code size can be reduced. However, segmented SDOs are required if the data type STRING must be
supported with string length greater than 4.
4.1.4 COS_SDO_BLOCK
The symbol defines if the SDO Block transfer is supported. A value of 0
denotes that SDO Block transfer is not supported. A value greater 0 denotes the maximum number of blocks that can be transferred between
master and slave. The maximum value is 127 blocks.
CANopen Slave Protocol Stack Manual
21
4
Service Data Objects - SDO
Object Dictionary
4.2 Object Dictionary
The file cos_conf.h holds definitions for the configuration of the object
dictionary module. Please set the symbols to an appropriate value in
order to include specific objects. For a detailed specification please refer
to the HTML documentation.
4
Index
Name
Configuration
1000h
Device type
-
1001h
Error register
-
1002h
Manufacturer status register
-
1003h
EMCY error history
COS_DICT_OBJ_1003
1005h
COB-ID SYNC
COS_DICT_OBJ_1005
1006h
Communication cycle period
COS_DICT_OBJ_1006
1008h
Manufacturer device name
COS_DICT_OBJ_1008
1009h
Manufacturer hardware version
COS_DICT_OBJ_1009
100Ah
Manufacturer software version
COS_DICT_OBJ_100A
100Ch
Guard time
COS_DICT_OBJ_100C
100Dh
Life time factor
COS_DICT_OBJ_100C
1010h
Store parameters
COS_DICT_OBJ_1010
1011h
Restore default parameters
COS_DICT_OBJ_1011
1012h
COB-ID time
COS_DICT_OBJ_1012
1013h
High-resolution time stamp
COS_DICT_OBJ_1013
1014h
COB-ID EMCY
COS_DICT_OBJ_1014
1015h
Inhibit time EMCY
COS_DICT_OBJ_1015
1016h
Consumer heartbeat time
COS_DICT_OBJ_1016
1017h
Heartbeat producer time
-
1018h
Identity object
-
1019h
Synchronous counter overflow value COS_DICT_OBJ_1019
1020h
Verify configuration
COS_DICT_OBJ_1020
1029h
Error behaviour
COS_DICT_OBJ_1029
1F80h
NMT startup
COS_DICT_OBJ_1F80
Table 5: Supported objects for CANopen Slave Protocol Stack
22
CANopen Slave Protocol Stack Manual
Object Dictionary
Service Data Objects - SDO
4.2.1 Manufacturer Objects
Manufacturer objects can be added to the object dictionary via the files
cos_mobj.c, cos_mobj.h and cos_mobj.inc. The header file and
the corresponding implementation file provide example code.
Index
Example
2000h
Access to an array of uint16_t values
2001h
Access to an uint8_t value with limit check
2002h
Access to an uint8_t variable
2003h
Access to an uint16_t variable
2004h
Access to an uint32_t variable
2005h
Access to an uint64_t variable
2006h
Deferred SDO response
2007h
Access to a character string with check
2008h
Access to a character string
4
Table 6: Example manufacturer objects of CANopen Slave Protocol Stack
CANopen Slave Protocol Stack Manual
23
Service Data Objects - SDO
SDO Client Functions
4.3 SDO Client Functions
The SDO client functions of the CANopen slave protocol stack have the
prefix CosSdo and are located in the file cos_sdo.c within the
source directory.
Function name
Description
CosSdoBlkUpObjectSize()
Retrieve object size
CosSdoCopyValueToMessage() Copy value into SDO message
CosSdoCopyMessageToValue() Copy data field from SDO message into
value
CosSdoSegFinal()
Handler for segmented SDO write
4
Table 7: SDO client service functions
4.3.1 CosSdoBlkUpObjectSize
Syntax
uint32_t CosSdoBlkUpObjectSize(
uint16_t
uwIndexV,
uint8_t
ubSubIndexV )
Function
This function is called by protocol stack in order to determine the size
(in bytes) of the object to be uploaded (read data from device with
SDO block protocol).
User
Parameters
Return value
24
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
uwIndexV
Index of object
ubSubIndexV
Sub-index of object
Number of bytes for upload
CANopen Slave Protocol Stack Manual
SDO Client Functions
Service Data Objects - SDO
4.3.2 CosSdoCopyValueToMessage
Syntax
void CosSdoCopyValueToMessage(
void *
pValueV,
uint8_t
ubDataTypeV )
Function
This function copies the given value into the data field of a SDO message. Depending on the data type the byte order is assigned according
to CiA 301.
Parameters
pValueV
Pointer to value
ubDataTypeV
Defines the data type of the object
Return value
4
None
uint8_t CosMob_Idx2000(uint8_t ubSubIndexV,
uint8_t ubReqCodeV)
{
...
//-----------------------------------------------------// read access
//
if(ubReqCodeV == eSDO_READ_REQ)
{
//--------------------------------------------------// setup the data size to be transferred
//
ulDataSizeT = ulCosMob_Size2000S;
//--------------------------------------------------// setup segmented SDO handler with data size
// and pointer to data
//
CosSdoSegSetup(&aubCosMob_Jpg2000S[0], ulDataSizeT);
//--------------------------------------------------// inform SDO client about data size
//
CosSdoCopyValueToMessage(&ulDataSizeT, CoDT_INTEGER32);
ubHandlerCodeT = eCosSdo_READ_SEG_OK;
}
...
}
Example 4:
CANopen Slave Protocol Stack Manual
Copy data to SDO message
25
Service Data Objects - SDO
SDO Client Functions
4.3.3 CosSdoCopyMessageToValue
4
Syntax
void CosSdoCopyMessageToValue(
void *
pValueV,
uint8_t
ubDataTypeV )
Function
This function copies the SDO data field into the location defined by
pValueV. Depending on the data type the byte order is assigned according to CiA 301.
Parameters
pValueV
Pointer to value
ubDataTypeV
Defines the data type of the object
Return value
None
uint8_t CosMob_Idx2000(uint8_t ubSubIndexV,
uint8_t ubReqCodeV)
{
...
//------------------------------------------------------// write access
//
else if(ubReqCodeV == eSDO_WRITE_REQ_SEG)
{
//------------------------------------------------// get the data size of the data to be uploaded
//
CosSdoCopyMessageToValue(&ulDataSizeT, CoDT_INTEGER32);
//------------------------------------------------// check the data size and return an error if too large
//
if(ulDataSizeT > JPG_SIZE_MAX)
{
ubHandlerCodeT = eCosSdo_ERR_VALUE_RANGE;
}
else
{
//--------------------------------------------// the data size is OK, setup segmented SDO handler
//
ulCosMob_Size2000S = (uint8_t) ulDataSizeT;
CosSdoSegSetup(&aubCosMob_Jpg2000S, ulDataSizeT);
ubHandlerCodeT = eCosSdo_WRITE_OK;
}
}
...
}
Example 5:
26
Read data from SDO message
CANopen Slave Protocol Stack Manual
SDO Client Functions
Service Data Objects - SDO
4.3.4 CosSdoSegFinal
Syntax
uint8_t CosSdoSegFinal(
uint8_t
ubReqCodeV,
uint16_t
uwIndexV,
uint8_t
ubSubIndexV )
Function
This function is called by the stack when all data during a segmented
transfer has been written to the device. The application can now check
for valid data before a final SDO response is sent. If no data is checked
by the application the function shall return eCosSdo_WRITE_OK.
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
4
Parameters
Return value
ubReqCodeV
Request Code of SDO
uwIndexV
Index of object
ubSubIndexV
Sub-index of object
Return code for SDO callbacks
CANopen Slave Protocol Stack Manual
27
Service Data Objects - SDO
SDO Client Functions
4
28
CANopen Slave Protocol Stack Manual
PDO Configuration Options
Process Data Objects - PDO
5. Process Data Objects - PDO
The real-time data transfer is performed by means of "Process Data Objects (PDO)". The transfer of PDOs is performed with no protocol overhead.
The PDOs correspond to entries in the device Object Dictionary and
provide the interface to the application objects. Data type and mapping of application objects into a PDO are determined by a corresponding default PDO mapping structure within the Device Object
Dictionary. If variable PDO-mapping is supported the number of PDOs
and the mapping of application objects into a PDO may be transmitted
to a device during the device configuration process by applying the
SDO services (refer to “Service Data Objects - SDO” on page 21.) to the
corresponding entries of the Object Dictionary. Number and length of
PDOs of a device are application specific and are specified within the
device profile.
There are two ways PDOs can be used. The first is data transmission
and the second data reception. It is distinguished in Transmit-PDOs
(TPDOs) and Receive-PDOs (RPDOs). Devices supporting TPDOs are
PDO producer and devices which are able to receive PDOs are called
PDO consumer /1/.
5.1 PDO Configuration Options
The file cos_conf.h holds definitions for the configuration of the PDO
module. Please set the symbols to an appropriate value in order to
achieve a specific PDO behaviour. For a detailed specification please refer to the HTML documentation.
5.1.1 COS_PDO_RCV_NUMBER
This symbol defines the number of receive PDOs used by the CANopen
slave. The number may vary between 0 (no receive PDO) and 32.
5.1.2 COS_PDO_RCV_ID_CONST
Depending on the device profile or application it may be required that
the identifier of the receive PDO is constant. This symbol defines if index 14xxh, sub 1 is read-only.
5.1.3 COS_PDO_TRM_NUMBER
This symbol defines the number of transmit PDOs used by the CANopen slave. The number may vary between 0 (no transmit PDO) and
32.
CANopen Slave Protocol Stack Manual
29
5
Process Data Objects - PDO
PDO Functions
5.1.4 COS_PDO_TRM_ID_CONST
Depending on the device profile or application it may be required that
the identifier of the transmit PDO is constant. This symbol defines if index 18xxh, sub 1 is read-only.
5.1.5 COS_PDO_INHIBIT
This symbol defines if an inhibit time is supported for transmit PDOs.
5.1.6 COS_PDO_SYNC_START
This symbol defines if a SYNC start value is supported for transmit
PDOs.
5.1.7 COS_PDO_MAPPING
5
This symbol defines how the PDO mapping is implemented. The fixed
PDO mapping consumes less memory space and computation time.
The variable PDO mapping offers the most flexibility for the PDO service.
5.2 PDO Functions
The PDO functions of the CANopen Slave Protocol Stack have the prefix CosPdo.
Function name
Description
CosPdoAppEvent()
Trigger PDO transmission
CosPdoRcvDataUpdate()
Update process data
CosPdoTrmDataUpdate()
Update process data
Table 8: PDO functions
30
CANopen Slave Protocol Stack Manual
PDO Functions
Process Data Objects - PDO
5.2.1 CosPdoAppEvent
Syntax
void CosPdoAppEvent(
uint8_t *
ubPdoNumberV)
Function
This function starts transmission of a TPDO specified by the parameter
ubPdoNumberV. The function checks if the PDO is enabled and if the
correct transmission type (ePDO_TYPE_EVENT_MANUFACTURER or
ePDO_TYPE_EVENT_PROFILE) is configured for the TPDO.
Parameters
ubPdoNumberV Zero based index of PDO
Return value
None
5.2.2 CosPdoRcvDataUpdate
Syntax
void CosPdoRcvDataUpdate(
uint8_t *
ubPdoNumberV)
Function
This function is called by the CANopen Slave Protocol Stack in order to
update process data which is received by the device via a PDO.
User
5
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
ubPdoNumberV Zero based index of PDO
Return value
None
void CosPdoRcvDataUpdate(uint8_t ubPdoNumberV)
{
uint8_t aubDataT[8];
//------------------------------------------------------// example for PDO receive update
//
CpCoreBufferGetData( &tsCanPortG,
eCosBuf_PDO1_RCV + ubPdoNumberV,
&aubDataT[0]);
// .. do something with this data
}
Example 6:
CANopen Slave Protocol Stack Manual
Reception of PDO data
31
Process Data Objects - PDO
PDO Functions
5.2.3 CosPdoTrmDataUpdate
Syntax
void CosPdoTrmDataUpdate(
uint8_t *
ubPdoNumberV)
Function
This function is called by the framework in order to update process data
which is transmitted by the device via a PDO.
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
ubPdoNumberV Zero based index of PDO
Return value
None
5
void CosPdoTrmDataUpdate(uint8_t ubPdoNumberV)
{
uint8_t aubTrmPdoDataT[8];
//-----------------------------------------------------// example for PDO transmit update
//
aubTrmPdoDataT[0] = 0x2F;
aubTrmPdoDataT[1] = 0x01;
aubTrmPdoDataT[2] = 0x20;
aubTrmPdoDataT[3] = 0x00;
aubTrmPdoDataT[4] = 0x01;
aubTrmPdoDataT[5] = 0x00;
aubTrmPdoDataT[6] = 0x00;
aubTrmPdoDataT[7] = 0x00;
CpCoreBufferSetData( &tsCanPortG,
eCosBuf_PDO1_TRM + ubPdoNumberV,
&aubTrmPdoDataT[0], 0, 8);
CpCoreBufferSetDlc( &tsCanPortG,
eCosBuf_PDO1_TRM + ubPdoNumberV,
8);
}
Example 7:
32
Transmission of PDO data
CANopen Slave Protocol Stack Manual
NMT Configuration Options
Network Management - NMT
6. Network Management - NMT
The network management (NMT) is CANopen device oriented and follows a master-slave structure. NMT objects are used to execute NMT
services. Through NMT services CANopen devices are initialised, started, monitored, reset or stopped.
All CANopen devices are regarded as NMT slaves. An NMT slave is
uniquely identified in the network by its node-ID, a value in the range
of 1 to 127. NMT requires that one CANopen device in the network
fulfils the function of the NMT master /1/.
6.1 NMT Configuration Options
The file cos_conf.h holds definitions for the configuration of the NMT
module. Please set the symbols to an appropriate value in order to
achieve a specific NMT behaviour. For a detailed specification please
refer to the HTML documentation.
6.1.1 COS_NMT_MASTER
This symbol defines if the device is a NMT master. A value of 0 means
the device is NMT slave. The option requires the CANopen Mini-Master
add-on package.
6.2 NMT Functions
The Network Management functions of the CANopen Slave Protocol
Stack have the prefix CosNmt.
Function name
Description
CosNmtCheckNodeReset()
Test for NMT reset command
CosNmtGetNodeState()
Check current node state
CosNmtServiceOnError()
Handle CAN error
CosNmtServiceOnGuardingEvent()
Handle guarding event
CosNmtServiceOnHeartbeatEvent() Handle heartbeat event
CosNmtServiceOnStart()
Handle NMT start node transition
CosNmtServiceOnStop()
Handle NMT stop node transition
CosNmtServiceOnPreOperational() Handle NMT pre-operational
transition
Table 9: NMT functions
CANopen Slave Protocol Stack Manual
33
6
Network Management - NMT
NMT Functions
6.2.1 CosNmtCheckNodeReset
Syntax
uint8_t CosNmtCheckNodeReset(void)
Function
This function returns the node reset state.
Parameters
None
Return value
Node reset state
6.2.2 CosNmtGetNodeState
Syntax
uint8_t CosNmtGetNodeState(void)
Function
This function returns the node state.
Parameters
None
Return value
Node state
6
6.2.3 CosNmtServiceOnError
Syntax
void CosNmtServiceOnError(void)
Function
This function is called when the NMT state machine receives an unknown NMT command, i.e. the identifier 0 with a DLC that does not
match or data that does not match.
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
None
Return value
None
34
CANopen Slave Protocol Stack Manual
NMT Functions
Network Management - NMT
6.2.4 CosNmtServiceOnGuardingEvent
Syntax
void CosNmtServiceOnGuardingEvent(void)
Function
This function is called upon the occurrence of a guarding event.
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
None
Return value
None
6.2.5 CosNmtServiceOnHeartbeatEvent
Syntax
void CosNmtServiceOnHeartbeatEvent(void)
Function
This function is called upon the occurrence of a heartbeat event
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
None
Return value
None
6.2.6 CosNmtServiceOnStart
Syntax
void CosNmtServiceOnStart(void)
Function
This service routine is called when the NMT state machine transits into
"Operational" state. It can be used to perform device specific routines
after reception of the NMT command.
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
None
Return value
None
CANopen Slave Protocol Stack Manual
35
6
Network Management - NMT
NMT Functions
6.2.7 CosNmtServiceOnStop
Syntax
void CosNmtServiceOnStop(void)
Function
This service routine is called when the NMT state machine transits into
"Stopped" state. It can be used to perform device specific routines after
reception of the NMT command.
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
None
Return value
None
6.2.8 CosNmtServiceOnPreOperational
Syntax
void CosNmtServiceOnPreOperational(void)
Function
This service routine is called when the NMT state machine transits into
"Pre-Operational" state. It can be used to perform device specific routines after reception of the NMT command.
6
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
None
Return value
None
36
CANopen Slave Protocol Stack Manual
EMCY Producer Configuration Options
Emergency Service - EMCY
7. Emergency Service - EMCY
Emergency objects are triggered by the occurrence of a device internal
error situation and are transmitted from an emergency producer on the
device. Emergency objects are suitable for interrupt type error alerts.
An emergency object is transmitted only once per 'error event'. As long
as no new errors occur on a device, no further emergency objects must
be transmitted.
The emergency object may be received by zero or more emergency
consumers. The reaction on the emergency consumer(s) is not specified /1/.
7.1 EMCY Producer Configuration Options
The file cos_conf.h holds definitions for the configuration of the EMCY
producer service. Please set the symbols to an appropriate value in order to achieve a specific EMCY behaviour. For a detailed specification
please refer to the HTML documentation.
7.1.1 COS_DICT_OBJ_1014
This symbol defines if the object 1014h (EMCY object) is supported by
the device. A value of 0 means the object is not supported. A values
greater than 0 defines the number of EMCY messages that can be
queued by the CANopen Slave Protocol Stack.
7.1.2 COS_DICT_OBJ_1015
This symbol defines if the object 1015h (Emergency inhibit time) is supported by the device. A value of 0 means the object is not supported.
A values of 1 enables index 1015h in the object dictionary.
CANopen Slave Protocol Stack Manual
37
7
Emergency Service - EMCY
EMCY Producer Functions
7.2 EMCY Producer Functions
The EMCY producer functions of the CANopen Slave Protocol Stack
have the prefix CosEmcy and are located in the file cos_emcy.c within the source directory.
Function name
Description
CosEmcySend()
Send an EMCY message
Table 10: EMCY Producer Service functions
7.2.1 CosEmcySend
Syntax
void CosEmcySend(
uint16_t
uint8_t *
uwEmcyCodeV,
pubManCodeV)
Function
This function is used to send an emergency message (EMCY). The possible values for uwEmcyCodeV are defined in CiA 301. The parameter
pubManCodeV is a pointer to an array of 5 bytes, which can be filled
with user defined data.
Parameters
uwEmcyCodeV
Emergency code
pubManCodeV
Pointer to manufacturer data
7
Return value
None
uint8_t aubDataT[5];
aubDataT[0]
aubDataT[1]
aubDataT[2]
aubDataT[3]
aubDataT[4]
=
=
=
=
=
0x01;
0x02;
0x03;
0x04;
0x05;
CosEmcySend(EMCY_ERR_DEV_GENERAL, &aubDataT[0]);
Example 8:
38
Transmission of EMCY message
CANopen Slave Protocol Stack Manual
SYNC Configuration Options
Synchronisation Service - SYNC
8. Synchronisation Service - SYNC
The Synchronisation Object is broadcasted periodically by the SYNC
producer. This SYNC provides the basic network clock. The time period
between the SYNCs is specified by the standard parameter communication cycle period (Object 1006h: Communication Cycle Period),
which may be written by a configuration tool to the application devices
during the boot-up process. There can be a time jitter in transmission
by the SYNC producer corresponding approximately to the latency due
to some other message being transmitted just before the SYNC. In order to guarantee timely access to the CAN bus the SYNC is given a very
high priority identifier (1005h). Devices which operate synchronously
may use the SYNC object to synchronise their own timing with that of
the Synchronisation Object producer. The details of this synchronisation are device dependent.
8.1 SYNC Configuration Options
The file cos_conf.h holds definitions for the configuration of the LSS
module. Please set the symbols to an appropriate value in order to
achieve a specific LSS behaviour. For a detailed specification please refer to the HTML documentation.
8.1.1 COS_DICT_OBJ_1005
This symbol defines if the object 1005h (SYNC identifier) is supported
by the device. A value of 0 means the object is not supported. A values
of 1 enables index 1005h in the object dictionary.
8
8.1.2 COS_DICT_OBJ_1006
This symbol defines if the object 1006h (communication cycle period)
is supported by the device. If the object is supported, the device can
also be used as SYNC producer. A value of 0 means the object is not
supported. A values of 1 enables index 1006h in the object dictionary.
8.1.3 COS_DICT_OBJ_1019
This symbol defines if the object 1019h (SYNC counter) is supported
by the device. A value of 0 means the object is not supported. A values
of 1 enables index 1019h in the object dictionary.
CANopen Slave Protocol Stack Manual
39
Synchronisation Service - SYNC
SYNC Functions
8.2 SYNC Functions
The SYNC functions of the CANopen Slave Protocol Stack have the prefix CosSync.
Function name
Description
CosSyncEventRcvPdo()
Handle Rcv PDOs
Table 11: SYNC functions
8.2.1 CosSyncEventRcvPdo
Syntax
void CosSyncEventRcvPdo(void)
Function
This function is called upon reception of a SYNC message when the device is operational and the device has Receive PDOs.
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
None
Return value
None
8
40
CANopen Slave Protocol Stack Manual
TIME Configuration Options
Time Service - TIME
9. Time Service - TIME
The are a number of CANopen services which require an internal timer
(e.g. Heartbeat, timer-driven PDO). The timer values for these services
are set in a multiple of 1 millisecond. The stack works internally with
timer ticks. A timer tick has a resolution of 1 microsecond, the time
span of a timer tick is set via the definition COS_TIMER_PERIOD inside
the cos_conf.h file.
The requested time values are converted into timer ticks and vice versa
with the functions CosTmrCalcTicks() and CosTmrCalcTime()
respectively.
9.1 TIME Configuration Options
The file cos_conf.h contains definitions for the configuration of the
TIME module. Please set the symbols to an appropriate value in order
to achieve a specific CANopen timing behaviour. For a detailed specification please refer to the HTML documentation.
9.1.1 COS_TIMER_PERIOD
This symbol defines the period of the timer interrupt. The value is a
multiple of 1 microsecond. It is used for timing services. Please set this
value to the timer interrupt period of the target system.
Please note that the value must be at least 1000 [microseconds], because all CANopen services use a multiple of 1 millisecond.
9
CANopen Slave Protocol Stack Manual
41
Time Service - TIME
Timing Functions
9.2 Timing Functions
The timing functions (prefix CosTmr) provide access to the CANopen
time service.
Function name
Description
CosTmrCalcTicks()
Convert time value to timer ticks
CosTmrCalcTime()
Convert timer ticks to time value
CosTmrEvent()
Execute timer-based services
CosTmrTimeStampConsume() Handle reception of TIME message
(cos_user.c)
CosTmrTimeStampProduce() Transmit TIME message
Table 12: Functions of CANopen Slave time service
9.2.1 CosTmrCalcTicks
Syntax
uint16_t CosTmrCalcTicks(uint16_t uwReqTimingV)
Function
The function calculates the number of required timer ticks based on the
required time uwReqTimingV (in milliseconds) and the constant value
COS_TIMER_PERIOD.
Parameters
uwReqTimingV
Return value
Number of ticks
9
Time value in millisecond
9.2.2 CosTmrCalcTime
Syntax
uint16_t CosTmrCalcTime(uint16_t uwTicksV)
Function
The function calculates the time (in milliseconds) based on the given
number of timer ticks and the constant value COS_TIMER_PERIOD.
Parameters
uwTicksV
Return value
Time in milliseconds
42
Number of timer ticks
CANopen Slave Protocol Stack Manual
Timing Functions
Time Service - TIME
9.2.3 CosTmrEvent
Syntax
void CosTmrEvent(void)
Function
Execute Timer-based Services
This function must be called periodically by a timer resource of the target system. It is responsible to call CANopen services that depend on a
timer (e.g. Heartbeat).
Parameters
None
Return value
None
//--------------------------------------------------------//
// Timer interrupt service routine
//
//
//
//--------------------------------------------------------//
void MyTimerInterrupt(void)
{
//... timer services of application ...
//--- call CANopen stack timer function ------------CosTmrEvent();
//... retrigger the timer
}
Example 9:
Example routine for CosTmrEvent()
In order to have periodical functions available (e.g. heartbeat), it is necessary to call the function CosTmrEvent() cyclically. The cycle time is
defined in microseconds by COS_TIMER_PERIOD in cos_conf.h and
must match the trigger time.
Typically CosTmrEvent() will be called from a timer interrupt but it’s
also possible to call it inside the main loop. This behaviour is controlled
by COS_TMR_INT defined in cos_conf.h.
CANopen Slave Protocol Stack Manual
43
9
Time Service - TIME
Timing Functions
9.2.4 CosTmrTimeStampConsume
Syntax
void CosTmrTimeStampConsume(
CosTimeOfDay_ts * ptsTimeStampV)
Function
This function is called upon reception of a TIME message. The function
is located in the file cos_user.c and has to be adopted to the application
(i.e. writing the data to a RTC).
User
Since the behaviour of this function is application specific, the implementation is available in the file cos_user.c.
Parameters
ptsTimeStampV Pointer to time-of-day structure
Return value
None
9.2.5 CosTmrTimeStampProduce
Syntax
void CosTmrTimeStampProduce(
CosTimeOfDay_ts * ptsTimeStampV)
Function
This function is triggered by the application in order to send a TIME
message. Please note that the TIME object (index 1012h) must be configured for transmission. Otherwise the transmission request is
dropped.
Parameters
ptsTimeStampV Pointer to time-of-day structure
Return value
None
9
44
CANopen Slave Protocol Stack Manual
LSS Configuration Options
Layer Setting Services - LSS
10. Layer Setting Services - LSS
LSS offers the possibility to inquire and change the settings of certain
parameters of the local layers on a CANopen module with LSS Slave capabilities by a CANopen module with LSS Master capabilities via the
CAN Network. The following parameters can be inquired and/or
changed by the use of LSS:
 Node-ID of the CANopen Slave
 Bit timing parameters of the physical layer (bit-rate)
 LSS address (Identity Object, Index 1018h)
By using LSS a LSS slave can be configured for a CANopen network
without using any devices such as DIP-switches for setting the parameters /3/.
10.1 LSS Configuration Options
The file cos_conf.h holds definitions for the configuration of the LSS
module. Please set the symbols to an appropriate value in order to
achieve a specific LSS behaviour. For a detailed specification please refer to the HTML documentation.
10.1.1 COS_LSS_SUPPORT
This symbol is used to enable/disable the LSS capability. If enabled, the
file cos_lss.c must be added to the project. A value of 0 means the
LSS service is not supported. A values of 1 enables the LSS service.
10.2 LSS Functions
The LSS functions of the CANopen Slave Protocol Stack have the prefix
CosLss. The LSS service is completely handled by the CANopen Slave
Protocol Stack.
10
CANopen Slave Protocol Stack Manual
45
Layer Setting Services - LSS
LSS Functions
10
46
CANopen Slave Protocol Stack Manual
Parameter Storage Configuration Options
Parameter Storage
11. Parameter Storage
If the CANopen Slave Protocol Stack is compiled with LSS support
(COS_LSS_SUPPORT) or support for parameter storage (objects 1010h
/ 1011h) the data is saved in a defined structure. This structure is defined by the enumeration CosNvm_e.
For data access to a non-volatile memory (e.g. EEPROM) a simple API
with read and write functions is provided.
11.1 Parameter Storage Configuration Options
The file cos_conf.h holds definitions for the configuration of the storage
module. Please set the symbols to an appropriate value in order to
achieve a specific behaviour. For a detailed specification please refer to
the HTML documentation.
11.1.1 COS_DICT_OBJ_1010
The symbol defines if the object 1010h is supported and how many
sub-indices are used. A value of 0 means the object is not supported,
i.e. the device can not store parameters. A value greater 0 denotes the
highest supported sub-index. The value must be in the range from 0 to
4.
11.1.2 COS_DICT_OBJ_1011
The symbol defines if the object 1011h is supported and how many
sub-indices are used. A value of 0 means the object is not supported,
i.e. the device can not restore parameters. A value greater 0 denotes
the highest supported sub-index. The value must be in the range from
0 to 4.
11
CANopen Slave Protocol Stack Manual
47
Parameter Storage
Parameter Storage Functions
11.2 Parameter Storage Functions
The non-volatile memory access functions of the CANopen Slave Protocol Stack have the prefix McNvm and are located in the file mc_nvm.h
within the source directory.
Function name
Description
McNvmInit()
Initialise Non-Volatile Memory
McNvmRead()
Read data
McNvmWriteEnable()
Enable Write Operation
McNvmWriteDisable()
Disable Write Operation
McNvmWrite()
Write data
Table 13: Parameter storage functions
Please note that the file mc_nvm.c provides only function stubs, they
have to be adopted to the target hardware.
11.2.1 McNvmInit
Syntax
Status_tv McNvmInit(void)
Function
This function is responsible for initialisation of the non-volatile memory.
It has to be called prior to all other functions for non-volatile memory
access.
Parameters
None
Return value
Possible return values are defined in the enumeration NVM_ERR_e, on
success the value eNVM_ERR_OK is returned.
11
48
CANopen Slave Protocol Stack Manual
Parameter Storage Functions
Parameter Storage
11.2.2 McNvmRead
Syntax
Status_tv McNvmRead(
NvmAddr_tv
tvAddressV,
void *
pvdDataV,
NvmSize_tv
tvSizeV)
Function
This function is used to read data from a given memory location tvAddressV. The first memory location is address 0. The address points to
a byte value location.
Parameters
tvAddressV
Memory read address
pvdDataV
Pointer to data
tvSizeV
Number of bytes to read
Return value
Possible return values are defined in the enumeration NVM_ERR_e, on
success the value eNVM_ERR_OK is returned.
11.2.3 McNvmWriteEnable
Syntax
Status_tv McNvmWriteEnable(void)
Function
This function enables write-operation to the non-volatile memory,
which are disabled by default.
Parameters
None
Return value
Possible return values are defined in the enumeration NVM_ERR_e, on
success the value eNVM_ERR_OK is returned.
11.2.4 McNvmWriteDisable
Syntax
Status_tv McNvmWriteDisable(void)
Function
This function disables write-operation to the non-volatile memory.
Parameters
None
Return value
Possible return values are defined in the enumeration NVM_ERR_e, on
success the value eNVM_ERR_OK is returned.
CANopen Slave Protocol Stack Manual
11
49
Parameter Storage
Parameter Storage Functions
11.2.5 McNvmWrite
Syntax
Status_tv McNvmWrite(
NvmAddr_tv
tvAddressV,
void *
pvdDataV,
NvmSize_tv
tvSizeV)
Function
This function is used to write data to a given memory location tvAddressV. The first memory location is address 0. The address points to
a byte value location.
Parameters
tvAddressV
Memory read address
pvdDataV
Pointer to data
tvSizeV
Number of bytes to read
Return value
Possible return values are defined in the enumeration NVM_ERR_e, on
success the value eNVM_ERR_OK is returned.
11
50
CANopen Slave Protocol Stack Manual
Source Code Agreement
A
Source Code Agreement
This source code agreement (hereinafter - "Agreement”) is made between MicroControl GmbH & Co.
KG, Junkersring 23, 53844 Troisdorf, Germany (hereinafter - "MicroControl") and you, the customer
(hereinafter - "Licensee"). MicroControl and Licensee agree as follows:
1.
DEFINITIONS
1.1 For purposes of this Agreement, the following definitions shall apply:
(a)
"Software" shall mean the particular Software product purchased by Licensee from MicroControl.
(b) "Source Code" shall include computer programming code or any computer instructions necessary
to compile the Software.
(c)
"Derivative Works" means any software programs which are developed by Licensee and which incorporate or contain modifications of any part of Source Code, and including any revision, modification, translation (including compilation or recapitulation by computer), abridgment,
condensation, expansion or any other form in which Source Code, may be recast, transformed or
adapted.
(d) "Purpose" means the creation of bug-fixes, corrections, enhancements, revisions, modifications and
adaptations of Source Code and addition of new user interfaces, features and functionality to the
Software.
2.
LICENSEE RIGHTS AND RESTRICTIONS
2.1 By completing this Agreement and subject to the restrictions and consideration stated below, MicroControl grants Licensee a non-exclusive, non-transferable, perpetual right to:
(a)
use and reproduce as many copies of the Source Code as are reasonably necessary only for the
purpose of exercising the rights granted under this Agreement;
A
(b) modify and create Derivative Works of the Source Code for the Purpose;
(c)
use, reproduce, have reproduced, sell (via sub-license), distribute (via sub-license), perform or otherwise transfer (via sub-license), directly or through distributors or resellers, Derivative Works, only
in object code format, that are consistent with the Purpose and subject to the reporting and audit
provisions of the Agreement.
2.2 No right is granted to Licensee hereunder to permit, authorize, license or sub-license any third party to view or use the Source Code.
2.3 No right is granted to Licensee hereunder to permit, authorize, license or sub-license any company
branches or company subsidiary to view or use the Source Code.
2.4 No right is granted to Licensee hereunder to sell, distribute, make available, publish or otherwise
transfer the Source Code except as provided in section 2.1 above.
2.5 Licensee shall not use the Source Code for anything other than its intended, legitimate, and legal
purpose.
2.6 Licensee shall not employ Source Code in any way that competes either directly or indirectly with
MicroControl including but not limited to creation of Derivative Works that compete either directly
or indirectly with Software.
CANopen Slave Protocol Stack Manual
51
Source Code Agreement
2.7 Licensee shall not use the Source Code in any manner not specifically permitted under this Agreement.
2.8 No right is granted under any patents, copyrights, trade secrets, trademarks or other proprietary
rights of MicroControl, except as expressly granted herein.
2.9 The terms of this Agreement entitles Licensee to receive support and maintenance services from
MicroControl with respect to the Source Code for one year after date of purchase.
3.
OWNERSHIP
3.1 MicroControl maintains title and ownership of all copyright interests in the Source Code.
4. CONFIDENTIALITY
4.1 Each party will protect the other's Confidential Information from unauthorized dissemination and
use the same degree of care that such party uses to protect its own like information, but in no event
less than a reasonable degree of care. Neither party will disclose to third parties the other's Confidential Information without the prior written consent of the other party. Neither party will use the
other's Confidential Information for purposes other than those necessary to directly further the purposes of this Agreement. Notwithstanding the foregoing, either party may use or disclose Confidential Information to the extent such party is legally compelled to disclose such Confidential
Information provided, however, that prior to any such compelled disclosure, the disclosing party
will notify the non-disclosing party and will cooperate fully with the non-disclosing party in protecting against any such disclosure and/or obtaining a protective order narrowing the scope of
such disclosure and/or use of the Confidential Information. The parties agree that any breach of
this Section would cause irreparable harm to the disclosing party for which monetary damages
would not be adequate and therefore, the parties agree that in the event of a breach of this Section
4.1, the disclosing party shall be entitled to equitable relief in addition to any remedies it may have
hereunder or at law.
A
4.2 In additional to the provisions of Section 4.1 above, Licensee acknowledges that the Source Code
(and to the extent containing MicroControl trade secrets, the Licensee Derivative Works) constitutes a valuable asset of MicroControl and therefore agrees that only the following Licensee employees shall have access to the Source Code and the source code to the Licensee Derivative Works:
those employees:
(a)
employees who have a need for such access to accomplish the purposes of the distribution rights
and license grants specified in Section 2 above; and
(b) with whom Licensee has a legally enforceable obligation that precludes disclosure of third-party
proprietary information and is otherwise sufficient to enable Licensee to comply with all the provisions of this Agreement. Licensee shall not grant any other individual or entity access to the Source
Code.
4.3 Licensee shall implement reasonable security measures to prevent unauthorized use or disclosure
of Source Code. Licensee agrees to segregate all Source Code and Confidential Information from
its own confidential information and from the confidential information of others in order to prevent
commingling.
4.4 Each party agrees to take appropriate action by instruction, agreement or otherwise with its employees, agents and contractors allowed access to the Confidential Information to satisfy its obligations under this Section 4.
52
CANopen Slave Protocol Stack Manual
Source Code Agreement
5. LIMITATION ON LIABILITY
5.1 To the maximum extent permitted by applicable law, MicroControl shall not be liable to Licensee
for any incidental, consequential, special, punitive or indirect damages, including without limitation, damages for loss of profits, business opportunity, data or use, incurred by Licensee or any third
party, even if it has been advised of the possibility of such damages.
6. WARRANTY AND DISCLAIMER
6.1 MicroControl warrants that it has all right, power and authority to enter into this Agreement and
to grant the licenses granted hereunder.
6.2 Except as set forth in section 6.1 above, MicroControl makes no representations or warranties with
respect to the Source Code. All express or implied representations and warranties, including without limitation any implied warranty of merchantability, of fitness for a particular purpose, of reliability or availability, of accuracy or completeness of responses, of results, of workmanlike effort, of
lack of viruses, and of lack of negligence, is hereby expressly disclaimed. Licensee specifically acknowledges that the Source Code is provided "as is" and may have bugs, errors, defects or deficiencies.
7. INDEMNITY
7.1 Licensee agrees to defend, indemnify and hold harmless MicroControl from and against any damages, costs and expenses (including, without limitation, reasonable attorneys fees and costs) arising
from or relating to any third party claims, actions or demands that the sale, distribution or other
transfer of any Derivative Works by Licensee or its distributors or resellers infringes the intellectual
property rights of any third party.
8. TERMINATION.
8.1 This Agreement is in effect so long as Licensee holds any copy of the Source Code on any Licensee
computer or storage media either onsite or offsite.
8.2 Upon termination or expiration of this Agreement for any reason whatsoever, Licensee shall immediately:
(a)
A
cease all use of Product Source Code;
(b) make all reasonable effort to destroy and/or remove all copies of Source Code from Licensee computers and storage media; and
(c)
return all Software, Source Code, Documentation, Confidential Information, and the source code
to all Licensee Derivative Works and all related materials and copies thereof to MicroControl. In
addition to the foregoing, Licensee agrees that it shall not, following termination of this Agreement, act in any way to damage the reputation or goodwill of MicroControl or any Software, Licensee Derivative Work or other product.
8.3 Except as otherwise expressly provided herein, upon the expiration or termination of this Agreement Licensee shall not be entitled to, and to the fullest extent permitted by law waives, any statutorily prescribed or other compensation, reimbursement or damages for loss of goodwill,
clientele, prospective profits, investments or anticipated sales or commitments of any kind.
CANopen Slave Protocol Stack Manual
53
Source Code Agreement
9. MISCELLANEOUS
9.1 Assignment and Effect: This Agreement shall inure to the benefit of and be binding upon both parties, as well as their employees, employers, agents, parents, subsidiaries, representatives, licensees,
and assigns.
9.2 Modifications: There will be no modifications, alterations, or amendments to this Agreement, unless both parties agree in writing.
9.3 Governing Law: This Agreement shall be governed by and construed under the laws of the Federal
Republic of Germany.
9.4 Jurisdiction and Venue: Should any dispute arise under the terms of this Agreement, such dispute
will finally be solved under the procedure established by the laws of the Federal Republic of Germany in the German court according to the place of domicile of MicroControl.
9.5 Transfer of Rights: Without prejudice to any other rights, MicroControl shall have the right to transfer any rights and/or obligations hereunder to any third party.
A
54
CANopen Slave Protocol Stack Manual
Index
B. Index
E
EMCY 37
EMCY Producer Functions 38
CosEmcySend 38
L
LSS 45
M
Manager 13
Manager Functions 16
CosMgrInit 18
CosMgrOnBusOff 16, 17
CosMgrRelease 19
CosMgrStart 19
N
NMT 33
NMT Functions 33
S
SDO 21
B
CANopen Slave Protocol Stack Manual
55
Index
B
56
CANopen Slave Protocol Stack Manual
Disclaimers
Life support — Products and software described in this manual are not designed for use in life
support appliances, devices, or systems where malfunction of these products can reasonably be
expected to result in personal injury. MicroControl customers using or selling these products for
use in such applications do so at their own risk and agree to fully indemnify MicroControl for
any damages resulting from such application.
Right to make changes — MicroControl reserves the right to make changes in the products including circuits and/or software - described or contained herein in order to improve design
and/or performance. MicroControl assumes no responsibility or liability for the use of any of
these products, conveys no licence or title under any patent, copyright, or mask work right to
these products, and makes no representations or warranties that these products are free from
patent, copyright, or mask work right infringement, unless otherwise specified.
Copyright
No part of this functional specification may be copied, transmitted or stored in a retrieval system
or reproduced in any way including, but not limited to, photography, magnetic, optic or other
recording means, without prior written permission from MicroControl GmbH & Co. KG.
© 2017 MicroControl GmbH & Co. KG, Troisdorf
CANopen Slave Protocol Stack Manual
57
Systemhaus fŸr Automatisierung
MicroControl GmbH & Co. KG
Junkersring 23
D-53844 Troisdorf
Fon: +49 / 2241 / 25 65 9 - 0
Fax: +49 / 2241 / 25 65 9 - 11
http://www.microcontrol.net
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement