This repository has been archived by the owner on May 1, 2021. It is now read-only.
forked from ckolivas/cgminer
-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathAPI-README
1431 lines (1035 loc) · 48.3 KB
/
API-README
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
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 ASC/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
ASC Count=N, <- the number of ASCs
PGA Count=N, <- the number of PGAs
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
ScanTime=N, <- --scan-time setting
Queue=N, <- --queue setting
Expiry=N| <- --expiry 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 ASC 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)
Last Valid Work=NNN, <- standand long time in seconds
of last work returned that wasn't an HW:
Will not report PGAs if PGA mining is disabled
Will not report ASCs if ASC 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
gpucount GPUS Count=N| <- the number of GPUs
pgacount PGAS Count=N| <- the number of PGAs
Always returns 0 if PGA 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
Network Difficulty=NN.NN|
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,
WorkTime, 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,
WorkTime=true/false|
setconfig|name,N (*)
none There is no reply section just the STATUS section
stating the results of setting 'name' to N
The valid values for name are currently:
queue, scantime, expiry
N is an integer in the range 0 to 9999
usbstats USBSTATS Stats of all LIBUSB mining devices except ztex
e.g. Name=MMQ,ID=0,Stat=SendWork,Count=99,...|
pgaset|N,opt[,val] (*)
none There is no reply section just the STATUS section
stating the results of setting PGA N with opt[,val]
This is only available if PGA mining is enabled
If the PGA does not support any set options, it will
always return a WARN stating pgaset isn't supported
If opt=help it will return an INFO status with a
help message about the options available
The current options are:
MMQ opt=clock val=160 to 230 (and a multiple of 2)
zero|Which,true/false (*)
none There is no reply section just the STATUS section
stating that the zero, and optional summary, was done
If Which='all', all normal cgminer and API statistics
will be zeroed other than the numbers displayed by the
usbstats and stats commands
If Which='bestshare', only the 'Best Share' values
are zeroed for each pool and the global 'Best Share'
The true/false option determines if a full summary is
shown on the cgminer display like is normally displayed
on exit.
hotplug|N (*) none There is no reply section just the STATUS section
stating that the hotplug setting succeeded
If the code is not compiled with hotplug in it, the
the warning reply will be 'Hotplug is not available'
If N=0 then hotplug will be disabled
If N>0 && <=9999, then hotplug will check for new
devices every N seconds
asc|N ASC The details of a single ASC number N in the same
format and details as for DEVS
This is only available if ASC mining is enabled
Use 'asccount' or 'config' first to see if there
are any
ascenable|N (*)
none There is no reply section just the STATUS section
stating the results of the enable request
You cannot enable a ASC if it's status is not WELL
This is only available if ASC mining is enabled
ascdisable|N (*)
none There is no reply section just the STATUS section
stating the results of the disable request
This is only available if ASC mining is enabled
ascidentify|N (*)
none There is no reply section just the STATUS section
stating the results of the identify request
This is only available if ASC mining is enabled
and currently only BFL ASICs 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 ASIC devices will return a
warning status message stating that they dont
support it
asccount ASCS Count=N| <- the number of ASCs
Always returns 0 if ASC mining is disabled
When you enable, disable or restart a GPU, PGA or ASC, 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.26 (cgminer v3.2.3)
Remove all CPU support (cgminer v3.0.0)
Added API commands:
'asc'
'ascenable'
'ascdisable'
'ascidentify|N' (only works for BFL ASICs so far)
'asccount'
Various additions to the debug 'stats' command
----------
API V1.25
Added API commands:
'hotplug'
Modified API commands:
'devs' 'gpu' and 'pga' - add 'Last Valid Work'
'devs' - list ASIC devices
'config' - add 'Hotplug', 'ASC Count'
'coin' - add 'Network Difficulty'
----------
API V1.24 (cgminer v2.11.0)
Added API commands:
'zero'
Modified API commands:
'pools' - add 'Best Share'
'devs' and 'pga' - add 'No Device' for PGAs if MMQ or BFL compiled
'stats' - add pool: 'Net Bytes Sent', 'Net Bytes Recv'
----------
API V1.23 (cgminer v2.10.2)
Added API commands:
'pgaset' - with: MMQ opt=clock val=160 to 230 (and a multiple of 2)
----------
API V1.22 (cgminer v2.10.1)
Enforced output limitation:
all extra records beyond the output limit of the API (~64k) are ignored
and chopped off at the record boundary before the limit is reached
however, JSON brackets will be correctly closed and the JSON id will be
set to 0 (instead of 1) if any data was truncated
Modified API commands:
'stats' - add 'Times Sent', 'Bytes Sent', 'Times Recv', 'Bytes Recv'
----------
API V1.21 (cgminer v2.10.0)
Added API commands:
'usbstats'
Modified API commands:
'summary' - add 'Best Share'
Modifed output:
each MMQ shows up as 4 devices, each with it's own stats
----------
API V1.20 (cgminer v2.8.5)
Modified API commands:
'pools' - add 'Has Stratum', 'Stratum Active', 'Stratum URL'
----------
API V1.19 (cgminer v2.7.6)
Added API commands:
'debug'
'pgaidentify|N' (only works for BFL Singles so far)
'setconfig|name,N'
Modified API commands:
'devs' - add 'Diff1 Work', 'Difficulty Accepted', 'Difficulty Rejected',
'Last Share Difficulty' to all devices
'gpu|N' - add 'Diff1 Work', 'Difficulty Accepted',
'Difficulty Rejected', 'Last Share Difficulty'
'pga|N' - add 'Diff1 Work', 'Difficulty Accepted',
'Difficulty Rejected', 'Last Share Difficulty'
'notify' - add '*Dev Throttle' (for BFL Singles)
'pools' - add 'Proxy Type', 'Proxy', 'Difficulty Accepted', 'Difficulty Rejected',
'Difficulty Stale', 'Last Share Difficulty'
'config' - add 'Queue', 'Expiry'
'stats' - add 'Work Diff', 'Min Diff', 'Max Diff', 'Min Diff Count',
'Max Diff Count' to the pool stats
----------
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 (apparently the first one is easiest - thanks jborkl)
http://www.easyphp.org/
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
---------