NerdQAxe+ Miner - Home Assistant HACS Integration

HACS integration to monitor and control your NerdQAxe+ Bitcoin Miner in Home Assistant.

💰 Support the Project

If this integration is useful to you, you can support its development with a Bitcoin donation:

🪙 Bitcoin Address: bc1qhe4ge22x0anuyeg0fmts6rdmz3t735dnqwt3p7

Your contributions help me continue improving this project and adding new features. Thank you! 🙏

Description

This custom integration allows you to integrate your NerdQAxe+ miner into Home Assistant. It automatically creates sensors to monitor performance, temperature, power consumption, and more.

Integration type: Custom Component HACS (not a Docker addon)

Project Architecture

NerdQAxe+ REST API

The NerdQAxe+ firmware already exposes a complete REST API (no firmware modifications needed):

Available endpoints:

GET /api/system/info - Complete system information
GET /api/system/asic - ASIC information
GET /api/swarm/info - Swarm information
PATCH /api/system - Modify configuration
POST /api/system/restart - Restart the miner

Data returned by /api/system/info:

{
  "hashRate": 1200.5,
  "hashRate_1m": 1185.2,
  "hashRate_1h": 1150.8,
  "temp": 65.3,
  "vrTemp": 58.7,
  "power": 15.2,
  "voltage": 12.1,
  "current": 1.25,
  "fanspeed": 75,
  "fanrpm": 4500,
  "sharesAccepted": 1234,
  "sharesRejected": 5,
  "coreVoltage": 1150,
  "coreVoltageActual": 1138,
  "stratum": {
    "poolMode": 0,
    "pools": [
      { "connected": true, "poolDifficulty": 10000 }
    ]
  },
  "deviceModel": "NerdQAxePlus",
  "hostname": "nerdqaxe-123",
  "version": "2.0.3"
}

Integration Structure

custom_components/nerdqaxe/
├── __init__.py          # Initialization and coordinator
├── manifest.json        # Integration metadata
├── const.py             # Constants
├── config_flow.py       # UI configuration
├── sensor.py            # Sensors (hashrate, temp, power, etc.)
├── binary_sensor.py     # Binary sensors (stratum connected)
├── button.py            # Restart button
├── number.py            # Number controls (frequency, voltage)
└── update.py            # Firmware update entity

Created Sensors

The integration automatically creates the following sensors:

Hashrate

sensor.nerdqaxe_hashrate - Current hashrate (GH/s)
sensor.nerdqaxe_hashrate_1m - 1-minute average hashrate (GH/s)
sensor.nerdqaxe_hashrate_10m - 10-minute average hashrate (GH/s)
sensor.nerdqaxe_hashrate_1h - 1-hour average hashrate (GH/s)
sensor.nerdqaxe_hashrate_1d - 1-day average hashrate (GH/s)

Temperature

sensor.nerdqaxe_temperature - Chip temperature (°C)
sensor.nerdqaxe_vr_temperature - Voltage regulator temperature (°C)
sensor.nerdqaxe_asic_1_temperature, sensor.nerdqaxe_asic_2_temperature, … - Per-ASIC temperature on multi-ASIC boards such as the NerdQX (°C, one per chip; only created when the board actually reports them)

Power

sensor.nerdqaxe_power - Power consumption (W)
sensor.nerdqaxe_voltage - Voltage (V)
sensor.nerdqaxe_current - Current (A)
sensor.nerdqaxe_core_voltage - Commanded core voltage (mV)
sensor.nerdqaxe_core_voltage_actual - Measured core voltage (mV)

Cooling

sensor.nerdqaxe_fan_speed - Fan speed (%)
sensor.nerdqaxe_fan_rpm - Fan RPM

Mining

sensor.nerdqaxe_shares_accepted - Accepted shares
sensor.nerdqaxe_shares_rejected - Rejected shares
sensor.nerdqaxe_best_difficulty - Best difficulty found
sensor.nerdqaxe_best_session_difficulty - Best session difficulty
sensor.nerdqaxe_found_blocks - Blocks found (current session)
sensor.nerdqaxe_total_found_blocks - Total blocks found
binary_sensor.nerdqaxe_stratum_connected - Pool connection status

