<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY appletversion "1.10">
<!ENTITY manrevision "2.1">
<!ENTITY date "January 2006">
<!ENTITY applet "MATE Sensors Applet">
<!ENTITY author-name "Alex Murray">
<!ENTITY author-email "murray.alex@gmail.com">
<!ENTITY project-webpage "https://github.com/mate-desktop/mate-sensors-applet/">
<!-- Information about the entities.
       Use the appletversion entity to specify the version of the applet.
       Use the manrevision entity to specify the revision number of this manual.
       Use the date entity to specify the release date of this manual.
       Use the applet entity to specify the name of the applet. -->]>
<!-- 
      (Do not remove this comment block.)
  Maintained by the MATE Documentation Project
  https://mate-desktop.org/development/
  Template version: 2.0 beta
  Template last modified Feb 06, 2003
-->
<!-- =============Document Header ============================= -->
<article id="index" lang="en-GB">
  <!-- please do not change the id; for translations, change lang to -->
  <!-- appropriate code -->
  <articleinfo> 
    <title>MATE Sensors Applet Manual V2.1</title>
    <copyright><year>2015-2021</year> <holder>MATE Documentation Team</holder></copyright>
    <copyright><year>2006</year> <holder>Alex Murray</holder></copyright> 
    <abstract role="description">
      <para>MATE Sensors Applet displays readings from temperature, voltage and fan sensors within the panel.</para>
    </abstract>
    
    <!-- translators: uncomment this:

    <copyright>
    <year>2002</year>
    <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

    -->
    <!-- An address can be added to the publisher information.  If a role is 
    not specified, the publisher/author is the same for all versions of the 
    document.
    <publisher> 
    <publishername> MATE Documentation Project </publishername> 
  </publisher> 
    -->

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="legal.xml"/>

    <authorgroup> 
      <author role="maintainer"><surname>MATE Development</surname> <affiliation> </affiliation></author> 
      <author role="maintainer"><firstname>Alex</firstname> <surname>Murray</surname> <affiliation> </affiliation></author> 
      <!-- This is appropriate place for other contributors: translators,
      maintainers,  etc. Commented out by default.
      <othercredit role="translator">
      <firstname>Latin</firstname> 
      <surname>Translator 1</surname> 
      <affiliation> 
      <orgname>Latin Translation Team</orgname> 
      <address> <email>translator@mate.org</email> </address> 
    </affiliation>
      <contrib>Latin translation</contrib>
    </othercredit>
      -->
    </authorgroup>
    <!-- According to GNU FDL, revision history is mandatory if you are -->
    <!-- modifying/reusing someone else's document.  If not, you can omit it. -->
    <!-- Remember to remove the &manrevision; entity from the revision entries other
    -->
    <!-- than the current revision. -->
    <!-- The revision numbering system for MATE manuals is as follows: -->
    <!-- * the revision number consists of two components -->
    <!-- * the first component of the revision number reflects the release version of the MATE desktop. -->
    <!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
    <!-- For example, if the MATE desktop release is V2.x, the first version of the manual that -->
    <!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
    <!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
    <!-- to V3.0, and so on. -->  
    <revhistory>
      <revision><revnumber>MATE Sensors Applet Manual V2.1</revnumber> <date>January 2006</date> <revdescription> 
	  <para role="author">Alex Murray <email>murray.alex@gmail.com</email></para> 
	  <!-- <para role="publisher">MATE Documentation Project</para> -->
	</revdescription></revision> 
    </revhistory> 
    <releaseinfo>This manual describes version 1.10 of MATE Sensors Applet.</releaseinfo> 
    <legalnotice>
      <title>Feedback</title>
      <para>To report a bug or make a suggestion regarding MATE Sensors Applet or this manual, follow the directions in the <ulink url="help:mate-user-guide/feedback" type="help">MATE Feedback Page</ulink>.</para>

