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

/** @defgroup comobj Communication Objects

    24

 *  @ingroup userapi

    25

 */

    26

    27

/** @defgroup sdo Service Data Object (SDO)

    28

 *  SDOs provide the access to entries in the CANopen Object Dictionary.

    29

 * 	An SDO is made up of at least two CAN messages with different identifiers.

    30

 * 	SDO s are always confirmed point-to-point communications services. 

    31

 *  @ingroup comobj

    32

 */

    33

    34

#ifndef __sdo_h__

    35

#define __sdo_h__

    36

    37

struct struct_s_transfer;

    38

    39

#include "timer.h"

    40

    41

typedef void (*SDOCallback_t)(CO_Data* d, UNS8 nodeId);

    42

    43

/* The Transfer structure

    44

Used to store the different segments of

    45

 - a SDO received before writing in the dictionary

    46

 - the reading of the dictionary to put on a SDO to transmit

    47

*/

    48

    49

struct struct_s_transfer {

    51

    52

  UNS8           whoami;     /**< Takes the values SDO_CLIENT or SDO_SERVER */

    53

  UNS8           state;      /**< state of the transmission : Takes the values SDO_... */

    54

  UNS8           toggle;	

    55

  UNS32          abortCode;  /**< Sent or received */

    56

  /**< index and subindex of the dictionary where to store */

    57

  /**< (for a received SDO) or to read (for a transmit SDO) */

    58

  UNS16          index;

    59

  UNS8           subIndex;

    60

  UNS32          count;      /**< Number of data received or to be sent. */

    61

  UNS32          offset;     /**< stack pointer of data[]

    62

                              * Used only to tranfer part of a line to or from a SDO.

    63

                              * offset is always pointing on the next free cell of data[].

    64

                              * WARNING s_transfer.data is subject to ENDIANISATION

    65

                              * (with respect to CANOPEN_BIG_ENDIAN)

    66

                              */

    67

  UNS8           data [SDO_MAX_LENGTH_TRANSFERT];

    68

#ifdef SDO_DYNAMIC_BUFFER_ALLOCATION

    69

  UNS8           *dynamicData;

    70

  UNS32          dynamicDataSize;

    71

#endif //SDO_DYNAMIC_BUFFER_ALLOCATION

    72

  UNS8           dataType;   /**< Defined in objdictdef.h Value is visible_string

    73

                              * if it is a string, any other value if it is not a string,

    74

                              * like 0. In fact, it is used only if client.

    75

                              */

    76

  TIMER_HANDLE   timer;      /**< Time counter to implement a timeout in milliseconds.

    77

                              * It is automatically incremented whenever

    78

                              * the line state is in SDO_DOWNLOAD_IN_PROGRESS or

    79

                              * SDO_UPLOAD_IN_PROGRESS, and reseted to 0

    80

                              * when the response SDO have been received.

    81

                              */

    82

  SDOCallback_t Callback;   /**< The user callback func to be called at SDO transaction end */

    83

};

    84

typedef struct struct_s_transfer s_transfer;

    85

    86

    87

#include "data.h"

    88

    90

struct BODY{

    91

    UNS8 data[8]; /**< The 8 bytes data of the SDO */

    92

};

    93

    94

/* The SDO structure ...*/

    95

struct struct_s_SDO {

    96

  UNS8 nodeId;		/**< In any case, Node ID of the server (case sender or receiver).*/

    97

  struct BODY body;

    98

};

    99

   100

   101

typedef struct struct_s_SDO s_SDO;

   102

   105

/** 

   106

 * @brief Reset of a SDO exchange on timeout.

   107

 * Send a SDO abort.

   108

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

   109

 * @param id

   110

 */

   111

void SDOTimeoutAlarm(CO_Data* d, UNS32 id);

   112

   113

/** 

   114

 * @brief Reset all SDO buffers.

   115

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

   116

 */

   117

void resetSDO (CO_Data* d);

   118

   119

   120

/** 

   121

 * @brief Copy the data received from the SDO line transfert to the object dictionary.

   122

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

   123

 * @param line SDO line

   124

 * @return SDO error code if error. Else, returns 0.

   125

 */

   126

UNS32 SDOlineToObjdict (CO_Data* d, UNS8 line);

   127

   128

/** 

   129

 * @brief Copy the data from the object dictionary to the SDO line for a network transfert.

   130

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

   131

 * @param line SDO line

   132

 * @return SDO error code if error. Else, returns 0.

   133

 */

   134

