112 lines
4.0 KiB
Markdown
112 lines
4.0 KiB
Markdown
# Bitcoin Price (Plasma 5 widget)
|
||
|
||
KDE Plasma 5 widget that shows the bitcoin price in EUR, fetched from the
|
||
[CoinGecko API](https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=eur).
|
||
|
||
## Display styles
|
||
|
||
Three display styles, configurable in the settings dialog:
|
||
|
||
| Style | Description |
|
||
|---|---|
|
||
| *Plain text* | Trend-colored text (green/red/grey) |
|
||
| *Split-flap board* | Airport board: white digit flaps, white € sign in the default font, cascading flip animation on price changes (configurable duration), trend LED |
|
||
| *Nixie tubes* | Retro amber glowing digits in glass tubes with configurable random flicker, white € sign in the default font, trend LED |
|
||
|
||
In the split-flap and nixie styles the digits keep their display color and the
|
||
trend (up/down/unchanged) is shown on a small LED next to the display.
|
||
Display style changes apply immediately, without restarting the shell.
|
||
|
||
| Situation | Plain text color | Trend LED |
|
||
|---|---|---|
|
||
| Price up | green | green |
|
||
| Price down | red | red |
|
||
| Price unchanged / first reading | grey | grey |
|
||
| API failure (network error, 4xx/5xx, rate limit 429) | `--` | grey |
|
||
|
||
Format: `68,969 €` (thousands separators follow the system locale, rounded to
|
||
whole euros) preceded by the bundled Bitcoin icon in the compact and full
|
||
representations.
|
||
|
||
## Configuration
|
||
|
||
- **Refresh interval (minutes)** — default 5, minimum **5**, maximum 1440.
|
||
The 5-minute floor exists because the CoinGecko API allows one request per
|
||
5 minutes. A hint text in the config dialog explains this.
|
||
- **Split-flap cascade (seconds)** — default 3, range 1–15. Spreads the flip
|
||
animation of a price change evenly over this many seconds (applies to the
|
||
split-flap display style). Only shown when that style is selected.
|
||
- **Nixie flicker (0 = off)** — default 40, range 0–100. Random cathode-dropout
|
||
flicker of the nixie tubes; 0 disables it, higher values flicker more often
|
||
and deeper. Only shown when the nixie style is selected.
|
||
|
||
Configurable via right-click on the widget → *Configure Bitcoin Price…* → *General*.
|
||
|
||
## Installation
|
||
|
||
### Graphical
|
||
Double-click `bitcoin-price-1.3.0.plasmoid` in Dolphin (Plasma installs it to
|
||
`~/.local/share/plasma/plasmoids/` automatically). The latest build is attached
|
||
to the [v1.3.0 release](../../releases/tag/v1.2.0).
|
||
|
||
### Terminal
|
||
```bash
|
||
kpackagetool5 --type Plasma/Applet --upgrade bitcoin-price-1.3.0.plasmoid
|
||
# Then restart the shell if needed:
|
||
plasmashell --replace &
|
||
```
|
||
|
||
Upgrading an already-installed widget requires `--upgrade` (`--install` fails
|
||
when the plugin id already exists).
|
||
|
||
Uninstall:
|
||
```bash
|
||
kpackagetool5 --type Plasma/Applet --remove nl.a14r.bitcoinprice
|
||
```
|
||
|
||
## Notes
|
||
|
||
- The API URL uses `vs_currencies=eur`. The original request referenced a
|
||
`usd` URL, but the requirement was "price versus the euro" with a €-sign;
|
||
showing a dollar amount under a € sign would be wrong.
|
||
- The trend comparison is made against the last known price. After an API
|
||
failure that reference is kept, so the color is correct again as soon as
|
||
fresh data arrives.
|
||
- Without a CoinGecko API key the API may occasionally return 429; the widget
|
||
shows `--` until the next successful poll.
|
||
- Tested on Plasma 5.27 / Qt 5.15. Plasma 6 is expected to work but is untested.
|
||
|
||
## Debugging
|
||
|
||
The widget logs to the plasmashell journal:
|
||
|
||
```bash
|
||
journalctl --user -u plasma-plasmashell.service | grep bitcoinprice
|
||
```
|
||
|
||
Expected lines: `started, refresh interval: N minutes`, `fetched EUR <price>`,
|
||
or `fetch failed, HTTP status: <code>`.
|
||
|
||
## Repository layout
|
||
|
||
```
|
||
metadata.desktop
|
||
contents/
|
||
├── config/
|
||
│ ├── main.xml # config schema (refreshMinutes, min 5, max 1440)
|
||
│ └── config.qml # config dialog registry (ConfigModel/ConfigCategory)
|
||
├── images/bitcoin.svg # bundled Bitcoin icon
|
||
└── ui/
|
||
├── main.qml # widget + fetch/compare logic
|
||
└── configGeneral.qml # interval setting page
|
||
```
|
||
|
||
Repackage yourself:
|
||
```bash
|
||
zip -r bitcoin-price.plasmoid metadata.desktop contents
|
||
```
|
||
|
||
## License
|
||
|
||
MIT — see [LICENSE](LICENSE).
|