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

/* Block mode : Data consumer receive step 

    42

 * - set to RXSTEP_STARTED when client receive initiate upload response 

    43

 * - set to RXSTEP_END when last segment of a block received 

    44

 */

    45

typedef enum {RXSTEP_INIT, RXSTEP_STARTED, RXSTEP_END } rxStep_t;

    46

    47

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

    48

    49

/* The Transfer structure

    50

Used to store the different segments of

    51

 - a SDO received before writing in the dictionary

    52

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

    53

WARNING : after a change in this structure check the macro s_transfer_Initializer in data.h

    54

*/

    55

    56

struct struct_s_transfer {

    57

  UNS8           CliServNbr; /**< The index of the SDO client / server in our OD minus 0x1280 / 0x1200 */

    58

    59

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

    60

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

    61

  UNS8           toggle;	

    62

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

    63

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

    64

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

    65

  UNS16          index;

    66

  UNS8           subIndex;

    67

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

    68

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

    69

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

    70

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

    71

                              * WARNING s_transfer.data is subject to ENDIANISATION

    72

                              * (with respect to CANOPEN_BIG_ENDIAN)

    73

                              */

    74

  UNS8           data [SDO_MAX_LENGTH_TRANSFER];

    75

#ifdef SDO_DYNAMIC_BUFFER_ALLOCATION

    76

  UNS8           *dynamicData;

    77

  UNS32          dynamicDataSize;

    78

#endif //SDO_DYNAMIC_BUFFER_ALLOCATION

    79

    80

  UNS8           peerCRCsupport;    /**< True if peer supports CRC */

    81

  UNS8           blksize;           /**< Number of segments per block with 0 < blksize < 128 */

    82

  UNS8           ackseq;            /**< sequence number of last segment that was received successfully */

    83

  UNS32          objsize;           /**< Size in bytes of the object provided by data producer */

    84

  UNS8           lastblockoffset;   /**< Value of offset before last block */

    85

  UNS8           seqno;             /**< Last sequence number received OK or transmitted */   

    86

  UNS8           endfield;          /**< nbr of bytes in last segment of last block that do not contain data */

    87

  rxStep_t       rxstep;            /**< data consumer receive step - set to true when last segment of a block received */

    88

  UNS8           tmpData[8];        /**< temporary segment storage */

    89

    90

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

    91

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

    92

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

    93

                              */

    94

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

    95

                              * It is automatically incremented whenever

    96

                              * the line state is in SDO_DOWNLOAD_IN_PROGRESS or

    97

                              * SDO_UPLOAD_IN_PROGRESS, and reseted to 0

    98

                              * when the response SDO have been received.

    99

                              */

   100

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

   101

};

   102

typedef struct struct_s_transfer s_transfer;

   103

   104

   105

#include "data.h"

   106

   107

/** 

   108

 * @brief Reset of a SDO exchange on timeout.

   109

 * Send a SDO abort.

   110

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

   111

 * @param id

   112

 */

   113

void SDOTimeoutAlarm(CO_Data* d, UNS32 id);

   114

   115

/** 

   116

 * @brief Reset all SDO buffers.

   117

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

   118

 */

   119

void resetSDO (CO_Data* d);

   120

   121

   122

/** 

   123

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

   124

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

   125

 * @param line SDO line

   126

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

   127

 */

   128

UNS32 SDOlineToObjdict (CO_Data* d, UNS8 line);

   129

   130

/** 

   131

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

   132

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

   133

 * @param line SDO line

   134

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

   135

 */

   136

UNS32 objdictToSDOline (CO_Data* d, UNS8 line);

   137

   138

/** 

   139

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

   140

 * @param d Pointer on a CAN object data structure

   141

 * @param line SDO line

   142

 * @param nbBytes

   143

 * @param *data Pointer on the data

   144

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

   145

 */

   146

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

   147

   148

/** 

   149

 * @brief Add data to an existant line

   150

 * @param d Pointer on a CAN object data structure

   151

 * @param line SDO line

   152

 * @param nbBytes

   153

 * @param *data Pointer on the data

   154

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

   155

 */

   156

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

   157

   158

