fsfw/tmtcservices/CommandingServiceBase.h

366 lines
12 KiB
C
Raw Normal View History

2020-09-01 12:58:29 +02:00
#ifndef FSFW_TMTCSERVICES_COMMANDINGSERVICEBASE_H_
#define FSFW_TMTCSERVICES_COMMANDINGSERVICEBASE_H_
2020-08-13 20:53:35 +02:00
#include "../objectmanager/SystemObject.h"
#include "../storagemanager/StorageManagerIF.h"
#include "../tasks/ExecutableObjectIF.h"
#include "../ipc/MessageQueueIF.h"
#include "AcceptsTelecommandsIF.h"
2020-07-16 11:47:11 +02:00
2020-08-13 20:53:35 +02:00
#include "VerificationReporter.h"
#include "../ipc/CommandMessage.h"
#include "../container/FixedMap.h"
#include "../container/FIFO.h"
#include "../serialize/SerializeIF.h"
2020-06-10 22:13:49 +02:00
class TcPacketStored;
2020-07-16 11:47:11 +02:00
namespace Factory{
void setStaticFrameworkObjectIds();
}
/**
2020-06-10 22:13:49 +02:00
* @brief This class is the basis for all PUS Services, which have to
* relay Telecommands to software bus.
*
2020-06-10 22:13:49 +02:00
* It manages Telecommand reception and the generation of Verification Reports
* similar to PusServiceBase. This class is used if a telecommand can't be
* handled immediately and must be relayed to the internal software bus.
* - isValidSubservice
* - getMessageQueueAndObject
* - prepareCommand
* - handleReply
2020-06-10 22:13:49 +02:00
* @author gaisser
* @ingroup pus_services
*/
class CommandingServiceBase: public SystemObject,
public AcceptsTelecommandsIF,
public ExecutableObjectIF,
public HasReturnvaluesIF {
2020-07-16 11:47:11 +02:00
friend void (Factory::setStaticFrameworkObjectIds)();
public:
2020-09-22 14:00:18 +02:00
// We could make this configurable via preprocessor and the FSFWConfig file.
static constexpr uint8_t COMMAND_INFO_FIFO_DEPTH = 3;
static const uint8_t INTERFACE_ID = CLASS_ID::COMMAND_SERVICE_BASE;
2020-09-22 14:00:18 +02:00
static const ReturnValue_t EXECUTION_COMPLETE = MAKE_RETURN_CODE(1);
static const ReturnValue_t NO_STEP_MESSAGE = MAKE_RETURN_CODE(2);
static const ReturnValue_t OBJECT_BUSY = MAKE_RETURN_CODE(3);
static const ReturnValue_t BUSY = MAKE_RETURN_CODE(4);
static const ReturnValue_t INVALID_TC = MAKE_RETURN_CODE(5);
static const ReturnValue_t INVALID_OBJECT = MAKE_RETURN_CODE(6);
static const ReturnValue_t INVALID_REPLY = MAKE_RETURN_CODE(7);
/**
* Class constructor. Initializes two important MessageQueues:
* commandQueue for command reception and requestQueue for device reception
* @param setObjectId
* @param apid
* @param service
* @param numberOfParallelCommands
* @param commandTimeout_seconds
* @param setPacketSource
* @param setPacketDestination
* @param queueDepth
*/
CommandingServiceBase(object_id_t setObjectId, uint16_t apid,
uint8_t service, uint8_t numberOfParallelCommands,
2020-07-16 11:47:11 +02:00
uint16_t commandTimeoutSeconds, size_t queueDepth = 20);
virtual ~CommandingServiceBase();
2020-07-16 11:47:11 +02:00
/**
* This setter can be used to set the packet source individually instead
* of using the default static framework ID set in the factory.
* This should be called at object initialization and not during run-time!
* @param packetSource
*/
void setPacketSource(object_id_t packetSource);
/**
* This setter can be used to set the packet destination individually
* instead of using the default static framework ID set in the factory.
* This should be called at object initialization and not during run-time!
* @param packetDestination
*/
void setPacketDestination(object_id_t packetDestination);
/***
* This is the periodically called function.
* Handle request queue for external commands.
* Handle command Queue for internal commands.
* @param opCode is unused here at the moment
* @return RETURN_OK
*/
2020-08-01 16:53:17 +02:00
virtual ReturnValue_t performOperation(uint8_t opCode) override;
virtual uint16_t getIdentifier();
/**
* Returns the requestQueue MessageQueueId_t
*
* The requestQueue is the queue for external commands (TC)
*
* @return requestQueue messageQueueId_t
*/
virtual MessageQueueId_t getRequestQueue();
/**
* Returns the commandQueue MessageQueueId_t
*
* Remember the CommandQueue is the queue for internal communication
* @return commandQueue messageQueueId_t
*/
virtual MessageQueueId_t getCommandQueue();
2020-07-16 11:47:11 +02:00
virtual ReturnValue_t initialize() override;
2018-07-13 18:28:26 +02:00
/**
* Implementation of ExecutableObjectIF function
*
* Used to setup the reference of the task, that executes this component
2020-07-16 11:47:11 +02:00
* @param task Pointer to the taskIF of this task
2018-07-13 18:28:26 +02:00
*/
virtual void setTaskIF(PeriodicTaskIF* task) override;
2018-07-13 18:28:26 +02:00
protected:
/**
* Check the target subservice
* @param subservice[in]
2020-07-16 11:47:11 +02:00
* @return
* -@c RETURN_OK Subservice valid, continue message handling
* -@c INVALID_SUBSERVICE if service is not known, rejects packet.
*/
virtual ReturnValue_t isValidSubservice(uint8_t subservice) = 0;
/**
2020-06-10 22:13:49 +02:00
* Once a TC Request is valid, the existence of the destination and its
* target interface is checked and retrieved. The target message queue ID
* can then be acquired by using the target interface.
* @param subservice
* @param tcData Application Data of TC Packet
* @param tcDataLen
* @param id MessageQueue ID is stored here
* @param objectId Object ID is extracted and stored here
2020-07-16 11:47:11 +02:00
* @return
* - @c RETURN_OK Cotinue message handling
* - @c RETURN_FAILED Reject the packet and generates a start failure
* verification
*/
virtual ReturnValue_t getMessageQueueAndObject(uint8_t subservice,
2020-06-10 21:41:48 +02:00
const uint8_t *tcData, size_t tcDataLen, MessageQueueId_t *id,
object_id_t *objectId) = 0;
/**
2020-06-10 22:13:49 +02:00
* After the Message Queue and Object ID are determined, the command is
* prepared by using an implementation specific CommandMessage type
* which is sent to the target object. It contains all necessary information
* for the device to execute telecommands.
* @param message [out] message which can be set and is sent to the object
* @param subservice Subservice of the current communication
* @param tcData Application data of command
* @param tcDataLen Application data length
* @param state [out/in] Setable state of the communication.
* communication
* @param objectId Target object ID
2020-06-10 21:41:48 +02:00
* @return
2020-07-16 11:47:11 +02:00
* - @c RETURN_OK to generate a verification start message
* - @c EXECUTION_COMPELTE Fire-and-forget command. Generate a completion
* verification message.
* - @c Anything else rejects the packets and generates a start failure
* verification.
*/
2020-06-24 16:01:17 +02:00
virtual ReturnValue_t prepareCommand(CommandMessage* message,
2020-06-10 21:41:48 +02:00
uint8_t subservice, const uint8_t *tcData, size_t tcDataLen,
uint32_t *state, object_id_t objectId) = 0;
/**
2020-06-10 22:13:49 +02:00
* This function is implemented by child services to specify how replies
2020-06-24 16:01:17 +02:00
* to a command from another software component are handled.
2020-06-10 22:13:49 +02:00
* @param reply
2020-06-24 16:01:17 +02:00
* This is the reply in form of a generic read-only command message.
2020-06-10 22:13:49 +02:00
* @param previousCommand
* Command_t of related command
* @param state [out/in]
* Additional parameter which can be used to pass state information.
* State of the communication
* @param optionalNextCommand [out]
* An optional next command which can be set in this function
* @param objectId Source object ID
* @param isStep Flag value to mark steps of command execution
2020-06-10 22:13:49 +02:00
* @return
* - @c RETURN_OK, @c EXECUTION_COMPLETE or @c NO_STEP_MESSAGE to
* generate TC verification success
2020-08-01 16:53:17 +02:00
* - @c INVALID_REPLY Calls handleUnrequestedReply
2020-08-01 16:55:20 +02:00
* - Anything else triggers a TC verification failure. If RETURN_FAILED or
* INVALID_REPLY is returned and the command ID is
* CommandMessage::REPLY_REJECTED, a failure verification message with
* the reason as the error parameter and the initial command as
* failure parameter 1 is generated.
*/
2020-06-24 16:01:17 +02:00
virtual ReturnValue_t handleReply(const CommandMessage* reply,
Command_t previousCommand, uint32_t *state,
2020-06-24 16:01:17 +02:00
CommandMessage* optionalNextCommand, object_id_t objectId,
bool *isStep) = 0;
2020-06-10 22:13:49 +02:00
/**
* This function can be overidden to handle unrequested reply,
* when the reply sender ID is unknown or is not found is the command map.
2020-06-24 16:01:17 +02:00
* The default implementation will clear the command message and all
* its contents.
2020-06-10 22:13:49 +02:00
* @param reply
2020-06-24 16:01:17 +02:00
* Reply which is non-const so the default implementation can clear the
* message.
2020-06-10 22:13:49 +02:00
*/
2020-06-24 16:01:17 +02:00
virtual void handleUnrequestedReply(CommandMessage* reply);
2020-06-10 22:13:49 +02:00
virtual void doPeriodicOperation();
2020-09-07 15:43:48 +02:00
struct CommandInfo: public SerializeIF{
struct tcInfo {
uint8_t ackFlags;
uint16_t tcPacketId;
uint16_t tcSequenceControl;
} tcInfo;
uint32_t uptimeOfStart;
uint8_t step;
uint8_t subservice;
uint32_t state;
Command_t command;
object_id_t objectId;
2020-09-22 14:00:18 +02:00
FIFO<store_address_t, COMMAND_INFO_FIFO_DEPTH> fifo;
2020-09-07 15:43:48 +02:00
virtual ReturnValue_t serialize(uint8_t **buffer, size_t *size,
size_t maxSize, Endianness streamEndianness) const override{
return HasReturnvaluesIF::RETURN_FAILED;
};
virtual size_t getSerializedSize() const override {
return 0;
};
virtual ReturnValue_t deSerialize(const uint8_t **buffer, size_t *size,
2020-09-22 14:00:18 +02:00
Endianness streamEndianness) override {
2020-09-07 15:43:48 +02:00
return HasReturnvaluesIF::RETURN_FAILED;
};
};
2020-06-24 16:01:17 +02:00
using CommandMapIter = FixedMap<MessageQueueId_t,
CommandingServiceBase::CommandInfo>::Iterator;
const uint16_t apid;
const uint8_t service;
2020-06-10 22:13:49 +02:00
const uint16_t timeoutSeconds;
2020-06-10 22:13:49 +02:00
uint8_t tmPacketCounter = 0;
2020-06-10 22:13:49 +02:00
StorageManagerIF *IPCStore = nullptr;
2020-06-10 22:13:49 +02:00
StorageManagerIF *TCStore = nullptr;
2020-06-10 22:13:49 +02:00
MessageQueueIF* commandQueue = nullptr;
2020-06-10 22:13:49 +02:00
MessageQueueIF* requestQueue = nullptr;
VerificationReporter verificationReporter;
FixedMap<MessageQueueId_t, CommandInfo> commandMap;
2020-06-10 22:13:49 +02:00
/* May be set be children to return a more precise failure condition. */
uint32_t failureParameter1 = 0;
uint32_t failureParameter2 = 0;
2020-07-16 11:47:11 +02:00
static object_id_t defaultPacketSource;
object_id_t packetSource = objects::NO_OBJECT;
static object_id_t defaultPacketDestination;
object_id_t packetDestination = objects::NO_OBJECT;
2018-07-13 18:28:26 +02:00
/**
2020-06-10 22:13:49 +02:00
* Pointer to the task which executes this component,
* is invalid before setTaskIF was called.
2018-07-13 18:28:26 +02:00
*/
2020-06-10 22:13:49 +02:00
PeriodicTaskIF* executingTask = nullptr;
2018-07-13 18:28:26 +02:00
/**
2020-06-10 21:41:48 +02:00
* @brief Send TM data from pointer to data.
* If a header is supplied it is added before data
* @param subservice Number of subservice
* @param data Pointer to the data in the Packet
* @param dataLen Lenght of data in the Packet
* @param headerData HeaderData will be placed before data
* @param headerSize Size of HeaderData
*/
2020-06-10 21:41:48 +02:00
ReturnValue_t sendTmPacket(uint8_t subservice, const uint8_t *data,
size_t dataLen, const uint8_t* headerData = nullptr,
size_t headerSize = 0);
/**
2020-06-10 21:41:48 +02:00
* @brief To send TM packets of objects that still need to be serialized
* and consist of an object ID with appended data.
* @param subservice Number of subservice
* @param objectId ObjectId is placed before data
* @param data Data to append to the packet
* @param dataLen Length of Data
*/
2020-06-10 21:41:48 +02:00
ReturnValue_t sendTmPacket(uint8_t subservice, object_id_t objectId,
const uint8_t *data, size_t dataLen);
/**
2020-06-10 21:41:48 +02:00
* @brief To send packets which are contained inside a class implementing
* SerializeIF.
* @param subservice Number of subservice
* @param content This is a pointer to the serialized packet
* @param header Serialize IF header which will be placed before content
*/
2020-06-10 21:41:48 +02:00
ReturnValue_t sendTmPacket(uint8_t subservice, SerializeIF* content,
SerializeIF* header = nullptr);
2020-09-22 14:00:18 +02:00
void checkAndExecuteFifo(CommandMapIter& iter);
private:
/**
* This method handles internal execution of a command,
2020-06-24 16:01:17 +02:00
* once it has been started by @sa{startExecution()} in the request
* queue handler.
* It handles replies generated by the devices and relayed by the specific
* service implementation. This means that it determines further course of
* action depending on the return values specified in the service
* implementation.
* This includes the generation of TC verification messages. Note that
2020-06-24 16:01:17 +02:00
* the static framework object ID @c VerificationReporter::messageReceiver
* needs to be set.
* - TM[1,5] Step Successs
* - TM[1,6] Step Failure
* - TM[1,7] Completion Success
* - TM[1,8] Completion Failure
*/
void handleCommandQueue();
/**
2020-07-16 11:47:11 +02:00
* @brief Handler function for request queue
* @details
* Sequence of request queue handling:
* isValidSubservice -> getMessageQueueAndObject -> startExecution
2020-07-16 11:47:11 +02:00
* Generates a Start Success Reports TM[1,3] in subfunction
* @sa{startExecution()} or a Start Failure Report TM[1,4] by using the
* TC Verification Service.
*/
void handleRequestQueue();
void rejectPacket(uint8_t reportId, TcPacketStored* packet,
ReturnValue_t errorCode);
void acceptPacket(uint8_t reportId, TcPacketStored* packet);
2020-06-24 16:01:17 +02:00
void startExecution(TcPacketStored *storedPacket, CommandMapIter iter);
2020-06-24 16:01:17 +02:00
void handleCommandMessage(CommandMessage* reply);
void handleReplyHandlerResult(ReturnValue_t result, CommandMapIter iter,
2020-06-24 16:01:17 +02:00
CommandMessage* nextCommand, CommandMessage* reply, bool& isStep);
void checkTimeout();
};
2020-09-01 12:58:29 +02:00
#endif /* FSFW_TMTCSERVICES_COMMANDINGSERVICEBASE_H_ */