Lely core libraries 2.3.4
csdo.h File Reference

This header file is part of the CANopen library; it contains the Client-SDO declarations. More...

#include <lely/can/net.h>
#include <lely/co/sdo.h>
Include dependency graph for csdo.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef void co_csdo_dn_con_t(co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, co_unsigned32_t ac, void *data)
 The type of a CANopen Client-SDO download confirmation callback function, invoked when a download request completes (with success or failure). More...
 
typedef void co_csdo_up_con_t(co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, co_unsigned32_t ac, const void *ptr, size_t n, void *data)
 The type of a CANopen Client-SDO upload confirmation callback function, invoked when an upload request completes (with success or failure). More...
 
typedef void co_csdo_ind_t(const co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, size_t size, size_t nbyte, void *data)
 The type of a CANopen Client-SDO request progress indication function, used to notify the user of the progress of the current upload/download request. More...
 

Functions

int co_dev_dn_req (co_dev_t *dev, co_unsigned16_t idx, co_unsigned8_t subidx, const void *ptr, size_t n, co_csdo_dn_con_t *con, void *data)
 Submits a download request to a local device. More...
 
int co_dev_dn_val_req (co_dev_t *dev, co_unsigned16_t idx, co_unsigned8_t subidx, co_unsigned16_t type, const void *val, co_csdo_dn_con_t *con, void *data)
 Submits a download request to a local device. More...
 
int co_dev_dn_dcf_req (co_dev_t *dev, const uint_least8_t *begin, const uint_least8_t *end, co_csdo_dn_con_t *con, void *data)
 Submits a series of download requests to a local device. More...
 
int co_dev_up_req (const co_dev_t *dev, co_unsigned16_t idx, co_unsigned8_t subidx, co_csdo_up_con_t *con, void *data)
 Submits an upload request to a local device. More...
 
co_csdo_tco_csdo_create (can_net_t *net, co_dev_t *dev, co_unsigned8_t num)
 Creates a new CANopen Client-SDO service. More...
 
void co_csdo_destroy (co_csdo_t *sdo)
 Destroys a CANopen Client-SDO service. More...
 
int co_csdo_start (co_csdo_t *sdo)
 Starts a Client-SDO service. More...
 
void co_csdo_stop (co_csdo_t *sdo)
 Stops a Client-SDO service. More...
 
int co_csdo_is_stopped (const co_csdo_t *sdo)
 Retuns 1 if the specified Client-SDO service is stopped, and 0 if not. More...
 
can_net_tco_csdo_get_net (const co_csdo_t *sdo)
 Returns a pointer to the CAN network of a Client-SDO.
 
co_dev_tco_csdo_get_dev (const co_csdo_t *sdo)
 Returns a pointer to the CANopen device of a Client-SDO.
 
co_unsigned8_t co_csdo_get_num (const co_csdo_t *sdo)
 Returns the SDO number of a Client-SDO.
 
const struct co_sdo_parco_csdo_get_par (const co_csdo_t *sdo)
 Returns a pointer to the SDO parameter record of a Client-SDO.
 
int co_csdo_get_timeout (const co_csdo_t *sdo)
 Returns the timeout (in milliseconds) of a Client-SDO. More...
 
void co_csdo_set_timeout (co_csdo_t *sdo, int timeout)
 Sets the timeout of a Client-SDO. More...
 
void co_csdo_get_dn_ind (const co_csdo_t *sdo, co_csdo_ind_t **pind, void **pdata)
 Retrieves the indication function used to notify the user of the progress of the current SDO download request. More...
 
void co_csdo_set_dn_ind (co_csdo_t *sdo, co_csdo_ind_t *ind, void *data)
 Sets the indication function used to notify the user of the progress of the current SDO download request. More...
 
void co_csdo_get_up_ind (const co_csdo_t *sdo, co_csdo_ind_t **pind, void **pdata)
 Retrieves the indication function used to notify the user of the progress of the current SDO upload request. More...
 
