{"id":15063420,"url":"https://github.com/benmeehan/iot-agent","last_synced_at":"2025-08-20T12:34:30.208Z","repository":{"id":255837513,"uuid":"853214672","full_name":"BenMeehan/iot-agent","owner":"BenMeehan","description":"A modular and configurable IoT agent designed to collect and transmit device data over MQTT, supporting a variety of services for Unix-based systems.","archived":false,"fork":false,"pushed_at":"2024-11-09T13:47:39.000Z","size":1060,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-16T06:43:29.787Z","etag":null,"topics":["agent","golang","iot","iot-platform","mqtt","unix-like"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BenMeehan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-06T08:01:57.000Z","updated_at":"2024-10-30T04:39:39.000Z","dependencies_parsed_at":"2024-10-29T16:47:51.092Z","dependency_job_id":null,"html_url":"https://github.com/BenMeehan/iot-agent","commit_stats":null,"previous_names":["benmeehan/iot-agent"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BenMeehan%2Fiot-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BenMeehan%2Fiot-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BenMeehan%2Fiot-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BenMeehan%2Fiot-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BenMeehan","download_url":"https://codeload.github.com/BenMeehan/iot-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225741257,"owners_count":17516894,"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":["agent","golang","iot","iot-platform","mqtt","unix-like"],"created_at":"2024-09-24T23:56:34.365Z","updated_at":"2025-07-11T16:30:52.815Z","avatar_url":"https://github.com/BenMeehan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IoT Agent\r\n\r\nA modular and configurable **IoT agent** designed to support a variety of services and operate on any Unix-based system. It enables secure communication and interaction with an MQTT backend. You can use [IOT-Cloud](https://github.com/BenMeehan/iot-cloud) or build your own MQTT backend.\r\n\r\n## Features\r\n\r\n- Modular service-based architecture  \r\n- Secure communication via MQTT  \r\n- Supports multiple services (Registration, Metrics, SSH, Updates, etc.)  \r\n- Configurable through YAML files  \r\n- Designed for low-resource IoT devices  \r\n\r\n## Installation \u0026 Setup\r\n\r\n### 1. Clone the Repository\r\n\r\n```sh\r\ngit clone https://github.com/BenMeehan/iot-agent.git\r\ncd iot-agent\r\n```\r\n\r\n### 2. Configure the Agent\r\n\r\nModify `config/config.yaml` to suit your requirements. Ensure correct MQTT broker settings and service configurations.\r\n\r\n### 3. Run the Agent\r\n\r\n```sh\r\ngo run cmd/agent/main.go\r\n```\r\n\r\n## Configuration\r\n\r\nThe agent is configured via `config/config.yaml`. Each service has its own parameters, such as MQTT topics, intervals, and authentication details.\r\n\r\nFor detailed service-specific documentation, refer to the [`/docs`](./docs/) folder.\r\n\r\n## Roadmap\r\n\r\n- [ ] **Cross-Compilation**: Simplify compilation for different architectures.\r\n\r\n## Architecture\r\n\r\n![arch.png](./.github/images/agent-arch.png)\r\n\r\n## Adding a New Service\r\n\r\nTo add a new service, follow these steps:\r\n\r\n1. **Update Configuration**  \r\n   - Add the necessary configurations in `config/config.yaml`.\r\n\r\n2. **Create Service Logic**  \r\n   - Add a new file in `internal/services` (e.g., `new_service.go`).  \r\n   - Implement the service logic, following the pattern of existing services (e.g., `heartbeat_service.go`).\r\n\r\n## Middlewares Overview\r\n\r\n### 1. Authentication Middlware\r\n- Handles the JWT based authentication at a central place.\r\n- Retries Auth requests and refreshes expired tokens.\r\n\r\n## Services Overview\r\n\r\nDetailed service documentation is available in the [`/docs`](./docs/) directory.\r\n\r\n### 1. Registration Service\r\n- Handles secure device registration via MQTT using JWT authentication.\r\n- Implements exponential backoff for retries.\r\n\r\n### 2. Heartbeat Service\r\n- Sends periodic heartbeat messages to indicate device activity.\r\n\r\n### 3. Metrics Service\r\n- Collects system metrics (CPU, memory, disk usage, network in/out, process metrics) and sends them via MQTT.\r\n\r\n### 4. Command Service\r\n- Executes commands on the IoT device and publishes output via MQTT.\r\n\r\n### 5. Geolocation Service\r\n- Retrieves device location via GPS or Google Geolocation API.\r\n\r\n### 6. SSH Service\r\n- Establishes a secure reverse SSH tunnel for remote access.\r\n\r\n### 7. Update Service\r\n- Handles OTA (Over-the-Air) updates for firmware or software.\r\n\r\n## Code Guidelines\r\n\r\n### 1. Naming Conventions\r\n- Use camel case for variables and constants (e.g., `deviceId`, `maxRetries`).\r\n- Use snake case for files and folders (e.g., `heartbeat_service.go`).\r\n\r\n### 2. Code Style\r\n- Maintain clean and readable code.\r\n- Comments should explain **why** something is done, not just **what** it does.\r\n\r\n### 3. Logging\r\n- Use structured logs with relevant context.\r\n- Ensure logs provide meaningful information for debugging.\r\n\r\n---\r\n\r\nThis project is licensed under the [Non-Commercial Software License 1.0](./LICENSE.md).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenmeehan%2Fiot-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenmeehan%2Fiot-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenmeehan%2Fiot-agent/lists"}