<!-- Translators may also add here feedback address for translations -->
    </legalnotice>
  </articleinfo> 
  <indexterm zone="index"><primary>MATE Sensors Applet</primary></indexterm> 
  <!-- ============= Document Body ============================= -->
  <!-- ============= Introduction ============================== -->
  <sect1 id="sensors-applet-introduction"> 
    <title>Introduction</title> 
    <!-- ==== Figure ============================================= -->
    <figure id="sensors-applet-fig"> 
      <title>MATE Sensors Applet</title> 
      <screenshot> 
	<mediaobject><imageobject> <imagedata fileref="figures/applet_in_panel.png" format="PNG"/> </imageobject> <textobject> <phrase>MATE Sensors Applet with 3 sensors enabled.</phrase> </textobject></mediaobject> 
      </screenshot> 
    </figure>
    <!-- ==== End of Figure ======================================= -->
    <para><application>MATE Sensors Applet</application> provides a convenient way to monitor the health of your computer in a simple display on your desktop.</para>
    <para>A number of sensor interfaces are supported, which should be configured before adding MATE Sensors Applet to the panel: <itemizedlist>
	<listitem>
	  <para>ACPI thermal zones, via the Linux kernel ACPI modules</para>
	</listitem>
	<listitem>
	  <!-- i2c modules -->
	  <para>Linux kernel i2c modules</para>
	  <itemizedlist>
	    <listitem>
	      <para>Via the sysfs filesystem and <ulink url="http://secure.netroedge.com/~lm78/kernel26.html" type="http">i2c</ulink> modules distributed directly with the kernel (kernel 2.6)</para>
	    </listitem>
	    <listitem>
	      <para>Via the proc filesystem and i2c modules from the <ulink url="http://secure.netroedge.com/~lm78/kernel26.html" type="http">lm_sensors and i2c</ulink> packages (kernel 2.4)</para>
	    </listitem>
	    <listitem>
	      <para>Via the libsensors library provided with the <ulink url="http://secure.netroedge.com/~lm78/kernel26.html" type="http">lm_sensors</ulink> package</para>
	    </listitem>
	  </itemizedlist>
	</listitem>
	<!-- i8k module -->
	<listitem>
	  <para>Linux kernel <ulink url="http://people.debian.org/~dz/i8k/00-README" type="http">i8k</ulink> module (for Dell Inspiron Laptops).</para>
	</listitem>
	<!-- ibm-acpi module -->
	<listitem>
	  <para>Linux kernel <ulink url="http://ibm-acpi.sourceforge.net/" type="http">ibm-acpi</ulink> module (for IBM Laptops).</para>
	</listitem>
	<!-- therm_adt746x and therm_windtunnel -->
	<listitem>
	  <para>Linux kernel PowerPC modules therm_adt746x and therm_windtunnel.</para>
	</listitem>
	<!-- iMac G5 Windfarm -->
	<listitem>
	  <para>Linux kernel iMac G5 Windfarm module.</para>
	</listitem>
	<!-- hddtemp -->
	<listitem>
	  <para><ulink url="http://www.guzu.net/linux/hddtemp.php" type="http">hddtemp</ulink> daemon for reading temperatures from S.M.A.R.T. equipped disks.</para>
	</listitem>
	<!-- Omnibook -->
	<listitem>
	  <para>Linux kernel <ulink url="http://sourceforge.net/projects/omke">Omnibook</ulink> module. (for HP and Toshiba Satellite Laptops)</para>
	</listitem>
	<!-- NVCtrl -->
	<listitem>
	  <para>NVIDIA graphics cards via libNVCtrl (provided with <ulink url="ftp://download.nvidia.com/XFree86/nvidia-settings/"> nvidia-settings</ulink> ).</para>
	</listitem>
      </itemizedlist></para>
    <para>To add <application>MATE Sensors Applet</application> to a panel right-click on the panel to open the panel pop-up menu, then choose <menuchoice> <guimenu>Add to Panel</guimenu> <guimenuitem>Hardware Sensors Monitor</guimenuitem> </menuchoice>.</para> 
  </sect1>
  <!-- ================ Usage ================================ -->
  <!-- Use this section to describe how to use the applet to perform the tasks for 
  which the applet is designed. -->
  <sect1 id="sensors-applet-usage"> 
    <title>Usage</title> 
    <para>When you add <application>MATE Sensors Applet</application> to a panel for the first time, the applet will search for any available sensors to monitor, and will display a sensible default sensor if found (such as the temperature of the CPU).</para>
    <para>Most users will then want to customize the display to their liking, which can be done via the <menuchoice> <guimenuitem>Preferences</guimenuitem> </menuchoice> menu item (see <xref linkend="sensors-applet-preferences"/>).</para>
  </sect1>
  <!-- ============= Preferences ============================= -->
  <!-- Use this section to describe how to customize the applet. -->
  <sect1 id="sensors-applet-preferences"> 
    <title>Preferences</title> 
    <para>To configure <application>MATE Sensors Applet</application>, right-click on the applet, then choose <menuchoice><guimenuitem>Preferences</guimenuitem></menuchoice> from the pop-up menu.</para> 
    <para>The <menuchoice><guimenuitem>Preferences</guimenuitem></menuchoice> window contains the following tabbed sections:</para> 
    <itemizedlist> 
      <listitem> 
	<para> 
	  <xref linkend="sensors-applet-general-options"/>
	</para> 
      </listitem> 
      <listitem> 
	<para> 
	  <xref linkend="sensors-applet-sensors"/>
	</para> 
      </listitem> 
    </itemizedlist>
  </sect1>
  <!-- =============== Customization Subsection ================ -->
  <!-- Use a new section to describe different tabbed sections on the Settings or Preferences
  dialog. -->
  <sect1 id="sensors-applet-general-options"> 
    <title>General Options</title> 
    <variablelist> 
      <varlistentry> 
	<term><guilabel>Display sensors in panel as</guilabel></term> 
	<listitem> 
	  <para>This option selects whether to display sensors in the panel with either their label or icon and their value, or to have no identifier for each sensor and just display their values, or simply to display the icon for each sensor. A graph can also be displayed for each sensor, showing the progression of the sensor value over time.</para>
	  <para>Default: icon with value.</para> 
	</listitem> 
      </varlistentry> 
      <varlistentry> 
	<term><guilabel>Preferred position of sensor values</guilabel></term> 
	<listitem> 
	  <para>Sensors can be display with either their value beside their icon / label, or with the value shown below the icon / label.</para>
	  <para>Default: beside labels / icons.</para> 

	  <note>
	    <para>If there is not enough room in the panel to use the requested position, the best position to ensure all sensor elements are visible will be used instead.</para>
	  </note>
	</listitem> 
      </varlistentry> 
      <varlistentry> 
	<term><guilabel>Graph size (pixels)</guilabel></term> 
	<listitem> 
	  <para>When displaying sensors as graphs, the size of the graph sets either the width of the graph (when displayed on either the top or bottom panel) or the height of the graph (when displayed on the left or right panel).</para>
	  <para>Default: 42 pixels.</para> 
	</listitem> 
      </varlistentry> 
      <varlistentry> 
	<term><guilabel>Temperature scale</guilabel></term> 
	<listitem> 
	  <para>Which scale to use for temperature sensors (Kelvin, Fahrenheit or Celsius are supported).</para>
	  <para>Default: Celsius.</para> 
	</listitem> 
      </varlistentry> 
      <varlistentry> 
	<term><guilabel>Update interval</guilabel></term> 
	<listitem> 
	  <para>How often to update the values of each sensor shown within the panel.</para>
	  <para>Default: 2 seconds.</para> 
	</listitem> 
      </varlistentry> 
      <varlistentry> 
	<term><guilabel>Display notifications</guilabel></term>
	<listitem> 
	  <para>If enabled, MATE Sensors Applet will display notifications to the user when alarm conditions occur.</para>
	  <para>Default: Enabled.</para> 
	  <note>
	    <para>Alarms for individual sensors must also be enabled.</para>
	  </note>
	</listitem> 
      </varlistentry> 
    </variablelist> 
  </sect1>
  <!-- ============= Customization Subsection ===================== -->
  <!-- Another tabbed section on the Preferences dialog. -->
  <sect1 id="sensors-applet-sensors"> 
    <title>Sensors</title> 
    <para>The Sensors tab within the preferences window provides the options for configuring each individual sensor. Each sensor is listed under its specific interface, along with: <itemizedlist>
	<listitem>
	  <para>A fixed ID to identify the sensor within its interface.</para>
	</listitem>
	<listitem>
	  <para>A user selectable icon to identify the sensor within the panel.</para>
	</listitem>

	<listitem>
	  <para>A user editable label to identify the sensor within the panel.</para>
	</listitem>

	<listitem>
	  <para>A check-box to allow the user to enable / disable monitoring and display of the sensor within the panel.</para>
	</listitem>

      </itemizedlist> The <guibutton>Properties</guibutton> button allows a specific sensor to be more finely configured, providing a separate window box for this purpose. (see <xref linkend="sensors-applet-sensor-config-dialog"/>)</para>
    <sect2 id="sensors-applet-sensor-config-dialog">
      <title>Sensor Properties</title>

      <para>Each sensor can be configured with a number of options, including the possibility to scale the sensor value, and to execute an alarm if a certain low or high value is reached. The sensor icon can also be selected if required. The high and low values are used to scale the graph display, as well as set the color for the thermometer displayed within the icons of temperature sensors.</para>

      <para>The sensor value can be scaled in a linear fashion by allowing the user to specify a multiplier and offset for each sensor. As each sensor value is read, it is first multiplied by the 'multiplier' and summed with the 'offset' to produce the final value.</para>

      <variablelist>
	<varlistentry> 
	  <term><guilabel>Sensor value multiplier</guilabel></term> 
	  <listitem> 
	    <para>This option allows the user to specify the multiplier of the sensor value.</para>
	    <para>Default: 1.0</para> 
	  </listitem> 
	</varlistentry> 

	<varlistentry> 
	  <term><guilabel>Sensor value offset</guilabel></term> 
	  <listitem> 
	    <para>This option allows the user to specify the offset for the sensor value.</para>
	    <para>Default: 0.0</para> 
	  </listitem> 
	</varlistentry> 
	<varlistentry> 
	  <term><guilabel>Sensor low value</guilabel></term> 
	  <listitem> 
	    <para>The value at which to trigger an alarm if the sensor drops below this value. This value is also used to scale the display of the graph and temperature icons.</para>
	    <para>Default: dependent on sensor type</para> 
	  </listitem> 
	</varlistentry>
	<varlistentry> 
	  <term><guilabel>Sensor high value</guilabel></term> 
	  <listitem> 
	    <para>The value at which to trigger an alarm if the sensor rises above this value. This value is also used to scale the display of the graph and temperature icons.</para>
	    <para>Default: dependent on sensor type</para> 
	  </listitem> 
	</varlistentry>
	<varlistentry> 
	  <term><guilabel>Enable alarm</guilabel></term> 
	  <listitem>       
	    <para>This option allows the user to enable alarm monitoring for this sensor. When the sensor value rises above, or drops below it's high or low values, the alarm condition will occur. This will display a notification to the user (if enabled), and execute the appropriate Alarm Command every Alarm repeat interval seconds.</para>
	    <para>Default: disabled</para> 
	    <note>
	      <para>Alarms will only execute for active sensors</para>
	    </note>
	  </listitem> 
	</varlistentry>
	<varlistentry> 
	  <term><guilabel>Alarm repeat interval (secs)</guilabel></term> 
	  <listitem> 
	    <para>How often to execute the alarm command while the alarm condition is met. A value of 0 specifies to execute the alarm once only when the alarm condition occurs.</para>
	    <para>Default: 0 seconds</para> 
	    <note>
	      <para>If notifications are also enabled, a notification will be displayed each time the alarm is executed as well to notify the user that the alarm condition has occurred.</para>
	    </note>
	  </listitem> 
	</varlistentry>

	<varlistentry> 
	  <term><guilabel>High alarm command</guilabel></term> 
	  <listitem> 
	    <para>The command to be executed at each repeat interval when the sensor value is equal to or above the upper limit.</para>
	    <para>Default: none</para> 
	  </listitem>
	</varlistentry>

	<varlistentry> 
	  <term><guilabel>Low alarm command</guilabel></term> 
	  <listitem> 
	    <para>The command to be executed at each repeat interval when the sensor value is equal to or below the lower limit.</para>
	    <para>Default: none</para> 
	      <tip>
		<variablelist>
		  <varlistentry>
		    <term><guilabel>Play a sound when the alarm occurs</guilabel></term>
		    <listitem>
		      <para>You can play a sound when the alarm occurs by using the command <command>esdplay</command> which should be available as part of the standard MATE installation. (Note: If this does not work, you could also try <command>aplay</command> which is the default ALSA sound player). <screen><userinput><command>esdplay /usr/share/sounds/gnibbles/gobble.wav</command></userinput></screen></para>
		    </listitem>
		  </varlistentry>
		  <varlistentry>
		    <term><guilabel>Pop-up a window to notify that the alarm has occurred</guilabel></term>
		    <listitem>
		      <para>The program <command>zenity</command> can be used to create dialog boxes to be displayed on the users current display, and can thus be used to create pop-up style notifications that the alarm has occurred. <screen><userinput><command>zenity --warning --title="Sensor Alarm" --text="Sensor Alarm occurred"</command></userinput></screen> For more information regarding Zenity please consult the Zenity <ulink type="help" url="help:zenity">documentation</ulink>.</para>
		  </listitem>
		  </varlistentry>
		<varlistentry>
		  <term><guilabel> Combine multiple commands into one alarm command </guilabel></term>
		  <listitem>
		    <para>Multiple commands can be executed one after the other using the "&amp;&amp;" construct to separate them. To play a sound and pop-up a dialog via Zenity the following command can be used: <screen><userinput><command>esdplay /usr/share/sounds/gnibbles/gobble.wav &amp;&amp; zenity --warning --title="Sensor Alarm" --text="Sensor Alarm occurred"</command></userinput></screen></para>
		  </listitem>
		</varlistentry>
		</variablelist>
	      </tip>
	  </listitem> 
	</varlistentry>
	<varlistentry> 
	  <term><guilabel>Sensor icon</guilabel></term> 
	  <listitem> 
	    <para>Provides a list of available icons to allow the user to select one to represent this sensor.</para>
	  </listitem> 
	</varlistentry>
	<varlistentry> 
	  <term><guilabel>Graph colour</guilabel></term> 
	  <listitem> 
	    <para>The colour to use to display the graph for the sensor.</para>
	    <note>
	      <para>To accurately display graphs both the high and low values for the sensor need to be set correctly.</para>
	    </note>
	  </listitem> 
	</varlistentry>
      </variablelist>
      
    </sect2>
  </sect1> 

  <!-- ============= Bugs ================================== -->
  <!-- This section is optional and is commented out by default. 
  You can use it to describe known bugs and limitations of the 
  program if there are any - please be frank and list all
  problems you know of. 
  
  <sect1 id="myapplet-bugs">
  <title>Known Bugs and Limitations</title>
  <para> </para>
 </sect1>
  -->
  <!-- ============= About ================================== -->
  <!-- This section contains info about the program (not docs), such as
  author's name(s), web page, license, feedback address. This
  section is optional: primary place for this info is "About.." box of
  the program. However, if you do wish to include this info in the
  manual, this is the place to put it. Alternatively, you can put this 
  information in the title page.-->

  <sect1 id="sensors-applet-about">
    <title>About MATE Sensors Applet</title>
    <para>The origin sensor applet was written by Alex Murray (<email>murray.alex@gmail.com</email>). <application>MATE Sensors Applet</application> is further develop by MATE Dev team. To find more information about <application>MATE Sensors Applet</application>, please visit the <ulink url="https://github.com/mate-desktop/mate-sensors-applet/" type="http">MATE Sensors Applet Project Homepage</ulink>.</para>  
    <para>To report a bug or make a suggestion regarding MATE Sensors Applet or this manual, follow the directions at the <ulink url="https://github.com/mate-desktop/mate-sensors-applet/" type="http">project homepage</ulink>.</para>

    <!-- For translations: uncomment this:

    <para>
    Latin translation was done by ME
    (<email>MYNAME@MYADDRESS</email>). Please send all  comments  and
    suggestions regarding this translation to SOMEWHERE.
  </para>

    -->

    <para>This program is distributed under the terms of the GNU General Public licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version. A copy of this licence can be found at this <ulink type="https" url="https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt">link</ulink>, or in the file COPYING included with the source code of this program.</para>
  </sect1> 

</article>
<!-- OVERRIDE DICTIONARY SETTING SO THAT USE AMERICAN ENGLISH STYLE - -->
<!-- FROM MATE HIG -->
<!-- Local IspellDict: english -->
<!-- LocalWords: hddtemp filesystem proc lm README Inspiron windtunnel -->
<!-- LocalWords: ibm ACPI sysfs PowerPC adt Omnibook NVIDIA -->
<!-- LocalWords: libNVCtrl libsensors nvidia esdplay aplay ALSA zenity -->
