labpulse 0.3.6__tar.gz

labpulse-0.3.6/.dockerignore

@@ -0,0 +1,4 @@
+*
+!Dockerfile
+!dist/
+!dist/labpulse-*.whl

labpulse-0.3.6/.gitattributes

@@ -0,0 +1,3 @@
+# Keep Raspberry Pi shell scripts executable by /usr/bin/env.
+*.sh text eol=lf
+*.py text eol=lf

labpulse-0.3.6/.github/workflows/release.yml

@@ -0,0 +1,170 @@
+name: Release LabPulse
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  validate:
+    name: Validate release artifacts
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine setuptools-scm
+
+      - name: Resolve release version from tag
+        id: version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version="${RELEASE_TAG#v}"
+          scm_version="$(python -m setuptools_scm)"
+          if [ "$scm_version" != "$version" ]; then
+            echo "Release tag $RELEASE_TAG produced package version $scm_version, expected $version" >&2
+            exit 1
+          fi
+          echo "Release tag determines package version $scm_version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Install LabPulse
+        run: python -m pip install --editable ".[dev]"
+
+      - name: Run hardware-free tests
+        run: python -m pytest
+
+      - name: Build and check distributions
+        run: |
+          python -m build
+          python -m twine check dist/*
+
+      - name: Smoke-test installed wheel and source distribution
+        run: |
+          python -m venv "$RUNNER_TEMP/wheel-smoke"
+          "$RUNNER_TEMP/wheel-smoke/bin/python" -m pip install dist/*.whl
+          "$RUNNER_TEMP/wheel-smoke/bin/labpulse" help
+          "$RUNNER_TEMP/wheel-smoke/bin/python" -c "from labpulse.installer import find_install_assets; print(find_install_assets())"
+          "$RUNNER_TEMP/wheel-smoke/bin/labpulse" \
+            --live-dir "$RUNNER_TEMP/labpulse-live" setup --fake-hardware
+          "$RUNNER_TEMP/wheel-smoke/bin/python" -c "import sys, yaml; data = yaml.safe_load(open(sys.argv[1])); images = {service.get('image') for name, service in data['services'].items() if name.startswith('labpulse-')}; expected = {'ghcr.io/lairdgrouplancaster/labpulse:${{ steps.version.outputs.version }}'}; assert images == expected, (images, expected)" "$RUNNER_TEMP/labpulse-live/compose.yaml"
+          test ! -d "$RUNNER_TEMP/labpulse-live/labpulse-python"
+          python -m venv "$RUNNER_TEMP/sdist-smoke"
+          "$RUNNER_TEMP/sdist-smoke/bin/python" -m pip install dist/*.tar.gz
+          "$RUNNER_TEMP/sdist-smoke/bin/labpulse" help
+
+      - name: Smoke-test container
+        run: |
+          docker build \
+            --build-arg "LABPULSE_VERSION=${{ steps.version.outputs.version }}" \
+            --tag labpulse-release-smoke \
+            .
+          docker run --rm labpulse-release-smoke \
+            python -c "from importlib.metadata import version; assert version('labpulse') == '${{ steps.version.outputs.version }}'"
+          docker run --rm labpulse-release-smoke python -m labpulse.hardware --help
+          docker run --rm labpulse-release-smoke python -m labpulse.sms --help
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-python:
+    name: Publish Python distributions to PyPI
+    needs: validate
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/labpulse/${{ needs.validate.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-container:
+    name: Publish multi-platform container
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate image metadata
+        id: metadata
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/lairdgrouplancaster/labpulse
+          tags: |
+            type=semver,pattern={{version}},value=${{ github.event.release.tag_name }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ github.event.release.tag_name }}
+          labels: |
+            org.opencontainers.image.title=LabPulse
+            org.opencontainers.image.description=Raspberry Pi laboratory infrastructure monitoring
+
+      - name: Build and push image
+        id: image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            LABPULSE_VERSION=${{ needs.validate.outputs.version }}
+          tags: ${{ steps.metadata.outputs.tags }}
+          labels: ${{ steps.metadata.outputs.labels }}
+          provenance: mode=max
+          sbom: true
+
+      - name: Attest image provenance
+        uses: actions/attest@v4
+        with:
+          subject-name: ghcr.io/lairdgrouplancaster/labpulse
+          subject-digest: ${{ steps.image.outputs.digest }}
+          push-to-registry: true

labpulse-0.3.6/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test LabPulse
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  pytest:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install LabPulse and test dependencies
+        run: python -m pip install --editable ".[dev]"
+
+      - name: Run hardware-free tests
+        run: python -m pytest

labpulse-0.3.6/.gitignore

@@ -0,0 +1,18 @@
+waterenv/
+.venv/
+build/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+/logs/
+**/__pycache__/
+
+# Generated Home Assistant smoke-test outputs
+tmp_ha_*/
+tmp_ha_*-check.py
+/testing/tmp/
+
+# Codex local workspace/artifact files
+.codex/
+.agents/

