/** * CANopen Process Data Object protocol. * * @file CO_PDO.h * @ingroup CO_PDO * @author Janez Paternoster * @copyright 2021 Janez Paternoster * * This file is part of , 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_PDO_H #define CO_PDO_H #include "301/CO_ODinterface.h" #include "301/CO_Emergency.h" #include "301/CO_SYNC.h" /* default configuration, see CO_config.h */ #ifndef CO_CONFIG_PDO #define CO_CONFIG_PDO \ (CO_CONFIG_RPDO_ENABLE | CO_CONFIG_TPDO_ENABLE | CO_CONFIG_RPDO_TIMERS_ENABLE | CO_CONFIG_TPDO_TIMERS_ENABLE \ | CO_CONFIG_PDO_SYNC_ENABLE | CO_CONFIG_PDO_OD_IO_ACCESS | CO_CONFIG_GLOBAL_RT_FLAG_CALLBACK_PRE \ | CO_CONFIG_GLOBAL_FLAG_TIMERNEXT | CO_CONFIG_GLOBAL_FLAG_OD_DYNAMIC) #endif #if (((CO_CONFIG_PDO) & (CO_CONFIG_RPDO_ENABLE | CO_CONFIG_TPDO_ENABLE)) != 0) || defined CO_DOXYGEN #ifdef __cplusplus extern "C" { #endif /** * @defgroup CO_PDO PDO * CANopen Process Data Object protocol. * * @ingroup CO_CANopen_301 * @{ * Process data objects are used for real-time data transfer with no protocol overhead. * * TPDO with specific identifier is transmitted by one device and recieved by zero or more devices as RPDO. PDO * communication parameters(COB-ID, transmission type, etc.) are in the Object Dictionary at index 0x1400+ and 0x1800+. * PDO mapping parameters (size and contents of the PDO) are in the Object Dictionary at index 0x1600+ and 0x1A00+. * * Features of the PDO as implemented in CANopenNode: * - Dynamic PDO mapping. * - Map granularity of one byte. * - Data from OD variables are accessed via @ref OD_IO_t read()/write() functions, which gives a great usefulness to * the application. * - For systems with very low memory and processing capabilities there is a simplified @ref CO_CONFIG_PDO option, * where instead of read()/write() access, PDO data are copied directly to/from memory locations of OD variables. * - After RPDO is received from CAN bus, its data are copied to internal buffer (inside fast CAN receive interrupt). * Function CO_RPDO_process() (called by application) copies data to the mapped objects in the Object Dictionary. * Synchronous RPDOs are processed AFTER reception of the next SYNC message. * - Function CO_TPDO_process() (called by application) sends TPDO when necessary. There are different transmission * types possible, controlled by: SYNC message, event timer, @ref CO_TPDOsendRequest() by application or @ref * OD_requestTPDO(), where application can request TPDO for OD variable mapped to any of them. In later case * application may, for example, monitor change of state of the OD variable and indicate TPDO request on it. * * @anchor CO_PDO_CAN_ID * ### CAN identifiers for PDO * * Each PDO can be configured with any valid 11-bit CAN identifier. Lower numbers have higher priorities on CAN bus. As * a general rule, each CAN message is identified with own CAN-ID, which must be unique and produced by single source. * The same is with PDO objects: Any TPDO produced on the CANopen network must have unique CAN-ID and there can be zero * to many RPDOs (from different devices) configured to match the CAN-ID of the TPDO of interest. * * CANopen standard provides pre-defined connection sets for four RPDOs and four TPDOs on each device with specific * 7-bit Node-ID. These are default values and are usable in configuration, where CANopen network contains a master * device, which directly communicates with many slaves. In de-centralized systems, where devices operate without a * master, it makes sense to configure CAN-IDs of the RPDOs to the non-default values. * * Default CAN identifiers for first four TPDOs on device with specific CANopen Node-Id are: 0x180+NodeId, 0x280+NodeId, * 0x380+NodeId and 0x480+NodeId. * * Default CAN identifiers for first four RPDOs on device with specific CANopen Node-Id are: 0x200+NodeId, 0x300+NodeId, * 0x400+NodeId and 0x500+NodeId. * * CANopenNode handles default (pre-defined) CAN-IDs. If it is detected, that PDO is configured with default CAN-ID * (when writing to OD variable PDO communication parameter, COB-ID), then COB-ID is stored without Node-Id to the * Object Dictionary. If Node-ID is changed, then COB-ID will always contain correct default CAN-ID (default CAN-ID + * Node-ID). If PDO is configured with non-default CAN-ID, then it will be stored to the Object Dictionary as is. * * If configuration CO_CONFIG_FLAG_OD_DYNAMIC is enabled in @ref CO_CONFIG_PDO, then PDOs can be configured dynamically, * also in NMT operational state. Otherwise PDOs are configured only in reset communication section and also default * CAN-IDs are always stored to OD as is, no default node-id is handled. * * Configure PDO by writing to the OD variables in the following procedure: * - Disable the PDO by setting bit-31 to 1 in PDO communication parameter, COB-ID * - Node-Id can be configured only when PDO is disabled. * - Disable mapping by setting PDO mapping parameter, sub index 0 to 0 * - Configure mapping * - Enable mapping by setting PDO mapping param, sub 0 to number of mapped objects * - Enable the PDO by setting bit-31 to 0 in PDO communication parameter, COB-ID */ /** Maximum size of PDO message, 8 for standard CAN */ #ifndef CO_PDO_MAX_SIZE #define CO_PDO_MAX_SIZE 8U #endif /** Maximum number of entries, which can be mapped to PDO, 8 for standard CAN, may be less to preserve RAM usage */ #ifndef CO_PDO_MAX_MAPPED_ENTRIES #define CO_PDO_MAX_MAPPED_ENTRIES 8U #endif /** Number of CANopen RPDO objects, which uses default CAN indentifiers. By default first four RPDOs have pre-defined * CAN identifiers, which depends on node-id. This constant may be set to 0 to disable functionality or set to any other * value. For example, if there are several logical devices inside single CANopen device, then more than four RPDOs may * have pre-defined CAN identifiers. In that case RPDO5 has CAN_ID=0x200+NodeId+1, RPDO6 has CAN_ID=0x300+NodeId+1, * RPDO9 has CAN_ID=0x200+NodeId+2 and so on. */ #ifndef CO_RPDO_DEFAULT_CANID_COUNT #define CO_RPDO_DEFAULT_CANID_COUNT 4U #endif /** Number of CANopen TPDO objects, which uses default CAN indentifiers. If value is more than four, then pre-defined * pre-defined CAN identifiers are: TPDO5 has CAN_ID=0x180+NodeId+1, TPDO6 has CAN_ID=0x280+NodeId+1, TPDO9 has * CAN_ID=0x180+NodeId+2 and so on. For description see @ref CO_RPDO_DEFAULT_CANID_COUNT. */ #ifndef CO_TPDO_DEFAULT_CANID_COUNT #define CO_TPDO_DEFAULT_CANID_COUNT 4U #endif #ifndef CO_PDO_OWN_TYPES /** Variable of type CO_PDO_size_t contains data length in bytes of PDO */ typedef uint8_t CO_PDO_size_t; #endif /** * PDO transmission Types */ typedef enum { CO_PDO_TRANSM_TYPE_SYNC_ACYCLIC = 0U, /**< synchronous (acyclic) */ CO_PDO_TRANSM_TYPE_SYNC_1 = 1U, /**< synchronous (cyclic every sync) */ CO_PDO_TRANSM_TYPE_SYNC_240 = 0xF0U, /**< synchronous (cyclic every 240-th sync) */ CO_PDO_TRANSM_TYPE_SYNC_EVENT_LO = 0xFEU, /**< event-driven, lower value (manufacturer specific), */ CO_PDO_TRANSM_TYPE_SYNC_EVENT_HI = 0xFFU /**< event-driven, higher value (device profile and application profile specific) */ } CO_PDO_transmissionTypes_t; /** * PDO object, common properties */ typedef struct { CO_EM_t* em; /**< From CO_xPDO_init() */ CO_CANmodule_t* CANdev; /**< From CO_xPDO_init() */ bool_t valid; /**< True, if PDO is enabled and valid */ CO_PDO_size_t dataLength; /**< Data length of the received PDO message. Calculated from mapping */ uint8_t mappedObjectsCount; /**< Number of mapped objects in PDO */ #if (((CO_CONFIG_PDO)&CO_CONFIG_PDO_OD_IO_ACCESS) != 0) || defined CO_DOXYGEN OD_IO_t OD_IO[CO_PDO_MAX_MAPPED_ENTRIES]; /**< Object dictionary interface for all mapped entries. OD_IO.dataOffset has special usage with PDO. It stores information about the number of bytes mapped to the PDO. If CO_CONFIG_PDO_BITWISE_MAPPING is enabled, it stores a number of bits instead. In either case, the number of bits mapped to the PDO can not be more than the size of the variable (OD_IO.dataLength) in bits. mappedLengthBits can be less or equal to the OD_IO.dataLength*8. mappedLengthBits greater than OD_IO.dataLength*8 indicates erroneous mapping. OD_IO.dataOffset is set to 0 before read/write function call and after the call OD_IO.dataOffset is set back to mappedLength (if CO_CONFIG_PDO_BITWISE_MAPPING is disabled) or mappedLengthBits (if CO_CONFIG_PDO_BITWISE_MAPPING is enabled). */ #if OD_FLAGS_PDO_SIZE > 0 uint8_t* flagPDObyte[CO_PDO_MAX_MAPPED_ENTRIES]; /**< Pointer to byte, which contains PDO flag bit from @ref OD_extension_t */ uint8_t flagPDObitmask[CO_PDO_MAX_MAPPED_ENTRIES]; /**< Bitmask for the flagPDObyte */ #endif #else /* Pointers to data objects inside OD, where PDO will be copied */ uint8_t* mapPointer[CO_PDO_MAX_SIZE]; #if OD_FLAGS_PDO_SIZE > 0 uint8_t* flagPDObyte[CO_PDO_MAX_SIZE]; uint8_t flagPDObitmask[CO_PDO_MAX_SIZE]; #endif #endif #if (((CO_CONFIG_PDO)&CO_CONFIG_FLAG_OD_DYNAMIC) != 0) || defined CO_DOXYGEN bool_t isRPDO; /**< True for RPDO, false for TPDO */ OD_t* OD; /**< From CO_xPDO_init() */ uint16_t CANdevIdx; /**< From CO_xPDO_init() */ uint16_t preDefinedCanId; /**< From CO_xPDO_init() */ uint16_t configuredCanId; /**< Currently configured CAN identifier */ OD_extension_t OD_communicationParam_ext; /**< Extension for OD object */ OD_extension_t OD_mappingParam_extension; /**< Extension for OD object */ #endif } CO_PDO_common_t; /******************************************************************************* * R P D O ******************************************************************************/ #if (((CO_CONFIG_PDO)&CO_CONFIG_RPDO_ENABLE) != 0) || defined CO_DOXYGEN /** * Number of buffers for received CAN message for RPDO */ #if (((CO_CONFIG_PDO)&CO_CONFIG_PDO_SYNC_ENABLE) != 0) || defined CO_DOXYGEN #define CO_RPDO_CAN_BUFFERS_COUNT 2 #else #define CO_RPDO_CAN_BUFFERS_COUNT 1 #endif /** * RPDO object. */ typedef struct { CO_PDO_common_t PDO_common; /**< PDO common properties, must be first element in this object */ volatile void* CANrxNew[CO_RPDO_CAN_BUFFERS_COUNT]; /**< Variable indicates, if new PDO message received from CAN */ uint8_t CANrxData[CO_RPDO_CAN_BUFFERS_COUNT][CO_PDO_MAX_SIZE]; /**< CO_PDO_MAX_SIZE data bytes of the received message. */ uint8_t receiveError; /**< Indication of RPDO length errors, use with CO_PDO_receiveErrors_t */ #if (((CO_CONFIG_PDO)&CO_CONFIG_PDO_SYNC_ENABLE) != 0) || defined CO_DOXYGEN CO_SYNC_t* SYNC; /**< From CO_RPDO_init() */ bool_t synchronous; /**< True if transmissionType <= 240 */ #endif #if (((CO_CONFIG_PDO)&CO_CONFIG_RPDO_TIMERS_ENABLE) != 0) || defined CO_DOXYGEN uint32_t timeoutTime_us; /**< Maximum timeout time between received PDOs in microseconds. Configurable by OD variable RPDO communication parameter, event-timer. */ uint32_t timeoutTimer; /**< Timeout timer variable in microseconds */ #endif #if (((CO_CONFIG_PDO)&CO_CONFIG_FLAG_CALLBACK_PRE) != 0) || defined CO_DOXYGEN void (*pFunctSignalPre)(void* object); /**< From CO_RPDO_initCallbackPre() or NULL */ void* functSignalObjectPre; /**< From CO_RPDO_initCallbackPre() or NULL */ #endif } CO_RPDO_t; /** * Initialize RPDO object. * * Function must be called in the end of the communication reset section, after all application initialization. * Otherwise mapping to application OD variables will not be correct. * * @param RPDO This object will be initialized. * @param OD Object Dictionary. * @param em Emergency object. * @param SYNC SYNC object, may be NULL. * @param preDefinedCanId CAN identifier from pre-defined connection set, including node-id for first four PDOs, or 0 * otherwise, see @ref CO_PDO_CAN_ID * @param OD_14xx_RPDOCommPar OD entry for 0x1400+ - "RPDO communication parameter", entry is required. * @param OD_16xx_RPDOMapPar OD entry for 0x1600+ - "RPDO mapping parameter", entry is required. * @param CANdevRx CAN device for PDO reception. * @param CANdevRxIdx Index of receive 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 on success. */ CO_ReturnError_t CO_RPDO_init(CO_RPDO_t* RPDO, OD_t* OD, CO_EM_t* em, #if (((CO_CONFIG_PDO)&CO_CONFIG_PDO_SYNC_ENABLE) != 0) || defined CO_DOXYGEN CO_SYNC_t* SYNC, #endif uint16_t preDefinedCanId, OD_entry_t* OD_14xx_RPDOCommPar, OD_entry_t* OD_16xx_RPDOMapPar, CO_CANmodule_t* CANdevRx, uint16_t CANdevRxIdx, uint32_t* errInfo); #if (((CO_CONFIG_PDO)&CO_CONFIG_FLAG_CALLBACK_PRE) != 0) || defined CO_DOXYGEN /** * Initialize RPDO callback function. * * Function initializes optional callback function, which should immediately start processing of CO_RPDO_process() * function. Callback is called after RPDO message is received from the CAN bus. * * @param RPDO This object. * @param object Pointer to object, which will be passed to pFunctSignalPre(). * @param pFunctSignalPre Pointer to the callback function. Not called if NULL. */ void CO_RPDO_initCallbackPre(CO_RPDO_t* RPDO, void* object, void (*pFunctSignalPre)(void* object)); #endif /** * Process received PDO messages. * * Function must be called cyclically in any NMT state. It copies data from RPDO to Object Dictionary variables if: new * PDO receives and PDO is valid and NMT operating state is operational. Synchronous RPDOs are processed after next SYNC * message. * * @param RPDO This object. * @param timeDifference_us Time difference from previous function call. * @param [out] timerNext_us info to OS - see CO_process(). * @param NMTisOperational True if this node is in NMT_OPERATIONAL state. * @param syncWas True, if CANopen SYNC message was just received or transmitted. */ void CO_RPDO_process(CO_RPDO_t* RPDO, #if (((CO_CONFIG_PDO)&CO_CONFIG_RPDO_TIMERS_ENABLE) != 0) || defined CO_DOXYGEN uint32_t timeDifference_us, uint32_t* timerNext_us, #endif bool_t NMTisOperational, bool_t syncWas); #endif /* (CO_CONFIG_PDO) & CO_CONFIG_RPDO_ENABLE */ /******************************************************************************* * T P D O ******************************************************************************/ #if (((CO_CONFIG_PDO)&CO_CONFIG_TPDO_ENABLE) != 0) || defined CO_DOXYGEN /** * TPDO object. */ typedef struct { CO_PDO_common_t PDO_common; /**< PDO common properties, must be first element in this object */ CO_CANtx_t* CANtxBuff; /**< CAN transmit buffer inside CANdev */ uint8_t transmissionType; /**< Copy of the variable from object dictionary */ bool_t sendRequest; /**< If this flag is set and TPDO is event driven (transmission type is 0, 254 or 255), then PDO will be sent by CO_TPDO_process(). */ #if (((CO_CONFIG_PDO)&CO_CONFIG_PDO_SYNC_ENABLE) != 0) || defined CO_DOXYGEN CO_SYNC_t* SYNC; /**< From CO_TPDO_init() */ uint8_t syncStartValue; /**< Copy of the variable from object dictionary */ uint8_t syncCounter; /**< SYNC counter used for PDO sending */ #endif #if (((CO_CONFIG_PDO)&CO_CONFIG_TPDO_TIMERS_ENABLE) != 0) || defined CO_DOXYGEN uint32_t inhibitTime_us; /**< Inhibit time from object dictionary translated to microseconds */ uint32_t eventTime_us; /**< Event time from object dictionary translated to microseconds */ uint32_t inhibitTimer; /**< Inhibit timer variable in microseconds */ uint32_t eventTimer; /**< Event timer variable in microseconds */ #endif } CO_TPDO_t; /** * Initialize TPDO object. * * Function must be called in the end of the communication reset section, after all application initialization. * Otherwise mapping to application OD variables will not be correct. * * @param TPDO This object will be initialized. * @param OD Object Dictionary. * @param em Emergency object. * @param SYNC SYNC object, may be NULL. * @param preDefinedCanId CAN identifier from pre-defined connection set, including node-id for first four PDOs, or 0 * otherwise, see @ref CO_PDO_CAN_ID * @param OD_18xx_TPDOCommPar OD entry for 0x1800+ - "TPDO communication parameter", entry is required. * @param OD_1Axx_TPDOMapPar OD entry for 0x1A00+ - "TPDO mapping parameter", entry is required. * @param CANdevTx CAN device used for PDO 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 on success. */ CO_ReturnError_t CO_TPDO_init(CO_TPDO_t* TPDO, OD_t* OD, CO_EM_t* em, #if (((CO_CONFIG_PDO)&CO_CONFIG_PDO_SYNC_ENABLE) != 0) || defined CO_DOXYGEN CO_SYNC_t* SYNC, #endif uint16_t preDefinedCanId, OD_entry_t* OD_18xx_TPDOCommPar, OD_entry_t* OD_1Axx_TPDOMapPar, CO_CANmodule_t* CANdevTx, uint16_t CANdevTxIdx, uint32_t* errInfo); /** * Request transmission of TPDO message. * * If TPDO transmission type is 0, 254 or 255, then TPDO will be sent by @ref CO_TPDO_process() after inhibit timer * expires. See also @ref OD_requestTPDO() and @ref OD_TPDOtransmitted(). * * @param TPDO TPDO object. */ static inline void CO_TPDOsendRequest(CO_TPDO_t* TPDO) { if (TPDO != NULL) { TPDO->sendRequest = true; } } /** * Process transmitting PDO messages. * * Function must be called cyclically in any NMT state. It prepares and sends TPDO if necessary. * * @param TPDO This object. * @param timeDifference_us Time difference from previous function call. * @param [out] timerNext_us info to OS - see CO_process(). * @param NMTisOperational True if this node is in NMT_OPERATIONAL state. * @param syncWas True, if CANopen SYNC message was just received or transmitted. */ void CO_TPDO_process(CO_TPDO_t* TPDO, #if (((CO_CONFIG_PDO)&CO_CONFIG_TPDO_TIMERS_ENABLE) != 0) || defined CO_DOXYGEN uint32_t timeDifference_us, uint32_t* timerNext_us, #endif bool_t NMTisOperational, bool_t syncWas); #endif /* (CO_CONFIG_PDO) & CO_CONFIG_TPDO_ENABLE */ /** @} */ /* CO_PDO */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* (CO_CONFIG_PDO) & (CO_CONFIG_RPDO_ENABLE | CO_CONFIG_TPDO_ENABLE) */ #endif /* CO_PDO_H */