Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,16 @@

All notable changes to SparkMiner will be documented in this file.

## [Unreleased]

### Added
- **Local stats API and settings page** (issue #12, opt-in, default OFF): AxeOS-compatible `/api/system/info` and `/api/system/statistics`, native `/api/sparkminer`, `/api/log`, mDNS announcement and an authenticated `/settings` page (WiFi, pools, display, access). See `WEB_API.md`.
- **LILYGO T-Display S3 compact layout** for the 170x320 panel (landscape and portrait) and a second-button backlight toggle.

### Fixed
- **ESP32-S3 hashrate**: `miner_sha256_header` runs from IRAM. The ~20 KB straight-line hot path thrashed the 16 KB instruction cache and limited the S3 to ~1.3 KH/s; it now reaches ~49 KH/s.
- Pool URL accepts `host:port` and `stratum+tcp://` prefixes.

## [v2.9.6-pre] - 2026-09-19

### Fixed
Expand Down
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,16 @@ Configuration is automatically saved to flash memory after first successful setu

---

## Local Stats API (optional)

SparkMiner can expose AxeOS / ESP-Miner compatible endpoints (`/api/system/info`,
`/api/system/statistics`) plus a settings page at `http://<ip>/settings`, so HashWatcher,
Home Assistant and other BitAxe tools can monitor the miner. It is off by default and costs
no hashrate while disabled. Enable it in the config portal ("Local Stats API").
See [WEB_API.md](WEB_API.md).

---

## Persistent Mining Stats

SparkMiner automatically saves mining statistics to ensure your lifetime totals are preserved across reboots and power cycles.
Expand Down
74 changes: 74 additions & 0 deletions WEB_API.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Local Stats API and Settings Page

SparkMiner can serve a small HTTP API with AxeOS / ESP-Miner compatible endpoints
(issue #12). HashWatcher, Home Assistant and other BitAxe tools can poll the miner
over the LAN. It is **opt-in**: while disabled no task is created and no socket is
opened, so there is no hashrate cost.

Uses the synchronous `WebServer` and `ESPmDNS` that ship with the Arduino core
(already pulled in by WiFiManager). No new library dependencies.

## Enable it

- **Config portal:** set "Local Stats API" to *Enabled* and save, or
- **Build default:** add `-DSPARKMINER_API_DEFAULT=1` to the build flags (only used while
the setting has never been written to NVS).

The miner announces itself via mDNS as `http://sparkminer-xxxx.local/` (`xxxx` = last two MAC bytes).

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Minimal status page |
| GET | `/api/system/info` | AxeOS-compatible system info (JSON, `hashRate` in GH/s) |
| GET | `/api/system/statistics` | AxeOS-compatible history, 120 samples x 30 s (`?columns=a,b,c`) |
| GET | `/api/sparkminer` | Compact native stats (`hashrate` in H/s), handy for Home Assistant |
| GET | `/api/log` | Recent pool/stratum events as plain text (no wallet, no passwords) |
| GET | `/settings` | Settings page (HTTP Basic auth) |
| POST | `/settings` | Save settings and restart |
| POST | `/settings/reset` | Factory reset |
| POST | `/api/system/restart` | Restart the miner |

The wallet address is masked in API responses unless "Wallet in API" is set to *Full address*.
Fields that a single ESP32 board cannot provide (power, voltage, fan, ...) are reported as `0`;
`temp` is the internal chip temperature.

## Settings page

`http://<ip>/settings`, user `admin`, default password = the setup hotspot password.
The password can be changed on the page (minimum 8 characters).

It edits WiFi, wallet, primary/backup pool, display options, live stats and API access.
Saving restarts the miner. If a new WiFi network cannot be joined, the miner returns to the
previous credentials on the next boot. The pool field accepts `host`, `host:port` and
`stratum+tcp://host:port`. POST requests with a foreign `Origin` header are rejected.

## Home Assistant

The **Bitaxe** custom integration reads `/api/system/info` and works with SparkMiner, but it
truncates `hashRate` (GH/s) to an integer, so a few hundred KH/s show up as `0`.
Use `/api/sparkminer` for a correct value, for example:

```yaml
rest:
- resource: http://<miner-ip>/api/sparkminer
scan_interval: 30
sensor:
- name: "SparkMiner Hashrate"
unique_id: sparkminer_hashrate_khs
unit_of_measurement: "kH/s"
state_class: measurement
value_template: "{{ (value_json.hashrate / 1000) | round(2) }}"
json_attributes:
- hashrate_1h
- shares_accepted
- shares_rejected
- pool_connected
```

## Event log

`GET /api/log` returns the last 64 pool/stratum events (connect, handshake, difficulty,
share submits and the pool's answers). It is kept in RAM only and helps to diagnose a pool
that rejects the miner when no serial console is attached.
Loading