linear-Slide/Middleware/CANopenNode/301/CO_SDOclient.h

/**
 * CANopen Service Data Object - client protocol.
 *
 * @file        CO_SDOclient.h
 * @ingroup     CO_SDOclient
 * @author      Janez Paternoster
 * @author      Matej Severkar
 * @copyright   2020 Janez Paternoster
 *
 * This file is part of <https://github.com/CANopenNode/CANopenNode>, a CANopen Stack.
 *
 * 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.
 */

#ifndef CO_SDO_CLIENT_H
#define CO_SDO_CLIENT_H

#include "301/CO_driver.h"
#include "301/CO_ODinterface.h"
#include "301/CO_SDOserver.h"
#include "301/CO_fifo.h"

/* default configuration, see CO_config.h */
#ifndef CO_CONFIG_SDO_CLI
#define CO_CONFIG_SDO_CLI (0)
#endif

#ifndef CO_DOXYGEN
#ifndef CO_CONFIG_SDO_CLI_BUFFER_SIZE
#if ((CO_CONFIG_SDO_CLI)&CO_CONFIG_SDO_CLI_BLOCK) != 0
#define CO_CONFIG_SDO_CLI_BUFFER_SIZE 1000U
#else
#define CO_CONFIG_SDO_CLI_BUFFER_SIZE 32U
#endif
#endif
#endif

