# README
IoT Agent
A modular and configurable IoT agent designed to support a variety of services and run on any Unix-based system. It enables secure communication and interaction with an MQTT backend. You can use IOT-Cloud or build your own MQTT backend.
š Pre-Alpha Discussions: Here
š Features
āļø Modular service-based architecture
āļø Secure communication via MQTT
āļø Supports multiple services (Registration, Metrics, SSH, Updates, etc.)
āļø Configurable through YAML files
āļø Designed for low-resource IoT devices
š Installation & Setup
1. Clone the Repository
git clone https://github.com/BenMeehan/iot-agent.git
cd iot-agent
2. Configure the Agent
Modify config/config.yaml
to suit your needs. Ensure correct MQTT broker settings and service configurations.
3. Run the Agent
go run cmd/agent/main.go
š§ Configuration
The agent is configured via config/config.yaml
. Each service has its own parameters, such as MQTT topics, intervals, and authentication details.
For detailed service-specific documentation, check the /docs
folder.
š TODO
- Cross-Compilation: Easier compilation for different architectures
š Architecture
āļø Adding a New Service
-
Update Configuration
- Add necessary configurations in
config/config.yaml
.
- Add necessary configurations in
-
Create Service Logic
- Add a new file in
internal/services
(e.g.,new_service.go
). - Implement the service logic similar to existing services (e.g.,
heartbeat_service.go
).
- Add a new file in
š Services Overview
š Detailed service documentation is available in the /docs
directory.
1ļøā£ Registration Service
š¹ Handles secure device registration via MQTT using JWT authentication.
š¹ Implements exponential backoff for retries.
2ļøā£ Heartbeat Service
š¹ Sends periodic heartbeat messages to indicate device activity.
3ļøā£ Metrics Service
š¹ Collects system metrics (CPU, memory, disk usage) and sends them via MQTT.
4ļøā£ Command Service
š¹ Executes commands on the IoT device and publishes output via MQTT.
5ļøā£ Geolocation Service
š¹ Retrieves device location via GPS or Google Geolocation API.
6ļøā£ SSH Service
š¹ Establishes a secure reverse SSH tunnel for remote access.
7ļøā£ Update Service
š¹ Handles OTA (Over-the-Air) updates for firmware or software.
š Code Guidelines
1. Naming Conventions
- Use camel case for variables/constants (e.g.,
deviceId
,maxRetries
). - Use snake case for files/folders (e.g.,
heartbeat_service.go
).
2. Code Style
- Keep code clean and readable.
- Comments should explain why something is done, not just what it does.
3. Logging
- Use structured logs with relevant context.
- Ensure logs are useful for debugging.
š¤ Contributing
Contributions are welcome! To contribute:
- Fork the repository
- Create a feature branch (
feature/your-feature-name
) - Commit your changes (
git commit -m "Added new feature"
) - Push to your branch
- Open a Pull Request
This project is under Apache License 2.0