UNS32 objdictToSDOline (CO_Data* d, UNS8 line);

   135

   136

/** 

   137

 * @brief Copy data from an existant line in the argument "* data"

   138

 * @param d Pointer on a CAN object data structure

   139

 * @param line SDO line

   140

 * @param nbBytes

   141

 * @param *data Pointer on the data

   142

 * @return 0xFF if error. Else, returns 0.

   143

 */

   144

UNS8 lineToSDO (CO_Data* d, UNS8 line, UNS32 nbBytes, UNS8 * data);

   145

   146

/** 

   147

 * @brief Add data to an existant line

   148

 * @param d Pointer on a CAN object data structure

   149

 * @param line SDO line

   150

 * @param nbBytes

   151

 * @param *data Pointer on the data

   152

 * @return 0xFF if error. Else, returns 0.

   153

 */

   154

UNS8 SDOtoLine (CO_Data* d, UNS8 line, UNS32 nbBytes, UNS8 * data);

   155

   156

/** 

   157

 * @brief Called when an internal SDO abort occurs.

   158

 * Release the line * Only if server *

   159

 * If client, the line must be released manually in the core application.

   160

 * The reason of that is to permit the program to read the transfers structure before its reset,

   161

 * because many informations are stored on it : index, subindex, data received or trasmited, ...

   162

 * In all cases, sends a SDO abort.

   163

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

   165

 * @param whoami

   166

 * @param index

   167

 * @param subIndex

   168

 * @param abortCode

   169

 * @return 0

   170

 */

   172

   173

/** 

   174

 * @brief Reset an unused line.

   175

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

   176

 * @param line SDO line

   177

 */

   178

void resetSDOline (CO_Data* d, UNS8 line);

   179

   180

/** 

   181

 * @brief Initialize some fields of the structure.

   182

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

   183

 * @param line

   185

 * @param index

   186

 * @param subIndex

   187

 * @param state

   188

 * @return 0

   189

 */

   191

   192

/** 

   193

 * @brief Search for an unused line in the transfers array

   194

 * to store a new SDO.

   195

 * ie a line which value of the field "state" is "SDO_RESET"

   196

 * An unused line have the field "state" at the value SDO_RESET

   197

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

   198

 * @param whoami Create the line for a SDO_SERVER or SDO_CLIENT.

   199

 * @param *line Pointer on a SDO line 

   200

 * @return 0xFF if all the lines are on use. Else, return 0.

   201

 */

   202

UNS8 getSDOfreeLine (CO_Data* d, UNS8 whoami, UNS8 *line);

   203

   204

/** 

   205

 * @brief Search for the line, in the transfers array, which contains the

   206

 * beginning of the reception of a fragmented SDO

   207

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

   209

 * @param whoami takes 2 values : look for a line opened as SDO_CLIENT or SDO_SERVER

   210

 * @param *line Pointer on a SDO line 

   211

 * @return 0xFF if error.  Else, return 0

   212

 */

   214

   215

/** 

   216

 * @brief Search for the line, in the transfers array, which contains the

   217

 * beginning of the reception of a fragmented SDO

   218

 *

   219

 * Because getSDOlineOnUse() does not return any line in state \c SDO_ABORTED_INTERNAL,

   220

 * this funtion is used to return them, too.

   221

 *

   222

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

   224

 * @param whoami takes 2 values : look for a line opened as SDO_CLIENT or SDO_SERVER

   225

 * @param *line Pointer on a SDO line

   226

 * @return 0xFF if error.  Else, return 0

   227

 */

   229

   230

/** 

   231

 * @brief Close a transmission.

   232

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

   234

 * @param whoami Line opened as SDO_CLIENT or SDO_SERVER

   235

 */

   237

   238

/** 

   239

 * @brief Bytes in the line structure which must be transmited (or received)

   240

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

   241

 * @param line SDO line 

   242

 * @param *nbBytes Pointer on nbBytes

   243

 * @return 0.

   244

 */

   245

UNS8 getSDOlineRestBytes (CO_Data* d, UNS8 line, UNS32 * nbBytes);

   246

   247

/** 

   248

 * @brief Store in the line structure the nb of bytes which must be transmited (or received)

   249

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

   250

 * @param line SDO line 

   251

 * @param nbBytes

   252

 * @return 0 if success, 0xFF if error.

   253

 */

   254

