Add Cricket scoreboard plugin

plugins.json

@@ -1,7 +1,34 @@
 {
   "version": "1.0.0",
-  "last_updated": "2026-07-08",
+  "last_updated": "2026-07-10",
   "plugins": [
+    {
+      "id": "cricket-scoreboard",
+      "name": "Cricket Scoreboard",
+      "description": "Live, recent, and upcoming cricket matches across international tours (Test/ODI/T20I) and major domestic T20 leagues including the IPL, Big Bash League, The Hundred, PSL, CPL, SA20 and more. Shows runs/wickets/overs, run rates, targets, and match results.",
+      "author": "ChuckBuilds",
+      "category": "sports",
+      "tags": [
+        "cricket",
+        "ipl",
+        "big-bash",
+        "t20",
+        "test-cricket",
+        "odi",
+        "sports",
+        "scoreboard",
+        "live-scores"
+      ],
+      "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins",
+      "branch": "main",
+      "plugin_path": "plugins/cricket-scoreboard",
+      "stars": 0,
+      "downloads": 0,
+      "last_updated": "2026-07-10",
+      "verified": true,
+      "screenshot": "",
+      "latest_version": "1.0.2"
+    },
     {
       "id": "7-segment-clock",
       "name": "7-Segment Clock",

plugins/cricket-scoreboard/.gitignore

@@ -0,0 +1,146 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypcache__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Project specific
+*.log
+config.json
+*.pem

plugins/cricket-scoreboard/LICENSE

@@ -0,0 +1,17 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2025 LEDMatrix Team
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

plugins/cricket-scoreboard/README.md

@@ -0,0 +1,109 @@
+# Cricket Scoreboard
+
+Live, recent, and upcoming cricket for the LEDMatrix display — covering both
+**international** matches (Test / ODI / T20I) and the **major domestic T20
+leagues** (IPL, Big Bash, The Hundred, PSL, CPL, SA20, ILT20, MLC, and more).
+
+Data comes from ESPN's public cricket API (no API key required).
+
+## Display modes
+
+| Mode | Shows |
+|------|-------|
+| `cricket_live` | In-progress matches. Limited-overs matches show `runs/wickets (overs/max ov)`, current run rate, and — when a side is chasing — the target, runs still needed, and required run rate. Test matches show the day + session (Stumps / Lunch / Tea …) and both innings, with no clock. |
+| `cricket_recent` | Completed matches: final scores + ESPN's result summary (e.g. `"RCB won by 5 wkts (12b rem)"`). |
+| `cricket_upcoming` | Scheduled matches: date/time, teams, venue, and a format badge. |
+
+Live matches take priority in the rotation when `live_priority` is on.
+
+## How series discovery works
+
+Unlike most sports, cricket has **no single stable league id** on ESPN — it is
+organised as dozens of concurrent, per-tour / per-season numeric *series* ids
+(e.g. a given season of the IPL might be `8048`, Major League Cricket `21266`,
+the Vitality Blast `8053`). Those ids change every season.
+
+So instead of hardcoding ids, the plugin **discovers them periodically**:
+
+1. It reads a curated seed list, [`competitions.json`](competitions.json), that
+   maps human competition keys (`ipl`, `bbl`, `the-hundred`, …) to stable
+   **search terms** (competition *names* are far more stable than their ids).
+2. Every `series_discovery_interval` seconds (default 24h) it queries ESPN's
+   cricket header endpoint, lists every active series, and resolves them:
+   - **domestic** competitions are matched by name against your
+     `favorite_competitions` search terms;
+   - **international** series are matched by your `favorite_teams` national-team
+     names appearing in the series/event names (e.g. *"India tour of England
+     2026"*).
+3. Each resolved numeric id's `/scoreboard` is then fetched and parsed.
+
+Resolved ids are cached (via the host `cache_manager`) so discovery is cheap.
+
+## Overs math (base-6)
+
+Cricket overs are **base-6 in the fractional part**: `18.4` overs means 18
+completed overs **plus 4 balls** = `18 + 4/6 = 18.667` decimal overs, *not*
+18.4. The plugin converts `overs → decimal overs` before any run-rate division:
+
+- current run rate = `runs / decimal_overs`
+- required run rate = `runs_needed / (balls_remaining / 6)`
+
+This conversion is unit-tested (`test_cricket_plugin.py::TestOversMath`).
+
+## Configuration
+
+Configured under the `cricket-scoreboard` key in `config/config.json`. See
+[`config_schema.json`](config_schema.json) for the full schema; key fields:
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `enabled` | `false` | Master on/off |
+| `favorite_teams` | `[]` | National teams (name or abbr, e.g. `"India"`, `"IND"`) whose international series are followed |
+| `favorite_competitions` | `["international","ipl","bbl"]` | Domestic competition keys from `competitions.json` (`international` follows Test/ODI/T20I tours for your favorite teams) |
+| `exclude_teams` | `[]` | Teams to always hide (spoiler protection) |
+| `show_favorite_teams_only` | `false` | Restrict *international* matches to those featuring a favorite team |
+| `live_game_duration` / `recent_game_duration` / `upcoming_game_duration` | 20 / 15 / 15 | Per-match on-screen seconds |
+| `non_favorite_live_game_duration` | `0` | Shorter turn for live matches without a favorite (0 = same as `live_game_duration`) |
+| `update_interval_seconds` / `live_update_interval` | 3600 / 30 | Data refresh cadence |
+| `series_discovery_interval` | `86400` | How often numeric series ids are re-resolved |
+| `recent_games_to_show` / `upcoming_games_to_show` | 5 / 5 | Match counts per mode |
+| `live_priority` | `true` | Live matches interrupt the normal rotation |
+| `display_modes` | all on | Toggle live / recent / upcoming |
+| `dynamic_duration`, `mode_durations` | off / null | Auto-size or cap each mode's total time |
+| `celebration_enabled`, `celebration_duration` | true / 8 | Win-celebration takeover |
+| `background_service` | enabled | Worker/timeout/retry tuning |
+| `customization` | — | Fonts + colors for score / overs / team / status / detail text |
+
+## Logos and flags
+
+- **Franchise** teams (IPL/BBL/etc.) auto-download their logo from ESPN
+  (`team.logos[0].href`) into `assets/logos/` on first sight, with a
+  text-abbreviation placeholder on failure — the same pattern the other sports
+  scoreboards use.
+- **National** teams use bundled flag PNGs in
+  [`assets/flags/`](assets/flags/) (keyed by both abbreviation and lowercase
+  name), because national-team abbreviations can collide with franchise codes.
+
+> **Note:** the bundled flags are **simple generated placeholders** (solid
+> national colors + abbreviation) so the wiring is complete and functional out
+> of the box. Replace them with real 48×48 flag art (same filenames) for a nicer
+> display.
+
+## v1 limitations
+
+- **No per-ball / per-player detail** (current striker, bowler figures, economy
+  rate). ESPN's cricket scoreboard response carries no `rosters`/`lineups`; that
+  would require a separate boxscore endpoint and is a possible fast-follow.
+- **The Hundred** counts balls (100) rather than overs; run rates for it are
+  best-effort.
+- Flag art is placeholder (see above).
+
+## Testing
+
+```bash
+python -m unittest test_cricket_plugin   # needs Pillow + requests
+```
+
+Covers the base-6 overs conversion, run-rate math, format normalization, all
+four renderer branches at every matrix size, and a manager update/display
+smoke test driven by the mocked responses in [`test/harness.json`](test/harness.json).

plugins/cricket-scoreboard/competitions.json

@@ -0,0 +1,63 @@
+[
+  {
+    "key": "international",
+    "name": "International (Test / ODI / T20I)",
+    "search_terms": null,
+    "description": "International tours and ICC events (Test, ODI, T20I). Matched by favorite national teams rather than a competition name."
+  },
+  {
+    "key": "ipl",
+    "name": "Indian Premier League",
+    "search_terms": ["Indian Premier League", "IPL"]
+  },
+  {
+    "key": "bbl",
+    "name": "Big Bash League",
+    "search_terms": ["Big Bash League", "KFC Big Bash", "BBL"]
+  },
+  {
+    "key": "the-hundred",
+    "name": "The Hundred",
+    "search_terms": ["The Hundred"]
+  },
+  {
+    "key": "psl",
+    "name": "Pakistan Super League",
+    "search_terms": ["Pakistan Super League", "PSL"]
+  },
+  {
+    "key": "cpl",
+    "name": "Caribbean Premier League",
+    "search_terms": ["Caribbean Premier League", "CPL"]
+  },
+  {
+    "key": "t20-blast",
+    "name": "T20 Blast (England)",
+    "search_terms": ["Twenty20 Cup", "Vitality Blast", "T20 Blast", "Blast"]
+  },
+  {
+    "key": "sa20",
+    "name": "SA20 (South Africa)",
+    "search_terms": ["SA20", "SA 20"]
+  },
+  {
+    "key": "ilt20",
+    "name": "International League T20 (UAE)",
+    "search_terms": ["International League T20", "ILT20", "DP World ILT20"]
+  },
+  {
+    "key": "mlc",
+    "name": "Major League Cricket (USA)",
+    "search_terms": ["Major League Cricket", "MLC"]
+  },
+  {
+    "key": "wbbl",
+    "name": "Women's Big Bash League",
+    "search_terms": ["Women's Big Bash League", "WBBL"]
+  },
+  {
+    "key": "wpl",
+    "name": "Women's Premier League",
+    "search_terms": ["Women's Premier League", "WPL"]
+  }
+]