KSat/fsfw
15
4
Fork 0
forked from fsfw/fsfw
Code Issues Pull Requests 1 Releases Wiki Activity

Restructured header file

Browse Source 
Abstract functions are closer to the top
because they must be implemented and documentation
should be near the top.
Important virtual functions moved up too.
Additional documentation added and existing adapted
to 80 column width.
I tried to reduce the number of included files and sorted them a bit
This commit is contained in:
Robin Müller 2020-04-19 14:03:47 +02:00
parent 574d6051ba
commit 7126c19ee0
2 changed files with 449 additions and 334 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
devicehandlers/DeviceHandlerBase.cpp
View File

@ -1,14 +1,14 @@
#include <framework/datapool/DataSet.h>
#include <framework/datapool/PoolVariable.h>
#include <framework/datapool/PoolVector.h>
#include <framework/devicehandlers/AcceptsDeviceResponsesIF.h>
#include <framework/devicehandlers/DeviceHandlerBase.h> #include <framework/devicehandlers/DeviceHandlerBase.h>
#include <framework/devicehandlers/DeviceTmReportingWrapper.h>
#include <framework/globalfunctions/CRC.h>
#include <framework/objectmanager/ObjectManager.h> #include <framework/objectmanager/ObjectManager.h>
#include <framework/storagemanager/StorageManagerIF.h> #include <framework/storagemanager/StorageManagerIF.h>
#include <framework/subsystem/SubsystemBase.h>
#include <framework/thermal/ThermalComponentIF.h> #include <framework/thermal/ThermalComponentIF.h>
#include <framework/devicehandlers/AcceptsDeviceResponsesIF.h>
#include <framework/datapool/DataSet.h>
#include <framework/datapool/PoolVariable.h>
#include <framework/devicehandlers/DeviceTmReportingWrapper.h>
#include <framework/globalfunctions/CRC.h>
#include <framework/subsystem/SubsystemBase.h>
#include <framework/ipc/QueueFactory.h> #include <framework/ipc/QueueFactory.h>
#include <framework/serviceinterface/ServiceInterfaceStream.h> #include <framework/serviceinterface/ServiceInterfaceStream.h>
@ -90,6 +90,85 @@ ReturnValue_t DeviceHandlerBase::performOperation(uint8_t counter) {
return RETURN_OK; 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, 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::decrementDeviceReplyMap() { void DeviceHandlerBase::decrementDeviceReplyMap() {
for (std::map<DeviceCommandId_t, DeviceReplyInfo>::iterator iter = for (std::map<DeviceCommandId_t, DeviceReplyInfo>::iterator iter =
deviceReplyMap.begin(); iter != deviceReplyMap.end(); iter++) { deviceReplyMap.begin(); iter != deviceReplyMap.end(); iter++) {
@ -454,7 +533,9 @@ void DeviceHandlerBase::doGetWrite() {
if (wiretappingMode == RAW) { if (wiretappingMode == RAW) {
replyRawData(rawPacket, rawPacketLen, requestedRawTraffic, true); 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); result = enableReplyInReplyMap(cookieInfo.pendingCommand);
} else { } else {
//always generate a failure event, so that FDIR knows what's up //always generate a failure event, so that FDIR knows what's up
@ -577,86 +658,6 @@ ReturnValue_t DeviceHandlerBase::getStorageData(store_address_t storageAddress,
*len = 0; *len = 0;
return result; return result;
} }
}
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, void DeviceHandlerBase::replyRawData(const uint8_t *data, size_t len,

606
devicehandlers/DeviceHandlerBase.h
View File

@ -1,26 +1,24 @@
#ifndef DEVICEHANDLERBASE_H_ #ifndef DEVICEHANDLERBASE_H_
#define DEVICEHANDLERBASE_H_ #define DEVICEHANDLERBASE_H_
#include <framework/action/ActionHelper.h> #include <framework/objectmanager/SystemObject.h>
#include <framework/tasks/ExecutableObjectIF.h>
#include <framework/returnvalues/HasReturnvaluesIF.h>
#include <framework/action/HasActionsIF.h> #include <framework/action/HasActionsIF.h>
#include <framework/datapool/DataSet.h>
#include <framework/datapool/PoolVariableIF.h> #include <framework/datapool/PoolVariableIF.h>
#include <framework/devicehandlers/DeviceCommunicationIF.h> #include <framework/devicehandlers/DeviceCommunicationIF.h>
#include <framework/devicehandlers/DeviceHandlerIF.h> #include <framework/devicehandlers/DeviceHandlerIF.h>
#include <framework/health/HealthHelper.h>
#include <framework/modes/HasModesIF.h> #include <framework/modes/HasModesIF.h>
#include <framework/objectmanager/SystemObject.h>
#include <framework/objectmanager/SystemObjectIF.h>
#include <framework/parameters/ParameterHelper.h>
#include <framework/power/PowerSwitchIF.h> #include <framework/power/PowerSwitchIF.h>
#include <framework/returnvalues/HasReturnvaluesIF.h>
#include <framework/tasks/ExecutableObjectIF.h>
#include <framework/devicehandlers/DeviceHandlerFailureIsolation.h>
#include <framework/datapool/HkSwitchHelper.h>
#include <framework/serialize/SerialFixedArrayListAdapter.h>
#include <map>
#include <framework/ipc/MessageQueueIF.h> #include <framework/ipc/MessageQueueIF.h>
#include <framework/tasks/PeriodicTaskIF.h>
#include <framework/action/ActionHelper.h>
#include <framework/health/HealthHelper.h>
#include <framework/parameters/ParameterHelper.h>
#include <framework/datapool/HkSwitchHelper.h>
#include <framework/devicehandlers/DeviceHandlerFailureIsolation.h>
#include <map>
namespace Factory{ namespace Factory{
void setStaticFrameworkObjectIds(); void setStaticFrameworkObjectIds();
@ -34,24 +32,48 @@ 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 * 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 * It features handling of @link DeviceHandlerIF::Mode_t Modes @endlink,
* communication with commanding objects. * 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. * It inherits SystemObject and thus can be created by the ObjectManagerIF.
* *
* This class uses the opcode of ExecutableObjectIF to perform a step-wise execution. * 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. * For each step an RMAP action is selected and executed.
* 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, * If data has been received (GET_READ), the data will be interpreted.
* a default implementation is provided. * 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. * 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 * 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.
* 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
*/ */
class DeviceHandlerBase: public DeviceHandlerIF, class DeviceHandlerBase: public DeviceHandlerIF,
public HasReturnvaluesIF, public HasReturnvaluesIF,
@ -68,56 +90,335 @@ public:
* *
* @param setObjectId the ObjectId to pass to the SystemObject() Constructor * @param setObjectId the ObjectId to pass to the SystemObject() Constructor
* @param maxDeviceReplyLen the length the RMAP getRead call will be sent with * @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 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 ioBoardAddress, object_id_t setObjectId,
uint32_t maxDeviceReplyLen, uint8_t setDeviceSwitch, uint32_t maxDeviceReplyLen, uint8_t setDeviceSwitch,
object_id_t deviceCommunication, uint32_t thermalStatePoolId = object_id_t deviceCommunication,
PoolVariableIF::NO_PARAMETER, uint32_t thermalStatePoolId = PoolVariableIF::NO_PARAMETER,
uint32_t thermalRequestPoolId = PoolVariableIF::NO_PARAMETER, uint32_t thermalRequestPoolId = PoolVariableIF::NO_PARAMETER,
FailureIsolationBase* fdirInstance = NULL, uint32_t cmdQueueSize = 20); FailureIsolationBase* fdirInstance = NULL, uint32_t cmdQueueSize = 20);
virtual MessageQueueId_t getCommandQueue(void) const;
/** /**
* This function is a core component and is called periodically. * @brief This function is the device handler base core component and is
* General sequence: * called periodically.
* If the State is SEND_WRITE: * @details
* 1. Set the cookie state to COOKIE_UNUSED and read the command queue * General sequence, showing where abstract virtual functions are called:
* 2. Handles Device State Modes by calling doStateMachine(). * If the State is SEND_WRITE:
* This function calls callChildStatemachine() which calls the abstract functions * 1. Set the cookie state to COOKIE_UNUSED and read the command queue
* doStartUp() and doShutDown() * 2. Handles Device State Modes by calling doStateMachine().
* 3. Check switch states by calling checkSwitchStates() * This function calls callChildStatemachine() which calls the
* 4. Decrements counter for timeout of replies by calling decrementDeviceReplyMap() * abstract functions doStartUp() and doShutDown()
* 5. Performs FDIR check for failures * 3. Check switch states by calling checkSwitchStates()
* 6. Calls hkSwitcher.performOperation() * 4. Decrements counter for timeout of replies by calling
* 7. If the device mode is MODE_OFF, return RETURN_OK. Otherwise, perform the Action property * decrementDeviceReplyMap()
* and performs depending on value specified * 5. Performs FDIR check for failures
* by input value counter. The child class tells base class what to do by setting this value. * 6. Calls hkSwitcher.performOperation()
* - SEND_WRITE: Send data or commands to device by calling doSendWrite() * 7. If the device mode is MODE_OFF, return RETURN_OK.
* Calls abstract funtions buildNomalDeviceCommand() * Otherwise, perform the Action property and performs depending
* or buildTransitionDeviceCommand() * on value specified by input value counter (incremented in PST).
* - GET_WRITE: Get ackknowledgement for sending by calling doGetWrite(). * The child class tells base class what to do by setting this value.
* Calls abstract functions scanForReply() and interpretDeviceReply(). * - SEND_WRITE: Send data or commands to device by calling
* - SEND_READ: Request reading data from device by calling doSendRead() * doSendWrite() which calls sendMessage function
* - GET_READ: Access requested reading data by calling doGetRead() * of #communicationInterface
* @param counter Specifies which Action to perform * and calls buildInternalCommand if the cookie state is COOKIE_UNUSED
* @return RETURN_OK for successful execution * - 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); 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(); virtual ReturnValue_t initialize();
/**
*
* @param parentQueueId
*/
virtual void setParentQueue(MessageQueueId_t parentQueueId);
/** /**
* Destructor. * Destructor.
*/ */
virtual ~DeviceHandlerBase(); virtual ~DeviceHandlerBase();
protected:
/**
* @brief This is used to let the child class handle the transition from
* mode @c _MODE_START_UP to @c MODE_ON
* @details
* 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;
/**
* @brief This is used to let the child class handle the transition
* from mode @c _MODE_SHUT_DOWN to @c _MODE_POWER_DOWN
* @details
* 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,
* 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).
*
* (Robin) This part confuses me. "must do as soon as" implies that
* the developer must do something somewhere else in the code. Is
* that really the case? If I understood correctly, DHB performs
* almost everything (e.g. in erirm function) as long as the commands
* are inserted correctly.
*
* As soon as the replies are enabled, DeviceCommandInfo.periodic must
* be set to true, 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 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,
* 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, 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 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,
* e.g. 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, ReturnValue_t executeAction(ActionId_t actionId,
MessageQueueId_t commandedBy, const uint8_t* data, uint32_t size); MessageQueueId_t commandedBy, const uint8_t* data, uint32_t size);
@ -136,6 +437,8 @@ public:
* @param task_ Pointer to the taskIF of this task * @param task_ Pointer to the taskIF of this task
*/ */
virtual void setTaskIF(PeriodicTaskIF* task_); virtual void setTaskIF(PeriodicTaskIF* task_);
virtual MessageQueueId_t getCommandQueue(void) const;
protected: protected:
/** /**
* The Returnvalues id of this class, required by HasReturnvaluesIF * The Returnvalues id of this class, required by HasReturnvaluesIF
@ -347,41 +650,6 @@ protected:
*/ */
void setMode(Mode_t newMode, Submode_t 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
*
* 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). * Do the transition to the main modes (MODE_ON, MODE_NORMAL and MODE_RAW).
* *
@ -411,24 +679,6 @@ protected:
*/ */
virtual void doTransition(Mode_t modeFrom, Submode_t subModeFrom); 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? * Is the combination of mode and submode valid?
* *
@ -450,40 +700,6 @@ protected:
*/ */
virtual RmapAction_t getRmapAction(); 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. * Build the device command to send for raw mode.
* *
@ -504,41 +720,6 @@ protected:
*/ */
virtual ReturnValue_t buildChildRawCommand(); 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. * This is a helper method to facilitate inserting entries in the command map.
* @param deviceCommand Identifier of the command to add. * @param deviceCommand Identifier of the command to add.
@ -586,58 +767,6 @@ protected:
*/ */
uint8_t getReplyDelayCycles(DeviceCommandId_t deviceCommand); 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 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, 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. * Construct a command reply containing a raw reply.
* *
@ -661,21 +790,6 @@ protected:
*/ */
void replyRawReplyIfnotWiretapped(const uint8_t *data, size_t len); 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 * notify child about mode change
*/ */