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

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

    69

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

    70

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

    71

                              */

    72

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

    73

                              * It is automatically incremented whenever

    74

                              * the line state is in SDO_DOWNLOAD_IN_PROGRESS or

    75

                              * SDO_UPLOAD_IN_PROGRESS, and reseted to 0

    76

                              * when the response SDO have been received.

    77

                              */

    78

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

    79

};

    80

typedef struct struct_s_transfer s_transfer;

    81

    82

    83

#include "data.h"

    84

    85

    86

struct BODY{

    87

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

    88

};

    89

    90

/* The SDO structure ...*/

    91

struct struct_s_SDO {

    92

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

    93

  struct BODY body;

    94

};

    95

    96

    97

typedef struct struct_s_SDO s_SDO;

    98

    99

/** 

   100

 * @brief Reset of a SDO exchange on timeout.

   101

 * Send a SDO abort.

   102

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

   103

 * @param id

   104

 */

   105

void SDOTimeoutAlarm(CO_Data* d, UNS32 id);

   106

   107

/** 

   108

 * @brief Reset all SDO buffers.

   109

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

   110

 */

   111

void resetSDO (CO_Data* d);

   112

   113

   114

/** 

   115

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

   116

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

   117

 * @param line SDO line

   118

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

   119

 */

   120

UNS32 SDOlineToObjdict (CO_Data* d, UNS8 line);

   121

   122

/** 

   123

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

   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 objdictToSDOline (CO_Data* d, UNS8 line);

   129

   130

/** 

   131

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

   132

 * @param d Pointer on a CAN object data structure

   133

 * @param line SDO line

   134

 * @param nbBytes

   135

 * @param *data Pointer on the data

   136

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

   137

 */

   138

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

   139

   140

/** 

   141

 * @brief Add data to an existant line

   142

 * @param d Pointer on a CAN object data structure

   143

 * @param line SDO line

   144

 * @param nbBytes

   145

 * @param *data Pointer on the data

   146

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

   147

 */

   148

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

   149

   150

/** 

   151

 * @brief Called when an internal SDO abort occurs.

   152

 * Release the line * Only if server *

   153

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

   154

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

   155

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

   156

 * In all cases, sends a SDO abort.

   157

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

   158

 * @param nodeId

   159

 * @param whoami

   160

 * @param index

   161

 * @param subIndex

   162

 * @param abortCode

   163

 * @return 0

   164

 */

   165

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

   166

   167

/** 

   168

 * @brief Reset an unused line.

   169

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

   170

 * @param line SDO line

   171

 */

   172

void resetSDOline (CO_Data* d, UNS8 line);

   173

   174

/** 

   175

 * @brief Initialize some fields of the structure.

   176

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

   177

 * @param line

   178

 * @param nodeId

   179

 * @param index

   180

 * @param subIndex

   181

 * @param state

   182

 * @return 0

   183

 */

   184

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

   185

   186

/** 

   187

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

   188

 * to store a new SDO.

   189

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

   190

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

   191

 * bus_id is hardware dependant

   192

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

   193

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

   194

 * @param *line Pointer on a SDO line 

   195

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

   196

 */

   197

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

   198

   199

/** 

   200

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

   201

 * beginning of the reception of a fragmented SDO

   202

 * bus_id is hardware dependant

   203

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

   204

 * @param nodeId correspond to the message node-id

   205

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

   206

 * @param *line Pointer on a SDO line 

   207

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

   208

 */

   209

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

   210

   211

/** 

   212

 * @brief Close a transmission.

   213

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

   214

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

   215

 * @param whoami Line opened as SDO_CLIENT or SDO_SERVER

   216

 */

   217

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

   218

   219

/** 

   220

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

   221

 * bus_id is hardware dependant.

   222

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

   223

 * @param line SDO line 

   224

 * @param *nbBytes Pointer on nbBytes

   225

 * @return 0.

   226

 */

   227

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

   228

   229

/** 

   230

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

   231

 * bus_id is hardware dependant.

   232

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

   233

 * @param line SDO line 

   234

 * @param nbBytes

   235

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

   236

 */

   237

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

   238

   239

/**

   240

 * @brief Transmit a SDO frame on the bus bus_id

   241

 * bus_id is hardware dependant

   242

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

   243

 * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER

   244

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

   245

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

   246

 */

   247

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

   248

   249

/** 

   250

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

   251

 * Read/Write to a undefined object

   252

 * Read/Write to a undefined subindex

   253

 * Read/write a not valid length object

   254

 * Write a read only object

   255

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

   256

 * @param whoami takes 2 values : SDO_CLIENT or SDO_SERVER

   257

 * @param nodeId

   258

 * @param index

   259

 * @param subIndex

   260

 * @param abortCode

   261

 * @return 0

   262

 */

   263

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

   264

   265

