{"id":29107486,"url":"https://github.com/ferarias/samqtt","last_synced_at":"2026-04-10T01:01:51.471Z","repository":{"id":298349519,"uuid":"999683066","full_name":"ferarias/samqtt","owner":"ferarias","description":"Push your system information into MQTT","archived":false,"fork":false,"pushed_at":"2025-06-20T10:01:57.000Z","size":1409,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-20T11:18:37.044Z","etag":null,"topics":["hassio","home-assistant","iot","linux","mqtt","windows"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ferarias.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/Roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-10T16:15:04.000Z","updated_at":"2025-06-20T10:00:19.000Z","dependencies_parsed_at":"2025-06-10T18:03:46.863Z","dependency_job_id":null,"html_url":"https://github.com/ferarias/samqtt","commit_stats":null,"previous_names":["ferarias/samqtt"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ferarias/samqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferarias%2Fsamqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferarias%2Fsamqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferarias%2Fsamqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferarias%2Fsamqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ferarias","download_url":"https://codeload.github.com/ferarias/samqtt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferarias%2Fsamqtt/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262539077,"owners_count":23325832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hassio","home-assistant","iot","linux","mqtt","windows"],"created_at":"2025-06-29T05:03:58.779Z","updated_at":"2026-04-10T01:01:51.460Z","avatar_url":"https://github.com/ferarias.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SAMQTT\n\n\u003cimg src=\"./docs/icon.png\" width=\"25%\"\u003e\n\nAcronym for **Sensors and Actions bridge to MQTT**, SAMQTT is a background service that exposes system sensors to MQTT so that they can be consumed from IOT applications such as Home Assistant.\nIt can be run in both Windows and Linux.\n\n## Installation\n\nIn both Linux and Windows there's an installer available. Keep these values at hand before installing\n\n- **Hostname**, **port** and (optional) **credentials** for your MQTT broker.\n- A **device identifier**, usually your system/device/machine hostname.\n\n### Windows\n\n1. Get the latest Windows installer from the [releases](https://github.com/ferarias/samqtt/releases/) section: `SamqttSetup.exe`\n2. Double-click the installer and follow the instructions.\n3. That's all. SAMQTT will be installed as a Windows Service.\n4. You can further customize settings in `%LOCALAPPDATA%\\SAMQTT\\samqtt.appsettings.json`\n\n### Linux\n\n#### Automated install\n\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/ferarias/samqtt/master/setup/install-latest-linux.sh)\n```\n\nFollow setup instrucions to configure SAMQTT step by step.\n\n#### Manual install\n\nGet the appropriate Linux latest version from the [releases](https://github.com/ferarias/samqtt/releases/) section.\n\nExample for Linux (X64)\n```\nwget https://github.com/ferarias/samqtt/releases/latest/download/samqtt-linux-x64.tar.gz\ntar xvfz samqtt-linux-x64.tar.gz\ncd ./samqtt\nchmod +x install.sh\n./install.sh\n```\n\nCustomize settings by editing `/etc/mqtt/samqtt.appsettings.json`\n\n#### Uninstall\n\n```bash\n./samqtt/uninstall.sh\n```\n\nif you deleted the original folder, you can re-download and uninstall:\n\n```bash\nwget https://github.com/ferarias/samqtt/releases/latest/download/samqtt-linux-x64.tar.gz\ntar xvfz samqtt-linux-x64.tar.gz\ncd ./samqtt\nchmod +x uninstall.sh\n./uninstall.sh\n```\n\n\n## Architecture\n\nSAMQTT is a .NET 8 Worker Service that bridges system sensors and actions to an MQTT broker, with built-in Home Assistant MQTT Discovery support.\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n    participant HA as Home Assistant\n    participant Broker as MQTT Broker\n    participant SVC as SamqttBackgroundService\n    participant Sensors as Sensor System\n    participant Actions as Action System\n\n    SVC-\u003e\u003eBroker: Connect (TCP/MQTTNet)\n    SVC-\u003e\u003eBroker: Publish LWT (offline, retained)\n    SVC-\u003e\u003eBroker: Publish discovery messages (homeassistant/sensor/…/config)\n    SVC-\u003e\u003eBroker: Publish online status\n    SVC-\u003e\u003eBroker: Subscribe to action command topics\n\n    loop Every polling interval (default 30s)\n        SVC-\u003e\u003eSensors: CollectAsync()\n        Sensors--\u003e\u003eSVC: value\n        SVC-\u003e\u003eBroker: Publish state (samqtt/system_sensor/{device}/{name}/state)\n    end\n\n    HA-\u003e\u003eBroker: Publish command to action topic\n    Broker-\u003e\u003eSVC: Message received\n    SVC-\u003e\u003eActions: HandleAsync(payload)\n    Actions--\u003e\u003eSVC: result (or Unit)\n    SVC-\u003e\u003eBroker: Publish result to state/attributes topics\n```\n\n### Component Overview\n\n```mermaid\ngraph TD\n    subgraph Entry[\"Samqtt (Entry Point)\"]\n        Program[\"Program.cs\\n(DI \u0026 config bootstrap)\"]\n    end\n\n    subgraph App[\"Samqtt.Application\"]\n        BG[\"SamqttBackgroundService\\n(orchestrator)\"]\n        SF[\"SystemSensorFactory\"]\n        AF[\"SystemActionFactory\"]\n        TP[\"TopicProvider\"]\n    end\n\n    subgraph Common[\"Samqtt.Common\"]\n        ISensor[\"ISystemSensor / ISystemMultiSensor\"]\n        IAction[\"ISystemAction\"]\n        IPublisher[\"IMessagePublisher\"]\n        IMqtt[\"IMqttPublisher / IMqttSubscriber\\nIMqttConnectionManager\"]\n    end\n\n    subgraph Broker[\"Samqtt.Broker.Tcp\"]\n        Conn[\"MqttConnector\"]\n        Pub[\"MqttPublisher\"]\n        Sub[\"MqttSubscriber\"]\n        Client[\"MqttTcpClient (MQTTNet)\"]\n    end\n\n    subgraph HA[\"Samqtt.HomeAssistant\"]\n        HAPublisher[\"HomeAssistantPublisher\\n(discovery + state)\"]\n        Fmt[\"SensorValueFormatter\"]\n    end\n\n    subgraph SensorsXP[\"Samqtt.SystemSensors (cross-platform)\"]\n        TS[\"TimestampSensor\"]\n        NA[\"NetworkAvailabilitySensor\"]\n        DMS[\"DriveMultiSensor\\n+ DriveFreeSizeSensor\\n+ DriveTotalSizeSensor\\n+ DrivePercentFreeSizeSensor\"]\n        CPU[\"CpuProcessorTimeSensor (Linux)\"]\n        MEM[\"FreeMemorySensor (Linux)\"]\n    end\n\n    subgraph SensorsWin[\"Samqtt.SystemSensors.Windows\"]\n        CIU[\"ComputerInUseSensor\"]\n    end\n\n    subgraph ActionsXP[\"Samqtt.SystemActions (cross-platform)\"]\n        ProcActions[\"GetProcess / GetProcesses\\nKillProcess / StartProcess\"]\n        SysActions[\"Reboot / Shutdown\\nSuspend / Hibernate (Linux)\"]\n        Notif[\"SendNotification (Linux)\"]\n    end\n\n    subgraph ActionsWin[\"Samqtt.SystemActions.Windows\"]\n        WinActions[\"Hibernate / Suspend\\nShutdown / Reboot\\nToast Notification / Exec\"]\n    end\n\n    Program --\u003e BG\n    BG --\u003e SF \u0026 AF \u0026 IPublisher \u0026 IMqtt\n    SF --\u003e ISensor\n    AF --\u003e IAction\n    IPublisher --\u003e HAPublisher\n    HAPublisher --\u003e Fmt\n    HAPublisher --\u003e IMqtt\n    IMqtt --\u003e Conn \u0026 Pub \u0026 Sub\n    Conn \u0026 Pub \u0026 Sub --\u003e Client\n    ISensor --\u003e TS \u0026 NA \u0026 DMS \u0026 CPU \u0026 MEM \u0026 CIU\n    IAction --\u003e ProcActions \u0026 SysActions \u0026 Notif \u0026 WinActions\n```\n\n### Key Design Principles\n\n- **Factory pattern** — `SystemSensorFactory` and `SystemActionFactory` resolve only enabled sensors/actions from DI at startup, using config keys for lookup.\n- **Multi-sensors** — `ISystemMultiSensor` (e.g., `DriveMultiSensor`) enumerates child identifiers (drive letters/mount points) at runtime; the factory creates a keyed instance per child.\n- **Actions return values or `Unit`** — `SystemAction\u003cT\u003e` where `T = Unit` is fire-and-forget (no state topic published); any other `T` causes the result to be serialized and published to a state and attributes topic.\n- **Home Assistant discovery** — On startup, SAMQTT publishes MQTT discovery payloads to `homeassistant/sensor/{uniqueId}/config` so HA auto-discovers all sensors and actions.\n- **AOT-compatible** — JSON serialization uses source-generated contexts (`SamqttBrokerJsonContext`, `SamqttHomeAssistantJsonContext`) with no runtime reflection.\n- **Cross-platform** — Shared core with platform-specific assemblies registered conditionally (`#if WINDOWS` / `OperatingSystem.IsLinux()`).\n\n### MQTT Topic Schema\n\n| Topic | Purpose |\n|---|---|\n| `samqtt/{device}/status` | Online/offline LWT (retained) |\n| `samqtt/system_sensor/{device}/{name}/state` | Sensor telemetry |\n| `samqtt/system_action/{device}/{name}/request` | Action command (subscribe) |\n| `samqtt/system_action/{device}/{name}/state` | Action result |\n| `samqtt/system_action/{device}/{name}/attributes` | Action JSON attributes |\n| `homeassistant/sensor/{uniqueId}/config` | HA discovery (sensors \u0026 actions) |\n| `homeassistant/binary_sensor/{uniqueId}/config` | HA discovery (binary sensors) |\n\n\n## Sensors\n\nSensors are published to Home Assistant, provided it has the MQTT integration enabled.\n\nState values are published to `samqtt/system_sensor/{device}/{name}/state`, where `{device}` defaults to the machine hostname and is configurable via `DeviceIdentifier` in settings.\n\nSee [Sensors](./docs/Sensors.md) to see the list of available sensors and their topics.\n\n## Actions (Listeners)\n\nSAMQTT subscribes to several topics and, when receiving messages, executes a command or action.\n\nSee [System Actions](./docs/SystemActions.md) to see the list of available actions and their topics.\n\n## Roadmap\n\nSee [this document](./docs/Roadmap.md) to find out what I intend to do in the future.\n\n\n## Setup\n\nSee [this document](./docs/setup.md) to understand how the installers work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fferarias%2Fsamqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fferarias%2Fsamqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fferarias%2Fsamqtt/lists"}