From abe7239018908ac5c4912dcc62b840b882fd95f6 Mon Sep 17 00:00:00 2001 From: "Robin.Mueller" Date: Sun, 19 Apr 2020 13:24:10 +0200 Subject: [PATCH] reset, splitting up merge request --- devicehandlers/CookieIF.h | 33 - devicehandlers/DeviceCommunicationIF.h | 142 +-- devicehandlers/DeviceHandlerBase.cpp | 357 ++++---- devicehandlers/DeviceHandlerBase.h | 1095 +++++++++++------------- devicehandlers/DeviceHandlerIF.h | 152 ++-- 5 files changed, 787 insertions(+), 992 deletions(-) delete mode 100644 devicehandlers/CookieIF.h diff --git a/devicehandlers/CookieIF.h b/devicehandlers/CookieIF.h deleted file mode 100644 index 55fdb44b..00000000 --- a/devicehandlers/CookieIF.h +++ /dev/null @@ -1,33 +0,0 @@ -#ifndef COOKIE_H_ -#define COOKIE_H_ -#include -#include - -/** - * @brief Physical address type - */ -typedef uint32_t address_t; - -/** - * @brief This datatype is used to identify different connection over a single interface - * (like RMAP or I2C) - * @details - * To use this class, implement a communication specific child cookie which - * inherits Cookie. Cookie instances are created in config/ Factory.cpp by calling - * CookieIF* childCookie = new ChildCookie(...). - * - * This cookie is then passed to the child device handlers, which stores the - * pointer and passes it to the communication interface functions. - * - * The cookie can be used to store all kinds of information - * about the communication, like slave addresses, communication status, - * communication parameters etc. - * - * @ingroup comm - */ -class CookieIF { -public: - virtual ~CookieIF() {}; -}; - -#endif /* COOKIE_H_ */ diff --git a/devicehandlers/DeviceCommunicationIF.h b/devicehandlers/DeviceCommunicationIF.h index 657f7232..e0aca573 100644 --- a/devicehandlers/DeviceCommunicationIF.h +++ b/devicehandlers/DeviceCommunicationIF.h @@ -1,117 +1,63 @@ #ifndef DEVICECOMMUNICATIONIF_H_ #define DEVICECOMMUNICATIONIF_H_ -#include -#include +#include #include -/** - * @defgroup interfaces Interfaces - * @brief Interfaces for flight software objects - */ -/** - * @defgroup comm Communication - * @brief Communication software components. - */ - -/** - * @brief This is an interface to decouple device communication from - * the device handler to allow reuse of these components. - * @details - * Documentation: Dissertation Baetz p.138. - * It works with the assumption that received data - * is polled by a component. There are four generic steps of device communication: - * - * 1. Send data to a device - * 2. Get acknowledgement for sending - * 3. Request reading data from a device - * 4. Read received data - * - * To identify different connection over a single interface can return - * so-called cookies to components. - * The CommunicationMessage message type can be used to extend the functionality of the - * ComIF if a separate polling task is required. - * @ingroup interfaces - * @ingroup comm - */ class DeviceCommunicationIF: public HasReturnvaluesIF { public: static const uint8_t INTERFACE_ID = CLASS_ID::DEVICE_COMMUNICATION_IF; - //!< This is used if no read request is to be made by the device handler. - static const ReturnValue_t NO_READ_REQUEST = MAKE_RETURN_CODE(0x01); - //! General protocol error. Define more concrete errors in child handler - static const ReturnValue_t PROTOCOL_ERROR = MAKE_RETURN_CODE(0x02); - //! If cookie is a null pointer - static const ReturnValue_t NULLPOINTER = MAKE_RETURN_CODE(0x03); - static const ReturnValue_t INVALID_COOKIE_TYPE = MAKE_RETURN_CODE(0x04); - // is this needed if there is no open/close call? - static const ReturnValue_t NOT_ACTIVE = MAKE_RETURN_CODE(0x05); - static const ReturnValue_t TOO_MUCH_DATA = MAKE_RETURN_CODE(0x06); + static const ReturnValue_t INVALID_COOKIE_TYPE = MAKE_RETURN_CODE(0x01); + static const ReturnValue_t NOT_ACTIVE = MAKE_RETURN_CODE(0x02); + static const ReturnValue_t INVALID_ADDRESS = MAKE_RETURN_CODE(0x03); + static const ReturnValue_t TOO_MUCH_DATA = MAKE_RETURN_CODE(0x04); + static const ReturnValue_t NULLPOINTER = MAKE_RETURN_CODE(0x05); + static const ReturnValue_t PROTOCOL_ERROR = MAKE_RETURN_CODE(0x06); + static const ReturnValue_t CANT_CHANGE_REPLY_LEN = MAKE_RETURN_CODE(0x07); - virtual ~DeviceCommunicationIF() {} + virtual ~DeviceCommunicationIF() { + + } + + virtual ReturnValue_t open(Cookie **cookie, uint32_t address, + uint32_t maxReplyLen) = 0; /** - * @brief Device specific initialization, using the cookie. - * @details - * The cookie is already prepared in the factory. If the communication - * interface needs to be set up in some way and requires cookie information, - * this can be performed in this function, which is called on device handler - * initialization. - * @param cookie - * @return -@c RETURN_OK if initialization was successfull - * - Everything else triggers failure event with returnvalue as parameter 1 - */ - virtual ReturnValue_t initializeInterface(CookieIF * cookie) = 0; - - /** - * Called by DHB in the SEND_WRITE doSendWrite(). - * This function is used to send data to the physical device - * by implementing and calling related drivers or wrapper functions. - * @param cookie - * @param data - * @param len - * @return -@c RETURN_OK for successfull send - * - Everything else triggers failure event with returnvalue as parameter 1 - */ - virtual ReturnValue_t sendMessage(CookieIF *cookie, const uint8_t * sendData, - size_t sendLen) = 0; - - /** - * Called by DHB in the GET_WRITE doGetWrite(). - * Get send confirmation that the data in sendMessage() was sent successfully. - * @param cookie - * @return -@c RETURN_OK if data was sent successfull - * - Everything else triggers falure event with returnvalue as parameter 1 - */ - virtual ReturnValue_t getSendSuccess(CookieIF *cookie) = 0; - - /** - * Called by DHB in the SEND_WRITE doSendRead(). - * It is assumed that it is always possible to request a reply - * from a device. If a requestLen of 0 is supplied, no reply was enabled - * and communication specific action should be taken (e.g. read nothing - * or read everything). + * Use an existing cookie to open a connection to a new DeviceCommunication. + * The previous connection must not be closed. + * If the returnvalue is not RETURN_OK, the cookie is unchanged and + * can be used with the previous connection. * * @param cookie - * @param requestLen Size of data to read - * @return -@c RETURN_OK to confirm the request for data has been sent. - * - Everything else triggers failure event with returnvalue as parameter 1 + * @param address + * @param maxReplyLen + * @return */ - virtual ReturnValue_t requestReceiveMessage(CookieIF *cookie, size_t requestLen) = 0; + virtual ReturnValue_t reOpen(Cookie *cookie, uint32_t address, + uint32_t maxReplyLen) = 0; + + virtual void close(Cookie *cookie) = 0; + + //SHOULDDO can data be const? + virtual ReturnValue_t sendMessage(Cookie *cookie, uint8_t *data, + uint32_t len) = 0; + + virtual ReturnValue_t getSendSuccess(Cookie *cookie) = 0; + + virtual ReturnValue_t requestReceiveMessage(Cookie *cookie) = 0; + + virtual ReturnValue_t readReceivedMessage(Cookie *cookie, uint8_t **buffer, + uint32_t *size) = 0; + + virtual ReturnValue_t setAddress(Cookie *cookie, uint32_t address) = 0; + + virtual uint32_t getAddress(Cookie *cookie) = 0; + + virtual ReturnValue_t setParameter(Cookie *cookie, uint32_t parameter) = 0; + + virtual uint32_t getParameter(Cookie *cookie) = 0; - /** - * Called by DHB in the GET_WRITE doGetRead(). - * This function is used to receive data from the physical device - * by implementing and calling related drivers or wrapper functions. - * @param cookie - * @param data - * @param len - * @return @c RETURN_OK for successfull receive - * - Everything else triggers failure event with returnvalue as parameter 1 - */ - virtual ReturnValue_t readReceivedMessage(CookieIF *cookie, uint8_t **buffer, - size_t *size) = 0; }; #endif /* DEVICECOMMUNICATIONIF_H_ */ diff --git a/devicehandlers/DeviceHandlerBase.cpp b/devicehandlers/DeviceHandlerBase.cpp index 5fb5a9e5..22d49d37 100644 --- a/devicehandlers/DeviceHandlerBase.cpp +++ b/devicehandlers/DeviceHandlerBase.cpp @@ -4,7 +4,7 @@ #include #include #include -#include +#include #include #include #include @@ -16,33 +16,37 @@ object_id_t DeviceHandlerBase::powerSwitcherId = 0; object_id_t DeviceHandlerBase::rawDataReceiverId = 0; object_id_t DeviceHandlerBase::defaultFDIRParentId = 0; -DeviceHandlerBase::DeviceHandlerBase(object_id_t setObjectId, object_id_t deviceCommunication, - CookieIF * comCookie_, uint8_t setDeviceSwitch, +DeviceHandlerBase::DeviceHandlerBase(uint32_t ioBoardAddress, + object_id_t setObjectId, uint32_t maxDeviceReplyLen, + uint8_t setDeviceSwitch, object_id_t deviceCommunication, uint32_t thermalStatePoolId, uint32_t thermalRequestPoolId, - FailureIsolationBase* fdirInstance, size_t cmdQueueSize) : - SystemObject(setObjectId), mode(MODE_OFF), submode(SUBMODE_NONE), - wiretappingMode(OFF), storedRawData(StorageManagerIF::INVALID_ADDRESS), - deviceCommunicationId(deviceCommunication), comCookie(comCookie_), - deviceThermalStatePoolId(thermalStatePoolId), deviceThermalRequestPoolId(thermalRequestPoolId), - healthHelper(this, setObjectId), modeHelper(this), parameterHelper(this), - fdirInstance(fdirInstance), hkSwitcher(this), - defaultFDIRUsed(fdirInstance == nullptr), switchOffWasReported(false), - executingTask(nullptr), actionHelper(this, nullptr), cookieInfo(), - childTransitionDelay(5000), transitionSourceMode(_MODE_POWER_DOWN), - transitionSourceSubMode(SUBMODE_NONE), deviceSwitch(setDeviceSwitch) -{ - commandQueue = QueueFactory::instance()-> - createMessageQueue(cmdQueueSize, CommandMessage::MAX_MESSAGE_SIZE); + FailureIsolationBase* fdirInstance, uint32_t cmdQueueSize) : + SystemObject(setObjectId), rawPacket(0), rawPacketLen(0), mode( + MODE_OFF), submode(SUBMODE_NONE), pstStep(0), maxDeviceReplyLen( + maxDeviceReplyLen), wiretappingMode(OFF), defaultRawReceiver(0), storedRawData( + StorageManagerIF::INVALID_ADDRESS), requestedRawTraffic(0), powerSwitcher( + NULL), IPCStore(NULL), deviceCommunicationId(deviceCommunication), communicationInterface( + NULL), cookie( + NULL), commandQueue(NULL), deviceThermalStatePoolId(thermalStatePoolId), deviceThermalRequestPoolId( + thermalRequestPoolId), healthHelper(this, setObjectId), modeHelper( + this), parameterHelper(this), childTransitionFailure(RETURN_OK), ignoreMissedRepliesCount( + 0), fdirInstance(fdirInstance), hkSwitcher(this), defaultFDIRUsed( + fdirInstance == NULL), switchOffWasReported(false),executingTask(NULL), actionHelper(this, NULL), cookieInfo(), ioBoardAddress( + ioBoardAddress), timeoutStart(0), childTransitionDelay(5000), transitionSourceMode( + _MODE_POWER_DOWN), transitionSourceSubMode(SUBMODE_NONE), deviceSwitch( + setDeviceSwitch) { + commandQueue = QueueFactory::instance()->createMessageQueue(cmdQueueSize, + CommandMessage::MAX_MESSAGE_SIZE); cookieInfo.state = COOKIE_UNUSED; insertInCommandMap(RAW_COMMAND_ID); - if (this->fdirInstance == nullptr) { - this->fdirInstance = - new DeviceHandlerFailureIsolation(setObjectId, defaultFDIRParentId); + if (this->fdirInstance == NULL) { + this->fdirInstance = new DeviceHandlerFailureIsolation(setObjectId, + defaultFDIRParentId); } } DeviceHandlerBase::~DeviceHandlerBase() { - delete comCookie; + communicationInterface->close(cookie); if (defaultFDIRUsed) { delete fdirInstance; } @@ -51,6 +55,7 @@ DeviceHandlerBase::~DeviceHandlerBase() { ReturnValue_t DeviceHandlerBase::performOperation(uint8_t counter) { this->pstStep = counter; + if (counter == 0) { cookieInfo.state = COOKIE_UNUSED; readCommandQueue(); @@ -59,13 +64,11 @@ ReturnValue_t DeviceHandlerBase::performOperation(uint8_t counter) { decrementDeviceReplyMap(); fdirInstance->checkForFailures(); hkSwitcher.performOperation(); - performOperationHook(); } if (mode == MODE_OFF) { return RETURN_OK; } - - switch (getComAction()) { + switch (getRmapAction()) { case SEND_WRITE: if ((cookieInfo.state == COOKIE_UNUSED)) { buildInternalCommand(); @@ -85,84 +88,6 @@ ReturnValue_t DeviceHandlerBase::performOperation(uint8_t counter) { default: break; } - - return RETURN_OK; -} - -ReturnValue_t DeviceHandlerBase::initialize() { - ReturnValue_t result = SystemObject::initialize(); - if (result != RETURN_OK) { - return result; - } - - communicationInterface = objectManager->get( - deviceCommunicationId); - if (communicationInterface == NULL) { - return RETURN_FAILED; - } - - result = communicationInterface->initializeInterface(comCookie); - if (result != RETURN_OK) { - return result; - } - - IPCStore = objectManager->get(objects::IPC_STORE); - if (IPCStore == NULL) { - return RETURN_FAILED; - } - - AcceptsDeviceResponsesIF *rawReceiver = objectManager->get< - AcceptsDeviceResponsesIF>(rawDataReceiverId); - - if (rawReceiver == NULL) { - return RETURN_FAILED; - } - - defaultRawReceiver = rawReceiver->getDeviceQueue(); - - powerSwitcher = objectManager->get(powerSwitcherId); - if (powerSwitcher == NULL) { - return RETURN_FAILED; - } - - result = healthHelper.initialize(); - if (result != RETURN_OK) { - return result; - } - - result = modeHelper.initialize(); - if (result != RETURN_OK) { - return result; - } - result = actionHelper.initialize(commandQueue); - if (result != RETURN_OK) { - return result; - } - result = fdirInstance->initialize(); - if (result != HasReturnvaluesIF::RETURN_OK) { - return result; - } - - result = parameterHelper.initialize(); - if (result != HasReturnvaluesIF::RETURN_OK) { - return result; - } - - result = hkSwitcher.initialize(); - if (result != HasReturnvaluesIF::RETURN_OK) { - return result; - } - - fillCommandAndReplyMap(); - - //Set temperature target state to NON_OP. - DataSet mySet; - PoolVariable thermalRequest(deviceThermalRequestPoolId, &mySet, - PoolVariableIF::VAR_WRITE); - mySet.read(); - thermalRequest = ThermalComponentIF::STATE_REQUEST_NON_OPERATIONAL; - mySet.commit(PoolVariableIF::VALID); - return RETURN_OK; } @@ -331,49 +256,55 @@ ReturnValue_t DeviceHandlerBase::isModeCombinationValid(Mode_t mode, } } -ReturnValue_t DeviceHandlerBase::insertInCommandAndReplyMap(DeviceCommandId_t deviceCommand, - uint16_t maxDelayCycles, size_t replyLen, uint8_t periodic, - bool hasDifferentReplyId, DeviceCommandId_t replyId) { - //No need to check, as we may try to insert multiple times. +ReturnValue_t DeviceHandlerBase::insertInCommandAndReplyMap( + DeviceCommandId_t deviceCommand, uint16_t maxDelayCycles, + uint8_t periodic, bool hasDifferentReplyId, DeviceCommandId_t replyId) { +//No need to check, as we may try to insert multiple times. insertInCommandMap(deviceCommand); if (hasDifferentReplyId) { - return insertInReplyMap(replyId, maxDelayCycles, replyLen, periodic); + return insertInReplyMap(replyId, maxDelayCycles, periodic); } else { - return insertInReplyMap(deviceCommand, maxDelayCycles, replyLen, periodic); + return insertInReplyMap(deviceCommand, maxDelayCycles, periodic); } } ReturnValue_t DeviceHandlerBase::insertInReplyMap(DeviceCommandId_t replyId, - uint16_t maxDelayCycles, size_t replyLen, uint8_t periodic) { + uint16_t maxDelayCycles, uint8_t periodic) { DeviceReplyInfo info; info.maxDelayCycles = maxDelayCycles; info.periodic = periodic; info.delayCycles = 0; - info.replyLen = replyLen; info.command = deviceCommandMap.end(); - std::pair result = deviceReplyMap.emplace(replyId, info); - if (result.second) { + std::pair::iterator, bool> returnValue; + returnValue = deviceReplyMap.insert( + std::pair(replyId, info)); + if (returnValue.second) { return RETURN_OK; } else { return RETURN_FAILED; } } -ReturnValue_t DeviceHandlerBase::insertInCommandMap(DeviceCommandId_t deviceCommand) { +ReturnValue_t DeviceHandlerBase::insertInCommandMap( + DeviceCommandId_t deviceCommand) { DeviceCommandInfo info; info.expectedReplies = 0; info.isExecuting = false; info.sendReplyTo = NO_COMMANDER; - std::pair result = deviceCommandMap.emplace(deviceCommand,info); - if (result.second) { + std::pair::iterator, bool> returnValue; + returnValue = deviceCommandMap.insert( + std::pair(deviceCommand, + info)); + if (returnValue.second) { return RETURN_OK; } else { return RETURN_FAILED; } } -ReturnValue_t DeviceHandlerBase::updateReplyMapEntry(DeviceCommandId_t deviceReply, - uint16_t delayCycles, uint16_t maxDelayCycles, uint8_t periodic) { +ReturnValue_t DeviceHandlerBase::updateReplyMapEntry( + DeviceCommandId_t deviceReply, uint16_t delayCycles, + uint16_t maxDelayCycles, uint8_t periodic) { std::map::iterator iter = deviceReplyMap.find(deviceReply); if (iter == deviceReplyMap.end()) { @@ -485,7 +416,7 @@ void DeviceHandlerBase::replyToReply(DeviceReplyMap::iterator iter, return; } //Check if more replies are expected. If so, do nothing. - DeviceCommandInfo * info = &(iter->second.command->second); + DeviceCommandInfo* info = &(iter->second.command->second); if (--info->expectedReplies == 0) { //Check if it was transition or internal command. Don't send any replies in that case. if (info->sendReplyTo != NO_COMMANDER) { @@ -498,7 +429,7 @@ void DeviceHandlerBase::replyToReply(DeviceReplyMap::iterator iter, void DeviceHandlerBase::doSendWrite() { if (cookieInfo.state == COOKIE_WRITE_READY) { - ReturnValue_t result = communicationInterface->sendMessage(comCookie, + ReturnValue_t result = communicationInterface->sendMessage(cookie, rawPacket, rawPacketLen); if (result == RETURN_OK) { @@ -519,13 +450,12 @@ void DeviceHandlerBase::doGetWrite() { return; } cookieInfo.state = COOKIE_UNUSED; - ReturnValue_t result = communicationInterface->getSendSuccess(comCookie); + ReturnValue_t result = communicationInterface->getSendSuccess(cookie); if (result == RETURN_OK) { if (wiretappingMode == RAW) { replyRawData(rawPacket, rawPacketLen, requestedRawTraffic, true); } - //We need to distinguish here, because a raw command never expects a reply. - //(Could be done in eRIRM, but then child implementations need to be careful. + //We need to distinguish here, because a raw command never expects a reply. (Could be done in eRIRM, but then child implementations need to be careful. result = enableReplyInReplyMap(cookieInfo.pendingCommand); } else { //always generate a failure event, so that FDIR knows what's up @@ -539,25 +469,12 @@ void DeviceHandlerBase::doGetWrite() { } void DeviceHandlerBase::doSendRead() { - ReturnValue_t result = RETURN_FAILED; - size_t requestLen = 0; - // If the device handler can only request replies after a command - // has been sent, there should be only one reply enabled and the - // correct reply length will be mapped. - for(DeviceReplyIter iter = deviceReplyMap.begin(); - iter != deviceReplyMap.end();iter++) - { - if(iter->second.delayCycles != 0) { - requestLen = iter->second.replyLen; - break; - } - } + ReturnValue_t result; - result = communicationInterface->requestReceiveMessage(comCookie, requestLen); + result = communicationInterface->requestReceiveMessage(cookie); if (result == RETURN_OK) { cookieInfo.state = COOKIE_READ_SENT; - } - else { + } else { triggerEvent(DEVICE_REQUESTING_REPLY_FAILED, result); //We can't inform anyone, because we don't know which command was sent last. //So, we need to wait for a timeout. @@ -568,10 +485,10 @@ void DeviceHandlerBase::doSendRead() { } void DeviceHandlerBase::doGetRead() { - size_t receivedDataLen; + uint32_t receivedDataLen; uint8_t *receivedData; DeviceCommandId_t foundId = 0xFFFFFFFF; - size_t foundLen = 0; + uint32_t foundLen = 0; ReturnValue_t result; if (cookieInfo.state != COOKIE_READ_SENT) { @@ -581,7 +498,7 @@ void DeviceHandlerBase::doGetRead() { cookieInfo.state = COOKIE_UNUSED; - result = communicationInterface->readReceivedMessage(comCookie, &receivedData, + result = communicationInterface->readReceivedMessage(cookie, &receivedData, &receivedDataLen); if (result != RETURN_OK) { @@ -591,7 +508,7 @@ void DeviceHandlerBase::doGetRead() { return; } - if (receivedDataLen == 0 or result == DeviceCommunicationIF::NO_REPLY_RECEIVED) + if (receivedDataLen == 0) return; if (wiretappingMode == RAW) { @@ -622,8 +539,6 @@ void DeviceHandlerBase::doGetRead() { break; case IGNORE_REPLY_DATA: break; - case IGNORE_FULL_PACKET: - return; default: //We need to wait for timeout.. don't know what command failed and who sent it. replyRawReplyIfnotWiretapped(receivedData, foundLen); @@ -642,8 +557,8 @@ void DeviceHandlerBase::doGetRead() { } ReturnValue_t DeviceHandlerBase::getStorageData(store_address_t storageAddress, - uint8_t ** data, size_t * len) { - size_t lenTmp; + uint8_t * *data, uint32_t * len) { + uint32_t lenTmp; if (IPCStore == NULL) { *data = NULL; @@ -664,6 +579,84 @@ ReturnValue_t DeviceHandlerBase::getStorageData(store_address_t storageAddress, } +ReturnValue_t DeviceHandlerBase::initialize() { + ReturnValue_t result = SystemObject::initialize(); + if (result != RETURN_OK) { + return result; + } + + communicationInterface = objectManager->get( + deviceCommunicationId); + if (communicationInterface == NULL) { + return RETURN_FAILED; + } + + result = communicationInterface->open(&cookie, ioBoardAddress, + maxDeviceReplyLen); + if (result != RETURN_OK) { + return result; + } + + IPCStore = objectManager->get(objects::IPC_STORE); + if (IPCStore == NULL) { + return RETURN_FAILED; + } + + AcceptsDeviceResponsesIF *rawReceiver = objectManager->get< + AcceptsDeviceResponsesIF>(rawDataReceiverId); + + if (rawReceiver == NULL) { + return RETURN_FAILED; + } + + defaultRawReceiver = rawReceiver->getDeviceQueue(); + + powerSwitcher = objectManager->get(powerSwitcherId); + if (powerSwitcher == NULL) { + return RETURN_FAILED; + } + + result = healthHelper.initialize(); + if (result != RETURN_OK) { + return result; + } + + result = modeHelper.initialize(); + if (result != RETURN_OK) { + return result; + } + result = actionHelper.initialize(commandQueue); + if (result != RETURN_OK) { + return result; + } + result = fdirInstance->initialize(); + if (result != HasReturnvaluesIF::RETURN_OK) { + return result; + } + + result = parameterHelper.initialize(); + if (result != HasReturnvaluesIF::RETURN_OK) { + return result; + } + + result = hkSwitcher.initialize(); + if (result != HasReturnvaluesIF::RETURN_OK) { + return result; + } + + fillCommandAndReplyMap(); + + //Set temperature target state to NON_OP. + DataSet mySet; + PoolVariable thermalRequest(deviceThermalRequestPoolId, &mySet, + PoolVariableIF::VAR_WRITE); + mySet.read(); + thermalRequest = ThermalComponentIF::STATE_REQUEST_NON_OPERATIONAL; + mySet.commit(PoolVariableIF::VALID); + + return RETURN_OK; + +} void DeviceHandlerBase::replyRawData(const uint8_t *data, size_t len, MessageQueueId_t sendTo, bool isCommand) { @@ -679,6 +672,7 @@ void DeviceHandlerBase::replyRawData(const uint8_t *data, size_t len, } CommandMessage message; + DeviceHandlerMessage::setDeviceHandlerRawReplyMessage(&message, getObjectId(), address, isCommand); @@ -694,7 +688,7 @@ void DeviceHandlerBase::replyRawData(const uint8_t *data, size_t len, //Default child implementations -DeviceHandlerBase::CommunicationAction_t DeviceHandlerBase::getComAction() { +DeviceHandlerBase::RmapAction_t DeviceHandlerBase::getRmapAction() { switch (pstStep) { case 0: return SEND_WRITE; @@ -754,20 +748,20 @@ void DeviceHandlerBase::handleReply(const uint8_t* receivedData, } } -//ReturnValue_t DeviceHandlerBase::switchCookieChannel(object_id_t newChannelId) { -// DeviceCommunicationIF *newCommunication = objectManager->get< -// DeviceCommunicationIF>(newChannelId); -// -// if (newCommunication != NULL) { -// ReturnValue_t result = newCommunication->reOpen(cookie, logicalAddress, -// maxDeviceReplyLen, comParameter1, comParameter2); -// if (result != RETURN_OK) { -// return result; -// } -// return RETURN_OK; -// } -// return RETURN_FAILED; -//} +ReturnValue_t DeviceHandlerBase::switchCookieChannel(object_id_t newChannelId) { + DeviceCommunicationIF *newCommunication = objectManager->get< + DeviceCommunicationIF>(newChannelId); + + if (newCommunication != NULL) { + ReturnValue_t result = newCommunication->reOpen(cookie, ioBoardAddress, + maxDeviceReplyLen); + if (result != RETURN_OK) { + return result; + } + return RETURN_OK; + } + return RETURN_FAILED; +} void DeviceHandlerBase::buildRawDeviceCommand(CommandMessage* commandMessage) { storedRawData = DeviceHandlerMessage::getStoreAddress(commandMessage); @@ -777,8 +771,8 @@ void DeviceHandlerBase::buildRawDeviceCommand(CommandMessage* commandMessage) { replyReturnvalueToCommand(result, RAW_COMMAND_ID); storedRawData.raw = StorageManagerIF::INVALID_ADDRESS; } else { - cookieInfo.pendingCommand = deviceCommandMap. - find((DeviceCommandId_t) RAW_COMMAND_ID); + cookieInfo.pendingCommand = deviceCommandMap.find( + (DeviceCommandId_t) RAW_COMMAND_ID); cookieInfo.pendingCommand->second.isExecuting = true; cookieInfo.state = COOKIE_WRITE_READY; } @@ -817,7 +811,7 @@ ReturnValue_t DeviceHandlerBase::enableReplyInReplyMap( iter = deviceReplyMap.find(command->first); } if (iter != deviceReplyMap.end()) { - DeviceReplyInfo * info = &(iter->second); + DeviceReplyInfo *info = &(iter->second); info->delayCycles = info->maxDelayCycles; info->command = command; command->second.expectedReplies = expectedReplies; @@ -843,9 +837,8 @@ ReturnValue_t DeviceHandlerBase::getStateOfSwitches(void) { ReturnValue_t result = getSwitches(&switches, &numberOfSwitches); if ((result == RETURN_OK) && (numberOfSwitches != 0)) { while (numberOfSwitches > 0) { - if (powerSwitcher-> getSwitchState(switches[numberOfSwitches - 1]) - == PowerSwitchIF::SWITCH_OFF) - { + if (powerSwitcher->getSwitchState(switches[numberOfSwitches - 1]) + == PowerSwitchIF::SWITCH_OFF) { return PowerSwitchIF::SWITCH_OFF; } numberOfSwitches--; @@ -1051,18 +1044,16 @@ ReturnValue_t DeviceHandlerBase::handleDeviceHandlerMessage( } replyReturnvalueToCommand(RETURN_OK); return RETURN_OK; - case DeviceHandlerMessage::CMD_SWITCH_ADDRESS: + case DeviceHandlerMessage::CMD_SWITCH_IOBOARD: if (mode != MODE_OFF) { replyReturnvalueToCommand(WRONG_MODE_FOR_COMMAND); } else { - // rework in progress - result = RETURN_OK; - //result = switchCookieChannel( - // DeviceHandlerMessage::getIoBoardObjectId(message)); + result = switchCookieChannel( + DeviceHandlerMessage::getIoBoardObjectId(message)); if (result == RETURN_OK) { replyReturnvalueToCommand(RETURN_OK); } else { - replyReturnvalueToCommand(CANT_SWITCH_ADDRESS); + replyReturnvalueToCommand(CANT_SWITCH_IOBOARD); } } return RETURN_OK; @@ -1121,7 +1112,8 @@ void DeviceHandlerBase::handleDeviceTM(SerializeIF* data, // hiding of sender needed so the service will handle it as unexpected Data, no matter what state //(progress or completed) it is in - actionHelper.reportData(defaultRawReceiver, replyId, &wrapper, true); + actionHelper.reportData(defaultRawReceiver, replyId, &wrapper, + true); } } else { //unrequested/aperiodic replies @@ -1144,12 +1136,11 @@ void DeviceHandlerBase::handleDeviceTM(SerializeIF* data, } ReturnValue_t DeviceHandlerBase::executeAction(ActionId_t actionId, - MessageQueueId_t commandedBy, const uint8_t* data, size_t size) { + MessageQueueId_t commandedBy, const uint8_t* data, uint32_t size) { ReturnValue_t result = acceptExternalDeviceCommands(); if (result != HasReturnvaluesIF::RETURN_OK) { return result; } - DeviceCommandMap::iterator iter = deviceCommandMap.find(actionId); if (iter == deviceCommandMap.end()) { result = COMMAND_NOT_SUPPORTED; @@ -1168,7 +1159,7 @@ ReturnValue_t DeviceHandlerBase::executeAction(ActionId_t actionId, } void DeviceHandlerBase::buildInternalCommand(void) { - // Neither Raw nor Direct could build a command +//Neither Raw nor Direct could build a command ReturnValue_t result = NOTHING_TO_SEND; DeviceCommandId_t deviceCommandId = NO_COMMAND_ID; if (mode == MODE_NORMAL) { @@ -1186,13 +1177,12 @@ void DeviceHandlerBase::buildInternalCommand(void) { } else { return; } - if (result == NOTHING_TO_SEND) { return; } if (result == RETURN_OK) { - DeviceCommandMap::iterator iter = - deviceCommandMap.find(deviceCommandId); + DeviceCommandMap::iterator iter = deviceCommandMap.find( + deviceCommandId); if (iter == deviceCommandMap.end()) { result = COMMAND_NOT_SUPPORTED; } else if (iter->second.isExecuting) { @@ -1207,7 +1197,6 @@ void DeviceHandlerBase::buildInternalCommand(void) { cookieInfo.state = COOKIE_WRITE_READY; } } - if (result != RETURN_OK) { triggerEvent(DEVICE_BUILDING_COMMAND_FAILED, result, deviceCommandId); } @@ -1281,9 +1270,3 @@ void DeviceHandlerBase::changeHK(Mode_t mode, Submode_t submode, bool enable) { void DeviceHandlerBase::setTaskIF(PeriodicTaskIF* task_){ executingTask = task_; } - -void DeviceHandlerBase::debugInterface(uint8_t positionTracker, object_id_t objectId, uint32_t parameter) { -} - -void DeviceHandlerBase::performOperationHook() { -} diff --git a/devicehandlers/DeviceHandlerBase.h b/devicehandlers/DeviceHandlerBase.h index c162210c..756ad530 100644 --- a/devicehandlers/DeviceHandlerBase.h +++ b/devicehandlers/DeviceHandlerBase.h @@ -17,11 +17,10 @@ #include #include #include -#include #include +#include #include #include -#include namespace Factory{ void setStaticFrameworkObjectIds(); @@ -30,53 +29,29 @@ void setStaticFrameworkObjectIds(); class StorageManagerIF; /** - * @defgroup devices Devices + * \defgroup devices Devices * Contains all devices and the DeviceHandlerBase class. */ /** - * @brief This is the abstract base class for device handlers. - * @details - * Documentation: Dissertation Baetz p.138,139, p.141-149 + * \brief This is the abstract base class for device handlers. * - * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, - * communication with physical devices, using the @link DeviceCommunicationIF @endlink, - * and communication with commanding objects. + * Documentation: Dissertation Baetz p.138,139, p.141-149 + * SpaceWire Remote Memory Access Protocol (RMAP) + * + * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, the RMAP communication and the + * communication with commanding objects. * It inherits SystemObject and thus can be created by the ObjectManagerIF. * * This class uses the opcode of ExecutableObjectIF to perform a step-wise execution. - * For each step an RMAP action is selected and executed. - * If data has been received (GET_READ), the data will be interpreted. - * The action for each step can be defined by the child class but as most - * device handlers share a 4-call (sendRead-getRead-sendWrite-getWrite) structure, - * a default implementation is provided. NOTE: RMAP is a standard which is used for FLP. - * RMAP communication is not mandatory for projects implementing the FSFW. - * However, the communication principles are similar to RMAP as there are - * two write and two send calls involved. + * For each step an RMAP action is selected and executed. If data has been received (eg in case of an RMAP Read), the data will be interpreted. + * The action for each step can be defined by the child class but as most device handlers share a 4-call (Read-getRead-write-getWrite) structure, + * a default implementation is provided. * * Device handler instances should extend this class and implement the abstract functions. * Components and drivers can send so called cookies which are used for communication - * and contain information about the communcation (e.g. slave address for I2C or RMAP structs). - * The following abstract methods must be implemented by a device handler: - * 1. doStartUp() - * 2. doShutDown() - * 3. buildTransitionDeviceCommand() - * 4. buildNormalDeviceCommand() - * 5. buildCommandFromCommand() - * 6. fillCommandAndReplyMap() - * 7. scanForReply() - * 8. interpretDeviceReply() * - * Other important virtual methods with a default implementation - * are the getTransitionDelayMs() function and the getSwitches() function. - * Please ensure that getSwitches() returns DeviceHandlerIF::NO_SWITCHES if - * power switches are not implemented yet. Otherwise, the device handler will - * not transition to MODE_ON, even if setMode(MODE_ON) is called. - * If a transition to MODE_ON is desired without commanding, override the - * intialize() function and call setMode(_MODE_START_UP) before calling - * DeviceHandlerBase::initialize(). - * - * @ingroup devices + * \ingroup devices */ class DeviceHandlerBase: public DeviceHandlerIF, public HasReturnvaluesIF, @@ -92,66 +67,284 @@ public: * The constructor passes the objectId to the SystemObject(). * * @param setObjectId the ObjectId to pass to the SystemObject() Constructor - * @param maxDeviceReplyLen the largest allowed reply size + * @param maxDeviceReplyLen the length the RMAP getRead call will be sent with * @param setDeviceSwitch the switch the device is connected to, for devices using two switches, overwrite getSwitches() - * @param deviceCommuncation Communcation Interface object which is used to implement communication functions - * @param thermalStatePoolId - * @param thermalRequestPoolId - * @param fdirInstance - * @param cmdQueueSize */ - DeviceHandlerBase(object_id_t setObjectId, object_id_t deviceCommunication, - CookieIF * comCookie_, uint8_t setDeviceSwitch, - uint32_t thermalStatePoolId = PoolVariableIF::NO_PARAMETER, + DeviceHandlerBase(uint32_t ioBoardAddress, object_id_t setObjectId, + uint32_t maxDeviceReplyLen, uint8_t setDeviceSwitch, + object_id_t deviceCommunication, uint32_t thermalStatePoolId = + PoolVariableIF::NO_PARAMETER, uint32_t thermalRequestPoolId = PoolVariableIF::NO_PARAMETER, - FailureIsolationBase* fdirInstance = nullptr, size_t cmdQueueSize = 20); + FailureIsolationBase* fdirInstance = NULL, uint32_t cmdQueueSize = 20); + + virtual MessageQueueId_t getCommandQueue(void) const; + /** - * @brief This function is the device handler base core component and is called periodically. - * @details - * General sequence, showing where abstract virtual functions are called: - * If the State is SEND_WRITE: - * 1. Set the cookie state to COOKIE_UNUSED and read the command queue - * 2. Handles Device State Modes by calling doStateMachine(). - * This function calls callChildStatemachine() which calls the abstract functions - * doStartUp() and doShutDown() - * 3. Check switch states by calling checkSwitchStates() - * 4. Decrements counter for timeout of replies by calling decrementDeviceReplyMap() - * 5. Performs FDIR check for failures - * 6. Calls hkSwitcher.performOperation() - * 7. If the device mode is MODE_OFF, return RETURN_OK. Otherwise, perform the Action property - * and performs depending on value specified - * by input value counter. The child class tells base class what to do by setting this value. - * - SEND_WRITE: Send data or commands to device by calling doSendWrite() which calls - * sendMessage function of #communicationInterface - * and calls buildInternalCommand if the cookie state is COOKIE_UNUSED - * - GET_WRITE: Get ackknowledgement for sending by calling doGetWrite() which calls - * getSendSuccess of #communicationInterface. - * Calls abstract functions scanForReply() and interpretDeviceReply(). - * - SEND_READ: Request reading data from device by calling doSendRead() which calls - * requestReceiveMessage of #communcationInterface - * - GET_READ: Access requested reading data by calling doGetRead() which calls - * readReceivedMessage of #communicationInterface - * @param counter Specifies which Action to perform - * @return RETURN_OK for successful execution - */ + * This function is a core component and is called periodically. + * General sequence: + * If the State is SEND_WRITE: + * 1. Set the cookie state to COOKIE_UNUSED and read the command queue + * 2. Handles Device State Modes by calling doStateMachine(). + * This function calls callChildStatemachine() which calls the abstract functions + * doStartUp() and doShutDown() + * 3. Check switch states by calling checkSwitchStates() + * 4. Decrements counter for timeout of replies by calling decrementDeviceReplyMap() + * 5. Performs FDIR check for failures + * 6. Calls hkSwitcher.performOperation() + * 7. If the device mode is MODE_OFF, return RETURN_OK. Otherwise, perform the Action property + * and performs depending on value specified + * by input value counter. The child class tells base class what to do by setting this value. + * - SEND_WRITE: Send data or commands to device by calling doSendWrite() + * Calls abstract funtions buildNomalDeviceCommand() + * or buildTransitionDeviceCommand() + * - GET_WRITE: Get ackknowledgement for sending by calling doGetWrite(). + * Calls abstract functions scanForReply() and interpretDeviceReply(). + * - SEND_READ: Request reading data from device by calling doSendRead() + * - GET_READ: Access requested reading data by calling doGetRead() + * @param counter Specifies which Action to perform + * @return RETURN_OK for successful execution + */ virtual ReturnValue_t performOperation(uint8_t counter); - /** - * @brief Initializes the device handler - * @details - * Initialize Device Handler as system object and - * initializes all important helper classes. - * Calls fillCommandAndReplyMap(). - * @return - */ virtual ReturnValue_t initialize(); + /** + * + * @param parentQueueId + */ + virtual void setParentQueue(MessageQueueId_t parentQueueId); /** * Destructor. */ virtual ~DeviceHandlerBase(); + + ReturnValue_t executeAction(ActionId_t actionId, + MessageQueueId_t commandedBy, const uint8_t* data, uint32_t size); + Mode_t getTransitionSourceMode() const; + Submode_t getTransitionSourceSubMode() const; + virtual void getMode(Mode_t *mode, Submode_t *submode); + HealthState getHealth(); + ReturnValue_t setHealth(HealthState health); + virtual ReturnValue_t getParameter(uint8_t domainId, uint16_t parameterId, + ParameterWrapper *parameterWrapper, + const ParameterWrapper *newValues, uint16_t startAtIndex); + /** + * Implementation of ExecutableObjectIF function + * + * Used to setup the reference of the task, that executes this component + * @param task_ Pointer to the taskIF of this task + */ + virtual void setTaskIF(PeriodicTaskIF* task_); protected: + /** + * The Returnvalues id of this class, required by HasReturnvaluesIF + */ + static const uint8_t INTERFACE_ID = CLASS_ID::DEVICE_HANDLER_BASE; + + static const ReturnValue_t INVALID_CHANNEL = MAKE_RETURN_CODE(4); + static const ReturnValue_t APERIODIC_REPLY = MAKE_RETURN_CODE(5); + static const ReturnValue_t IGNORE_REPLY_DATA = MAKE_RETURN_CODE(6); +// static const ReturnValue_t ONE_SWITCH = MAKE_RETURN_CODE(8); +// static const ReturnValue_t TWO_SWITCHES = MAKE_RETURN_CODE(9); + static const ReturnValue_t NO_SWITCH = MAKE_RETURN_CODE(10); + static const ReturnValue_t COMMAND_MAP_ERROR = MAKE_RETURN_CODE(11); + static const ReturnValue_t NOTHING_TO_SEND = MAKE_RETURN_CODE(12); + + //Mode handling error Codes + static const ReturnValue_t CHILD_TIMEOUT = MAKE_RETURN_CODE(0xE1); + static const ReturnValue_t SWITCH_FAILED = MAKE_RETURN_CODE(0xE2); + + static const DeviceCommandId_t RAW_COMMAND_ID = -1; + static const DeviceCommandId_t NO_COMMAND_ID = -2; + static const MessageQueueId_t NO_COMMANDER = 0; + + /** + * Pointer to the raw packet that will be sent. + */ + uint8_t *rawPacket; + /** + * Size of the #rawPacket. + */ + uint32_t rawPacketLen; + + /** + * The mode the device handler is currently in. + * + * This should never be changed directly but only with setMode() + */ + Mode_t mode; + + /** + * The submode the device handler is currently in. + * + * This should never be changed directly but only with setMode() + */ + Submode_t submode; + + /** + * This is the counter value from performOperation(). + */ + uint8_t pstStep; + + /** + * This will be used in the RMAP getRead command as expected length, is set by the constructor, can be modiefied at will. + */ + const uint32_t maxDeviceReplyLen; + + /** + * wiretapping flag: + * + * indicates either that all raw messages to and from the device should be sent to #theOneWhoWantsToReadRawTraffic + * or that all device TM should be downlinked to #theOneWhoWantsToReadRawTraffic + */ + enum WiretappingMode { + OFF = 0, RAW = 1, TM = 2 + } wiretappingMode; + + /** + * A message queue that accepts raw replies + * + * Statically initialized in initialize() to a configurable object. Used when there is no method + * of finding a recipient, ie raw mode and reporting erreonous replies + */ + MessageQueueId_t defaultRawReceiver; + + store_address_t storedRawData; + + /** + * the message queue which wants to read all raw traffic + * + * if #isWiretappingActive all raw communication from and to the device will be sent to this queue + */ + MessageQueueId_t requestedRawTraffic; + + /** + * the object used to set power switches + */ + PowerSwitchIF *powerSwitcher; + + /** + * Pointer to the IPCStore. + * + * This caches the pointer received from the objectManager in the constructor. + */ + StorageManagerIF *IPCStore; + + /** + * cached for init + */ + object_id_t deviceCommunicationId; + + /** + * Communication object used for device communication + */ + DeviceCommunicationIF *communicationInterface; + + /** + * Cookie used for communication + */ + Cookie *cookie; + + /** + * The MessageQueue used to receive device handler commands and to send replies. + */ + MessageQueueIF* commandQueue; + + /** + * this is the datapool variable with the thermal state of the device + * + * can be set to PoolVariableIF::NO_PARAMETER to deactivate thermal checking + */ + uint32_t deviceThermalStatePoolId; + + /** + * this is the datapool variable with the thermal request of the device + * + * can be set to PoolVariableIF::NO_PARAMETER to deactivate thermal checking + */ + uint32_t deviceThermalRequestPoolId; + + /** + * Taking care of the health + */ + HealthHelper healthHelper; + + ModeHelper modeHelper; + + ParameterHelper parameterHelper; + + /** + * Optional Error code + * Can be set in doStartUp(), doShutDown() and doTransition() to signal cause for Transition failure. + */ + ReturnValue_t childTransitionFailure; + + uint32_t ignoreMissedRepliesCount; //!< Counts if communication channel lost a reply, so some missed replys can be ignored. + + FailureIsolationBase* fdirInstance; //!< Pointer to the used FDIR instance. If not provided by child, default class is instantiated. + + HkSwitchHelper hkSwitcher; + + bool defaultFDIRUsed; //!< To correctly delete the default instance. + + bool switchOffWasReported; //!< Indicates if SWITCH_WENT_OFF was already thrown. + + PeriodicTaskIF* executingTask;//!< Pointer to the task which executes this component, is invalid before setTaskIF was called. + + static object_id_t powerSwitcherId; //!< Object which switches power on and off. + + static object_id_t rawDataReceiverId; //!< Object which receives RAW data by default. + + static object_id_t defaultFDIRParentId; //!< Object which may be the root cause of an identified fault. + /** + * Helper function to report a missed reply + * + * Can be overwritten by children to act on missed replies or to fake reporting Id. + * + * @param id of the missed reply + */ + virtual void missedReply(DeviceCommandId_t id); + + /** + * Send a reply to a received device handler command. + * + * This also resets #DeviceHandlerCommand to 0. + * + * @param reply the reply type + * @param parameter parameter for the reply + */ + void replyReturnvalueToCommand(ReturnValue_t status, + uint32_t parameter = 0); + + /** + * + + * @param parameter2 additional parameter + */ + void replyToCommand(ReturnValue_t status, uint32_t parameter = 0); + + /** + * Set the device handler mode + * + * Sets #timeoutStart with every call. + * + * Sets #transitionTargetMode if necessary so transitional states can be entered from everywhere without breaking the state machine + * (which relies on a correct #transitionTargetMode). + * + * The submode is left unchanged. + * + * + * @param newMode + */ + void setMode(Mode_t newMode); + + /** + * @overload + * @param submode + */ + void setMode(Mode_t newMode, Submode_t submode); + /** * This is used to let the child class handle the transition from mode @c _MODE_START_UP to @c MODE_ON * @@ -187,457 +380,6 @@ protected: */ virtual void doShutDown() = 0; - /** - * Build the device command to send for normal mode. - * - * This is only called in @c MODE_NORMAL. If multiple submodes for @c MODE_NORMAL are supported, - * different commands can built returned depending on the submode. - * - * #rawPacket and #rawPacketLen must be set by this method to the packet to be sent. - * If variable command frequence is required, a counter can be used and - * the frequency in the reply map has to be set manually - * by calling updateReplyMap(). - * - * @param[out] id the device command id that has been built - * @return - * - @c RETURN_OK to send command after setting #rawPacket and #rawPacketLen. - * - @c NOTHING_TO_SEND when no command is to be sent. - * - Anything else triggers an even with the returnvalue as a parameter. - */ - virtual ReturnValue_t buildNormalDeviceCommand(DeviceCommandId_t * id) = 0; - - /** - * Build the device command to send for a transitional mode. - * - * This is only called in @c _MODE_TO_NORMAL, @c _MODE_TO_ON, @c _MODE_TO_RAW, - * @c _MODE_START_UP and @c _MODE_TO_POWER_DOWN. So it is used by doStartUp() and doShutDown() as well as doTransition() - * - * A good idea is to implement a flag indicating a command has to be built and a variable containing the command number to be built - * and filling them in doStartUp(), doShutDown() and doTransition() so no modes have to be checked here. - * - * #rawPacket and #rawPacketLen must be set by this method to the packet to be sent. - * - * @param[out] id the device command id built - * @return - * - @c RETURN_OK when a command is to be sent - * - @c NOTHING_TO_SEND when no command is to be sent - * - Anything else triggers an even with the returnvalue as a parameter - */ - virtual ReturnValue_t buildTransitionDeviceCommand(DeviceCommandId_t * id) = 0; - - /** - * @brief Build a device command packet from data supplied by a direct command. - * - * @details - * #rawPacket and #rawPacketLen should be set by this method to the packet to be sent. - * The existence of the command in the command map and the command size check - * against 0 are done by the base class. - * - * @param deviceCommand the command to build, already checked against deviceCommandMap - * @param commandData pointer to the data from the direct command - * @param commandDataLen length of commandData - * @return - * - @c RETURN_OK to send command after #rawPacket and #rawPacketLen have been set. - * - Anything else triggers an event with the returnvalue as a parameter - */ - virtual ReturnValue_t buildCommandFromCommand(DeviceCommandId_t deviceCommand, - const uint8_t * commandData, size_t commandDataLen) = 0; - - /** - * @brief fill the #deviceCommandMap - * called by the initialize() of the base class - * @details - * This is used to let the base class know which replies are expected. - * There are different scenarios regarding this: - * - "Normal" commands. These are commands, that trigger a direct reply from the device. - * In this case, the id of the command should be added to the command map - * with a commandData_t where maxDelayCycles is set to the maximum expected - * number of PST cycles the reply will take. Then, scanForReply returns - * the id of the command and the base class can handle time-out and missing replies. - * - Periodic, unrequested replies. These are replies that, once enabled, are sent by the device - * on its own in a defined interval. In this case, the id of the reply - * or a placeholder id should be added to the deviceCommandMap with a commandData_t - * where maxDelayCycles is set to the maximum expected number of PST cycles between - * two replies (also a tolerance should be added, as an FDIR message will be generated if it is missed). - * As soon as the replies are enabled, DeviceCommandInfo.periodic must be set to 1, - * DeviceCommandInfo.delayCycles to DeviceCommandInfo.MaxDelayCycles. - * From then on, the base class handles the reception. - * Then, scanForReply returns the id of the reply or the placeholder id and the base class will - * take care of checking that all replies are received and the interval is correct. - * When the replies are disabled, DeviceCommandInfo.periodic must be set to 0, - * DeviceCommandInfo.delayCycles to 0; - * - Aperiodic, unrequested replies. These are replies that are sent - * by the device without any preceding command and not in a defined interval. - * These are not entered in the deviceCommandMap but handled by returning @c APERIODIC_REPLY in scanForReply(). - * - */ - virtual void fillCommandAndReplyMap() = 0; - - /** - * @brief Scans a buffer for a valid reply. - * @details - * This is used by the base class to check the data received for valid packets. - * It only checks if a valid packet starts at @c start. - * It also only checks the structural validy of the packet, - * e.g. checksums lengths and protocol data. - * No information check is done, e.g. range checks etc. - * - * Errors should be reported directly, the base class does NOT report - * any errors based on the returnvalue of this function. - * - * @param start start of remaining buffer to be scanned - * @param len length of remaining buffer to be scanned - * @param[out] foundId the id of the data found in the buffer. - * @param[out] foundLen length of the data found. Is to be set in function, - * buffer is scanned at previous position + foundLen. - * @return - * - @c RETURN_OK a valid packet was found at @c start, @c foundLen is valid - * - @c RETURN_FAILED no reply could be found starting at @c start, - * implies @c foundLen is not valid, - * base class will call scanForReply() again with ++start - * - @c DeviceHandlerIF::INVALID_DATA a packet was found but it is invalid, - * e.g. checksum error, implies @c foundLen is valid, can be used to skip some bytes - * - @c DeviceHandlerIF::LENGTH_MISSMATCH @c len is invalid - * - @c DeviceHandlerIF::IGNORE_REPLY_DATA Ignore this specific part of the packet - * - @c DeviceHandlerIF::IGNORE_FULL_PACKET Ignore the packet - * - @c APERIODIC_REPLY if a valid reply is received that has not been - * requested by a command, but should be handled anyway - * (@see also fillCommandAndCookieMap() ) - */ - virtual ReturnValue_t scanForReply(const uint8_t *start, size_t remainingSize, - DeviceCommandId_t *foundId, size_t *foundLen) = 0; - - /** - * @brief Interpret a reply from the device. - * @details - * This is called after scanForReply() found a valid packet, it can be assumed that the length and structure is valid. - * This routine extracts the data from the packet into a DataSet and then calls handleDeviceTM(), which either sends - * a TM packet or stores the data in the DataPool depending on whether the it was an external command. - * No packet length is given, as it should be defined implicitly by the id. - * - * @param id the id found by scanForReply() - * @param packet - * @return - * - @c RETURN_OK when the reply was interpreted. - * - @c RETURN_FAILED when the reply could not be interpreted, eg. logical errors or range violations occurred - */ - virtual ReturnValue_t interpretDeviceReply(DeviceCommandId_t id, - const uint8_t *packet) = 0; - - /** - * set all datapool variables that are update periodically in normal mode invalid - * - * Child classes should provide an implementation which sets all those variables invalid - * which are set periodically during any normal mode. - */ - virtual void setNormalDatapoolEntriesInvalid() = 0; - - /** - * @brief Can be implemented by child handler to - * perform debugging - * @details Example: Calling this in performOperation - * to track values like mode. - * @param positionTracker Provide the child handler a way to know where the debugInterface was called - * @param objectId Provide the child handler object Id to specify actions for spefic devices - * @param parameter Supply a parameter of interest - * Please delete all debugInterface calls in DHB after debugging is finished ! - */ - virtual void debugInterface(uint8_t positionTracker = 0, object_id_t objectId = 0, uint32_t parameter = 0); - - /** - * Get the time needed to transit from modeFrom to modeTo. - * - * Used for the following transitions: - * modeFrom -> modeTo: - * - MODE_ON -> [MODE_ON, MODE_NORMAL, MODE_RAW, _MODE_POWER_DOWN] - * - MODE_NORMAL -> [MODE_ON, MODE_NORMAL, MODE_RAW, _MODE_POWER_DOWN] - * - MODE_RAW -> [MODE_ON, MODE_NORMAL, MODE_RAW, _MODE_POWER_DOWN] - * - _MODE_START_UP -> MODE_ON (do not include time to set the switches, the base class got you covered) - * - * The default implementation returns 0 ! - * @param modeFrom - * @param modeTo - * @return time in ms - */ - virtual uint32_t getTransitionDelayMs(Mode_t modeFrom, Mode_t modeTo); - - /** - * Return the switches connected to the device. - * - * The default implementation returns one switch set in the ctor. - * - * @param[out] switches pointer to an array of switches - * @param[out] numberOfSwitches length of returned array - * @return - * - @c RETURN_OK if the parameters were set - * - @c NO_SWITCH or any other returnvalue if no switches exist - */ - virtual ReturnValue_t getSwitches(const uint8_t **switches, - uint8_t *numberOfSwitches); - - /** - * Can be used to perform device specific periodic operations. - * This is called on the SEND_READ step of the performOperation() call - */ - virtual void performOperationHook(); - - /** - * The Returnvalues id of this class, required by HasReturnvaluesIF - */ - static const uint8_t INTERFACE_ID = CLASS_ID::DEVICE_HANDLER_BASE; - -public: - /** - * @param parentQueueId - */ - virtual void setParentQueue(MessageQueueId_t parentQueueId); - - /** - * This function call handles the execution of external commands as required - * by the HasActionIF. - * @param actionId - * @param commandedBy - * @param data - * @param size - * @return - */ - ReturnValue_t executeAction(ActionId_t actionId, - MessageQueueId_t commandedBy, const uint8_t* data, size_t size); - - Mode_t getTransitionSourceMode() const; - Submode_t getTransitionSourceSubMode() const; - virtual void getMode(Mode_t *mode, Submode_t *submode); - HealthState getHealth(); - ReturnValue_t setHealth(HealthState health); - virtual ReturnValue_t getParameter(uint8_t domainId, uint16_t parameterId, - ParameterWrapper *parameterWrapper, - const ParameterWrapper *newValues, uint16_t startAtIndex); - /** - * Implementation of ExecutableObjectIF function - * - * Used to setup the reference of the task, that executes this component - * @param task_ Pointer to the taskIF of this task - */ - virtual void setTaskIF(PeriodicTaskIF* task_); - virtual MessageQueueId_t getCommandQueue(void) const; - -protected: - //Mode handling error Codes - static const ReturnValue_t CHILD_TIMEOUT = MAKE_RETURN_CODE(0xE1); - static const ReturnValue_t SWITCH_FAILED = MAKE_RETURN_CODE(0xE2); - - static const DeviceCommandId_t RAW_COMMAND_ID = -1; - static const DeviceCommandId_t NO_COMMAND_ID = -2; - static const MessageQueueId_t NO_COMMANDER = 0; - - /** - * Pointer to the raw packet that will be sent. - */ - uint8_t *rawPacket = nullptr; - /** - * Size of the #rawPacket. - */ - size_t rawPacketLen = 0; - - /** - * The mode the device handler is currently in. - * - * This should never be changed directly but only with setMode() - */ - Mode_t mode; - - /** - * The submode the device handler is currently in. - * - * This should never be changed directly but only with setMode() - */ - Submode_t submode; - - /** - * This is the counter value from performOperation(). - */ - uint8_t pstStep = 0; - - /** - * wiretapping flag: - * - * indicates either that all raw messages to and from the device should be sent to #theOneWhoWantsToReadRawTraffic - * or that all device TM should be downlinked to #theOneWhoWantsToReadRawTraffic - */ - enum WiretappingMode: uint8_t { - OFF = 0, RAW = 1, TM = 2 - } wiretappingMode; - - /** - * A message queue that accepts raw replies - * - * Statically initialized in initialize() to a configurable object. Used when there is no method - * of finding a recipient, ie raw mode and reporting erreonous replies - */ - MessageQueueId_t defaultRawReceiver = 0; - - store_address_t storedRawData; - - /** - * the message queue which wants to read all raw traffic - * - * if #isWiretappingActive all raw communication from and to the device will be sent to this queue - */ - MessageQueueId_t requestedRawTraffic = 0; - - /** - * the object used to set power switches - */ - PowerSwitchIF *powerSwitcher = nullptr; - - /** - * Pointer to the IPCStore. - * - * This caches the pointer received from the objectManager in the constructor. - */ - StorageManagerIF *IPCStore = nullptr; - - /** - * cached for init - */ - object_id_t deviceCommunicationId; - - /** - * Communication object used for device communication - */ - DeviceCommunicationIF *communicationInterface = nullptr; - - /** - * Cookie used for communication. This is passed to the communication - * interface. - */ - CookieIF *comCookie; - - struct DeviceCommandInfo { - bool isExecuting; //!< Indicates if the command is already executing. - uint8_t expectedReplies; //!< Dynamic value to indicate how many replies are expected. Inititated with 0. - MessageQueueId_t sendReplyTo; //!< if this is != NO_COMMANDER, DHB was commanded externally and shall report everything to commander. - }; - typedef std::map DeviceCommandMap; - typedef DeviceCommandMap::iterator DeviceCommandIter; - - /** - * @brief Information about expected replies - * - * This is used to keep track of pending replies - */ - struct DeviceReplyInfo { - uint16_t maxDelayCycles; //!< The maximum number of cycles the handler should wait for a reply to this command. - uint16_t delayCycles; //!< The currently remaining cycles the handler should wait for a reply, 0 means there is no reply expected - size_t replyLen = 0; //!< Expected size of the reply. - uint8_t periodic; //!< if this is !=0, the delayCycles will not be reset to 0 but to maxDelayCycles - DeviceCommandMap::iterator command; //!< The command that expects this reply. - }; - - typedef std::map DeviceReplyMap; - typedef DeviceReplyMap::iterator DeviceReplyIter; - - /** - * The MessageQueue used to receive device handler commands and to send replies. - */ - MessageQueueIF* commandQueue = nullptr; - - /** - * this is the datapool variable with the thermal state of the device - * - * can be set to PoolVariableIF::NO_PARAMETER to deactivate thermal checking - */ - uint32_t deviceThermalStatePoolId; - - /** - * this is the datapool variable with the thermal request of the device - * - * can be set to PoolVariableIF::NO_PARAMETER to deactivate thermal checking - */ - uint32_t deviceThermalRequestPoolId; - - /** - * Taking care of the health - */ - HealthHelper healthHelper; - - ModeHelper modeHelper; - - ParameterHelper parameterHelper; - - /** - * Optional Error code - * Can be set in doStartUp(), doShutDown() and doTransition() to signal cause for Transition failure. - */ - ReturnValue_t childTransitionFailure = RETURN_OK; - - uint32_t ignoreMissedRepliesCount = 0; //!< Counts if communication channel lost a reply, so some missed replys can be ignored. - - FailureIsolationBase* fdirInstance; //!< Pointer to the used FDIR instance. If not provided by child, default class is instantiated. - - HkSwitchHelper hkSwitcher; - - bool defaultFDIRUsed; //!< To correctly delete the default instance. - - bool switchOffWasReported; //!< Indicates if SWITCH_WENT_OFF was already thrown. - - PeriodicTaskIF* executingTask;//!< Pointer to the task which executes this component, is invalid before setTaskIF was called. - - static object_id_t powerSwitcherId; //!< Object which switches power on and off. - - static object_id_t rawDataReceiverId; //!< Object which receives RAW data by default. - - static object_id_t defaultFDIRParentId; //!< Object which may be the root cause of an identified fault. - - /** - * Set the device handler mode - * - * Sets #timeoutStart with every call. - * - * Sets #transitionTargetMode if necessary so transitional states can be entered from everywhere without breaking the state machine - * (which relies on a correct #transitionTargetMode). - * - * The submode is left unchanged. - * - * - * @param newMode - */ - void setMode(Mode_t newMode); - - /** - * @overload - * @param submode - */ - void setMode(Mode_t newMode, Submode_t submode); - - /** - * Helper function to report a missed reply - * - * Can be overwritten by children to act on missed replies or to fake reporting Id. - * - * @param id of the missed reply - */ - virtual void missedReply(DeviceCommandId_t id); - - /** - * Send a reply to a received device handler command. - * - * This also resets #DeviceHandlerCommand to 0. - * - * @param reply the reply type - * @param parameter parameter for the reply - */ - void replyReturnvalueToCommand(ReturnValue_t status, - uint32_t parameter = 0); - - /** - * Send reply to a command, differentiate between raw command - * and normal command. - * @param status - * @param parameter - */ - void replyToCommand(ReturnValue_t status, uint32_t parameter = 0); - /** * Do the transition to the main modes (MODE_ON, MODE_NORMAL and MODE_RAW). * @@ -667,18 +409,144 @@ protected: */ virtual void doTransition(Mode_t modeFrom, Submode_t subModeFrom); + /** + * Get the time needed to transit from modeFrom to modeTo. + * + * Used for the following transitions: + * modeFrom -> modeTo: + * MODE_ON -> [MODE_ON, MODE_NORMAL, MODE_RAW, _MODE_POWER_DOWN] + * MODE_NORMAL -> [MODE_ON, MODE_NORMAL, MODE_RAW, _MODE_POWER_DOWN] + * MODE_RAW -> [MODE_ON, MODE_NORMAL, MODE_RAW, _MODE_POWER_DOWN] + * _MODE_START_UP -> MODE_ON (do not include time to set the switches, the base class got you covered) + * + * The default implementation returns 0; + * + * @param modeFrom + * @param modeTo + * @return time in ms + */ + virtual uint32_t getTransitionDelayMs(Mode_t modeFrom, Mode_t modeTo); + + /** + * Is the combination of mode and submode valid? + * + * @param mode + * @param submode + * @return + * - @c RETURN_OK if valid + * - @c RETURN_FAILED if invalid + */ + virtual ReturnValue_t isModeCombinationValid(Mode_t mode, + Submode_t submode); + + /** + * Get the Rmap action for the current step. + * + * The step number can be read from #pstStep. + * + * @return The Rmap action to execute in this step + */ + virtual RmapAction_t getRmapAction(); + + /** + * Build the device command to send for normal mode. + * + * This is only called in @c MODE_NORMAL. If multiple submodes for @c MODE_NORMAL are supported, + * different commands can built returned depending on the submode. + * + * #rawPacket and #rawPacketLen must be set by this method to the packet to be sent. + * + * @param[out] id the device command id that has been built + * @return + * - @c RETURN_OK when a command is to be sent + * - not @c RETURN_OK when no command is to be sent + */ + virtual ReturnValue_t buildNormalDeviceCommand(DeviceCommandId_t * id) = 0; + + /** + * Build the device command to send for a transitional mode. + * + * This is only called in @c _MODE_TO_NORMAL, @c _MODE_TO_ON, @c _MODE_TO_RAW, + * @c _MODE_START_UP and @c _MODE_TO_POWER_DOWN. So it is used by doStartUp() and doShutDown() as well as doTransition() + * + * A good idea is to implement a flag indicating a command has to be built and a variable containing the command number to be built + * and filling them in doStartUp(), doShutDown() and doTransition() so no modes have to be checked here. + * + * #rawPacket and #rawPacketLen must be set by this method to the packet to be sent. + * + * @param[out] id the device command id built + * @return + * - @c RETURN_OK when a command is to be sent + * - not @c RETURN_OK when no command is to be sent + */ + virtual ReturnValue_t buildTransitionDeviceCommand( + DeviceCommandId_t * id) = 0; + + /** + * Build the device command to send for raw mode. + * + * This is only called in @c MODE_RAW. It is for the rare case that in raw mode packets + * are to be sent by the handler itself. It is NOT needed for the raw commanding service. + * Its only current use is in the STR handler which gets its raw packets from a different + * source. + * Also it can be used for transitional commands, to get the device ready for @c MODE_RAW + * + * As it is almost never used, there is a default implementation returning @c NOTHING_TO_SEND. + * + * #rawPacket and #rawPacketLen must be set by this method to the packet to be sent. + * + * @param[out] id the device command id built + * @return + * - @c RETURN_OK when a command is to be sent + * - not @c NOTHING_TO_SEND when no command is to be sent + */ + virtual ReturnValue_t buildChildRawCommand(); + + /** + * Build a device command packet from data supplied by a direct command. + * + * #rawPacket and #rawPacketLen should be set by this method to the packet to be sent. + * + * @param deviceCommand the command to build, already checked against deviceCommandMap + * @param commandData pointer to the data from the direct command + * @param commandDataLen length of commandData + * @return + * - @c RETURN_OK when #rawPacket is valid + * - @c RETURN_FAILED when #rawPacket is invalid and no data should be sent + */ + virtual ReturnValue_t buildCommandFromCommand( + DeviceCommandId_t deviceCommand, const uint8_t * commandData, + size_t commandDataLen) = 0; + + /** + * fill the #deviceCommandMap + * + * called by the initialize() of the base class + * + * This is used to let the base class know which replies are expected. + * There are different scenarios regarding this: + * - "Normal" commands. These are commands, that trigger a direct reply from the device. In this case, the id of the command should be added to the command map + * with a commandData_t where maxDelayCycles is set to the maximum expected number of PST cycles the reply will take. Then, scanForReply returns the id of the command and the base class can handle time-out and missing replies. + * - Periodic, unrequested replies. These are replies that, once enabled, are sent by the device on its own in a defined interval. In this case, the id of the reply or a placeholder id should be added to the deviceCommandMap + * with a commandData_t where maxDelayCycles is set to the maximum expected number of PST cycles between two replies (also a tolerance should be added, as an FDIR message will be generated if it is missed). + * As soon as the replies are enabled, DeviceCommandInfo.periodic must be set to 1, DeviceCommandInfo.delayCycles to DeviceCommandInfo.MaxDelayCycles. From then on, the base class handles the reception. + * Then, scanForReply returns the id of the reply or the placeholder id and the base class will take care of checking that all replies are received and the interval is correct. + * When the replies are disabled, DeviceCommandInfo.periodic must be set to 0, DeviceCommandInfo.delayCycles to 0; + * - Aperiodic, unrequested replies. These are replies that are sent by the device without any preceding command and not in a defined interval. These are not entered in the deviceCommandMap but handled by returning @c APERIODIC_REPLY in scanForReply(). + * + */ + virtual void fillCommandAndReplyMap() = 0; + /** * This is a helper method to facilitate inserting entries in the command map. * @param deviceCommand Identifier of the command to add. * @param maxDelayCycles The maximum number of delay cycles the command waits until it times out. - * @param periodic Indicates if the reply is periodic (i.e. it is sent by the device repeatedly without request) or not. + * @param periodic Indicates if the command is periodic (i.e. it is sent by the device repeatedly without request) or not. * Default is aperiodic (0) - * @param hasDifferentReplyId - * @param replyId * @return RETURN_OK when the command was successfully inserted, COMMAND_MAP_ERROR else. */ ReturnValue_t insertInCommandAndReplyMap(DeviceCommandId_t deviceCommand, - uint16_t maxDelayCycles, size_t replyLen = 0, uint8_t periodic = 0, + uint16_t maxDelayCycles, uint8_t periodic = 0, bool hasDifferentReplyId = false, DeviceCommandId_t replyId = 0); /** * This is a helper method to insert replies in the reply map. @@ -689,7 +557,7 @@ protected: * @return RETURN_OK when the command was successfully inserted, COMMAND_MAP_ERROR else. */ ReturnValue_t insertInReplyMap(DeviceCommandId_t deviceCommand, - uint16_t maxDelayCycles, size_t replyLen = 0, uint8_t periodic = 0); + uint16_t maxDelayCycles, uint8_t periodic = 0); /** * A simple command to add a command to the commandList. * @param deviceCommand The command to add @@ -715,47 +583,48 @@ protected: * @return The current delay count. If the command does not exist (should never happen) it returns 0. */ uint8_t getReplyDelayCycles(DeviceCommandId_t deviceCommand); - /** - * Is the combination of mode and submode valid? + * Scans a buffer for a valid reply. * - * @param mode - * @param submode + * This is used by the base class to check the data received from the RMAP stack for valid packets. + * It only checks if a valid packet starts at @c start. + * It also only checks the structural validy of the packet, eg checksums lengths and protocol data. No + * information check is done, eg range checks etc. + * + * Errors should be reported directly, the base class does NOT report any errors based on the return + * value of this function. + * + * @param start start of data + * @param len length of data + * @param[out] foundId the id of the packet starting at @c start + * @param[out] foundLen length of the packet found * @return - * - @c RETURN_OK if valid - * - @c RETURN_FAILED if invalid + * - @c RETURN_OK a valid packet was found at @c start, @c foundLen is valid + * - @c NO_VALID_REPLY no reply could be found starting at @c start, implies @c foundLen is not valid, base class will call scanForReply() again with ++start + * - @c INVALID_REPLY a packet was found but it is invalid, eg checksum error, implies @c foundLen is valid, can be used to skip some bytes + * - @c TOO_SHORT @c len is too short for any valid packet + * - @c APERIODIC_REPLY if a valid reply is received that has not been requested by a command, but should be handled anyway (@see also fillCommandAndCookieMap() ) */ - virtual ReturnValue_t isModeCombinationValid(Mode_t mode, - Submode_t submode); + virtual ReturnValue_t scanForReply(const uint8_t *start, uint32_t len, + DeviceCommandId_t *foundId, uint32_t *foundLen) = 0; /** - * Get the Rmap action for the current step. + * Interpret a reply from the device. * - * The step number can be read from #pstStep. + * This is called after scanForReply() found a valid packet, it can be assumed that the length and structure is valid. + * This routine extracts the data from the packet into a DataSet and then calls handleDeviceTM(), which either sends + * a TM packet or stores the data in the DataPool depending on whether the it was an external command. + * No packet length is given, as it should be defined implicitly by the id. * - * @return The Rmap action to execute in this step - */ - virtual CommunicationAction_t getComAction(); - - /** - * Build the device command to send for raw mode. - * - * This is only called in @c MODE_RAW. It is for the rare case that in raw mode packets - * are to be sent by the handler itself. It is NOT needed for the raw commanding service. - * Its only current use is in the STR handler which gets its raw packets from a different - * source. - * Also it can be used for transitional commands, to get the device ready for @c MODE_RAW - * - * As it is almost never used, there is a default implementation returning @c NOTHING_TO_SEND. - * - * #rawPacket and #rawPacketLen must be set by this method to the packet to be sent. - * - * @param[out] id the device command id built + * @param id the id found by scanForReply() + * @param packet + * @param commander the one who initiated the command, is 0 if not external commanded * @return - * - @c RETURN_OK when a command is to be sent - * - not @c NOTHING_TO_SEND when no command is to be sent + * - @c RETURN_OK when the reply was interpreted. + * - @c RETURN_FAILED when the reply could not be interpreted, eg. logical errors or range violations occurred */ - virtual ReturnValue_t buildChildRawCommand(); + virtual ReturnValue_t interpretDeviceReply(DeviceCommandId_t id, + const uint8_t *packet) = 0; /** * Construct a command reply containing a raw reply. @@ -780,11 +649,33 @@ protected: */ void replyRawReplyIfnotWiretapped(const uint8_t *data, size_t len); + /** + * Return the switches connected to the device. + * + * The default implementation returns one switch set in the ctor. + * + * + * @param[out] switches pointer to an array of switches + * @param[out] numberOfSwitches length of returned array + * @return + * - @c RETURN_OK if the parameters were set + * - @c RETURN_FAILED if no switches exist + */ + virtual ReturnValue_t getSwitches(const uint8_t **switches, + uint8_t *numberOfSwitches); + /** * notify child about mode change */ virtual void modeChanged(void); + struct DeviceCommandInfo { + bool isExecuting; //!< Indicates if the command is already executing. + uint8_t expectedReplies; //!< Dynamic value to indicate how many replies are expected. + MessageQueueId_t sendReplyTo; //!< if this is != NO_COMMANDER, DHB was commanded externally and shall report everything to commander. + }; + + typedef std::map DeviceCommandMap; /** * Enable the reply checking for a command * @@ -795,16 +686,16 @@ protected: * When found, copies maxDelayCycles to delayCycles in the reply information and sets the command to * expect one reply. * - * Can be overwritten by the child, if a command activates multiple replies - * or replyId differs from commandId. + * Can be overwritten by the child, if a command activates multiple replies or replyId differs from + * commandId. * Notes for child implementations: * - If the command was not found in the reply map, NO_REPLY_EXPECTED MUST be returned. * - A failure code may be returned if something went fundamentally wrong. * * @param deviceCommand * @return - RETURN_OK if a reply was activated. - * - NO_REPLY_EXPECTED if there was no reply found. This is not an - * error case as many commands do not expect a reply. + * - NO_REPLY_EXPECTED if there was no reply found. This is not an error case as many commands + * do not expect a reply. */ virtual ReturnValue_t enableReplyInReplyMap(DeviceCommandMap::iterator cmd, uint8_t expectedReplies = 1, bool useAlternateId = false, @@ -820,6 +711,14 @@ protected: */ ReturnValue_t getStateOfSwitches(void); + /** + * set all datapool variables that are update periodically in normal mode invalid + * + * Child classes should provide an implementation which sets all those variables invalid + * which are set periodically during any normal mode. + */ + virtual void setNormalDatapoolEntriesInvalid() = 0; + /** * build a list of sids and pass it to the #hkSwitcher */ @@ -848,6 +747,7 @@ protected: virtual void startTransition(Mode_t mode, Submode_t submode); virtual void setToExternalControl(); virtual void announceMode(bool recursive); + virtual ReturnValue_t letChildHandleMessage(CommandMessage *message); /** @@ -894,6 +794,22 @@ protected: bool commandIsExecuting(DeviceCommandId_t commandId); + /** + * Information about expected replies + * + * This is used to keep track of pending replies + */ + struct DeviceReplyInfo { + uint16_t maxDelayCycles; //!< The maximum number of cycles the handler should wait for a reply to this command. + uint16_t delayCycles; //!< The currently remaining cycles the handler should wait for a reply, 0 means there is no reply expected + uint8_t periodic; //!< if this is !=0, the delayCycles will not be reset to 0 but to maxDelayCycles + DeviceCommandMap::iterator command; //!< The command that expects this reply. + }; + + /** + * Definition for the important reply Map. + */ + typedef std::map DeviceReplyMap; /** * This map is used to check and track correct reception of all replies. * @@ -913,13 +829,12 @@ protected: DeviceCommandMap deviceCommandMap; ActionHelper actionHelper; - private: /** * State a cookie is in. * - * Used to keep track of the state of the communication. + * Used to keep track of the state of the RMAP communication. */ enum CookieState_t { COOKIE_UNUSED, //!< The Cookie is unused @@ -946,12 +861,17 @@ private: */ CookieInfo cookieInfo; + /** + * cached from ctor for initialize() + */ + const uint32_t ioBoardAddress; + /** * Used for timing out mode transitions. * * Set when setMode() is called. */ - uint32_t timeoutStart = 0; + uint32_t timeoutStart; /** * Delay for the current mode transition, used for time out @@ -993,20 +913,22 @@ private: * - checks whether commanded mode transitions are required and calls handleCommandedModeTransition() * - does the necessary action for the current mode or calls doChildStateMachine in modes @c MODE_TO_ON and @c MODE_TO_OFF * - actions that happen in transitions (eg setting a timeout) are handled in setMode() - * - Maybe export this into own class to increase modularity of software - * and reduce the massive class size ? */ void doStateMachine(void); void buildRawDeviceCommand(CommandMessage* message); void buildInternalCommand(void); +// /** +// * Send a reply with the current mode and submode. +// */ +// void announceMode(void); + /** * Decrement the counter for the timout of replies. * * This is called at the beginning of each cycle. It checks whether a reply has timed out (that means a reply was expected * but not received). - * In case the reply is periodic, the counter is simply set back to a specified value. */ void decrementDeviceReplyMap(void); @@ -1073,8 +995,8 @@ private: * - @c RETURN_FAILED IPCStore is NULL * - the return value from the IPCStore if it was not @c RETURN_OK */ - ReturnValue_t getStorageData(store_address_t storageAddress, - uint8_t ** data, size_t * len); + ReturnValue_t getStorageData(store_address_t storageAddress, uint8_t **data, + uint32_t *len); /** * set all switches returned by getSwitches() @@ -1103,16 +1025,9 @@ private: * - @c RETURN_FAILED when cookies could not be changed, eg because the newChannel is not enabled * - @c returnvalues of RMAPChannelIF::isActive() */ - //ReturnValue_t switchCookieChannel(object_id_t newChannelId); + ReturnValue_t switchCookieChannel(object_id_t newChannelId); - /** - * Handle device handler messages (e.g. commands sent by PUS Service 2) - * @param message - * @return - */ ReturnValue_t handleDeviceHandlerMessage(CommandMessage *message); - - }; #endif /* DEVICEHANDLERBASE_H_ */ diff --git a/devicehandlers/DeviceHandlerIF.h b/devicehandlers/DeviceHandlerIF.h index 34aa4114..fe0ee8e8 100644 --- a/devicehandlers/DeviceHandlerIF.h +++ b/devicehandlers/DeviceHandlerIF.h @@ -8,8 +8,7 @@ #include /** - * @brief This is the Interface used to communicate with a device handler. - * @details Includes all expected return values, events and modes. + * This is the Interface used to communicate with a device handler. * */ class DeviceHandlerIF { @@ -23,95 +22,80 @@ public: * * @details The mode of the device handler must not be confused with the mode the device is in. * The mode of the device itself is transparent to the user but related to the mode of the handler. - * MODE_ON and MODE_OFF are included in hasModesIF.h */ +// MODE_ON = 0, //!< The device is powered and ready to perform operations. In this mode, no commands are sent by the device handler itself, but direct commands van be commanded and will be interpreted +// MODE_OFF = 1, //!< The device is powered off. The only command accepted in this mode is a mode change to on. + static const Mode_t MODE_NORMAL = 2; //!< The device is powered on and the device handler periodically sends commands. The commands to be sent are selected by the handler according to the submode. + static const Mode_t MODE_RAW = 3; //!< The device is powered on and ready to perform operations. In this mode, raw commands can be sent. The device handler will send all replies received from the command back to the commanding object. + static const Mode_t MODE_ERROR_ON = 4; //!4< The device is shut down but the switch could not be turned off, so the device still is powered. In this mode, only a mode change to @c MODE_OFF can be commanded, which tries to switch off the device again. + static const Mode_t _MODE_START_UP = TRANSITION_MODE_CHILD_ACTION_MASK | 5; //!< This is a transitional state which can not be commanded. The device handler performs all commands to get the device in a state ready to perform commands. When this is completed, the mode changes to @c MODE_ON. + static const Mode_t _MODE_SHUT_DOWN = TRANSITION_MODE_CHILD_ACTION_MASK | 6; //!< This is a transitional state which can not be commanded. The device handler performs all actions and commands to get the device shut down. When the device is off, the mode changes to @c MODE_OFF. + static const Mode_t _MODE_TO_ON = TRANSITION_MODE_CHILD_ACTION_MASK | HasModesIF::MODE_ON; + static const Mode_t _MODE_TO_RAW = TRANSITION_MODE_CHILD_ACTION_MASK | MODE_RAW; + static const Mode_t _MODE_TO_NORMAL = TRANSITION_MODE_CHILD_ACTION_MASK | MODE_NORMAL; + static const Mode_t _MODE_POWER_DOWN = TRANSITION_MODE_BASE_ACTION_MASK | 1; //!< This is a transitional state which can not be commanded. The device is shut down and ready to be switched off. After the command to set the switch off has been sent, the mode changes to @c MODE_WAIT_OFF + static const Mode_t _MODE_POWER_ON = TRANSITION_MODE_BASE_ACTION_MASK | 2; //!< This is a transitional state which can not be commanded. The device will be switched on in this state. After the command to set the switch on has been sent, the mode changes to @c MODE_WAIT_ON + static const Mode_t _MODE_WAIT_OFF = TRANSITION_MODE_BASE_ACTION_MASK | 3; //!< This is a transitional state which can not be commanded. The switch has been commanded off and the handler waits for it to be off. When the switch is off, the mode changes to @c MODE_OFF. + static const Mode_t _MODE_WAIT_ON = TRANSITION_MODE_BASE_ACTION_MASK | 4; //!< This is a transitional state which can not be commanded. The switch has been commanded on and the handler waits for it to be on. When the switch is on, the mode changes to @c MODE_TO_ON. + static const Mode_t _MODE_SWITCH_IS_OFF = TRANSITION_MODE_BASE_ACTION_MASK | 5; //!< This is a transitional state which can not be commanded. The switch has been commanded off and is off now. This state is only to do an RMAP cycle once more where the doSendRead() function will set the mode to MODE_OFF. The reason to do this is to get rid of stuck packets in the IO Board - // MODE_ON = 0, //!< The device is powered and ready to perform operations. In this mode, no commands are sent by the device handler itself, but direct commands van be commanded and will be interpreted - // MODE_OFF = 1, //!< The device is powered off. The only command accepted in this mode is a mode change to on. - static const Mode_t MODE_NORMAL = 2; //!< The device is powered on and the device handler periodically sends commands. The commands to be sent are selected by the handler according to the submode. - static const Mode_t MODE_RAW = 3; //!< The device is powered on and ready to perform operations. In this mode, raw commands can be sent. The device handler will send all replies received from the command back to the commanding object. - static const Mode_t MODE_ERROR_ON = 4; //!4< The device is shut down but the switch could not be turned off, so the device still is powered. In this mode, only a mode change to @c MODE_OFF can be commanded, which tries to switch off the device again. - static const Mode_t _MODE_START_UP = TRANSITION_MODE_CHILD_ACTION_MASK | 5; //!< This is a transitional state which can not be commanded. The device handler performs all commands to get the device in a state ready to perform commands. When this is completed, the mode changes to @c MODE_ON. - static const Mode_t _MODE_SHUT_DOWN = TRANSITION_MODE_CHILD_ACTION_MASK | 6; //!< This is a transitional state which can not be commanded. The device handler performs all actions and commands to get the device shut down. When the device is off, the mode changes to @c MODE_OFF. - static const Mode_t _MODE_TO_ON = TRANSITION_MODE_CHILD_ACTION_MASK | HasModesIF::MODE_ON; //!< It is possible to set the mode to _MODE_TO_ON to use the to on transition if available. - static const Mode_t _MODE_TO_RAW = TRANSITION_MODE_CHILD_ACTION_MASK | MODE_RAW; - static const Mode_t _MODE_TO_NORMAL = TRANSITION_MODE_CHILD_ACTION_MASK | MODE_NORMAL; - static const Mode_t _MODE_POWER_DOWN = TRANSITION_MODE_BASE_ACTION_MASK | 1; //!< This is a transitional state which can not be commanded. The device is shut down and ready to be switched off. After the command to set the switch off has been sent, the mode changes to @c MODE_WAIT_OFF - static const Mode_t _MODE_POWER_ON = TRANSITION_MODE_BASE_ACTION_MASK | 2; //!< This is a transitional state which can not be commanded. The device will be switched on in this state. After the command to set the switch on has been sent, the mode changes to @c MODE_WAIT_ON - static const Mode_t _MODE_WAIT_OFF = TRANSITION_MODE_BASE_ACTION_MASK | 3; //!< This is a transitional state which can not be commanded. The switch has been commanded off and the handler waits for it to be off. When the switch is off, the mode changes to @c MODE_OFF. - static const Mode_t _MODE_WAIT_ON = TRANSITION_MODE_BASE_ACTION_MASK | 4; //!< This is a transitional state which can not be commanded. The switch has been commanded on and the handler waits for it to be on. When the switch is on, the mode changes to @c MODE_TO_ON. - static const Mode_t _MODE_SWITCH_IS_OFF = TRANSITION_MODE_BASE_ACTION_MASK | 5; //!< This is a transitional state which can not be commanded. The switch has been commanded off and is off now. This state is only to do an RMAP cycle once more where the doSendRead() function will set the mode to MODE_OFF. The reason to do this is to get rid of stuck packets in the IO Board + static const uint8_t SUBSYSTEM_ID = SUBSYSTEM_ID::CDH; + static const Event DEVICE_BUILDING_COMMAND_FAILED = MAKE_EVENT(0, SEVERITY::LOW); + static const Event DEVICE_SENDING_COMMAND_FAILED = MAKE_EVENT(1, SEVERITY::LOW); + static const Event DEVICE_REQUESTING_REPLY_FAILED = MAKE_EVENT(2, SEVERITY::LOW); + static const Event DEVICE_READING_REPLY_FAILED = MAKE_EVENT(3, SEVERITY::LOW); + static const Event DEVICE_INTERPRETING_REPLY_FAILED = MAKE_EVENT(4, SEVERITY::LOW); + static const Event DEVICE_MISSED_REPLY = MAKE_EVENT(5, SEVERITY::LOW); + static const Event DEVICE_UNKNOWN_REPLY = MAKE_EVENT(6, SEVERITY::LOW); + static const Event DEVICE_UNREQUESTED_REPLY = MAKE_EVENT(7, SEVERITY::LOW); + static const Event INVALID_DEVICE_COMMAND = MAKE_EVENT(8, SEVERITY::LOW); //!< Indicates a SW bug in child class. + static const Event MONITORING_LIMIT_EXCEEDED = MAKE_EVENT(9, SEVERITY::LOW); + static const Event MONITORING_AMBIGUOUS = MAKE_EVENT(10, SEVERITY::HIGH); - static const uint8_t SUBSYSTEM_ID = SUBSYSTEM_ID::CDH; - static const Event DEVICE_BUILDING_COMMAND_FAILED = MAKE_EVENT(0, SEVERITY::LOW); - static const Event DEVICE_SENDING_COMMAND_FAILED = MAKE_EVENT(1, SEVERITY::LOW); - static const Event DEVICE_REQUESTING_REPLY_FAILED = MAKE_EVENT(2, SEVERITY::LOW); - static const Event DEVICE_READING_REPLY_FAILED = MAKE_EVENT(3, SEVERITY::LOW); - static const Event DEVICE_INTERPRETING_REPLY_FAILED = MAKE_EVENT(4, SEVERITY::LOW); - static const Event DEVICE_MISSED_REPLY = MAKE_EVENT(5, SEVERITY::LOW); - static const Event DEVICE_UNKNOWN_REPLY = MAKE_EVENT(6, SEVERITY::LOW); - static const Event DEVICE_UNREQUESTED_REPLY = MAKE_EVENT(7, SEVERITY::LOW); - static const Event INVALID_DEVICE_COMMAND = MAKE_EVENT(8, SEVERITY::LOW); //!< Indicates a SW bug in child class. - static const Event MONITORING_LIMIT_EXCEEDED = MAKE_EVENT(9, SEVERITY::LOW); - static const Event MONITORING_AMBIGUOUS = MAKE_EVENT(10, SEVERITY::HIGH); + static const uint8_t INTERFACE_ID = CLASS_ID::DEVICE_HANDLER_IF; + static const ReturnValue_t NO_COMMAND_DATA = MAKE_RETURN_CODE(0xA0); + static const ReturnValue_t COMMAND_NOT_SUPPORTED = MAKE_RETURN_CODE(0xA1); + static const ReturnValue_t COMMAND_ALREADY_SENT = MAKE_RETURN_CODE(0xA2); + static const ReturnValue_t COMMAND_WAS_NOT_SENT = MAKE_RETURN_CODE(0xA3); + static const ReturnValue_t CANT_SWITCH_IOBOARD = MAKE_RETURN_CODE(0xA4); + static const ReturnValue_t WRONG_MODE_FOR_COMMAND = MAKE_RETURN_CODE(0xA5); + static const ReturnValue_t TIMEOUT = MAKE_RETURN_CODE(0xA6); + static const ReturnValue_t BUSY = MAKE_RETURN_CODE(0xA7); + static const ReturnValue_t NO_REPLY_EXPECTED = MAKE_RETURN_CODE(0xA8); //!< Used to indicate that this is a command-only command. + static const ReturnValue_t NON_OP_TEMPERATURE = MAKE_RETURN_CODE(0xA9); + static const ReturnValue_t COMMAND_NOT_IMPLEMENTED = MAKE_RETURN_CODE(0xAA); - static const uint8_t INTERFACE_ID = CLASS_ID::DEVICE_HANDLER_IF; + //standard codes used in scan for reply + // static const ReturnValue_t TOO_SHORT = MAKE_RETURN_CODE(0xB1); + static const ReturnValue_t CHECKSUM_ERROR = MAKE_RETURN_CODE(0xB2); + static const ReturnValue_t LENGTH_MISSMATCH = MAKE_RETURN_CODE(0xB3); + static const ReturnValue_t INVALID_DATA = MAKE_RETURN_CODE(0xB4); + static const ReturnValue_t PROTOCOL_ERROR = MAKE_RETURN_CODE(0xB5); - // Standard codes used when building commands. - static const ReturnValue_t NOTHING_TO_SEND = MAKE_RETURN_CODE(0xA0); //!< Return this if no command sending in required - // Mostly used for internal handling. - static const ReturnValue_t NO_COMMAND_DATA = MAKE_RETURN_CODE(0xA2); //!< If the command size is 0. Checked in DHB - static const ReturnValue_t NO_REPLY_EXPECTED = MAKE_RETURN_CODE(0xA3); //!< Used to indicate that this is a command-only command. - static const ReturnValue_t COMMAND_NOT_SUPPORTED = MAKE_RETURN_CODE(0xA4); //!< Command ID not in commandMap. Checked in DHB - static const ReturnValue_t COMMAND_ALREADY_SENT = MAKE_RETURN_CODE(0xA5); //!< Command was already executed. Checked in DHB - static const ReturnValue_t COMMAND_WAS_NOT_SENT = MAKE_RETURN_CODE(0xA6); - static const ReturnValue_t CANT_SWITCH_ADDRESS = MAKE_RETURN_CODE(0xA7); - static const ReturnValue_t WRONG_MODE_FOR_COMMAND = MAKE_RETURN_CODE(0xA8); - static const ReturnValue_t TIMEOUT = MAKE_RETURN_CODE(0xA9); - static const ReturnValue_t BUSY = MAKE_RETURN_CODE(0xAA); - static const ReturnValue_t NON_OP_TEMPERATURE = MAKE_RETURN_CODE(0xAB); - static const ReturnValue_t COMMAND_NOT_IMPLEMENTED = MAKE_RETURN_CODE(0xAC); + //standard codes used in interpret device reply + static const ReturnValue_t DEVICE_DID_NOT_EXECUTE = MAKE_RETURN_CODE(0xC1); //the device reported, that it did not execute the command + static const ReturnValue_t DEVICE_REPORTED_ERROR = MAKE_RETURN_CODE(0xC2); + static const ReturnValue_t UNKNOW_DEVICE_REPLY = MAKE_RETURN_CODE(0xC3); //the deviceCommandId reported by scanforReply is unknown + static const ReturnValue_t DEVICE_REPLY_INVALID = MAKE_RETURN_CODE(0xC4); //syntax etc is correct but still not ok, eg parameters where none are expected - // Standard codes used in scanForReply - static const ReturnValue_t APERIODIC_REPLY = MAKE_RETURN_CODE(0xB1); //!< This is used to specify for replies from a device which are not replies to requests - static const ReturnValue_t LENGTH_MISSMATCH = MAKE_RETURN_CODE(0xB2); - static const ReturnValue_t IGNORE_REPLY_DATA = MAKE_RETURN_CODE(0xB3); //!< Ignore parts of the received packet - static const ReturnValue_t IGNORE_FULL_PACKET = MAKE_RETURN_CODE(0xB4); //!< Ignore full received packet - static const ReturnValue_t CHECKSUM_ERROR = MAKE_RETURN_CODE(0xB5); - static const ReturnValue_t INVALID_DATA = MAKE_RETURN_CODE(0xB6); - static const ReturnValue_t PROTOCOL_ERROR = MAKE_RETURN_CODE(0xB7); - - // Standard codes used in interpretDeviceReply - static const ReturnValue_t DEVICE_DID_NOT_EXECUTE = MAKE_RETURN_CODE(0xC1); //the device reported, that it did not execute the command - static const ReturnValue_t DEVICE_REPORTED_ERROR = MAKE_RETURN_CODE(0xC2); - static const ReturnValue_t UNKNOW_DEVICE_REPLY = MAKE_RETURN_CODE(0xC3); //the deviceCommandId reported by scanforReply is unknown - static const ReturnValue_t DEVICE_REPLY_INVALID = MAKE_RETURN_CODE(0xC4); //syntax etc is correct but still not ok, eg parameters where none are expected - - // Standard codes used in buildCommandFromCommand - static const ReturnValue_t INVALID_COMMAND_PARAMETER = MAKE_RETURN_CODE(0xD0); - static const ReturnValue_t INVALID_NUMBER_OR_LENGTH_OF_PARAMETERS = MAKE_RETURN_CODE(0xD1); - - // Standard codes used in getSwitches - static const ReturnValue_t NO_SWITCH = MAKE_RETURN_CODE(0xE1); //!< Return in getSwitches() to specify there are no switches - - // static const ReturnValue_t ONE_SWITCH = MAKE_RETURN_CODE(8); - // static const ReturnValue_t TWO_SWITCHES = MAKE_RETURN_CODE(9); - // where is this used? - // static const ReturnValue_t COMMAND_MAP_ERROR = MAKE_RETURN_CODE(11); - - /** - * Communication action that will be executed. - * - * This is used by the child class to tell the base class what to do. - */ - enum CommunicationAction_t: uint8_t { - SEND_WRITE,//!< Send write - GET_WRITE, //!< Get write - SEND_READ, //!< Send read - GET_READ, //!< Get read - NOTHING //!< Do nothing. - }; + //Standard codes used in buildCommandFromCommand + static const ReturnValue_t INVALID_COMMAND_PARAMETER = MAKE_RETURN_CODE( + 0xD0); + static const ReturnValue_t INVALID_NUMBER_OR_LENGTH_OF_PARAMETERS = + MAKE_RETURN_CODE(0xD1); + /** + * RMAP Action that will be executed. + * + * This is used by the child class to tell the base class what to do. + */ + enum RmapAction_t { + SEND_WRITE,//!< RMAP send write + GET_WRITE, //!< RMAP get write + SEND_READ, //!< RMAP send read + GET_READ, //!< RMAP get read + NOTHING //!< Do nothing. + }; /** * Default Destructor */