Getting started

This guide walks through the typical workflow for creating and developing a Plesty-compliant device project.

1. Scaffold a new project

Name the project directory plesty-<name>, navigate into it, and run plesty init. The module name is automatically inferred by stripping the plesty- prefix:

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

This produces a plesty/power_meter/ source folder, a PyPI distribution named plesty-power-meter, and a package importable as plesty.power_meter. Alternatively, specify everything explicitly:

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

This generates a project pre-configured with the expected repository structure, pyproject.toml, example source files, CI pipeline (.gitlab-ci.yml), documentation stubs, and a CHANGELOG.md. A pre-push git hook is also installed automatically — it runs plesty check before every git push, at the project’s resolved standard (see Standard resolution).

Note

Git hooks live in .git/ and are never cloned. Anyone who clones an existing project — every contributor after the one who scaffolded it — installs the hook once:

plesty update --install-hook

Use --standard to choose the compliance standard the generated CI pipeline enforces (default pixel — a fresh scaffold is a prototype; bump it alongside your releases), or --no-ci to omit the CI file entirely.

Running what you scaffolded

A device module’s entry point does one of two things, and they are alternatives — both want the one session the instrument grants:

python -m plesty.power_meter --tcp-port 5555   # serve it for clients to drive
uv sync --extra gui
python -m plesty.power_meter --gui             # drive it yourself, in a window

The panel is built from the device schema, so the parameters and operations you declare are the controls you get — there is no GUI code to write. Qt lives in the gui extra, so a headless bench that only ever serves the device never installs it. See plesty init for how the panel picks up an instrument’s real limits, and which operations it leaves out.

2. Check compliance

Navigate into the project and run the compliance checker:

cd plesty-power-meter
plesty check

By default this checks against the project’s resolved standard — a fresh scaffold without a release tag starts at pixel and ramps up to quantum with v1.0.0 (see Standard resolution). Add --standard pixel for a fast metadata + code hygiene check, or --standard nebula for all static gates (1–6) without the slower quantum-only ones (7–11 and the module-type gates). Fix any reported issues and re-run until the check passes.

3. Test the device, without and then with hardware

Under quantum, a device module must pass gate d1: a test that runs plesty-lib’s eight mock gates without an instrument attached. Once the device declares its schema, generate that test — the command works out by itself how to reach the device without hardware:

plesty init mock-test          # writes tests/test_mock_pipeline.py

When the instrument is on the bench, add the field test. It interviews you about what is safe to run unattended, then writes a test that runs against the real device and publishes a report:

plesty init field-test
uv run python tests/field_test.py --address mock        # rehearse against the simulator
uv run python tests/field_test.py --address <address>   # then the instrument

See plesty init mock-test and plesty init field-test for what each asks and writes.

4. Preview the documentation

Start a local documentation server with live reload:

plesty docs serve

Open http://localhost:8000 in your browser. Any changes to .md or .rst files in the docs/ directory are reflected immediately.

5. Apply license headers

Keep all Python files covered by the SPDX license header:

plesty license update

This reads author and maintainer information from pyproject.toml and writes the correct header to every .py file in the project.

6. Update project metadata

Use plesty update to change author info, the PyPI distribution name, or the CI pipeline at any time without re-scaffolding the project:

# Change the author
plesty update --author "Jane Doe" --email jane@example.com

# Rename the PyPI distribution
plesty update --name plesty-pm100d

# Regenerate the CI pipeline with a different standard
plesty update --standard quantum

7. Deploy documentation

Documentation deployment is handled automatically by the hub-deploy-docs job of the plesty-standard-ci component when commits land on the default branch or a release tag is pushed. To deploy manually:

# Development snapshot
plesty docs deploy \
  https://oauth2:${TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --latest

# Versioned release
plesty docs deploy \
  https://oauth2:${TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --release