bfgminer/API-README

This README contains details about the cgminer RPC API


If you start cgminer with the "--api-listen" option, it will listen on a
simple TCP/IP socket for single string API requests from the same machine
running cgminer and reply with a string and then close the socket each time
If you add the "--api-network" option, it will accept API requests from any
network attached computer.

You can only access the comands that reply with data in this mode.
By default, you cannot access any privileged command that affects the miner -
you will receive an access denied status message see --api-allow below.

You can specify IP addresses/prefixes that are only allowed to access the API
with the "--api-allow" option e.g. --api-allow W:192.168.0.1,10.0.0/24
will allow 192.168.0.1 or any address matching 10.0.0.*, but nothing else
IP addresses are automatically padded with extra '.0's as needed
Without a /prefix is the same as specifying /32
0/0 means all IP addresses.
The 'W:' on the front gives that address/subnet privileged access to commands
that modify cgminer (thus all API commands)
Without it those commands return an access denied status.
See --api-groups below to define other groups like W:
Privileged access is checked in the order the IP addresses were supplied to
"--api-allow"
The first match determines the privilege level.
Using the "--api-allow" option overides the "--api-network" option if they
are both specified
With "--api-allow", 127.0.0.1 is not by default given access unless specified

More groups (like the privileged group W:) can be defined using the
--api-groups command
Valid groups are only the letters A-Z (except R & W are predefined) and are
not case sensitive
The R: group is the same as not privileged access
The W: group is (as stated) privileged access (thus all API commands)
To give an IP address/subnet access to a group you use the group letter
in front of the IP address instead of W: e.g. P:192.168.0/32
An IP address/subnet can only be a member of one group
A sample API group would be:
 --api-groups P:switchpool:enablepool:addpool:disablepool:removepool.poolpriority:*
This would create a group 'P' that can do all current pool commands and all
non-priviliged commands - the '*' means all non-priviledged commands
Without the '*' the group would only have access to the pool commands
Defining multiple groups example:
 --api-groups Q:quit:restart:*,S:save
This would define 2 groups:
 Q: that can 'quit' and 'restart' as well as all non-priviledged commands
 S: that can only 'save' and no other commands

The RPC API request can be either simple text or JSON.

If the request is JSON (starts with '{'), it will reply with a JSON formatted
response, otherwise it replies with text formatted as described further below.

The JSON request format required is '{"command":"CMD","parameter":"PARAM"}'
(though of course parameter is not required for all requests)
where "CMD" is from the "Request" column below and "PARAM" would be e.g.
the CPU/GPU number if required.

An example request in both formats to set GPU 0 fan to 80%:
  gpufan|0,80
  {"command":"gpufan","parameter":"0,80"}

The format of each reply (unless stated otherwise) is a STATUS section
followed by an optional detail section

From API version 1.7 onwards, reply strings in JSON and Text have the
necessary escaping as required to avoid ambiguity - they didn't before 1.7
For JSON the 2 characters '"' and '\' are escaped with a '\' before them
For Text the 4 characters '|' ',' '=' and '\' are escaped the same way

Only user entered information will contain characters that require being
escaped, such as Pool URL, User and Password or the Config save filename,
when they are returned in messages or as their values by the API

For API version 1.4 and later:

