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