smoothieware-website-v1

Temperaturecontrol

This module reads temperature reading sensors (thermistors) and uses heater and cooler elements to maintain a set temperature.

This is used for example for extruder hotends, or heated beds.

A hotend

This is a J-head hotend with its thermistor and heating element.

Multiple modules

In Smoothie, you do not get just one TemperatureControl module. You can actually create as many as you want, simply by adding them to the configuration file.

It goes something like this:

temperature_control.hotend.enable                    true
temperature_control.hotend.thermistor_pin            0.23
etc ...

temperature_control.bed.enable                       true
temperature_control.bed.thermistor_pin               0.24
etc ...

This will create and configure two separate TemperatureControl modules that will act completely independently from each other.

The line that effectively “creates” the module is the enable option. If set to true, a module is created and further configuration is read. If set to false, further configuration for this module is ignored as no module is created.

In the Configuration section below, the first two parts (temperature_control.module_name) of the configuration are sometimes omitted for conciseness, but have to be added in your actual configuration file (see example).

Configuration

Reading temperatures

To reach a desired temperature, you must be able to know what the current temperature is. This is done using a Thermistor connected to an ADC on the controller board, or a Thermocouple.

Thermistor

A given controller board only has a given number of ADCs (analog (temperature) to digital (Smoothie) converter) capable pins.

On the Smoothieboard for example, there are 4 thermistor inputs, labelled from T0 (or th1) to T3 (or th4), and corresponding in the same order to the pins 0.23 to 0.26. T0 is usually used for the hotend, and T1 for the bed.

Thermistor inputs are not polarized, the direction you connect them in on your board is not important.

temperature_control.hotend.thermistor_pin        0.23
Smoothieboard thermistor input name T0 (th1) T1 (th2) T2(th3) T3(th4)
Pin for configuration 0.23 0.24 0.25 0.26

[!WARNING] You read the value of the thermistor inputs by sending the M105 command.

If you receive a value of inf for an input, for example:

ok T :inf /0.0 @0 B:24.1 /0.0 @

It means the sensor is not properly connected, or it is damaged in some way.

Choosing the right thermistor

Thermistor Choice

Different models of thermistors are used in hotends or heated beds, and each type translates temperature into resistance differently. It’s essential to inform Smoothie about the specific thermistor model you have to ensure accurate temperature readings.

This configuration is done using the thermistor option in the configuration file. You provide the name of your thermistor, and Smoothie will handle the math accordingly.

temperature_control.hotend.thermistor        EPCOS100K

Currently, Smoothie recognizes the following thermistor models:

Name Beta for 0-80°C Beta for 185-230°C I for Steinhart Hart J for Steinhart Hart K for Steinhart Hart Part number
EPCOS100K 4066 4193 0.000722378300319346F 0.000216301852054578F 9.2641025635702e-08F B57540G0104F000
Honeywell100K 3974 4385 0.000596153185928425F 0.000231333192738335F 6.19534004306738e-08F 135-104LAG-J01
Semitec 4267 4375 0.000811290160145459F 0.000211355789144265F 7.17614730463848e-08F 104GT-2
Honeywell-QAD 0.000827339299500986F 0.000208786427208899F 8.05595282332277e-08F 135-104QAD-J01    
Semitec-104NT4 0.000797110609710217F 0.000213433144381270F 6.5338987554e-08F 104NT-4R025H42G    
RRRF100K 3960          
RRRF10K 3964          
HT100K 3990          

Unknown Thermistor

If your thermistor is not recognized by Smoothie, you can define the parameters manually in the configuration file using either the beta value or the Steinhart Hart algorithm.

Using Beta Values

Set the beta value in the configuration file:

temperature_control.hotend.beta       4066   # set beta for thermistor

[!WARNING] Beta values provided by manufacturers are typically for the 0-80°C range, which can result in readings being about 7-10°C too high for the 185-230°C range. This makes beta values generally suitable for heated beds but not for hotends.

If the thermistor is 100K ohms at 25°C, this setting is usually sufficient. Additional settings like r0, t0, r1, r2 are not typically needed as the defaults work well.

If you’re unsure about your thermistor model, contact the designer or seller of your 3D printer, hotend, or heated bed to obtain the specifications and beta value.

