include/sdo.h
changeset 561 f9be4262c68d
parent 539 187058b4a4b8
child 636 033fe6f1ec3c
equal deleted inserted replaced
560:0bb927393dd0 561:f9be4262c68d
   186 /** 
   186 /** 
   187  * @brief Search for an unused line in the transfers array
   187  * @brief Search for an unused line in the transfers array
   188  * to store a new SDO.
   188  * to store a new SDO.
   189  * ie a line which value of the field "state" is "SDO_RESET"
   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
   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
   191  * @param *d Pointer on a CAN object data structure
   193  * @param whoami Create the line for a SDO_SERVER or SDO_CLIENT.
   192  * @param whoami Create the line for a SDO_SERVER or SDO_CLIENT.
   194  * @param *line Pointer on a SDO line 
   193  * @param *line Pointer on a SDO line 
   195  * @return 0xFF if all the lines are on use. Else, return 0.
   194  * @return 0xFF if all the lines are on use. Else, return 0.
   196  */
   195  */
   197 UNS8 getSDOfreeLine (CO_Data* d, UNS8 whoami, UNS8 *line);
   196 UNS8 getSDOfreeLine (CO_Data* d, UNS8 whoami, UNS8 *line);
   198 
   197 
   199 /** 
   198 /** 
   200  * @brief Search for the line, in the transfers array, which contains the
   199  * @brief Search for the line, in the transfers array, which contains the
   201  * beginning of the reception of a fragmented SDO
   200  * beginning of the reception of a fragmented SDO
   202  * bus_id is hardware dependant
       
   203  * @param *d Pointer on a CAN object data structure
   201  * @param *d Pointer on a CAN object data structure
   204  * @param nodeId correspond to the message node-id
   202  * @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
   203  * @param whoami takes 2 values : look for a line opened as SDO_CLIENT or SDO_SERVER
   206  * @param *line Pointer on a SDO line 
   204  * @param *line Pointer on a SDO line 
   207  * @return 0xFF if error.  Else, return 0
   205  * @return 0xFF if error.  Else, return 0
   216  */
   214  */
   217 UNS8 closeSDOtransfer (CO_Data* d, UNS8 nodeId, UNS8 whoami);
   215 UNS8 closeSDOtransfer (CO_Data* d, UNS8 nodeId, UNS8 whoami);
   218 
   216 
   219 /** 
   217 /** 
   220  * @brief Bytes in the line structure which must be transmited (or received)
   218  * @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
   219  * @param *d Pointer on a CAN object data structure
   223  * @param line SDO line 
   220  * @param line SDO line 
   224  * @param *nbBytes Pointer on nbBytes
   221  * @param *nbBytes Pointer on nbBytes
   225  * @return 0.
   222  * @return 0.
   226  */
   223  */
   227 UNS8 getSDOlineRestBytes (CO_Data* d, UNS8 line, UNS32 * nbBytes);
   224 UNS8 getSDOlineRestBytes (CO_Data* d, UNS8 line, UNS32 * nbBytes);
   228 
   225 
   229 /** 
   226 /** 
   230  * @brief Store in the line structure the nb of bytes which must be transmited (or received)
   227  * @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
   228  * @param *d Pointer on a CAN object data structure
   233  * @param line SDO line 
   229  * @param line SDO line 
   234  * @param nbBytes
   230  * @param nbBytes
   235  * @return 0 if success, 0xFF if error.
   231  * @return 0 if success, 0xFF if error.
   236  */
   232  */
   237 UNS8 setSDOlineRestBytes (CO_Data* d, UNS8 line, UNS32 nbBytes);
   233 UNS8 setSDOlineRestBytes (CO_Data* d, UNS8 line, UNS32 nbBytes);
   238 
   234 
   239 /**
   235 /**
   240  * @brief Transmit a SDO frame on the bus bus_id
   236  * @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
   237  * @param *d Pointer on a CAN object data structure
   243  * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER
   238  * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER
   244  * @param sdo SDO Structure which contains the sdo to transmit
   239  * @param sdo SDO Structure which contains the sdo to transmit
   245  * @return canSend(bus_id,&m) or 0xFF if error.
   240  * @return canSend(bus_id,&m) or 0xFF if error.
   246  */
   241  */
   262  */
   257  */
   263 UNS8 sendSDOabort (CO_Data* d, UNS8 whoami, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS32 abortCode);
   258 UNS8 sendSDOabort (CO_Data* d, UNS8 whoami, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS32 abortCode);
   264 
   259 
   265 /** 
   260 /** 
   266  * @brief Treat a SDO frame reception
   261  * @brief Treat a SDO frame reception
   267  * bus_id is hardware dependant
       
   268  * call the function sendSDO
   262  * call the function sendSDO
   269  * @param *d Pointer on a CAN object data structure
   263  * @param *d Pointer on a CAN object data structure
   270  * @param *m Pointer on a CAN message structure 
   264  * @param *m Pointer on a CAN message structure 
   271  * @return code : 
   265  * @return code : 
   272  * 		   - 0xFF if error
   266  * 		   - 0xFF if error
   275  */
   269  */
   276 UNS8 proceedSDO (CO_Data* d, Message *m);
   270 UNS8 proceedSDO (CO_Data* d, Message *m);
   277 
   271 
   278 /** 
   272 /** 
   279  * @ingroup sdo
   273  * @ingroup sdo
   280  * @brief Used by the application to send a SDO request frame to write the data *data
   274  * @brief Used to send a SDO request frame to write the data at the index and subIndex indicated
   281  * at the index and subIndex indicated
   275  * @param *d Pointer to a CAN object data structure
   282  * bus_id is hardware dependant
   276  * @param nodeId Node Id of the slave
   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
   277  * @param index At index indicated
   286  * @param subIndex At subIndex indicated
   278  * @param subIndex At subIndex indicated
   287  * @param count number of bytes to write in the dictionnary.
   279  * @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.
   280  * @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
   281  * @param *data Pointer to data
   290  * @return 0xFF if error, else return 0
   282  * @return 
       
   283  * - 0 is returned upon success.
       
   284  * - 0xFE is returned when no sdo client to communicate with node.
       
   285  * - 0xFF is returned when error occurs.
   291  */
   286  */
   292 UNS8 writeNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index,
   287 UNS8 writeNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index,
   293 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data);
   288 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data);
   294 
   289 
   295 /** 
   290 /** 
   296  * @ingroup sdo
   291  * @ingroup sdo
   297  * @brief Used to send a SDO request frame to write in a distant node dictionnary.
   292  * @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
   293  * @details The function Callback which must be defined in the user code is called at the
   299  * end of the exchange. (on succes or abort).
   294  * end of the exchange. (on succes or abort).
   300  * @param *d Pointer on a CAN object data structure
   295  * @param *d Pointer to a CAN object data structure
   301  * @param nodeId In the dictionary of the slave whose node_id is nodeId
   296  * @param nodeId Node Id of the slave
   302  * @param index At index indicated
   297  * @param index At index indicated
   303  * @param subIndex At subIndex indicated
   298  * @param subIndex At subIndex indicated
   304  * @param count number of bytes to write in the dictionnary.
   299  * @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.
   300  * @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
   301  * @param *data Pointer to data
   307  * @param Callback Callback function
   302  * @param Callback Callback function
   308  * @return 0xFF if error, else return 0
   303  * @return 
       
   304  * - 0 is returned upon success.
       
   305  * - 0xFE is returned when no sdo client to communicate with node.
       
   306  * - 0xFF is returned when error occurs.
   309  */
   307  */
   310 UNS8 writeNetworkDictCallBack (CO_Data* d, UNS8 nodeId, UNS16 index,
   308 UNS8 writeNetworkDictCallBack (CO_Data* d, UNS8 nodeId, UNS16 index,
   311 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback);
   309 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback);
   312 
   310 
   313 /**
   311 /**
   314  * @ingroup sdo 
   312  * @ingroup sdo 
   315  * @brief Used to send a SDO request frame to write in a distant node dictionnary.
   313  * @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
   314  * @details 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
   315  * end of the exchange. (on succes or abort). First free SDO client parameter is
   318  * automatically initialized for specific node if not already defined.
   316  * automatically initialized for specific node if not already defined.
   319  * @param *d Pointer on a CAN object data structure
   317  * @param *d Pointer to a CAN object data structure
   320  * @param nodeId In the dictionary of the slave whose node_id is nodeId
   318  * @param nodeId Node Id of the slave
   321  * @param index At index indicated
   319  * @param index At index indicated
   322  * @param subIndex At subIndex indicated
   320  * @param subIndex At subIndex indicated
   323  * @param count number of bytes to write in the dictionnary.
   321  * @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.
   322  * @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
   323  * @param *data Pointer to data
   326  * @param Callback Callback function
   324  * @param Callback Callback function
   327  * @param endianize When not 0, data is endianized into network byte order
   325  * @param endianize When not 0, data is endianized into network byte order
   328  *                  when 0, data is not endianized and copied in machine native
   326  *                  when 0, data is not endianized and copied in machine native
   329  *                  endianness
   327  *                  endianness
   330  * @return 0xFF if error, else return 0
   328  * @return 
       
   329  * - 0 is returned upon success.
       
   330  * - 0xFF is returned when error occurs.
   331  */
   331  */
   332 UNS8 writeNetworkDictCallBackAI (CO_Data* d, UNS8 nodeId, UNS16 index,
   332 UNS8 writeNetworkDictCallBackAI (CO_Data* d, UNS8 nodeId, UNS16 index,
   333 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback, UNS8 endianize);
   333 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback, UNS8 endianize);
   334 
   334 
   335 /**
   335 /**
   336  * @ingroup sdo 
   336  * @ingroup sdo 
   337  * @brief Used by the application to send a SDO request frame to read
   337  * @brief Used to send a SDO request frame to read.
   338  * @param *d Pointer on a CAN object data structure
   338  * @param *d Pointer to a CAN object data structure
   339  * @param nodeId In the dictionary of the slave whose node_id is nodeId
   339  * @param nodeId Node Id of the slave
   340  * @param index At index indicated
   340  * @param index At index indicated
   341  * @param subIndex At subIndex 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
   342  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
   343  * @return 0xFF if error, else return 0
   343  * @return 
       
   344  * - 0 is returned upon success.
       
   345  * - 0xFE is returned when no sdo client to communicate with node.
       
   346  * - 0xFF is returned when error occurs.
   344  */
   347  */
   345 UNS8 readNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType);
   348 UNS8 readNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType);
   346 
   349 
   347 /** 
   350 /** 
   348  * @ingroup sdo
   351  * @ingroup sdo
   349  * @brief Used to send a SDO request frame to read in a distant node dictionnary.
   352  * @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
   353  * @details The function Callback which must be defined in the user code is called at the
   351  * end of the exchange. (on succes or abort).
   354  * end of the exchange. (on succes or abort).
   352  * @param *d Pointer on a CAN object data structure
   355  * @param *d Pointer on a CAN object data structure
   353  * @param nodeId In the dictionary of the slave whose node_id is nodeId
   356  * @param nodeId Node Id of the slave
   354  * @param index At index indicated
   357  * @param index At index indicated
   355  * @param subIndex At subIndex indicated
   358  * @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.
   359  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
   357  * @param Callback Callback function
   360  * @param Callback Callback function
   358  * @return 0xFF if error, else return 0
   361  * @return 
       
   362  * - 0 is returned upon success.
       
   363  * - 0xFE is returned when no sdo client to communicate with node.
       
   364  * - 0xFF is returned when error occurs.
   359  */
   365  */
   360 UNS8 readNetworkDictCallback (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
   366 UNS8 readNetworkDictCallback (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
   361 
   367 
   362 /** 
   368 /** 
   363  * @ingroup sdo
   369  * @ingroup sdo
   364  * @brief Used to send a SDO request frame to read in a distant node dictionnary.
   370  * @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
   371  * @details 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
   372  * end of the exchange. (on succes or abort). First free SDO client parameter is
   367  * automatically initialized for specific node if not already defined.
   373  * automatically initialized for specific node if not already defined.
   368  * @param *d Pointer on a CAN object data structure
   374  * @param *d Pointer on a CAN object data structure
   369  * @param nodeId In the dictionary of the slave whose node_id is nodeId
   375  * @param nodeId Node Id of the slave
   370  * @param index At index indicated
   376  * @param index At index indicated
   371  * @param subIndex At subIndex indicated
   377  * @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.
   378  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
   373  * @param Callback Callback function
   379  * @param Callback Callback function
   374  * @return 0xFF if error, else return 0
   380  * @return 
       
   381  * - 0 is returned upon success.
       
   382  * - 0xFF is returned when error occurs.
   375  */
   383  */
   376 UNS8 readNetworkDictCallbackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
   384 UNS8 readNetworkDictCallbackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
   377 
   385 
   378 /** 
   386 /** 
   379  * @ingroup sdo
   387  * @ingroup sdo
   380  * @brief Use this function after a readNetworkDict to get the result.
   388  * @brief Use this function after calling readNetworkDict to get the result.
   381  * @param *d Pointer on a CAN object data structure
   389  * 
   382  * @param nodeId In the dictionary of the slave whose node_id is nodeId
   390  * @param *d Pointer to a CAN object data structure
   383  * @param *data Pointer on data
   391  * @param nodeId Node Id of the slave
   384  * @param *size Pointer on size
   392  * @param *data Pointer to the datas
   385  * @param *abortCode Pointer on the abortcode. 0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
   393  * @param *size Pointer to the size
       
   394  * @param *abortCode Pointer to the abortcode. (0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
   386  * 
   395  * 
   387  * 
   396  * 
   388  * @return
   397  * @return
   389  *           - SDO_FINISHED             // data is available
   398  *           - SDO_FINISHED             // datas are available
   390  *           - SDO_ABORTED_RCV          // Transfert failed. (abort SDO received)
   399  *           - SDO_ABORTED_RCV          // Transfert failed (abort SDO received)
   391  *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.
   400  *           - SDO_ABORTED_INTERNAL     // Transfert failed (internal abort)
   392  *           - SDO_UPLOAD_IN_PROGRESS   // Data not yet available
   401  *           - SDO_UPLOAD_IN_PROGRESS   // Datas are not yet available
   393  *           - SDO_DOWNLOAD_IN_PROGRESS // Should not arrive !
   402  *           - SDO_DOWNLOAD_IN_PROGRESS // Download is in progress
       
   403  * \n\n
       
   404  * example :
   394  * @code
   405  * @code
   395  * example :
       
   396  * UNS32 data;
   406  * UNS32 data;
   397  * UNS8 size;
   407  * UNS8 size;
   398  * readNetworkDict(0, 0x05, 0x1016, 1, 0) // get the data index 1016 subindex 1 of node 5
   408  * 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);
   409  * while (getReadResultNetworkDict (0, 0x05, &data, &size) == SDO_UPLOAD_IN_PROGRESS);
   400  * @endcode
   410  * @endcode
   401 */
   411 */
   402 UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data, UNS32 *size, UNS32 * abortCode);
   412 UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data, UNS32 *size, UNS32 * abortCode);
   403 
   413 
   404 /**
   414 /**
   405  * @brief Use this function after a writeNetworkDict to get the result of the write
   415  * @ingroup sdo
   406  * It is mandatory to call this function because it is releasing the line used for the transfer.
   416  * @brief Use this function after calling writeNetworkDict function to get the result of the write.
   407  * @param *d Pointer on a CAN object data structure
   417  * @details It is mandatory to call this function because it is releasing the line used for the transfer.
   408  * @param nodeId In the dictionary of the slave whose node_id is nodeId
   418  * @param *d Pointer to a CAN object data structure
   409  * @param *abortCode Pointer on the abortcode. 0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
   419  * @param nodeId Node Id of the slave
       
   420  * @param *abortCode Pointer to the abortcode
       
   421  * - 0 = not available. 
       
   422  * - SDO abort code (received if return SDO_ABORTED_RCV)
   410  * 
   423  * 
   411  * @return : 
   424  * @return : 
   412  *           - SDO_FINISHED             // data is available
   425  *           - SDO_FINISHED             // datas are available
   413  *           - SDO_ABORTED_RCV          // Transfert failed. (abort SDO received)
   426  *           - SDO_ABORTED_RCV          // Transfert failed (abort SDO received)
   414  *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.
   427  *           - SDO_ABORTED_INTERNAL     // Transfert failed (Internal abort)
   415  *           - SDO_DOWNLOAD_IN_PROGRESS // Data not yet available
   428  *           - SDO_DOWNLOAD_IN_PROGRESS // Datas are not yet available
   416  *           - SDO_UPLOAD_IN_PROGRESS   // Should not arrive !
   429  *           - SDO_UPLOAD_IN_PROGRESS   // Upload in progress
   417  * 
   430  * \n\n
       
   431  * example :
   418  * @code
   432  * @code
   419  * example :
       
   420  * UNS32 data = 0x50;
   433  * UNS32 data = 0x50;
   421  * UNS8 size;
   434  * UNS8 size;
   422  * UNS32 abortCode;
   435  * UNS32 abortCode;
   423  * writeNetworkDict(0, 0x05, 0x1016, 1, size, &data) // write the data index 1016 subindex 1 of node 5
   436  * 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);
   437  * while (getWriteResultNetworkDict (0, 0x05, &abortCode) == SDO_DOWNLOAD_IN_PROGRESS);
   425  * @endcode
   438  * @endcode
   426 */
   439 */
   427 UNS8 getWriteResultNetworkDict (CO_Data* d, UNS8 nodeId, UNS32 * abortCode);
   440 UNS8 getWriteResultNetworkDict (CO_Data* d, UNS8 nodeId, UNS32 * abortCode);
   428 
   441 
   429 #endif
   442 #endif