From b7d8539b7a0360a7a310324704f8854f38b537be Mon Sep 17 00:00:00 2001 From: UpstreamData Date: Mon, 29 Nov 2021 15:28:23 -0700 Subject: [PATCH] added README.md --- README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..8c1e09af --- /dev/null +++ b/README.md @@ -0,0 +1,130 @@ +# minerInterface +*A set of modules for interfacing with many common types of ASIC bitcoin miners, using both their API and SSH.* +## Usage +To use this repo, first download it, create a virtual environment, enter the virtual environment, and install relevant packages by navigating to this directory and running ```pip install -r requirements.txt``` on Windows or ```pip3 install -r requirements.txt``` on Mac or UNIX if the first command fails. + +### CFG Util +*CFG Util is a GUI for interfacing with the miners easily, it is mostly self-explanatory.* + +To use CFG Util you have 2 options - +1. Run it directly with the file ```config_tool.py``` or import it with ```from cfg_util import main```, then run the ```main()``` function in an asyncio event loop like - + +```python +from cfg_util import main + +if __name__ == '__main__': + main() +``` +2. Make a build of the CFG Util for your system using cx_freeze and ```make_cfg_tool_exe.py``` + 1. Open either Command Prompt on Windows of Terminal on Mac or UNIX. + 2. Navigate to this directory, and run ```make_cfg_tool_exe.py build``` on Windows or ```python3 make_cfg_tool_exe.py``` on Mac or UNIX. + +### Interfacing with miners programmatically + +To write your own custom programs with this repo, you have many options. + +It is recommended that you explore the files in this repo to familiarize yourself with them, try starting with the miners module and going from there. + +A basic script to find all miners on the network and get the hashrate from them looks like this - + +```python +import asyncio +from network import MinerNetwork +from cfg_util.func import safe_parse_api_data + +async def get_hashrate(): + # Miner Network class allows for easy scanning of a network + # Give it any IP on a network and it will find the whole subnet + # It can also be passed a subnet mask: + # miner_network = MinerNetwork('192.168.1.55', mask=23) + miner_network = MinerNetwork('192.168.1.1') + # Miner Network scan function returns Miner classes for all miners found + miners = await miner_network.scan_network_for_miners() + # Each miner will return with its own set of functions, and an API class instance + tasks = [miner.api.summary() for miner in miners] + # Gather all tasks asynchronously and run them + data = await asyncio.gather(*tasks) + parse_tasks = [] + for item in data: + # safe_parse_api_data parses the data from a miner API + # It will raise an APIError (from API import APIError) if there is a problem + parse_tasks.append(safe_parse_api_data(item, 'SUMMARY', 0, 'MHS 5s')) + # Gather all tasks asynchronously and run them + data = await asyncio.gather(*parse_tasks) + # Print a list of all the hashrates + print(data) + +if __name__ == '__main__': + asyncio.new_event_loop().run_until_complete(get_hashrate()) +``` +
+You can also create your own miner without scanning if you know the IP: + +```python +import asyncio +import ipaddress +from miners.miner_factory import MinerFactory +from cfg_util.func import safe_parse_api_data + +async def get_miner_hashrate(ip: str): + # Instantiate a Miner Factory to generate miners from their IP + miner_factory = MinerFactory() + # Make the string IP into an IP address + miner_ip = ipaddress.ip_address(ip) + # Wait for the factory to return the miner + miner = await miner_factory.get_miner(miner_ip) + # Get the API data + summary = await miner.api.summary() + # safe_parse_api_data parses the data from a miner API + # It will raise an APIError (from API import APIError) if there is a problem + data = await safe_parse_api_data(summary, 'SUMMARY', 0, 'MHS 5s') + print(data) + +if __name__ == '__main__': + asyncio.new_event_loop().run_until_complete(get_miner_hashrate(str("192.168.1.69"))) +``` + +
+Or generate a miner directly without the factory: + +```python +import asyncio +from miners.bosminer import BOSminer +from cfg_util.func import safe_parse_api_data + +async def get_miner_hashrate(ip: str): + # Create a BOSminer miner object + miner = BOSminer(ip) + # Get the API data + summary = await miner.api.summary() + # safe_parse_api_data parses the data from a miner API + # It will raise an APIError (from API import APIError) if there is a problem + data = await safe_parse_api_data(summary, 'SUMMARY', 0, 'MHS 5s') + print(data) + +if __name__ == '__main__': + asyncio.new_event_loop().run_until_complete(get_miner_hashrate(str("192.168.1.69"))) +``` + +
+Or finally, just get the API directly: + +```python +import asyncio +from API.bosminer import BOSMinerAPI +from cfg_util.func import safe_parse_api_data + +async def get_miner_hashrate(ip: str): + # Create a BOSminerAPI object + # Port can be declared manually, if not it defaults to 4028 + api = BOSMinerAPI(ip, port=4028) + # Get the API data + summary = await api.summary() + # safe_parse_api_data parses the data from a miner API + # It will raise an APIError (from API import APIError) if there is a problem + data = await safe_parse_api_data(summary, 'SUMMARY', 0, 'MHS 5s') + print(data) + +if __name__ == '__main__': + asyncio.new_event_loop().run_until_complete(get_miner_hashrate(str("192.168.1.69"))) +```