Skip to content

01-getting-started.md

Latest commit

 

History

History
100 lines (75 loc) · 3.37 KB

01-getting-started.md

File metadata and controls

100 lines (75 loc) · 3.37 KB
Raw

Getting Started with Serial Studio Extensions

What are Extensions?

Extensions add functionality to Serial Studio without modifying the core application. There are two types:

Type Description Example
Theme Custom color palette for the entire UI Solarized Dark, Midnight
Plugin External program with its own UI Digital Indicator, Custom Gauge

Installing Extensions

  1. Open Serial Studio and click Extensions in the toolbar
  2. Browse the catalog. Extensions are grouped by type
  3. Click a card to see details, then click Install
  4. Themes appear in Preferences, plugins can be launched from the detail view or the dashboard Start Menu

Creating Your First Extension

Every extension needs:

  1. A directory under the correct type folder (theme/, plugin/, etc.)
  2. An info.json file with metadata
  3. The extension files (theme JSON, Python script, etc.)
  4. A README.md describing the extension

Minimal info.json

{
  "schemaVersion": 2,
  "id": "my-extension",
  "type": "theme",
  "title": "My Extension",
  "description": "What it does.",
  "author": "Your Name",
  "version": "1.0.0",
  "license": "MIT",
  "category": "Dark",
  "files": ["info.json", "my-theme.json", "code-editor/my-theme.xml"],
  "sha256": {
    "my-theme.json": { "sha256": "<64 hex chars>", "size": 5447 },
    "code-editor/my-theme.xml": { "sha256": "<64 hex chars>", "size": 1905 }
  }
}

File Digests

Serial Studio verifies every file it installs against the SHA-256 the entry publishes: files land in a staging directory, each is checked, and only a complete verified set replaces the installed version. A single mismatched byte aborts the install and leaves the previous version untouched. An entry that publishes no digests is refused.

Never write the sha256 table by hand. Run:

python3 scripts/update-digests.py           # rewrite every info.json
python3 scripts/update-digests.py --check   # CI gate: fail if any digest is stale

Rerun it after every edit to a listed file, including a one-character fix. CI runs --check on each pull request.

Two details are worth knowing:

  • info.json is listed in files but never gets a digest. Its digest would have to live inside the bytes it covers. Serial Studio installs the catalog document it already parsed.
  • files stays a plain list of paths. The digests live in the separate sha256 table keyed by the same path, which is what keeps this repository installable by Serial Studio 4.1.0 and earlier: those releases read files and ignore the rest. Newer releases verify.

Per-platform overrides carry their own sha256 table, merged over the entry-wide one at install time, so platforms."windows/*" publishes the digest of run.cmd and nothing else.

Adding to a Repository

Add the path to your extension's info.json in the repository's manifest.json:

{
  "version": 2,
  "repository": "My Extensions",
  "extensions": [
    "theme/my-extension/info.json"
  ]
}

Testing Locally

In Serial Studio Pro, open Extensions → Repos → Browse and select your repository folder. Extensions appear immediately for installation and testing.

Next Steps