1

/*

     2

This file is part of CanFestival, a library implementing CanOpen Stack. 

     3

     4

Copyright (C): Edouard TISSERANT and Francis DUPIN

     5

     6

See COPYING file for copyrights details.

     7

     8

This library is free software; you can redistribute it and/or

     9

modify it under the terms of the GNU Lesser General Public

    10

License as published by the Free Software Foundation; either

    11

version 2.1 of the License, or (at your option) any later version.

    12

    13

This library is distributed in the hope that it will be useful,

    14

but WITHOUT ANY WARRANTY; without even the implied warranty of

    15

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    16

Lesser General Public License for more details.

    17

    18

You should have received a copy of the GNU Lesser General Public

    19

License along with this library; if not, write to the Free Software

    20

Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    21

*/

    22

    23

/** @file

    24

 *  @brief Responsible for accessing the object dictionary.

    25

 *

    26

 *  This file contains functions for accessing the object dictionary and

    27

 *  variables that are contained by the object dictionary.

    28

 *  Accessing the object dictionary contains setting local variables

    29

 *  as PDOs and accessing (read/write) all entries of the object dictionary

    30

 *  @warning Only the basic entries of an object dictionary are included

    31

 *           at the moment.

    32

 */

    33

    34

/** @defgroup od Object Dictionary Management

    35

 *  @brief The Object Dictionary is the heart of each CANopen device containing all communication and application objects.

    36

 *  @ingroup userapi

    37

 */

    38

    39

#ifndef __objacces_h__

    40

#define __objacces_h__

    41

    42

#include <applicfg.h>

    43

    44

    45

#ifdef __cplusplus

    46

extern "C" {

    47

#endif

    48

    49

    50

typedef UNS32 (*valueRangeTest_t)(UNS8 typeValue, void *Value);

    51

typedef void (* storeODSubIndex_t)(CO_Data* d, UNS16 wIndex, UNS8 bSubindex);

    52

void _storeODSubIndex (CO_Data* d, UNS16 wIndex, UNS8 bSubindex);

    53

    54

/**

    55

 * @brief Print MSG_WAR (s) if error to the access to the object dictionary occurs.

    56

 * 

    57

 * You must uncomment the lines in the file objaccess.c :\n

    58

 * //#define DEBUG_CAN\n

    59

 * //#define DEBUG_WAR_CONSOLE_ON\n

    60

 * //#define DEBUG_ERR_CONSOLE_ON\n\n

    61

 * Beware that sometimes, we force the sizeDataDict or sizeDataGiven to 0, when we wants to use

    62

 * this function but we do not have the access to the right value. One example is

    63

 * getSDOerror(). So do not take attention to these variables if they are null.

    64

 * @param index

    65

 * @param subIndex

    66

 * @param sizeDataDict Size of the data defined in the dictionary

    67

 * @param sizeDataGiven Size data given by the user.

    68

 * @param code error code to print. (SDO abort code. See file def.h)

    69

 * @return

    70

 */ 

    71

UNS8 accessDictionaryError(UNS16 index, UNS8 subIndex, 

    72

			   UNS32 sizeDataDict, UNS32 sizeDataGiven, UNS32 code);

    73

    74

    75

/* _getODentry() Reads an entry from the object dictionary.\n

    76

 * 

    77

 *    use getODentry() macro to read from object and endianize

    78

 *    use readLocalDict() macro to read from object and not endianize   

    79

 *

    80

 * @code

    81

 * // Example usage:

    82

 * UNS8  *pbData;

    83

 * UNS8 length;

    84

 * UNS32 returnValue;

    85

 *

    86

 * returnValue = getODentry( (UNS16)0x100B, (UNS8)1, 

    87

 * (void * *)&pbData, (UNS8 *)&length );

    88

 * if( returnValue != SUCCESSFUL )

    89

 * {

    90

 *     // error handling

    91

 * }

    92

 * @endcode 

    93

 * @param *d Pointer to a CAN object data structure

    94

 * @param wIndex The index in the object dictionary where you want to read

    95

 *               an entry

    96

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

    97

 *                  used to tell you how many valid entries you can find

    98

 *                  in this index. Look at the canopen standard for further

    99

 *                  information

   100

 * @param *pDestData Pointer to the pointer which points to the variable where

   101

 *                   the value of this object dictionary entry should be copied

   102

 * @param pExpectedSize This function writes the size of the copied value (in Byte)

   103

 *                      into this variable.

   104

 * @param *pDataType Pointer to the type of the data. See objdictdef.h

   105

 * @param CheckAccess if other than 0, do not read if the data is Write Only

   106

 *                    [Not used today. Put always 0].

   107

 * @param Endianize  When not 0, data is endianized into network byte order

   108

 *                   when 0, data is not endianized and copied in machine native

   109

 *                   endianness 

   110

 * @return 

   111

 * - OD_SUCCESSFUL is returned upon success. 

   112

 * - SDO abort code is returned if error occurs . (See file def.h)

   113

 */

   114

UNS32 _getODentry( CO_Data* d,

   115

                   UNS16 wIndex,

   116

                   UNS8 bSubindex,

   117

                   void * pDestData,

   118

                   UNS32 * pExpectedSize,

   119

                   UNS8 * pDataType,

   120

                   UNS8 checkAccess,

   121

                   UNS8 endianize);

   122

   123

/** 

   124

 * @ingroup od

   125

 * @brief getODentry() to read from object and endianize

   126

 * @param OD Pointer to a CAN object data structure

   127

 * @param wIndex The index in the object dictionary where you want to read

   128

 *                an entry

   129

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   130

 *                  used to tell you how many valid entries you can find

   131

 *                  in this index. Look at the canopen standard for further

   132

 *                  information

   133

 * @param *pDestData Pointer to the pointer which points to the variable where

   134

 *                   the value of this object dictionary entry should be copied

   135

 * @param pExpectedSize This function writes the size of the copied value (in Byte)

   136

 *                      into this variable.

   137

 * @param *pDataType Pointer to the type of the data. See objdictdef.h

   138

 * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)

   139

 * @param endianize  Set to 1 : endianized into network byte order 

   140

 * @return 

   141

 * - OD_SUCCESSFUL is returned upon success. 

   142

 * - SDO abort code is returned if error occurs . (See file def.h)

   143

 */

   144

#define getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \

   145

		          pDataType,  checkAccess)                         \

   146

       _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \

   147

		          pDataType,  checkAccess, 1)            

   148

   149