Using the Steinhart Hart Algorithm

This is the preferred method. Set the Steinhart Hart coefficients in the configuration file:

temperature_control.hotend.coefficients 0.000722376862540841,0.000216302098124288,0.000000092640163984

To determine the Steinhart Hart coefficients for your thermistor, please refer to the SteinhartHart page.

Alternatively, if you have the temperature curve for your thermistor, you can define three points on that curve and let Smoothie calculate the coefficients:

temperature_control.hotend.rt_curve          20.0,126800,150,1360,240,206.5

PT100

Note PT100 as used by the e3d amplifier is supported in current edge, but not in the current pre-built binary firmware.

Configuration and usage

A PT100 is a commonly used RTD. Compared to NTC (the most common) thermistors work, the PT100 is “PTC” so the change in resistance with temperature is “other way around”. (PT100’s also have a very different curve than NTCs handled by Thermistor class.)

“PTC” means “positive temperature coefficient” so electrical resistance increases with raising temperature. They cannot be used as-is, you must use an amplifier circuit to raise the voltage change so they become usable by SmoothieBoard.

Currently, Smoothie only supports E3D’s PT100 amplifier board. Other PT100 amplifiers may be supported later (i.e. MAX31865 via SPI).

[!DANGER] The PT100 E3D amplifier needs to be powered from the AVCC and AGND header pins on the SmoothieBoard, only newer boards have this header.

If you do not have AVCC/AGND pins, you can use 3.3V and GND. However, this may introduce noise in the ADC system and may affect all temperature readings from analog sources (i.e. thermistors and PT100).

DO NOT power from 5v or you will kill the port.

You wire a PT100 almost the same way you would a thermistor, but you need to specify to Smoothie it is a PT100 and where you connected the amplifier signal output:

temperature_control.hotend.enable              true
temperature_control.hotend.sensor              pt100_e3d
temperature_control.hotend.e3d_amplifier_pin   1.30        # must be a free ADC pin, not a temperature input

[!NOTE] When using a PT100 sensor type you do not need to set values for the thermistor kind or thermistor_pin. If you do, these values will be ignored.

[!DANGER] You must use a spare ADC pin to connect the amplifier signal; you cannot use a thermistor input due to the pull-up that is already on the board. On most boards that means either 1.30 or 1.31, depending on what is more convenient.

Thermocouple via SPI

Thermocouples are currently supported by connecting a MAX31855 chip to one of the SPI channels. Thermocouples give a stable measurement over a wide temperature range, and can typically withstand higher temperatures than thermistors.

Note: the MAX31855 does not like having the thermocouple electrically connected to ground, and will flag an error if this happens. Make sure your thermocouple is isolated. If you must use a non-isolated thermocouple, try the AD8495 analog amplifier instead (see next section). Note: Connecting a thermocouple and a RRD GLCD panel to the same SPI bus does not work. Note: you need the latest edge build if you want to have multiple Thermocouples on the SPI bus. Note: As of 2/13/2018, the max31855 module does not work when configured without a heater pin

Here is an example of how to connect the Adafruit Thermocouple Amplifier MAX31855 breakout board to the Smoothieboard.

Smoothieboard Breakout board
3v3 Vin
GND GND
0.16 CS CS
0.18 MOSI Not used
0.15 SCK CLK
0.17 MISO DO

To configure Smoothie to use the thermocouple connected like this, replace the thermistor and thermistor_pin parameters with the following:

temperature_control.hotend.sensor        max31855

The SPI channel and chip select pin can be changed using the following parameters:

temperature_control.hotend.chip_select_pin    0.16
temperature_control.hotend.spi_channel         0    # SPI channel 0 or 1

Note that when using max31855, you need to reduce the frequency at which temperatures are read. This is due to a limitation in the amplifier. For more information see this pull request.

There is a quirk to the max31855 and max6675 chips: They take 100 and 220 milliseconds, respectively, to perform the temp conversion. Sampling them faster than this will interrupt the conversion process, causing the chip to return the same value every for every subsequent sampling. To resolve that issue, readings_per_second should be 9 for the max31855 and 4 for the max6675.

temperature_control.module_name.readings_per_second      4

