reflow-oven-control-sw/stm-firmware/include/reflow-controller/safety/safety-controller.h

/* Reflow Oven Controller
*
* Copyright (C) 2020  Mario Hüttel <mario.huettel@gmx.net>
*
* This file is part of the Reflow Oven Controller Project.
*
* The reflow oven controller is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*
* The Reflow Oven Control Firmware is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with the reflow oven controller project.
* If not, see <http://www.gnu.org/licenses/>.
*/

/**
 * @addtogroup safety-controller
 * @{
 */

#ifndef __SAFETY_CONTROLLER_H__
#define __SAFETY_CONTROLLER_H__

#include <reflow-controller/safety/safety-config.h>
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

/**
 * @brief State of an analog monitor
 */
enum analog_monitor_status {ANALOG_MONITOR_OK = 0,	/**< @brief Monitor set up and ok */
			    ANALOG_MONITOR_ERROR,	/**< @brief An internal error occured */
			    ANALOG_MONITOR_INACTIVE,	/**< @brief Monitor inactive. Reading is not valid */
			    ANALOG_MONITOR_OVER,	/**< @brief Value too high */
			    ANALOG_MONITOR_UNDER};	/**< @brief Value too low */

/**
 * @brief Info structure describing an analog monitor
 */
struct analog_monitor_info {
	float value;	/**< @brief Current analog value */
	float min;	/**< @brief Minumum value allowed */
	float max;	/**< @brief Maximum value allowed */
	enum analog_monitor_status status; /**< @brief Current monitor status */
	enum safety_flag associated_flag; /**< @brief Associated safety flag, that will be set, if monitor out of range */
	uint64_t timestamp; /**< @brief ms timestamp when @ref analog_monitor_info::value was taken. */
};

/**
 * @brief Info structure describing a timing monitor
 */
struct timing_monitor_info {
	uint64_t last_run;	/**< @brief Timestamp, when the monitor was last triggered */
	uint64_t min;		/**< @brief Minimum delay between two activations in ms */
	uint64_t max;		/**< @brief Maximum delay between two activations in ms */
	bool enabled;		/**< @brief Monitor enabled */
	uint64_t delta;		/**< @brief Last delta between two activations */
};

/**
 * @brief Initialize the safety controller.
 *
 * After a call to this function the controller is iniotlaized and the watchdog is set up.
 * You have to call safety_controller_handle
 * If this function fails, it will hang, because errors in the safety controller are not recoverable
 */
void safety_controller_init();

/**
 * @brief Handle the safety controller.
 * @note This function must be executed periodically in order to prevent the watchdog from resetting the firmware
 * @return 0 if successful
 */
int safety_controller_handle();

/**
 * @brief Report one or multiple errors to the safety controller
 *
 * When passing multipe error glags, the flags have to be ORed together.
 *
 * @param flag Error flag to report
 * @return 0 if successful.
 */
int safety_controller_report_error(enum safety_flag flag);

/**
 * @brief Report one or multiple error flags with a key.
 *
 * When setting a \p key on an error flag. The error flag can only be cleared,
 * by passing the same key value to the @ref safety_controller_ack_flag_with_key function.
 *
 * @param flag Error flag to report
 * @param key Key
 * @return 0 if successful
 */
int safety_controller_report_error_with_key(enum safety_flag flag, uint32_t key);

/**
 * @brief Report timing to a timing monitor.
 * @param monitor Monitor to report
 */
void safety_controller_report_timing(enum timing_monitor monitor);

/**
 * @brief Report an analog value to an analog value monitor
 * @param monitor Monitor to report
 * @param value Analog value
 */
void safety_controller_report_analog_value(enum analog_value_monitor monitor, float value);

/**
 * @brief Enable or disable a timing monitor.
 * @param monitor Monitor to enable
 * @param enable State to set the monitor to.
 * @return 0 if successful.
 */
int safety_controller_enable_timing_mon(enum timing_monitor monitor, bool enable);

/**
 * @brief Get the value of an analog monitor.
 * @param monitor Monitor to get value from
 * @param[out] value The analog value
 * @returns Status of the analog monitor. \p value only valid, if return value does not indicate an internal error,
 *          or an inactive monitor.
 */
enum analog_monitor_status safety_controller_get_analog_mon_value(enum analog_value_monitor monitor, float *value);