labpulse-0.3.6/.vscode/launch.json

@@ -0,0 +1,7 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": []
+}

labpulse-0.3.6/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:system",
+    "python-envs.defaultPackageManager": "ms-python.python:pip"
+}

labpulse-0.3.6/.vscode/tasks.json

@@ -0,0 +1,29 @@
+{
+    "tasks": [
+        {
+            "type": "cppbuild",
+            "label": "C/C++: clang build active file",
+            "command": "/usr/bin/clang",
+            "args": [
+                "-fcolor-diagnostics",
+                "-fansi-escape-codes",
+                "-g",
+                "${file}",
+                "-o",
+                "${fileDirname}/${fileBasenameNoExtension}"
+            ],
+            "options": {
+                "cwd": "${fileDirname}"
+            },
+            "problemMatcher": [
+                "$gcc"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "detail": "Task generated by Debugger."
+        }
+    ],
+    "version": "2.0.0"
+}

labpulse-0.3.6/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable user-visible changes will be recorded here. The earlier prototype
+history was not maintained as formal releases.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+### Added
+
+- Independent Triton control-PC publisher heartbeats and availability, with
+  fridge service alerts driven by script health instead of logfile activity.
+- A per-service `notify_on_service_failure` setting, enabled by default, to
+  silence known unreliable or intentionally disconnected hubs without hiding
+  their status.
+
+- Repository-wide MIT licensing for software, firmware, documentation, and
+  hardware design files.
+- A reference Raspberry Pi deployment matrix and explicit pre-1.0 support,
+  compatibility, safety, and experimental-feature boundaries.
+- An explicit product boundary defining LabPulse as monitoring and best-effort
+  alerting rather than safety-critical equipment control.
+- A pipx-installable `labpulse` package and unified operator command.
+- Setup, lifecycle, logs, configuration, browser, firmware-help, and diagnostic
+  commands.
+- Version reporting through `labpulse version` and runtime-image matching in
+  `labpulse doctor`.
+- Tag-derived package, runtime, and container versions through `setuptools-scm`.
+- One-container-per-service hardware execution with a central lifecycle runner.
+- Self-contained serial, DHT11, and X1200 drivers with declarative resources.
+- A self-contained Sensirion SHT40 I2C temperature/humidity driver with
+  CRC-validated measurements and least-privilege device access.
+- Compressed-air Arduino firmware that publishes pressure plus SHT40
+  temperature/humidity through the standard serial pipe, with the superseded
+  pressure-only sketch retained under `legacy/Arduino/pressure_monitor/`.
+- Complete fake-hardware deployments which preserve the configured dashboard
+  and container layout while simulating every sensor and output in memory.
+- Generated Home Assistant MQTT entities, alarm package, and native YAML
+  dashboard.
+- Dry-run, test-mode, and modem-backed SMS delivery with subscription controls.
+- Checksummed, consistent state archives and guarded blank-host reconstruction
+  through `labpulse backup` and `labpulse restore`.
+- A release workflow that validates wheel, source distribution, and container
+  artifacts, publishes through PyPI Trusted Publishing, and publishes
+  attested AMD64/ARM64 images to GHCR.
+
+### Changed
+
+- Home Assistant now receives the validated IANA timezone selected in
+  `config.yaml` instead of a hard-coded `Europe/London` timezone.
+- Service measurement configuration now supports typed shared defaults,
+  infers labels from stable IDs when omitted, and keeps MQTT JSON source names
+  beside their measurements instead of duplicating IDs under driver options.
+- Optional hardware dependencies are grouped by the `serial`, `i2c`, and
+  `gpio` connection types instead of individual driver names.
+- The installed deployment directory is `~/labpulse-live`.
+- The guarded configuration command is `labpulse config`.
+- Deployment shell scripts are maintained under `deployment/`.
+- Measurement units are published exactly as configured while icons are
+  derived independently.
+- Real-Pi reliability acceptance now records two weeks of continuous operation,
+  real and injected hardware faults, UPS and abrupt-power recovery, restart
+  alarm reconciliation, SMS delivery, and the built-in watchdog decision.
+- `labpulse config` now preserves an active fake-hardware deployment and validates
+  and regenerates its derived runtime configuration transactionally.
+- Hardware lifecycle logs now include stable service/driver/target context,
+  status transitions, and the age of the last valid reading.
+- `labpulse doctor` now reports the active runtime mode and gives corrective
+  commands or checks for common deployment, container, hardware, MQTT, and
+  Home Assistant failures.
+- `labpulse down` and `labpulse restart` accept individual Compose service
+  names.
+- Generated deployments use the GHCR image matching the installed package
+  version instead of copying source and rebuilding containers on each Pi.
+- Guarded configuration now uses the same configurable Docker command as every
+  other lifecycle operation.
+- Doctor now checks Docker daemon access and versions, host timezone/NTP state,
+  and systemd hardware-watchdog activation.
+- Installation now includes ordered Home Assistant/MQTT onboarding, a
+  first-install acceptance checklist, host-time validation, and a non-editable
+  production update command.
+- Power-loss and restoration notifications are explicitly separate: loss is
+  reported promptly, while recovery closes the lifecycle with outage duration.
+- Persistent Python worker logs now rotate daily and retain seven previous
+  daily files instead of growing without a bound.
+- The deployed USB assignment helper now reliably switches from the system
+  Python to LabPulse's managed environment before importing the package.
+- Measurement configuration now uses the optional strict boolean `required`
+  field, defaulting to `true`, with plainly named missing/recovery timers.
+- The generated Diagnostics view is now a human-readable System Status view
+  with Working, Needs attention, and Offline service states.
+
+### Removed
+
+- Prototype package layouts and earlier Pi implementations from the active
+  runtime. They remain under `legacy/` for reference only.
+- The redundant per-reading availability sensor and the old
+  `availability: required|optional` measurement configuration.

labpulse-0.3.6/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: >-
+  If you use LabPulse in published research, please cite the software and
+  record the exact release and local configuration used.
+title: LabPulse
+type: software
+authors:
+  - name: LabPulse contributors
+repository-code: https://github.com/lairdgrouplancaster/LabPulse
+url: https://github.com/lairdgrouplancaster/LabPulse
+license: MIT

labpulse-0.3.6/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to LabPulse
+
+Thank you for helping improve LabPulse. Changes to public commands,
+configuration or extension interfaces need migration notes and normal semantic
+versioning so existing installations are not surprised.
+
+## Before starting
+
+For a small correction, open a focused pull request. For a new feature,
+configuration change, public interface, or hardware driver, open an issue first
+so the intended behavior and test boundary can be agreed.
+
+Read:
+
+1. [User guide and safety boundary](docs/USER_GUIDE.md)
+2. [Architecture](docs/ARCHITECTURE.md)
+3. [Development](docs/DEVELOPMENT.md)
+4. [Hardware driver package guide](src/labpulse/hardware/drivers/README.md)
+   when adding direct hardware support
+5. [Firmware guide](firmware/README.md) when changing Arduino firmware or
+   serial output
+
+## Development principles
+
+- Preserve `~/labpulse-live/config.yaml` as the installed source of truth.
+- Keep sensor acquisition in Python and alarm decisions in Home Assistant.
+- Keep equipment control and safety functions outside the measurement driver
+  contract; discuss any actuation proposal before implementation.
+- Prefer the standard serial protocol when firmware can normalize a device.
+- Keep optional hardware libraries lazy so unrelated drivers and host-side
+  generation do not require them.
+- Make important behavior testable without Raspberry Pi hardware.
+- Add compatibility or migration logic only for a concrete published-release
+  requirement.
+- Do not commit phone numbers, credentials, Home Assistant state, logs, or
+  locally generated deployment files.
+
+## Making a change
+
+1. Create a branch from the current main branch.
+2. Install the project in editable mode as described in
+   [Development](docs/DEVELOPMENT.md).
+3. Make the smallest coherent change.
+4. Add or update automated tests.
+5. Update the authoritative documentation for changed behavior.
+6. Run the complete hardware-free suite with `python -m pytest`.
+7. Describe any real-Pi checks that are still required.
+
+By submitting a contribution, you agree that it may be distributed under the
+[MIT License](LICENSE) used by this project.
+
+Do not hand-edit generated `compose.yaml`,
+`homeassistant/config/packages/labpulse_generated.yaml`, or
+`homeassistant/config/labpulse-dashboard.yaml` as source changes. Update their
+generators, models, templates, or source configuration.
+
+## Pull requests
+
+A pull request should explain:
+
+- the problem and intended behavior;
+- the components changed;
+- automated tests run;
+- real hardware tested, if any;
+- configuration or generated-output changes;
+- documentation updated;
+- remaining risks or follow-up work.
+
+Keep unrelated formatting and refactors out of functional changes. Preserve
+user changes already present in the branch.
+
+## Hardware contributions
+
+First decide whether the device can emit the unit-free pipe-delimited serial
+protocol. If it can, add firmware, configuration, simulator coverage, and
+documentation without creating a Python driver.
+
+A direct-hardware driver must include:
+
+- a stable driver ID and strict options model;
+- `connect`, `read`, and idempotent `close` behavior;
+- normalized numeric readings and classified failures;
+- declarative container resources;
+- lazy optional dependency imports;
+- hardware-free tests for configuration, reading, failure, and cleanup;
+- fake or injectable hardware where practical;
+- example configuration and documentation;
+- a recorded real-device smoke test before release.
+
+See the [hardware driver package guide](src/labpulse/hardware/drivers/README.md).
+
+## Documentation style
+
+Write current facts rather than implementation history. Put operator tasks in
+operator guides, cross-component contracts in architecture references, and
+code-local details in docstrings. Avoid creating one-off implementation-plan
+documents for completed features.
+
+Use relative links inside the repository. Examples must distinguish the
+repository starter `config.yaml` from the installed
+`~/labpulse-live/config.yaml`.
+
+## Participation
+
+Be respectful, constructive, and professional when opening issues, reviewing
+changes, or discussing the project. Do not publish credentials, phone numbers,
+private network details, or other sensitive information in issues or pull
+requests.

labpulse-0.3.6/Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12-slim
+
+ARG LABPULSE_VERSION
+
+LABEL org.opencontainers.image.source="https://github.com/lairdgrouplancaster/LabPulse"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.version="${LABPULSE_VERSION}"
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        gpiod \
+        modemmanager \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY dist/labpulse-${LABPULSE_VERSION}-py3-none-any.whl /tmp/
+
+RUN python -m pip install --no-cache-dir \
+      "labpulse[serial,i2c,gpio] @ file:///tmp/labpulse-${LABPULSE_VERSION}-py3-none-any.whl" \
+    && rm "/tmp/labpulse-${LABPULSE_VERSION}-py3-none-any.whl"
+
+CMD ["python", "-m", "labpulse.hardware", "--help"]

labpulse-0.3.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LabPulse contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.