2020-07-06 21:12:18 +02:00
|
|
|
/* 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/>.
|
|
|
|
*/
|
|
|
|
|
2020-07-07 19:26:00 +02:00
|
|
|
/**
|
|
|
|
* @addtogroup safety-controller
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
2020-07-06 21:12:18 +02:00
|
|
|
#ifndef __SAFETY_CONTROLLER_H__
|
|
|
|
#define __SAFETY_CONTROLLER_H__
|
|
|
|
|
2020-07-07 20:47:22 +02:00
|
|
|
#include <reflow-controller/safety/safety-config.h>
|
|
|
|
#include <stdbool.h>
|
2020-07-27 21:29:15 +02:00
|
|
|
#include <stdint.h>
|
2020-07-28 22:55:02 +02:00
|
|
|
#include <stddef.h>
|
2020-07-07 19:26:00 +02:00
|
|
|
|
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
|
|
|
|
*/
|
2020-07-30 20:29:41 +02:00
|
|
|
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 */
|
2021-01-24 20:27:07 +01:00
|
|
|
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-07-30 20:29:41 +02:00
|
|
|
};
|
|
|
|
|
2020-09-22 23:45:22 +02:00
|
|
|
/**
|
|
|
|
* @brief Info structure describing a timing monitor
|
|
|
|
*/
|
2020-08-16 12:34:41 +02:00
|
|
|
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-08-16 12:34:41 +02:00
|
|
|
};
|
|
|
|
|
2020-07-07 19:26:00 +02:00
|
|
|
/**
|
2020-09-22 23:45:22 +02:00
|
|
|
* @brief Initialize the safety controller.
|
2020-07-07 19:26:00 +02:00
|
|
|
*
|
|
|
|
* 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
|
|
|
|
*/
|
2022-07-16 13:01:38 +02:00
|
|
|
void safety_controller_init(void);
|
2020-07-07 19:26:00 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Handle the safety controller.
|
|
|
|
* @note This function must be executed periodically in order to prevent the watchdog from resetting the firmware
|
2022-07-30 16:04:46 +02:00
|
|
|
* @returns Worst flag weigth that is currently set.
|
2020-07-07 19:26:00 +02:00
|
|
|
*/
|
2022-07-30 16:04:46 +02:00
|
|
|
enum config_weight safety_controller_handle(void);
|
2020-07-07 19:26:00 +02:00
|
|
|
|
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.
|
|
|
|
*/
|
2020-07-07 20:47:22 +02:00
|
|
|
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
|
|
|
|
*/
|
2020-07-27 22:15:01 +02:00
|
|
|
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
|
|
|
|
*/
|
2020-07-07 20:47:22 +02:00
|
|
|
void safety_controller_report_timing(enum timing_monitor monitor);
|
2020-07-06 21:12:18 +02:00
|
|
|
|
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.
|
|
|
|
*/
|
2020-07-07 20:47:22 +02:00
|
|
|
int safety_controller_enable_timing_mon(enum timing_monitor monitor, bool enable);
|
2020-07-06 21:12:18 +02:00
|
|
|
|
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.
|
|
|
|
*/
|
2020-07-27 22:15:01 +02:00
|
|
|
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
|
|
|
|
*/
|
2022-07-16 13:01:38 +02:00
|
|
|
uint32_t safety_controller_get_flag_count(void);
|
2020-07-28 22:55:02 +02:00
|
|
|
|
2020-09-22 23:45:22 +02:00
|
|
|
/**
|
|
|
|
* @brief Get the count of analog monitors
|
|
|
|
* @return Analog monitor count
|
|
|
|
*/
|
2022-07-16 13:01:38 +02:00
|
|
|
uint32_t safety_controller_get_analog_monitor_count(void);
|
2020-07-30 20:29:41 +02:00
|
|
|
|
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
|
|
|
|
*/
|
2020-07-28 22:55:02 +02:00
|
|
|
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
|
|
|
|
*/
|
2020-07-28 22:55:02 +02:00
|
|
|
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
|
|
|
|
*/
|
2020-07-30 20:29:41 +02:00
|
|
|
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
|
|
|
|
*/
|
2020-07-30 20:29:41 +02:00
|
|
|
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
|
|
|
|
*/
|
2020-08-16 12:34:41 +02:00
|
|
|
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
|
|
|
|
*/
|
2020-08-16 12:34:41 +02:00
|
|
|
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
|
|
|
|
*/
|
2021-02-02 20:35:45 +01:00
|
|
|
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
|
|
|
|
*/
|
2021-02-15 20:28:45 +01:00
|
|
|
int safety_controller_set_overtemp_limit(float over_temperature);
|
2021-02-02 20:35:45 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Read the current overtemperature limit.
|
|
|
|
* @return Over temperature limit
|
|
|
|
*/
|
|
|
|
float safety_controller_get_overtemp_limit(void);
|
2020-08-16 12:34:41 +02:00
|
|
|
|
2021-07-16 21:17:59 +02:00
|
|
|
/**
|
|
|
|
* @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);
|
|
|
|
|
2021-07-23 20:06:09 +02:00
|
|
|
/**
|
|
|
|
* @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);
|
|
|
|
|
2020-07-06 21:12:18 +02:00
|
|
|
#endif /* __SAFETY_CONTROLLER_H__ */
|
2020-07-07 19:26:00 +02:00
|
|
|
|
|
|
|
/** @} */
|