Braiins OS+ Integration for Home Assistant

This is a custom integration for Home Assistant that allows you to control and monitor your cryptocurrency miners running Braiins OS+. It connects directly to your miner's local API, providing advanced tuning controls and detailed telemetry.

Features

• Local Control: Connects directly to your miner via its local IP address. No cloud services are required.
• Detailed Monitoring: Provides sensor entities for key metrics with a rapid 5-second update interval.
  • Total hashrate (TH/s).
  • Real-time power consumption (W) and energy efficiency (J/TH).
  • Highest chip and board temperatures.
  • Per-hashboard hashrate, chip temperature, and board temperature.
  • Per-hashboard enabled state and per-pool enabled/alive/active state.
  • Monitor RPM and Target Speed (%) for every fan detected.
• Simple Controls: Provides button entities to perform key actions:
  • Pause and Resume mining operations.
  • Increment and Decrement the power target.
  • Start, Stop, and Restart BOSminer, plus reboot the device.
  • Fine-tune how much the increment/decrement buttons change your targets via dedicated configuration entities.
• Direct Braiins Diagnostics:
  • API heartbeat status (whether the last refresh succeeded).
  • Public API version, current miner errors, tuner state, efficiency profile diagnostics, pool diagnostics, and locate LED state.
• Tuner Management:
  • Set specific Power Targets (Watts) or Hashrate Targets (TH/s).
  • Dynamic slider limits: Sliders automatically adjust their min/max range based on your specific miner's hardware constraints.
• Robust Authentication: Automatically handles the renewal of authentication tokens to ensure the connection is always active.

Prerequisites

• A miner running a recent version of Braiins OS+.
• Home Assistant (Version 2023.11.0 or newer).
• HACS (Home Assistant Community Store) installed and running.

Installation

This integration is best installed via HACS.

HACS (Recommended Method)

1. Navigate to the HACS section in your Home Assistant.
2. Go to "Integrations", then click the three-dots menu in the top right and select "Custom repositories".
3. Paste the following URL into the "Repository" field:

   https://github.com/aleixps/Braiins-OS-HA
   

4. Select "Integration" as the category.
5. Click "Add".
6. The "Braiins OS+" integration will now be available in HACS. Find it and click "Install".
7. Restart Home Assistant after the installation is complete.

Manual Installation

1. Go to the latest release page of this repository.
2. Download the braiins_os_plus.zip file.
3. Unzip the file.
4. Copy the braiins_os_plus directory into your Home Assistant config/custom_components/ directory.
5. Restart Home Assistant.

Configuration

Once installed, you can add and configure the integration through the Home Assistant UI.

1. Go to Settings > Devices & Services.
2. Click the "+ Add Integration" button in the bottom right.
3. Search for "Braiins OS+".
4. In the configuration dialog, enter the following details:
   • Miner IP: The local IP address of your miner.
   • Username: The username for your miner's web interface.
   • Password: The password for your miner.
5. Click "Submit".

The integration will log in and create a new device with all associated entities.

Entities Created

Controls & Configuration

Entity ID	Description
number.power_target	Set specific power draw in Watts. Limits are dynamic per model.
number.hashrate_target	Set specific hashrate target in TH/s.
number.power_adjustment_step	Config: Set how many Watts buttons change (e.g., 100W, 250W).
number.hashrate_adjustment_step	Config: Set how many TH/s buttons change (e.g., 1.0, 5.0).
button.increment_power_target	Increases Power Target by the configured step.
button.decrement_power_target	Decreases Power Target by the configured step.
button.increment_hashrate_target	Increases Hashrate Target by the configured step.
button.decrement_hashrate_target	Decreases Hashrate Target by the configured step.
button.pause_miner	Pauses mining operations.
button.resume_miner	Resumes mining operations.
button.start_bosminer	Starts the BOSminer process.
button.stop_bosminer	Stops the BOSminer process.
button.restart_bosminer	Restarts the BOSminer process.
button.reboot_device	Reboots the miner device.
switch.device_locate_led_blinking	Turns the miner locate LED blinking state on or off.

Sensors (Updated every 5s)

Sensor	Description	Unit
Total Hashrate	Combined real-time hashrate of all boards.	TH/s
Miner Consumption	Real-time power draw from the wall.	W
Miner Efficiency	Real-time efficiency (reports 0.0 when paused).	J/TH
Chip Temperature	The highest chip temperature reported by cooling system.	°C
Board Temperature	Calculated highest surface temperature among all boards.	°C
Fan Speed	Actual RPM for each individual fan.	RPM
Fan Target Speed	The duty cycle percentage for each fan.	%
API Version	Braiins OS Public API version reported by the miner.	-
Miner Error Count	Number of current miner errors; raw error list is exposed as attributes.	count
Tuner State	Overall Braiins tuner state as a readable label such as stable or tuning.	-
Efficiency Profile Points	Number of efficiency profile points exposed by Braiins.	count
Efficiency Profile Min/Max Power Target	Lowest and highest power targets present in the efficiency profile.	W
Efficiency Profile Min/Max Hashrate	Lowest and highest hashrates present in the efficiency profile.	TH/s
Pool Groups	Number of configured pool groups.	count
Pool Count	Number of configured pools.	count
Pool Active	URL of the currently active pool.	-

Binary Sensors

Binary Sensor	Description
API Heartbeat	On when the last coordinator/API refresh succeeded; off when the integration cannot currently poll the miner.
Hashboard N Enabled	One binary sensor per hashboard, using the direct Braiins enabled flag for that board.
Pool N Enabled	One binary sensor per configured pool, showing whether Braiins marks that pool as enabled.
Pool N Alive	One binary sensor per configured pool, showing whether Braiins reports that pool as reachable/alive.
Pool N Active	One binary sensor per configured pool, showing whether Braiins currently uses that pool.

Notes:

• Per-hashboard means the integration creates one entity for each hashboard reported by the miner.
• Per-pool means the integration creates one set of pool state entities for each pool configured in Braiins.

Per-hashboard sensors for hashrate and temperature are also created automatically, alongside hashboard enabled binary sensors.

Creating an Energy Sensor (kWh)

To track total energy consumption for the Home Assistant Energy Dashboard:

1. Go to Settings > Devices & Services > Helpers.
2. Create a "Riemann sum integral sensor".
3. Input sensor: sensor.miner_consumption.
4. Metric prefix: k (kilo).
5. Unit of time: Hours.
6. Use the resulting entity in your Energy Dashboard.

AI Assistance

This integration was developed with the assistance of Artificial Intelligence tools.

Contributing

Contributions and bug reports are welcome! Check the issues page to get involved.

License

This project is licensed under the MIT License. See the LICENSE file for details.