/firmware/src/shared/Heater.hh

  1/*
  2 * Copyright 2010 by Adam Mayer	 <adam@makerbot.com>
  3 *
  4 * This program is free software: you can redistribute it and/or modify
  5 * it under the terms of the GNU General Public License as published by
  6 * the Free Software Foundation, either version 3 of the License, or
  7 * (at your option) any later version.
  8 *
  9 * This program is distributed in the hope that it will be useful,
 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 12 * GNU General Public License for more details.
 13 *
 14 * You should have received a copy of the GNU General Public License
 15 * along with this program.  If not, see <http://www.gnu.org/licenses/>
 16 */
 17
 18#ifndef HEATER_H
 19#define HEATER_H
 20
 21#include "TemperatureSensor.hh"
 22#include "HeatingElement.hh"
 23#include "Pin.hh"
 24#include "PID.hh"
 25#include "Types.hh"
 26#include "Timeout.hh"
 27
 28/// A heater object uses a #TemperatureSensor to control a #HeatingElement.
 29/// It is primarily a #PID controller, but enters a bypass mode when the setpoint
 30/// temperature is much higher than the current temperature. The #manage_temperature()
 31/// function must be called periodically for it to be able to maintain accurate
 32/// temperature control.
 33/// \ingroup SoftwareLibraries
 34class Heater
 35{
 36  private:
 37    TemperatureSensor& sensor;          ///< Sensor used to measure input temperature
 38    HeatingElement& element;            ///< Heating element used to produce an output
 39    Timeout next_pid_timeout;           ///< Timeout timer for PID loop (should be slower
 40                                        ///< or the same speed as sensor timeout)
 41    Timeout next_sense_timeout;         ///< Timeout timer for sensor measurement
 42    micros_t sample_interval_micros;    ///< Interval that the temperature sensor should
 43                                        ///< be updated at.
 44    
 45    // TODO: Delete this.
 46    int current_temperature;            ///< Last known temperature reading
 47    uint16_t eeprom_base;               ///< Base address to read EEPROM configuration from
 48
 49    PID pid;                            ///< PID controller instance
 50    bool bypassing_PID;                 ///< True if the heater is in full on
 51
 52    bool fail_state;                    ///< True if the heater has detected a hardware
 53                                        ///< failure and is shut down.
 54    uint8_t fail_count;                 ///< Count of the number of hardware failures that
 55                                        ///< have been reported by #getTemperature().
 56                                        ///< If this goes over #SENSOR_MAX_BAD_READINGS,
 57                                        ///< then the heater will go into a fail state.
 58
 59    /// This is the interval between PID calculations.  It doesn't make sense for
 60    /// this to be fast (<1 sec) because of the long system delay between heater
 61    /// and sensor.
 62    const static micros_t UPDATE_INTERVAL_MICROS = 500L * 1000L;
 63
 64    /// Put the heater into a failure state, ensuring that the heating element is
 65    /// disabled.
 66    void fail();
 67
 68  public:
 69    /// Instantiate a new heater object.
 70    /// \param[in] sensor #TemperatureSensor element to use as an input
 71    /// \param[in] element #HeatingElement to use as an output
 72    /// \param[in] sample_interval_micros Interval to sample the temperature sensor,
 73    ///                                    in microseconds.
 74    /// \param[in] eeprom_base EEPROM address where the PID settings are stored.
 75    Heater(TemperatureSensor& sensor,
 76           HeatingElement& element,
 77           const micros_t sample_interval_micros,
 78           const uint16_t eeprom_base);
 79    
 80    /// Get the current sensor temperature
 81    /// \return Current sensor temperature, in degrees Celcius
 82    int get_current_temperature();
 83
 84    /// Get the setpoint temperature
 85    /// \return Setpoint temperature, in degrees Celcius
 86    int get_set_temperature();
 87
 88    /// Set the target output temperature
 89    /// \param temp New target temperature, in degrees Celcius.
 90    void set_target_temperature(int temp);
 91
 92    /// Check if the heater is within the specified band
 93    /// \return True if the heater temperature is within #TARGET_HYSTERESIS degrees
 94    ///         of the setpoint temperature.
 95    bool has_reached_target_temperature();
 96
 97    /// Check if the heater is in a failure state
 98    /// \return true if the heater has failed.
 99    bool has_failed();
100
101    /// Run the heater management loop. This must be called periodically,
102    /// at a higher frequency than #sample_interval_micros.
103    void manage_temperature();
104
105    /// Change the setpoint temperature
106    /// \param value New setpoint temperature, in degrees Celcius.
107    void set_output(uint8_t value);
108
109    /// Reset the heater to a to board-on state
110    void reset();
111
112    /// Get the current PID error term
113    /// \return E term from the PID controller
114    int getPIDErrorTerm();
115
116    /// Get the current PID delta term
117    /// \return D term from the PID controller
118    int getPIDDeltaTerm();
119
120    /// Get the last PID output
121    /// \return last output from the PID controller
122    int getPIDLastOutput();
123};
124
125#endif // HEATER_H