eive/fsfw
eive
/
fsfw
forked from fsfw/fsfw
14
1
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

Device Handler Base Proposals 

1. Interface functions moved closer to top (and functions which should
be implemented)
2. ioBoardAddress renamed to logicalAddress. getter FUnction added.
3. debug interface for easier debugging of device handlers
4. new documentation
5. new return value for scanForReply to ignore full packet
This commit is contained in:
Robin Müller 2020-02-03 22:34:15 +01:00
parent cd7e47ccbb
commit e03aff3731
2 changed files with 417 additions and 343 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
devicehandlers/DeviceHandlerBase.cpp
View File

@ -16,32 +16,32 @@ object_id_t DeviceHandlerBase::powerSwitcherId = 0;
object_id_t DeviceHandlerBase::rawDataReceiverId = 0;
object_id_t DeviceHandlerBase::defaultFDIRParentId = 0;
DeviceHandlerBase::DeviceHandlerBase(uint32_t ioBoardAddress,
DeviceHandlerBase::DeviceHandlerBase(uint32_t logicalAddress_,
object_id_t setObjectId, uint32_t maxDeviceReplyLen,
uint8_t setDeviceSwitch, object_id_t deviceCommunication,
uint32_t thermalStatePoolId, uint32_t thermalRequestPoolId,
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);
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(), logicalAddress(logicalAddress_),
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 == NULL) {
this->fdirInstance = new DeviceHandlerFailureIsolation(setObjectId,
defaultFDIRParentId);
this->fdirInstance =
new DeviceHandlerFailureIsolation(setObjectId, defaultFDIRParentId);
}
}
@ -55,7 +55,6 @@ DeviceHandlerBase::~DeviceHandlerBase() {
ReturnValue_t DeviceHandlerBase::performOperation(uint8_t counter) {
this->pstStep = counter;
if (counter == 0) {
cookieInfo.state = COOKIE_UNUSED;
readCommandQueue();
@ -91,6 +90,85 @@ ReturnValue_t DeviceHandlerBase::performOperation(uint8_t counter) {
return RETURN_OK;
}
ReturnValue_t DeviceHandlerBase::initialize() {
ReturnValue_t result = SystemObject::initialize();
if (result != RETURN_OK) {
return result;
}
communicationInterface = objectManager->get<DeviceCommunicationIF>(
deviceCommunicationId);
if (communicationInterface == NULL) {
return RETURN_FAILED;
}
result = communicationInterface->open(&cookie, logicalAddress,
maxDeviceReplyLen);
if (result != RETURN_OK) {
return result;
}
IPCStore = objectManager->get<StorageManagerIF>(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<PowerSwitchIF>(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<int8_t> thermalRequest(deviceThermalRequestPoolId, &mySet,
PoolVariableIF::VAR_WRITE);
mySet.read();
thermalRequest = ThermalComponentIF::STATE_REQUEST_NON_OPERATIONAL;
mySet.commit(PoolVariableIF::VALID);
return RETURN_OK;
}
void DeviceHandlerBase::decrementDeviceReplyMap() {
for (std::map<DeviceCommandId_t, DeviceReplyInfo>::iterator iter =
deviceReplyMap.begin(); iter != deviceReplyMap.end(); iter++) {
@ -455,7 +533,8 @@ void DeviceHandlerBase::doGetWrite() {
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
@ -470,7 +549,6 @@ void DeviceHandlerBase::doGetWrite() {
void DeviceHandlerBase::doSendRead() {
ReturnValue_t result;
result = communicationInterface->requestReceiveMessage(cookie);
if (result == RETURN_OK) {
cookieInfo.state = COOKIE_READ_SENT;
@ -539,6 +617,8 @@ 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);
@ -579,84 +659,6 @@ 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<DeviceCommunicationIF>(
deviceCommunicationId);
if (communicationInterface == NULL) {
return RETURN_FAILED;
}
result = communicationInterface->open(&cookie, ioBoardAddress,
maxDeviceReplyLen);
if (result != RETURN_OK) {
return result;
}
IPCStore = objectManager->get<StorageManagerIF>(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<PowerSwitchIF>(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<int8_t> 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) {
@ -672,7 +674,6 @@ void DeviceHandlerBase::replyRawData(const uint8_t *data, size_t len,
}
CommandMessage message;
DeviceHandlerMessage::setDeviceHandlerRawReplyMessage(&message,
getObjectId(), address, isCommand);
@ -753,7 +754,7 @@ ReturnValue_t DeviceHandlerBase::switchCookieChannel(object_id_t newChannelId) {
DeviceCommunicationIF>(newChannelId);
if (newCommunication != NULL) {
ReturnValue_t result = newCommunication->reOpen(cookie, ioBoardAddress,
ReturnValue_t result = newCommunication->reOpen(cookie, logicalAddress,
maxDeviceReplyLen);
if (result != RETURN_OK) {
return result;
@ -837,8 +838,9 @@ 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--;
@ -1112,8 +1114,7 @@ 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
@ -1270,3 +1271,10 @@ 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) {
}
uint32_t DeviceHandlerBase::getLogicalAddress() {
return logicalAddress;
}

540
devicehandlers/DeviceHandlerBase.h
View File

@ -34,24 +34,40 @@ class StorageManagerIF;
*/
/**
* \brief This is the abstract base class for device handlers.
*
* @brief This is the abstract base class for device handlers.
* @details
* 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 features handling of @link DeviceHandlerIF::Mode_t Modes @endlink, communication with
* physical devices, using the @link DeviceCommunicationIF @endlink, and 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 (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.
* 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.
*
* 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()
*
* \ingroup devices
* Other important virtual methods with a default implementation
* are the getTransitionDelayMs() function and the getSwitches() function.
*
* @ingroup devices
*/
class DeviceHandlerBase: public DeviceHandlerIF,
public HasReturnvaluesIF,
@ -69,55 +85,270 @@ public:
* @param setObjectId the ObjectId to pass to the SystemObject() Constructor
* @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(uint32_t ioBoardAddress, object_id_t setObjectId,
DeviceHandlerBase(uint32_t logicalAddress, object_id_t setObjectId,
uint32_t maxDeviceReplyLen, uint8_t setDeviceSwitch,
object_id_t deviceCommunication, uint32_t thermalStatePoolId =
PoolVariableIF::NO_PARAMETER,
object_id_t deviceCommunication,
uint32_t thermalStatePoolId = PoolVariableIF::NO_PARAMETER,
uint32_t thermalRequestPoolId = PoolVariableIF::NO_PARAMETER,
FailureIsolationBase* fdirInstance = NULL, uint32_t cmdQueueSize = 20);
virtual MessageQueueId_t getCommandQueue(void) const;
/**
* 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
*/
* @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
*/
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();
protected:
/**
* This is used to let the child class handle the transition from mode @c _MODE_START_UP to @c MODE_ON
*
* It is only called when the device handler is in mode @c _MODE_START_UP. That means, the device switch(es) are already set to on.
* Device handler commands are read and can be handled by the child class. If the child class handles a command, it should also send
* an reply accordingly.
* If an Command is not handled (ie #DeviceHandlerCommand is not @c CMD_NONE, the base class handles rejecting the command and sends a reply.
* The replies for mode transitions are handled by the base class.
*
* If the device is started and ready for operation, the mode should be set to MODE_ON. It is possible to set the mode to _MODE_TO_ON to
* use the to on transition if available.
* If the power-up fails, the mode should be set to _MODE_POWER_DOWN which will lead to the device being powered off.
* If the device does not change the mode, the mode will be changed to _MODE_POWER_DOWN, after the timeout (from getTransitionDelay()) has passed.
*
* #transitionFailure can be set to a failure code indicating the reason for a failed transition
*/
virtual void doStartUp() = 0;
/**
* This is used to let the child class handle the transition from mode @c _MODE_SHUT_DOWN to @c _MODE_POWER_DOWN
*
* It is only called when the device handler is in mode @c _MODE_SHUT_DOWN.
* Device handler commands are read and can be handled by the child class. If the child class handles a command, it should also send
* an reply accordingly.
* If an Command is not handled (ie #DeviceHandlerCommand is not @c CMD_NONE, the base class handles rejecting the command and sends a reply.
* The replies for mode transitions are handled by the base class.
*
* If the device ready to be switched off, the mode should be set to _MODE_POWER_DOWN.
* If the device should not be switched off, the mode can be changed to _MODE_TO_ON (or MODE_ON if no transition is needed).
* If the device does not change the mode, the mode will be changed to _MODE_POWER_DOWN, when the timeout (from getTransitionDelay()) has passed.
*
* #transitionFailure can be set to a failure code indicating the reason for a failed transition
*/
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.
*
* @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 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;
/**
* @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, eg 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 return
* value 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, eg 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, uint32_t len,
DeviceCommandId_t *foundId, uint32_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;
/**
* @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 RETURN_FAILED if no switches exist
*/
virtual ReturnValue_t getSwitches(const uint8_t **switches,
uint8_t *numberOfSwitches);
public:
/**
* @param parentQueueId
*/
virtual void setParentQueue(MessageQueueId_t parentQueueId);
ReturnValue_t executeAction(ActionId_t actionId,
MessageQueueId_t commandedBy, const uint8_t* data, uint32_t size);
@ -136,6 +367,8 @@ public:
* @param task_ Pointer to the taskIF of this task
*/
virtual void setTaskIF(PeriodicTaskIF* task_);
virtual MessageQueueId_t getCommandQueue(void) const;
protected:
/**
* The Returnvalues id of this class, required by HasReturnvaluesIF
@ -143,8 +376,9 @@ protected:
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 APERIODIC_REPLY = MAKE_RETURN_CODE(5); //!< This is used to specify for replies from a device which are not replies to requests
static const ReturnValue_t IGNORE_REPLY_DATA = MAKE_RETURN_CODE(6); //!< Ignore parts of the received packet
static const ReturnValue_t IGNORE_FULL_PACKET = MAKE_RETURN_CODE(7); //!< Ignore full received packet
// 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);
@ -318,9 +552,10 @@ protected:
uint32_t parameter = 0);
/**
*
* @param parameter2 additional parameter
* 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);
@ -345,41 +580,6 @@ protected:
*/
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
*
* It is only called when the device handler is in mode @c _MODE_START_UP. That means, the device switch(es) are already set to on.
* Device handler commands are read and can be handled by the child class. If the child class handles a command, it should also send
* an reply accordingly.
* If an Command is not handled (ie #DeviceHandlerCommand is not @c CMD_NONE, the base class handles rejecting the command and sends a reply.
* The replies for mode transitions are handled by the base class.
*
* If the device is started and ready for operation, the mode should be set to MODE_ON. It is possible to set the mode to _MODE_TO_ON to
* use the to on transition if available.
* If the power-up fails, the mode should be set to _MODE_POWER_DOWN which will lead to the device being powered off.
* If the device does not change the mode, the mode will be changed to _MODE_POWER_DOWN, after the timeout (from getTransitionDelay()) has passed.
*
* #transitionFailure can be set to a failure code indicating the reason for a failed transition
*/
virtual void doStartUp() = 0;
/**
* This is used to let the child class handle the transition from mode @c _MODE_SHUT_DOWN to @c _MODE_POWER_DOWN
*
* It is only called when the device handler is in mode @c _MODE_SHUT_DOWN.
* Device handler commands are read and can be handled by the child class. If the child class handles a command, it should also send
* an reply accordingly.
* If an Command is not handled (ie #DeviceHandlerCommand is not @c CMD_NONE, the base class handles rejecting the command and sends a reply.
* The replies for mode transitions are handled by the base class.
*
* If the device ready to be switched off, the mode should be set to _MODE_POWER_DOWN.
* If the device should not be switched off, the mode can be changed to _MODE_TO_ON (or MODE_ON if no transition is needed).
* If the device does not change the mode, the mode will be changed to _MODE_POWER_DOWN, when the timeout (from getTransitionDelay()) has passed.
*
* #transitionFailure can be set to a failure code indicating the reason for a failed transition
*/
virtual void doShutDown() = 0;
/**
* Do the transition to the main modes (MODE_ON, MODE_NORMAL and MODE_RAW).
*
@ -409,24 +609,6 @@ 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?
*
@ -448,40 +630,6 @@ protected:
*/
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.
*
@ -502,40 +650,6 @@ protected:
*/
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.
@ -583,48 +697,6 @@ protected:
* @return The current delay count. If the command does not exist (should never happen) it returns 0.
*/
uint8_t getReplyDelayCycles(DeviceCommandId_t deviceCommand);
/**
* Scans a buffer for a valid reply.
*
* 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 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 scanForReply(const uint8_t *start, uint32_t len,
DeviceCommandId_t *foundId, uint32_t *foundLen) = 0;
/**
* Interpret a reply from the device.
*
* 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
* @param commander the one who initiated the command, is 0 if not external commanded
* @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;
/**
* Construct a command reply containing a raw reply.
@ -649,21 +721,6 @@ 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
*/
@ -671,7 +728,8 @@ protected:
struct DeviceCommandInfo {
bool isExecuting; //!< Indicates if the command is already executing.
uint8_t expectedReplies; //!< Dynamic value to indicate how many replies are expected.
uint8_t expectedReplies; //!< Dynamic value to indicate how many replies are expected. Inititated with 0.
uint8_t expectedRepliesWhenEnablingReplyMap; //!< Constant value which specifies expected replies when enabling reply map. Inititated in insertInCommandAndReplyMap()
MessageQueueId_t sendReplyTo; //!< if this is != NO_COMMANDER, DHB was commanded externally and shall report everything to commander.
};
@ -735,6 +793,11 @@ protected:
*/
virtual bool dontCheckQueue();
/**
* Used to retrieve logical address
* @return logicalAddress
*/
virtual uint32_t getLogicalAddress();
Mode_t getBaseMode(Mode_t transitionMode);
bool isAwaitingReply();
@ -747,7 +810,6 @@ protected:
virtual void startTransition(Mode_t mode, Submode_t submode);
virtual void setToExternalControl();
virtual void announceMode(bool recursive);
virtual ReturnValue_t letChildHandleMessage(CommandMessage *message);
/**
@ -829,6 +891,7 @@ protected:
DeviceCommandMap deviceCommandMap;
ActionHelper actionHelper;
private:
/**
@ -862,9 +925,9 @@ private:
CookieInfo cookieInfo;
/**
* cached from ctor for initialize()
*/
const uint32_t ioBoardAddress;
* cached from ctor for initialize()
*/
const uint32_t logicalAddress;
/**
* Used for timing out mode transitions.
@ -919,16 +982,12 @@ private:
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);
@ -1027,7 +1086,14 @@ private:
*/
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_ */