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
@@ -318,6 +321,7 @@ 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
  and also to use the option to display a multi-rig summary
+ See the end of this API-README for more details
 
 ----------
 
@@ -533,3 +537,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 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: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, 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:
+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, NOTIFY, 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
+	If 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 CPU device: 'Name' and 'ID'
+	They don't exist in the API 'devs' output but you can correctly calculate
+	them from the CPU 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;