/** 

   159

 * @brief Called when an internal SDO abort occurs.

   160

 * Release the line * Only if server *

   161

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

   162

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

   163

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

   164

 * In all cases, sends a SDO abort.

   165

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

   166

 * @param CliServNbr

   167

 * @param whoami

   168

 * @param index

   169

 * @param subIndex

   170

 * @param abortCode

   171

 * @return 0

   172

 */

   173

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

   174

   175

/** 

   176

 * @brief Reset an unused line.

   177

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

   178

 * @param line SDO line

   179

 */

   180

void resetSDOline (CO_Data* d, UNS8 line);

   181

   182

/** 

   183

 * @brief Initialize some fields of the structure.

   184

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

   185

 * @param line

   186

 * @param CliServNbr

   187

 * @param index

   188

 * @param subIndex

   189

 * @param state

   190

 * @return 0

   191

 */

   192

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

   193

   194

/** 

   195

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

   196

 * to store a new SDO.

   197

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

   198

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

   199

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

   200

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

   201

 * @param *line Pointer on a SDO line 

   202

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

   203

 */

   204

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

   205

   206

/** 

   207

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

   208

 * beginning of the reception of a fragmented SDO

   209

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

   210

 * @param CliServNbr Client or Server object involved

   211

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

   212

 * @param *line Pointer on a SDO line 

   213

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

   214

 */

   215

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

   216

   217

/** 

   218

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

   219

 * beginning of the reception of a fragmented SDO

   220

 *

   221

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

   222

 * this funtion is used to return them, too.

   223

 *

   224

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

   225

 * @param CliServNbr Client or Server object involved

   226

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

   227

 * @param *line Pointer on a SDO line

   228

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

   229

 */

   230

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

   231

   232

/** 

   233

 * @brief Close a transmission.

   234

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

   235

 * @param CliServNbr Client or Server object involved

   236

 * @param whoami Line opened as SDO_CLIENT or SDO_SERVER

   237

 */

   238

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

   239

   240

/** 

   241

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

   242

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

   243

 * @param line SDO line 

   244

 * @param *nbBytes Pointer on nbBytes

   245

 * @return 0.

   246

 */

   247

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

   248

   249

/** 

   250

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

   251

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

   252

 * @param line SDO line 

   253

 * @param nbBytes

   254

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

   255

 */

   256

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

   257

   258

/**

   259

 * @brief Transmit a SDO frame on the bus bus_id

   260

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

   261

 * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER

   262

 * @param CliServNbr Client or Server object involved

   263

 * @param data Array of the 8 bytes to transmit

   264

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

   265

 */

   266

UNS8 sendSDO (CO_Data* d, UNS8 whoami, UNS8 CliServNbr, UNS8 *pData);

   267

   268

/** 

   269

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

   270

 * Read/Write to a undefined object

   271

 * Read/Write to a undefined subindex

   272

 * Read/write a not valid length object

   273

 * Write a read only object

   274

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

   275

 * @param whoami takes 2 values : SDO_CLIENT or SDO_SERVER

   276

 * @param CliServNbr

   277

 * @param index

   278

 * @param subIndex

   279

 * @param abortCode

   280

 * @return 0

   281

 */

   282

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

   283

   284

/** 

   285

 * @brief Treat a SDO frame reception

   286

 * call the function sendSDO

   287

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

   288

 * @param *m Pointer on a CAN message structure 

   289

 * @return code : 

   290

 * 		   - 0xFF if error

   291

 *         - 0x80 if transfer aborted by the server

   292

 *         - 0x0  ok

   293

 */

   294

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

   295

   296

/** 

   297

 * @ingroup sdo

   298

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

   299

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

   300

 * @param nodeId Node Id of the slave

   301

 * @param index At index indicated

   302

 * @param subIndex At subIndex indicated

   303

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

   304

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

   305

 * @param *data Pointer to data

   306

 * @return 

   307

 * - 0 is returned upon success.

   308

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

   309

 * - 0xFF is returned when error occurs.

   310

 */

   311

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

   312

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

   313

   314

/** 

   315

 * @ingroup sdo

   316

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

   317

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

   318

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

   319

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

   320

 * @param nodeId Node Id of the slave

   321

 * @param index At index indicated

   322

 * @param subIndex At subIndex indicated

   323

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

   324

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

   325

 * @param *data Pointer to data

   326

 * @param Callback Callback function

   327

 * @return 

   328

 * - 0 is returned upon success.

   329

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

   330

 * - 0xFF is returned when error occurs.

   331

 */

   332

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

   333

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

   334

   335