Thermocouple via Amplifier

Smoothie supports reading thermocouples via an ADC (the same kind used to read thermistors) if the analog value is converted by the AD8495 thermocouple amplifier.

This allows you to read values from a thermocouple without having to use a SPI port.

To use the AD8495, you need to set the right sensor type:

temperature_control.hotend.sensor    ad8495

And then configure the pin you’ll be using to read the sensor:

temperature_control.hotend.ad8495_pin   0.24

And the offset. This will depend on the AD8495 wiring. If the REF pin(pin 2) is connected to ground or 0V then the offset is 0. This means that Smoothie can measure 0C to 660C, depending on thermocouple. If, like the Adafruit board, the REF pin is connected to 1.25V then the offset is 250. With a 250 offset, Smoothie can measure -250C to 410C. The formula for calculating offset is offset = REF/0.005. The simplest way to see if the offset is set incorrectly is that the temperature reading at room temperature will be wrong.

NOTE from a community member: The AD8495 needs a GND and VCC. Using either GND or AGND from the Smoothieboard seems to work. Unclear which is preferred (if you know, please update this note!).

temperature_control.hotend.ad8495_offset   250

Heating things up.

To reach the desired temperature, you need a means of changing the temperature. This is usually done by letting current through:

This is for example how hotends or heated beds are heated to their target temperature.

The component turning the current on and off can be a mosFET (like on Smoothieboard) or a Solid-State Relay for example.

This is controlled from the board running Smoothie using a GPIO pin.

In the case of mosfets, on a Smoothieboard, a given pin is connected to a given mosfet, and you have to use that specific pin to control that specific mosfet.

See this schematic below or on the Smoothieboard page to see what mosfet corresponds to what pin.

Mosfet inputs and outputs

Read more about the mosfets here

To set a pin to a given heater, do for example:

temperature_control.hotend.heater_pin        2.7

Note on pins:

Pin Configuration

A “pin” is an input or output on the Smoothieboard.

In a lot of cases (step/direction for external stepper motors, button inputs), you can use any pin for any use.

In other cases, a given pin is tied to a given peripheral on the board.

See Pinout to learn about which pins are where.

You can have a pin’s output inverted by adding a ! after this pin’s number in the config line, example:

my_pin_name 19!

There are other modifiers for pins:

Modifier Symbol Description
Invert pin ! Exclamation mark
Open drain o Lowercase O letter
Pull up ^ Caret, Shift+6 on QWERTY keyboards (Default on most pins)
Pull down v Lowercase v letter
No pullup - Minus sign
Repeater mode @ At / Arobase sign
No modifier   If you do not set any option/modifier for your pin, it will be in pullup mode as if it had ^ specified

[!WARNING] Some pins have hardware on the board itself, enforcing a given configuration.

The main example of this is the endstop inputs, which have on-board pull-up resistors, meaning trying to deactivate pull-ups in configuration (- for them) will not work (configuration cannot deactivate/remove physically present pull-up resistors, it can only act on pull-up pin-configuration peripherals “inside” the chip).

Controlling with G-codes

By default, Smoothie will not heat anything. That could be a dangerous thing to do unwatched.

You have to send G-codes to turn your heater on and off, set a given temperature etc.

There is a set of widely used G-codes corresponding to different usual actions (for example setting the hotend temperature is M104 in the Reprap world).

But as you are defining your own custom temperature controller, you have to choose what gcode will be used to control it, Smoothie doesn’t know what exactly it’s controlling.

So for example if this is a hotend, it will look something like this for the “standard” gcodes:

temperature_control.hotend.set_m_code            104
temperature_control.hotend.set_and_wait_m_code   109

set_m_code is used to set a given temperature, and continue running Smoothie immediately. set_and_wait_m_code is used to set a given temperature, and then pause Smoothie until that temperature is reached.

Reading with G-code

There is a single g-code used to read temperature for all the temperature_control modules at the same time: M105

But it has to have a way to tell you what temperature corresponds to what specific module.

There is a standard format for this which was used before Smoothie and still is today:

ok T:22.1 /0.0 @0 B:22.5 /75.0 @210

Here T is the hotend, and B is the bed. This is a convention. But in your configuration, we have to specify which is which:

