firmngin 0.0.1__tar.gz

firmngin-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firmngin
+
+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.

firmngin-0.0.1/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: firmngin
+Version: 0.0.1
+Summary: Python SDK for building Firmngin device integrations
+Author-email: Firmngin <arif@firmngin.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/firmngin/firmngin-sdk-python
+Project-URL: Repository, https://github.com/firmngin/firmngin-sdk-python
+Project-URL: Issues, https://github.com/firmngin/firmngin-sdk-python/issues
+Project-URL: Changelog, https://github.com/firmngin/firmngin-sdk-python/blob/main/CHANGELOG.md
+Keywords: iot,firmngin,device,sdk,asyncio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiomqtt<3.0,>=2.0
+Requires-Dist: cryptography<44.0,>=42.0
+Provides-Extra: http
+Requires-Dist: httpx<1.0,>=0.27; extra == "http"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: httpx<1.0,>=0.27; extra == "dev"
+Requires-Dist: mypy<2.0,>=1.13; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: testcontainers>=4.7; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Requires-Dist: packaging>=24.2; extra == "dev"
+Dynamic: license-file
+
+# Firmngin Python SDK
+
+<p align="center">
+  <img src="logo.png" alt="Firmngin Logo" width="96"/>
+</p>
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Python SDK for [Firmngin](https://firmngin.dev) device clients, Raspberry Pi. Supports async and sync styles with mTLS, E2EE, entity state, payments, and optional image upload.
+
+**Docs:** [Introduction](https://firmngin.dev/docs/libraries/raspi) — Python SDK menu on [firmngin.dev/docs](https://firmngin.dev/docs)
+
+## Install
+
+```bash
+pip install firmngin
+```
+
+Image upload (optional):
+
+```bash
+pip install firmngin[http]
+```
+
+From Git:
+
+```bash
+pip install git+https://github.com/firmngin/firmngin-sdk-python.git
+```
+
+## Dependencies
+
+Core install uses `aiomqtt` (MQTT) and `cryptography` (TLS + AES-GCM E2EE) only.
+
+## Client vs AsyncClient
+
+|            | `AsyncClient`                   | `Client`                  |
+| ---------- | ------------------------------- | ------------------------- | --- |
+| Style      | `async` / `await`               | Blocking calls            |     |
+| Push state | `await client.push_entity(...)` | `client.push_entity(...)` |
+| Event loop | `await client.run()`            | `client.run()`            |
+
+Both use `ClientConfig.from_file("keys.json")` and support the same events.
+
+## Quickstart
+
+```python
+from firmngin import Client, ClientConfig, Entity, EntityCommand
+
+relay = Entity("relay")
+temperature = Entity("temperature")
+
+with Client(ClientConfig.from_file("keys.json")) as client:
+
+    @client.on_entity(relay)
+    def handle_relay(command: EntityCommand) -> None:
+        print("relay:", command.value)
+
+    client.connect()
+    client.push_entity(temperature, 27.5)
+    client.run()
+```
+
+## Debug mode
+
+Debug is **off** by default — no banner or console output.
+
+```python
+client.set_debug(True)
+client.connect()
+```
+
+With debug enabled, `connect()` prints the Firmngin banner, connection details, and connect/disconnect messages.
+
+## Events
+
+Register handlers with `client.on(Event.X, handler)`:
+
+| Event                    | Payload         | Description            |
+| ------------------------ | --------------- | ---------------------- |
+| `Event.PAYMENT`          | `Payment`       | Payment updates        |
+| `Event.PAYMENT_PENDING`  | `Payment`       | Payment pending        |
+| `Event.PAYMENT_SUCCESS`  | `Payment`       | Payment succeeded      |
+| `Event.INIT`             | `Init`          | Device init payload    |
+| `Event.MERCHANT_STATUS`  | `str`           | Merchant status string |
+| `Event.VERIFICATION`     | `Verification`  | Verification result    |
+| `Event.PIN`              | `Verification`  | PIN display            |
+| `Event.DEVICE_STATUS`    | `DeviceStatus`  | Device lifecycle       |
+| `Event.ENTITY_COMMAND`   | `EntityCommand` | Any entity command     |
+| `Event.ACTIVE_SESSION`   | `ActiveSession` | Active paid session    |
+| `Event.METADATA_PENDING` | `str`           | Raw JSON from `mop`    |
+| `Event.METADATA_EXPIRED` | `str`           | Raw JSON from `moe`    |
+| `Event.METADATA_SUCCESS` | `str`           | Raw JSON from `mos`    |
+| `Event.ERROR`            | `Exception`     | Runtime error          |
+
+Metadata events pass the decrypted payload as a **JSON string** — parse it in your handler.
+
+```python
+import json
+
+@client.on(Event.METADATA_PENDING)
+def on_metadata(raw_json: str) -> None:
+    data = json.loads(raw_json)
+```
+
+Per-entity commands:
+
+```python
+@client.on_entity(Entity("relay"))
+def on_relay(command: EntityCommand) -> None:
+    print(command.value)
+```
+
+## API overview
+
+| Import                         | Role                             |
+| ------------------------------ | -------------------------------- |
+| `AsyncClient`                  | Async device client              |
+| `Client`                       | Sync blocking client             |
+| `ClientConfig`                 | Runtime settings                 |
+| `KeysConfig`                   | `keys.json` loader               |
+| `Event`                        | Event names for `client.on(...)` |
+| `Entity`, `Payment`, `Init`, … | Typed payloads                   |
+
+## Device keys
+
+Download `keys.json` from the Firmngin dashboard. The SDK accepts dashboard fields including `server_fingerprint_bytes` (20-byte Arduino-style fingerprint) and picks the right TLS validation mode automatically.
+
+Never commit real keys. See `keys.json.example`.
+
+## Image upload
+
+```bash
+pip install firmngin[http]
+```
+
+```python
+await client.upload_image(Entity("camera"), "snapshot.jpg")
+```
+
+## Examples
+
+See [`examples/`](examples/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

firmngin-0.0.1/README.md

@@ -0,0 +1,148 @@
+# Firmngin Python SDK
+
+<p align="center">
+  <img src="logo.png" alt="Firmngin Logo" width="96"/>
+</p>
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Python SDK for [Firmngin](https://firmngin.dev) device clients, Raspberry Pi. Supports async and sync styles with mTLS, E2EE, entity state, payments, and optional image upload.
+
+**Docs:** [Introduction](https://firmngin.dev/docs/libraries/raspi) — Python SDK menu on [firmngin.dev/docs](https://firmngin.dev/docs)
+
+## Install
+
+```bash
+pip install firmngin
+```
+
+Image upload (optional):
+
+```bash
+pip install firmngin[http]
+```
+
+From Git:
+
+```bash
+pip install git+https://github.com/firmngin/firmngin-sdk-python.git
+```
+
+## Dependencies
+
+Core install uses `aiomqtt` (MQTT) and `cryptography` (TLS + AES-GCM E2EE) only.
+
+## Client vs AsyncClient
+
+|            | `AsyncClient`                   | `Client`                  |
+| ---------- | ------------------------------- | ------------------------- | --- |
+| Style      | `async` / `await`               | Blocking calls            |     |
+| Push state | `await client.push_entity(...)` | `client.push_entity(...)` |
+| Event loop | `await client.run()`            | `client.run()`            |
+
+Both use `ClientConfig.from_file("keys.json")` and support the same events.
+
+## Quickstart
+
+```python
+from firmngin import Client, ClientConfig, Entity, EntityCommand
+
+relay = Entity("relay")
+temperature = Entity("temperature")
+
+with Client(ClientConfig.from_file("keys.json")) as client:
+
+    @client.on_entity(relay)
+    def handle_relay(command: EntityCommand) -> None:
+        print("relay:", command.value)
+
+    client.connect()
+    client.push_entity(temperature, 27.5)
+    client.run()
+```
+
+## Debug mode
+
+Debug is **off** by default — no banner or console output.
+
+```python
+client.set_debug(True)
+client.connect()
+```
+
+With debug enabled, `connect()` prints the Firmngin banner, connection details, and connect/disconnect messages.
+
+## Events
+
+Register handlers with `client.on(Event.X, handler)`:
+
+| Event                    | Payload         | Description            |
+| ------------------------ | --------------- | ---------------------- |
+| `Event.PAYMENT`          | `Payment`       | Payment updates        |
+| `Event.PAYMENT_PENDING`  | `Payment`       | Payment pending        |
+| `Event.PAYMENT_SUCCESS`  | `Payment`       | Payment succeeded      |
+| `Event.INIT`             | `Init`          | Device init payload    |
+| `Event.MERCHANT_STATUS`  | `str`           | Merchant status string |
+| `Event.VERIFICATION`     | `Verification`  | Verification result    |
+| `Event.PIN`              | `Verification`  | PIN display            |
+| `Event.DEVICE_STATUS`    | `DeviceStatus`  | Device lifecycle       |
+| `Event.ENTITY_COMMAND`   | `EntityCommand` | Any entity command     |
+| `Event.ACTIVE_SESSION`   | `ActiveSession` | Active paid session    |
+| `Event.METADATA_PENDING` | `str`           | Raw JSON from `mop`    |
+| `Event.METADATA_EXPIRED` | `str`           | Raw JSON from `moe`    |
+| `Event.METADATA_SUCCESS` | `str`           | Raw JSON from `mos`    |
+| `Event.ERROR`            | `Exception`     | Runtime error          |
+
+Metadata events pass the decrypted payload as a **JSON string** — parse it in your handler.
+
+```python
+import json
+
+@client.on(Event.METADATA_PENDING)
+def on_metadata(raw_json: str) -> None:
+    data = json.loads(raw_json)
+```
+
+Per-entity commands:
+
+```python
+@client.on_entity(Entity("relay"))
+def on_relay(command: EntityCommand) -> None:
+    print(command.value)
+```
+
+## API overview
+
+| Import                         | Role                             |
+| ------------------------------ | -------------------------------- |
+| `AsyncClient`                  | Async device client              |
+| `Client`                       | Sync blocking client             |
+| `ClientConfig`                 | Runtime settings                 |
+| `KeysConfig`                   | `keys.json` loader               |
+| `Event`                        | Event names for `client.on(...)` |
+| `Entity`, `Payment`, `Init`, … | Typed payloads                   |
+
+## Device keys
+
+Download `keys.json` from the Firmngin dashboard. The SDK accepts dashboard fields including `server_fingerprint_bytes` (20-byte Arduino-style fingerprint) and picks the right TLS validation mode automatically.
+
+Never commit real keys. See `keys.json.example`.
+
+## Image upload
+
+```bash
+pip install firmngin[http]
+```
+
+```python
+await client.upload_image(Entity("camera"), "snapshot.jpg")
+```
+
+## Examples
+
+See [`examples/`](examples/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

firmngin-0.0.1/pyproject.toml

@@ -0,0 +1,191 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "firmngin"
+version = "0.0.1"
+description = "Python SDK for building Firmngin device integrations"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    {name = "Firmngin", email = "arif@firmngin.dev"},
+]
+keywords = [
+    "iot",
+    "firmngin",
+    "device",
+    "sdk",
+    "asyncio",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications",
+    "Topic :: Software Development :: Embedded Systems",
+    "Topic :: System :: Hardware",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiomqtt>=2.0,<3.0",
+    "cryptography>=42.0,<44.0",
+]
+
+[project.optional-dependencies]
+http = [
+    "httpx>=0.27,<1.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "respx>=0.21",
+    "httpx>=0.27,<1.0",
+    # Pinned to <2 because mypy 2.x dropped support for python_version = "3.9".
+    # We target 3.9 runtime; once we raise minimum to 3.10, bump to mypy 2.x.
+    "mypy>=1.13,<2.0",
+    "ruff>=0.5",
+    "testcontainers>=4.7",
+    "pip-audit>=2.7",
+    "bandit>=1.7",
+    "build>=1.2",
+    "twine>=6.1",
+    "packaging>=24.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/firmngin/firmngin-sdk-python"
+Repository = "https://github.com/firmngin/firmngin-sdk-python"
+Issues = "https://github.com/firmngin/firmngin-sdk-python/issues"
+Changelog = "https://github.com/firmngin/firmngin-sdk-python/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+license-files = ["LICENSE"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["firmngin*"]
+
+[tool.setuptools.package-data]
+firmngin = ["py.typed"]
+
+# --------------------------------------------------------------------------------------
+# Ruff — lint + format (replaces black + isort + flake8)
+# --------------------------------------------------------------------------------------
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+extend-exclude = [
+    ".venv",
+    "build",
+    "dist",
+    ".tox",
+]
+
+[tool.ruff.lint]
+# Strict-ish default; relax if needed with explicit per-file ignores.
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "N",   # pep8-naming
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "SIM", # flake8-simplify
+    "TID", # flake8-tidy-imports
+    "PL",  # pylint
+    "RUF", # ruff-specific
+]
+ignore = [
+    "PLR0913", # too-many-arguments — frequent in async APIs, not a bug
+    "PLR2004", # magic value — fine for protocol constants
+    "E501",    # line length handled by formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLR0913", "PLR0915", "PLR2004", "N802", "N803", "N806", "S101", "B011"]
+"examples/*" = ["TID252", "N802", "N803"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["firmngin", "tests"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+# --------------------------------------------------------------------------------------
+# Mypy — strict typing on the public package
+# --------------------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = "httpx"
+ignore_missing_imports = true
+
+# Third-party libs without full type stubs — added per-module as we import them
+# in later phases. Keep this list empty for Phase 0; expand as needed.
+
+# --------------------------------------------------------------------------------------
+# Pytest
+# --------------------------------------------------------------------------------------
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--showlocals",
+    "--tb=short",
+]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "integration: integration tests requiring a real broker (deselect with -m 'not integration')",
+    "slow: slow tests (deselect with -m 'not slow')",
+]
+
+# --------------------------------------------------------------------------------------
+# Coverage
+# --------------------------------------------------------------------------------------
+[tool.coverage.run]
+branch = true
+source = ["src/firmngin"]
+omit = ["*/tests/*", "*/examples/*"]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "\\.\\.\\.",
+]
+fail_under = 90

firmngin-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

firmngin-0.0.1/src/firmngin/__init__.py

@@ -0,0 +1,42 @@
+"""Firmngin Python SDK."""
+
+from firmngin._version import __version__
+from firmngin.builders import BatchState, LocationUpdate
+from firmngin.client import AsyncClient, Event, FirmnginClient
+from firmngin.client_sync import Client, SyncClient, SyncFirmnginClient
+from firmngin.config import ClientConfig, KeysConfig, ValidationMode
+from firmngin.payloads import (
+    DeviceStatus,
+    Entity,
+    EntityCommand,
+    EntityValue,
+    Init,
+    Payment,
+    Usage,
+    Verification,
+)
+from firmngin.session import ActiveSession
+
+__all__ = [
+    "ActiveSession",
+    "AsyncClient",
+    "BatchState",
+    "Client",
+    "ClientConfig",
+    "DeviceStatus",
+    "Entity",
+    "EntityCommand",
+    "EntityValue",
+    "Event",
+    "FirmnginClient",
+    "Init",
+    "KeysConfig",
+    "LocationUpdate",
+    "Payment",
+    "Usage",
+    "SyncClient",
+    "SyncFirmnginClient",
+    "ValidationMode",
+    "Verification",
+    "__version__",
+]

firmngin-0.0.1/src/firmngin/_banner.py

@@ -0,0 +1,25 @@
+"""Startup banner for Firmngin device clients."""
+
+from __future__ import annotations
+
+_BANNER_LINES = (
+    "",
+    r"   __ _                            _            _            ",
+    r"  / _(_)                          (_)          | |           ",
+    r" | |_ _ _ __ _ __ ___  _ __   __ _ _ _ __    __| | _____   __",
+    r" |  _| | '__| '_ ` _ \| '_ \ / _` | | '_ \  / _` |/ _ \ \ / /",
+    r" | | | | |  | | | | | | | | | (_| | | | | || (_| |  __/\ V / ",
+    r" |_| |_|_|  |_| |_| |_|_| |_|\__, |_|_| |_(_)__,_|\___| \_/  ",
+    r"                              __/ |                          ",
+    r" The AIoT Platform           |___/                           ",
+)
+
+
+def print_startup_banner(version: str) -> None:
+    for line in _BANNER_LINES:
+        print(line)
+    print(f" Version: {version}")
+    print()
+
+
+__all__ = ["print_startup_banner"]