path: root/help/C/index.docbook

<?xml version="1.0"?>
<!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">
  <!-- please do not change the id; for translations, change lang to -->
  <!-- appropriate code -->
  <articleinfo> 
    <title>&applet; Manual V&manrevision;</title>
    <copyright> 
      <year>2015-2020</year> 
      <holder>MATE Documentation Team</holder>
    </copyright>
    <copyright> 
      <year>2006</year> 
      <holder>&author-name;</holder> 
    </copyright> 
    <abstract role="description">
      <para>&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> 
	  <!-- <orgname>MATE Documentation
	  Project</orgname> -->
	  <!-- The email address of the author is optional and is commented out by default. 
	  <address> <email>doc-writer2@mate.org</email> </address> 
	  --> 
	</affiliation> 
      </author> 
      <author role="maintainer"> 
	<firstname>Alex</firstname> 
	<surname>Murray</surname> 
	<affiliation> 
	  <!-- <orgname>MATE Documentation
	  Project</orgname> -->
	  <!-- The email address of the author is optional and is commented out by default. 
	  <address> <email>doc-writer2@mate.org</email> </address> 
	  --> 
	</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>&applet; Manual V&manrevision;</revnumber> 
	<date>&date;</date> 
	<revdescription> 
	  <para role="author">&author-name;

	    <email>&author-email;</email>
	  </para> 
	  <!-- <para role="publisher">MATE Documentation Project</para> -->
	</revdescription> 
      </revision> 
    </revhistory> 
    <releaseinfo> This manual describes version &appletversion; of &applet;.
    </releaseinfo> 
    <legalnotice>
      <title>Feedback</title>
      <para>To report a bug or make a suggestion regarding &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>&applet;</primary> 
  </indexterm> 
  <!-- ============= Document Body ============================= -->
  <!-- ============= Introduction ============================== -->
  <sect1 id="sensors-applet-introduction"> 
    <title>Introduction</title> 
    <!-- ==== Figure ============================================= -->
    <figure id="sensors-applet-fig"> 
      <title>&applet;</title> 
      <screenshot> 
	<mediaobject> 
	  <imageobject>
	    <imagedata fileref="figures/applet_in_panel.png" format="PNG"/> 
	  </imageobject>
	  <textobject> 
	    <phrase>&applet; with 3 sensors enabled.</phrase>
	  </textobject>
	</mediaobject> 
      </screenshot> 
    </figure>
    <!-- ==== End of Figure ======================================= -->
    <para>
      <application>&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 &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>&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>&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>&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, &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).

		      <!-- Make sure there is no extra whitespace
			around these commands as it is a verbose
			environment - preserves whitespace and
			carriage returns etc -->

			<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 follow 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 color</guilabel>
	  </term> 
	  <listitem> 
	    <para>The color 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="myapplet-about">
    <title>About &applet;</title>
    <para> The origin sensor applet was written by Alex Murray
      (<email>murray.alex@gmail.com</email>).
      <application>&applet;</application> is further develop by MATE Dev team.
      To find more information about
      <application>&applet;</application>, please visit the <ulink
        url="&project-webpage;" type="http">&applet; Project
        Homepage</ulink>. 
    </para>  
    <para> To report a bug or make a suggestion regarding &applet; or this
      manual, follow the directions at the
      <ulink url="&project-webpage;"
	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 license as published by the Free Software Foundation;
      either version 2 of the License, or (at your option) any later
      version. A copy of this license 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 -->