Index: firmware/App/Modes/Dialysis.c =================================================================== diff -u -r57ee0134869672b53ab5b7146b8988ede8f828d6 -r7a14f1cc62ad1cb1d7d694f632ff3ddb90ca4717 --- firmware/App/Modes/Dialysis.c (.../Dialysis.c) (revision 57ee0134869672b53ab5b7146b8988ede8f828d6) +++ firmware/App/Modes/Dialysis.c (.../Dialysis.c) (revision 7a14f1cc62ad1cb1d7d694f632ff3ddb90ca4717) @@ -1,4 +1,4 @@ -/************************************************************************** +/**********************************************************************//** * * Copyright (c) 2020 Diality Inc. - All Rights Reserved. * @@ -23,42 +23,49 @@ #include "Timers.h" #include "ModeTreatment.h" +/** + * @addtogroup Dialysis + * @{ + */ + // ********** private definitions ********** +/// Enumeration of dialysis sub-mode states. typedef enum Dialysis_States { - DIALYSIS_START_STATE = 0, - DIALYSIS_UF_STATE, - DIALYSIS_SOLUTION_INFUSION_STATE, - NUM_OF_DIALYSIS_STATES + DIALYSIS_START_STATE = 0, ///< Start state of the dialysis sub-mode state machine. + DIALYSIS_UF_STATE, ///< Ultrafiltration state of the dialysis sub-mode state machine. + DIALYSIS_SOLUTION_INFUSION_STATE, ///< Solution infusion state of the dialysis sub-mode state machine. + NUM_OF_DIALYSIS_STATES ///< # of dialysis sub-mode states. } DIALYSIS_STATE_T; +/// Enumeration of ultrafiltration states. typedef enum UF_States { - UF_START_STATE = 0, - UF_PAUSED_STATE, - UF_RUNNING_STATE, - UF_COMPLETED_OR_OFF_STATE, - NUM_OF_UF_STATES + UF_START_STATE = 0, ///< Start state of the ultrafiltration state machine. + UF_PAUSED_STATE, ///< Paused state of the ultrafiltration state machine. + UF_RUNNING_STATE, ///< Running state of the ultrafiltration state machine. + UF_COMPLETED_OR_OFF_STATE, ///< Completed/off state of the ultrafiltration state machine. + NUM_OF_UF_STATES ///< # of ultrafiltration states. } UF_STATE_T; // ********** private data ********** -static DIALYSIS_STATE_T currentDialysisState; -static UF_STATE_T currentUFState; +static DIALYSIS_STATE_T currentDialysisState; ///< Current state of the dialysis sub-mode state machine. +static UF_STATE_T currentUFState; ///< Current state of the ultrafiltration state machine. -static F32 refUFVolume; -static F32 measUFVolume; -static F32 resStartVolume; -static F32 measUFVolumeFromPriorReservoirs; +static F32 refUFVolume; ///< Current reference volume for ultrafiltration (Where should we be w/r/t ultrafiltration). +static F32 measUFVolume; ///< Current total measured volume for ultrafiltration (Where are we w/r/t ultrafiltration). +static F32 resStartVolume; ///< Reservoir start volume for ultrafiltration (i.e. where did we start with current reservoir). +static F32 measUFVolumeFromPriorReservoirs; ///< Current total ultrafiltration volume from previous reservoirs in current treatment. -static U32 uFTimeMS; -static U32 lastUFTimeStamp; +static U32 uFTimeMS; ///< Current elapsed ultrafiltration time (in ms). Used for calculating UF reference volume. +static U32 lastUFTimeStamp; ///< HD timer value when we last took stock of ultrafiltration time (so we can determine how much time has elapsed since). -static U32 setBloodFlowRate; -static U32 setDialysateFlowRate; -static F32 maxUFVolumeML; -static F32 setUFRate; +static U32 setBloodFlowRate; ///< Currently set blood flow rate (from prescription). +static U32 setDialysateFlowRate; ///< Currently set dialysate flow rate (from prescription). +static F32 maxUFVolumeML; ///< Currently set total ultrafiltration volume for treatment (from prescription). +static F32 setUFRate; ///< Currently set ultrafiltration rate (from prescription). // ********** private function prototypes ********** @@ -72,12 +79,14 @@ static void updateUFVolumes( void ); -/************************************************************************* +/*********************************************************************//** * @brief - * The initDialysis function initializes the Dialysis module. + * The initDialysis function initializes the Dialysis sub-mode module. \n + * Calling this function will reset dialysis and therefore should only \n + * be called when a new treatment is due to begin. * @details * Inputs : none - * Outputs : Dialysis module initialized. + * Outputs : Dialysis sub-mode module initialized. * @param none * @return none *************************************************************************/ @@ -100,24 +109,29 @@ setUFRate = 0.0; } -/************************************************************************* +/*********************************************************************//** * @brief - * The transitionToDialysis function prepares for transition to dialysis sub-mode. + * The transitionToDialysis function prepares for transition to dialysis sub-mode. \n + * This function will reset anything required for resuming dialysis in a \n + * treatment that has already begun. It does not reset everything as dialysis \n + * may be stopped and resumed multiple times due to alarms or user intervention \n + * and we don't want to start the treatment all over again. * @details * Inputs : none - * Outputs : + * Outputs : none * @param none * @return none *************************************************************************/ void transitionToDialysis( void ) { - // while in treatment mode, we may transition in and out of dialysis sub-mode. - // we'll want to retain our state to facilitate resumption of dialysis. + // TODO - anything needed here? } -/************************************************************************* +/*********************************************************************//** * @brief - * The setDialysisParams function sets the dialysis treatment parameters. + * The setDialysisParams function sets the dialysis treatment parameters. \n + * This function should be called prior to beginning dialysis treatment \n + * and when the user changes one or more parameters during treatment. * @details * Inputs : none * Outputs : dialysis treatment parameters are set. @@ -135,12 +149,14 @@ setUFRate = uFRate; } -/************************************************************************* +/*********************************************************************//** * @brief - * The startDialysis function starts/resumes dialysis. + * The startDialysis function starts/resumes dialysis. This function \n + * will be called by Treatment Mode when beginning or resuming dialysis \n + * treatment. * @details * Inputs : none - * Outputs : none + * Outputs : Dialysis module prepared for immediate resumption. * @return none *************************************************************************/ void startDialysis( void ) @@ -150,15 +166,17 @@ setBloodPumpTargetFlowRate( setBloodFlowRate, MOTOR_DIR_FORWARD, PUMP_CONTROL_MODE_OPEN_LOOP ); setDialInPumpTargetFlowRate( setDialysateFlowRate, MOTOR_DIR_FORWARD, PUMP_CONTROL_MODE_OPEN_LOOP ); setDialOutPumpTargetRate( setDialysateFlowRate, MOTOR_DIR_FORWARD, PUMP_CONTROL_MODE_CLOSED_LOOP ); + // TODO - Heparin pump } -/************************************************************************* +/*********************************************************************//** * @brief - * The stopDialysis function stops dialysis. This may be due to an alarm \n - * or user pressed the stop button. Dialysis may be resumed later. + * The stopDialysis function stops dialysis. This function will be called \n + * by Treatment Mode when an alarm occurs or the user pressed the stop button. \n + * Dialysis may be resumed later. * @details * Inputs : none - * Outputs : none + * Outputs : Blood and dialysate pumps stopped. Heparing pump stopped. * @return none *************************************************************************/ void stopDialysis( void ) @@ -168,7 +186,7 @@ setDialOutPumpTargetRate( 0, MOTOR_DIR_FORWARD, PUMP_CONTROL_MODE_CLOSED_LOOP ); } -/************************************************************************* +/*********************************************************************//** * @brief * The execDialysis function executes the Dialysis sub-mode state machine. * @details @@ -200,13 +218,13 @@ } } -/************************************************************************* +/*********************************************************************//** * @brief * The handleDialysisUltrafiltrationState function handles the ultrafiltration \n * state of the Dialysis state machine. * @details - * Inputs : none - * Outputs : none + * Inputs : currentUFState + * Outputs : currentUFState * @return next Dialysis state. *************************************************************************/ static DIALYSIS_STATE_T handleDialysisUltrafiltrationState( void ) @@ -239,13 +257,13 @@ return result; } -/************************************************************************* +/*********************************************************************//** * @brief * The handleDialysisSolutionInfusionState function handles the solution \n * infustion state of the Dialysis state machine. * @details - * Inputs : none - * Outputs : none + * Inputs : TBD + * Outputs : TBD * @return next Dialysis state. *************************************************************************/ static DIALYSIS_STATE_T handleDialysisSolutionInfusionState( void ) @@ -255,13 +273,14 @@ return result; } -/************************************************************************* +/*********************************************************************//** * @brief * The handleUFStartState function handles the Start state of the \n * ultrafiltration state machine. * @details - * Inputs : none - * Outputs : none + * Inputs : maxUFVolumeML + * Outputs : if ultrafiltration prescribed, ultrafiltration time is + * initialized. * @return next ultrafiltration state. *************************************************************************/ static UF_STATE_T handleUFStartState( void ) @@ -282,13 +301,13 @@ return result; } -/************************************************************************* +/*********************************************************************//** * @brief * The handleUFPausedState function handles the Paused state of the \n * ultrafiltration state machine. * @details * Inputs : none - * Outputs : none + * Outputs : if ultrafiltration resumption requested, UF time is set to resume. * @return next ultrafiltration state. *************************************************************************/ static UF_STATE_T handleUFPausedState( void ) @@ -308,13 +327,14 @@ return result; } -/************************************************************************* +/*********************************************************************//** * @brief * The handleUFRunningState function handles the Running state of the \n * ultrafiltration state machine. * @details - * Inputs : none - * Outputs : none + * Inputs : ms timer, lastUFTimeStamp + * Outputs : UF timer incremented, UF volumes updated and provided to DPo \n + * pump controller. * @return next ultrafiltration state. *************************************************************************/ static UF_STATE_T handleUFRunningState( void ) @@ -339,13 +359,13 @@ return result; } -/************************************************************************* +/*********************************************************************//** * @brief * The handleUFCompletedOrOffState function handles the UF Completed or Off \n * state of the ultrafiltration state machine. * @details * Inputs : none - * Outputs : none + * Outputs : UF volumes updated and provided to DPo pump controller. * @return next ultrafiltration state *************************************************************************/ static UF_STATE_T handleUFCompletedOrOffState( void ) @@ -364,7 +384,7 @@ return result; } -/************************************************************************* +/*********************************************************************//** * @brief * The updateUFVolumes function updates the ultrafiltration volumes based on \n * set UF rate, latest UF elapsed time, and the latest load cell weight for the \n @@ -385,4 +405,6 @@ setDialOutUFVolumes( refUFVolume, measUFVolume ); } +/**@}*/ +