/**
 * @brief Get error flag state and optionally acknowledge the flag
 *
 * If the flag is persistent, it cannot be ack'ed. In this case this function
 * does not return an error code.
 *
 * @param flag Error flag
 * @param[out] status state of the flag.
 * @param try_ack Try to ack the flag. This might fail, if the flag is persistent.
 * @return 0 if successful.
 */
int safety_controller_get_flag(enum safety_flag flag, bool *status, bool try_ack);

/**
 * @brief Ack an error flag
 * @param flag Error flag to ack
 * @return 0 if successful, -2 if flag is persistent or keyed. All other values: Errors
 */
int safety_controller_ack_flag(enum safety_flag flag);

/**
 * @brief Acknowledge error flag with a key
 * @param flag Error flag
 * @param key Key
 * @return 0 if successful, -2 if flag is persistent or key wrong. All other values: Errors
 */
int safety_controller_ack_flag_with_key(enum safety_flag flag, uint32_t key);

/**
 * @brief Get an ored status of multiple flags.
 * @param mask Flags to check
 * @return True if errors. False if no errors.
 */
bool safety_controller_get_flags_by_mask(enum safety_flag mask);

/**
 * @brief Get the count of error flags
 * @return Error flag count
 */
uint32_t safety_controller_get_flag_count();

/**
 * @brief Get the count of analog monitors
 * @return Analog monitor count
 */
uint32_t safety_controller_get_analog_monitor_count();

/**
 * @brief Get an error flag's name by its index.
 *
 * The name of the flag will be cropped, if the buffersize is too small.
 * Paramter \p buffsize may not be zero.
 *
 * @param index 0 based index.
 * @param[out] buffer Buffer to write the name to.
 * @param buffsize Buffer size. This has to be big enough to hold the name and the \0-terminator
 * @return 0 of successful
 */
int safety_controller_get_flag_name_by_index(uint32_t index, char *buffer, size_t buffsize);

/**
 * @brief Get the safety flag by its internal index.
 * @param index 0 based index.
 * @param[out] status Current flag state. May be NULL.
 * @param[out] flag_enum Flag enum used in SW. May be NULL.
 * @return 0 if successful; else: negative
 */
int safety_controller_get_flag_by_index(uint32_t index, bool *status, enum safety_flag *flag_enum);

/**
 * @brief Get an analog monitor info by the monitor's index
 * @param index 0 based index
 * @param[out] info Info structure.
 * @return 0 if successful.
 *         -1001, if \p index out of range
 *         -1002, if \p info is NULL
 */
int safety_controller_get_analog_mon_by_index(uint32_t index, struct analog_monitor_info *info);

/**
 * @brief Get the name of an analog monitor by its index
 *
 * The buffer has to be large enough to hold the name plus a null terminator.
 * If the buffer is not large enough, The name will be cropped.
 * Parameter \p buffsize may not be zero.
 *
 * @param index 0 based index
 * @param buffer Buffer to write name to
 * @param buffsize Buffer size
 * @return
 */
int safety_controller_get_analog_mon_name_by_index(uint32_t index, char *buffer, size_t buffsize);

/**
 * @brief Get timing monitor information by index
 * @param index 0 based index
 * @param[out] info Info
 * @return 0 if successful
 */
int safety_controller_get_timing_mon_by_index(uint32_t index, struct timing_monitor_info *info);

/**
 * @brief Get the name of a timing monitor by its index
 *
 * The buffer has to be large enough to hold the name plus a null terminator.
 * If the buffer is not large enough, The name will be cropped.
 * Parameter \p buffsize may not be zero.
 *
 * @param index 0 based index
 * @param buffer Buffer to write name to.
 * @param buffsize Buffer size
 * @return 0 if successful
 */
int safety_controller_get_timing_mon_name_by_index(uint32_t index, char *buffer, size_t buffsize);

/**
 * @brief Get the count of timing monitors
 * @return Timing monitor count
 */
uint32_t safety_controller_get_timing_monitor_count(void);

/**
 * @brief Set the overtemperature limit and store it permanently in the EEPROM
 *
 * If no EEPROM is present, this will fail. The default value @ref SAFETY_DEFAULT_OVERTEMP_LIMIT_DEGC will be used.
 * @param over_temperature Over temperature to set
 * @return 0 if successfully saved and applied, negative if error
 */
int safety_controller_set_overtemp_limit(float over_temperature);

/**
 * @brief Read the current overtemperature limit.
 * @return Over temperature limit
 */
float safety_controller_get_overtemp_limit(void);

#endif /* __SAFETY_CONTROLLER_H__ */

/** @} */