#if (((CO_CONFIG_SDO_CLI)&CO_CONFIG_SDO_CLI_ENABLE) != 0) || defined CO_DOXYGEN

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup CO_SDOclient SDO client
 * CANopen Service Data Object - client protocol.
 *
 * @ingroup CO_CANopen_301
 * @{
 * SDO client is able to access Object Dictionary variables from remote nodes. Usually there is one SDO client on
 * CANopen network, which is able to configure other CANopen nodes. It is also possible to establish individual SDO
 * client-server communication channels between devices.
 *
 * SDO client is used in CANopenNode from CO_gateway_ascii.c with default SDO CAN identifiers. There is quite advanced
 * usage in non-blocking function.
 *
 * If enabled, SDO client is initialized in CANopen.c file with @ref CO_SDOclient_init() function.
 *
 * Basic usage:
 * @code{.c}
CO_SDO_abortCode_t
read_SDO(CO_SDOclient_t* SDO_C, uint8_t nodeId, uint16_t index, uint8_t subIndex, uint8_t* buf, size_t bufSize,
         size_t* readSize) {
    CO_SDO_return_t SDO_ret;

    // setup client (this can be skipped, if remote device don't change)
    SDO_ret = CO_SDOclient_setup(SDO_C, CO_CAN_ID_SDO_CLI + nodeId, CO_CAN_ID_SDO_SRV + nodeId, nodeId);
    if (SDO_ret != CO_SDO_RT_ok_communicationEnd) {
        return CO_SDO_AB_GENERAL;
    }

    // initiate upload
    SDO_ret = CO_SDOclientUploadInitiate(SDO_C, index, subIndex, 1000, false);
    if (SDO_ret != CO_SDO_RT_ok_communicationEnd) {
        return CO_SDO_AB_GENERAL;
    }

    // upload data
    do {
        uint32_t timeDifference_us = 10000;
        CO_SDO_abortCode_t abortCode = CO_SDO_AB_NONE;

        SDO_ret = CO_SDOclientUpload(SDO_C, timeDifference_us, false, &abortCode, NULL, NULL, NULL);
        if (SDO_ret < 0) {
            return abortCode;
        }

        sleep_us(timeDifference_us);
    } while (SDO_ret > 0);

    // copy data to the user buffer (for long data function must be called several times inside the loop)
    *readSize = CO_SDOclientUploadBufRead(SDO_C, buf, bufSize);

    return CO_SDO_AB_NONE;
}

CO_SDO_abortCode_t
write_SDO(CO_SDOclient_t* SDO_C, uint8_t nodeId, uint16_t index, uint8_t subIndex, uint8_t* data, size_t dataSize) {
    CO_SDO_return_t SDO_ret;
    bool_t bufferPartial = false;

    // setup client (this can be skipped, if remote device is the same)
    SDO_ret = CO_SDOclient_setup(SDO_C, CO_CAN_ID_SDO_CLI + nodeId, CO_CAN_ID_SDO_SRV + nodeId, nodeId);
    if (SDO_ret != CO_SDO_RT_ok_communicationEnd) {
        return -1
    }

    // initiate download
    SDO_ret = CO_SDOclientDownloadInitiate(SDO_C, index, subIndex, dataSize, 1000, false);
    if (SDO_ret != CO_SDO_RT_ok_communicationEnd) {
        return -1
    }

    // fill data
    size_t nWritten = CO_SDOclientDownloadBufWrite(SDO_C, data, dataSize);
    if (nWritten < dataSize) {
        bufferPartial = true;
        // If SDO Fifo buffer is too small, data can be refilled in the loop.
    }

    // download data
    do {
        uint32_t timeDifference_us = 10000;
        CO_SDO_abortCode_t abortCode = CO_SDO_AB_NONE;

        SDO_ret = CO_SDOclientDownload(SDO_C, timeDifference_us, false, bufferPartial, &abortCode, NULL, NULL);
        if (SDO_ret < 0) {
            return abortCode;
        }

        sleep_us(timeDifference_us);
    } while (SDO_ret > 0);

    return CO_SDO_AB_NONE;
}
 * @endcode
 *
 * @see @ref CO_SDOserver
 */

/**
 * SDO client object
 */
typedef struct {
#if (((CO_CONFIG_SDO_CLI)&CO_CONFIG_SDO_CLI_LOCAL) != 0) || defined CO_DOXYGEN
    OD_t* OD;       /**< From CO_SDOclient_init() */
    uint8_t nodeId; /**< From CO_SDOclient_init() */
    OD_IO_t OD_IO;  /**< Object dictionary interface for locally transferred object */
#endif
    CO_CANmodule_t* CANdevRx; /**< From CO_SDOclient_init() */
    uint16_t CANdevRxIdx;     /**< From CO_SDOclient_init() */
    CO_CANmodule_t* CANdevTx; /**< From CO_SDOclient_init() */
    uint16_t CANdevTxIdx;     /**< From CO_SDOclient_init() */
    CO_CANtx_t* CANtxBuff;    /**< CAN transmit buffer inside CANdevTx for CAN tx message */
#if (((CO_CONFIG_SDO_CLI)&CO_CONFIG_FLAG_OD_DYNAMIC) != 0) || defined CO_DOXYGEN

    uint32_t COB_IDClientToServer;    /**< Copy of CANopen COB_ID Client -> Server, meaning of the specific bits:
                                           - Bit 0...10: 11-bit CAN identifier.
                                           - Bit 11..30: reserved, must be 0.
                                           - Bit 31: if 1, SDO client object is not used. */
    uint32_t COB_IDServerToClient;    /**< Copy of CANopen COB_ID Server -> Client, similar as above */
    OD_extension_t OD_1280_extension; /**< Extension for OD object */
#endif
    uint8_t nodeIDOfTheSDOServer;  /**< Node-ID of the SDO server */
    bool_t valid;                  /**<  If true, SDO channel is valid */
    uint16_t index;                /**< Index of current object in Object Dictionary */
    uint8_t subIndex;              /**< Subindex of current object in Object Dictionary */
    bool_t finished;               /**< If true, then data transfer is finished */
    size_t sizeInd;                /**< Size of data, which will be transferred. It is optionally indicated by client
                                      in case of download or by server in case of upload. */
    size_t sizeTran;               /**< Size of data which is actually transferred. */
    volatile CO_SDO_state_t state; /**< Internal state of the SDO client */
    uint32_t SDOtimeoutTime_us;    /**< Maximum timeout time between request and response in microseconds */
    uint32_t timeoutTimer;         /**< Timeout timer for SDO communication */
    CO_fifo_t bufFifo;             /**< CO_fifo_t object for data buffer (not pointer) */
    uint8_t buf[CO_CONFIG_SDO_CLI_BUFFER_SIZE + 1U]; /**< Data buffer of usable size @ref CO_CONFIG_SDO_CLI_BUFFER_SIZE,
                                                        used inside bufFifo. Must be one byte larger for fifo usage. */
    volatile void* CANrxNew; /**< Indicates, if new SDO message received from CAN bus. It is not cleared, until received
                                message is completely processed. */
    uint8_t CANrxData[8];    /**< 8 data bytes of the received message */
#if (((CO_CONFIG_SDO_CLI)&CO_CONFIG_FLAG_CALLBACK_PRE) != 0) || defined CO_DOXYGEN
    void (*pFunctSignal)(void* object); /**< From CO_SDOclient_initCallbackPre() or NULL */
    void* functSignalObject;            /**< From CO_SDOclient_initCallbackPre() or NULL */
#endif
#if (((CO_CONFIG_SDO_CLI)&CO_CONFIG_SDO_CLI_SEGMENTED) != 0) || defined CO_DOXYGEN
    uint8_t toggle; /**< Toggle bit toggled in each segment in segmented transfer */
#endif
#if (((CO_CONFIG_SDO_CLI)&CO_CONFIG_SDO_CLI_BLOCK) != 0) || defined CO_DOXYGEN
    uint32_t block_SDOtimeoutTime_us; /**< Timeout time for SDO sub-block upload, half of #SDOtimeoutTime_us */
    uint32_t block_timeoutTimer;      /**< Timeout timer for SDO sub-block upload */
    uint8_t block_seqno;              /**< Sequence number of segment in block, 1..127 */
    uint8_t block_blksize;            /**< Number of segments per block, 1..127 */
    uint8_t block_noData;             /**< Number of bytes in last segment that do not contain data */
    bool_t block_crcEnabled;          /**< Server CRC support in block transfer */
    uint8_t block_dataUploadLast[7];  /**< Last 7 bytes of data at block upload */
    uint16_t block_crc;               /**< Calculated CRC checksum */
#endif
} CO_SDOclient_t;

/**
 * Initialize SDO client object.
 *
 * Function must be called in the communication reset section.
 *
 * @param SDO_C This object will be initialized.
 * @param OD Object Dictionary. It is used in case, if client is accessing object dictionary from its own device. If
 * NULL, it will be ignored.
 * @param OD_1280_SDOcliPar OD entry for SDO client parameter (0x1280+). It may have IO extension enabled to allow
 * dynamic configuration (see also
 * @ref CO_CONFIG_FLAG_OD_DYNAMIC). Entry is required.
 * @param nodeId CANopen Node ID of this device. It is used in case, if client is accessing object dictionary from its
 * own device. If 0, it will be ignored.
 * @param CANdevRx CAN device for SDO client reception.
 * @param CANdevRxIdx Index of receive buffer in the above CAN device.
 * @param CANdevTx CAN device for SDO client transmission.
 * @param CANdevTxIdx Index of transmit buffer in the above CAN device.
 * @param [out] errInfo Additional information in case of error, may be NULL.
 *
 * @return #CO_ReturnError_t: CO_ERROR_NO or CO_ERROR_ILLEGAL_ARGUMENT.
 */
CO_ReturnError_t CO_SDOclient_init(CO_SDOclient_t* SDO_C, OD_t* OD, OD_entry_t* OD_1280_SDOcliPar, uint8_t nodeId,
                                   CO_CANmodule_t* CANdevRx, uint16_t CANdevRxIdx, CO_CANmodule_t* CANdevTx,
                                   uint16_t CANdevTxIdx, uint32_t* errInfo);

#if (((CO_CONFIG_SDO_CLI)&CO_CONFIG_FLAG_CALLBACK_PRE) != 0) || defined CO_DOXYGEN
/**
 * Initialize SDOclient callback function.
 *
 * Function initializes optional callback function, which should immediately start processing of CO_SDOclientDownload()
 * or CO_SDOclientUpload() function. Callback is called after SDOclient message is received from the CAN bus or when new
 * call without delay is necessary (exchange data with own SDO server or SDO block transfer is in progress).
 *
 * @param SDOclient This object.
 * @param object Pointer to object, which will be passed to pFunctSignal(). Can be NULL.
 * @param pFunctSignal Pointer to the callback function. Not called if NULL.
 */
void CO_SDOclient_initCallbackPre(CO_SDOclient_t* SDOclient, void* object, void (*pFunctSignal)(void* object));
#endif

/**
 * Setup SDO client object.
 *
 * Function is called in from CO_SDOclient_init() and each time when "SDO client parameter" is written. Application can
 * call this function before new SDO communication. If parameters to this function are the same as before, then CAN is
 * not reconfigured.
 *
 * @param SDO_C This object.
 * @param COB_IDClientToServer See @ref CO_SDOclient_t.
 * @param COB_IDServerToClient See @ref CO_SDOclient_t.
 * @param nodeIDOfTheSDOServer Node-ID of the SDO server. If it is the same as node-ID of this node, then data will be
 * exchanged with this node (without CAN communication).
 *
 * @return #CO_SDO_return_t, CO_SDO_RT_ok_communicationEnd or CO_SDO_RT_wrongArguments
 */
CO_SDO_return_t CO_SDOclient_setup(CO_SDOclient_t* SDO_C, uint32_t COB_IDClientToServer, uint32_t COB_IDServerToClient,
                                   uint8_t nodeIDOfTheSDOServer);

/**
 * Initiate SDO download communication.
 *
 * Function initiates SDO download communication with server specified in CO_SDOclient_init() function. Data will be
 * written to remote node. Function is non-blocking.
 *
 * @param SDO_C This object.
 * @param index Index of object in object dictionary in remote node.
 * @param subIndex Subindex of object in object dictionary in remote node.
 * @param sizeIndicated Optionally indicate size of data to be downloaded. Actual data are written with one or multiple
 * CO_SDOclientDownloadBufWrite() calls.
 * - If sizeIndicated is different than 0, then total number of data written by CO_SDOclientDownloadBufWrite() will be
 *   compared against sizeIndicated. Also sizeIndicated info will be passed to the server, which will compare actual
 *   data size downloaded. In case of mismatch, SDO abort message will be generated.
 * - If sizeIndicated is 0, then actual data size will not be verified.
 * @param SDOtimeoutTime_ms Timeout time for SDO communication in milliseconds.
 * @param blockEnable Try to initiate block transfer.
 *
 * @return #CO_SDO_return_t
 */
CO_SDO_return_t CO_SDOclientDownloadInitiate(CO_SDOclient_t* SDO_C, uint16_t index, uint8_t subIndex,
                                             size_t sizeIndicated, uint16_t SDOtimeoutTime_ms, bool_t blockEnable);

/**
 * Initiate SDO download communication - update size.
 *
 * This is optional function, which updates sizeIndicated, if it was not known in the CO_SDOclientDownloadInitiate()
 * function call. This function can be used after CO_SDOclientDownloadBufWrite(), but must be used before
 * CO_SDOclientDownload().
 *
 * @param SDO_C This object.
 * @param sizeIndicated Same as in CO_SDOclientDownloadInitiate().
 */
void CO_SDOclientDownloadInitSize(CO_SDOclient_t* SDO_C, size_t sizeIndicated);

/**
 * Write data into SDO client buffer
 *
 * This function copies data from buf into internal SDO client fifo buffer. Function returns number of bytes
 * successfully copied. If there is not enough space in destination, not all bytes will be copied. Additional data can
 * be copied in next cycles. If there is enough space in destination and sizeIndicated is different than zero, then all
 * data must be written at once.
 *
 * This function is basically a wrapper for CO_fifo_write() function. As alternative, other functions from CO_fifo can
 * be used directly, for example CO_fifo_cpyTok2U8() or similar.
 *
 * @param SDO_C This object.
 * @param buf Buffer which will be copied
 * @param count Number of bytes in buf
 *
 * @return number of bytes actually written.
 */
size_t CO_SDOclientDownloadBufWrite(CO_SDOclient_t* SDO_C, const uint8_t* buf, size_t count);

/**
 * Process SDO download communication.
 *
 * Function must be called cyclically until it returns <=0. It Proceeds SDO download communication initiated with
 * CO_SDOclientDownloadInitiate(). Function is non-blocking.
 *
 * If function returns #CO_SDO_RT_blockDownldInProgress and OS has buffer for CAN tx messages, then this function may be
 * called multiple times within own loop. This can speed-up SDO block transfer.
 *
 * @param SDO_C This object.
 * @param timeDifference_us Time difference from previous function call in [microseconds].
 * @param send_abort If true, SDO client will send abort message from SDOabortCode and transmission will be aborted.
 * @param bufferPartial True indicates, not all data were copied to internal buffer yet. Buffer will be refilled later
 * with #CO_SDOclientDownloadBufWrite.
 * @param [out] SDOabortCode In case of error in communication, SDO abort code contains reason of error. Ignored if
 * NULL.
 * @param [out] sizeTransferred Actual size of data transferred. Ignored if NULL
 * @param [out] timerNext_us info to OS - see CO_process(). Ignored if NULL.
 *
 * @return #CO_SDO_return_t. If less than 0, then error occurred, SDOabortCode contains reason and state becomes idle.
 * If 0, communication ends successfully and state becomes idle. If greater than 0, then communication is in progress.
 */
CO_SDO_return_t CO_SDOclientDownload(CO_SDOclient_t* SDO_C, uint32_t timeDifference_us, bool_t send_abort,
                                     bool_t bufferPartial, CO_SDO_abortCode_t* SDOabortCode, size_t* sizeTransferred,
                                     uint32_t* timerNext_us);

/**
 * Initiate SDO upload communication.
 *
 * Function initiates SDO upload communication with server specified in CO_SDOclient_init() function. Data will be read
 * from remote node. Function is non-blocking.
 *
 * @param SDO_C This object.
 * @param index Index of object in object dictionary in remote node.
 * @param subIndex Subindex of object in object dictionary in remote node.
 * @param SDOtimeoutTime_ms Timeout time for SDO communication in milliseconds.
 * @param blockEnable Try to initiate block transfer.
 *
 * @return #CO_SDO_return_t
 */
CO_SDO_return_t CO_SDOclientUploadInitiate(CO_SDOclient_t* SDO_C, uint16_t index, uint8_t subIndex,
                                           uint16_t SDOtimeoutTime_ms, bool_t blockEnable);

/**
 * Process SDO upload communication.
 *
 * Function must be called cyclically until it returns <=0. It Proceeds SDO upload communication initiated with
 * CO_SDOclientUploadInitiate(). Function is non-blocking.
 *
 * If this function returns #CO_SDO_RT_uploadDataBufferFull, then data must be read from fifo buffer to make it empty.
 * This function can then be called once again immediately to speed-up block transfer. Note also, that remaining data
 * must be read after function returns #CO_SDO_RT_ok_communicationEnd. Data must not be read, if function returns
 * #CO_SDO_RT_blockUploadInProgress.
 *
 * @param SDO_C This object.
 * @param timeDifference_us Time difference from previous function call in [microseconds].
 * @param send_abort If true, SDO client will send abort message from SDOabortCode and reception will be aborted.
 * @param [out] SDOabortCode In case of error in communication, SDO abort code contains reason of error. Ignored if
 * NULL.
 * @param [out] sizeIndicated If larger than 0, then SDO server has indicated size of data transfer. Ignored if NULL.
 * @param [out] sizeTransferred Actual size of data transferred. Ignored if NULL
 * @param [out] timerNext_us info to OS - see CO_process(). Ignored if NULL.
 *
 * @return #CO_SDO_return_t. If less than 0, then error occurred, SDOabortCode contains reason and state becomes idle.
 * If 0, communication ends successfully and state becomes idle. If greater than 0, then communication is in progress.
 */
CO_SDO_return_t CO_SDOclientUpload(CO_SDOclient_t* SDO_C, uint32_t timeDifference_us, bool_t send_abort,
                                   CO_SDO_abortCode_t* SDOabortCode, size_t* sizeIndicated, size_t* sizeTransferred,
                                   uint32_t* timerNext_us);

/**
 * Read data from SDO client buffer.
 *
 * This function copies data from internal fifo buffer of SDO client into buf. Function returns number of bytes
 * successfully copied. It can be called in multiple cycles, if data length is large.
 *
 * This function is basically a wrapper for CO_fifo_read() function. As alternative, other functions from CO_fifo can be
 * used directly, for example CO_fifo_readU82a() or similar.
 *
 * @warning This function (or similar) must NOT be called when CO_SDOclientUpload() returns
 * #CO_SDO_RT_blockUploadInProgress!
 *
 * @param SDO_C This object.
 * @param buf Buffer into which data will be copied
 * @param count Copy up to count bytes into buffer
 *
 * @return number of bytes actually read.
 */
size_t CO_SDOclientUploadBufRead(CO_SDOclient_t* SDO_C, uint8_t* buf, size_t count);

/**
 * Close SDO communication temporary.
 *
 * Function must be called after finish of each SDO client communication cycle. It disables reception of SDO client CAN
 * messages. It is necessary, because CO_SDOclient_receive function may otherwise write into undefined SDO buffer.
 *
 * @param SDO_C This object.
 */
void CO_SDOclientClose(CO_SDOclient_t* SDO_C);

/** @} */ /* CO_SDOclient */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* (CO_CONFIG_SDO_CLI) & CO_CONFIG_SDO_CLI_ENABLE */

#endif /* CO_SDO_CLIENT_H */