3D Guardian User Guide

= Quick Start Guide =
== Training and Guarding modes ==
* The CO and smoke detectors have to "burn in" before using them with 3D Guardian. Specifically, connect them to a source of 5V (at least 1A) power, and leave them on for 24 hours.
* Initially, the device will be in the Training mode (the top LCD line says "Training", the yellow LED is steady on). 
* Before you can start proper training, you need to set the zero for the bed voltage meter (part of the bed resistance sensor). For that, power up the device and the printer, but make sure the bed heating is off. Then execute the menu option "Training -> Init voltage".
* Start training right before you start printing a reasonable large project (a few hours). Keep checking the output from different sensors (use Up / Down keys in the keypad). The CO and Smoke sensors will show 0 for the first 10 minutes after rebooting the gadget (changeable in user_config.h - the init_delay parameter in sensor_struc).
* During the training, you get almost no protection (only against very high temperature - CRAZY_TEMP parameter), so you should closely monitor the printer.
* Ideally, you should train the device from a few printing jobs, covering the realistic range of your printing jobs.
* You can combine Training and Guarding within a single printing job. E.g., you can start a long printing job at daytime in Training mode, and then switch it to Guarding mode ("Training -> On/Off" toggle in the menu) before going to bed at night.
* If something spoils the trained data for a single sensor (e.g., you accidentally used alcohol or aceton near the CO or smoke sensors), you can re-initialize the data just for that sensor using the "Training -> Re-init -> One sensor" menu option. To re-initialize all the sensors, use "Training -> Re-init -> All sensors". (You don't need to redo "Training -> Init voltage" in either case.)
* Once you have good training data, it is good idea to save them to a custom memory register - 1 or 2, using the menu command "Training -> Save data". Later you can load these data back using "Training -> Load data" command.
* Once you are satisfied with the training, you can switch the device to Guarding mode ("Training -> On/Off" toggle in the menu). The current state (Training or Guarding) is always saved to EEPROM (non-volatile memory).
* If you start getting a warning (piezzo chirps, red LED short flashes) in Guarding mode, check the output from all the sensors (Up / Down keys) to find the culprit (sensor which value is approaching the alarm value - in the left bottom corner). If you are certain that this is due to the normal change in the environment (e.g., the room became warmer; or you are using higher bed temperature - for the resistance sensor), you can update the trained values by executing "Training -> Update" from the menu (while in Guarding mode). Alternatively, this could be a pre-failure (pre-fire) situation, so take the corrective actions immediately.
* If you get the alarm (piezzo beeping, red LED flashing, printer automatically shut down), this could be either a fire/pre-fire situation, a failure of a sensor, or a significant change in the environment (e.g. using alcohol or acetone near the CO / smoke sensors). Take an appropriate action immediately. The alarm will not stop until you reboot the device.
* You can do a factory reset by executing "Config -> Reset". (Warning - all the trained data will be lost!)
* You can always shut down the printer (almost) instantly by pressing the large red "Panic" button. This can also be done remotely (see below), and via top menu option "Printer". In any of these cases, the printer cab be turned back on by executing the menu option "Printer". (This will not work if the printer was shut down due to an alarm; in the latter case, only rebooting the device will turn the printer back on.)
== Exhaust fan operation ==
* From the Config option in the menu, you can set a desired value for T_target (temperature threshold used in Fan=Auto mode), Fan time (minutes) in the Clearing mode, and Manual fan for the Fan=Manual mode.
* When printing ABS an other warp-prone filaments, keep the exhaust fan off during the printing (set "Fan -> Fan mode" to "Off"). If you want the exhaust to kick in once the enclosure temperature moves above a certain high point (T_target), use the "Auto" fan mode.
* For non warp-prone filaments (like PLA) you might want to use the "Manual" fan mode (in "Fan -> Fan mode"). Exhaust fan will run continuously at a non-full speed setting (given by "Config -> Manual fan" menu option).
* Once the printing is done (and in the case of ABS - once the enclosure cooled down to the room temperature), you can start removing the fumes with the "Fan -> Clear case" menu option. It will run for the number of minutes specified in "Config -> Fan time". At any time you can exit this mode by clicking again "Fan -> Clear case".
== Remote control ==
Once the remote control is set up (see #Setting up remote control), the OpenHAB interface to 3D Guardian can be accessed from a browser (on a smart phone etc.). The top level screen looks like this:
* The first line shows the current mode (Guarding / Training / Warning / Alarm). 
* The second line is a toggle mode switch, Training <-> Guarding. 
* The third line is a toggle enable/disable switch for the Clearing the case functionality.
* The fourth line is an entry to the next level screen, with all the sensor data.
* The fifth line shows the current case temperature (sensor "Th1").
* The sixth line shows the state of the fan (off, or the percentage of the full speed).
* The last line is the red Panic button (shuts down the printer instantly).
The next level screen contains the summary of the sensor data (list of all the sensors with their current values):
 
Here you can see (from the top to the bottom):
* The minimum reading in this session (for Guarding mode), or the cumulative trained minimum (in Training mode).
* The current reading.
* The maximum reading in this session (for Guarding mode), or the cumulative trained maximum (in Training mode).
* The threshold for alarm (if the current reading goes above this value, an alarm is triggered and the printer is shut down).
= Menu structure =
 Fan -------- Clear case
 `--- Fan mode
 
 Training --- On/off
 |- Update
 |- Re-init --- One sensor
 | `- All sensors
 |- Load data
 |- Save data
 `- Init voltage
 
 Printer
 
 Config ----- T_target
 |-- Fan time
 |-- Manual fan
 `-- Reset
= Setting up remote control =
* The gadget uses the standard MQTT protocol to communicate with the rest of your Smart Home. One can use a MQTT binding (plugin) with the smart home server OpenHab to add the 3D Guardian to your smart home. One has to run both a MQTT server (e.g. Mosquitto) and OpenHAB server on a home computer (PC or Raspberri Pi). Here are an example sitemap file for OpenHAB:
 sitemap my_home label="Main Menu"
 {
 Text label="3D printer" icon="3d_printer" 
 {
 Frame
 {
 Text item=Alarm
 }
 Frame
 {
 Switch item=Mode_toggle mappings=[ON="Mode toggle"]
 }
 Frame 
 {
 Switch item=Clear_case mappings=[ON="Clear case"]
 }
 Text label="Sensors" icon="sensors" 
 {
 Text item=Sensor1_cur label="Smoke" icon="smoke"
 {
 Text item=Sensor1_min
 Text item=Sensor1_cur
 Text item=Sensor1_max
 Text item=Sensor1_alarm
 } 
 Text item=Sensor2_cur label="CO" icon="co"
 {
 Text item=Sensor2_min
 Text item=Sensor2_cur
 Text item=Sensor2_max
 Text item=Sensor2_alarm
 } 
 Text item=Sensor3_cur label="Case" icon="temperature" 
 {
 Text item=Sensor3_min
 Text item=Sensor3_cur
 Text item=Sensor3_max
 Text item=Sensor3_alarm
 } 
 Text item=Sensor4_cur label="Electronics" icon="temperature"
 {
 Text item=Sensor4_min
 Text item=Sensor4_cur
 Text item=Sensor4_max
 Text item=Sensor4_alarm
 }
 Text item=Sensor5_cur label="PSU" icon="temperature"
 {
 Text item=Sensor5_min
 Text item=Sensor5_cur
 Text item=Sensor5_max
 Text item=Sensor5_alarm
 }
 Text item=Sensor6_cur label="Bed" icon="resistor"
 {
 Text item=Sensor6_min
 Text item=Sensor6_cur
 Text item=Sensor6_max
 Text item=Sensor6_alarm
 }
 Text item=Sensor7_cur label="SSR" icon="temperature"
 {
 Text item=Sensor7_min
 Text item=Sensor7_cur
 Text item=Sensor7_max
 Text item=Sensor7_alarm
 }
 }
 Text item=Sensor3_cur label="Case temperature" icon="temperature"
 Text item=Fan_speed
 Frame
 {
 Switch item=Shut_down_printer mappings=[ON="Shut down"]
 }
 }
 }
 </source>
and an example items file:
 Switch Clear_case "" <shutdown> {mqtt=">[broker:3d_printer/clear_case/switch:command:ON:1],>[broker:3d_printer/clear_case/switch:command:ON:0],<[broker:3d_printer/clear_case/status:state:MAP(onoff.map)]"}
 Switch Mode_toggle "" <empty> {mqtt=">[broker:3d_printer/mode_toggle/switch:command:ON:1],>[broker:3d_printer/mode_toggle/switch:command:ON:0]"}
 Switch Shut_down_printer "" <casestatus> {mqtt=">[broker:3d_printer/shut_down/switch:command:ON:1],>[broker:3d_printer/shut_down/switch:command:ON:0],<[broker:3d_printer/shut_down/status:state:MAP(onoff.map)]"}
 String Alarm "Mode: [%s]" <empty> {mqtt="<[broker:3d_printer/out/alarm:state:MAP(alarm.map)]"}
 Number Fan_speed "[%d %%]" <fan> {mqtt="<[broker:3d_printer/out/fan_speed:state:default]"}
 
 Number Sensor1_min "Min: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor1/min:state:default]"}
 Number Sensor1_max "Max: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor1/max:state:default]"}
 Number Sensor1_cur "Current: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor1/cur:state:default]"}
 Number Sensor1_alarm "Alarm: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor1/alarm:state:default]"} 
 
 Number Sensor2_min "Min: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor2/min:state:default]"}
 Number Sensor2_max "Max: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor2/max:state:default]"}
 Number Sensor2_cur "Current: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor2/cur:state:default]"}
 Number Sensor2_alarm "Alarm: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor2/alarm:state:default]"} 
 
 Number Sensor3_min "Min: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor3/min:state:default]"}
 Number Sensor3_max "Max: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor3/max:state:default]"}
 Number Sensor3_cur "Current: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor3/cur:state:default]"}
 Number Sensor3_alarm "Alarm: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor3/alarm:state:default]"}
 
 Number Sensor4_min "Min: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor4/min:state:default]"}
 Number Sensor4_max "Max: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor4/max:state:default]"}
 Number Sensor4_cur "Current: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor4/cur:state:default]"}
 Number Sensor4_alarm "Alarm: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor4/alarm:state:default]"}
 
 Number Sensor5_min "Min: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor5/min:state:default]"}
 Number Sensor5_max "Max: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor5/max:state:default]"}
 Number Sensor5_cur "Current: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor5/cur:state:default]"}
 Number Sensor5_alarm "Alarm: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor5/alarm:state:default]"}
 
 Number Sensor6_min "Min: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor6/min:state:default]"}
 Number Sensor6_max "Max: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor6/max:state:default]"}
 Number Sensor6_cur "Current: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor6/cur:state:default]"}
 Number Sensor6_alarm "Alarm: [%d]" <empty> {mqtt="<[broker:3d_printer/out/sensor6/alarm:state:default]"}
 
 Number Sensor7_min "Min: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor7/min:state:default]"}
 Number Sensor7_max "Max: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor7/max:state:default]"}
 Number Sensor7_cur "Current: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor7/cur:state:default]"}
 Number Sensor7_alarm "Alarm: [%d °C]" <empty> {mqtt="<[broker:3d_printer/out/sensor7/alarm:state:default]"}