UNS8 setSDOlineRestBytes (CO_Data* d, UNS8 line, UNS32 nbBytes);

   255

   256

/**

   257

 * @brief Transmit a SDO frame on the bus bus_id

   258

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

   259

 * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER

   262

 * @return canSend(bus_id,&m) or 0xFF if error.

   263

 */

   265

   266

/** 

   267

 * @brief Transmit a SDO error to the client. The reasons may be :

   268

 * Read/Write to a undefined object

   269

 * Read/Write to a undefined subindex

   270

 * Read/write a not valid length object

   271

 * Write a read only object

   272

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

   273

 * @param whoami takes 2 values : SDO_CLIENT or SDO_SERVER

   275

 * @param index

   276

 * @param subIndex

   277

 * @param abortCode

   278

 * @return 0

   279

 */

   281

   282

/** 

   283

 * @brief Treat a SDO frame reception

   284

 * call the function sendSDO

   285

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

   286

 * @param *m Pointer on a CAN message structure 

   287

 * @return code : 

   288

 * 		   - 0xFF if error

   289

 *         - 0x80 if transfert aborted by the server

   290

 *         - 0x0  ok

   291

 */

   292

UNS8 proceedSDO (CO_Data* d, Message *m);

   293

   294

/** 

   295

 * @ingroup sdo

   296

 * @brief Used to send a SDO request frame to write the data at the index and subIndex indicated

   297

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

   298

 * @param nodeId Node Id of the slave

   299

 * @param index At index indicated

   300

 * @param subIndex At subIndex indicated

   301

 * @param count number of bytes to write in the dictionnary.

   302

 * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.

   303

 * @param *data Pointer to data

   304

 * @return 

   305

 * - 0 is returned upon success.

   306

 * - 0xFE is returned when no sdo client to communicate with node.

   307

 * - 0xFF is returned when error occurs.

   308

 */

   309

UNS8 writeNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index,

   310

		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data);

   311

   312

/** 

   313

 * @ingroup sdo

   314

 * @brief Used to send a SDO request frame to write in a distant node dictionnary.

   315

 * @details The function Callback which must be defined in the user code is called at the

   316

 * end of the exchange. (on succes or abort).

   317

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

   318

 * @param nodeId Node Id of the slave

   319

 * @param index At index indicated

   320

 * @param subIndex At subIndex indicated

   321

 * @param count number of bytes to write in the dictionnary.

   322

 * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.

   323

 * @param *data Pointer to data

   324

 * @param Callback Callback function

   325

 * @return 

   326

 * - 0 is returned upon success.

   327

 * - 0xFE is returned when no sdo client to communicate with node.

   328

 * - 0xFF is returned when error occurs.

   329

 */

   330

UNS8 writeNetworkDictCallBack (CO_Data* d, UNS8 nodeId, UNS16 index,

   331

		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback);

   332

   333

/**

   334

 * @ingroup sdo 

   335

 * @brief Used to send a SDO request frame to write in a distant node dictionnary.

   336

 * @details The function Callback which must be defined in the user code is called at the

   337

 * end of the exchange. (on succes or abort). First free SDO client parameter is

   338

 * automatically initialized for specific node if not already defined.

   339

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

   340

 * @param nodeId Node Id of the slave

   341

 * @param index At index indicated

   342

 * @param subIndex At subIndex indicated

   343

 * @param count number of bytes to write in the dictionnary.

   344

 * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.

   345

 * @param *data Pointer to data

   346

 * @param Callback Callback function

   347

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

   348

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

   349

 *                  endianness

   350

 * @return 

   351

 * - 0 is returned upon success.

   352

 * - 0xFF is returned when error occurs.

   353

 */

   354

UNS8 writeNetworkDictCallBackAI (CO_Data* d, UNS8 nodeId, UNS16 index,

   355

		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback, UNS8 endianize);

   356

   357

/**

   358

 * @ingroup sdo 

   359

 * @brief Used to send a SDO request frame to read.

   360

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

   361

 * @param nodeId Node Id of the slave

   362

 * @param index At index indicated

   363

 * @param subIndex At subIndex indicated

   364

 * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.

   365

 * @return 

   366

 * - 0 is returned upon success.

   367

 * - 0xFE is returned when no sdo client to communicate with node.

   368

 * - 0xFF is returned when error occurs.

   369

 */

   370

UNS8 readNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType);

   371

   372

