Hash :
6c251575
Author :
Date :
2012-09-12T19:05:50
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158
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
running cgminer and reply with a string and then close the socket each time
If you add the "--api-network" option, it will accept API requests from any
network attached computer.
You can only access the comands that reply with data in this mode.
By default, you cannot access any privileged command that affects the miner -
you will receive an access denied status message see --api-allow below.
You can specify IP addresses/prefixes that are only allowed to access the API
with the "--api-allow" option e.g. --api-allow W:192.168.0.1,10.0.0/24
will allow 192.168.0.1 or any address matching 10.0.0.*, but nothing else
IP addresses are automatically padded with extra '.0's as needed
Without a /prefix is the same as specifying /32
0/0 means all IP addresses.
The 'W:' on the front gives that address/subnet privileged access to commands
that modify cgminer (thus all API commands)
Without it those commands return an access denied status.
See --api-groups below to define other groups like W:
Privileged access is checked in the order the IP addresses were supplied to
"--api-allow"
The first match determines the privilege level.
Using the "--api-allow" option overides the "--api-network" option if they
are both specified
With "--api-allow", 127.0.0.1 is not by default given access unless specified
More groups (like the privileged group W:) can be defined using the
--api-groups command
Valid groups are only the letters A-Z (except R & W are predefined) and are
not case sensitive
The R: group is the same as not privileged access
The W: group is (as stated) privileged access (thus all API commands)
To give an IP address/subnet access to a group you use the group letter
in front of the IP address instead of W: e.g. P:192.168.0/32
An IP address/subnet can only be a member of one group
A sample API group would be:
--api-groups P:switchpool:enablepool:addpool:disablepool:removepool:poolpriority:*
This would create a group 'P' that can do all current pool commands and all
non-priviliged commands - the '*' means all non-priviledged commands
Without the '*' the group would only have access to the pool commands
Defining multiple groups example:
--api-groups Q:quit:restart:*,S:save
This would define 2 groups:
Q: that can 'quit' and 'restart' as well as all non-priviledged commands
S: that can only 'save' and no other commands
The RPC API request can be either simple text or JSON.
If the request is JSON (starts with '{'), it will reply with a JSON formatted
response, otherwise it replies with text formatted as described further below.
The JSON request format required is '{"command":"CMD","parameter":"PARAM"}'
(though of course parameter is not required for all requests)
where "CMD" is from the "Request" column below and "PARAM" would be e.g.
the CPU/GPU number if required.
An example request in both formats to set GPU 0 fan to 80%:
gpufan|0,80
{"command":"gpufan","parameter":"0,80"}
The format of each reply (unless stated otherwise) is a STATUS section
followed by an optional detail section
From API version 1.7 onwards, reply strings in JSON and Text have the
necessary escaping as required to avoid ambiguity - they didn't before 1.7
For JSON the 2 characters '"' and '\' are escaped with a '\' before them
For Text the 4 characters '|' ',' '=' and '\' are escaped the same way
Only user entered information will contain characters that require being
escaped, such as Pool URL, User and Password or the Config save filename,
when they are returned in messages or as their values by the API
For API version 1.4 and later:
The STATUS section is:
STATUS=X,When=NNN,Code=N,Msg=string,Description=string|
STATUS=X Where X is one of:
W - Warning
I - Informational
S - Success
E - Error
F - Fatal (code bug)
When=NNN
Standard long time of request in seconds
Code=N
Each unique reply has a unigue Code (See api.c - #define MSG_NNNNNN)
Msg=string
Message matching the Code value N
Description=string
This defaults to the cgminer version but is the value of --api-description
if it was specified at runtime.
For API version 1.10 and later:
The list of requests - a (*) means it requires privileged access - and replies are:
Request Reply Section Details
------- ------------- -------
version VERSION CGMiner=cgminer, version
API=API| version
config CONFIG Some miner configuration information:
GPU Count=N, <- the number of GPUs
PGA Count=N, <- the number of PGAs
CPU Count=N, <- the number of CPUs
Pool Count=N, <- the number of Pools
ADL=X, <- Y or N if ADL is compiled in the code
ADL in use=X, <- Y or N if any GPU has ADL
Strategy=Name, <- the current pool strategy
Log Interval=N, <- log interval (--log N)
Device Code=GPU ICA , <- spaced list of compiled devices
OS=Linux/Apple/..., <- operating System
Failover-Only=true/false | <- failover-only setting
summary SUMMARY The status summary of the miner
e.g. Elapsed=NNN,Found Blocks=N,Getworks=N,...|
pools POOLS The status of each pool
e.g. Pool=0,URL=http://pool.com:6311,Status=Alive,...|
devs DEVS Each available GPU, PGA and CPU with their details
e.g. GPU=0,Accepted=NN,MHS av=NNN,...,Intensity=D|
Last Share Time=NNN, <- standand long time in seconds
(or 0 if none) of last accepted share
Last Share Pool=N, <- pool number (or -1 if none)
Will not report PGAs if PGA mining is disabled
Will not report CPUs if CPU mining is disabled
gpu|N GPU The details of a single GPU number N in the same
format and details as for DEVS
pga|N PGA The details of a single PGA number N in the same
format and details as for DEVS
This is only available if PGA mining is enabled
Use 'pgacount' or 'config' first to see if there are any
cpu|N CPU The details of a single CPU number N in the same
format and details as for DEVS
This is only available if CPU mining is enabled
Use 'cpucount' or 'config' first to see if there are any
gpucount GPUS Count=N| <- the number of GPUs
pgacount PGAS Count=N| <- the number of PGAs
Always returns 0 if PGA mining is disabled
cpucount CPUS Count=N| <- the number of CPUs
Always returns 0 if CPU mining is disabled
switchpool|N (*)
none There is no reply section just the STATUS section
stating the results of switching pool N to the
highest priority (the pool is also enabled)
The Msg includes the pool URL
enablepool|N (*)
none There is no reply section just the STATUS section
stating the results of enabling pool N
The Msg includes the pool URL
addpool|URL,USR,PASS (*)
none There is no reply section just the STATUS section
stating the results of attempting to add pool N
The Msg includes the pool URL
Use '\\' to get a '\' and '\,' to include a comma
inside URL, USR or PASS
poolpriority|N,... (*)
none There is no reply section just the STATUS section
stating the results of changing pool priorities
See usage below
disablepool|N (*)
none There is no reply section just the STATUS section
stating the results of disabling pool N
The Msg includes the pool URL
removepool|N (*)
none There is no reply section just the STATUS section
stating the results of removing pool N
The Msg includes the pool URL
N.B. all details for the pool will be lost
gpuenable|N (*)
none There is no reply section just the STATUS section
stating the results of the enable request
gpudisable|N (*)
none There is no reply section just the STATUS section
stating the results of the disable request
gpurestart|N (*)
none There is no reply section just the STATUS section
stating the results of the restart request
gpuintensity|N,I (*)
none There is no reply section just the STATUS section
stating the results of setting GPU N intensity to I
gpumem|N,V (*)
none There is no reply section just the STATUS section
stating the results of setting GPU N memoryclock to V MHz
gpuengine|N,V (*)
none There is no reply section just the STATUS section
stating the results of setting GPU N clock to V MHz
gpufan|N,V (*)
none There is no reply section just the STATUS section
stating the results of setting GPU N fan speed to V%
gpuvddc|N,V (*)
none There is no reply section just the STATUS section
stating the results of setting GPU N vddc to V
save|filename (*)
none There is no reply section just the STATUS section
stating success or failure saving the cgminer config
to filename
The filename is optional and will use the cgminer
default if not specified
quit (*) none There is no status section but just a single "BYE"
reply before cgminer quits
notify NOTIFY The last status and history count of each devices problem
This lists all devices including those not supported
by the 'devs' command
e.g. NOTIFY=0,Name=GPU,ID=0,Last Well=1332432290,...|
privileged (*)
none There is no reply section just the STATUS section
stating an error if you do not have privileged access
to the API and success if you do have privilege
The command doesn't change anything in cgminer
pgaenable|N (*)
none There is no reply section just the STATUS section
stating the results of the enable request
You cannot enable a PGA if it's status is not WELL
This is only available if PGA mining is enabled
pgadisable|N (*)
none There is no reply section just the STATUS section
stating the results of the disable request
This is only available if PGA mining is enabled
pgaidentify|N (*)
none There is no reply section just the STATUS section
stating the results of the identify request
This is only available if PGA mining is enabled
and currently only BFL singles support this command
On a BFL single it will flash the led on the front
of the device for appoximately 4s
All other non BFL PGA devices will return a warning
status message stating that they dont support it
This adds a 4s delay to the BFL share being processed
so you may get a message stating that procssing took
longer than 7000ms if the request was sent towards
the end of the timing of any work being worked on
e.g.: BFL0: took 8438ms - longer than 7000ms
You should ignore this
devdetails DEVDETAILS Each device with a list of their static details
This lists all devices including those not supported
by the 'devs' command
e.g. DEVDETAILS=0,Name=GPU,ID=0,Driver=opencl,...|
restart (*) none There is no status section but just a single "RESTART"
reply before cgminer restarts
stats STATS Each device or pool that has 1 or more getworks
with a list of stats regarding getwork times
The values returned by stats may change in future
versions thus would not normally be displayed
Device drivers are also able to add stats to the
end of the details returned
check|cmd COMMAND Exists=Y/N, <- 'cmd' exists in this version
Access=Y/N| <- you have access to use 'cmd'
failover-only|true/false (*)
none There is no reply section just the STATUS section
stating what failover-only was set to
coin COIN Coin mining information:
Hash Method=sha256/scrypt,
Current Block Time=N.N, <- 0 means none
Current Block Hash=XXXX..., <- blank if none
LP=true/false| <- LP is in use on at least 1 pool
debug|setting (*)
DEBUG Debug settings
The optional commands for 'setting' are the same as
the screen curses debug settings
You can only specify one setting
Only the first character is checked (case insensitive):
Silent, Quiet, Verbose, Debug, RPCProto, PerDevice, Normal
The output fields are (as above):
Silent=true/false,
Quiet=true/false,
Verbose=true/false,
Debug=true/false,
RPCProto=true/false,
PerDevice=true/false|
When you enable, disable or restart a GPU or PGA, you will also get Thread messages
in the cgminer status window
The 'poolpriority' command can be used to reset the priority order of multiple
pools with a single command - 'switchpool' only sets a single pool to first priority
Each pool should be listed by id number in order of preference (first = most
preferred)
Any pools not listed will be prioritised after the ones that are listed, in the
priority order they were originally
If the priority change affects the miner's preference for mining, it may switch
immediately
When you switch to a different pool to the current one (including by priority
change), you will get a 'Switching to URL' message in the cgminer status
windows
Obviously, the JSON format is simply just the names as given before the '='
with the values after the '='
If you enable cgminer debug (-D or --debug) or, when cgminer debug is off,
turn on debug with the API command 'debug|debug' you will also get messages
showing some details of the requests received and the replies
There are included 4 program examples for accessing the API:
api-example.php - a php script to access the API
usAge: php api-example.php command
by default it sends a 'summary' request to the miner at 127.0.0.1:4028
If you specify a command it will send that request instead
You must modify the line "$socket = getsock('127.0.0.1', 4028);" at the
beginning of "function request($cmd)" to change where it looks for cgminer
API.java/API.class
a java program to access the API (with source code)
usAge is: java API command address port
Any missing or blank parameters are replaced as if you entered:
java API summary 127.0.0.1 4028
api-example.c - a 'C' program to access the API (with source code)
usAge: api-example [command [ip/host [port]]]
again, as above, missing or blank parameters are replaced as if you entered:
api-example summary 127.0.0.1 4028
miner.php - an example web page to access the API
This includes buttons and inputs to attempt access to the privileged commands
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
----------
Feature Changelog for external applications using the API:
API V1.19
Added API commands:
'debug'
'pgaidentify|N'
Modified API commands:
Change pool field name 'Diff1 Shares' to 'Diff1 Work'
'devs' - add 'Diff1 Work' to all devices
'gpu|N' - add 'Diff1 Work'
'pga|N' - add 'Diff1 Work'
'notify' - add '*Dev Throttle' (for BFL Singles)
'pools' - add 'Proxy Type', 'Proxy'
----------
API V1.18 (cgminer v2.7.4)
Modified API commands:
'stats' - add 'Work Had Roll Time', 'Work Can Roll', 'Work Had Expire',
'Work Roll Time' to the pool stats
'config' - include 'ScanTime'
----------
API V1.17 (cgminer v2.7.1)
Added API commands:
'coin'
Modified API commands:
'summary' - add 'Work Utility'
'pools' - add 'Diff1 Shares'
----------
API V1.16 (cgminer v2.6.5)
Added API commands:
'failover-only'
Modified API commands:
'config' - include failover-only state
----------
API V1.15 (cgminer v2.6.1)
Added API commands:
'poolpriority'
----------
API V1.14 (cgminer v2.5.0)
Modified API commands:
'stats' - more icarus timing stats added
'notify' - include new device comms error counter
The internal code for handling data was rewritten (~25% of the code)
Completely backward compatible
----------
API V1.13 (cgminer v2.4.4)
Added API commands:
'check'
Support was added to cgminer for API access groups with the --api-groups option
It's 100% backward compatible with previous --api-access commands
----------
API V1.12 (cgminer v2.4.3)
Modified API commands:
'stats' - more pool stats added
Support for the ModMinerQuad FPGA was added
----------
API V1.11 (cgminer v2.4.2)
Modified API commands:
'save' no longer requires a filename (use default if not specified)
'save' incorrectly returned status E (error) on success before.
It now correctly returns S (success)
----------
API V1.10 (cgminer v2.4.1)
Added API commands:
'stats'
N.B. the 'stats' command can change at any time so any specific content
present should not be relied upon.
The data content is mainly used for debugging purposes or hidden options
in cgminer and can change as development work requires
Modified API commands:
'pools' added "Last Share Time"
----------
API V1.9 (cgminer v2.4.0)
Added API commands:
'restart'
Modified API commands:
'notify' corrected invalid JSON
----------
API V1.8 (cgminer v2.3.5)
Added API commands:
'devdetails'
Support for the ZTex FPGA was added
----------
API V1.7 (cgminer v2.3.4)
Added API commands:
'removepool'
Modified API commands:
'pools' added "User"
From API version 1.7 onwards, reply strings in JSON and Text have the
necessary escaping as required to avoid ambiguity
For JSON the 2 characters '"' and '\' are escaped with a '\' before them
For Text the 4 characters '|' ',' '=' and '\' are escaped the same way
----------
API V1.6 (cgminer v2.3.2)
Added API commands:
'pga'
'pgaenable'
'pgadisable'
'pgacount'
Modified API commands:
'devs' now includes Icarus and Bitforce FPGA devices
'notify' added "*" to the front of the name of all numeric error fields
'config' correct "Log Interval" to use numeric (not text) type for JSON
Support for Icarus and Bitforce FPGAs was added
----------
API V1.5 was not released
----------
API V1.4 (Kano's interim release of cgminer v2.3.1)
Added API commands:
'notify'
Modified API commands:
'config' added "Device Code" and "OS"
Added "When" to the STATUS reply section of all commands
----------
API V1.3 (cgminer v2.3.1-2)
Added API commands:
'addpool'
Modified API commands:
'devs'/'gpu' added "Total MH" for each device
'summary' added "Total MH"
----------
API V1.2 (cgminer v2.3.0)
Added API commands:
'enablepool'
'disablepool'
'privileged'
Modified API commands:
'config' added "Log Interval"
Starting with API V1.2, any attempt to access a command that requires
privileged security, from an IP address that does not have privileged
security, will return an "Access denied" Error Status
----------
API V1.1 (cgminer v2.2.4)
There were no changes to the API commands in cgminer v2.2.4,
however support was added to cgminer for IP address restrictions
with the --api-allow option
----------
API V1.1 (cgminer v2.2.2)
Prior to V1.1, devs/gpu incorrectly reported GPU0 Intensity for all GPUs
Modified API commands:
'devs'/'gpu' added "Last Share Pool" and "Last Share Time" for each device
----------
API V1.0 (cgminer v2.2.0)
Remove default CPU support
Added API commands:
'config'
'gpucount'
'cpucount'
'switchpool'
'gpuintensity'
'gpumem'
'gpuengine'
'gpufan'
'gpuvddc'
'save'
----------
API V0.7 (cgminer v2.1.0)
Initial release of the API in the main cgminer git
Commands:
'version'
'devs'
'pools'
'summary'
'gpuenable'
'gpudisable'
'gpurestart'
'gpu'
'cpu'
'gpucount'
'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:
$dfmt = 'H:i:s j-M-Y \U\T\CP';
Define the date format used to print full length dates
If you get the string 'UTCP' on the end of your dates shown, that
means you are using an older version of PHP and you can instead use:
$dfmt = 'H:i:s j-M-Y \U\T\CO';
The PHP documentation on the date format is here:
http://us.php.net/manual/en/function.date.php
---------
Default:
$title = 'Mine';
Web page title
If you know PHP you can of course use code to define it e.g.
$title = 'My Rig at: '.date($dfmt);
Which would set the web page title to something like:
My Rig at: 10:34:00 22-Aug-2012 UTC+10:00
---------
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, COIN
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
SUMMARY+COIN
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 and COIN)
There are 2 hard coded sections:
DATE - displays a date table like at the start of 'Summary'
RIGS - displays a rig table like at the start of '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 I 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'