/** 

   150

 * @ingroup od

   151

 * @brief readLocalDict() reads an entry from the object dictionary, but in 

   152

 * contrast to getODentry(), readLocalDict() doesn't endianize entry and reads

   153

 * entry in machine native endianness. 

   154

 * @param OD Pointer to a CAN object data structure

   155

 * @param wIndex The index in the object dictionary where you want to read

   156

 *                an entry

   157

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   158

 *                  used to tell you how many valid entries you can find

   159

 *                  in this index. Look at the canopen standard for further

   160

 *                  information

   161

 * @param *pDestData Pointer to the pointer which points to the variable where

   162

 *                   the value of this object dictionary entry should be copied

   163

 * @param pExpectedSize This function writes the size of the copied value (in Byte)

   164

 *                      into this variable.

   165

 * @param *pDataType Pointer to the type of the data. See objdictdef.h

   166

 * @param checkAccess if other than 0, do not read if the data is Write Only

   167

 *                    [Not used today. Put always 0].

   168

 * @param endianize Set to 0, data is not endianized and copied in machine native

   169

 *                  endianness 

   170

 * @return 

   171

 * - OD_SUCCESSFUL is returned upon success. 

   172

 * - SDO abort code is returned if error occurs . (See file def.h)

   173

 */

   174

#define readLocalDict( OD, wIndex, bSubindex, pDestData, pExpectedSize, \

   175

		          pDataType,  checkAccess)                         \

   176

       _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \

   177

		          pDataType,  checkAccess, 0)

   178

   179

