{"id":30891151,"url":"https://github.com/hparreao/multiagentsystem-parkingmanagement","last_synced_at":"2026-05-09T02:33:07.326Z","repository":{"id":312777211,"uuid":"1048670402","full_name":"hparreao/multiagentsystem-parkingmanagement","owner":"hparreao","description":"Parking management system using IoT devices in conjunction with an integrated multi-agent system. The objective was to monitor parking space availability in real time, identifying occupancy. Intelligent system capable of analyzing and managing available spaces.","archived":false,"fork":false,"pushed_at":"2025-09-01T22:45:48.000Z","size":348,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-02T00:23:23.379Z","etag":null,"topics":["arduino","iot","mqtt-protocol","multi-agents-system","spade"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hparreao.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T20:39:29.000Z","updated_at":"2025-09-01T22:45:51.000Z","dependencies_parsed_at":"2025-09-02T00:23:29.810Z","dependency_job_id":"1cd48674-fba9-4ba1-9dfa-3db10f5e1d78","html_url":"https://github.com/hparreao/multiagentsystem-parkingmanagement","commit_stats":null,"previous_names":["hparreao/multiagentsystem-parkingmanagement"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hparreao/multiagentsystem-parkingmanagement","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hparreao%2Fmultiagentsystem-parkingmanagement","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hparreao%2Fmultiagentsystem-parkingmanagement/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hparreao%2Fmultiagentsystem-parkingmanagement/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hparreao%2Fmultiagentsystem-parkingmanagement/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hparreao","download_url":"https://codeload.github.com/hparreao/multiagentsystem-parkingmanagement/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hparreao%2Fmultiagentsystem-parkingmanagement/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32804943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["arduino","iot","mqtt-protocol","multi-agents-system","spade"],"created_at":"2025-09-08T18:03:14.838Z","updated_at":"2026-05-09T02:33:07.300Z","avatar_url":"https://github.com/hparreao.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Parking Management System using IoT and Multi-Agent Systems\n\n## Overview\n\nThis project implements a smart parking management system using IoT devices in conjunction with an integrated multi-agent system. The system monitors parking space availability in real-time and identifies occupancy status. It's an intelligent system capable of analyzing and managing available spaces using IoT (Arduino ESP32), Multi-agent systems (SPADE), and MQTT protocol.\n\n## System Architecture\n\nThe system is composed of three main components:\n\n1. **IoT Layer**: ESP32 modules with ultrasonic sensors that detect vehicle presence\n2. **Multi-Agent System Layer**: SPADE-based agents that manage parking spaces and coordinate auctions\n3. **Mobile Application Layer**: React Native app for user interaction and navigation\n\n## Prerequisites\n\n### Hardware Requirements\n- ESP32 modules with HC-SR04 ultrasonic sensors\n- Computer/server for running the agent system\n- Mobile device for the application\n\n### Software Requirements\n- Python 3.8+\n- Node.js 14+\n- React Native CLI\n- Android Studio or Xcode for mobile development\n- MQTT Broker (Mosquitto)\n- Arduino IDE\n\n## Installation\n\n### 1. Setting up the Multi-Agent System (SPADE)\n\n```bash\n# Navigate to the SPADE directory\ncd SPADE\n\n# Install Python dependencies\npip install spade fastapi uvicorn paho-mqtt pydantic\n\n# Run the server\npython main.py\n```\n\nThe server will start on `http://localhost:8000`\n\n### 2. Setting up the ESP32 Modules\n\n1. Open one of the template files in the `ESP32` directory:\n   - `ESP32/parkingmodulescript/parkingmodulescript.ino.template` for single sensor\n   - `ESP32/parkingmodulescript/double/parkingmodulescriptDouble.ino.template` for double sensors\n   - `ESP32/displaymodulescript/displaymodulescript.ino.template` for display module\n   - `ESP32/displaymodulescript/double/displaymodulescriptdouble.ino.template` for double displays\n\n2. Copy the template file to remove the `.template` extension:\n   ```bash\n   cp parkingmodulescript.ino.template parkingmodulescript.ino\n   ```\n\n3. Install required libraries via Library Manager:\n   - ArduinoJson\n   - PubSubClient (for MQTT)\n   - SevSeg (for 7-segment displays)\n\n4. Update the following variables in the code with your actual values:\n   ```cpp\n   // WiFi credentials\n   const char* ssid = \"YOUR_WIFI_SSID\";\n   const char* password = \"YOUR_WIFI_PASSWORD\";\n   \n   // Server IP address\n   const char* server_ip = \"http://YOUR_SERVER_IP:8000/parking_module/ps1\";\n   \n   // MQTT broker IP (for display modules)\n   const char* mqttServer = \"YOUR_MQTT_BROKER_IP\";\n   ```\n\n5. Connect the HC-SR04 sensor(s) to the ESP32:\n   - VCC to 5V\n   - GND to GND\n   - Trig to GPIO 5 (first sensor) / GPIO 27 (second sensor)\n   - Echo to GPIO 18 (first sensor) / GPIO 26 (second sensor)\n\n6. Upload the code to your ESP32 module\n\n### 3. Setting up the Mobile Application\n\n```bash\n# Navigate to the app directory\ncd parking-mobile-app\n\n# Install dependencies\nnpm install\n\n# For iOS\ncd ios \u0026\u0026 pod install \u0026\u0026 cd ..\nnpx react-native run-ios\n\n# For Android\nnpx react-native run-android\n```\n\nBefore running the app, create a `config.json` file in the `parking-mobile-app` directory:\n\n```json\n{\n  \"ip_adress\": \"YOUR_SERVER_IP\"\n}\n```\n\nReplace `YOUR_SERVER_IP` with the IP address of the machine running the SPADE server.\n\n## System Components\n\n### Multi-Agent System\n\nThe system implements a three-level agent hierarchy using SPADE (Smart Python Agent Development Environment), a Python framework for developing multi-agent systems based on XMPP protocol:\n\n1. **Driver Agent**: Represents users looking for parking spaces. This agent communicates with Parking Zone Manager Agents to request parking spots based on user preferences.\n2. **Parking Zone Manager Agent**: Manages a specific parking zone and coordinates between Driver Agents and Parking Spot Module Agents. It conducts auctions among available parking spots and assigns the best match to drivers.\n3. **Parking Spot Module Agent**: Represents individual parking spots and continuously monitors occupancy status through IoT sensors. These agents report real-time data to their respective Parking Zone Manager Agents.\n\n#### Agent Communication and Coordination\n\nThe agents communicate using the XMPP protocol facilitated by SPADE framework. When a driver requests a parking spot:\n\n1. The Driver Agent sends a request to the Parking Zone Manager Agent with preferences (price range, environment, location)\n2. The Parking Zone Manager Agent initiates an auction among Parking Spot Module Agents in the zone\n3. Each Parking Spot Module Agent responds with a bid based on proximity, pricing, and availability\n4. The Parking Zone Manager Agent evaluates the bids and assigns the best matching spot to the driver\n5. The assigned Parking Spot Module Agent confirms the reservation and provides navigation information\n\n### FastAPI Integration\n\nThe SPADE agents are integrated with FastAPI, a modern Python web framework, to expose RESTful endpoints for system interaction:\n\n- **Parking Management Endpoints**: Handle creation and management of parking entities (drivers, managers, zones, spots)\n- **Data Ingestion Endpoints**: Receive real-time sensor data from ESP32 modules\n- **Configuration Endpoints**: Allow system configuration and monitoring\n\nFastAPI provides automatic API documentation through Swagger UI and ReDoc, making it easy to understand and test the system's capabilities.\n\n### MQTT Communication\n\nMQTT protocol is used for lightweight, real-time communication between IoT devices (ESP32 modules) and the system:\n\n- ESP32 modules publish sensor data to MQTT topics\n- Display modules subscribe to MQTT topics to receive parking availability information\n- The SPADE system can also subscribe to MQTT topics for real-time sensor updates\n\n### API Endpoints\n\nThe FastAPI server exposes the following REST API endpoints with automatic documentation available at `/docs`:\n\n#### Parking Preferences\n- `GET /parking_preferences` - Get available parking environments and pricing options\n\n#### Parking Spot Modules\n- `POST /parking_module/{pmodule_id}/{zone_id}` - Create a new parking spot module\n- `POST /parking_module/{pmodule_id}` - Send sonar data from a parking spot\n- `GET /parking_module/{pmodule_id}` - Get parking spot module information\n- `PUT /parking_module/{pmodule_id}` - Update parking spot module information\n\n#### Parking Zones\n- `POST /parking_zone/{zone_id}/{manager_id}` - Create a new parking zone\n- `GET /parking_zone/{zone_id}` - Get parking zone information\n- `PUT /parking_zone/{zone_id}` - Update parking zone information\n\n#### Parking Managers\n- `POST /parking_manager/{manager_id}` - Create a new parking manager\n- `GET /parking_manager/{manager_id}` - Get parking manager information\n- `PUT /parking_manager/{manager_id}` - Update parking manager information\n\n#### Drivers\n- `POST /driver/{driver_id}` - Create a new driver\n- `GET /driver/{driver_id}` - Request a parking spot for a driver\n- `PUT /driver/{driver_id}` - Update driver information\n\n#### System Status\n- `GET /system_status` - Get overall system status and health information\n- `GET /metrics` - Get system metrics for monitoring\n\n### Mobile Application Features\n\nThe React Native mobile application provides a comprehensive interface for users to interact with the parking system:\n\n1. **Interactive Map**: Shows available parking zones with real-time occupancy status\n2. **Parking Search**: Allows users to search for parking spots based on location, price range, and environment preferences\n3. **Spot Selection**: Displays available parking spots with detailed information including pricing, distance, and amenities\n4. **Reservation System**: Enables users to reserve parking spots and receive confirmation\n5. **Turn-by-Turn Navigation**: Provides GPS-based navigation to the assigned parking spot\n6. **Real-time Updates**: Shows live updates on parking spot availability during navigation\n7. **Payment Integration**: Calculates parking costs and processes payments automatically\n8. **Parking History**: Maintains a history of previous parking sessions for user reference\n9. **Notifications**: Sends alerts for reservation confirmations, upcoming expiration, and payment reminders\n\n## Usage\n\n### 1. Starting the System\n\n1. Start the MQTT broker:\n   ```bash\n   mosquitto\n   ```\n\n2. Start the SPADE server:\n   ```bash\n   cd SPADE\n   python main.py\n   ```\n\n3. Power on the ESP32 modules\n\n4. Start the mobile application\n\n### 2. Creating Agents\n\nBefore using the system, you need to create the agents:\n\n1. Create a parking manager:\n   ```bash\n   curl -X POST http://localhost:8000/parking_manager/pm1\n   ```\n\n2. Create a parking zone:\n   ```bash\n   curl -X POST \"http://localhost:8000/parking_zone/pz1/pm1?lat=41.1776\u0026lon=-8.6077\u0026price_hour=2.5\u0026environment=Outdoor\"\n   ```\n\n3. Create a parking spot module:\n   ```bash\n   curl -X POST \"http://localhost:8000/parking_module/ps1/pz1\" -H \"Content-Type: application/json\" -d '{\"lat\": 41.1776, \"lon\": -8.6077}'\n   ```\n\n4. Create a driver:\n   ```bash\n   curl -X POST http://localhost:8000/driver/d1\n   ```\n\n### 3. Using the Mobile App\n\n1. Open the app and select a parking zone from the map\n2. Choose your parking preferences (price and environment)\n3. Confirm the assigned spot\n4. Follow the directions to reach your parking spot\n5. The app will detect when you've arrived using BLE\n\n## System Architecture Diagram\n\n```mermaid\nsequenceDiagram\n    participant D as Driver\n    participant PM as Parking Manager\n    participant PZM as Parking Zone Manager\n    participant PS as Parking Spot\n\n    D-\u003e\u003ePM: Requests parking spot with preferences\n    PM-\u003e\u003ePZM: Checks parking zone that best matches preferences with vacant spots\n    PZM-\u003e\u003ePS: Broadcasts auction start to empty parking spots\n    \n    Note over PS: While auctioning\n    PS--\u003e\u003ePS: Bids\n    PS--\u003e\u003ePS: Broadcasts bidding values\n    PS--\u003e\u003ePZM: Broadcasts end of auction\n    \n    PZM--\u003e\u003ePM: Informs winning spot\n    PM--\u003e\u003eD: Informs user of selected spot and asks for confirmation\n    D--\u003e\u003ePM: Confirms spot\n    PM--\u003e\u003eD: Traces route to parking spot\n    \n    Note over D: Arrives near parking spot\n    \n    D-\u003e\u003ePS: Attempts connection with parking module\n    PS-\u003e\u003ePS: Detects parking spot occupancy and updates value Saves timestamp\n    PS--\u003e\u003ePZM: Informs that is no longer vacant and user ID\n    PZM--\u003e\u003ePM: Informs updated zone occupancy\n    PM--\u003e\u003eD: Informs arrival\n    \n    Note over D: Leaves parking spot\n    \n    PS-\u003e\u003ePS: Detects parking spot occupancy and updates value Calculates time interval\n    PS--\u003e\u003ePZM: Informs that is no longer vacant, user ID and interval\n    PZM--\u003e\u003ePM: Informs updated zone occupancy\n    PM--\u003e\u003eD: Informs payment\n    D--\u003e\u003ePM: Pays\n```\n\n## How It Works\n\n1. **Parking Detection**: ESP32 modules with ultrasonic sensors continuously monitor parking spaces and send data via MQTT to the broker\n2. **Data Processing**: FastAPI server receives sensor data and updates the system state\n3. **Agent Communication**: Parking spot agents inform parking zone managers about vacancy status through XMPP protocol\n4. **User Request**: Driver uses mobile app to request a parking spot with preferences\n5. **Auction System**: Parking zone manager initiates an auction among available parking spots\n6. **Spot Assignment**: The best matching spot is assigned to the driver based on proximity, pricing, and availability\n7. **Navigation**: The mobile app guides the driver to the assigned spot using map directions\n8. **Real-time Updates**: Display modules show real-time parking availability through MQTT\n9. **Payment**: Parking duration and cost are calculated automatically based on arrival and departure times\n\n## Configuration\n\n### Environment Variables\n\nThe system supports the following environment variables for configuration:\n\n- `MQTT_BROKER_HOST`: MQTT broker host (default: localhost)\n- `MQTT_BROKER_PORT`: MQTT broker port (default: 1883)\n- `SERVER_PORT`: FastAPI server port (default: 8000)\n- `SPADE_HOST`: SPADE XMPP server host (default: localhost)\n- `SPADE_PORT`: SPADE XMPP server port (default: 5222)\n- `DATABASE_URL`: Database connection string for persistent storage\n- `DEBUG`: Enable debug logging (default: False)\n- `SECRET_KEY`: Secret key for JWT token generation\n- `ALLOWED_ORIGINS`: Comma-separated list of allowed origins for CORS\n\n### Available Parking Environments\n\nThe system supports multiple parking environment types to match user preferences:\n\n- **Outdoor**: Open-air parking spaces (exposed to weather)\n- **Indoor**: Covered parking spaces (protected from weather)\n- **Both**: Flexible option for users who don't have a strong preference\n- **Indoor-Preferred**: Preference for indoor parking when available, but willing to accept outdoor\n- **Outdoor-Preferred**: Preference for outdoor parking when available, but willing to accept indoor\n\n### Available Pricing Options\n\nPricing options help users filter parking spots based on their budget:\n\n- **Low ($)**: Economical parking options (typically $1-3/hour)\n- **Medium ($)**: Mid-range pricing (typically $3-6/hour)\n- **High ($$)**: Premium parking locations (typically $6+/hour)\n\nPricing is configurable per parking zone and can be adjusted based on demand, time of day, or special events.\n\n## Auction System and Pricing Mechanism\n\nThe parking management system implements a sophisticated auction-based allocation mechanism that ensures fair and efficient distribution of parking spots while optimizing user satisfaction and resource utilization.\n\n### How the Auction System Works\n\n#### 1. Agent Architecture\nThe system employs a three-tiered agent hierarchy:\n- **Driver Agents**: Represent users seeking parking spots with specific preferences\n- **Parking Zone Manager Agents**: Coordinate auctions within designated parking zones\n- **Parking Spot Module Agents**: Monitor individual parking spots and participate in auctions\n\n#### 2. Auction Process Flow\n\n1. **Driver Request Initiation**\n   - Driver Agent submits parking request with preferences:\n     - Location/distance requirements\n     - Price range (Low, Medium, High)\n     - Environment preference (Indoor, Outdoor, Both)\n     - Time constraints\n\n2. **Zone Manager Coordination**\n   - Parking Zone Manager Agent receives the request\n   - Identifies all available Parking Spot Module Agents in the zone\n   - Initiates distributed auction process\n\n3. **Bid Calculation by Spot Agents**\n   Each Parking Spot Module Agent calculates its bid based on:\n   - **Proximity Factor**: Distance from driver's location (closer = more valuable)\n   - **Pricing Model**: Hourly rate configured for the zone\n   - **Availability Status**: Real-time occupancy data from sensors\n   - **Demand Dynamics**: Historical usage patterns and current demand\n\n4. **Bid Formula**\n   The bid calculation follows this formula:\n   ```\n   Bid = (BaseValue × ProximityMultiplier) + (TimeValue × DemandFactor)\n   ```\n   Where:\n   - **BaseValue**: Configured hourly rate for the parking zone\n   - **ProximityMultiplier**: Inverse relationship to distance (0.5-1.0 scale)\n   - **TimeValue**: Estimated parking duration cost\n   - **DemandFactor**: Adjustment based on zone occupancy (0.8-1.2 scale)\n\n5. **Bid Evaluation and Assignment**\n   - Parking Zone Manager Agent collects all bids\n   - Evaluates based on:\n     - Best value proposition for driver\n     - Fair pricing balance\n     - Preference matching\n   - Selects optimal spot and notifies driver\n\n6. **Confirmation and Navigation**\n   - Assigned Parking Spot Module Agent confirms reservation\n   - Navigation data provided to driver via mobile app\n   - Real-time status updates to all system components\n\n### Dynamic Pricing Model\n\n#### Base Pricing Configuration\nPricing is set at the parking zone level and can be adjusted based on:\n- **Location Premium**: City center vs. residential areas\n- **Environment Type**: Indoor spaces typically command higher rates\n- **Amenities**: Covered, secure, or valet services increase value\n- **Time-Based Adjustments**: Peak hours vs. off-peak pricing\n\n#### Real-Time Price Adjustments\nThe system dynamically adjusts prices based on:\n- **Supply and Demand**: High occupancy zones may increase prices\n- **Time of Day**: Business districts more expensive during work hours\n- **Special Events**: Temporary price adjustments for concerts, games, etc.\n- **Seasonal Variations**: Tourist areas adjust for seasonal traffic\n\n### Setting Up Parking Infrastructure\n\n#### Prerequisites for System Operation\nBefore the auction system can function, you must configure the parking infrastructure:\n\n1. **Create Parking Manager**\n   ```bash\n   curl -X POST http://localhost:8000/parking_manager/{manager_id}\n   ```\n   Example:\n   ```bash\n   curl -X POST http://localhost:8000/parking_manager/city_center_manager\n   ```\n\n2. **Create Parking Zones**\n   ```bash\n   curl -X POST \"http://localhost:8000/parking_zone/{zone_id}/{manager_id}?lat={latitude}\u0026lon={longitude}\u0026price_hour={hourly_rate}\u0026environment={environment_type}\"\n   ```\n   Example:\n   ```bash\n   curl -X POST \"http://localhost:8000/parking_zone/downtown_zone/city_center_manager?lat=41.1579\u0026lon=-8.6291\u0026price_hour=3.5\u0026environment=Both\"\n   ```\n\n3. **Create Parking Spots**\n   ```bash\n   curl -X POST \"http://localhost:8000/parking_module/{spot_id}/{zone_id}\" -H \"Content-Type: application/json\" -d '{\"lat\": {latitude}, \"lon\": {longitude}}'\n   ```\n   Example:\n   ```bash\n   curl -X POST \"http://localhost:8000/parking_module/spot_001/downtown_zone\" -H \"Content-Type: application/json\" -d '{\"lat\": 41.1579, \"lon\": -8.6291}'\n   ```\n\n4. **Create Driver Profile**\n   ```bash\n   curl -X POST http://localhost:8000/driver/{driver_id}\n   ```\n   Example:\n   ```bash\n   curl -X POST http://localhost:8000/driver/user_123\n   ```\n\n#### Complete Setup Example\n\n```bash\n# 1. Create parking manager for city center\ncurl -X POST http://localhost:8000/parking_manager/city_center\n\n# 2. Create downtown parking zone (premium location)\ncurl -X POST \"http://localhost:8000/parking_zone/downtown/city_center?lat=41.1579\u0026lon=-8.6291\u0026price_hour=4.0\u0026environment=Both\"\n\n# 3. Create multiple parking spots in downtown zone\ncurl -X POST \"http://localhost:8000/parking_module/dt_001/downtown\" -H \"Content-Type: application/json\" -d '{\"lat\": 41.1579, \"lon\": -8.6291}'\ncurl -X POST \"http://localhost:8000/parking_module/dt_002/downtown\" -H \"Content-Type: application/json\" -d '{\"lat\": 41.1580, \"lon\": -8.6292}'\ncurl -X POST \"http://localhost:8000/parking_module/dt_003/downtown\" -H \"Content-Type: application/json\" -d '{\"lat\": 41.1581, \"lon\": -8.6293}'\n\n# 4. Create residential parking zone (economical)\ncurl -X POST \"http://localhost:8000/parking_zone/residential/city_center?lat=41.1600\u0026lon=-8.6350\u0026price_hour=1.5\u0026environment=Outdoor\"\n\n# 5. Create spots in residential zone\ncurl -X POST \"http://localhost:8000/parking_module/res_001/residential\" -H \"Content-Type: application/json\" -d '{\"lat\": 41.1600, \"lon\": -8.6350}'\ncurl -X POST \"http://localhost:8000/parking_module/res_002/residential\" -H \"Content-Type: application/json\" -d '{\"lat\": 41.1601, \"lon\": -8.6351}'\n\n# 6. Create driver profile\ncurl -X POST http://localhost:8000/driver/driver_001\n```\n\n### Testing the System\n\n#### Prerequisites for Testing\n1. **Hardware Requirements** (for real testing):\n   - ESP32 modules with HC-SR04 ultrasonic sensors\n   - Display modules (optional)\n   - WiFi network access\n   - MQTT broker (Mosquitto) running\n\n2. **Software Requirements**:\n   - Python 3.8+\n   - Node.js 14+\n   - MQTT broker\n   - Arduino IDE (for ESP32 programming)\n\n#### System Startup Sequence\n\n1. **Start MQTT Broker**\n   ```bash\n   mosquitto\n   ```\n\n2. **Start SPADE Server**\n   ```bash\n   cd SPADE\n   python main.py\n   ```\n\n3. **Configure and Deploy ESP32 Modules**\n   - Edit ESP32 code with your WiFi credentials\n   - Set MQTT broker IP address\n   - Upload code to ESP32 modules\n   - Power on hardware\n\n4. **Start Mobile Application** (optional)\n   ```bash\n   cd parking-mobile-app\n   npm start\n   ```\n\n#### Testing Without Hardware\n\nYou can test the auction system without physical hardware by simulating sensor data:\n\n1. **Create Infrastructure** (as shown above)\n2. **Simulate Sensor Data**\n   ```bash\n   # Send occupancy data for a parking spot\n   curl -X POST \"http://localhost:8000/parking_module/dt_001\" -H \"Content-Type: application/json\" -d '{\"sonar_value\": 150}'\n   \n   # Send data for another spot\n   curl -X POST \"http://localhost:8000/parking_module/dt_002\" -H \"Content-Type: application/json\" -d '{\"sonar_value\": 20}'\n   ```\n\n3. **Request Parking Spot**\n   ```bash\n   curl -X GET http://localhost:8000/driver/driver_001\n   ```\n\n#### Monitoring System Performance\n\nThe system provides comprehensive monitoring capabilities:\n\n1. **API Documentation**: Visit `http://localhost:8000/docs` for interactive API testing\n2. **System Metrics**: Access `/metrics` endpoint for Prometheus-formatted metrics\n3. **Health Status**: Check `/system_status` for system health information\n4. **Real-time Updates**: Monitor MQTT topics for sensor data flow\n\n### Benefits of the Auction System\n\n1. **Efficient Allocation**: Spots go to drivers who value them most\n2. **Dynamic Pricing**: Prices adjust automatically to market conditions\n3. **User Satisfaction**: Balances price and location preferences\n4. **Resource Optimization**: Maximizes parking spot utilization\n5. **Scalability**: Distributed agent architecture handles growth\n6. **Fairness**: Transparent bidding process for all users\n\n## Troubleshooting\n\n### Common Issues\n\n1. **ESP32 not connecting to WiFi**: \n   - Check SSID and password in the Arduino code\n   - Verify WiFi network is accessible from ESP32 location\n   - Ensure WiFi credentials don't contain special characters that need escaping\n\n2. **Agents not communicating**: \n   - Ensure the SPADE server is running and accessible\n   - Check XMPP server configuration and connectivity\n   - Verify agent JID credentials are correctly configured\n\n3. **Mobile app not connecting**: \n   - Verify the IP address in config.json\n   - Ensure the FastAPI server is running and accessible from the mobile device\n   - Check firewall settings on the server machine\n\n4. **MQTT connection issues**: \n   - Check that the MQTT broker is running\n   - Verify broker host and port configuration\n   - Ensure network connectivity between devices and broker\n\n5. **Database connection errors**:\n   - Verify DATABASE_URL environment variable is correctly set\n   - Check database server is running and accessible\n   - Ensure proper database credentials and permissions\n\n### Debugging\n\nEnable debug logging by setting the following environment variables:\n\n```bash\nexport DEBUG=1\nexport SPADE_DEBUG=1\nexport MQTT_DEBUG=1\n```\n\nFor detailed agent communication logs, you can also enable XMPP protocol logging:\n\n```bash\nexport XMPP_DEBUG=1\n```\n\n### System Monitoring\n\nThe system provides built-in monitoring endpoints:\n\n- `/metrics`: Prometheus-formatted metrics for system performance\n- `/system_status`: JSON response with system health information\n- `/docs`: Interactive API documentation with testing capabilities\n\nUse these endpoints to diagnose system issues and monitor performance.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by [Hugo Parreão]**\n\n[⭐ Star this project](https://github.com/hparreao/multiagentsystem-parkingmanagement) • [🍴 Fork it](https://github.com/hparreao/multiagentsystem-parkingmanagement) • [📢 Report Issues](https://github.com/hparreao/multiagentsystem-parkingmanagement/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhparreao%2Fmultiagentsystem-parkingmanagement","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhparreao%2Fmultiagentsystem-parkingmanagement","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhparreao%2Fmultiagentsystem-parkingmanagement/lists"}