/** 

   266

 * @brief Treat a SDO frame reception

   267

 * bus_id is hardware dependant

   268

 * call the function sendSDO

   269

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

   270

 * @param *m Pointer on a CAN message structure 

   271

 * @return code : 

   272

 * 		   - 0xFF if error

   273

 *         - 0x80 if transfert aborted by the server

   274

 *         - 0x0  ok

   275

 */

   276

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

   277

   278

/** 

   279

 * @ingroup sdo

   280

 * @brief Used by the application to send a SDO request frame to write the data *data

   281

 * at the index and subIndex indicated

   282

 * bus_id is hardware dependant

   283

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

   284

 * @param nodeId In the dictionary of the slave whose node_id is nodeId

   285

 * @param index At index indicated

   286

 * @param subIndex At subIndex indicated

   287

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

   288

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

   289

 * @param *data Pointer on data

   290

 * @return 0xFF if error, else return 0

   291

 */

   292

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

   293

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

   294

   295

/** 

   296

 * @ingroup sdo

   297

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

   298

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

   299

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

   300

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

   301

 * @param nodeId In the dictionary of the slave whose node_id is nodeId

   302

 * @param index At index indicated

   303

 * @param subIndex At subIndex indicated

   304

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

   305

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

   306

 * @param *data Pointer on data

   307

 * @param Callback Callback function

   308

 * @return 0xFF if error, else return 0

   309

 */

   310

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

   311

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

   312

   313

/**

   314

 * @ingroup sdo 

   315

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

   316

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

   317

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

   318

 * automatically initialized for specific node if not already defined.

   319

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

   320

 * @param nodeId In the dictionary of the slave whose node_id is nodeId

   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 on data

   326

 * @param Callback Callback function

   327

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

   328

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

   329

 *                  endianness

   330

 * @return 0xFF if error, else return 0

   331

 */

   332

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

   333

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

   334

   335

/**

   336

 * @ingroup sdo 

   337

 * @brief Used by the application to send a SDO request frame to read

   338

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

   339

 * @param nodeId In the dictionary of the slave whose node_id is nodeId

   340

 * @param index At index indicated

   341

 * @param subIndex At subIndex indicated

   342

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

   343

 * @return 0xFF if error, else return 0

   344

 */

   345

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

   346

   347

/** 

   348

 * @ingroup sdo

   349

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

   350

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

   351

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

   352

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

   353

 * @param nodeId In the dictionary of the slave whose node_id is nodeId

   354

 * @param index At index indicated

   355

 * @param subIndex At subIndex indicated

   356

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

   357

 * @param Callback Callback function

   358

 * @return 0xFF if error, else return 0

   359

 */

   360

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

   361

   362

/** 

   363

 * @ingroup sdo

   364

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

   365

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

   366

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

   367

 * automatically initialized for specific node if not already defined.

   368

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

   369

 * @param nodeId In the dictionary of the slave whose node_id is nodeId

   370

 * @param index At index indicated

   371

 * @param subIndex At subIndex indicated

   372

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

   373

 * @param Callback Callback function

   374

 * @return 0xFF if error, else return 0

   375

 */

   376

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

   377

   378

/** 

   379

 * @ingroup sdo

   380

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

   381

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

   382

 * @param nodeId In the dictionary of the slave whose node_id is nodeId

   383

 * @param *data Pointer on data

   384

 * @param *size Pointer on size

   385

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

   386

 * 

   387

 * 

   388

 * @return

   389

 *           - SDO_FINISHED             // data is available

   390

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

   391

 *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.

   392

 *           - SDO_UPLOAD_IN_PROGRESS   // Data not yet available

   393

 *           - SDO_DOWNLOAD_IN_PROGRESS // Should not arrive !

   394

 * @code

   395

 * example :

   396

 * UNS32 data;

   397

 * UNS8 size;

   398

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

   399

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

   400

 * @endcode

   401

*/

   402

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

   403

   404

/**

   405

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

   406

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

   407

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

   408

 * @param nodeId In the dictionary of the slave whose node_id is nodeId

   409

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

   410

 * 

   411

 * @return : 

   412

 *           - SDO_FINISHED             // data is available

   413

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

   414

 *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.

   415

 *           - SDO_DOWNLOAD_IN_PROGRESS // Data not yet available

   416

 *           - SDO_UPLOAD_IN_PROGRESS   // Should not arrive !

   417

 * 

   418

 * @code

   419

 * example :

   420

 * UNS32 data = 0x50;

   421

 * UNS8 size;

   422

 * UNS32 abortCode;

   423

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

   424

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

   425

 * @endcode

   426

*/

   427

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

   428

   429

#endif