/* By this function you can write an entry into the object dictionary

   180

 * @param *d Pointer to a CAN object data structure

   181

 * @param wIndex The index in the object dictionary where you want to write

   182

 *               an entry

   183

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   184

 *                  used to tell you how many valid entries you can find

   185

 *                  in this index. Look at the canopen standard for further

   186

 *                  information

   187

 * @param *pSourceData Pointer to the variable that holds the value that should

   188

 *                     be copied into the object dictionary

   189

 * @param *pExpectedSize The size of the value (in Byte).

   190

 * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)

   191

 * @param endianize When not 0, data is endianized into network byte order

   192

 *                  when 0, data is not endianized and copied in machine native

   193

 *                  endianness   

   194

 * @return 

   195

 * - OD_SUCCESSFUL is returned upon success. 

   196

 * - SDO abort code is returned if error occurs . (See file def.h)

   197

 */

   198

UNS32 _setODentry( CO_Data* d,

   199

                   UNS16 wIndex,

   200

                   UNS8 bSubindex,

   201

                   void * pSourceData,

   202

                   UNS32 * pExpectedSize,

   203

                   UNS8 checkAccess,

   204

                   UNS8 endianize);

   205

   206

/**

   207

 * @ingroup od

   208

 * @brief setODentry converts SourceData from network byte order to machine native 

   209

 * format, and writes that to OD.

   210

 * @code

   211

 * // Example usage:

   212

 * UNS8 B;

   213

 * B = 0xFF; // set transmission type

   214

 *

   215

 * retcode = setODentry( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );

   216

 * @endcode

   217

 * @param d Pointer to a CAN object data structure

   218

 * @param wIndex The index in the object dictionary where you want to write

   219

 *               an entry

   220

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   221

 *                  used to tell you how many valid entries you can find

   222

 *                  in this index. Look at the canopen standard for further

   223

 *                  information

   224

 * @param *pSourceData Pointer to the variable that holds the value that should

   225

 *                     be copied into the object dictionary

   226

 * @param *pExpectedSize The size of the value (in Byte).

   227

 * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)

   228

 * @param endianize Set to 1 : endianized into network byte order

   229

 * @return 

   230

 * - OD_SUCCESSFUL is returned upon success. 

   231

 * - SDO abort code is returned if error occurs . (See file def.h)

   232

 */

   233

#define setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, \

   234

                  checkAccess) \

   235

       _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, \

   236

                  checkAccess, 1)

   237

   238

/** @fn UNS32 writeLocalDict(d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess)

   239

 * @ingroup od

   240

 * @hideinitializer

   241

 * @brief Writes machine native SourceData to OD.

   242

 * @param d Pointer to a CAN object data structure

   243

 * @param wIndex The index in the object dictionary where you want to write

   244

 *               an entry

   245

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   246

 *                  used to tell you how many valid entries you can find

   247

 *                  in this index. Look at the canopen standard for further

   248

 *                  information

   249

 * @param *pSourceData Pointer to the variable that holds the value that should

   250

 *                     be copied into the object dictionary

   251

 * @param *pExpectedSize The size of the value (in Byte).

   252

 * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)

   253

 * @param endianize Data is not endianized and copied in machine native endianness 

   254

 * @return 

   255

 * - OD_SUCCESSFUL is returned upon success. 

   256

 * - SDO abort code is returned if error occurs . (See file def.h)

   257

 * \n\n

   258

 * @code

   259

 * // Example usage:

   260

 * UNS8 B;

   261

 * B = 0xFF; // set transmission type

   262

 *

   263

 * retcode = writeLocalDict( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );

   264

 * @endcode

   265

 */

   266

#define writeLocalDict( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \

   267

       _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 0)

   268

   269

   270

   271

/**

   272

 * @brief Scan the index of object dictionary. Used only by setODentry and getODentry.

   273

 * @param *d Pointer to a CAN object data structure

   274

 * @param wIndex

   275

 * @param *errorCode :  OD_SUCCESSFUL if index foundor SDO abort code. (See file def.h)

   276

 * @param **Callback

   277

 * @return NULL if index not found. Else : return the table part of the object dictionary.

   278

 */

   279

 const indextable * scanIndexOD (CO_Data* d, UNS16 wIndex, UNS32 *errorCode, ODCallback_t **Callback);

   280

   281

UNS32 RegisterSetODentryCallBack(CO_Data* d, UNS16 wIndex, UNS8 bSubindex, ODCallback_t Callback);

   282

   283

#ifdef __cplusplus

   284

}

   285

#endif

   286

   287

#endif /* __objacces_h__ */