void co_csdo_set_up_ind (co_csdo_t *sdo, co_csdo_ind_t *ind, void *data)
 Sets the indication function used to notify the user of the progress of the current SDO upload request. More...
 
int co_csdo_is_valid (const co_csdo_t *sdo)
 Returns 1 of the COB-IDs of the specified Client-SDO service are valid, and 0 if not.
 
int co_csdo_is_idle (const co_csdo_t *sdo)
 Returns 1 if the specified Client-SDO service is idle, and 0 if a transfer is ongoing.
 
void co_csdo_abort_req (co_csdo_t *sdo, co_unsigned32_t ac)
 Submits an abort transfer request to a remote Server-SDO. More...
 
int co_csdo_dn_req (co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, const void *ptr, size_t n, co_csdo_dn_con_t *con, void *data)
 Submits a download request to a remote Server-SDO. More...
 
int co_csdo_dn_val_req (co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, co_unsigned16_t type, const void *val, co_csdo_dn_con_t *con, void *data)
 Submits a download request to a remote Server-SDO. More...
 
int co_csdo_dn_dcf_req (co_csdo_t *sdo, const uint_least8_t *begin, const uint_least8_t *end, co_csdo_dn_con_t *con, void *data)
 Submits a series of download requests to a remote Server-SDO. More...
 
int co_csdo_up_req (co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, co_csdo_up_con_t *con, void *data)
 Submits an upload request to a remote Server-SDO. More...
 
int co_csdo_blk_dn_req (co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, const void *ptr, size_t n, co_csdo_dn_con_t *con, void *data)
 Submits a block download request to a remote Server-SDO. More...
 
int co_csdo_blk_dn_val_req (co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, co_unsigned16_t type, const void *val, co_csdo_dn_con_t *con, void *data)
 Submits a block download request to a remote Server-SDO. More...
 
int co_csdo_blk_up_req (co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, co_unsigned8_t pst, co_csdo_up_con_t *con, void *data)
 Submits a block upload request to a remote Server-SDO. More...
 

Detailed Description

This header file is part of the CANopen library; it contains the Client-SDO declarations.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file csdo.h.

Typedef Documentation

◆ co_csdo_dn_con_t

typedef void co_csdo_dn_con_t(co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, co_unsigned32_t ac, void *data)

The type of a CANopen Client-SDO download confirmation callback function, invoked when a download request completes (with success or failure).

Parameters
sdoa pointer to a Client-SDO service (NULL in case of a local device).
idxthe object index.
subidxthe object sub-index.
acthe abort code (0 on success).
dataa pointer to user-specified data.

Definition at line 43 of file csdo.h.

◆ co_csdo_up_con_t

typedef void co_csdo_up_con_t(co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, co_unsigned32_t ac, const void *ptr, size_t n, void *data)

The type of a CANopen Client-SDO upload confirmation callback function, invoked when an upload request completes (with success or failure).

Parameters
sdoa pointer to a Client-SDO service (NULL in case of a local device).
idxthe object index.
subidxthe object sub-index.
acthe abort code (0 on success).
ptra pointer to the uploaded bytes.
nthe number of bytes at ptr.
dataa pointer to user-specified data.

Definition at line 59 of file csdo.h.

◆ co_csdo_ind_t

typedef void co_csdo_ind_t(const co_csdo_t *sdo, co_unsigned16_t idx, co_unsigned8_t subidx, size_t size, size_t nbyte, void *data)

The type of a CANopen Client-SDO request progress indication function, used to notify the user of the progress of the current upload/download request.

The indication function is invoked after the size of the value has been sent/received, and again after each block (of at most 127 segments) is sent/received. The last invocation occurs before the upload/download confirmation. No notification is generated for expedited transfers.

Parameters
sdoa pointer to a Client-SDO service.
idxthe object index.
subidxthe object sub-index.
sizeThe total size (in bytes) of the value being uploaded/downloaded.
nbyteThe number of bytes already uploaded/downloaded.
dataa pointer to user-specified data.

