v1.1.0: English UI + docs, bundled Bitcoin icon, canonical config page, gitea.a14r.be website URL, journal diagnostics
This commit is contained in:
ArnoldCordewiner
@@ -1,77 +1,92 @@
|
||||
# plasma-bitcoin-price
|
||||
# Bitcoin Price (Plasma 5 widget)
|
||||
|
||||
KDE Plasma 5 widget die de bitcoinprijs in EUR toont, opgehaald bij de
|
||||
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).
|
||||
|
||||
## Weergave
|
||||
## Display
|
||||
|
||||
| Situatie | Weergave |
|
||||
| Situation | Display |
|
||||
|---|---|
|
||||
| Prijs gestegen t.o.v. vorige meting | groen |
|
||||
| Prijs gedaald t.o.v. vorige meting | rood |
|
||||
| Prijs gelijk gebleven (of eerste meting) | grijs |
|
||||
| API-fout (netwerkfout, 4xx/5xx, rate limit 429) | `--` |
|
||||
| Price up compared to the previous reading | green |
|
||||
| Price down compared to the previous reading | red |
|
||||
| Price unchanged (or first reading) | grey |
|
||||
| API failure (network error, 4xx/5xx, rate limit 429) | `--` |
|
||||
|
||||
Formaat: `₿ 68.969 €` — duizendtallen volgens de systeemlocale, afgerond op hele euro's.
|
||||
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.
|
||||
|
||||
## Configuratie
|
||||
## Configuration
|
||||
|
||||
- **Vernieuwinterval (minuten)** — standaard 5, minimaal **5**, maximaal 1440.
|
||||
Het minimum van 5 minuten komt door de CoinGecko rate limit van 1 call per 5 minuten.
|
||||
- **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.
|
||||
|
||||
Instelbaar via rechtsklik op de widget → *Configureer Bitcoin-prijs* → *Algemeen*.
|
||||
Configurable via right-click on the widget → *Configure Bitcoin Price…* → *General*.
|
||||
|
||||
## Installatie
|
||||
## Installation
|
||||
|
||||
### Grafisch
|
||||
Dubbelklik op `dist/bitcoin-price-1.0.0.plasmoid` in Dolphin (Plasma installeert
|
||||
dan automatisch naar `~/.local/share/plasma/plasmoids/`).
|
||||
### Graphical
|
||||
Double-click `bitcoin-price-1.1.0.plasmoid` in Dolphin (Plasma installs it to
|
||||
`~/.local/share/plasma/plasmoids/` automatically). The latest build is attached
|
||||
to the [v1.1.0 release](../../releases/tag/v1.1.0).
|
||||
|
||||
### Terminal
|
||||
```bash
|
||||
kpackagetool5 --type Plasma/Applet --install dist/bitcoin-price-1.0.0.plasmoid
|
||||
# widget toevoegen via Add Widgets; bij twijfel plasma herladen:
|
||||
kpackagetool5 --type Plasma/Applet --upgrade bitcoin-price-1.1.0.plasmoid
|
||||
# Then restart the shell if needed:
|
||||
plasmashell --replace &
|
||||
```
|
||||
|
||||
Verwijderen:
|
||||
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
|
||||
```
|
||||
|
||||
## Notities
|
||||
## Notes
|
||||
|
||||
- De API-URL gebruikt `vs_currencies=eur`. In de oorspronkelijke opdracht stond
|
||||
een `usd`-URL, maar de eis was "prijs t.o.v. de euro" met een `€`-teken; een
|
||||
dollarwaarde onder een €-teken zou foutief zijn.
|
||||
- De trendvergelijking gebeurt tegen de laatst bekend geraakte prijs. Na een
|
||||
API-fout blijft die referentie staan, zodat de kleur klopt zodra er weer
|
||||
data binnenkomt.
|
||||
- Zonder CoinGecko API-key kan de API ook tussendoor een 429 geven; de widget
|
||||
toont dan `--` tot de eerstvolgende geslaagde poll.
|
||||
- Getest op Debian 12 / Plasma 5 (Qt 5.15). Plasma 6 werkt vermoedelijk ook,
|
||||
maar is niet getest.
|
||||
- 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.
|
||||
|
||||
## Repository-layout
|
||||
## 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/main.xml # config schema (refreshMinutes, min 5, max 1440)
|
||||
├── images/bitcoin.svg # bundled Bitcoin icon
|
||||
└── ui/
|
||||
├── main.qml # widget + fetch/vergelijk-logica
|
||||
├── config.qml # configuratievenster (categorieën)
|
||||
└── configGeneral.qml # interval-instelling
|
||||
├── main.qml # widget + fetch/compare logic
|
||||
├── config.qml # config dialog (categories)
|
||||
└── configGeneral.qml # interval setting
|
||||
```
|
||||
|
||||
Het kant-en-klare installatiebestand (`bitcoin-price-1.0.0.plasmoid`) staat als
|
||||
bijlage bij de [v1.0.0-release](../../releases/tag/v1.0.0).
|
||||
|
||||
Zelf (her)packagen:
|
||||
Repackage yourself:
|
||||
```bash
|
||||
zip -r bitcoin-price.plasmoid metadata.desktop contents
|
||||
```
|
||||
|
||||
## Licentie
|
||||
## License
|
||||
|
||||
MIT — zie [LICENSE](LICENSE).
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user