thepihub 0.1.0__tar.gz

thepihub-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

thepihub-0.1.0/NOTICE

@@ -0,0 +1,4 @@
+ThePiHub SDK
+Copyright 2026 Nick Harris
+
+This product includes software developed by Nick Harris (https://thepihub.com).

thepihub-0.1.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: thepihub
+Version: 0.1.0
+Summary: The ThePiHub device SDK: connect a Raspberry Pi to a web dashboard
+Author: ThePiHub
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://thepihub.com
+Keywords: raspberry-pi,iot,dashboard,gpio,webrtc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: websocket-client>=1.9
+Requires-Dist: aiortc>=1.9; platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "aarch64" or platform_machine == "arm64"
+Provides-Extra: webrtc
+Requires-Dist: aiortc>=1.9; (platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "aarch64" or platform_machine == "arm64") and extra == "webrtc"
+Provides-Extra: gpio
+Requires-Dist: gpiozero>=2.0; extra == "gpio"
+Dynamic: license-file
+
+# ThePiHub SDK
+
+Put a Raspberry Pi (or any Linux machine) on a web dashboard without writing any web code. You say what the device has - a temperature to
+show, a button that runs your code, a setting to change, a camera - and ThePiHub draws the dashboard, keeps it live, and works when you
+are away from home. You never lay anything out.
+
+```python
+from pihub import Device, Program
+
+device = Device()
+
+weather = Program(id="weather", name="Weather Station")
+temperature = weather.output(id="temperature", type="Gauge")
+device.add_program(weather)
+device.start()
+
+temperature.set(21.5)     # the gauge on the dashboard now reads 21.5
+```
+
+The first time you run it at a terminal, it prints a link and a code to approve in your browser, and the platform gives the Pi its id; every run after
+that connects straight away. There is nothing to add to your program for that. (A program with no terminal, such as a service started at boot, never
+waits for anyone: `pihub install my_program.py` links the machine and installs the service in one step.)
+
+This package is the **device** side only. It talks to ThePiHub, the hosted dashboard at <https://thepihub.com>, where you need an account.
+It is alpha software (0.1): expect the API to move.
+
+## Install
+
+```bash
+pip install thepihub
+```
+
+The package is called `thepihub`; you `import pihub`, and the command is `pihub`. Python 3.10 or newer, Linux (built for Raspberry Pi OS).
+
+That one command installs everything pip can install. It includes the WebRTC library (aiortc and PyAV), so a browser can connect straight to your device and the
+live **Camera** widget works. (`thepihub[webrtc]`, which older instructions use, still works and means the same.)
+
+Two things come from somewhere else:
+
+- **On a 32-bit Pi** (an original Pi Zero) pip has no ready-made PyAV, so the install leaves the WebRTC library out. Install it with apt instead, and make the virtualenv
+  with `--system-site-packages`: `sudo apt install python3-picamera2 python3-av python3-aiortc`. If it is missing, the device says so in its log when it starts.
+- **The Pi camera and the pin driver** are Raspberry Pi OS packages, not something pip can install: `sudo apt install python3-picamera2` for the camera.
+
+One optional extra: `pip install "thepihub[gpio]"` adds gpiozero, for buttons, LEDs and sensors on the Pi's pins (see GPIO pins below).
+
+## First run
+
+The first time a machine connects, the program prints a link and a code. Open the link while logged in to ThePiHub, approve it, and
+answer `y` in the terminal when it asks you to confirm the account. The device is then yours and the platform gives it its id; every
+later run connects straight away. Nothing is typed onto the Pi but the `y`, so it works headless over SSH.
+
+The saved identity lives in `~/.config/thepihub/config.json`. To set a machine up without running a program, use `pihub setup`.
+The server is `https://thepihub.com` unless you pass `--server` or set `PIHUB_SERVER`.
+
+## How it fits together
+
+```text
+Device            this machine, connected to the platform
+  Program         a named group of things; it becomes one section of the dashboard
+    output        a value you publish              -> Gauge, Status, Chart, Camera
+    command       something the dashboard can run  -> Button
+    setting       a value the dashboard can change -> Toggle, Select, Slider
+```
+
+The **device** says what it has. The **platform** owns the dashboards, the layout and how things look: you choose a widget by name and
+give it a title; you never say where it goes. `group="Lights"` on any component is a hint that it belongs with others.
+
+In the snippets below, `program` is a `Program` you create like the one at the top: declare its outputs, commands and settings, then
+`device.add_program(program)` and `device.start()`, then publish values.
+
+### Outputs: show a value
+
+```python
+from pihub import StringProperty
+
+temperature = weather.output(id="temperature", type="Gauge",
+                             properties=[StringProperty("title", default="Temperature"), StringProperty("units", default="°C")])
+temperature.set(21.5)                                 # one value
+conditions = weather.output(id="conditions", type="Chart")
+conditions.set_values({"temperature": 21.5, "humidity": 60})   # several at once, for a Chart
+```
+
+While the connection is down `set()` does not raise: the latest value is sent when it comes back. Values are only sent to the platform
+while someone is looking at the device (see Direct connections below).
+
+### Commands: run your code from the dashboard
+
+```python
+lights = program.command(id="lights-on", type="Button", properties=[StringProperty("title", default="Lights on")])
+
+@lights.handler
+def pressed(command):
+    switch_the_relay_on()
+    program.info("Lights on")          # a message in the dashboard's notification history
+```
+
+### Settings: a value the dashboard changes and the device remembers
+
+```python
+program.setting("mode", "Select", default="Auto", options=["Auto", "Day", "Night"], title="Mode",
+                apply=lambda value: print("mode is now", value))
+program.setting("brightness", "Slider", default=50, minimum=0, maximum=100, step=5, units="%")
+program.setting("armed", "Toggle", default=False)
+```
+
+The device checks a new value (one out of range is refused), saves it so it survives a restart, publishes it back and then calls `apply`.
+
+### Notifications
+
+`program.info(...)`, `program.warning(...)` and `program.error(...)` appear on the dashboard. A warning stays until someone acknowledges it.
+
+### The Camera
+
+```python
+from pihub.video import best_camera_source
+
+camera = program.output(id="camera", type="Camera")
+camera.use(best_camera_source())     # the Pi's camera (its hardware encoder, or software encoding where there is none); anywhere else, a moving test pattern
+camera.recorder_if_possible()        # adds a Record button when the camera can be recorded; recordings and snapshots are saved on the device
+```
+
+`best_camera_source()` uses the Pi's hardware H.264 encoder where there is one (the Pi Zero to the Pi 4: cheap, about 5% of a Pi 3A+). Where there is none (a Pi 5) it encodes the Pi camera on the CPU with
+libx264 (`SoftwareEncodedCameraSource`: about 40% of one core of a Pi 3A+ at 640x480, and limited to 640x480 until a Pi 5 has been measured). Both hand on H.264 packets, so both stream, take snapshots
+and record (`camera.recorder_if_possible()`, and the Motion Trap). If PyAV has no libx264 it falls back to raw frames that `aiortc` encodes: streaming and snapshots only, no recording. On a computer with no camera it is a moving test pattern;
+on a Raspberry Pi that cannot use its camera it raises `CameraUnavailable` saying what to check, rather than showing a test pattern as if it were the camera. `source.description` says which one it chose.
+
+The picture goes straight from the device to the browser and only while someone is watching, so an idle camera costs nothing.
+
+## Examples
+
+The source repository has small programs to copy, each a single file that connects to the real platform:
+
+- `examples/widget_showcase.py` - every widget the dashboard can draw, in one program (the best place to start copying from)
+- `examples/weather_station.py` - gauges and a chart
+- `examples/greenhouse.py` - two gauges, a button that runs your code, and a warning
+- `examples/birdbox.py` - a Pi camera on the dashboard
+
+and, in `apps/`, complete programs to run as they are: a live bird-box camera, a GPIO panel (a button in, an LED out) and a motion-triggered camera trap.
+
+## Command Line
+
+```bash
+pihub setup                      # link this machine with a code (headless onboarding)
+pihub register TOKEN --device-id ID   # exchange a registration token you already have
+pihub camera setup               # tell this machine what camera it has (a NoIR camera needs this)
+pihub camera show
+pihub install my_program.py      # link this machine if needed, then run the program at boot (one step)
+```
+
+`camera setup` looks at the camera's picture, asks whether it is a **NoIR** camera (no infrared filter) and saves the answer in
+`camera.json` beside `config.json`. A NoIR camera is strongly pink until it is told, because libcamera picks its colour tuning by the
+sensor's name and cannot tell the two apart. Every camera program then uses the answer by itself; `--noir` / `--normal` skip the
+question, and `PiCameraSource(tuning=...)` / `HardwareCameraSource(tuning=...)` override it. Run it with the same `XDG_CONFIG_HOME`
+as a service that uses its own. If nobody runs it, a program that calls `watch_camera_colour(source, device.information.warning)` (the sample app
+does) raises one warning, from Device Information, the first time a real camera's picture is strongly pink; it points at the "Camera is NoIR" toggle there.
+
+`setup` shows a link code, waits while the owner enters it in the web app,
+asks for confirmation, then registers under a platform-issued `deviceId`.
+Afterwards `Device()` (no arguments) loads that id from
+`~/.config/thepihub/config.json`; `Device(id=...)` still works unchanged.
+The server comes from `--server`, else `$PIHUB_SERVER`, else the default.
+
+## Grouping components (a hint)
+
+Any component can say it belongs with others: `output(..., group="Camera")`, `command(...)` and `setting(...)` take the same argument. It is sent as an
+ordinary `group` property and it is only a **hint**: the dashboard shows a section's ungrouped components first, then each group under a small
+heading, and is free to ignore it. Device Information puts the camera's sensor and its settings (Resolution, Frame rate, Bitrate, Camera is NoIR)
+in the group `"Camera"`.
+
+## Device Information (automatic)
+
+A device that built its own connection (after `pihub setup`) also gets a **Device Information** program without any code of its own: it
+is registered first, and shows the Pi model, hostname, OS, SDK version, uptime, CPU usage, temperature, memory, disk, power supply
+(under-voltage or throttling), Wi-Fi signal, and the camera sensor if the device has a camera. Each field appears only if its source is
+on that machine (a plain Linux server gets fewer). The live readings are taken only while someone is viewing the device. It is read-only
+and does not include the serial number or machine id.
+
+```python
+Device()                                              # on (a real device)
+Device(device_information=False)                      # off
+Device(device_information=DeviceInformation(show_ip_address=True))   # on, plus the IP address (off by default)
+```
+
+A device given its own transport (a simulation or a test) does not get it unless you ask.
+
+## Alerts from the machine's vitals
+
+Device Information also **watches the vitals itself**, once a minute, whether or not anyone is viewing (about 0.01% of a Pi Zero W's one core), and
+sends a notification from Device Information when something is wrong: a **warning** and an **error** level for CPU temperature (70 and 80 °C), CPU
+usage (90 and 98%, over five checks in a row, so a brief spike is not an alert), memory (90 and 97%) and disk (85 and 95%). The dashboard asks the user
+to acknowledge both.
+
+It says so **once per episode**, not at every check: a reading that stays high says nothing more, and it must fall a margin below the level before it
+counts as recovered (so a reading hovering around a level cannot flap); recovery is an information notice. The levels are provisional, a first guess.
+
+```python
+DeviceInformation(alerts=False)                       # no alerts
+DeviceInformation(alerts=[AlertRule(...)])            # your own levels (pihub.device_alerts)
+DeviceInformation(alert_seconds=300)                  # check every 5 minutes instead
+```
+
+Any section can run its own periodic work the same way: `section.every(seconds, func)` (before `start()`; first run one interval after start).
+
+## Direct connections (WebRTC)
+
+A browser can connect straight to the device (the WebRTC library is part of the install; see Install). Then every runtime value the device publishes also goes to that browser over
+its DataChannel (a viewer that has just connected is first sent the latest value of everything), and the browser may send commands the same way. A command from a
+viewer reaches your handlers exactly like one from the platform (`@command.handler`), on its own thread, so a slow handler cannot stall the connection. The device only
+accepts one while that viewer's session is alive, and limits it: a burst of 50, then 30 a second per viewer; a viewer is told at once whether it was handed over (202) or
+refused, but not whether it was done.
+
+**The platform only gets a value while it is needed.** With nobody watching, or every viewer connected directly, runtime values are not sent to the platform at all (notifications, registration and
+signalling still are), which is what keeps a device's cost down. A viewer that is still connecting, or has failed, is served through the platform, and the moment that starts the device sends it a
+snapshot of the latest of everything. So the platform's stored copy of a value is only as fresh as the last time it was needed: `GET /devices/{id}/runtime` says "the last value the platform received".
+A device without the extra sends everything to the platform, as it always did. The device and the page each say what they support when the channel opens, and each relies on the direct path only once
+the other has said it can, so an older page (still open in a tab) or an older device is left on the platform's path.
+
+## Staying Connected
+
+A device that built its own connection (the normal case, after `pihub setup`)
+reconnects by itself when the connection drops - a server redeploy, a wifi
+blip, a pulled cable. It retries forever with a growing delay (1s to 60s,
+jittered), and on reconnect re-announces itself and re-sends the latest value
+of each output, so the dashboard is never left empty.
+
+```python
+Device()                      # reconnects (its own connection)
+Device(id="x", transport=t)   # does not (you supplied the transport)
+Device(reconnect=False)       # switched off explicitly
+```
+
+While reconnecting, `Output.set()` does not raise; the latest value is sent
+once the connection is back. A refused login (HTTP 403) is retried with a
+clear error in the log and never given up on - the platform gives the same
+answer for a bad secret and for a rate-limited device.
+
+## GPIO pins (sensors, LEDs, buttons)
+
+Apps drive pins with gpiozero (`pip install "thepihub[gpio]"`). Call `pihub.gpio.prepare_pins()` before making the first gpiozero
+device: gpiozero's driver on current Raspberry Pi OS, `lgpio`, comes from apt (`python3-lgpio`) and does not build under pip, so a
+venv without system packages would otherwise fall back to gpiozero's own driver, which cannot watch a pin for changes on current
+kernels (a `Button` or `DigitalInputDevice` fails with `OSError: [Errno 22]`). `prepare_pins()` lets the venv see the system's
+`lgpio`, as the camera code already does for picamera2.
+
+## Running At Boot (opt-in)
+
+Nothing is installed unless you ask:
+
+```bash
+pihub service install apps/birdbox_live.py [--name N] [--config-home DIR]
+pihub service status [N]
+pihub service uninstall N
+```
+
+It creates a systemd *user* service that restarts the program if it dies.
+To start at boot with nobody logged in, run once:
+`sudo loginctl enable-linger <user>` (the command prints this when needed).
+
+## Licence
+
+Apache License 2.0; see `LICENSE` and `NOTICE`.

thepihub-0.1.0/README.md

@@ -0,0 +1,33 @@
+# ThePiHub SDK
+
+The Python SDK for [ThePiHub](https://thepihub.com): connect a Raspberry Pi (or any Linux machine) to a web dashboard.
+
+```bash
+pip install thepihub
+```
+
+The package is called `thepihub`, you `import pihub`, and the command is `pihub`. **Start with [the SDK guide](sdk/pihub/README.md)**: what it does,
+how to install it, your first run and the concepts, with code.
+
+| Folder | What is in it |
+|---|---|
+| [`sdk/pihub/`](sdk/pihub/) | the SDK itself |
+| [`examples/`](examples/) | small programs to copy, each connecting to the real platform; start with `widget_showcase.py`, which shows every widget |
+| [`apps/`](apps/) | complete programs to run as they are: a live bird-box camera, a GPIO panel, a motion-triggered camera trap |
+| [`tests/`](tests/) | the SDK's tests |
+
+## Working on the SDK
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[gpio]" pytest
+python -m pytest tests -q
+```
+
+Use `python -m pytest`, not bare `pytest`: the tests import the programs in `examples/`.
+
+This repository is a copy of the SDK published from ThePiHub's main repository.
+
+## Licence
+
+Apache License 2.0; see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

thepihub-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thepihub"
+version = "0.1.0"
+description = "The ThePiHub device SDK: connect a Raspberry Pi to a web dashboard"
+authors = [{ name = "ThePiHub" }]
+readme = { file = "sdk/pihub/README.md", content-type = "text/markdown" }
+keywords = ["raspberry-pi", "iot", "dashboard", "gpio", "webrtc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Home Automation",
+    "Topic :: System :: Hardware",
+]
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.10"
+dependencies = [
+    "websocket-client>=1.9",
+    # Direct browser-to-device connections, live video and the Camera widget (aiortc brings PyAV). Part of the plain install, so nobody has to
+    # know to ask for it. Only where PyAV has pip wheels (the allow-list below): on a 32-bit Raspberry Pi pip cannot build it, so the dependency is
+    # skipped there and the apt packages are the route (python3-aiortc python3-av, in a virtualenv made with --system-site-packages). The device
+    # says so at run time if the library is missing.
+    'aiortc>=1.9; platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "aarch64" or platform_machine == "arm64"',
+]
+
+[project.optional-dependencies]
+# Kept so `pip install "thepihub[webrtc]"` (in older docs, hints and posts) still works: it is now the same as the plain install.
+webrtc = ['aiortc>=1.9; platform_machine == "x86_64" or platform_machine == "AMD64" or platform_machine == "aarch64" or platform_machine == "arm64"']
+# Sensors, LEDs and buttons on the GPIO pins (apps/motion_trap.py). Raspberry Pi OS already has it for its own Python;
+# its mock pins let the apps run, and be tested, on any machine.
+gpio = ["gpiozero>=2.0"]
+
+[project.urls]
+Homepage = "https://thepihub.com"
+
+[project.scripts]
+pihub = "pihub.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["sdk"]