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

273 lines
8.9 KiB
C
Raw Normal View History

/* 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>
2020-07-27 21:29:15 +02:00
#include <stdint.h>
#include <stddef.h>
2020-09-22 23:45:22 +02:00
/**
* @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 */
2020-07-09 22:31:42 +02:00
2020-09-22 23:45:22 +02:00
/**
* @brief Info structure describing an analog monitor
*/
struct analog_monitor_info {
2020-09-22 23:45:22 +02:00
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 */
2020-09-22 23:45:22 +02:00
uint64_t timestamp; /**< @brief ms timestamp when @ref analog_monitor_info::value was taken. */
};
2020-09-22 23:45:22 +02:00
/**
* @brief Info structure describing a timing monitor
*/
struct timing_monitor_info {
2020-09-22 23:45:22 +02:00
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 */
};
/**
2020-09-22 23:45:22 +02:00
* @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();
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @brief Report timing to a timing monitor.
* @param monitor Monitor to report
*/
void safety_controller_report_timing(enum timing_monitor monitor);
2020-09-22 23:45:22 +02:00
/**
* @brief Report an analog value to an analog value monitor
* @param monitor Monitor to report
* @param value Analog value
*/
2020-07-09 22:31:42 +02:00
void safety_controller_report_analog_value(enum analog_value_monitor monitor, float value);
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @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.
*/
2020-07-09 22:31:42 +02:00
enum analog_monitor_status safety_controller_get_analog_mon_value(enum analog_value_monitor monitor, float *value);
2020-09-22 23:45:22 +02:00
/**
* @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.
*/
2020-07-26 21:40:09 +02:00
int safety_controller_get_flag(enum safety_flag flag, bool *status, bool try_ack);
2020-09-22 23:45:22 +02:00
/**
* @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
*/
2020-07-26 21:40:09 +02:00
int safety_controller_ack_flag(enum safety_flag flag);
2020-07-09 22:31:42 +02:00
2020-09-22 23:45:22 +02:00
/**
* @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
*/
2020-07-27 21:29:15 +02:00
int safety_controller_ack_flag_with_key(enum safety_flag flag, uint32_t key);
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @brief Get the count of error flags
* @return Error flag count
*/
uint32_t safety_controller_get_flag_count();
2020-09-22 23:45:22 +02:00
/**
* @brief Get the count of analog monitors
* @return Analog monitor count
*/
uint32_t safety_controller_get_analog_monitor_count();
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @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);
2020-09-22 23:45:22 +02:00
/**
* @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__ */
/** @} */