/* Reflow Oven Controller * * Copyright (C) 2020 Mario Hüttel * * 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 . */ /** * @addtogroup safety-controller * @{ */ #ifndef __SAFETY_CONTROLLER_H__ #define __SAFETY_CONTROLLER_H__ #include #include #include #include /** * @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); /** * @brief Perform a CRC check of the flash memory and set appropriate flags * @return negative if internal error occured. Otherwise (independent from CRC check result) 0. * @note This function requires the safety controller to be set up before! */ int safety_controller_trigger_flash_crc_check(void); /** * @brief Recalculate the CRC of a given CRC Monitor. This has to be done once the supervised registers update * @param mon Monitor to recalculate * @param password Password * @return 0 if successful */ int safety_controller_set_crc_monitor(enum crc_monitor mon, uint32_t password); #endif /* __SAFETY_CONTROLLER_H__ */ /** @} */