/ API-README
API-README
1 2 This README contains details about the cgminer RPC API 3 4 It also includes some detailed information at the end, 5 about using miner.php 6 7 8 If you start cgminer with the "--api-listen" option, it will listen on a 9 simple TCP/IP socket for single string API requests from the same machine 10 running cgminer and reply with a string and then close the socket each time 11 If you add the "--api-network" option, it will accept API requests from any 12 network attached computer. 13 14 You can only access the comands that reply with data in this mode. 15 By default, you cannot access any privileged command that affects the miner - 16 you will receive an access denied status message see --api-allow below. 17 18 You can specify IP addresses/prefixes that are only allowed to access the API 19 with the "--api-allow" option e.g. --api-allow W:192.168.0.1,10.0.0/24 20 will allow 192.168.0.1 or any address matching 10.0.0.*, but nothing else 21 IP addresses are automatically padded with extra '.0's as needed 22 Without a /prefix is the same as specifying /32 23 0/0 means all IP addresses. 24 The 'W:' on the front gives that address/subnet privileged access to commands 25 that modify cgminer (thus all API commands) 26 Without it those commands return an access denied status. 27 See --api-groups below to define other groups like W: 28 Privileged access is checked in the order the IP addresses were supplied to 29 "--api-allow" 30 The first match determines the privilege level. 31 Using the "--api-allow" option overides the "--api-network" option if they 32 are both specified 33 With "--api-allow", 127.0.0.1 is not by default given access unless specified 34 35 If you start cgminer also with the "--api-mcast" option, it will listen for 36 a multicast message and reply to it with a message containing it's API port 37 number, but only if the IP address of the sender is allowed API access 38 39 More groups (like the privileged group W:) can be defined using the 40 --api-groups command 41 Valid groups are only the letters A-Z (except R & W are predefined) and are 42 not case sensitive 43 The R: group is the same as not privileged access 44 The W: group is (as stated) privileged access (thus all API commands) 45 To give an IP address/subnet access to a group you use the group letter 46 in front of the IP address instead of W: e.g. P:192.168.0/32 47 An IP address/subnet can only be a member of one group 48 A sample API group would be: 49 --api-groups 50 P:switchpool:enablepool:addpool:disablepool:removepool:poolpriority:* 51 This would create a group 'P' that can do all current pool commands and all 52 non-priviliged commands - the '*' means all non-priviledged commands 53 Without the '*' the group would only have access to the pool commands 54 Defining multiple groups example: 55 --api-groups Q:quit:restart:*,S:save 56 This would define 2 groups: 57 Q: that can 'quit' and 'restart' as well as all non-priviledged commands 58 S: that can only 'save' and no other commands 59 60 The RPC API request can be either simple text or JSON. 61 62 If the request is JSON (starts with '{'), it will reply with a JSON formatted 63 response, otherwise it replies with text formatted as described further below. 64 65 The JSON request format required is '{"command":"CMD","parameter":"PARAM"}' 66 (though of course parameter is not required for all requests) 67 where "CMD" is from the "Request" column below and "PARAM" would be e.g. 68 the ASC/PGA number if required. 69 70 An example request in both formats to disable Hotplug: 71 hotplug|0 72 {"command":"hotplug","parameter":"0"} 73 74 The format of each reply (unless stated otherwise) is a STATUS section 75 followed by an optional detail section 76 77 From API version 1.7 onwards, reply strings in JSON and Text have the 78 necessary escaping as required to avoid ambiguity - they didn't before 1.7 79 For JSON the 2 characters '"' and '\' are escaped with a '\' before them 80 For Text the 4 characters '|' ',' '=' and '\' are escaped the same way 81 82 Only user entered information will contain characters that require being 83 escaped, such as Pool URL, User and Password or the Config save filename, 84 when they are returned in messages or as their values by the API 85 86 For API version 1.4 and later: 87 88 The STATUS section is: 89 90 STATUS=X,When=NNN,Code=N,Msg=string,Description=string| 91 92 STATUS=X Where X is one of: 93 W - Warning 94 I - Informational 95 S - Success 96 E - Error 97 F - Fatal (code bug) 98 99 When=NNN 100 Standard long time of request in seconds 101 102 Code=N 103 Each unique reply has a unique Code (See api.c - #define MSG_NNNNNN) 104 105 Msg=string 106 Message matching the Code value N 107 108 Description=string 109 This defaults to the cgminer version but is the value of --api-description 110 if it was specified at runtime. 111 112 With API V3.1 you can also request multiple report replies in a single command 113 request 114 e.g. to request both summary and devs, the command would be summary+devs 115 116 This is only available for report commands that don't need parameters, 117 and is not available for commands that change anything 118 Any parameters supplied will be ignored 119 120 The extra formatting of the result is to have a section for each command 121 e.g. CMD=summary|STATUS=....|CMD=devs|STATUS=... 122 With JSON, each result is within a section of the command name 123 e.g. {"summary":{"STATUS":[{"STATUS":"S"...}],"SUMMARY":[...],"id":1}, 124 "devs":{"STATUS":[{"STATUS:"S"...}],"DEVS":[...],"id":1},"id":1} 125 126 As before, if you supply bad JSON you'll just get a single 'E' STATUS section 127 in the old format, since it doesn't switch to using the new format until it 128 correctly processes the JSON and can match a '+' in the command 129 130 If you request a command multiple times, e.g. devs+devs 131 you'll just get it once 132 If this results in only one command, it will still use the new layout 133 with just the one command 134 135 If you request a command that can't be used due to requiring parameters, 136 a command that isn't a report, or an invalid command, you'll get an 'E' STATUS 137 for that one but it will still attempt to process all other commands supplied 138 139 Blank/missing commands are ignored e.g. +devs++ 140 will just show 'devs' using the new layout 141 142 For API version 1.10 and later: 143 144 The list of requests - a (*) means it requires privileged access - and replies: 145 146 Request Reply Section Details 147 ------- ------------- ------- 148 version VERSION CGMiner=cgminer, version 149 API=API| version 150 151 config CONFIG Some miner configuration information: 152 ASC Count=N, <- the number of ASCs 153 PGA Count=N, <- the number of PGAs 154 Pool Count=N, <- the number of Pools 155 Strategy=Name, <- the current pool strategy 156 Log Interval=N, <- log interval (--log N) 157 Device Code=ICA , <- spaced list of compiled 158 device drivers 159 OS=Linux/Apple/..., <- operating System 160 161 summary SUMMARY The status summary of the miner 162 e.g. Elapsed=NNN,Found Blocks=N,Getworks=N,...| 163 164 pools POOLS The status of each pool e.g. 165 Pool=0,URL=http://pool.com:6311,Status=Alive,...| 166 167 devs DEVS Each available PGA and ASC with their details 168 e.g. ASC=0,Accepted=NN,MHS av=NNN,...,Intensity=D| 169 Last Share Time=NNN, <- standand long time in sec 170 (or 0 if none) of last accepted share 171 Last Share Pool=N, <- pool number (or -1 if none) 172 Last Valid Work=NNN, <- standand long time in sec 173 of last work returned that wasn't an HW: 174 Will not report PGAs if PGA mining is disabled 175 Will not report ASCs if ASC mining is disabled 176 177 edevs[|old] DEVS The same as devs, except it ignores blacklisted 178 devices and zombie devices 179 If you specify the optional 'old' parameter, then 180 the output will include zombie devices that became 181 zombies less than 'old' seconds ago 182 A value of zero for 'old', which is the default, 183 means ignore all zombies 184 It will return an empty list of devices if all 185 devices are blacklisted or zombies 186 187 pga|N PGA The details of a single PGA number N in the same 188 format and details as for DEVS 189 This is only available if PGA mining is enabled 190 Use 'pgacount' or 'config' first to see if there 191 are any 192 193 pgacount PGAS Count=N| <- the number of PGAs 194 Always returns 0 if PGA mining is disabled 195 196 switchpool|N (*) 197 none There is no reply section just the STATUS section 198 stating the results of switching pool N to the 199 highest priority (the pool is also enabled) 200 The Msg includes the pool URL 201 202 enablepool|N (*) 203 none There is no reply section just the STATUS section 204 stating the results of enabling pool N 205 The Msg includes the pool URL 206 207 addpool|URL,USR,PASS (*) 208 none There is no reply section just the STATUS section 209 stating the results of attempting to add pool N 210 The Msg includes the pool number and URL 211 Use '\\' to get a '\' and '\,' to include a comma 212 inside URL, USR or PASS 213 214 poolpriority|N,... (*) 215 none There is no reply section just the STATUS section 216 stating the results of changing pool priorities 217 See usage below 218 219 poolquota|N,Q (*) 220 none There is no reply section just the STATUS section 221 stating the results of changing pool quota to Q 222 223 disablepool|N (*) 224 none There is no reply section just the STATUS section 225 stating the results of disabling pool N 226 The Msg includes the pool URL 227 228 removepool|N (*) 229 none There is no reply section just the STATUS section 230 stating the results of removing pool N 231 The Msg includes the pool URL 232 N.B. all details for the pool will be lost 233 234 save|filename (*) 235 none There is no reply section just the STATUS section 236 stating success or failure saving the cgminer 237 config to filename 238 The filename is optional and will use the cgminer 239 default if not specified 240 241 quit (*) none Status is a single "BYE" reply before cgminer 242 quits 243 244 notify NOTIFY The last status and history count of each devices 245 problem 246 This lists all devices including those not 247 supported by the 'devs' command e.g. 248 NOTIFY=0,Name=ASC,ID=0,Last Well=1332432290,...| 249 250 privileged (*) 251 none There is no reply section just the STATUS section 252 stating an error if you do not have privileged 253 access to the API and success if you do have 254 privilege 255 The command doesn't change anything in cgminer 256 257 pgaenable|N (*) 258 none There is no reply section just the STATUS section 259 stating the results of the enable request 260 You cannot enable a PGA if it's status is not WELL 261 This is only available if PGA mining is enabled 262 263 pgadisable|N (*) 264 none There is no reply section just the STATUS section 265 stating the results of the disable request 266 This is only available if PGA mining is enabled 267 268 pgaidentify|N (*) 269 none There is no reply section just the STATUS section 270 stating the results of the identify request 271 This is only available if PGA mining is enabled 272 and currently only BFL singles and Cairnsmore1's 273 with the appropriate firmware support this command 274 On a BFL single it will flash the led on the front 275 of the device for appoximately 4s 276 All other non BFL,ICA PGA devices will return a 277 warning status message stating that they dont 278 support it. Non-CMR ICAs will ignore the command. 279 This adds a 4s delay to the BFL share being 280 processed so you may get a message stating that 281 procssing took longer than 7000ms if the request 282 was sent towards the end of the timing of any work 283 being worked on 284 e.g.: BFL0: took 8438ms - longer than 7000ms 285 You should ignore this 286 287 devdetails DEVDETAILS Each device with a list of their static details 288 This lists all devices including those not 289 supported by the 'devs' command 290 e.g. DEVDETAILS=0,Name=ASC,ID=0,Driver=yuu,...| 291 292 restart (*) none Status is a single "RESTART" reply before cgminer 293 restarts 294 295 stats STATS Each device or pool that has 1 or more getworks 296 with a list of stats regarding getwork times 297 The values returned by stats may change in future 298 versions thus would not normally be displayed 299 Device drivers are also able to add stats to the 300 end of the details returned 301 302 estats[|old] STATS The same as stats, except it ignores blacklisted 303 devices, zombie devices and pools 304 If you specify the optional 'old' parameter, then 305 the output will include zombie devices that became 306 zombies less than 'old' seconds ago 307 A value of zero for 'old', which is the default, 308 means ignore all zombies 309 It will return an empty list of devices if all 310 devices are blacklisted or zombies 311 312 check|cmd CHECK Exists=Y/N, <- 'cmd' exists in this version 313 Access=Y/N| <- you have access to use 'cmd' 314 315 failover-only|true/false (*) 316 none This command has been deprecated, only returning a 317 deprecated message. 318 319 coin COIN Coin mining information: 320 Hash Method=sha256/scrypt, 321 Current Block Time=N.N, <- 0 means none 322 Current Block Hash=XXXX..., <- blank if none 323 LP=true/false, <- LP is in use on at least 1 pool 324 Network Difficulty=NN.NN| 325 326 debug|setting (*) 327 DEBUG Debug settings 328 The optional commands for 'setting' are the same 329 as the screen curses debug settings 330 You can only specify one setting 331 Only the first character is checked - case 332 insensitive: 333 Silent, Quiet, Verbose, Debug, RPCProto, 334 PerDevice, WorkTime, Normal 335 The output fields are (as above): 336 Silent=true/false, 337 Quiet=true/false, 338 Verbose=true/false, 339 Debug=true/false, 340 RPCProto=true/false, 341 PerDevice=true/false, 342 WorkTime=true/false| 343 344 setconfig|name,N (*) 345 none There is no reply section just the STATUS section 346 stating the results of setting 'name' to N 347 No values are supported any more and only a 348 deprecated message will be returned. 349 350 usbstats USBSTATS Stats of all LIBUSB mining devices except ztex 351 e.g. Name=MMQ,ID=0,Stat=SendWork,Count=99,...| 352 353 pgaset|N,opt[,val] (*) 354 none There is no reply section just the STATUS section 355 stating the results of setting PGA N with 356 opt[,val] 357 This is only available if PGA mining is enabled 358 359 If the PGA does not support any set options, it 360 will always return a WARN stating pgaset isn't 361 supported 362 363 If opt=help it will return an INFO status with a 364 help message about the options available 365 366 The current options are: 367 MMQ opt=clock val=160 to 230 (a multiple of 2) 368 CMR opt=clock val=100 to 220 369 370 zero|Which,true/false (*) 371 none There is no reply section just the STATUS section 372 stating that the zero, and optional summary, was 373 done 374 If Which='all', all normal cgminer and API 375 statistics will be zeroed other than the numbers 376 displayed by the usbstats and stats commands 377 If Which='bestshare', only the 'Best Share' values 378 are zeroed for each pool and the global 379 'Best Share' 380 The true/false option determines if a full summary 381 is shown on the cgminer display like is normally 382 displayed on exit. 383 384 hotplug|N (*) none There is no reply section just the STATUS section 385 stating that the hotplug setting succeeded 386 If the code is not compiled with hotplug in it, 387 the the warning reply will be 388 'Hotplug is not available' 389 If N=0 then hotplug will be disabled 390 If N>0 && <=9999, then hotplug will check for new 391 devices every N seconds 392 393 asc|N ASC The details of a single ASC number N in the same 394 format and details as for DEVS 395 This is only available if ASC mining is enabled 396 Use 'asccount' or 'config' first to see if there 397 are any 398 399 ascenable|N (*) 400 none There is no reply section just the STATUS section 401 stating the results of the enable request 402 You cannot enable a ASC if it's status is not WELL 403 This is only available if ASC mining is enabled 404 405 ascdisable|N (*) 406 none There is no reply section just the STATUS section 407 stating the results of the disable request 408 This is only available if ASC mining is enabled 409 410 ascidentify|N (*) 411 none There is no reply section just the STATUS section 412 stating the results of the identify request 413 This is only available if ASC mining is enabled 414 and currently only BFL ASICs support this command 415 On a BFL single it will flash the led on the front 416 of the device for appoximately 4s 417 All other non BFL ASIC devices will return a 418 warning status message stating that they dont 419 support it 420 421 asccount ASCS Count=N| <- the number of ASCs 422 Always returns 0 if ASC mining is disabled 423 424 ascset|N,opt[,val] (*) 425 none There is no reply section just the STATUS section 426 stating the results of setting ASC N with 427 opt[,val] 428 This is only available if ASC mining is enabled 429 430 If the ASC does not support any set options, it 431 will always return a WARN stating ascset isn't 432 supported 433 434 If opt=help it will return an INFO status with a 435 help message about the options available 436 437 The current options are: 438 AVA+BTB opt=freq val=256 to 1024 - chip frequency 439 BTB opt=millivolts val=1000 to 1400 - corevoltage 440 MBA opt=reset val=0 to chipcount - reset a chip 441 BMA opt=volt val=0-9 opt=clock val=0-15 442 MBA opt=freq val=0-chip:100-1400 - set chip freq 443 MBA opt=ledcount val=0-100 - chip count for led 444 MBA opt=ledlimit val=0-200 - led off below GHs 445 MBA opt=spidelay val=0-9999 - SPI per I/O delay 446 MBA opt=spireset i|s0-9999 - SPI regular reset 447 MBA opt=spisleep val=0-9999 - SPI reset sleep ms 448 449 lcd LCD An all-in-one short status summary of the miner 450 e.g. Elapsed,GHS av,GHS 5m,GHS 5s,Temp, 451 Last Share Difficulty,Last Share Time, 452 Best Share,Last Valid Work,Found Blocks, 453 Pool,User| 454 455 lockstats (*) none There is no reply section just the STATUS section 456 stating the results of the request 457 A warning reply means lock stats are not compiled 458 into cgminer 459 The API writes all the lock stats to stderr 460 461 When you enable, disable or restart a PGA or ASC, you will also get 462 Thread messages in the cgminer status window 463 464 The 'poolpriority' command can be used to reset the priority order of multiple 465 pools with a single command - 'switchpool' only sets a single pool to first 466 priority 467 Each pool should be listed by id number in order of preference (first = most 468 preferred) 469 Any pools not listed will be prioritised after the ones that are listed, in the 470 priority order they were originally 471 If the priority change affects the miner's preference for mining, it may switch 472 immediately 473 474 When you switch to a different pool to the current one (including by priority 475 change), you will get a 'Switching to URL' message in the cgminer status 476 windows 477 478 Obviously, the JSON format is simply just the names as given before the '=' 479 with the values after the '=' 480 481 If you enable cgminer debug (-D or --debug) or, when cgminer debug is off, 482 turn on debug with the API command 'debug|debug' you will also get messages 483 showing some details of the requests received and the replies 484 485 There are included 4 program examples for accessing the API: 486 487 api-example.php - a php script to access the API 488 usAge: php api-example.php command 489 by default it sends a 'summary' request to the miner at 127.0.0.1:4028 490 If you specify a command it will send that request instead 491 You must modify the line "$socket = getsock('127.0.0.1', 4028);" at the 492 beginning of "function request($cmd)" to change where it looks for cgminer 493 494 api-example.rb - a Ruby script to access the API. 495 usage: ruby api-example.rb command[:parameter] [HOST [PORT]] 496 This script prints the parsed cgminer API response 497 498 API.java/API.class 499 a java program to access the API (with source code) 500 usAge is: java API command address port 501 Any missing or blank parameters are replaced as if you entered: 502 java API summary 127.0.0.1 4028 503 504 api-example.c - a 'C' program to access the API (with source code) 505 usAge: api-example [command [ip/host [port]]] 506 again, as above, missing or blank parameters are replaced as if you entered: 507 api-example summary 127.0.0.1 4028 508 509 miner.php - an example web page to access the API 510 This includes buttons and inputs to attempt access to the privileged commands 511 See the end of this API-README for details of how to tune the display 512 and also to use the option to display a multi-rig summary 513 514 ---------- 515 516 Feature Changelog for external applications using the API: 517 518 --------- 519 520 API V3.7 (cgminer v4.9.3?) 521 522 Modified API commands: 523 'pools' - add 'Work Difficulty' 524 525 --------- 526 527 API V3.6 (cgminer v4.9.2) 528 529 Modified API commands: 530 'pools' - add 'Bad Work' 531 'setconfig' - expire, scantime and queue have all been deprecated and will 532 only return a deprecated message. 533 'failover-only' - deprecated, a deprecated message will be returned. 534 535 --------- 536 537 API V3.5 (cgminer v4.7.0) 538 539 - Made quit and restart return valid JSON as a STATUS mirroring the request. 540 - Made addpool return what pool number the added pool is. 541 542 --------- 543 544 API V3.4 (cgminer v4.3.?) 545 546 Added API commands: 547 'lcd' - An all-in-one short status summary of the miner 548 549 --------- 550 551 API V3.3 (cgminer v4.2.0) 552 553 Added API commands: 554 'edevs' - Only enabled devices, for 'devs' 555 'estats' - Only enabled devices, for 'stats' 556 557 --------- 558 559 API V3.2 (cgminer v4.1.0) 560 561 Fix for: 562 HEX32 data type in the API version v3.1 JSON - since cgminer v3.12.1 - 563 returns an incorrect formatted json data element for the API stats command 564 for HashFast hardware 565 566 --------- 567 568 API V3.1 (cgminer v3.12.1) 569 570 Multiple report request command with '+' e.g. summary+devs 571 572 --------- 573 574 API V3.0 (cgminer v3.11.0) 575 576 Allow unlimited size replies 577 578 --------- 579 580 API V2.0 (cgminer v3.8.0) 581 582 Removed all GPU related commands and information from the replies 583 584 --------- 585 586 API V1.32 (cgminer v3.6.5) 587 588 Modified API commands: 589 'devs' 'gpu' 'pga' and 'asc' - add 'Device Elapsed' 590 591 --------- 592 593 API V1.31 (cgminer v3.6.3) 594 595 Added API command: 596 'lockstats' - display cgminer dev lock stats if compiled in 597 598 Modified API command: 599 'summary' - add 'MHS %ds' (where %d is the log interval) 600 601 --------- 602 603 API V1.30 (cgminer v3.4.3) 604 605 Added API command: 606 'poolquota' - Set pool quota for load-balance strategy. 607 608 Modified API command: 609 'pools' - add 'Quota' 610 611 --------- 612 613 API V1.29 (cgminer v3.4.1) 614 615 Muticast identification added to the API 616 617 ---------- 618 619 API V1.28 (cgminer v3.3.4) 620 621 Modified API commands: 622 'devs', 'pga', 'asc', 'gpu' - add 'Device Hardware%' and 'Device Rejected%' 623 'pools' - add 'Pool Rejected%' and 'Pool Stale%' 624 'summary' - add 'Device Hardware%', 'Device Rejected%', 'Pool Rejected%', 625 'Pool Stale%' 626 627 ---------- 628 629 API V1.27 (cgminer v3.3.2) 630 631 Added API commands: 632 'ascset' - with: BTB opt=millivolts val=1000 to 1310 - core voltage 633 AVA+BTB opt=freq val=256 to 450 - chip frequency 634 635 ---------- 636 637 API V1.26 (cgminer v3.2.3) 638 639 Remove all CPU support (cgminer v3.0.0) 640 641 Added API commands: 642 'asc' 643 'ascenable' 644 'ascdisable' 645 'ascidentify|N' (only works for BFL ASICs so far) 646 'asccount' 647 648 Various additions to the debug 'stats' command 649 650 ---------- 651 652 API V1.25 653 654 Added API commands: 655 'hotplug' 656 657 Modified API commands: 658 'devs' 'gpu' and 'pga' - add 'Last Valid Work' 659 'devs' - list ASIC devices 660 'config' - add 'Hotplug', 'ASC Count' 661 'coin' - add 'Network Difficulty' 662 663 ---------- 664 665 API V1.24 (cgminer v2.11.0) 666 667 Added API commands: 668 'zero' 669 670 Modified API commands: 671 'pools' - add 'Best Share' 672 'devs' and 'pga' - add 'No Device' for PGAs if MMQ or BFL compiled 673 'stats' - add pool: 'Net Bytes Sent', 'Net Bytes Recv' 674 675 ---------- 676 677 API V1.23 (cgminer v2.10.2) 678 679 Added API commands: 680 'pgaset' - with: MMQ opt=clock val=160 to 230 (and a multiple of 2) 681 682 ---------- 683 684 API V1.22 (cgminer v2.10.1) 685 686 Enforced output limitation: 687 all extra records beyond the output limit of the API (~64k) are ignored 688 and chopped off at the record boundary before the limit is reached 689 however, JSON brackets will be correctly closed and the JSON id will be 690 set to 0 (instead of 1) if any data was truncated 691 692 Modified API commands: 693 'stats' - add 'Times Sent', 'Bytes Sent', 'Times Recv', 'Bytes Recv' 694 695 ---------- 696 697 API V1.21 (cgminer v2.10.0) 698 699 Added API commands: 700 'usbstats' 701 702 Modified API commands: 703 'summary' - add 'Best Share' 704 705 Modified output: 706 each MMQ shows up as 4 devices, each with it's own stats 707 708 ---------- 709 710 API V1.20 (cgminer v2.8.5) 711 712 Modified API commands: 713 'pools' - add 'Has Stratum', 'Stratum Active', 'Stratum URL' 714 715 ---------- 716 717 API V1.19 (cgminer v2.7.6) 718 719 Added API commands: 720 'debug' 721 'pgaidentify|N' (only works for BFL Singles so far) 722 'setconfig|name,N' 723 724 Modified API commands: 725 'devs' - add 'Diff1 Work', 'Difficulty Accepted', 'Difficulty Rejected', 726 'Last Share Difficulty' to all devices 727 'gpu|N' - add 'Diff1 Work', 'Difficulty Accepted', 728 'Difficulty Rejected', 'Last Share Difficulty' 729 'pga|N' - add 'Diff1 Work', 'Difficulty Accepted', 730 'Difficulty Rejected', 'Last Share Difficulty' 731 'notify' - add '*Dev Throttle' (for BFL Singles) 732 'pools' - add 'Proxy Type', 'Proxy', 'Difficulty Accepted', 733 'Difficulty Rejected', 'Difficulty Stale', 734 'Last Share Difficulty' 735 'config' - add 'Queue', 'Expiry' 736 'stats' - add 'Work Diff', 'Min Diff', 'Max Diff', 'Min Diff Count', 737 'Max Diff Count' to the pool stats 738 739 ---------- 740 741 API V1.18 (cgminer v2.7.4) 742 743 Modified API commands: 744 'stats' - add 'Work Had Roll Time', 'Work Can Roll', 'Work Had Expire', 745 'Work Roll Time' to the pool stats 746 'config' - include 'ScanTime' 747 748 ---------- 749 750 API V1.17 (cgminer v2.7.1) 751 752 Added API commands: 753 'coin' 754 755 Modified API commands: 756 'summary' - add 'Work Utility' 757 'pools' - add 'Diff1 Shares' 758 759 ---------- 760 761 API V1.16 (cgminer v2.6.5) 762 763 Added API commands: 764 'failover-only' 765 766 Modified API commands: 767 'config' - include failover-only state 768 769 ---------- 770 771 API V1.15 (cgminer v2.6.1) 772 773 Added API commands: 774 'poolpriority' 775 776 ---------- 777 778 API V1.14 (cgminer v2.5.0) 779 780 Modified API commands: 781 'stats' - more icarus timing stats added 782 'notify' - include new device comms error counter 783 784 The internal code for handling data was rewritten (~25% of the code) 785 Completely backward compatible 786 787 ---------- 788 789 API V1.13 (cgminer v2.4.4) 790 791 Added API commands: 792 'check' 793 794 Support was added to cgminer for API access groups with the --api-groups option 795 It's 100% backward compatible with previous --api-access commands 796 797 ---------- 798 799 API V1.12 (cgminer v2.4.3) 800 801 Modified API commands: 802 'stats' - more pool stats added 803 804 Support for the ModMinerQuad FPGA was added 805 806 ---------- 807 808 API V1.11 (cgminer v2.4.2) 809 810 Modified API commands: 811 'save' no longer requires a filename (use default if not specified) 812 813 'save' incorrectly returned status E (error) on success before. 814 It now correctly returns S (success) 815 816 ---------- 817 818 API V1.10 (cgminer v2.4.1) 819 820 Added API commands: 821 'stats' 822 823 N.B. the 'stats' command can change at any time so any specific content 824 present should not be relied upon. 825 The data content is mainly used for debugging purposes or hidden options 826 in cgminer and can change as development work requires 827 828 Modified API commands: 829 'pools' added "Last Share Time" 830 831 ---------- 832 833 API V1.9 (cgminer v2.4.0) 834 835 Added API commands: 836 'restart' 837 838 Modified API commands: 839 'notify' corrected invalid JSON 840 841 ---------- 842 843 API V1.8 (cgminer v2.3.5) 844 845 Added API commands: 846 'devdetails' 847 848 Support for the ZTex FPGA was added 849 850 ---------- 851 852 API V1.7 (cgminer v2.3.4) 853 854 Added API commands: 855 'removepool' 856 857 Modified API commands: 858 'pools' added "User" 859 860 From API version 1.7 onwards, reply strings in JSON and Text have the 861 necessary escaping as required to avoid ambiguity 862 For JSON the 2 characters '"' and '\' are escaped with a '\' before them 863 For Text the 4 characters '|' ',' '=' and '\' are escaped the same way 864 865 ---------- 866 867 API V1.6 (cgminer v2.3.2) 868 869 Added API commands: 870 'pga' 871 'pgaenable' 872 'pgadisable' 873 'pgacount' 874 875 Modified API commands: 876 'devs' now includes Icarus and Bitforce FPGA devices 877 'notify' added "*" to the front of the name of all numeric error fields 878 'config' correct "Log Interval" to use numeric (not text) type for JSON 879 880 Support for Icarus and Bitforce FPGAs was added 881 882 ---------- 883 884 API V1.5 was not released 885 886 ---------- 887 888 API V1.4 (Kano's interim release of cgminer v2.3.1) 889 890 Added API commands: 891 'notify' 892 893 Modified API commands: 894 'config' added "Device Code" and "OS" 895 896 Added "When" to the STATUS reply section of all commands 897 898 ---------- 899 900 API V1.3 (cgminer v2.3.1-2) 901 902 Added API commands: 903 'addpool' 904 905 Modified API commands: 906 'devs'/'gpu' added "Total MH" for each device 907 'summary' added "Total MH" 908 909 ---------- 910 911 API V1.2 (cgminer v2.3.0) 912 913 Added API commands: 914 'enablepool' 915 'disablepool' 916 'privileged' 917 918 Modified API commands: 919 'config' added "Log Interval" 920 921 Starting with API V1.2, any attempt to access a command that requires 922 privileged security, from an IP address that does not have privileged 923 security, will return an "Access denied" Error Status 924 925 ---------- 926 927 API V1.1 (cgminer v2.2.4) 928 929 There were no changes to the API commands in cgminer v2.2.4, 930 however support was added to cgminer for IP address restrictions 931 with the --api-allow option 932 933 ---------- 934 935 API V1.1 (cgminer v2.2.2) 936 937 Prior to V1.1, devs/gpu incorrectly reported GPU0 Intensity for all GPUs 938 939 Modified API commands: 940 'devs'/'gpu' added "Last Share Pool" and "Last Share Time" for each device 941 942 ---------- 943 944 API V1.0 (cgminer v2.2.0) 945 946 Remove default CPU support 947 948 Added API commands: 949 'config' 950 'gpucount' 951 'cpucount' 952 'switchpool' 953 'gpuintensity' 954 'gpumem' 955 'gpuengine' 956 'gpufan' 957 'gpuvddc' 958 'save' 959 960 ---------- 961 962 API V0.7 (cgminer v2.1.0) 963 964 Initial release of the API in the main cgminer git 965 966 Commands: 967 'version' 968 'devs' 969 'pools' 970 'summary' 971 'gpuenable' 972 'gpudisable' 973 'gpurestart' 974 'gpu' 975 'cpu' 976 'gpucount' 977 'cpucount' 978 'quit' 979 980 ---------------------------------------- 981 982 miner.php 983 ========= 984 985 miner.php is a PHP based interface to the cgminer RPC API 986 (referred to simply as the API below) 987 988 It can show rig details, summaries and input fields to allow you to change 989 cgminer 990 You can also create custom summary pages with it 991 992 It has two levels to the security: 993 1) cgminer can be configured to allow or disallow API access and access level 994 security for miner.php 995 2) miner.php can be configured to allow or disallow privileged cgminer 996 access, if cgminer is configured to allow privileged access for miner.php 997 998 --------- 999 1000 To use miner.php requires a web server with PHP 1001 1002 Basics: On xubuntu 11.04, to install apache2 and php, the commands are: 1003 sudo apt-get install apache2 1004 sudo apt-get install php5 1005 sudo /etc/init.d/apache2 reload 1006 1007 On Fedora 17: 1008 yum install httpd php 1009 systemctl restart httpd.service 1010 systemctl enable httpd.service --system 1011 1012 On windows there are a few options. 1013 Try one of these (apparently the first one is easiest - thanks jborkl) 1014 http://www.easyphp.org/ 1015 http://www.apachefriends.org/en/xampp.html 1016 http://www.wampserver.com/en/ 1017 1018 --------- 1019 1020 The basic cgminer option to enable the API is: 1021 1022 --api-listen 1023 1024 or in your cgminer.conf 1025 1026 "api-listen" : true, 1027 1028 (without the ',' on the end if it is the last item) 1029 1030 If the web server is running on the cgminer computer, the above 1031 is the only change required to give miner.php basic access to 1032 the cgminer API 1033 1034 - 1035 1036 If the web server runs on a different computer to cgminer, 1037 you will also need to tell cgminer to allow the web server 1038 to access cgminer's API and tell miner.php where cgminer is 1039 1040 Assuming a.b.c.d is the IP address of the web server, you 1041 would add the following to cgminer: 1042 1043 --api-listen --api-allow a.b.c.d 1044 1045 or in your cgminer.conf 1046 1047 "api-listen" : true, 1048 "api-allow" : "a.b.c.d", 1049 1050 to tell cgminer to give the web server read access to the API 1051 1052 You also need to tell miner.php where cgminer is. 1053 Assuming cgminer is at IP address e.f.g.h, then you would 1054 edit miner.php and change the line 1055 1056 $rigs = array('127.0.0.1:4028'); 1057 1058 to 1059 1060 $rigs = array('e.f.g.h:4028'); 1061 1062 See --api-network or --api-allow for more access details 1063 and how to give write access 1064 1065 You can however, also tell miner.php to find your cgminer rigs automatically 1066 on the local subnet 1067 1068 Add the following to each cgminer: 1069 1070 --api-mcast 1071 1072 or in your cgminer.conf 1073 1074 "api-mcast" : true, 1075 1076 And in miner.php set $mcast = true; 1077 1078 This will ignore the value of $rigs and overwrite it with the list of zero or 1079 more rigs found on the network in the timeout specified 1080 A rig will not reply if the API settings would mean it would also ignore an 1081 API request from the web server running miner.php 1082 1083 --------- 1084 1085 Once you have a web server with PHP running 1086 1087 copy your miner.php to the main web folder 1088 1089 On Xubuntu 11.04 1090 /var/www/ 1091 1092 On Fedora 17 1093 /var/www/html/ 1094 1095 On Windows 1096 see your windows Web/PHP documentation 1097 1098 Assuming the IP address of the web server is a.b.c.d 1099 Then in your web browser go to: 1100 1101 http://a.b.c.d/miner.php 1102 1103 Done :) 1104 1105 --------- 1106 1107 The rest of this documentation deals with the more complex 1108 functions of miner.php, using myminer.php, creaing custom 1109 summaries and displaying multiple cgminer rigs 1110 1111 --------- 1112 1113 If you create a file called myminer.php in the same web folder 1114 where you put miner.php, miner.php will load it when it runs 1115 1116 This is useful, to put any changes you need to make to miner.php 1117 instead of changing miner.php 1118 Thus if you update/get a new miner.php, you won't lose the changes 1119 you have made if you put all your changes in myminer.php 1120 (and don't change miner.php at all) 1121 1122 A simple example myminer.php that defines 2 rigs 1123 (that I will keep referring to further below) is: 1124 1125 <?php 1126 # 1127 $rigs = array('192.168.0.100:4028:A', '192.168.0.102:4028:B'); 1128 # 1129 ?> 1130 1131 Changes in myminer.php superscede what is in miner.php 1132 However, this is only valid for variables in miner.php before the 1133 2 lines where myminer.php is included by miner.php: 1134 1135 if (file_exists('myminer.php')) 1136 include_once('myminer.php'); 1137 1138 Every variable in miner.php above those 2 lines, can be changed by 1139 simply defining them in your myminer.php 1140 1141 So although miner.php originally contains the line 1142 1143 $rigs = array('127.0.0.1:4028'); 1144 1145 if you created the example myminer.php given above, it would actually 1146 change the value of $rigs that is used when miner.php is running 1147 i.e. you don't have to remove or comment out the $rigs line in miner.php 1148 It will be superceded by myminer.php 1149 1150 --------- 1151 1152 The example myminer.php above also shows how to define more that one rig 1153 to be shown my miner.php 1154 1155 Each rig string is 2 or 3 values seperated by colons ':' 1156 They are simply an IP address or host name, followed by the 1157 port number (usually 4028) and an optional Name string 1158 1159 miner.php displays rig buttons that will show the defails of a single 1160 rig when you click on it - the button shows either the rig number, 1161 or the 'Name' string if you provide it 1162 1163 PHP arrays contain each string seperated by a comma, but no comma after 1164 the last one 1165 1166 So an example for 3 rigs would be: 1167 1168 $rigs = array('192.168.0.100:4028:A', '192.168.0.102:4028:B', 1169 '192.168.0.110:4028:C'); 1170 1171 Of course each of the rigs listed would also have to have the API 1172 running and be set to allow the web server to access the API - as 1173 explained before 1174 1175 --------- 1176 1177 So basically, any variable explained below can be put in myminer.php 1178 if you wanted to set it to something different to it's default value 1179 and did not want to change miner.php itself every time you updated it 1180 1181 Below is each variable that can be changed and an explanation of each 1182 1183 --------- 1184 1185 Default: 1186 $dfmt = 'H:i:s j-M-Y \U\T\CP'; 1187 1188 Define the date format used to print full length dates 1189 If you get the string 'UTCP' on the end of your dates shown, that 1190 means you are using an older version of PHP and you can instead use: 1191 $dfmt = 'H:i:s j-M-Y \U\T\CO'; 1192 1193 The PHP documentation on the date format is here: 1194 http://us.php.net/manual/en/function.date.php 1195 1196 --------- 1197 1198 Default: 1199 $title = 'Mine'; 1200 1201 Web page title 1202 If you know PHP you can of course use code to define it e.g. 1203 $title = 'My Rig at: '.date($dfmt); 1204 1205 Which would set the web page title to something like: 1206 My Rig at: 10:34:00 22-Aug-2012 UTC+10:00 1207 1208 --------- 1209 1210 Default: 1211 $readonly = false; 1212 1213 Set $readonly to true to force miner.php to be readonly 1214 This means it won't allow you to change cgminer even if the cgminer API 1215 options allow it to 1216 1217 If you set $readonly to false then it will check cgminer 'privileged' 1218 and will show input fields and buttons on the single rig page 1219 allowing you to change devices, pools and even quit or restart 1220 cgminer 1221 1222 However, if the 'privileged' test fails, the code will set $readonly to 1223 true 1224 1225 --------- 1226 1227 Default: 1228 $userlist = null; 1229 1230 Define password checking and default access 1231 null means there is no password checking 1232 1233 $userlist is an array of 3 arrays e.g. 1234 $userlist = array('sys' => array('boss' => 'bpass'), 1235 'usr' => array('user' => 'upass', 'pleb' => 'ppass'), 1236 'def' => array('Pools')); 1237 1238 'sys' is an array of system users and passwords (full access) 1239 'usr' is an array of user level users and passwords (readonly access) 1240 'def' is an array of custompages that anyone not logged in can view 1241 1242 Any of the 3 can be null, meaning there are none of that item 1243 1244 All validated 'usr' users are given $readonly = true; access 1245 All validated 'sys' users are given the $readonly access you defined 1246 1247 If 'def' has one or more values, and allowcustompages is true, then 1248 anyone without a password can see the list of custompage buttons given 1249 in 'def' and will see the first one when they go to the web page, with 1250 a login button at the top right 1251 1252 From the login page, if you login with no username or password, it will 1253 show the first 'def' custompage (if there are any) 1254 1255 If you are logged in, it will show a logout button at the top right 1256 1257 --------- 1258 1259 Default: 1260 $notify = true; 1261 1262 Set $notify to false to NOT attempt to display the notify command 1263 table of data 1264 1265 Set $notify to true to attempt to display the notify command on 1266 the single rig page 1267 If your older version of cgminer returns an 'Invalid command' 1268 coz it doesn't have notify - it just shows the error status table 1269 1270 --------- 1271 1272 Default: 1273 $checklastshare = true; 1274 1275 Set $checklastshare to true to do the following checks: 1276 If a device's last share is 12x expected ago then display as an error 1277 If a device's last share is 8x expected ago then display as a warning 1278 If either of the above is true, also display the whole line highlighted 1279 This assumes shares are 1 difficulty shares 1280 1281 Set $checklastshare to false to not do the above checks 1282 1283 'expected' is calculated from the device MH/s value 1284 So for example, a device that hashes at 380MH/s should (on average) 1285 find a share every 11.3s 1286 If the last share was found more than 11.3 x 12 seconds (135.6s) ago, 1287 it is considered an error and highlighted 1288 If the last share was found more than 11.3 x 8 seconds (90.4s) ago, 1289 it is considered a warning and highlighted 1290 1291 The default highlighting is very subtle 1292 1293 --------- 1294 1295 Default: 1296 $poolinputs = false; 1297 1298 Set $poolinputs to true to show the input fields for adding a pool 1299 and changing the pool priorities on a single rig page 1300 However, if $readonly is true, it will not display them 1301 1302 --------- 1303 1304 Default: 1305 $rigport = 4028; 1306 1307 Default port to use if any $rigs entries don't specify the port number 1308 1309 --------- 1310 1311 Default: 1312 $rigs = array('127.0.0.1:4028'); 1313 1314 Set $rigs to an array of your cgminer rigs that are running 1315 format: 'IP' or 'Host' or 'IP:Port' or 'Host:Port' or 'Host:Port:Name' 1316 If you only have one rig, it will just show the detail of that rig 1317 If you have more than one rig it will show a summary of all the rigs 1318 with buttons to show the details of each rig - 1319 the button contents will be 'Name' rather than rig number, if you 1320 specify 'Name' 1321 If Port is missing or blank, it will try $rigport 1322 e.g. $rigs = array('127.0.0.1:4028','myrig.com:4028:Sugoi'); 1323 1324 --------- 1325 1326 Default: 1327 $rignames = false; 1328 1329 Set $rignames to false to not affect the display. 1330 Set $rignames to one of 'ip' or 'ipx' to alter the name displayed 1331 if the rig doesn't have a 'name' in $rigs 1332 Currently: 1333 'ip' means use the 4th byte of the rig IP address as an integer 1334 'ipx' means use the 4th byte of the rig IP address as 2 hex bytes 1335 1336 --------- 1337 1338 Default: 1339 $rigbuttons = true; 1340 1341 Set $rigbuttons to false to display a link rather than a button on 1342 the left of any summary table with rig buttons, in order to reduce 1343 the height of the table cells 1344 1345 --------- 1346 1347 Default: 1348 $mcast = false; 1349 1350 Set $mcast to true to look for your rigs and ignore $rigs 1351 1352 --------- 1353 1354 Default: 1355 $mcastexpect = 0; 1356 1357 The minimum number of rigs expected to be found when $mcast is true 1358 If fewer are found, an error will be included at the top of the page 1359 1360 --------- 1361 1362 Default: 1363 $mcastaddr = '224.0.0.75'; 1364 1365 API Multicast address all cgminers are listening on 1366 1367 --------- 1368 1369 Default: 1370 $mcastport = 4028; 1371 1372 API Multicast UDP port all cgminers are listening on 1373 1374 --------- 1375 1376 Default: 1377 $mcastcode = 'FTW'; 1378 1379 The code all cgminers expect in the Multicast message sent 1380 The message sent is "cgm-code-listport" 1381 Don't use the '-' character if you change it 1382 1383 --------- 1384 1385 Default: 1386 $mcastlistport = 4027; 1387 1388 UDP port number that is added to the broadcast message sent 1389 that specifies to the cgminers the port to reply on 1390 1391 --------- 1392 1393 Default: 1394 $mcasttimeout = 1.5; 1395 1396 Set $mcasttimeout to the number of seconds (floating point) 1397 to wait for replies to the Multicast message 1398 N.B. the accuracy of the timing used to wait for the replies is 1399 ~0.1s so there's no point making it more than one decimal place 1400 1401 --------- 1402 1403 Default: 1404 $mcastretries = 0; 1405 1406 Set $mcastretries to the number of times to retry the multicast 1407 1408 If $mcastexpect is 0, this is simply the number of extra times 1409 that it will send the multicast request 1410 N.B. cgminer doesn't listen for multicast requests for 1000ms after 1411 each one it hears 1412 1413 If $mcastexpect is > 0, it will stop looking for replies once it 1414 has found at least $mcastexpect rigs, but it only checks this rig 1415 limit each time it reaches the $mcasttimeout limit, thus it can find 1416 more than $mcastexpect rigs if more exist 1417 It will send the multicast message up to $mcastretries extra times or 1418 until it has found at least $mcastexpect rigs 1419 However, when using $mcastretries, it is possible for it to sometimes 1420 ignore some rigs on the network if $mcastexpect is less than the 1421 number of rigs on the network and some rigs are too slow to reply 1422 1423 --------- 1424 1425 Default: 1426 $allowgen = false; 1427 1428 Set $allowgen to true to allow customsummarypages to use 'gen' and 'bgen' 1429 false means ignore any 'gen' or 'bgen' options 1430 This is disabled by default due to the possible security risk of using it 1431 See the end of this document for an explanation 1432 1433 --------- 1434 1435 Default: 1436 $rigipsecurity = true; 1437 1438 Set $rigipsecurity to false to show the IP/Port of the rig 1439 in the socket error messages and also show the full socket message 1440 1441 --------- 1442 1443 Default: 1444 $rigtotals = true; 1445 $forcerigtotals = false; 1446 1447 Set $rigtotals to true to display totals on the single rig page 1448 'false' means no totals (and ignores $forcerigtotals) 1449 1450 If $rigtotals is true, all data is also right aligned 1451 With false, it's as before, left aligned 1452 1453 This option is just here to allow people to set it to false 1454 if they prefer the old non-total display when viewing a single rig 1455 1456 Also, if there is only one line shown in any section, then no 1457 total will be shown (to save screen space) 1458 You can force it to always show rig totals on the single rig page, 1459 even if there is only one line, by setting $forcerigtotals = true; 1460 1461 --------- 1462 1463 Default: 1464 $socksndtimeoutsec = 10; 1465 $sockrcvtimeoutsec = 40; 1466 1467 The numbers are integer seconds 1468 1469 The defaults should be OK for most cases 1470 However, the longer SND is, the longer you have to wait while 1471 php hangs if the target cgminer isn't runnning or listening 1472 1473 RCV should only ever be relevant if cgminer has hung but the 1474 API thread is still running, RCV would normally be >= SND 1475 1476 Feel free to increase SND if your network is very slow 1477 or decrease RCV if that happens often to you 1478 1479 Also, on some windows PHP, apparently the $usec is ignored 1480 (so usec can't be specified) 1481 1482 --------- 1483 1484 Default: 1485 $hidefields = array(); 1486 1487 List of fields NOT to be displayed 1488 You can use this to hide data you don't want to see or don't want 1489 shown on a public web page 1490 The list of sections are: 1491 SUMMARY, POOL, PGA, GPU, NOTIFY, CONFIG, DEVDETAILS, DEVS 1492 See the web page for the list of field names (the table headers) 1493 It is an array of 'SECTION.Field Name' => 1 1494 1495 This example would hide the slightly more sensitive pool information: 1496 Pool URL and pool username: 1497 $hidefields = array('POOL.URL' => 1, 'POOL.User' => 1); 1498 1499 If you just want to hide the pool username: 1500 $hidefields = array('POOL.User' => 1); 1501 1502 --------- 1503 1504 Default: 1505 $ignorerefresh = false; 1506 $changerefresh = true; 1507 $autorefresh = 0; 1508 1509 Auto-refresh of the page (in seconds) - integers only 1510 1511 $ignorerefresh = true/false always ignore refresh parameters 1512 $changerefresh = true/false show buttons to change the value 1513 $autorefresh = default value, 0 means dont auto-refresh 1514 1515 --------- 1516 1517 Default: 1518 $miner_font_family = 'verdana,arial,sans'; 1519 $miner_font_size = '13pt'; 1520 1521 Change these to set the font and font size used on the web page 1522 1523 --------- 1524 1525 Default: 1526 $add_css_names = array(); 1527 1528 List of CSS names to add to the CSS style object 1529 e.g. array('td.cool' => false); 1530 true/false to not include the default $miner_font 1531 The CSS name/value pairs must be defined in $colouroverride below 1532 1533 This allows you to create multiple complete CSS styles, optionally 1534 using a different font to the default used/specified for all other 1535 styles, and then when using the class name in a custom formatting 1536 function (fmt) in a customsummarypage, it can use this style 1537 1538 --------- 1539 1540 Default: 1541 $colouroverride = array(); 1542 1543 Use this to change the web page colour scheme 1544 1545 See $colourtable in miner.php for the list of possible names to change 1546 1547 Simply put in $colouroverride, just the colours you wish to change 1548 1549 e.g. to change the colour of the header font and background 1550 you could do the following: 1551 1552 $colouroverride = array( 1553 'td.h color' => 'green', 1554 'td.h background' => 'blue' 1555 ); 1556 1557 You can also add your own CSS styles to be used by a customsummarypage 1558 custom format function, if you specify the class name in $add_css_names 1559 and put the class styles in $colouroverride 1560 1561 --------- 1562 1563 Default: 1564 $placebuttons = 'top'; 1565 1566 Where to place the Refresh, Summary, Custom Pages, Quit, etc. buttons 1567 1568 Valid values are: 'top' 'bot' 'both' 1569 anything else means don't show them - case sensitive 1570 1571 --------- 1572 1573 Default: 1574 $allowcustompages = true; 1575 1576 Should we allow custom pages? 1577 (or just completely ignore them and don't display the buttons) 1578 1579 --------- 1580 1581 OK this part is more complex: Custom Summary Pages 1582 1583 A custom summary page in an array of 'section' => array('FieldA','FieldB'...) 1584 1585 The section defines what data you want in the summary table and the Fields 1586 define what data you want shown from that section 1587 1588 Standard sections are: 1589 SUMMARY, POOL, PGA, GPU, NOTIFY, CONFIG, DEVDETAILS, DEVS, EDEVS, STATS, 1590 ESTATS, COIN 1591 1592 Fields are the names as shown on the headers on the normal pages 1593 1594 There is a special field name '#' that will total to the number of rows 1595 displayed in the custom summary page 1596 In the actual row output it is a row counter per rig 1597 1598 Fields can be 'name=new name' to display 'name' with a different heading 1599 'new name' 1600 1601 There are also now joined sections: 1602 SUMMARY+POOL, SUMMARY+DEVS, SUMMARY+EDEVS, DEVS+STATS, EDEVS+ESTATS, 1603 POOL+STATS plus many more 1604 See the miner.php function joinsections() for the full list 1605 1606 These sections are an SQL join of the two sections and the fields in them 1607 are named section.field where section. is the section the field comes from 1608 See the example further down 1609 1610 Also note: 1611 - empty tables are not shown 1612 - empty columns (e.g. an unknown field) are not shown 1613 - missing field data shows as blank 1614 - the field name '*' matches all fields except in joined sections 1615 (useful for STATS and COIN) 1616 1617 There are 2 hard coded sections: 1618 DATE - displays a date table like at the start of 'Summary' 1619 RIGS - displays a rig table like at the start of 'Summary' 1620 1621 Each custom summary requires a second array, that can be empty, listing fields 1622 to be totaled for each section 1623 If there is no matching total data, no total will show 1624 1625 --------- 1626 1627 Looking at the Mobile example: 1628 1629 $mobilepage = array( 1630 'DATE' => null, 1631 'RIGS' => null, 1632 'SUMMARY' => array('Elapsed', 'MHS av', 'Found Blocks=Blks', 1633 Accepted', 'Rejected=Rej', 'Utility'), 1634 'DEVS+NOTIFY' => array('DEVS.Name=Name', 'DEVS.ID=ID', 'DEVS.Status=Status', 1635 'DEVS.Temperature=Temp', 'DEVS.MHS av=MHS av', 1636 'DEVS.Accepted=Accept', 'DEVS.Rejected=Rej', 1637 'DEVS.Utility=Utility', 'NOTIFY.Last Not Well=Not Well'), 1638 'POOL' => array('POOL', 'Status', 'Accepted', 'Rejected=Rej', 1639 'Last Share Time')); 1640 1641 $mobilesum = array( 1642 'SUMMARY' => array('MHS av', 'Found Blocks', 'Accepted', 'Rejected', 1643 'Utility'), 1644 'DEVS+NOTIFY' => array('DEVS.MHS av', 'DEVS.Accepted', 'DEVS.Rejected', 1645 'DEVS.Utility'), 1646 'POOL' => array('Accepted', 'Rejected')); 1647 1648 $customsummarypages = array('Mobile' => array($mobilepage, $mobilesum)); 1649 1650 This will show 5 tables (according to $mobilepage) 1651 Each table will have the chosen details for all the rigs specified in $rigs 1652 1653 DATE 1654 A single box with the web server's current date and time 1655 1656 RIGS 1657 A table of the rigs: description, time, versions etc 1658 1659 SUMMARY 1660 1661 This will use the API 'summary' command and show the selected fields: 1662 Elapsed, MHS av, Found Blocks, Accepted, Rejected and Utility 1663 However, 'Rejected=Rej' means that the header displayed for the 'Rejected' 1664 field will be 'Rej', instead of 'Rejected' (to save space) 1665 Same for 'Found Blocks=Blks' - to save space 1666 1667 DEVS+NOTIFY 1668 1669 This will list each of the devices on each rig and display the list of 1670 fields as shown 1671 It will also include the 'Last Not Well' field from the 'notify' command 1672 so you know when the device was last not well 1673 1674 You will notice that you need to rename each field e.g. 'DEVS.Name=Name' 1675 since each field name in the join between DEVS and NOTIFY is actually 1676 section.fieldname, not just fieldname 1677 1678 The join code automatically adds 2 fields to each GPU device: 'Name' and 'ID' 1679 They don't exist in the API 'devs' output but I can correctly calculate 1680 them from the GPU device data 1681 These two fields are used to join DEVS to NOTIFY i.e. find the NOTIFY 1682 record that has the same Name and ID as the DEVS record and join them 1683 1684 POOL 1685 1686 This will use the API 'pools' command and show the selected fields: 1687 POOL, Status, Accepted, Rejected, Last Share Time 1688 Again, I renamed the 'Rejected' field using 'Rejected=Rej', to save space 1689 1690 $mobilesum lists the sections and fields that should have a total 1691 You can't define them for 'DATE' or 'RIGS' since they are hard coded tables 1692 The example given: 1693 1694 SUMMARY 1695 Show a total at the bottom of the columns for: 1696 MHS av, Found Blocks, Accepted, Rejected, Utility 1697 1698 Firstly note that you use the original name i.e. for 'Rejected=Rej' 1699 you use 'Rejected', not 'Rej' and not 'Rejected=Rej' 1700 1701 Secondly note that it simply adds up the fields 1702 If you ask for a total of a string field you will get the numerical 1703 sum of the string data 1704 1705 DEVS+NOTIFY 1706 1707 Simply note in this join example that you must use the original field 1708 names which are section.fieldname, not just fieldname 1709 1710 POOL 1711 Show a total at the bottom of the columns for: 1712 Accepted and Rejected 1713 1714 Again remember to use the original field name 'Rejected' 1715 1716 --------- 1717 1718 With cgminer 2.10.2 and later, miner.php includes an extension to 1719 the custom pages that allows you to apply SQL style commands to 1720 the data: where, group, and having 1721 cgminer 3.4.2 and later also includes another option 'gen' 1722 cgminer 4.2.0 and later also includes another option 'fmt' 1723 cgminer 4.2.1 and later also includes another option 'bgen' 1724 1725 An example of an 'ext' section in a more complex custom summary page: 1726 1727 $poolsext = array( 1728 'POOL+STATS' => array( 1729 'where' => null, 1730 'group' => array('POOL.URL', 'POOL.Has Stratum', 1731 'POOL.Stratum Active', 'POOL.Has GBT'), 1732 'calc' => array('POOL.Difficulty Accepted' => 'sum', 1733 'POOL.Difficulty Rejected' => 'sum', 1734 'STATS.Times Sent' => 'sum', 1735 'STATS.Bytes Sent' => 'sum', 1736 'STATS.Times Recv' => 'sum', 1737 'STATS.Bytes Recv' => 'sum'), 1738 'gen' => array('AvShr', 'POOL.Difficulty Accepted/max(POOL.Accepted,1)), 1739 'having' => array(array('STATS.Bytes Recv', '>', 0)), 1740 'fmt' => 'myfmtfunc')); 1741 1742 function myfmtfunc($section, $name, $value, $when, $alldata, 1743 $warnclass, $errorclass, $hiclass, $loclass, $totclass); 1744 { 1745 $ret = ''; 1746 $class = ''; 1747 switch ($section.'.'.$name) 1748 { 1749 case 'GEN.AvShr': 1750 $ret = number_format((float)$value, 2); 1751 if ($value == 0) 1752 $class = $errorclass; 1753 break; 1754 // Nonsence example :) since total would show the sum of the averages 1755 case 'total.AvShr': 1756 $ret = $value; 1757 if ($value == 0) 1758 $class = $warnclass; 1759 break; 1760 } 1761 return array($ret, $class); 1762 } 1763 1764 This allows you to group records together from one or more rigs 1765 In the example, you'll get each Pool (with the same URL+Stratum+GBT settings) 1766 listed once for all rigs and a sum of each of the fields listed in 'calc' 1767 1768 1769 'where' and 'having' are an array of fields and restrictions to apply 1770 1771 In the above example, it will only display the rows where it contains the 1772 'STATS.Bytes Recv' field with a value greater than zero 1773 If the row doesn't have the field, it will always be included 1774 All restrictions must be true in order for the row to be included 1775 Any restiction that is invalid or unknown is true 1776 An empty array, or null, means there are no restrictions 1777 1778 A restriction is formatted as: array('Field', 'restriction', 'value') 1779 Field is the simple field name as normally displayed, or SECTION.Field 1780 if it is a joined section (as in this case 'POOL+STATS') 1781 The list of restrictions are: 1782 'set' - true if the row contains the 'Field' ('value' is not required or used) 1783 '=', '<', '<=', '>', '>' - a numerical comparison 1784 'eq', 'lt', 'le', 'gt', 'ge' - a case insensitive string comparison 1785 1786 You can have multiple restrictions on a 'Field' - but all must be true to 1787 include the row containing the 'Field' 1788 e.g. a number range between 0 and 10 would be: 1789 array('STATS.Bytes Recv', '>', 0), array('STATS.Bytes Recv', '<', 10) 1790 1791 The difference between 'where' and 'having' is that 'where' is applied to the 1792 data before grouping it and 'having' is applied to the data after grouping it 1793 - otherwise they work the same 1794 1795 1796 'group' lists the fields to group over and 'calc' lists the function to apply 1797 to other fields that are not part of 'group' 1798 1799 You can only see fields listed in 'group' and 'calc' 1800 1801 A 'calc' is formatted as: 'Field' => 'function' 1802 The current list of operations available for 'calc' are: 1803 'sum', 'avg', 'min', 'max', 'lo', 'hi', 'count', 'any' 1804 The first 4 are as expected - the numerical sum, average, minimum or maximum 1805 'lo' is the first string of the list, sorted ignoring case 1806 'hi' is the last string of the list, sorted ignoring case 1807 'count' is the number of rows in the section specified in the calc e.g. 1808 ('DEVS.Name' => 'count') would be the number of DEVS selected in the 'where' 1809 of course any valid 'DEVS.Xyz' would give the same 'count' value 1810 'any' is effectively random: the field value in the 1st row of the grouped data 1811 An unrecognised 'function' uses 'any' 1812 1813 1814 A 'fmt' allows you to specify a function to be called by miner.php to format 1815 data to be displayed in the output html 1816 If the function doesn't exist in miner.php or myminer.php, then it will be 1817 ignored 1818 If the function returns a $ret value (see the example 'myfmtfunc' above) then 1819 that will be displayed, however if $ret is empty, then the normal formatting 1820 code will process the data to be displayed 1821 Thus, if there is no formatting code in miner.php for the field value, then it 1822 will be displayed as it was received from the API 1823 i.e. this allows you to either supply some php code to format field values 1824 that are not formatted by miner.php, or you can also override the formatting 1825 done by miner.php itself for your chosen list of field data 1826 You can return an ' ' if you wish to force it to display as blank 1827 Use the example 'myfmtfunc' above as a template to write your own 1828 Note that your provided function will be called for all data being displayed, 1829 so you should use the 'case' layout as in the example to select the data fields 1830 you wish to format, but return '' for fields you don't wish to change the way 1831 they are formatted 1832 The 2nd return field is the name of a CSS class in $colourtable or created in 1833 your own $add_css_names and $colouroverride 1834 The value you return can stay in effect even if you return an empty $ret, if 1835 the default formatting function for the field doesn't set the $class variable 1836 The fields passed to your function by miner.php: 1837 $warnclass, $errorclass, $hiclass, $loclass, $totclass 1838 contain the default class names used for formatting 1839 1840 1841 A 'gen' or 'bgen' allows you to generate new fields from any php valid function 1842 of any of the other fields 1843 e.g. 'gen' => array('AvShr', 'POOL.Difficulty Accepted/max(POOL.Accepted,1)), 1844 will generate a new field called GEN.AvShr that is the function shown, which 1845 in this case is the average difficulty of each share submitted 1846 1847 The difference between 'bgen' and 'gen' is that 'bgen' is done before doing 1848 the 'group' and 'calc', however 'gen' is done after doing 'group' and 'calc' 1849 This means that 'group' and 'calc' can also use 'bgen' fields 1850 As before, 'gen' fields act on the results of the 'group' and 'calc' 1851 If there is no 'group' or 'calc' then they both will produce the same results 1852 Note that 'gen' fields are called 'GEN.field' and 'bgen' fields, 'BGEN.field' 1853 1854 THERE IS A SECURITY RISK WITH HOW GEN/BGEN WORKS 1855 It simply replaces all the variables with their values and then requests PHP 1856 to execute the formula - thus if a field value returned from a cgminer API 1857 request contained PHP code, it could be executed by your web server 1858 Of course cgminer doesn't do this, but if you do not control the cgminer that 1859 returns the data in the API calls, someone could modify cgminer to return a 1860 PHP string in a field you use in 'gen' or 'bgen' 1861 Thus use 'gen' and 'bgen' at your own risk 1862 If someone feels the urge to write a mathematical interpreter in PHP to get 1863 around this risk, feel free to write one and submit it to the API author for 1864 consideration