Scaffold a Device Project

The command

mkdir plesty-power-meter && cd plesty-power-meter
uv run --directory /path/to/plesty-sdk plesty init device

Or, if plesty-sdk is globally installed:

mkdir plesty-power-meter && cd plesty-power-meter
plesty init device

With explicit options:

plesty --project-dir ~/projects/plesty-power-meter init device \
  --name power_meter \
  --author "Jane Doe" \
  --email jane@example.com

plesty init infers the module name from the directory: plesty-power-meter → power_meter. The --name flag overrides this.

Generated layout

plesty-power-meter/
├── plesty/
│   └── power_meter/
│       ├── __init__.py          # public exports
│       ├── __main__.py          # entry point (guarded by __name__ == "__main__")
│       ├── base_device.py       # BaseDeviceSyncModel subclass
│       └── device.py            # thin wrapper / DocDevice for manual generation
├── docs/
│   ├── index.md                 # Gate 5 requirement
│   └── toc.yaml
├── tests/
│   ├── __init__.py
│   └── test_power_meter.py      # smoke tests covering all public methods
├── .env.example                 # credential template — real values go in .env (never committed)
├── .git/
│   └── hooks/
│       └── pre-push             # runs plesty check (standard from pyproject.toml)
├── .gitignore
├── .gitlab-ci.yml               # plesty-standard-ci component
├── CHANGELOG.md                 # Gate 5 requirement
├── LICENSE
├── LICENSES/
│   └── LGPL-3.0-or-later.txt
├── REUSE.toml                   # licensing metadata for non-code files
├── pyproject.toml
└── README.md

Parameter and operation schemas are not part of the scaffold — you add them during implementation; see Schemas.

What init does automatically

After copying the template, plesty init:

1. Formats generated files — runs ruff format with the SDK config, so the scaffold already passes Gate 2 from commit zero.
2. Creates the initial git commit — required by versioningit to resolve a package version from git history.
3. Installs the pre-push hook — writes .git/hooks/pre-push to run plesty check using the standard in pyproject.toml.

First check after scaffolding

uv sync
uv run plesty check

A freshly scaffolded project passes all quantum gates immediately. If any gate fails on a fresh scaffold, that is a bug in plesty init — report it.

pyproject.toml highlights

[project]
name = "plesty-power-meter"
dynamic = ["version"]
dependencies = ["plesty-lib>=<newest>"]   # resolved when the scaffold runs

[dependency-groups]
dev = ["pytest>=9.0.0", "pytest-cov>=5.0", "mypy>=1.0", "plesty-sdk>=<newest>"]

[tool.plesty]
# standard derives from the release version (no tag yet = pixel);
# set standard = "quantum" to pin it.
module_type = "device"

Both plesty-lib and plesty-sdk are pinned to the newest release published when the scaffold runs — plesty init asks PyPI and writes the number in, so <newest> above is a real version in your file. --lib-version overrides it when you need an older library or a pre-release.

The module_type = "device" line activates the device gates — d1 Device API Pipeline, d2 Device Status Contract and d3 Device Docs. Setting it to experiment or analyzer activates that type's gates instead, and leaving it out means all of them report N/A.