Merge pull request #295 from kanoi/api

miner.php documentation (in API-README) v0.1

API-README

@@ -1,6 +1,9 @@
 
 This README contains details about the cgminer RPC API
 
+It also includes some detailed information at the end,
+about using miner.php
+
 
 If you start cgminer with the "--api-listen" option, it will listen on a
 simple TCP/IP socket for single string API requests from the same machine
@@ -316,7 +319,7 @@ api-example.c - a 'C' program to access the API (with source code)
 
 miner.php - an example web page to access the API
  This includes buttons and inputs to attempt access to the privileged commands
- Read the top of the file (miner.php) for details of how to tune the display
+ See the end of this API-README for details of how to tune the display
  and also to use the option to display a multi-rig summary
 
 ----------
@@ -533,3 +536,507 @@ Commands:
  'cpucount'
  'quit'
 
+----------------------------------------
+
+miner.php
+=========
+
+miner.php is a PHP based interface to the cgminer RPC API
+(referred to simply as the API below)
+
+It can show rig details, summaries and input fields to allow you to change
+cgminer
+You can also create custom summary pages with it
+
+It has two levels to the security:
+1) cgminer can be configured to allow or disallow API access and access level
+   security for miner.php
+2) miner.php can be configured to allow or disallow privileged cgminer
+   access, if cgminer is configured to allow privileged access for miner.php
+
+---------
+
+To use miner.php requires a web server with PHP
+
+Basics: On xubuntu 11.04, to install apache2 and php, the commands are:
+ sudo apt-get install apache2
+ sudo apt-get install php5
+ sudo /etc/init.d/apache2 reload
+
+On Fedora 17:
+ yum install httpd php
+ systemctl restart httpd.service
+ systemctl enable httpd.service --system
+
+On windows there are a few options.
+Try one of these (I've never used either one)
+ http://www.apachefriends.org/en/xampp.html
+ http://www.wampserver.com/en/
+
+---------
+
+The basic cgminer option to enable the API is:
+
+ --api-listen
+
+or in your cgminer.conf
+
+ "api-listen" : true,
+
+(without the ',' on the end if it is the last item)
+
+If the web server is running on the cgminer computer, the above
+is the only change required to give miner.php basic access to
+the cgminer API
+
+-
+
+If the web server runs on a different computer to cgminer,
+you will also need to tell cgminer to allow the web server
+to access cgminer's API and tell miner.php where cgminer is
+
+Assuming a.b.c.d is the IP address of the web server, you
+would add the following to cgminer:
+
+ --api-listen --api-allow a.b.c.d
+
+or in your cgminer.conf
+
+ "api-listen" : true,
+ "api-allow" : "a.b.c.d",
+
+to tell cgminer to give the web server read access to the API
+
+You also need to tell miner.php where cgminer is.
+Assuming cgminer is at IP address e.f.g.h, then you would
+edit miner.php and change the line
+
+ $rigs = array('127.0.0.1:4028');
+
+to
+
+ $rigs = array('e.f.g.h:4028');
+
+See --api-network or --api-allow for more access details
+and how to give write access
+
+---------
+
+Once you have a web server with PHP running
+
+ copy your miner.php to the main web folder
+
+On Xubuntu 11.04
+ /var/www/
+
+On Fedora 17
+ /var/www/html/
+
+On Windows
+ see your windows Web/PHP documentation
+
+Assuming the IP address of the web server is a.b.c.d
+Then in your web browser go to:
+
+ http://a.b.c.d/miner.php
+
+Done :)
+
+---------
+
+The rest of this documentation deals with the more complex
+functions of miner.php, using myminer.php, creaing custom
+summaries and displaying multiple cgminer rigs
+
+---------
+
+If you create a file called myminer.php in the same web folder
+where you put miner.php, miner.php will load it when it runs
+
+This is useful, to put any changes you need to make to miner.php
+instead of changing miner.php
+Thus if you update/get a new miner.php, you won't lose the changes
+you have made if you put all your changes in myminer.php
+(and don't change miner.php at all)
+
+A simple example myminer.php that defines 2 rigs
+(that I will keep referring to further below) is:
+
+<?php
+#
+$rigs = array('192.168.0.100:4028:A', '192.168.0.102:4028:B');
+#
+?>
+
+Changes in myminer.php superscede what is in miner.php
+However, this is only valid for variables in miner.php before the
+2 lines where myminer.php is included by miner.php:
+
+ if (file_exists('myminer.php'))
+  include_once('myminer.php');
+ 
+Every variable in miner.php above those 2 lines, can be changed by
+simply defining them in your myminer.php
+
+So although miner.php originally contains the line
+
+ $rigs = array('127.0.0.1:4028');
+
+if you created the example myminer.php given above, it would actually
+change the value of $rigs that is used when miner.php is running
+i.e. you don't have to remove or comment out the $rigs line in miner.php
+It will be superceded by myminer.php
+
+---------
+
+The example.php above also shows how to define more that one rig to
+be shown my miner.php
+
+Each rig string is 2 or 3 values seperated by colons ':'
+They are simply an IP address or host name, followed by the
+port number (usually 4028) and an optional Name string
+
+miner.php displays rig buttons that will show the defails of a single
+rig when you click on it - the button shows either the rig number,
+or the 'Name' string if you provide it
+
+PHP arrays contain each string seperated by a comma, but no comma after
+the last one
+
+So an example for 3 rigs would be:
+
+ $rigs = array('192.168.0.100:4028:A', '192.168.0.102:4028:B', '192.168.0.110:4028:C');
+
+Of course each of the rigs listed would also have to have the API
+running and be set to allow the web server to access the API - as
+explained before
+
+---------
+
+So basically, any variable explained below can be put in myminer.php
+if you wanted to set it to something different to it's default value
+and did not want to change miner.php itself every time you updated it
+
+Below is each variable that can be changed and an explanation of each
+
+---------
+
+Default:
+ $readonly = false;
+
+Set $readonly to true to force miner.php to be readonly
+This means it won't allow you to change cgminer even if the cgminer API
+options allow it to
+
+If you set $readonly to false then it will check cgminer 'privileged'
+and will show input fields and buttons on the single rig page
+allowing you to change devices, pools and even quit or restart
+cgminer
+
+However, if the 'privileged' test fails, the code will set $readonly to
+true
+
+---------
+
+Default:
+ $notify = true;
+
+Set $notify to false to NOT attempt to display the notify command
+table of data
+
+Set $notify to true to attempt to display the notify command on
+the single rig page
+If your older version of cgminer returns an 'Invalid command'
+coz it doesn't have notify - it just shows the error status table
+
+---------
+
+Default:
+ $checklastshare = true;
+
+Set $checklastshare to true to do the following checks:
+If a device's last share is 12x expected ago then display as an error
+If a device's last share is 8x expected ago then display as a warning
+If either of the above is true, also display the whole line highlighted
+This assumes shares are 1 difficulty shares
+
+Set $checklastshare to false to not do the above checks
+
+'expected' is calculated from the device MH/s value
+So for example, a device that hashes at 380MH/s should (on average)
+find a share every 11.3s
+If the last share was found more than 11.3 x 12 seconds (135.6s) ago,
+it is considered an error and highlighted
+If the last share was found more than 11.3 x 8 seconds (90.4s) ago,
+it is considered a warning and highlighted
+
+The default highlighting is very subtle
+
+---------
+
+Default:
+ $poolinputs = false;
+
+Set $poolinputs to true to show the input fields for adding a pool
+and changing the pool priorities on a single rig page
+However, if $readonly is true, it will not display them
+
+---------
+
+Default:
+ $rigs = array('127.0.0.1:4028');
+
+Set $rigs to an array of your cgminer rigs that are running
+ format: 'IP:Port' or 'Host:Port' or 'Host:Port:Name'
+If you only have one rig, it will just show the detail of that rig
+If you have more than one rig it will show a summary of all the rigs
+ with buttons to show the details of each rig -
+ the button contents will be 'Name' rather than rig number, if you
+ specify 'Name'
+e.g. $rigs = array('127.0.0.1:4028','myrig.com:4028:Sugoi');
+
+---------
+
+Default:
+ $rigtotals = true;
+ $forcerigtotals = false;
+
+Set $rigtotals to true to display totals on the single rig page
+'false' means no totals (and ignores $forcerigtotals)
+
+If $rigtotals is true, all data is also right aligned
+With false, it's as before, left aligned
+
+This option is just here to allow people to set it to false
+if they prefer the old non-total display when viewing a single rig
+
+Also, if there is only one line shown in any section, then no
+total will be shown (to save screen space)
+You can force it to always show rig totals on the single rig page,
+even if there is only one line, by setting $forcerigtotals = true;
+
+---------
+
+Default:
+ $socksndtimeoutsec = 10;
+ $sockrcvtimeoutsec = 40;
+
+The numbers are integer seconds
+
+The defaults should be OK for most cases
+However, the longer SND is, the longer you have to wait while
+php hangs if the target cgminer isn't runnning or listening
+
+RCV should only ever be relevant if cgminer has hung but the
+API thread is still running, RCV would normally be >= SND
+
+Feel free to increase SND if your network is very slow
+or decrease RCV if that happens often to you
+
+Also, on some windows PHP, apparently the $usec is ignored
+(so usec can't be specified)
+
+---------
+
+Default:
+ $hidefields = array();
+
+List of fields NOT to be displayed
+You can use this to hide data you don't want to see or don't want
+shown on a public web page
+The list of sections are:
+ SUMMARY, POOL, PGA, GPU, NOTIFY, CONFIG, DEVDETAILS, DEVS
+See the web page for the list of field names (the table headers)
+It is an array of 'SECTION.Field Name' => 1
+
+This example would hide the slightly more sensitive pool information:
+Pool URL and pool username:
+ $hidefields = array('POOL.URL' => 1, 'POOL.User' => 1);
+
+If you just want to hide the pool username:
+ $hidefields = array('POOL.User' => 1);
+
+---------
+
+Default:
+ $ignorerefresh = false;
+ $changerefresh = true;
+ $autorefresh = 0;
+
+Auto-refresh of the page (in seconds) - integers only
+
+$ignorerefresh = true/false always ignore refresh parameters
+$changerefresh = true/false show buttons to change the value
+$autorefresh = default value, 0 means dont auto-refresh
+
+---------
+
+Default:
+ $placebuttons = 'top';
+
+Where to place the Refresh, Summary, Custom Pages, Quit, etc. buttons
+
+Valid values are: 'top' 'bot' 'both'
+ anything else means don't show them - case sensitive
+
+---------
+
+Default:
+ $miner_font_family = 'verdana,arial,sans';
+ $miner_font_size = '13pt';
+
+Change these to set the font and font size used on the web page
+
+---------
+
+Default:
+ $colouroverride = array();
+
+Use this to change the web page colour scheme
+
+See $colourtable in miner.php for the list of possible names to change
+
+Simply put in $colouroverride, just the colours you wish to change
+
+e.g. to change the colour of the header font and background
+you could do the following:
+
+ $colouroverride = array(
+	'td.h color'		=> 'green',
+	'td.h background'	=> 'blue'
+ );
+
+---------
+
+Default:
+ $allowcustompages = true;
+
+Should we allow custom pages?
+(or just completely ignore them and don't display the buttons)
+
+---------
+
+OK this part is more complex: Custom Summary Pages
+
+A custom summary page in an array of 'section' => array('FieldA','FieldB'...)
+
+The section defines what data you want in the summary table and the Fields
+define what data you want shown from that section
+
+Standard sections are:
+ SUMMARY, POOL, PGA, GPU, NOTIFY, CONFIG, DEVDETAILS, DEVS, STATS
+
+Fields are the names as shown on the headers on the normal pages
+
+Fields can be 'name=new name' to display 'name' with a different heading
+'new name'
+
+There are also now joined sections:
+ SUMMARY+POOL, SUMMARY+DEVS, SUMMARY+CONFIG, DEVS+NOTIFY, DEVS+DEVDETAILS
+
+These sections are an SQL join of the two sections and the fields in them
+are named section.field where section. is the section the field comes from
+See the example further down
+
+Also note:
+- empty tables are not shown
+- empty columns (e.g. an unknown field) are not shown
+- missing field data shows as blank
+- the field name '*' matches all fields except in joined sections
+  (useful for STATS)
+
+There are 2 hard coded sections:
+ DATE - displays a date table like 'Summary'
+ RIGS - displays a rig table like 'Summary'
+
+Each custom summary requires a second array, that can be empty, listing fields
+to be totaled for each section
+If there is no matching total data, no total will show
+
+---------
+
+Looking at the Mobile example:
+
+ $mobilepage = array(
+  'DATE' => null,
+  'RIGS' => null,
+  'SUMMARY' => array('Elapsed', 'MHS av', 'Found Blocks=Blks', 
+			Accepted', 'Rejected=Rej', 'Utility'),
+  'DEVS+NOTIFY' => array('DEVS.Name=Name', 'DEVS.ID=ID', 'DEVS.Status=Status',
+			'DEVS.Temperature=Temp', 'DEVS.MHS av=MHS av',
+			'DEVS.Accepted=Accept', 'DEVS.Rejected=Rej',
+			'DEVS.Utility=Utility', 'NOTIFY.Last Not Well=Not Well'),
+  'POOL' => array('POOL', 'Status', 'Accepted', 'Rejected=Rej', 'Last Share Time'));
+
+ $mobilesum = array(
+  'SUMMARY' => array('MHS av', 'Found Blocks', 'Accepted', 'Rejected', 'Utility'),
+  'DEVS+NOTIFY' => array('DEVS.MHS av', 'DEVS.Accepted', 'DEVS.Rejected', 'DEVS.Utility'),
+  'POOL' => array('Accepted', 'Rejected'));
+
+ $customsummarypages = array('Mobile' => array($mobilepage, $mobilesum));
+
+This will show 5 tables (according to $mobilepage)
+Each table will have the chosen details for all the rigs specified in $rigs
+
+ DATE
+	A single box with the web server's current date and time
+
+ RIGS
+	A table of the rigs: description, time, versions etc
+
+ SUMMARY
+
+	This will use the API 'summary' command and show the selected fields:
+		Elapsed, MHS av, Found Blocks, Accepted, Rejected and Utility
+	However, 'Rejected=Rej' means that the header displayed for the 'Rejected'
+	field will be 'Rej', instead of 'Rejected' (to save space)
+	Same for 'Found Blocks=Blks' - to save space
+
+ DEVS+NOTIFY
+
+	This will list each of the devices on each rig and display the list of
+	fields as shown
+	It will also include the 'Last Not Well' field from the 'notify' command
+	so you know when the device was last not well
+
+	You will notice that you need to rename each field e.g. 'DEVS.Name=Name'
+	since each field name in the join between DEVS and NOTIFY is actually
+	section.fieldname, not just fieldname
+
+	The join code automatically adds 2 fields to each GPU device: 'Name' and 'ID'
+	They don't exist in the API 'devs' output but you can correctly calculate
+	them from the GPU device data
+	These two fields are used to join DEVS to NOTIFY i.e. find the NOTIFY
+	record that has the same Name and ID as the DEVS record and join them
+
+ POOL
+
+	This will use the API 'pools' command and show the selected fields:
+		POOL, Status, Accepted, Rejected, Last Share Time
+	Again, I renamed the 'Rejected' field using 'Rejected=Rej', to save space
+
+$mobilesum lists the sections and fields that should have a total
+You can't define them for 'DATE' or 'RIGS' since they are hard coded tables
+The example given:
+
+ SUMMARY
+	Show a total at the bottom of the columns for:
+		MHS av, Found Blocks, Accepted, Rejected, Utility
+
+	Firstly note that you use the original name i.e. for 'Rejected=Rej'
+	you use 'Rejected', not 'Rej' and not 'Rejected=Rej'
+
+	Secondly note that it simply adds up the fields
+	If you ask for a total of a string field you will get the numerical
+	sum of the string data
+
+ DEVS+NOTIFY
+
+	Simply note in this join example that you must use the original field
+	names which are section.fieldname, not just fieldname
+
+ POOL
+	Show a total at the bottom of the columns for:
+		Accepted and Rejected
+
+	Again remember to use the original field name 'Rejected'

miner.php

@@ -10,9 +10,8 @@ global $allowcustompages, $customsummarypages;
 global $miner_font_family, $miner_font_size;
 global $colouroverride, $placebuttons;
 #
-# Don't touch these 2 - see $rigs below
+# See API-README for more details of these variables and how
-$miner = null;
+# to configure miner.php
-$port = null;
 #
 # Set $readonly to true to force miner.php to be readonly
 # Set $readonly to false then it will check cgminer 'privileged'
@@ -20,8 +19,6 @@ $readonly = false;
 #
 # Set $notify to false to NOT attempt to display the notify command
 # Set $notify to true to attempt to display the notify command
-# If your older version of cgminer returns an 'Invalid command'
-#  coz it doesn't have notify - it just shows the error status table
 $notify = true;
 #
 # Set $checklastshare to true to do the following checks:
@@ -38,44 +35,20 @@ $poolinputs = false;
 #
 # Set $rigs to an array of your cgminer rigs that are running
 #  format: 'IP:Port' or 'Host:Port' or 'Host:Port:Name'
-# If you only have one rig, it will just show the detail of that rig
-# If you have more than one rig it will show a summary of all the rigs
-#  with buttons to show the details of each rig -
-#  the button contents will be 'Name' if that was specified
-# e.g. $rigs = array('127.0.0.1:4028','myrig.com:4028:Sugoi');
 $rigs = array('127.0.0.1:4028');
 #
 # Set $rigtotals to true to display totals on the single rig page
 # 'false' means no totals (and ignores $forcerigtotals)
-# If $rigtotals is true, all data is also right aligned
-#	with false, it's as before, left aligned
-# This option is just here to allow people to set it to false
-# if they prefer the old non-total display when viewing a single rig
-# Also, if there is only one line shown in any section, then no
-# total will be shown (to save screen space)
 # You can force it to always show rig totals when there is only
 # one line by setting $forcerigtotals = true;
 $rigtotals = true;
 $forcerigtotals = false;
 #
 # These should be OK for most cases
-# However, the longer SND is, the longer you have to wait while
-# php hangs if the target cgminer isn't runnning or listening
-# RCV should only ever be relevant if cgminer has hung but the
-# API thread is still running, RCV would normally be >= SND
-# Feel free to increase SND if your network is very slow
-# or decrease RCV if that happens often to you
-# Also, on some windows PHP, apparently the $usec is ignored
 $socksndtimeoutsec = 10;
 $sockrcvtimeoutsec = 40;
 #
 # List of fields NOT to be displayed
-# You can use this to hide data you don't want to see or don't want
-# shown on a public web page
-# The list of sections are:
-#  SUMMARY, POOL, PGA, GPU, NOTIFY, CONFIG, NOTIFY, DEVDETAILS, DEVS
-# See the web page for the list of field names (the table headers)
-# It is an array of 'SECTION.Field Name' => 1
 # This example would hide the slightly more sensitive pool information
 #$hidefields = array('POOL.URL' => 1, 'POOL.User' => 1);
 $hidefields = array();
@@ -93,15 +66,7 @@ $autorefresh = 0;
 $allowcustompages = true;
 #
 # OK this is a bit more complex item: Custom Summary Pages
-# A custom summary page in an array of 'section' => array('FieldA','FieldB'...)
+# As mentioned above, see API-README
-#  Field can be 'name=new name' to display 'name' with a different heading 'new name'
-# This makes up what is displayed with each 'section' separately as a table
-# - empty tables are not shown
-# - empty columns (an unknown field) are not shown
-# - and missing field data shows as blank
-# - section = 'DATE' displays a date table like 'Summary'
-# - section = 'RIGS' displays a rig table like 'Summary'
-# There is a second array, listing fields to be totaled for each section
 # see the example below (if there is no matching data, no total will show)
 $mobilepage = array(
  'DATE' => null,
@@ -176,6 +141,10 @@ $colourtable = array(
 	'td.lo background'	=> '#deffff'
 );
 #
+# Don't touch these 2
+$miner = null;
+$port = null;
+#
 # Ensure it is only ever shown once
 global $showndate;
 $showndate = false;