Information

sensor.nerdqaxe_device_model - Device model
sensor.nerdqaxe_hostname - Miner hostname
sensor.nerdqaxe_wifi_rssi - WiFi signal strength (dBm)
sensor.nerdqaxe_frequency - ASIC frequency (MHz)
sensor.nerdqaxe_version - Firmware version

Control and Updates

button.nerdqaxe_restart - Button to restart the miner
number.nerdqaxe_asic_frequency - ASIC frequency control (1-1000 MHz)
number.nerdqaxe_core_voltage - Core voltage control (1000-1350 mV)
update.nerdqaxe_firmware_update - Firmware update entity (automatically checks for new versions on GitHub)

Installation

Method 1: Via HACS (recommended)

Open HACS in Home Assistant
Go to "Integrations"
Click the 3 dots in the top right → "Custom repositories"
Add URL: https://github.com/foXaCe/homeassistant-nerdqaxe-addon
Category: "Integration"
Click "Add"
Search for "NerdQAxe+" and install
Restart Home Assistant

Method 2: Manual Installation

Download the custom_components/nerdqaxe folder
Copy to <config>/custom_components/nerdqaxe
Restart Home Assistant

Configuration

Automatic discovery (DHCP)

When a NerdQAxe+ miner (any host whose name starts with nerd) requests a DHCP lease, Home Assistant automatically detects it and shows it under Settings → Devices & Services as a discovered device — just click Configure. An already-configured miner has its IP refreshed automatically when it changes. If your miner isn't discovered (e.g. Home Assistant cannot see DHCP traffic on your network), add it manually below.

Via User Interface

Go to Settings → Devices & Services
Click + Add Integration
Search for "NerdQAxe+"
Enter your miner's IP address (e.g., 192.168.1.100)
The integration will connect and automatically create all sensors

Options

After installation, you can configure:

Scan interval: Update interval in seconds (5-300, default: 30)

To modify options:

Go to Settings → Devices & Services
Find "NerdQAxe+ Miner"
Click Options

Removal

To remove the integration:

Go to Settings → Devices & Services
Click on the NerdQAxe+ Miner integration
Click the 3 dots next to the entry → Delete
All devices, entities and history for this miner are removed automatically

To also remove the files (if installed via HACS):

Open HACS → Integrations
Find NerdQAxe+ Miner, click the 3 dots → Remove
Restart Home Assistant

Usage

Example Lovelace Card

type: entities
title: NerdQAxe+ Miner
entities:
  - entity: sensor.nerdqaxe_hashrate
    name: Hashrate
  - entity: sensor.nerdqaxe_hashrate_1h
    name: Hashrate 1h
  - entity: sensor.nerdqaxe_temperature
    name: Temperature
  - entity: sensor.nerdqaxe_power
    name: Power
  - entity: sensor.nerdqaxe_shares_accepted
    name: Accepted Shares
  - entity: binary_sensor.nerdqaxe_stratum_connected
    name: Pool Connected

Card with Graph

type: vertical-stack
cards:
  - type: entities
    title: NerdQAxe+ Miner
    entities:
      - entity: sensor.nerdqaxe_hashrate_1h
        name: Hashrate 1h
      - entity: sensor.nerdqaxe_temperature
      - entity: sensor.nerdqaxe_power
      - entity: binary_sensor.nerdqaxe_stratum_connected

  - type: history-graph
    title: Hashrate
    hours_to_show: 24
    entities:
      - entity: sensor.nerdqaxe_hashrate_1h

  - type: history-graph
    title: Temperature
    hours_to_show: 24
    entities:
      - entity: sensor.nerdqaxe_temperature

Automation Example - High Temperature Alert

automation:
  - alias: "High Miner Temperature Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.nerdqaxe_temperature
        above: 80
    action:
      - service: notify.mobile_app
        data:
          message: "⚠️ High miner temperature: {{ states('sensor.nerdqaxe_temperature') }}°C"
          title: "NerdQAxe+ Alert"

Automation Example - Pool Disconnected

automation:
  - alias: "Pool Disconnected Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.nerdqaxe_stratum_connected
        to: "off"
        for: "00:05:00"
    action:
      - service: notify.mobile_app
        data:
          message: "⚠️ NerdQAxe+ miner disconnected from pool for 5 minutes"