temperature_control.hotend.designator        T

Bang Bang Control

The simplest form of heat control is called bang bang this simply turns the heater on or off depending on whether it is under or over the target temperature (plus some hysteresis). This is best used for high amp beds using a relay to turn it on and off.

to enable this form of control in the config define the following…

temperature_control.bed.bang_bang            true            # set to true to use bang bang control rather than PID
temperature_control.bed.hysteresis            2.0              # set to the temperature in degrees C to use as hysteresis when

Example: If you set your temperature to 50 degrees, and your hysterisis is 2 degrees, then the heaters will turn on if the temperature is below 48 degrees, and off if the temperature is above 52 degrees.

The default form of heater control is PID.

PID


It’s not very refined

PID is important. Without PID, a simple way to control temperature would be:

But there is a big problem with that method. Due to temperature not traveling instantly in what you heat from the heater to the thermistor, when the thermistor reads a given temperature, the heater is already hotter than what the thermistor reads. And that overshooting is something we do not want. It means reaching temperatures that could be undesirable, and it means you will not be able to correctly stabilize the temperature.

The solution to this is PID. It uses some math, allowing us to correct those problems by turning the heater on and off in a smarter sequence.

The P, I, and D factors are configured as follows:

temperature_control.hotend.p_factor     100
temperature_control.hotend.i_factor     0.1
temperature_control.hotend.d_factor     100

But the really tricky thing is to find the right values for these 3 factors: the default ones are most probably wrong for your setup. So unless you have been given those values with your hardware, or you are a PID grand-master, you will need some help:

[!WARNING] Do not try to use PID settings from Marlin as they are not compatible.

PID autotuning

PID Autotuning

Smoothie can automatically tune (find) your P, I, and D factors using a process described here.

Here is an example of the G-code command used to launch PID autotune:

M303 E0 S190

When you run the command, tuning begins:

Target: 190.0
Start PID tune, command is M303 E0 S190
T: Starting PID Autotune, M304 aborts
ok
T:  21.3/190.0 @80 1 0/8
T:  22.0/190.0 @80 1 0/8
T:  22.3/190.0 @80 1 0/8
T:  22.1/190.0 @80 1 0/8
Etc...

It continues for 3 to 8 cycles, heating up, cooling down. Then:

Cycle 4: max: 246.189, min: 227.627, avg separation: 0.418274
	Ku: 34.9838, Pu: 39.85
	Trying:
	Kp:  21.0
	Ki: 1.053
	Kd:   105
PID Autotune Complete! The settings above have been loaded into memory, but not written to your config file.

Now edit your configuration to use those three values (Kp is p_factor, Ki is i_factor, Kd is d_factor), reset, and temperature control should work much better. (Also M301 can be used to set the PID values and saved with M500)

Alternatively, you can also enter the following G-code:

M500

Which will save the configuration values automatically in a configuration override file.

Learn more about configuration overrides here.

[!WARNING] Do not send M303 over the web interface, use Telnet, Pronterface, or any other serial terminal. If sent over the web, the answers will accumulate in Smoothie’s RAM and may crash it.

Fine Tuning

If you are using a 12v heater on a 24v system

You need to set max_pwm to 64:

temperature_control.hotend.max_pwm 64 #

If you are getting 10°C or more initial overshoot of temperature

You can set i_max to a lower value (default is max_pwm). 128 seems to be a good value, but it can be tuned with M301 S0 Xnnn where nnn is a number less than or equal to max_pwm:

temperature_control.hotend.i_max 128 #

To avoid accidental setting of too high a temperature

You can set max_temp to the maximum temp that is safe for the target heater. This will ignore any setting of temperatures that are higher than this and instead set the temp to max_temp. It will also shutdown if this temperature is exceeded.

temperature_control.hotend.max_temp 230    #

Safety

This module controls temperature by actuating heating elements. Heat, if left unchecked, causes fire.

Fires are painful, expensive, and can even cause death.

You definitely should set up as many safety features as you can, even those that are disabled by default. This section explains how to do so.

[!DANGER] This can happen to you

Fire

It has already been known to happen to Reprap/CNC enthusiasts. For an example see here.