Definition at line 79 of file csdo.h.

Function Documentation

◆ co_dev_dn_req()

int co_dev_dn_req ( co_dev_t dev,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
const void *  ptr,
size_t  n,
co_csdo_dn_con_t con,
void *  data 
)

Submits a download request to a local device.

This is equivalent to a write operation into an dictionary.

Parameters
deva pointer to CANopen device.
idxthe remote object index.
subidxthe remote object sub-index.
ptra pointer to the bytes to be downloaded.
nthe number of bytes at ptr.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 664 of file csdo.c.

◆ co_dev_dn_val_req()

int co_dev_dn_val_req ( co_dev_t dev,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
co_unsigned16_t  type,
const void *  val,
co_csdo_dn_con_t con,
void *  data 
)

Submits a download request to a local device.

This is equivalent to a write operation into an object dictionary.

Parameters
deva pointer to CANopen device.
idxthe remote object index.
subidxthe remote object sub-index.
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be written. In case of string or domains, this MUST be the address of pointer.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 701 of file csdo.c.

◆ co_dev_dn_dcf_req()

int co_dev_dn_dcf_req ( co_dev_t dev,
const uint_least8_t *  begin,
const uint_least8_t *  end,
co_csdo_dn_con_t con,
void *  data 
)

Submits a series of download requests to a local device.

This function calls co_dev_dn_req() for each entry in the specified concise DCF.

Parameters
deva pointer to CANopen device.
begina pointer the the first byte in a concise DCF (see object 1F22 in CiA 302-3 version 4.1.0).
enda pointer to one past the last byte in the concise DCF. At most end - begin bytes are read.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 739 of file csdo.c.

◆ co_dev_up_req()

int co_dev_up_req ( const co_dev_t dev,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
co_csdo_up_con_t con,
void *  data 
)

Submits an upload request to a local device.

This is equivalent to a read operation from an object dictionary.

Parameters
deva pointer to CANopen device.
idxthe remote object index.
subidxthe remote object sub-index.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 812 of file csdo.c.

◆ co_csdo_create()

co_csdo_t * co_csdo_create ( can_net_t net,
co_dev_t dev,
co_unsigned8_t  num 
)

Creates a new CANopen Client-SDO service.

The service is started as if by co_csdo_start().

Parameters
neta pointer to a CAN network.
deva pointer to a CANopen device describing the client (can be NULL).
numthe SDO number (in the range [1..128]). The SDO parameter record MUST exist in the object dictionary of dev. However, if dev is NULL, num is interpreted as a node-ID (in the range [1..127]) and the default SDO parameters are used.
Returns
a pointer to a new Client-SDO service, or NULL on error. In the latter case, the error number can be obtained with get_errc().
See also
co_csdo_destroy()

Definition at line 997 of file csdo.c.

◆ co_csdo_destroy()

void co_csdo_destroy ( co_csdo_t sdo)

Destroys a CANopen Client-SDO service.

See also
co_csdo_create()

Definition at line 1024 of file csdo.c.

◆ co_csdo_start()

int co_csdo_start ( co_csdo_t sdo)

Starts a Client-SDO service.

Postcondition
on success, co_csdo_is_stopped() returns 0.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_csdo_stop()

Definition at line 1034 of file csdo.c.

◆ co_csdo_stop()

void co_csdo_stop ( co_csdo_t sdo)

Stops a Client-SDO service.

Any ongoing request is aborted.

Postcondition
co_csdo_is_stopped() returns 1.
See also
co_csdo_start()

Definition at line 1069 of file csdo.c.

◆ co_csdo_is_stopped()

int co_csdo_is_stopped ( const co_csdo_t sdo)

Retuns 1 if the specified Client-SDO service is stopped, and 0 if not.

See also
co_csdo_start, co_csdo_stop()

Definition at line 1094 of file csdo.c.