The STATUS section is:

 STATUS=X,When=NNN,Code=N,Msg=string,Description=string|

  STATUS=X Where X is one of:
   W - Warning
   I - Informational
   S - Success
   E - Error
   F - Fatal (code bug)

  When=NNN
   Standard long time of request in seconds

  Code=N
   Each unique reply has a unigue Code (See api.c - #define MSG_NNNNNN)

  Msg=string
   Message matching the Code value N

  Description=string
   This defaults to the cgminer version but is the value of --api-description
   if it was specified at runtime.

For API version 1.10 and later:

The list of requests - a (*) means it requires privileged access - and replies are:

 Request       Reply Section  Details
 -------       -------------  -------
 version       VERSION        CGMiner=cgminer, version
                              API=API| version

 config        CONFIG         Some miner configuration information:
                              GPU Count=N, <- the number of GPUs
                              PGA Count=N, <- the number of PGAs
                              CPU Count=N, <- the number of CPUs
                              Pool Count=N, <- the number of Pools
                              ADL=X, <- Y or N if ADL is compiled in the code
                              ADL in use=X, <- Y or N if any GPU has ADL
                              Strategy=Name, <- the current pool strategy
                              Log Interval=N, <- log interval (--log N)
                              Device Code=GPU ICA | <- spaced list of compiled devices

 summary       SUMMARY        The status summary of the miner
                              e.g. Elapsed=NNN,Found Blocks=N,Getworks=N,...|

 pools         POOLS          The status of each pool
                              e.g. Pool=0,URL=http://pool.com:6311,Status=Alive,...|

 devs          DEVS           Each available GPU, PGA and CPU with their details
                              e.g. GPU=0,Accepted=NN,MHS av=NNN,...,Intensity=D|
                              Last Share Time=NNN, <- standand long time in seconds
                               (or 0 if none) of last accepted share
                              Last Share Pool=N, <- pool number (or -1 if none)
                              Will not report PGAs if PGA mining is disabled
                              Will not report CPUs if CPU mining is disabled

 gpu|N         GPU            The details of a single GPU number N in the same
                              format and details as for DEVS

 pga|N         PGA            The details of a single PGA number N in the same
                              format and details as for DEVS
                              This is only available if PGA mining is enabled
                              Use 'pgacount' or 'config' first to see if there are any

 cpu|N         CPU            The details of a single CPU number N in the same
                              format and details as for DEVS
                              This is only available if CPU mining is enabled
                              Use 'cpucount' or 'config' first to see if there are any

 gpucount      GPUS           Count=N| <- the number of GPUs

 pgacount      PGAS           Count=N| <- the number of PGAs
                              Always returns 0 if PGA mining is disabled

 cpucount      CPUS           Count=N| <- the number of CPUs
                              Always returns 0 if CPU mining is disabled

 switchpool|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of switching pool N to the
                              highest priority (the pool is also enabled)
                              The Msg includes the pool URL

 enablepool|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of enabling pool N
                              The Msg includes the pool URL

 addpool|URL,USR,PASS (*)
               none           There is no reply section just the STATUS section
                              stating the results of attempting to add pool N
                              The Msg includes the pool URL
                              Use '\\' to get a '\' and '\,' to include a comma
                              inside URL, USR or PASS

 poolpriority|N,... (*)
               none           There is no reply section just the STATUS section
                              stating the results of changing pool priorities
                              See usage below

 disablepool|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of disabling pool N
                              The Msg includes the pool URL

 removepool|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of removing pool N
                              The Msg includes the pool URL
                              N.B. all details for the pool will be lost

 gpuenable|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of the enable request

 gpudisable|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of the disable request

 gpurestart|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of the restart request

 gpuintensity|N,I (*)
               none           There is no reply section just the STATUS section
                              stating the results of setting GPU N intensity to I

 gpumem|N,V (*)
               none           There is no reply section just the STATUS section
                              stating the results of setting GPU N memoryclock to V MHz

 gpuengine|N,V (*)
               none           There is no reply section just the STATUS section
                              stating the results of setting GPU N clock to V MHz

 gpufan|N,V (*)
               none           There is no reply section just the STATUS section
                              stating the results of setting GPU N fan speed to V%

 gpuvddc|N,V (*)
               none           There is no reply section just the STATUS section
                              stating the results of setting GPU N vddc to V

 save|filename (*)
               none           There is no reply section just the STATUS section
                              stating success or failure saving the cgminer config
                              to filename
                              The filename is optional and will use the cgminer
                              default if not specified

 quit (*)      none           There is no status section but just a single "BYE"
                              reply before cgminer quits

 notify        NOTIFY         The last status and history count of each devices problem
                              This lists all devices including those not supported
                              by the 'devs' command
                              e.g. NOTIFY=0,Name=GPU,ID=0,Last Well=1332432290,...|

 privileged (*)
               none           There is no reply section just the STATUS section
                              stating an error if you do not have privileged access
                              to the API and success if you do have privilege
                              The command doesn't change anything in cgminer

 pgaenable|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of the enable request
                              You cannot enable a PGA if it's status is not WELL
                              This is only available if PGA mining is enabled

 pgadisable|N (*)
               none           There is no reply section just the STATUS section
                              stating the results of the disable request
                              This is only available if PGA mining is enabled

 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'

When you enable, disable or restart a GPU or PGA, you will also get Thread messages
in the cgminer status window

The 'poolpriority' command can be used to reset the priority order of multiple
pools with a single command - 'switchpool' only sets a single pool to first priority
Each pool should be listed by id number in order of preference (first = most
preferred)
Any pools not listed will be prioritised after the ones that are listed, in the
priority order they were originally
If the priority change affects the miner's preference for mining, it may switch
immediately

When you switch to a different pool to the current one (including by priority
change), you will get a 'Switching to URL' message in the cgminer status
windows

Obviously, the JSON format is simply just the names as given before the '='
with the values after the '='

If you enable cgminer debug (-D or --debug) you will also get messages showing
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
 Read the top of the file (miner.php) for details of how to tune the display
 and also to use the option to display a multi-rig summary

----------

Feature Changelog for external applications using the API:


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'