/** 

   373

 * @ingroup sdo

   374

 * @brief Used to send a SDO request frame to read in a distant node dictionnary.

   375

 * @details The function Callback which must be defined in the user code is called at the

   376

 * end of the exchange. (on succes or abort).

   377

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

   378

 * @param nodeId Node Id of the slave

   379

 * @param index At index indicated

   380

 * @param subIndex At subIndex indicated

   381

 * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.

   382

 * @param Callback Callback function

   383

 * @return 

   384

 * - 0 is returned upon success.

   385

 * - 0xFE is returned when no sdo client to communicate with node.

   386

 * - 0xFF is returned when error occurs.

   387

 */

   388

UNS8 readNetworkDictCallback (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);

   389

   390

/** 

   391

 * @ingroup sdo

   392

 * @brief Used to send a SDO request frame to read in a distant node dictionnary.

   393

 * @details The function Callback which must be defined in the user code is called at the

   394

 * end of the exchange. (on succes or abort). First free SDO client parameter is

   395

 * automatically initialized for specific node if not already defined.

   396

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

   397

 * @param nodeId Node Id of the slave

   398

 * @param index At index indicated

   399

 * @param subIndex At subIndex indicated

   400

 * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.

   401

 * @param Callback Callback function

   402

 * @return 

   403

 * - 0 is returned upon success.

   404

 * - 0xFF is returned when error occurs.

   405

 */

   406

UNS8 readNetworkDictCallbackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);

   407

   408

/** 

   409

 * @ingroup sdo

   410

 * @brief Use this function after calling readNetworkDict to get the result.

   411

 * 

   412

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

   413

 * @param nodeId Node Id of the slave

   414

 * @param *data Pointer to the datas

   415

 * @param *size Pointer to the size

   416

 * @param *abortCode Pointer to the abortcode. (0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)

   417

 * 

   418

 * 

   419

 * @return

   420

 *           - SDO_FINISHED             // datas are available

   421

 *           - SDO_ABORTED_RCV          // Transfert failed (abort SDO received)

   422

 *           - SDO_ABORTED_INTERNAL     // Transfert failed (internal abort)

   423

 *           - SDO_UPLOAD_IN_PROGRESS   // Datas are not yet available

   424

 *           - SDO_DOWNLOAD_IN_PROGRESS // Download is in progress

   425

 * \n\n

   426

 * example :

   427

 * @code

   428

 * UNS32 data;

   429

 * UNS8 size;

   430

 * readNetworkDict(0, 0x05, 0x1016, 1, 0) // get the data index 1016 subindex 1 of node 5

   431

 * while (getReadResultNetworkDict (0, 0x05, &data, &size) == SDO_UPLOAD_IN_PROGRESS);

   432

 * @endcode

   433

*/

   434

UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data, UNS32 *size, UNS32 * abortCode);

   435

   436

/**

   437

 * @ingroup sdo

   438

 * @brief Use this function after calling writeNetworkDict function to get the result of the write.

   439

 * @details It is mandatory to call this function because it is releasing the line used for the transfer.

   440

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

   441

 * @param nodeId Node Id of the slave

   442

 * @param *abortCode Pointer to the abortcode

   443

 * - 0 = not available. 

   444

 * - SDO abort code (received if return SDO_ABORTED_RCV)

   445

 * 

   446

 * @return : 

   447

 *           - SDO_FINISHED             // datas are available

   448

 *           - SDO_ABORTED_RCV          // Transfert failed (abort SDO received)

   449

 *           - SDO_ABORTED_INTERNAL     // Transfert failed (Internal abort)

   450

 *           - SDO_DOWNLOAD_IN_PROGRESS // Datas are not yet available

   451

 *           - SDO_UPLOAD_IN_PROGRESS   // Upload in progress

   452

 * \n\n

   453

 * example :

   454

 * @code

   455

 * UNS32 data = 0x50;

   456

 * UNS8 size;

   457

 * UNS32 abortCode;

   458

 * writeNetworkDict(0, 0x05, 0x1016, 1, size, &data) // write the data index 1016 subindex 1 of node 5

   459

 * while (getWriteResultNetworkDict (0, 0x05, &abortCode) == SDO_DOWNLOAD_IN_PROGRESS);

   460

 * @endcode

   461

*/

   462

UNS8 getWriteResultNetworkDict (CO_Data* d, UNS8 nodeId, UNS32 * abortCode);

   463

   464

#endif