Device Handler Base Proposals #15

Closed
muellerr wants to merge 3 commits from KSat:mueller_DeviceHandlerBase_Changes into master
2 changed files with 128 additions and 99 deletions

View File

@ -63,6 +63,7 @@ ReturnValue_t DeviceHandlerBase::performOperation(uint8_t counter) {
decrementDeviceReplyMap();
fdirInstance->checkForFailures();
hkSwitcher.performOperation();
performOperationHook();
}
if (mode == MODE_OFF) {
return RETURN_OK;
@ -1053,17 +1054,17 @@ ReturnValue_t DeviceHandlerBase::handleDeviceHandlerMessage(
replyReturnvalueToCommand(RETURN_OK);
return RETURN_OK;
case DeviceHandlerMessage::CMD_SWITCH_IOBOARD:
if (mode != MODE_OFF) {
replyReturnvalueToCommand(WRONG_MODE_FOR_COMMAND);
} else {
result = switchCookieChannel(
DeviceHandlerMessage::getIoBoardObjectId(message));
if (result == RETURN_OK) {
replyReturnvalueToCommand(RETURN_OK);
} else {
replyReturnvalueToCommand(CANT_SWITCH_IO_ADDRESS);
}
}
// if (mode != MODE_OFF) {
// replyReturnvalueToCommand(WRONG_MODE_FOR_COMMAND);
// } else {
// result = switchCookieChannel(
// DeviceHandlerMessage::getIoBoardObjectId(message));
// if (result == RETURN_OK) {
// replyReturnvalueToCommand(RETURN_OK);
// } else {
// replyReturnvalueToCommand(CANT_SWITCH_IO_ADDRESS);
// }
// }
return RETURN_OK;
case DeviceHandlerMessage::CMD_RAW:
if ((mode != MODE_RAW)) {
@ -1278,3 +1279,9 @@ void DeviceHandlerBase::changeHK(Mode_t mode, Submode_t submode, bool enable) {
void DeviceHandlerBase::setTaskIF(PeriodicTaskIF* task_){
executingTask = task_;
}
// Default implementations empty.
void DeviceHandlerBase::debugInterface(uint8_t positionTracker,
object_id_t objectId, uint32_t parameter) {}
void DeviceHandlerBase::performOperationHook() {}

View File

@ -268,51 +268,6 @@ protected:
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
@ -370,14 +325,114 @@ protected:
virtual ReturnValue_t interpretDeviceReply(DeviceCommandId_t id,
const uint8_t *packet) = 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;
/**
* 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 command is periodic (i.e. it is sent
* by the device repeatedly without request) or not. Default is aperiodic (0)
* @return - @c RETURN_OK when the command was successfully inserted,
* - @c RETURN_FAILED else.
*/
ReturnValue_t insertInCommandAndReplyMap(DeviceCommandId_t deviceCommand,
uint16_t maxDelayCycles, size_t replyLen = 0, uint8_t periodic = 0,
bool hasDifferentReplyId = false, DeviceCommandId_t replyId = 0);
/**
* @brief This is a helper method to insert replies in the reply map.
* @param deviceCommand Identifier of the reply to add.
* @param maxDelayCycles The maximum number of delay cycles the reply waits
* until it times out.
* @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)
* @return - @c RETURN_OK when the command was successfully inserted,
* - @c RETURN_FAILED else.
*/
ReturnValue_t insertInReplyMap(DeviceCommandId_t deviceCommand,
uint16_t maxDelayCycles, size_t replyLen = 0, uint8_t periodic = 0);
/**
* @brief A simple command to add a command to the commandList.
* @param deviceCommand The command to add
* @return - @c RETURN_OK when the command was successfully inserted,
* - @c RETURN_FAILED else.
*/
ReturnValue_t insertInCommandMap(DeviceCommandId_t deviceCommand);
/**
* @brief This is a helper method to facilitate updating entries
* in the reply map.
* @param deviceCommand Identifier of the reply to update.
* @param delayCycles The current number of delay cycles to wait.
* As stated in #fillCommandAndCookieMap, to disable periodic commands,
* this is set to zero.
* @param maxDelayCycles The maximum number of delay cycles the reply waits
* until it times out. By passing 0 the entry remains untouched.
* @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).
* Warning: The setting always overrides the value that was entered in the map.
* @return - @c RETURN_OK when the command was successfully inserted,
* - @c RETURN_FAILED else.
*/
ReturnValue_t updateReplyMapEntry(DeviceCommandId_t deviceReply,
uint16_t delayCycles, uint16_t maxDelayCycles,
uint8_t periodic = 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
* @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,
@ -391,7 +446,8 @@ protected:
* 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)
* _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
@ -414,6 +470,11 @@ protected:
virtual ReturnValue_t getSwitches(const uint8_t **switches,
uint8_t *numberOfSwitches);
/**
* @brief Hook function for child handlers which is called once per
* performOperation(). Default implementation is empty.
*/
virtual void performOperationHook();
public:
/**
* @param parentQueueId
@ -750,45 +811,6 @@ protected:
*/
virtual ReturnValue_t buildChildRawCommand();
/**
* 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 command is periodic (i.e. it is sent by the device repeatedly without request) or not.
* Default is aperiodic (0)
* @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,
bool hasDifferentReplyId = false, DeviceCommandId_t replyId = 0);
/**
* This is a helper method to insert replies in the reply map.
* @param deviceCommand Identifier of the reply to add.
* @param maxDelayCycles The maximum number of delay cycles the reply waits until it times out.
* @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)
* @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);
/**
* A simple command to add a command to the commandList.
* @param deviceCommand The command to add
* @return RETURN_OK if the command was successfully inserted, RETURN_FAILED else.
*/
ReturnValue_t insertInCommandMap(DeviceCommandId_t deviceCommand);
/**
* This is a helper method to facilitate updating entries in the reply map.
* @param deviceCommand Identifier of the reply to update.
* @param delayCycles The current number of delay cycles to wait. As stated in #fillCommandAndCookieMap, to disable periodic commands, this is set to zero.
* @param maxDelayCycles The maximum number of delay cycles the reply waits until it times out. By passing 0 the entry remains untouched.
* @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). Warning: The setting always overrides the value that was entered in the map.
* @return RETURN_OK when the reply was successfully updated, COMMAND_MAP_ERROR else.
*/
ReturnValue_t updateReplyMapEntry(DeviceCommandId_t deviceReply,
uint16_t delayCycles, uint16_t maxDelayCycles,
uint8_t periodic = 0);
/**
* Returns the delay cycle count of a reply.
* A count != 0 indicates that the command is already executed.