sdo.h

00001 /*
00002 This file is part of CanFestival, a library implementing CanOpen Stack.
00003 
00004 Copyright (C): Edouard TISSERANT and Francis DUPIN
00005 
00006 See COPYING file for copyrights details.
00007 
00008 This library is free software; you can redistribute it and/or
00009 modify it under the terms of the GNU Lesser General Public
00010 License as published by the Free Software Foundation; either
00011 version 2.1 of the License, or (at your option) any later version.
00012 
00013 This library is distributed in the hope that it will be useful,
00014 but WITHOUT ANY WARRANTY; without even the implied warranty of
00015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00016 Lesser General Public License for more details.
00017 
00018 You should have received a copy of the GNU Lesser General Public
00019 License along with this library; if not, write to the Free Software
00020 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00021 */
00022 
00023 /** @defgroup comobj Communication Objects
00024  *  @ingroup userapi
00025  */
00026  
00027 /** @defgroup sdo Service Data Object (SDO)
00028  *  SDOs provide the access to entries in the CANopen Object Dictionary.
00029  *     An SDO is made up of at least two CAN messages with different identifiers.
00030  *     SDO s are always confirmed point-to-point communications services. 
00031  *  @ingroup comobj
00032  */
00033  
00034 #ifndef __sdo_h__
00035 #define __sdo_h__
00036 
00037 struct struct_s_transfer;
00038 
00039 #include "canopen_timer.h"
00040 
00041 typedef void (*SDOCallback_t)(CO_Data* d, UNS8 nodeId);
00042 
00043 /* The Transfer structure
00044 Used to store the different segments of
00045  - a SDO received before writing in the dictionary
00046  - the reading of the dictionary to put on a SDO to transmit
00047 */
00048 
00049 struct struct_s_transfer {
00050   UNS8           nodeId;     /**<own ID if server, or node ID of the server if client */
00051 
00052   UNS8           whoami;     /**< Takes the values SDO_CLIENT or SDO_SERVER */
00053   UNS8           state;      /**< state of the transmission : Takes the values SDO_... */
00054   UNS8           toggle;    
00055   UNS32          abortCode;  /**< Sent or received */
00056   /**< index and subindex of the dictionary where to store */
00057   /**< (for a received SDO) or to read (for a transmit SDO) */
00058   UNS16          index;
00059   UNS8           subIndex;
00060   UNS32          count;      /**< Number of data received or to be sent. */
00061   UNS32          offset;     /**< stack pointer of data[]
00062                               * Used only to tranfer part of a line to or from a SDO.
00063                               * offset is always pointing on the next free cell of data[].
00064                               * WARNING s_transfer.data is subject to ENDIANISATION
00065                               * (with respect to CANOPEN_BIG_ENDIAN)
00066                               */
00067   UNS8           data [SDO_MAX_LENGTH_TRANSFERT];
00068 #ifdef SDO_DYNAMIC_BUFFER_ALLOCATION
00069   UNS8           *dynamicData;
00070   UNS32          dynamicDataSize;
00071 #endif //SDO_DYNAMIC_BUFFER_ALLOCATION
00072   UNS8           dataType;   /**< Defined in objdictdef.h Value is visible_string
00073                               * if it is a string, any other value if it is not a string,
00074                               * like 0. In fact, it is used only if client.
00075                               */
00076   TIMER_HANDLE   timer;      /**< Time counter to implement a timeout in milliseconds.
00077                               * It is automatically incremented whenever
00078                               * the line state is in SDO_DOWNLOAD_IN_PROGRESS or
00079                               * SDO_UPLOAD_IN_PROGRESS, and reseted to 0
00080                               * when the response SDO have been received.
00081                               */
00082   SDOCallback_t Callback;   /**< The user callback func to be called at SDO transaction end */
00083 };
00084 typedef struct struct_s_transfer s_transfer;
00085 
00086 
00087 #include "data.h"
00088 
00089 
00090 struct BODY{
00091     UNS8 data[8]; /**< The 8 bytes data of the SDO */
00092 };
00093 
00094 /* The SDO structure ...*/
00095 struct struct_s_SDO {
00096   UNS8 nodeId;        /**< In any case, Node ID of the server (case sender or receiver).*/
00097   struct BODY body;
00098 };
00099 
00100 
00101 typedef struct struct_s_SDO s_SDO;
00102 
00103 /*!
00104 ** Called by writeNetworkDict
00105 **
00106 ** @param d
00107 ** @param nodeId
00108 ** @param index
00109 ** @param subIndex
00110 ** @param count
00111 ** @param dataType
00112 ** @param data
00113 ** @param Callback
00114 ** @param endianize
00115 **
00116 ** @return
00117 **/
00118 UNS8 _writeNetworkDict  (CO_Data* d, UNS8 nodeId, UNS16 index,
00119                UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback, UNS8 endianize);
00120 
00121 /** 
00122  * @brief Reset of a SDO exchange on timeout.
00123  * Send a SDO abort.
00124  * @param *d Pointer on a CAN object data structure
00125  * @param id
00126  */
00127 void SDOTimeoutAlarm(CO_Data* d, UNS32 id);
00128 
00129 /** 
00130  * @brief Reset all SDO buffers.
00131  * @param *d Pointer on a CAN object data structure
00132  */
00133 void resetSDO (CO_Data* d);
00134 
00135 
00136 /** 
00137  * @brief Copy the data received from the SDO line transfert to the object dictionary.
00138  * @param *d Pointer on a CAN object data structure
00139  * @param line SDO line
00140  * @return SDO error code if error. Else, returns 0.
00141  */
00142 UNS32 SDOlineToObjdict (CO_Data* d, UNS8 line);
00143 
00144 /** 
00145  * @brief Copy the data from the object dictionary to the SDO line for a network transfert.
00146  * @param *d Pointer on a CAN object data structure
00147  * @param line SDO line
00148  * @return SDO error code if error. Else, returns 0.
00149  */
00150 UNS32 objdictToSDOline (CO_Data* d, UNS8 line);
00151 
00152 /** 
00153  * @brief Copy data from an existant line in the argument "* data"
00154  * @param d Pointer on a CAN object data structure
00155  * @param line SDO line
00156  * @param nbBytes
00157  * @param *data Pointer on the data
00158  * @return 0xFF if error. Else, returns 0.
00159  */
00160 UNS8 lineToSDO (CO_Data* d, UNS8 line, UNS32 nbBytes, UNS8 * data);
00161 
00162 /** 
00163  * @brief Add data to an existant line
00164  * @param d Pointer on a CAN object data structure
00165  * @param line SDO line
00166  * @param nbBytes
00167  * @param *data Pointer on the data
00168  * @return 0xFF if error. Else, returns 0.
00169  */
00170 UNS8 SDOtoLine (CO_Data* d, UNS8 line, UNS32 nbBytes, UNS8 * data);
00171 
00172 /** 
00173  * @brief Called when an internal SDO abort occurs.
00174  * Release the line * Only if server *
00175  * If client, the line must be released manually in the core application.
00176  * The reason of that is to permit the program to read the transfers structure before its reset,
00177  * because many informations are stored on it : index, subindex, data received or trasmited, ...
00178  * In all cases, sends a SDO abort.
00179  * @param *d Pointer on a CAN object data structure
00180  * @param nodeId
00181  * @param whoami
00182  * @param index
00183  * @param subIndex
00184  * @param abortCode
00185  * @return 0
00186  */
00187 UNS8 failedSDO (CO_Data* d, UNS8 nodeId, UNS8 whoami, UNS16 index, UNS8 subIndex, UNS32 abortCode);
00188 
00189 /** 
00190  * @brief Reset an unused line.
00191  * @param *d Pointer on a CAN object data structure
00192  * @param line SDO line
00193  */
00194 void resetSDOline (CO_Data* d, UNS8 line);
00195 
00196 /** 
00197  * @brief Initialize some fields of the structure.
00198  * @param *d Pointer on a CAN object data structure
00199  * @param line
00200  * @param nodeId
00201  * @param index
00202  * @param subIndex
00203  * @param state
00204  * @return 0
00205  */
00206 UNS8 initSDOline (CO_Data* d, UNS8 line, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 state);
00207 
00208 /** 
00209  * @brief Search for an unused line in the transfers array
00210  * to store a new SDO.
00211  * ie a line which value of the field "state" is "SDO_RESET"
00212  * An unused line have the field "state" at the value SDO_RESET
00213  * @param *d Pointer on a CAN object data structure
00214  * @param whoami Create the line for a SDO_SERVER or SDO_CLIENT.
00215  * @param *line Pointer on a SDO line 
00216  * @return 0xFF if all the lines are on use. Else, return 0.
00217  */
00218 UNS8 getSDOfreeLine (CO_Data* d, UNS8 whoami, UNS8 *line);
00219 
00220 /** 
00221  * @brief Search for the line, in the transfers array, which contains the
00222  * beginning of the reception of a fragmented SDO
00223  * @param *d Pointer on a CAN object data structure
00224  * @param nodeId correspond to the message node-id
00225  * @param whoami takes 2 values : look for a line opened as SDO_CLIENT or SDO_SERVER
00226  * @param *line Pointer on a SDO line 
00227  * @return 0xFF if error.  Else, return 0
00228  */
00229 UNS8 getSDOlineOnUse (CO_Data* d, UNS8 nodeId, UNS8 whoami, UNS8 *line);
00230 
00231 /** 
00232  * @brief Search for the line, in the transfers array, which contains the
00233  * beginning of the reception of a fragmented SDO
00234  *
00235  * Because getSDOlineOnUse() does not return any line in state \c SDO_ABORTED_INTERNAL,
00236  * this funtion is used to return them, too.
00237  *
00238  * @param *d Pointer on a CAN object data structure
00239  * @param nodeId correspond to the message node-id
00240  * @param whoami takes 2 values : look for a line opened as SDO_CLIENT or SDO_SERVER
00241  * @param *line Pointer on a SDO line
00242  * @return 0xFF if error.  Else, return 0
00243  */
00244 UNS8 getSDOlineToClose (CO_Data* d, UNS8 nodeId, UNS8 whoami, UNS8 *line);
00245 
00246 /** 
00247  * @brief Close a transmission.
00248  * @param *d Pointer on a CAN object data structure
00249  * @param nodeId Node id of the server if both server or client
00250  * @param whoami Line opened as SDO_CLIENT or SDO_SERVER
00251  */
00252 UNS8 closeSDOtransfer (CO_Data* d, UNS8 nodeId, UNS8 whoami);
00253 
00254 /** 
00255  * @brief Bytes in the line structure which must be transmited (or received)
00256  * @param *d Pointer on a CAN object data structure
00257  * @param line SDO line 
00258  * @param *nbBytes Pointer on nbBytes
00259  * @return 0.
00260  */
00261 UNS8 getSDOlineRestBytes (CO_Data* d, UNS8 line, UNS32 * nbBytes);
00262 
00263 /** 
00264  * @brief Store in the line structure the nb of bytes which must be transmited (or received)
00265  * @param *d Pointer on a CAN object data structure
00266  * @param line SDO line 
00267  * @param nbBytes
00268  * @return 0 if success, 0xFF if error.
00269  */
00270 UNS8 setSDOlineRestBytes (CO_Data* d, UNS8 line, UNS32 nbBytes);
00271 
00272 /**
00273  * @brief Transmit a SDO frame on the bus bus_id
00274  * @param *d Pointer on a CAN object data structure
00275  * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER
00276  * @param sdo SDO Structure which contains the sdo to transmit
00277  * @return canSend(bus_id,&m) or 0xFF if error.
00278  */
00279 UNS8 sendSDO (CO_Data* d, UNS8 whoami, s_SDO sdo);
00280 
00281 /** 
00282  * @brief Transmit a SDO error to the client. The reasons may be :
00283  * Read/Write to a undefined object
00284  * Read/Write to a undefined subindex
00285  * Read/write a not valid length object
00286  * Write a read only object
00287  * @param *d Pointer on a CAN object data structure
00288  * @param whoami takes 2 values : SDO_CLIENT or SDO_SERVER
00289  * @param nodeId
00290  * @param index
00291  * @param subIndex
00292  * @param abortCode
00293  * @return 0
00294  */
00295 UNS8 sendSDOabort (CO_Data* d, UNS8 whoami, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS32 abortCode);
00296 
00297 /** 
00298  * @brief Treat a SDO frame reception
00299  * call the function sendSDO
00300  * @param *d Pointer on a CAN object data structure
00301  * @param *m Pointer on a CAN message structure 
00302  * @return code : 
00303  *            - 0xFF if error
00304  *         - 0x80 if transfert aborted by the server
00305  *         - 0x0  ok
00306  */
00307 UNS8 proceedSDO (CO_Data* d, Message *m);
00308 
00309 /** 
00310  * @ingroup sdo
00311  * @brief Used to send a SDO request frame to write the data at the index and subIndex indicated
00312  * @param *d Pointer to a CAN object data structure
00313  * @param nodeId Node Id of the slave
00314  * @param index At index indicated
00315  * @param subIndex At subIndex indicated
00316  * @param count number of bytes to write in the dictionnary.
00317  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
00318  * @param *data Pointer to data
00319  * @return 
00320  * - 0 is returned upon success.
00321  * - 0xFE is returned when no sdo client to communicate with node.
00322  * - 0xFF is returned when error occurs.
00323  */
00324 UNS8 writeNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index,
00325                UNS8 subIndex, UNS32 count, UNS8 dataType, void *data);
00326 
00327 /** 
00328  * @ingroup sdo
00329  * @brief Used to send a SDO request frame to write in a distant node dictionnary.
00330  * @details The function Callback which must be defined in the user code is called at the
00331  * end of the exchange. (on succes or abort).
00332  * @param *d Pointer to a CAN object data structure
00333  * @param nodeId Node Id of the slave
00334  * @param index At index indicated
00335  * @param subIndex At subIndex indicated
00336  * @param count number of bytes to write in the dictionnary.
00337  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
00338  * @param *data Pointer to data
00339  * @param Callback Callback function
00340  * @return 
00341  * - 0 is returned upon success.
00342  * - 0xFE is returned when no sdo client to communicate with node.
00343  * - 0xFF is returned when error occurs.
00344  */
00345 UNS8 writeNetworkDictCallBack (CO_Data* d, UNS8 nodeId, UNS16 index,
00346                UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback);
00347 
00348 /**
00349  * @ingroup sdo 
00350  * @brief Used to send a SDO request frame to write in a distant node dictionnary.
00351  * @details The function Callback which must be defined in the user code is called at the
00352  * end of the exchange. (on succes or abort). First free SDO client parameter is
00353  * automatically initialized for specific node if not already defined.
00354  * @param *d Pointer to a CAN object data structure
00355  * @param nodeId Node Id of the slave
00356  * @param index At index indicated
00357  * @param subIndex At subIndex indicated
00358  * @param count number of bytes to write in the dictionnary.
00359  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
00360  * @param *data Pointer to data
00361  * @param Callback Callback function
00362  * @param endianize When not 0, data is endianized into network byte order
00363  *                  when 0, data is not endianized and copied in machine native
00364  *                  endianness
00365  * @return 
00366  * - 0 is returned upon success.
00367  * - 0xFF is returned when error occurs.
00368  */
00369 UNS8 writeNetworkDictCallBackAI (CO_Data* d, UNS8 nodeId, UNS16 index,
00370                UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback, UNS8 endianize);
00371 
00372 /**
00373  * @ingroup sdo 
00374  * @brief Used to send a SDO request frame to read.
00375  * @param *d Pointer to a CAN object data structure
00376  * @param nodeId Node Id of the slave
00377  * @param index At index indicated
00378  * @param subIndex At subIndex indicated
00379  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
00380  * @return 
00381  * - 0 is returned upon success.
00382  * - 0xFE is returned when no sdo client to communicate with node.
00383  * - 0xFF is returned when error occurs.
00384  */
00385 UNS8 readNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType);
00386 
00387 /** 
00388  * @ingroup sdo
00389  * @brief Used to send a SDO request frame to read in a distant node dictionnary.
00390  * @details The function Callback which must be defined in the user code is called at the
00391  * end of the exchange. (on succes or abort).
00392  * @param *d Pointer on a CAN object data structure
00393  * @param nodeId Node Id of the slave
00394  * @param index At index indicated
00395  * @param subIndex At subIndex indicated
00396  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
00397  * @param Callback Callback function
00398  * @return 
00399  * - 0 is returned upon success.
00400  * - 0xFE is returned when no sdo client to communicate with node.
00401  * - 0xFF is returned when error occurs.
00402  */
00403 UNS8 readNetworkDictCallback (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
00404 
00405 /** 
00406  * @ingroup sdo
00407  * @brief Used to send a SDO request frame to read in a distant node dictionnary.
00408  * @details The function Callback which must be defined in the user code is called at the
00409  * end of the exchange. (on succes or abort). First free SDO client parameter is
00410  * automatically initialized for specific node if not already defined.
00411  * @param *d Pointer on a CAN object data structure
00412  * @param nodeId Node Id of the slave
00413  * @param index At index indicated
00414  * @param subIndex At subIndex indicated
00415  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
00416  * @param Callback Callback function
00417  * @return 
00418  * - 0 is returned upon success.
00419  * - 0xFF is returned when error occurs.
00420  */
00421 UNS8 readNetworkDictCallbackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
00422 
00423 /** 
00424  * @ingroup sdo
00425  * @brief Use this function after calling readNetworkDict to get the result.
00426  * 
00427  * @param *d Pointer to a CAN object data structure
00428  * @param nodeId Node Id of the slave
00429  * @param *data Pointer to the datas
00430  * @param *size Pointer to the size
00431  * @param *abortCode Pointer to the abortcode. (0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
00432  * 
00433  * 
00434  * @return
00435  *           - SDO_FINISHED             // datas are available
00436  *           - SDO_ABORTED_RCV          // Transfert failed (abort SDO received)
00437  *           - SDO_ABORTED_INTERNAL     // Transfert failed (internal abort)
00438  *           - SDO_UPLOAD_IN_PROGRESS   // Datas are not yet available
00439  *           - SDO_DOWNLOAD_IN_PROGRESS // Download is in progress
00440  * \n\n
00441  * example :
00442  * @code
00443  * UNS32 data;
00444  * UNS8 size;
00445  * readNetworkDict(0, 0x05, 0x1016, 1, 0) // get the data index 1016 subindex 1 of node 5
00446  * while (getReadResultNetworkDict (0, 0x05, &data, &size) == SDO_UPLOAD_IN_PROGRESS);
00447  * @endcode
00448 */
00449 UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data, UNS32 *size, UNS32 * abortCode);
00450 
00451 /**
00452  * @ingroup sdo
00453  * @brief Use this function after calling writeNetworkDict function to get the result of the write.
00454  * @details It is mandatory to call this function because it is releasing the line used for the transfer.
00455  * @param *d Pointer to a CAN object data structure
00456  * @param nodeId Node Id of the slave
00457  * @param *abortCode Pointer to the abortcode
00458  * - 0 = not available. 
00459  * - SDO abort code (received if return SDO_ABORTED_RCV)
00460  * 
00461  * @return : 
00462  *           - SDO_FINISHED             // datas are available
00463  *           - SDO_ABORTED_RCV          // Transfert failed (abort SDO received)
00464  *           - SDO_ABORTED_INTERNAL     // Transfert failed (Internal abort)
00465  *           - SDO_DOWNLOAD_IN_PROGRESS // Datas are not yet available
00466  *           - SDO_UPLOAD_IN_PROGRESS   // Upload in progress
00467  * \n\n
00468  * example :
00469  * @code
00470  * UNS32 data = 0x50;
00471  * UNS8 size;
00472  * UNS32 abortCode;
00473  * writeNetworkDict(0, 0x05, 0x1016, 1, size, &data) // write the data index 1016 subindex 1 of node 5
00474  * while (getWriteResultNetworkDict (0, 0x05, &abortCode) == SDO_DOWNLOAD_IN_PROGRESS);
00475  * @endcode
00476 */
00477 UNS8 getWriteResultNetworkDict (CO_Data* d, UNS8 nodeId, UNS32 * abortCode);
00478 
00479 #endif