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 {

    50

  UNS8           nodeId;     /**<own ID if server, or node ID of the server if client */

    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

    89

    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

   103

/** 

   104

 * @brief Reset of a SDO exchange on timeout.

   105

 * Send a SDO abort.

   106

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

   107

 * @param id

   108

 */

   109

void SDOTimeoutAlarm(CO_Data* d, UNS32 id);

   110

   111

/** 

   112

 * @brief Reset all SDO buffers.

   113

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

   114

 */

   115

void resetSDO (CO_Data* d);

   116

   117

   118

/** 

   119

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

   120

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

   121

 * @param line SDO line

   122

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

   123

 */

   124

UNS32 SDOlineToObjdict (CO_Data* d, UNS8 line);

   125

   126

/** 

   127

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

   128

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

   129

 * @param line SDO line

   130

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

   131

 */

   132

UNS32 objdictToSDOline (CO_Data* d, UNS8 line);

   133

   134

/** 

   135

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

   136

 * @param d Pointer on a CAN object data structure

   137

 * @param line SDO line

   138

 * @param nbBytes

   139

 * @param *data Pointer on the data

   140

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

   141

 */

   142

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

   143

   144

/** 

   145

 * @brief Add data to an existant line

   146

 * @param d Pointer on a CAN object data structure

   147

 * @param line SDO line

   148

 * @param nbBytes

   149

 * @param *data Pointer on the data

   150

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

   151

 */

   152

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

   153

   154

/** 

   155

 * @brief Called when an internal SDO abort occurs.

   156

 * Release the line * Only if server *

   157

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

   158

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

   159

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

   160

 * In all cases, sends a SDO abort.

   161

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

   162

 * @param nodeId

   163

 * @param whoami

   164

 * @param index

   165

 * @param subIndex

   166

 * @param abortCode

   167

 * @return 0

   168

 */

   169

UNS8 failedSDO (CO_Data* d, UNS8 nodeId, UNS8 whoami, UNS16 index, UNS8 subIndex, UNS32 abortCode);

   170

   171

/** 

   172

 * @brief Reset an unused line.

   173

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

   174

 * @param line SDO line

   175

 */

   176

void resetSDOline (CO_Data* d, UNS8 line);

   177

   178

/** 

   179

 * @brief Initialize some fields of the structure.

   180

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

   181

 * @param line

   182

 * @param nodeId

   183

 * @param index

   184

 * @param subIndex

   185

 * @param state

   186

 * @return 0

   187

 */

   188

UNS8 initSDOline (CO_Data* d, UNS8 line, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 state);

   189

   190

/** 

   191

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

   192

 * to store a new SDO.

   193

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

   194

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

   195

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

   196

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

   197

 * @param *line Pointer on a SDO line 

   198

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

   199

 */

   200

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

   201

   202

/** 

   203

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

   204

 * beginning of the reception of a fragmented SDO

   205

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

   206

 * @param nodeId correspond to the message node-id

   207

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

   208

 * @param *line Pointer on a SDO line 

   209

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

   210

 */

   211

UNS8 getSDOlineOnUse (CO_Data* d, UNS8 nodeId, UNS8 whoami, UNS8 *line);

   212

   213

/** 

   214

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

   215

 * beginning of the reception of a fragmented SDO

   216

 *

   217

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

   218

 * this funtion is used to return them, too.

   219

 *

   220

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

   221

 * @param nodeId correspond to the message node-id

   222

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

   223

 * @param *line Pointer on a SDO line

   224

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

   225

 */

   226

UNS8 getSDOlineToClose (CO_Data* d, UNS8 nodeId, UNS8 whoami, UNS8 *line);

   227

   228

/** 

   229

 * @brief Close a transmission.

   230

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

   231

 * @param nodeId Node id of the server if both server or client

   232

 * @param whoami Line opened as SDO_CLIENT or SDO_SERVER

   233

 */

   234

UNS8 closeSDOtransfer (CO_Data* d, UNS8 nodeId, UNS8 whoami);

   235

   236

/** 

   237

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

   238

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

   239

 * @param line SDO line 

   240

 * @param *nbBytes Pointer on nbBytes

   241

 * @return 0.

   242

 */

   243

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

   244

   245

/** 

   246

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

   247

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

   248

 * @param line SDO line 

   249

 * @param nbBytes

   250

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

   251

 */

   252

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

   253

   254

/**

   255

 * @brief Transmit a SDO frame on the bus bus_id

   256

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

   257

 * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER

   258

 * @param sdo SDO Structure which contains the sdo to transmit

   259

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

   260

 */

   261

UNS8 sendSDO (CO_Data* d, UNS8 whoami, s_SDO sdo);

   262

   263

/** 

   264

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

   265

 * Read/Write to a undefined object

   266

 * Read/Write to a undefined subindex

   267

 * Read/write a not valid length object

   268

 * Write a read only object

   269

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

   270

 * @param whoami takes 2 values : SDO_CLIENT or SDO_SERVER

   271

 * @param nodeId

   272

 * @param index

   273

 * @param subIndex

   274

 * @param abortCode

   275

 * @return 0

   276

 */

   277

UNS8 sendSDOabort (CO_Data* d, UNS8 whoami, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS32 abortCode);

   278

   279

/** 

   280

 * @brief Treat a SDO frame reception

   281

 * call the function sendSDO

   282

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

   283

 * @param *m Pointer on a CAN message structure 

   284

 * @return code : 

   285

 * 		   - 0xFF if error

   286

 *         - 0x80 if transfert aborted by the server

   287

 *         - 0x0  ok

   288

 */

   289

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

   290

   291

/** 

   292

 * @ingroup sdo

   293

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

   294

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

   295

 * @param nodeId Node Id of the slave

   296

 * @param index At index indicated

   297

 * @param subIndex At subIndex indicated

   298

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

   299

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

   300

 * @param *data Pointer to data

   301

 * @return 

   302

 * - 0 is returned upon success.

   303

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

   304

 * - 0xFF is returned when error occurs.

   305

 */

   306

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

   307

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

   308

   309

/** 

   310

 * @ingroup sdo

   311

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

   312

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

   313

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

   314

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

   315

 * @param nodeId Node Id of the slave

   316

 * @param index At index indicated

   317

 * @param subIndex At subIndex indicated

   318

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

   319

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

   320

 * @param *data Pointer to data

   321

 * @param Callback Callback function

   322

 * @return 

   323

 * - 0 is returned upon success.

   324

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

   325

 * - 0xFF is returned when error occurs.

   326

 */

   327

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

   328

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

   329

   330

/**

   331

 * @ingroup sdo 

   332

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

   333

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

   334

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

   335

 * automatically initialized for specific node if not already defined.

   336

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

   337

 * @param nodeId Node Id of the slave

   338

 * @param index At index indicated

   339

 * @param subIndex At subIndex indicated

   340

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

   341

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

   342

 * @param *data Pointer to data

   343

 * @param Callback Callback function

   344

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

   345

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

   346

 *                  endianness

   347

 * @return 

   348

 * - 0 is returned upon success.

   349

 * - 0xFF is returned when error occurs.

   350

 */

   351

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

   352

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

   353

   354

/**

   355

 * @ingroup sdo 

   356

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

   357

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

   358

 * @param nodeId Node Id of the slave

   359

 * @param index At index indicated

   360

 * @param subIndex At subIndex indicated

   361

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

   362

 * @return 

   363

 * - 0 is returned upon success.

   364

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

   365

 * - 0xFF is returned when error occurs.

   366

 */

   367

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

   368

   369

/** 

   370

 * @ingroup sdo

   371

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

   372

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

   373

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

   374

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

   375

 * @param nodeId Node Id of the slave

   376

 * @param index At index indicated

   377

 * @param subIndex At subIndex indicated

   378

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

   379

 * @param Callback Callback function

   380

 * @return 

   381

 * - 0 is returned upon success.

   382

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

   383

 * - 0xFF is returned when error occurs.

   384

 */

   385

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

   386

   387

/** 

   388

 * @ingroup sdo

   389

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

   390

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

   391

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

   392

 * automatically initialized for specific node if not already defined.

   393

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

   394

 * @param nodeId Node Id of the slave

   395

 * @param index At index indicated

   396

 * @param subIndex At subIndex indicated

   397

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

   398

 * @param Callback Callback function

   399

 * @return 

   400

 * - 0 is returned upon success.

   401

 * - 0xFF is returned when error occurs.

   402

 */

   403

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

   404

   405

/** 

   406

 * @ingroup sdo

   407

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

   408

 * 

   409

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

   410

 * @param nodeId Node Id of the slave

   411

 * @param *data Pointer to the datas

   412

 * @param *size Pointer to the size

   413

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

   414

 * 

   415

 * 

   416

 * @return

   417

 *           - SDO_FINISHED             // datas are available

   418

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

   419

 *           - SDO_ABORTED_INTERNAL     // Transfert failed (internal abort)

   420

 *           - SDO_UPLOAD_IN_PROGRESS   // Datas are not yet available

   421

 *           - SDO_DOWNLOAD_IN_PROGRESS // Download is in progress

   422

 * \n\n

   423

 * example :

   424

 * @code

   425

 * UNS32 data;

   426

 * UNS8 size;

   427

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

   428

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

   429

 * @endcode

   430

*/

   431

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

   432

   433

/**

   434

 * @ingroup sdo

   435

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

   436

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

   437

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

   438

 * @param nodeId Node Id of the slave

   439

 * @param *abortCode Pointer to the abortcode

   440

 * - 0 = not available. 

   441

 * - SDO abort code (received if return SDO_ABORTED_RCV)

   442

 * 

   443

 * @return : 

   444

 *           - SDO_FINISHED             // datas are available

   445

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

   446

 *           - SDO_ABORTED_INTERNAL     // Transfert failed (Internal abort)

   447

 *           - SDO_DOWNLOAD_IN_PROGRESS // Datas are not yet available

   448

 *           - SDO_UPLOAD_IN_PROGRESS   // Upload in progress

   449

 * \n\n

   450

 * example :

   451

 * @code

   452

 * UNS32 data = 0x50;

   453

 * UNS8 size;

   454

 * UNS32 abortCode;

   455

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

   456

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

   457

 * @endcode

   458

*/

   459

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

   460

   461

#endif