◆ co_csdo_get_timeout()

int co_csdo_get_timeout ( const co_csdo_t sdo)

Returns the timeout (in milliseconds) of a Client-SDO.

A return value of 0 (the default) means no timeout is being used.

See also
co_csdo_set_timeout()

Definition at line 1134 of file csdo.c.

◆ co_csdo_set_timeout()

void co_csdo_set_timeout ( co_csdo_t sdo,
int  timeout 
)

Sets the timeout of a Client-SDO.

If the timeout expires before receiving a response from a server, the client aborts the transfer.

Parameters
sdoa pointer to a Client-SDO service.
timeoutthe timeout (in milliseconds). A value of 0 (the default) disables the timeout.
See also
co_csdo_get_timeout()

Definition at line 1142 of file csdo.c.

◆ co_csdo_get_dn_ind()

void co_csdo_get_dn_ind ( const co_csdo_t sdo,
co_csdo_ind_t **  pind,
void **  pdata 
)

Retrieves the indication function used to notify the user of the progress of the current SDO download request.

Parameters
sdoa pointer to a Client-SDO service.
pindthe address at which to store a pointer to the indication function (can be NULL).
pdatathe address at which to store a pointer to user-specified data (can be NULL).
See also
co_csdo_set_dn_ind()

Definition at line 1153 of file csdo.c.

◆ co_csdo_set_dn_ind()

void co_csdo_set_dn_ind ( co_csdo_t sdo,
co_csdo_ind_t ind,
void *  data 
)

Sets the indication function used to notify the user of the progress of the current SDO download request.

Parameters
sdoa pointer to a Client-SDO service.
inda pointer to the function to be invoked.
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to ind.
See also
co_csdo_get_dn_ind()

Definition at line 1164 of file csdo.c.

◆ co_csdo_get_up_ind()

void co_csdo_get_up_ind ( const co_csdo_t sdo,
co_csdo_ind_t **  pind,
void **  pdata 
)

Retrieves the indication function used to notify the user of the progress of the current SDO upload request.

Parameters
sdoa pointer to a Client-SDO service.
pindthe address at which to store a pointer to the indication function (can be NULL).
pdatathe address at which to store a pointer to user-specified data (can be NULL).
See also
co_csdo_set_up_ind()

Definition at line 1173 of file csdo.c.

◆ co_csdo_set_up_ind()

void co_csdo_set_up_ind ( co_csdo_t sdo,
co_csdo_ind_t ind,
void *  data 
)

Sets the indication function used to notify the user of the progress of the current SDO upload request.

Parameters
sdoa pointer to a Client-SDO service.
inda pointer to the function to be invoked.
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to ind.
See also
co_csdo_get_up_ind()

Definition at line 1184 of file csdo.c.

◆ co_csdo_abort_req()

void co_csdo_abort_req ( co_csdo_t sdo,
co_unsigned32_t  ac 
)

Submits an abort transfer request to a remote Server-SDO.

This function has no effect if the Client-SDO service is idle (see co_csdo_is_idle()).

Parameters
sdoa pointer to a Client-SDO service.
acthe abort code.

Definition at line 1211 of file csdo.c.

◆ co_csdo_dn_req()

int co_csdo_dn_req ( co_csdo_t sdo,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
const void *  ptr,
size_t  n,
co_csdo_dn_con_t con,
void *  data 
)

Submits a download request to a remote Server-SDO.

This requests the server to download the value and is equivalent to a write operation into a remote object dictionary. Note that the request will fail if another transfer is in progress (see co_csdo_is_idle()).

Parameters
sdoa pointer to a Client-SDO service.
idxthe remote object index.
subidxthe remote object sub-index.
ptra pointer to the bytes to be downloaded. It is the responsibility of the user to ensure that the buffer remains valid until the operation completes.
nthe number of bytes at ptr.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 1219 of file csdo.c.

◆ co_csdo_dn_val_req()