Automation Example - Low Hashrate

automation:
  - alias: "Low Hashrate Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.nerdqaxe_hashrate_1h
        below: 1000
        for: "00:10:00"
    action:
      - service: notify.mobile_app
        data:
          message: "⚠️ Low hashrate: {{ states('sensor.nerdqaxe_hashrate_1h') }} GH/s"

Miner Restart

The restart button is available in the interface:

type: button
entity: button.nerdqaxe_restart
name: Restart Miner
icon: mdi:restart

Or in an automation:

automation:
  - alias: "Auto Restart if Pool Disconnected"
    trigger:
      - platform: state
        entity_id: binary_sensor.nerdqaxe_stratum_connected
        to: "off"
        for: "00:15:00"
    action:
      - service: button.press
        target:
          entity_id: button.nerdqaxe_restart
      - service: notify.mobile_app
        data:
          message: "🔄 Restarting miner due to prolonged pool disconnection"

Frequency and Voltage Control

Control your miner's performance by adjusting frequency and core voltage:

In Lovelace:

type: entities
title: Miner Performance Control
entities:
  - entity: number.nerdqaxe_asic_frequency
    name: ASIC Frequency
  - entity: number.nerdqaxe_core_voltage
    name: Core Voltage
  - entity: sensor.nerdqaxe_power
    name: Current Power
  - entity: sensor.nerdqaxe_temperature
    name: Temperature

Via Automation:

automation:
  - alias: "Reduce Power on High Temperature"
    trigger:
      - platform: numeric_state
        entity_id: sensor.nerdqaxe_temperature
        above: 75
    action:
      - service: number.set_value
        target:
          entity_id: number.nerdqaxe_asic_frequency
        data:
          value: 450
      - service: notify.mobile_app
        data:
          message: "⚠️ Temperature high, reducing frequency to 450 MHz"

Eco / Night Mode (low power)

The firmware has no true software "off" — the shutdown field is read-only, and cutting power with an external relay also cuts the Wi-Fi, so Home Assistant loses control and can't turn the miner back on. You can, however, cut most of the draw by underclocking with the ASIC Frequency and Core Voltage entities.

Measured on a NerdAxe Gamma:

Mode	Frequency / Voltage	Power
Full	500 MHz / 1120 mV	~18.5 W
Eco	100 MHz / 1000 mV	~6.3 W

That's roughly −66 %. Around 6 W is the floor (the ESP32, VR and fan keep running), so software can't reach 0 W — for that you need to physically cut power.

Example: drop to eco when there's no solar, restore when it comes back (replace sensor.solar_power with your PV sensor):

automation:
  - alias: "NerdQAxe eco when no solar"
    trigger:
      - platform: numeric_state
        entity_id: sensor.solar_power
        below: 50
    action:
      - action: number.set_value
        target:
          entity_id: number.nerdqaxe_asic_frequency
        data:
          value: 100
      - action: number.set_value
        target:
          entity_id: number.nerdqaxe_core_voltage
        data:
          value: 1000
  - alias: "NerdQAxe full power when solar returns"
    trigger:
      - platform: numeric_state
        entity_id: sensor.solar_power
        above: 200
    action:
      - action: number.set_value
        target:
          entity_id: number.nerdqaxe_asic_frequency
        data:
          value: 500
      - action: number.set_value
        target:
          entity_id: number.nerdqaxe_core_voltage
        data:
          value: 1150

Firmware Updates

The update.nerdqaxe_firmware_update entity automatically checks for new versions on GitHub:

Display in Lovelace:

type: update
entity: update.nerdqaxe_firmware_update
show_title: true
show_current_version: true
show_latest_version: true

Installing an Update:

The update entity automatically appears in the Home Assistant dashboard when a new version is available. Simply click "Install" to download and flash the new version directly from GitHub.

Important note: The miner will automatically restart after the update installation.

Development

Technical Architecture

`init.py`

Main file that:

Initializes the integration
Creates the DataUpdateCoordinator to manage updates
Configures platforms (sensor, binary_sensor, button, update)

