API-README 62 KB

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