int co_csdo_dn_val_req ( co_csdo_t sdo,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
co_unsigned16_t  type,
const void *  val,
co_csdo_dn_con_t con,
void *  data 
)

Submits a download request to a remote Server-SDO.

This requests the server to download the value and is equivalent to a write operation into a remote object dictionary. Note that the request will fail if another transfer is in progress (see co_csdo_is_idle()).

Parameters
sdoa pointer to a Client-SDO service.
idxthe remote object index.
subidxthe remote object sub-index.
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be written. In case of string or domains, this MUST be the address of pointer.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 1241 of file csdo.c.

◆ co_csdo_dn_dcf_req()

int co_csdo_dn_dcf_req ( co_csdo_t sdo,
const uint_least8_t *  begin,
const uint_least8_t *  end,
co_csdo_dn_con_t con,
void *  data 
)

Submits a series of download requests to a remote Server-SDO.

This function calls co_csdo_dn_req() for each entry in the specified concise DCF.

Parameters
sdoa pointer to a Client-SDO service.
begina pointer the the first byte in a concise DCF (see object 1F22 in CiA 302-3 version 4.1.0).
enda pointer to one past the last byte in the concise DCF. At most end - begin bytes are read.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 1265 of file csdo.c.

◆ co_csdo_up_req()

int co_csdo_up_req ( co_csdo_t sdo,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
co_csdo_up_con_t con,
void *  data 
)

Submits an upload request to a remote Server-SDO.

This requests the server to upload the value and is equivalent to a read operation from a remote object dictionary. Note that the request will fail if another transfer is in progress (see co_csdo_is_idle()).

Parameters
sdoa pointer to a Client-SDO service.
idxthe remote object index.
subidxthe remote object sub-index.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 1294 of file csdo.c.

◆ co_csdo_blk_dn_req()

int co_csdo_blk_dn_req ( co_csdo_t sdo,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
const void *  ptr,
size_t  n,
co_csdo_dn_con_t con,
void *  data 
)

Submits a block download request to a remote Server-SDO.

This requests the server to download the value and is equivalent to a write operation into a remote object dictionary. Note that the request will fail if another transfer is in progress (see co_csdo_is_idle()).

Parameters
sdoa pointer to a Client-SDO service.
idxthe remote object index.
subidxthe remote object sub-index.
ptra pointer to the bytes to be downloaded.
nthe number of bytes at ptr.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 1313 of file csdo.c.

◆ co_csdo_blk_dn_val_req()

int co_csdo_blk_dn_val_req ( co_csdo_t sdo,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
co_unsigned16_t  type,
const void *  val,
co_csdo_dn_con_t con,
void *  data 
)

Submits a block download request to a remote Server-SDO.

This requests the server to download the value and is equivalent to a write operation into a remote object dictionary. Note that the request will fail if another transfer is in progress (see co_csdo_is_idle()).

Parameters
sdoa pointer to a Client-SDO service.
idxthe remote object index.
subidxthe remote object sub-index.
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be written. In case of string or domains, this MUST be the address of pointer.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 1332 of file csdo.c.

◆ co_csdo_blk_up_req()

int co_csdo_blk_up_req ( co_csdo_t sdo,
co_unsigned16_t  idx,
co_unsigned8_t  subidx,
co_unsigned8_t  pst,
co_csdo_up_con_t con,
void *  data 
)

Submits a block upload request to a remote Server-SDO.

This requests the server to upload the value and is equivalent to a read operation from a remote object dictionary. Note that the request will fail if another transfer is in progress (see co_csdo_is_idle()).

Parameters
sdoa pointer to a Client-SDO service.
idxthe remote object index.
subidxthe remote object sub-index.
pstthe protocol switch threshold. If pst is non-zero, and the number of bytes to be uploaded is less than or equal to pst, the server may switch to the SDO upload protocol.
cona pointer to the confirmation function (can be NULL).
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to con.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 1356 of file csdo.c.