/**

   336

 * @ingroup sdo 

   337

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

   338

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

   339

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

   340

 * automatically initialized for specific node if not already defined.

   341

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

   342

 * @param nodeId Node Id of the slave

   343

 * @param index At index indicated

   344

 * @param subIndex At subIndex indicated

   345

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

   346

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

   347

 * @param *data Pointer to data

   348

 * @param Callback Callback function

   349

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

   350

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

   351

 *                  endianness

   352

 * @return 

   353

 * - 0 is returned upon success.

   354

 * - 0xFF is returned when error occurs.

   355

 */

   356

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

   357

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

   358

   359

/**

   360

 * @ingroup sdo 

   361

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

   362

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

   363

 * @param nodeId Node Id of the slave

   364

 * @param index At index indicated

   365

 * @param subIndex At subIndex indicated

   366

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

   367

 * @return 

   368

 * - 0 is returned upon success.

   369

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

   370

 * - 0xFF is returned when error occurs.

   371

 */

   372

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

   373

   374

/** 

   375

 * @ingroup sdo

   376

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

   377

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

   378

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

   379

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

   380

 * @param nodeId Node Id of the slave

   381

 * @param index At index indicated

   382

 * @param subIndex At subIndex indicated

   383

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

   384

 * @param Callback Callback function

   385

 * @return 

   386

 * - 0 is returned upon success.

   387

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

   388

 * - 0xFF is returned when error occurs.

   389

 */

   390

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

   391

   392

/** 

   393

 * @ingroup sdo

   394

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

   395

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

   396

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

   397

 * automatically initialized for specific node if not already defined.

   398

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

   399

 * @param nodeId Node Id of the slave

   400

 * @param index At index indicated

   401

 * @param subIndex At subIndex indicated

   402

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

   403

 * @param Callback Callback function

   404

 * @return 

   405

 * - 0 is returned upon success.

   406

 * - 0xFF is returned when error occurs.

   407

 */

   408

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

   409

   410

/** 

   411

 * @ingroup sdo

   412

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

   413

 * 

   414

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

   415

 * @param nodeId Node Id of the slave

   416

 * @param *data Pointer to the buffer to get the data

   417

 * @param *size Pointer to the size : MUST contain the size of the buffer before calling

   418

 *                                    The function set it to the actual number of written bytes

   419

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

   420

 * 

   421

 * 

   422

 * @return

   423

 *           - SDO_FINISHED             // datas are available

   424

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

   425

 *           - SDO_ABORTED_INTERNAL     // Transfer failed (internal abort)

   426

 *           - SDO_UPLOAD_IN_PROGRESS   // Datas are not yet available

   427

 *           - SDO_DOWNLOAD_IN_PROGRESS // Download is in progress

   428

 *           - SDO_PROVIDED_BUFFER_TOO_SMALL //The value *size is not enough to store the received data

   429

 * \n\n

   430

 * example :

   431

 * @code

   432

 * UNS32 data;

   433

 * UNS8 size;

   434

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

   435

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

   436

 * @endcode

   437

*/

   438

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

   439

   440

/**

   441

 * @ingroup sdo

   442

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

   443

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

   444

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

   445

 * @param nodeId Node Id of the slave

   446

 * @param *abortCode Pointer to the abortcode

   447

 * - 0 = not available. 

   448

 * - SDO abort code (received if return SDO_ABORTED_RCV)

   449

 * 

   450

 * @return : 

   451

 *           - SDO_FINISHED             // datas are available

   452

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

   453

 *           - SDO_ABORTED_INTERNAL     // Transfer failed (Internal abort)

   454

 *           - SDO_DOWNLOAD_IN_PROGRESS // Datas are not yet available

   455

 *           - SDO_UPLOAD_IN_PROGRESS   // Upload in progress

   456

 * \n\n

   457

 * example :

   458

 * @code

   459

 * UNS32 data = 0x50;

   460

 * UNS8 size;

   461

 * UNS32 abortCode;

   462

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

   463

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

   464

 * @endcode

   465

*/

   466

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

   467

   468

#endif