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

    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) */

    60

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

    61

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

    68

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

    72

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

    78

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

    85

    87

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

    92

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

    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

   107

/** 

   108

 * @brief Reset all SDO buffers.

   109

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

   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.

   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.

   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.

   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.

   150

/** 

   151

 * @brief Called when an internal SDO abort occurs.

   154

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

   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

   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

   186

/** 

   187

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

   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.

   199

/** 

   200

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

   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

   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

   219

/** 

   220

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

   222

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

   223

 * @param line SDO line 

   224

 * @param *nbBytes Pointer on nbBytes

   225

 * @return 0.

   229

/** 

   230

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

   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.

   239

/**

   240

 * @brief Transmit a SDO frame on the bus bus_id

   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.

   249

/** 

   250

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

   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

   265

/** 

   266

 * @brief Treat a SDO frame reception

   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

   278

/** 

   279

 * @ingroup sdo

   280

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

   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

   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

   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

   312

   313

/**

   314

 * @ingroup sdo 

   315

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

   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

   328

 * @return 0xFF if error, else return 0

   332

   333

/**

   334

 * @ingroup sdo 

   335

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

   336

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

   337

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

   338

 * @param index At index indicated

   339

 * @param subIndex At subIndex indicated

   340

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

   341

 * @return 0xFF if error, else return 0

   342

 */

   343

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

   344

   345

/** 

   346

 * @ingroup sdo

   347

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

   348

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

   350

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

   351

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

   352

 * @param index At index indicated

   353

 * @param subIndex At subIndex indicated

   354

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

   355

 * @param Callback Callback function

   356

 * @return 0xFF if error, else return 0

   360

/** 

   361

 * @ingroup sdo

   362

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

   366

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

   367

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

   368

 * @param index At index indicated

   369

 * @param subIndex At subIndex indicated

   370

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

   371

 * @param Callback Callback function

   372

 * @return 0xFF if error, else return 0

   376

/** 

   377

 * @ingroup sdo

   378

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

   379

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

   380

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

   381

 * @param *data Pointer on data

   382

 * @param *size Pointer on size

   383

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

   384

 * 

   385

 * 

   386

 * @return

   387

 *           - SDO_FINISHED             // data is available

   388

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

   389

 *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.

   390

 *           - SDO_UPLOAD_IN_PROGRESS   // Data not yet available

   391

 *           - SDO_DOWNLOAD_IN_PROGRESS // Should not arrive !

   392

 *

   393

 * example :

   394

 * UNS32 data;

   395

 * UNS8 size;

   396

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

   397

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

   399

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

   402

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

   403

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

   404

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

   405

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

   406

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

   407

 * 

   408

 * @return : 

   409

 *           - SDO_FINISHED             // data is available

   410

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

   411

 *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.

   412

 *           - SDO_DOWNLOAD_IN_PROGRESS // Data not yet available

   413

 *           - SDO_UPLOAD_IN_PROGRESS   // Should not arrive !

   414

 * 

   415

 * example :

   416

 * UNS32 data = 0x50;

   417

 * UNS8 size;

   418

 * UNS32 abortCode;

   419

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

   420

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