Add the user manual
Ten chapters in docs/manual, published at /manual/ on the project site: getting started, scanning, the table, health icons, actions, settings and credentials, restore to stock, export, command line, troubleshooting. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,55 @@
|
||||
# Getting started
|
||||
|
||||
Alkane Toolkit finds the ASIC miners on your network and shows them in one
|
||||
table: model, firmware, hashrate, power, temperatures, fans and the health of
|
||||
every hashboard. From the same table you can run the controls each miner's
|
||||
firmware supports, such as pausing, restarting or changing pools.
|
||||
|
||||
## Download
|
||||
|
||||
Get the latest release from the
|
||||
[downloads page](https://gitea.bluefla.re/blueflare/alkane-toolkit/releases).
|
||||
|
||||
| Platform | File | Notes |
|
||||
|---|---|---|
|
||||
| Windows 10 and 11 (x86_64) | `alkane-toolkit-vX.Y.Z-windows-x86_64.zip` | One signed `alkane-toolkit.exe`; nothing to install |
|
||||
| Linux (x86_64) | `alkane-toolkit-vX.Y.Z-linux-x86_64.tar.gz` | One binary; needs GTK 3 (`sudo apt install libgtk-3-0`) |
|
||||
|
||||
### Windows
|
||||
|
||||
1. Download the zip, right-click it, choose **Properties**, tick **Unblock** if
|
||||
it is shown, then extract it.
|
||||
2. Run `alkane-toolkit.exe`. Windows shows *BlueFlare Energy Solutions Inc.* as
|
||||
the verified publisher. To check the signature yourself, right-click the exe,
|
||||
choose **Properties** and open **Digital Signatures**.
|
||||
|
||||
### Linux
|
||||
|
||||
```sh
|
||||
tar xzf alkane-toolkit-vX.Y.Z-linux-x86_64.tar.gz
|
||||
./alkane-toolkit-vX.Y.Z-linux-x86_64/alkane-toolkit
|
||||
```
|
||||
|
||||
## First run
|
||||
|
||||
The toolkit starts a scan as soon as it opens. Set your own ranges first with
|
||||
**Scan ranges** (see [Scanning](02-scanning.md)); until you do, it scans a
|
||||
built-in default range.
|
||||
|
||||
To look around without touching any miner, start it in demo mode. It shows a
|
||||
built-in sample fleet and simulates every action:
|
||||
|
||||
| Platform | Command |
|
||||
|---|---|
|
||||
| Windows (Command Prompt) | `set ALKANE_FAKE_SCAN=1 && alkane-toolkit.exe` |
|
||||
| Linux | `ALKANE_FAKE_SCAN=1 ./alkane-toolkit` |
|
||||
|
||||
## Where settings are kept
|
||||
|
||||
| Platform | Folder |
|
||||
|---|---|
|
||||
| Windows | `%APPDATA%\alkane-toolkit` |
|
||||
| Linux | `~/.config/alkane-toolkit` |
|
||||
|
||||
See [Settings and credentials](06-settings.md) for the files in that folder.
|
||||
Deleting the folder resets the toolkit to its defaults.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Scanning
|
||||
|
||||
Discovery is read-only: a scan asks each address what it is and records what
|
||||
it reports. It never changes a miner.
|
||||
|
||||
## Scan ranges
|
||||
|
||||
Click **Scan ranges** to edit the addresses to scan. Put one entry per line;
|
||||
blank lines and lines starting with `#` are ignored.
|
||||
|
||||
| Form | Example | Scans |
|
||||
|---|---|---|
|
||||
| Single address | `192.168.1.50` | that address |
|
||||
| CIDR block | `192.168.1.0/24` | the whole block |
|
||||
| Full range | `192.168.1.10-192.168.2.40` | every address between the two, inclusive |
|
||||
| Short range | `192.168.1.10-90` | `.10` to `.90` within the same /24 |
|
||||
| Per-octet ranges | `10.1-4.0-1.1-255` | every combination (10.1.0.1 ... 10.4.1.255) |
|
||||
|
||||
Commas or spaces between several entries on one line are not accepted; use one
|
||||
line each. Duplicates are removed automatically. One line, and all lines
|
||||
together, may cover at most 1,000,000 addresses.
|
||||
|
||||
**Apply** saves the ranges and starts a scan. A mistake keeps the dialog open
|
||||
and the status bar explains it, for example `invalid range: bad octet range`.
|
||||
|
||||
The same dialog has three numbers:
|
||||
|
||||
| Field | Meaning | Default |
|
||||
|---|---|---|
|
||||
| Rescan (s) | seconds between automatic rescans; `0` turns auto-rescan off | 300 |
|
||||
| Timeout (s) | how long to wait for one miner (scans, refreshes, actions and log fetches) | 10 |
|
||||
| Concurrency | how many addresses are probed at once (8 to 256); higher is faster but slow miners may report fewer values | 128 |
|
||||
|
||||
When the ranges change, miners outside the new ranges leave the table at the
|
||||
next scan.
|
||||
|
||||
## Running, pausing and stopping
|
||||
|
||||
The three buttons next to **Scan ranges** control scanning:
|
||||
|
||||
- **Play** (green) turns auto-rescan on and starts a scan now if none is running.
|
||||
- **Pause** (amber) turns auto-rescan off and lets the current scan finish.
|
||||
- **Stop** (red) turns auto-rescan off and cancels the current scan.
|
||||
|
||||
While a scan runs, a progress bar spans the top of the table and the status bar
|
||||
shows progress such as `1935/4590 - scanning 192.168.1.86 (92 found)`. Afterwards
|
||||
it shows the count and the time to the next scan, for example
|
||||
`245 miners - next scan in 4m 12s`.
|
||||
|
||||
Actions that change miners wait for the scan to finish; see
|
||||
[Actions](05-actions.md).
|
||||
@@ -0,0 +1,80 @@
|
||||
# The table and header
|
||||
|
||||
## Summary cards
|
||||
|
||||
The cards at the top count the miners **currently shown** (after any filter).
|
||||
Each miner is in exactly one status: slow, paused, hashing or not hashing.
|
||||
|
||||
| Card | Counts | Click |
|
||||
|---|---|---|
|
||||
| Total | rows in the view | - |
|
||||
| Hashing (green rabbit) | mining at 80% of expected hashrate or more | show only these; click again to clear |
|
||||
| Slow (amber turtle) | mining below 80% of expected hashrate | show only these |
|
||||
| Not hashing (red glass) | answering but not mining | show only these |
|
||||
| Paused (blue otter) | stopped on purpose (paused, stopped, suspended) | show only these |
|
||||
| SHA-256 Hashrate | total hashrate, per algorithm | switch algorithm when the fleet runs more than one |
|
||||
| Est. power | total reported power draw | - |
|
||||
|
||||
On a narrow window the hashrate and power cards are hidden.
|
||||
|
||||
## Columns
|
||||
|
||||
IP is always the first column. The default view shows Model, Health,
|
||||
Hashrate, Power, Chip temp, Firmware, CPU, Access and Light. More than seventy
|
||||
other columns are available, grouped as Identity, Firmware and board, Health
|
||||
and status, Performance, Temperature, Cooling, Hardware and Pools.
|
||||
|
||||
- **Columns** opens a checklist: tick to show, drag to reorder, or sort the list
|
||||
alphabetically or by category. *Hide columns with no scanned values* hides
|
||||
columns that are empty for every miner (it resets when the app restarts).
|
||||
- Drag a column header to move it.
|
||||
- Right-click a header to sort by it, auto-size one or all columns, hide it, or
|
||||
open the column chooser.
|
||||
|
||||
Some values worth knowing:
|
||||
|
||||
| Column | Shows |
|
||||
|---|---|
|
||||
| Hashrate | actual/expected, for example `95.0T/96.0T`; the actual part is red at 50% of expected or less, amber around 75%, green at 100% |
|
||||
| Chip temp | hottest chip on each hashboard, for example `77 / 64 / 74`; blue when cool, red at 90 C and above |
|
||||
| Firmware | the firmware family, coloured (Braiins purple, LuxOS gold, VNish green, ePIC light blue, Hiveon orange, Bixbit pink); stock firmware uses the normal text colour |
|
||||
| Pool account / Worker | the pool user split at the first dot |
|
||||
| Board HR / V / freq | per-hashboard hashrate, voltage and frequency |
|
||||
|
||||
A blank cell means the miner did not report that value.
|
||||
|
||||
## Sorting
|
||||
|
||||
Click a header to sort ascending, again for descending, again to clear.
|
||||
|
||||
- **Hashrate** also sorts by *relative* hashrate (actual as a share of
|
||||
expected), shown as `%^` and `%v` in the header.
|
||||
- **Health** sorts by overall health, then by power (`Pwr`), fans (`Fan`) and
|
||||
hashboards (`Brd`). Ascending puts the most broken miners first.
|
||||
|
||||
## Selecting miners
|
||||
|
||||
Click a row to select it; Ctrl-click and Shift-click add to the selection, and
|
||||
you can drag across rows to select a block. The selection follows miners by IP,
|
||||
so it survives rescans. Double-click a row (or press Enter) to open the miner's
|
||||
web page in your browser. Right-click the selection for [actions](05-actions.md).
|
||||
|
||||
## Filters and presets
|
||||
|
||||
**Filter** keeps only the rows that match. Pick a column, then:
|
||||
|
||||
- for numbers: between, =, !=, >, >=, < or <= (blank cells never match);
|
||||
- for text: *is any of* (tick values; `(blank)` matches empty cells), contains,
|
||||
does not contain, begins with, ends with or equals (case does not matter).
|
||||
|
||||
Filters on different columns must all match. **Reset** clears them. Clicking a
|
||||
status card is a quick filter of its own.
|
||||
|
||||
**Presets** saves and loads whole views: column order and visibility, sort and
|
||||
filters. *Default* is built in and cannot be deleted; saving under an existing
|
||||
name replaces it.
|
||||
|
||||
## Zoom and theme
|
||||
|
||||
The slider in the bottom-right corner zooms the table: text, icons and column
|
||||
widths scale together. The window follows the system light or dark theme.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Health, access and light
|
||||
|
||||
## The Health column
|
||||
|
||||
Each miner gets a row of icons, always in the same order, so problems line up
|
||||
across the table:
|
||||
|
||||
1. **Bolt**: the power supply
|
||||
2. **Brain**: the control board
|
||||
3. **Fan**: one icon per fan
|
||||
4. **Chip**: one icon per hashboard
|
||||
|
||||
Hover over any icon to see its details: PSU voltage and current, the fan speed,
|
||||
or a hashboard's actual and expected hashrate, frequency and voltage, and any
|
||||
fault message with its code.
|
||||
|
||||
| Colour | Meaning |
|
||||
|---|---|
|
||||
| Green | healthy |
|
||||
| Amber | working but below par (a slow board, a fan well below the others, a PSU fault while still mining) |
|
||||
| Red | detected but down (a faulted board, a stopped fan, a PSU that is not delivering) |
|
||||
| Grey | expected but not detected or not reachable |
|
||||
| Blue | the miner is paused, so its boards and stopped fans are idle on purpose |
|
||||
|
||||
How each part is judged:
|
||||
|
||||
- **Power** is green when the miner draws power, its PSU fan turns or it is
|
||||
mining; a reported PSU fault makes it amber (still mining) or red.
|
||||
- **Control board** is red for a control-board fault and amber for a
|
||||
miner-wide warning such as a high ambient temperature.
|
||||
- **Fans** are red at 0 rpm and amber below half the speed of the fastest fan.
|
||||
- **Hashboards** follow the status the miner reports for each board. When the
|
||||
firmware names the failing boards, only those turn red. A board the miner
|
||||
cannot see is grey.
|
||||
|
||||
While an action runs on a miner, its Health cell shows progress such as
|
||||
`restarting...` or `refreshing...`.
|
||||
|
||||
## Access
|
||||
|
||||
The padlock shows whether the toolkit can change the miner:
|
||||
|
||||
- **green, open**: changes are possible with the saved credentials;
|
||||
- **red, closed**: view only;
|
||||
- **blank**: not known yet.
|
||||
|
||||
After a scan the padlock is an estimate from what the firmware offers. Use
|
||||
**Check access (auth)** in the right-click menu for a real, read-only login
|
||||
test.
|
||||
|
||||
## Light
|
||||
|
||||
A flashing green-over-red dot means the miner's locate light is on. Turn it on
|
||||
or off with **Flash lights** / **Stop flashing lights**.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Actions
|
||||
|
||||
Right-click one or more selected miners for the actions menu. With several
|
||||
miners selected, labels show the count, for example *Restart (12)*. An action
|
||||
appears only when **every** selected miner's firmware supports it, so the menu
|
||||
changes with the selection.
|
||||
|
||||
| Action | What it does | Changes the miner |
|
||||
|---|---|---|
|
||||
| Open in browser | opens each miner's web page | no |
|
||||
| Refresh | re-reads just these miners | no |
|
||||
| Check access (auth) | tests whether the saved login is accepted | no |
|
||||
| View log (API)... | shows the first selected miner's log (WhatsMiner: its active fault codes) | no |
|
||||
| Restore to stock firmware... | removes aftermarket firmware; see [Restore to stock](07-restore.md) | yes, reboots |
|
||||
| Flash lights / Stop flashing lights | locate light on or off | yes, harmless |
|
||||
| Pause mining / Resume mining | stop or start hashing | yes |
|
||||
| Set tuning %... | tuning level, 0 to 100 | yes |
|
||||
| Set power target... | power target in watts; the prompt shows the current value and the allowed range | yes |
|
||||
| Set hashrate target... | hashrate target in TH/s, for firmware that tunes by hashrate | yes |
|
||||
| Set profile... | pick a firmware profile or preset (only profiles every selected miner has are listed) | yes |
|
||||
| Restart | reboot | yes |
|
||||
| Configure pools... | set up to three pools | yes |
|
||||
| Set timezone... | IANA time zone, for example `America/Edmonton` | yes |
|
||||
| Change password... | new web/API password | yes |
|
||||
| Factory reset... | wipes pools, tuning and network settings and reboots; the miner may come back on a new DHCP address | yes, destructive |
|
||||
|
||||
## Safety
|
||||
|
||||
- Pause, Resume, Restart and Factory reset ask for confirmation. Value prompts
|
||||
(tuning, targets, timezone, password) apply when you confirm the value.
|
||||
- Actions that change miners do not start while a scan is running, including an
|
||||
automatic rescan. Wait for it to finish or press **Pause**. Scans in turn wait
|
||||
for running actions.
|
||||
- Each changed miner is re-read automatically when the action finishes. Results
|
||||
and failures appear in the bottom-right corner of the status bar and in
|
||||
**Settings > Logs**.
|
||||
- If **Change password** succeeds on every selected miner, the saved global
|
||||
login is updated to the new password. If only some succeed, the saved login
|
||||
is left alone and the log says so.
|
||||
|
||||
## Configuring pools
|
||||
|
||||
The pool dialog has three rows: Address, Account, Worker and Password. A row is
|
||||
used only when it has an address and an account. A blank password becomes `x`.
|
||||
The miner's username becomes `account.worker`.
|
||||
|
||||
Each field has a **+** menu with common pool addresses and the values you saved
|
||||
before (**Add new...** edits that list). Worker names can use placeholders that
|
||||
are filled in per miner:
|
||||
|
||||
| Placeholder | Becomes |
|
||||
|---|---|
|
||||
| `{ip1}` to `{ip4}` | one octet of the miner's IP |
|
||||
| `{serial}`, `{mac}` | serial number; MAC without colons |
|
||||
| `{hostname}` | the miner's hostname |
|
||||
| `{brand}`, `{model}`, `{submodel}` | make and model |
|
||||
| `{firmware}`, `{cpu}`, `{cb}` | firmware family, control-board CPU and board |
|
||||
| `{nameplate-hr}` | the model's rated hashrate |
|
||||
|
||||
For example, `rack3-{ip3}-{ip4}` gives `rack3-1-50` for `10.0.1.50`.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Settings and credentials
|
||||
|
||||
**Settings** opens a menu with Credentials, Language and Logs.
|
||||
|
||||
## Credentials
|
||||
|
||||
Miners need a login for anything beyond basic discovery: for some details, and
|
||||
for every action. The Credentials dialog has two parts:
|
||||
|
||||
- **All firmwares** at the top: one username and password tried on every miner.
|
||||
The saved password is never shown; leave the field blank to keep it. Blank
|
||||
username and password clear it.
|
||||
- **One row per firmware**, pre-filled with that firmware's factory default.
|
||||
Change a row to override the login for that firmware only.
|
||||
|
||||
The toolkit tries, in order, the firmware's own row, then the global login,
|
||||
then the firmware's built-in default.
|
||||
|
||||
| Firmware | Factory default (user / password) |
|
||||
|---|---|
|
||||
| AntMiner Stock | root / root |
|
||||
| WhatsMiner Stock | admin / admin |
|
||||
| Braiins | root / root |
|
||||
| VNish | (none) / admin |
|
||||
| LuxOS | root / root |
|
||||
| UMC OS | (none) / letmein |
|
||||
| Marathon | root / root |
|
||||
| VolcMiner Stock | root / ltc@dog |
|
||||
| Elphapex Stock | root / root |
|
||||
| FutureBit Stock | futurebit / futurebit123 |
|
||||
| SealMiner Stock | seal / seal |
|
||||
| Auradine Stock | admin / admin |
|
||||
|
||||
**Reset to defaults** clears every override and the global login at once.
|
||||
|
||||
Logins are stored as plain text in the settings folder, readable only by your
|
||||
user account (Linux file mode 0600; on Windows, your profile folder's
|
||||
permissions).
|
||||
|
||||
### SSH login
|
||||
|
||||
Restoring Braiins to stock runs a command over SSH, using the system `ssh`
|
||||
client (built into Windows 10/11). There is no dialog for this login yet:
|
||||
create `ssh-credentials.txt` in the settings folder with the username on the
|
||||
first line and the password on the second.
|
||||
|
||||
## Language
|
||||
|
||||
English, Chinese, Russian, French, Spanish and Portuguese. The toolbar, cards
|
||||
and column headers switch immediately; menus and dialogs not yet translated
|
||||
stay in English.
|
||||
|
||||
## Logs
|
||||
|
||||
An activity log of scans, actions, errors and exports, newest last, kept for
|
||||
the current session (the last 2000 lines). Times are shown in UTC.
|
||||
|
||||
## Files in the settings folder
|
||||
|
||||
| File | Holds |
|
||||
|---|---|
|
||||
| `scan-ranges.txt` | scan ranges, one per line |
|
||||
| `auto-rescan-secs.txt`, `scan-timeout-secs.txt`, `scan-concurrency.txt` | the three scan numbers |
|
||||
| `scan-credentials.txt` | global login |
|
||||
| `firmware-credentials.txt` | per-firmware logins |
|
||||
| `ssh-credentials.txt` | SSH login (created by hand) |
|
||||
| `presets.json` | saved views |
|
||||
| `language.txt` | UI language |
|
||||
| `pool-addresses.txt`, `pool-accounts.txt`, `pool-workers.txt`, `pool-passwords.txt` | saved pool values |
|
||||
@@ -0,0 +1,18 @@
|
||||
# Restore to stock firmware
|
||||
|
||||
**Restore to stock firmware...** removes aftermarket firmware and returns the
|
||||
miner to the manufacturer's firmware it keeps on board. Nothing is uploaded.
|
||||
The miner reboots, and some firmwares come back on a new address.
|
||||
|
||||
It is offered when the selection includes a supported firmware, and asks for
|
||||
confirmation with the list of miners first.
|
||||
|
||||
| Firmware | How it is removed | Login used |
|
||||
|---|---|---|
|
||||
| VNish (and builds based on it) | web API: unlock, then remove firmware; reboots in seconds | the VNish row in Credentials, else `admin` |
|
||||
| LuxOS | miner API: log on, then uninstall | none |
|
||||
| Braiins OS | SSH: runs the firmware's own `uninstall.sh` | `ssh-credentials.txt` (see [Settings](06-settings.md)) |
|
||||
|
||||
Miners are restored one at a time. A dropped connection after the command is
|
||||
sent counts as success, because that is the reboot. A refused login counts as
|
||||
a failure and leaves the miner unchanged.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Export
|
||||
|
||||
**Export** saves the scan as a CSV file for spreadsheets or other tools.
|
||||
|
||||
1. Choose the fields to include (all are ticked by default; **All** and
|
||||
**None** help).
|
||||
2. Pick where to save. The suggested name is `alkane-export-YYYYMMDD-HHMMSS.csv`.
|
||||
|
||||
The export contains **every scanned miner**, not just the rows the current
|
||||
filter shows. Per-board temperatures, fan speeds, board status and pools
|
||||
become numbered columns (`board_temp_1_c`, `fan_2_rpm`, `pool_1_url`, ...).
|
||||
|
||||
Values that start with `=`, `+`, `-` or `@` are prefixed with `'` so a
|
||||
spreadsheet treats them as text, not formulas.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Command line and environment
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Effect |
|
||||
|---|---|
|
||||
| `ALKANE_FAKE_SCAN=1` | demo mode: a built-in sample fleet, no network traffic, simulated actions |
|
||||
| `ALKANE_APPEARANCE=light` or `dark` | force the light or dark theme |
|
||||
| `ALKANE_SELFTEST=1` | run the built-in UI self-test on the sample fleet and exit (prints `SELFTEST PASS` or `FAIL`) |
|
||||
| `ALKANE_ACCESS_PROBE="<ip> <make>"` | print whether the saved login can change that miner, then exit |
|
||||
| `ALKANE_LOG_SCAN="<ip> <brand>"` | fetch that miner's log through its API, print the size, then exit |
|
||||
|
||||
On Windows these one-shot modes print to the Command Prompt they are started
|
||||
from.
|
||||
|
||||
## miner_probe
|
||||
|
||||
`miner_probe` is a command-line companion for scripting and diagnosis. These
|
||||
commands only read:
|
||||
|
||||
| Command | Prints |
|
||||
|---|---|
|
||||
| `miner_probe scan <cidr> [<cidr>...]` | discovered miners and their telemetry, as tab-separated values |
|
||||
| `miner_probe hashrate <cidr>...` | raw hashrate and algorithm |
|
||||
| `miner_probe msgs <ip>` | fault messages and per-board data |
|
||||
| `miner_probe tune <ip>` | tuning support and limits |
|
||||
| `miner_probe presets <ip>` | available firmware profiles |
|
||||
| `miner_probe timezone <ip>` | the current time zone |
|
||||
|
||||
Its other commands change miners. It uses the global login from the settings
|
||||
folder, or `ALKANE_PROBE_USER` and `ALKANE_PROBE_PASS`, and
|
||||
`ALKANE_PROBE_CONCURRENCY` (default 128).
|
||||
@@ -0,0 +1,28 @@
|
||||
# Troubleshooting
|
||||
|
||||
**Windows says "Windows protected your PC".** SmartScreen warns about new
|
||||
downloads until a certificate has built up reputation. The publisher shown
|
||||
should be *BlueFlare Energy Solutions Inc.*; click **More info**, then **Run
|
||||
anyway**. If no publisher is shown, do not run the file and download it again
|
||||
from the releases page.
|
||||
|
||||
**A miner is missing.** Check that its address is inside the scan ranges and
|
||||
that it answers on its web page from this computer. On busy or slow networks,
|
||||
raise **Timeout** or lower **Concurrency** in the Scan ranges dialog.
|
||||
|
||||
**An action is missing from the right-click menu.** Actions appear only when
|
||||
every selected miner supports them. Select fewer miners, or only miners with
|
||||
the same firmware.
|
||||
|
||||
**An action does nothing and the status says a scan is in progress.** Changes
|
||||
wait for scans. Press **Pause**, let the scan finish, then try again.
|
||||
|
||||
**Check access says locked.** The saved login is not accepted. Set the right
|
||||
password in **Settings > Credentials**, either for all firmwares or for that
|
||||
firmware's row.
|
||||
|
||||
**Values are blank.** The firmware did not report them, or it needs a login to
|
||||
report them. Try **Check access** and the Credentials dialog.
|
||||
|
||||
**The window is too small or too large.** It opens at most as large as your
|
||||
screen's work area. Use the zoom slider in the status bar to scale the table.
|
||||
Reference in New Issue
Block a user