= Troubleshooting =
Properly functioning 3D Guardian (providing full protection - in the Guarding mode) will have the green LED steady on, no red or yellow LED lights, no flashing LEDs, no piezzo sounds. No green LED light is still okay - full protection, just no WiFi connectivity.
In any other situation there will be minimal or no protection, and with one exception (steady yellow light = Training mode), this is a sign of a problem which needs to be addressed immediately.
Symptom 	Problem 	Solution(s)
Green LED on, the rest is off 	Full protection (Guarding mode) 	-
Green LED double-flashing 	No protection (SSR cable disconnected) 	Connect the cable to the power (SSR) unit, reboot the device
All LEDs are off (display is on) 	WiFi is off, full protection 	Check if the WiFi credentials are correct in private.h. 
Check if the WiFi signal from the router is strong.
All LEDs and the display are off 	No protection (no power) 	Make sure there is power to the gadget
Yellow LED on 	Limited protection (only CRAZY_TEMP), Training mode 	Only use this mode for the initial training (at least a few hours of printing). Once training is done, switch to the Guarding mode (Training / Off from the menu).
Yellow LED steady flashing 	No protection (Programming mode) 	Only use this for programming Arduino or ESP. If not programming, switch the Prog switch to the "OFF" position.
Yellow LED double-flashing 	No protection (printer cable disconnected) 	Power down the device, connect the printer cable, then power up the device
Red LED short flashes / piezzo chirps 	Limited protection (one or more sensors outside of the normal range)	Check which sensors moved outside of the trained range. If this is due to a change in the environment (e.g. ambient temperature became higher - in the case of temperature sensors; or using higher heated bed temperature in the case of the bed resistance sensor), you can update the trained value to the new reality, by using Training/Update menu option. Another possibility (for smoke/CO sensors) - you just used a volatile organic (alcohol, acetone etc) near the printer; you'll have to refresh the air (do not Update the trained data). If none of the above, it could be a sign of a failing sensor, or a sign of a real problem with the printer (burning connectors, failing bed wiring, thermal runaway with the hot end or bed etc.) In the latter case, shut down the printer and try to fix the issue.
Red LED steady flashing / piezzo beeping	Alarm; the printer is shut down 	This could be a failed sensor - check the sensor outputs to see which one, and fix it. Or it could be a real problem with the printer (smoke / fire / failing bed wiring / failing bed PSU etc.). In the latter case, check the sensor outputs, and take an appropriate action depending on the sensor. Once the problem is fixed, reboot the device.