NerdQAxeDataUpdateCoordinator Class:

Connects to http://<host>/api/system/info every X seconds
Parses JSON data
Distributes data to sensors via the Coordinator pattern

`config_flow.py`

Handles UI configuration:

Validates miner connection
Configures scan interval
Automatic detection of hostname and model

`sensor.py`

Defines all sensors:

Uses CoordinatorEntity for automatic updates
Appropriate device classes for Energy Dashboard
State classes for long-term statistics

`binary_sensor.py`

Binary sensor for Stratum pool connection status.

`button.py`

Defines the restart button:

Calls the miner's POST /api/system/restart API
Restarts the miner instantly

`number.py`

Number entities for performance control:

ASIC frequency control (1-1000 MHz)
Core voltage control (1000-1350 mV)
Calls the miner's PATCH /api/system API
Automatically refreshes coordinator after changes

`update.py`

Firmware update entity:

Automatically checks GitHub releases
Compares installed version with latest available version
Filters pre-releases and RC versions
Downloads and installs firmware directly from GitHub
Uses the POST /api/system/OTA/github endpoint with firmware URL
Displays release notes in Home Assistant
Checks for updates every 6 hours

Adding a New Sensor

In const.py, add the constant:

ATTR_NEW_FIELD = "newField"

In sensor.py, add a NerdQAxeSensorEntityDescription to the SENSORS tuple:

NerdQAxeSensorEntityDescription(
    key="new_sensor",
    icon="mdi:icon-name",
    native_unit_of_measurement="unit",
    device_class=SensorDeviceClass.XXX,
    state_class=SensorStateClass.MEASUREMENT,
    value_fn=lambda data: data.get(ATTR_NEW_FIELD),
),

Add the entity name under entity.sensor.new_sensor.name in strings.json and every file in translations/ (keep all language files in sync — the entity name is resolved from translation_key, never from a hardcoded _attr_name).

Local Testing

Copy custom_components/nerdqaxe to your HA config
Restart HA
Add the integration via UI
Check logs: Settings → System → Logs

Debug

Enable debug logs in configuration.yaml:

logger:
  default: info
  logs:
    custom_components.nerdqaxe: debug

Roadmap / Future Features

✅ Implemented Features:

Miner restart button
Update entity with automatic GitHub version checking
Firmware version sensor
HA Energy Dashboard integration (power, voltage, current sensors)
Uptime sensors (via 1d hashrate)
Periodic update checks (every 6 hours)
Number entities to dynamically modify frequency/voltage
Automatic network discovery of miners (DHCP) with IP auto-refresh

🔜 Features to Add:

WebSocket support for real-time hashrate updates
Multi-miner support (multiple devices in one integration)
Pre-configured Lovelace dashboard with all cards
Pool difficulty sensor
Configurable alerts via UI
Update available notifications
Miner configuration backup/restore

Possible Improvements:

Add Home Assistant services to control the miner
Support multiple miners with a single entry
Integrated performance graphs
Configurable push notifications via UI
Support for NerdAxeGamma boards and other variants

Contributing

Contributions are welcome! Feel free to:

Open an issue for a bug or feature request
Submit a pull request
Improve documentation

License

MIT

Credits

NerdQAxe+ Firmware: https://github.com/shufps/ESP-Miner-NerdQAxePlus
NerdQAxe+ Hardware: https://github.com/shufps/qaxe
BitAxe devs: @skot (ESP-Miner), @ben, @jhonny
NerdAxe dev: @BitMaker

Support

HA Integration Issues: GitHub Issues
Firmware Issues: ESP-Miner-NerdQAxePlus Issues
NerdMiner Discord:

Name		Name	Last commit message	Last commit date
Latest commit History 83 Commits
.github		.github
custom_components/nerdqaxe		custom_components/nerdqaxe
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
NerdAxeGamma_dark.png		NerdAxeGamma_dark.png
NerdAxeGamma_dark_256.png		NerdAxeGamma_dark_256.png
NerdAxeGamma_light.png		NerdAxeGamma_light.png
README.md		README.md
hacs.json		hacs.json
pyproject.toml		pyproject.toml
renovate.json		renovate.json

Folders and files

Latest commit

History

Repository files navigation