This chapter covers all of the safety features, and how to set them up if needed.

Thermistor disconnect

If a thermistor is disconnected from its thermistor input (cable gets cut, connector falls), Smoothie can detect the problem by itself, as this causes a recognizably different input.

When this happens, Smoothie will detect the problem, turn off all heaters, and enter the HALT state. It will also show you the following message:

Temperature reading is unreliable on T, HALT asserted - reset or M999 required

You need to solve the issue, and then either reset the board or issue the M999 command.

You do not need to do anything to activate this safety check.

Watchdog

The watchdog is a peripheral inside the microcontroller. Smoothie must tell it « Hey, I’m alive and I have not crashed » on a regular basis.

If Smoothie stops doing that, the watchdog knows Smoothie has crashed, and resets the board, which turns all heaters off.

This ensures that if the firmware crashes, your board’s heaters turn off, and everything is safe.

You do not need to do anything to activate this, it is on by default.

Maximum temperature detection

You activate this safety check (and you should) by adding the following to your configuration:

temperature_control.module_name.max_temp      300

Once this is set, it will be impossible to set temperatures higher than the max_temp value.

Also, if the temperature reaches this max_temp temperature, Smoothie will turn off all heaters, go into HALT state, and print out the following message:

Error: MINTEMP or MAXTEMP triggered on T. Check your temperature sensors!
HALT asserted - reset or M999 required

You need to solve the issue, and then either reset the board or issue the M999 command.

The most likely cause for this problem is that a heater mosfet is stuck being always active. If this is the case, Smoothie cannot control that heater anymore, and nothing the firmware can do can solve the issue, and you are on your way to a fire.

This is why you need to give Smoothie a second way to cut power: either by having a signal that allows you to turn the power supply off, or a solid-state relay capable of cutting all power to all mosfets. See documentation below for how to achieve this.

Runaway detection

We call “temperature runaway” a phenomenon where Smoothie tries to control temperature, but for some reason the temperature increases out of control.

There are several ways this can happen:

NOTE This is now enabled by default in newer versions of edge, the timeout is set pretty high (900 seconds), it can be disabled by setting the values below to 0.

Initial heat-up runaway detection

To detect if the thermistor is disconnected during the initial heat-up (temperature increasing until it reaches its target), we need to define how long it should take for temperature to increase to the target. And if the temperature takes too long to reach this target, we know something is wrong (likely the thermistor is detached from the heating element).

To configure this value, we first need to ask the machine to heat-up, and use a timer to know how long it takes. For example, a given hotend could take 100 seconds to heat up. Then, we add a margin to this, for example 20%, and we say that if the hotend takes more than 120 seconds to heat up, something is wrong.

Now that you have a reasonable safety value, add the runaway_heating_timeout option to your configuration file:

temperature_control.module_name.runaway_heating_timeout      120 # max is 4088 seconds

Now, if heating ever takes longer than 120 seconds, Smoothie will know there is a problem, enter HALT state, turn off heaters, and show the following message:

Error: Temperature too long to be reached on T, HALT asserted, TURN POWER OFF IMMEDIATELY - reset or M999 required

You can disable this by setting it to 0.

Please note that if your PID settings are not correctly tuned, this can get activated by accident because of the “swings” un-tuned temperature curves can have. Please tune your PID settings before activating this feature.

If the Smoothieboard is being a bit too strict with detecting the temperatures, you can add runaway_error_range as a parameter (optional), it is 1° by default meaning acceptable temperature detected can be +/- 1° of the set temp. If your printer tends to not stick close enough to the right temperature, increase this value. It only applies to the heat up and cool down timeouts.

[!WARNING] Cool down timeout

NOTE If you set runaway_cooling_timeout then understand that if you set a bed temp when the bed is already hotter than the setting it will need to cool down within the time period you set. If the bed has a lot of thermal mass then this may take a long time or actually never happen, and a timeout will occur eventually. This is why it is disabled by default. However, if you do reduce the bed temperature during a print you MUST set this value otherwise you will get a runaway detection error if the new temp is lower than the current temp. This is also true of setting the hotend temperature lower while printing, then you also need to set this timeout correctly.

Out of range runaway detection

This safety feature allows to detect if the current temperature