include/sdo.h

   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 #ifndef __sdo_h__
  24 #define __sdo_h__
  25
  26 struct struct_s_transfer;
  27
  28 #include "timer.h"
  29
  30 typedef void (*SDOCallback_t)(CO_Data* d, UNS8 nodeId);
  31
  32 /* The Transfer structure
  33 Used to store the different segments of
  34  - a SDO received before writing in the dictionary
  35  - the reading of the dictionary to put on a SDO to transmit
  36 */
  37
  38 struct struct_s_transfer {
  39   UNS8           nodeId;     /*own ID if server, or node ID of the server if client */
  40
  41   UNS8           whoami;     /* Takes the values SDO_CLIENT or SDO_SERVER */
  42   UNS8           state;      /* state of the transmission : Takes the values SDO_... */
  43   UNS8           toggle;
  44   UNS32          abortCode;  /* Sent or received */
  45   /* index and subindex of the dictionary where to store */
  46   /* (for a received SDO) or to read (for a transmit SDO) */
  47   UNS16          index;
  48   UNS8           subIndex;
  49   UNS32          count;      /* Number of data received or to be sent. */
  50   UNS32          offset;     /* stack pointer of data[]
  51                               * Used only to tranfer part of a line to or from a SDO.
  52                               * offset is always pointing on the next free cell of data[].
  53                               * WARNING s_transfer.data is subject to ENDIANISATION
  54                               * (with respect to CANOPEN_BIG_ENDIAN)
  55                               */
  56   UNS8           data [SDO_MAX_LENGTH_TRANSFERT];
  57   UNS8           dataType;   /* Defined in objdictdef.h Value is visible_string
  58                               * if it is a string, any other value if it is not a string,
  59                               * like 0. In fact, it is used only if client.
  60                               */
  61   TIMER_HANDLE   timer;      /* Time counter to implement a timeout in milliseconds.
  62                               * It is automatically incremented whenever
  63                               * the line state is in SDO_DOWNLOAD_IN_PROGRESS or
  64                               * SDO_UPLOAD_IN_PROGRESS, and reseted to 0
  65                               * when the response SDO have been received.
  66                               */
  67   SDOCallback_t Callback;   /* The user callback func to be called at SDO transaction end */
  68 };
  69 typedef struct struct_s_transfer s_transfer;
  70
  71
  72 #include "data.h"
  73
  74 /* The 8 bytes data of the SDO */
  75 struct BODY{
  76     UNS8 data[8];
  77 };
  78
  79 /* The SDO structure ...*/
  80 struct struct_s_SDO {
  81   UNS8 nodeId;          /*in any case, Node ID of the server (case sender or receiver).*/
  82   struct BODY body;
  83 };
  84
  85
  86 typedef struct struct_s_SDO s_SDO;
  87
  88 /** Reset of a SDO exchange on timeout.
  89  * Send a SDO abort
  90  */
  91 void SDOTimeoutAlarm(CO_Data* d, UNS32 id);
  92
  93 /** Reset all sdo buffers
  94  */
  95 void resetSDO (CO_Data* d);
  96
  97
  98 /** Copy the data received from the SDO line transfert to the object dictionary
  99  * Returns SDO error code if error. Else, returns 0;
 100  */
 101 UNS32 SDOlineToObjdict (CO_Data* d, UNS8 line);
 102
 103 /** Copy the data from the object dictionary to the SDO line for a network transfert.
 104  * Returns SDO error code if error. Else, returns 0;
 105  */
 106 UNS32 objdictToSDOline (CO_Data* d, UNS8 line);
 107
 108 /** copy data from an existant line in the argument "* data"
 109  * Returns 0xFF if error. Else, returns 0;
 110  */
 111 UNS8 lineToSDO (CO_Data* d, UNS8 line, UNS8 nbBytes, UNS8 * data);
 112
 113 /** Add data to an existant line
 114  * Returns 0xFF if error. Else, returns 0;
 115  */
 116 UNS8 SDOtoLine (CO_Data* d, UNS8 line, UNS8 nbBytes, UNS8 * data);
 117
 118 /** Called when an internal SDO abort occurs.
 119  * Release the line * Only if server *
 120  * If client, the line must be released manually in the core application.
 121  * The reason of that is to permit the program to read the transfers[][] structure before its reset,
 122  * because many informations are stored on it : index, subindex, data received or trasmited, ...
 123  * In all cases, sends a SDO abort.
 124  * Returns 0
 125  */
 126 UNS8 failedSDO (CO_Data* d, UNS8 nodeId, UNS8 whoami, UNS16 index,
 127                 UNS8 subIndex, UNS32 abortCode);
 128
 129 /** Reset an unused line.
 130  *
 131  */
 132 void resetSDOline (CO_Data* d, UNS8 line);
 133
 134 /** Initialize some fields of the structure.
 135  * Returns 0
 136  */
 137 UNS8 initSDOline (CO_Data* d, UNS8 line, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 state);
 138
 139 /** Search for an unused line in the transfers array
 140  * to store a new SDO.
 141  * ie a line which value of the field "state" is "SDO_RESET"
 142  * An unused line have the field "state" at the value SDO_RESET
 143  * bus_id is hardware dependant
 144  * whoami : create the line for a SDO_SERVER or SDO_CLIENT.
 145  * return 0xFF if all the lines are on use. Else, return 0
 146  */
 147 UNS8 getSDOfreeLine (CO_Data* d, UNS8 whoami, UNS8 *line);
 148
 149 /** Search for the line, in the transfers array, which contains the
 150  * beginning of the reception of a fragmented SDO
 151  * whoami takes 2 values : look for a line opened as SDO_CLIENT or SDO_SERVER
 152  * bus_id is hardware dependant
 153  * nodeId correspond to the message node-id
 154  * return 0xFF if error.  Else, return 0
 155  */
 156 UNS8 getSDOlineOnUse (CO_Data* d, UNS8 nodeId, UNS8 whoami, UNS8 *line);
 157
 158 /** Close a transmission.
 159  * nodeId : Node id of the server if both server or client
 160  * whoami : Line opened as SDO_CLIENT or SDO_SERVER
 161  */
 162 UNS8 closeSDOtransfer (CO_Data* d, UNS8 nodeId, UNS8 whoami);
 163
 164 /** Bytes in the line structure which must be transmited (or received)
 165  * bus_id is hardware dependant.
 166  * return 0.
 167  */
 168 UNS8 getSDOlineRestBytes (CO_Data* d, UNS8 line, UNS8 * nbBytes);
 169
 170 /** Store in the line structure the nb of bytes which must be transmited (or received)
 171  * bus_id is hardware dependant.
 172  * return 0 if success, 0xFF if error.
 173  */
 174 UNS8 setSDOlineRestBytes (CO_Data* d, UNS8 line, UNS8 nbBytes);
 175
 176 /** Transmit a SDO frame on the bus bus_id
 177  * sdo is a structure which contains the sdo to transmit
 178  * bus_id is hardware dependant
 179  * whoami takes 2 values : SDO_CLIENT or SDO_SERVER
 180  * return canSend(bus_id,&m) or 0xFF if error
 181  */
 182 UNS8 sendSDO (CO_Data* d, UNS8 whoami, s_SDO sdo);
 183
 184 /** Transmit a SDO error to the client. The reasons may be :
 185  * Read/Write to a undefined object
 186  * Read/Write to a undefined subindex
 187  * Read/write a not valid length object
 188  * Write a read only object
 189  * whoami takes 2 values : SDO_CLIENT or SDO_SERVER
 190  */
 191 UNS8 sendSDOabort (CO_Data* d, UNS8 whoami, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS32 abortCode);
 192
 193 /** Treat a SDO frame reception
 194  * bus_id is hardware dependant
 195  * call the function sendSDO
 196  * return 0xFF if error
 197  *        0x80 if transfert aborted by the server
 198  *        0x0  ok
 199  */
 200 UNS8 proceedSDO (CO_Data* d, Message *m);
 201
 202 /** Used by the application to send a SDO request frame to write the data *data
 203  * at the index and subIndex indicated
 204  * in the dictionary of the slave whose node_id is nodeId
 205  * Count : nb of bytes to write in the dictionnary.
 206  * datatype (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
 207  * bus_id is hardware dependant
 208  * return 0xFF if error, else return 0
 209  */
 210 UNS8 writeNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index,
 211                        UNS8 subIndex, UNS8 count, UNS8 dataType, void *data);
 212 /** Used to send a SDO request frame to write in a distant node dictionnary.
 213  * The function Callback        which must be defined in the user code is called at the
 214  * end of the exchange. (on succes or abort).
 215  */
 216 UNS8 writeNetworkDictCallBack (CO_Data* d, UNS8 nodeId, UNS16 index,
 217                        UNS8 subIndex, UNS8 count, UNS8 dataType, void *data, SDOCallback_t Callback);
 218 /** Used to send a SDO request frame to write in a distant node dictionnary.
 219  * The function Callback        which must be defined in the user code is called at the
 220  * end of the exchange. (on succes or abort). First free SDO client parameter is
 221  * automatically initialized for specific node if not already defined.
 222  */
 223 UNS8 writeNetworkDictCallBackAI (CO_Data* d, UNS8 nodeId, UNS16 index,
 224                        UNS8 subIndex, UNS8 count, UNS8 dataType, void *data, SDOCallback_t Callback, UNS8 endianize);
 225 /** Used by the application to send a SDO request frame to read
 226  * in the dictionary of a server node whose node_id is ID
 227  * at the index and subIndex indicated
 228  * bus_id is hardware dependant
 229  * datatype (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
 230  * return 0xFF if error, else return 0
 231  */
 232 UNS8 readNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index,
 233                       UNS8 subIndex, UNS8 dataType);
 234
 235 /** Used to send a SDO request frame to read in a distant node dictionnary.
 236  * The function Callback        which must be defined in the user code is called at the
 237  * end of the exchange. (on succes or abort).
 238  */
 239 UNS8 readNetworkDictCallback (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
 240
 241 /** Used to send a SDO request frame to read in a distant node dictionnary.
 242  * The function Callback which must be defined in the user code is called at the
 243  * end of the exchange. (on succes or abort). First free SDO client parameter is
 244  * automatically initialized for specific node if not already defined.
 245  */
 246 UNS8 readNetworkDictCallbackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
 247
 248 /** Use this function after a readNetworkDict to get the result.
 249   Returns : SDO_FINISHED             // data is available
 250             SDO_ABORTED_RCV          // Transfert failed. (abort SDO received)
 251             SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.
 252             SDO_UPLOAD_IN_PROGRESS   // Data not yet available
 253             SDO_DOWNLOAD_IN_PROGRESS // Should not arrive !
 254
 255   dataType (defined in objdictdef.h) : type expected. put "visible_string" for strings, 0 for integers or reals.
 256   abortCode : 0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
 257   example :
 258   UNS32 data;
 259   UNS8 size;
 260   readNetworkDict(0, 0x05, 0x1016, 1, 0) // get the data index 1016 subindex 1 of node 5
 261   while (getReadResultNetworkDict (0, 0x05, &data, &size) != SDO_UPLOAD_IN_PROGRESS);
 262 */
 263 UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data,
 264                                UNS8 *size, UNS32 * abortCode);
 265
 266 /**
 267   Use this function after a writeNetworkDict to get the result of the write
 268   It is mandatory to call this function because it is releasing the line used for the transfer.
 269   Returns : SDO_FINISHED             // data is available
 270             SDO_ABORTED_RCV          // Transfert failed. (abort SDO received)
 271             SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.
 272             SDO_DOWNLOAD_IN_PROGRESS // Data not yet available
 273             SDO_UPLOAD_IN_PROGRESS   // Should not arrive !
 274   abortCode : 0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
 275   example :
 276   UNS32 data = 0x50;
 277   UNS8 size;
 278   UNS32 abortCode;
 279   writeNetworkDict(0, 0x05, 0x1016, 1, size, &data) // write the data index 1016 subindex 1 of node 5
 280   while ( getWriteResultNetworkDict (0, 0x05, &abortCode) != SDO_DOWNLOAD_IN_PROGRESS);
 281 */
 282 UNS8 getWriteResultNetworkDict (CO_Data* d, UNS8 nodeId, UNS32 * abortCode);
 283
 284
 285
 286
 287 #endif