{"id":23536208,"url":"https://github.com/nhathout/pira","last_synced_at":"2026-05-02T02:34:54.729Z","repository":{"id":269380149,"uuid":"905607941","full_name":"nhathout/PIRA","owner":"nhathout","description":"Personal Indoor Robot Assistant.","archived":false,"fork":false,"pushed_at":"2024-12-23T06:16:27.000Z","size":1390,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-17T06:41:53.293Z","etag":null,"topics":["ir-sensors","obstacle-avoidance","obstacle-avoidance-robot","optitrack","robot","streamlit"],"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/nhathout.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":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-19T07:06:34.000Z","updated_at":"2024-12-23T06:16:31.000Z","dependencies_parsed_at":"2024-12-23T07:30:12.820Z","dependency_job_id":null,"html_url":"https://github.com/nhathout/PIRA","commit_stats":null,"previous_names":["nhathout/pira"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nhathout%2FPIRA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nhathout%2FPIRA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nhathout%2FPIRA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nhathout%2FPIRA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nhathout","download_url":"https://codeload.github.com/nhathout/PIRA/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254240216,"owners_count":22037841,"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":["ir-sensors","obstacle-avoidance","obstacle-avoidance-robot","optitrack","robot","streamlit"],"created_at":"2024-12-26T02:17:28.065Z","updated_at":"2026-05-02T02:34:54.669Z","avatar_url":"https://github.com/nhathout.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PIRA - Personal Indoor Robot Assistant\n\n**Date:** December 10, 2024\n\n## Overview\nThis project centers on building a personal indoor robot assistant capable of autonomous navigation and real-time obstacle avoidance in an indoor environment. The system supports both fully autonomous waypoint traversal, guided by an indoor positioning system (Optitrack), and manual driving via WASD inputs. A Node.js server coordinates data exchange among multiple robots on the same Wi-Fi network, while a Streamlit interface provides a live 2D visualization of each robot’s position and waypoints. TingoDB stores positional data for real-time monitoring and historical analysis.\n\n---\n\n## Key Features\n\n- **Autonomous Navigation**  \n  - Uses feedback control (PID) to follow predefined waypoints within a ±10cm margin.  \n  - Leverages Optitrack for accurate (x, z, θ) positioning updates.\n\n- **Obstacle Avoidance**  \n  - Sharp-IR sensors detect nearby obstacles.  \n  - Priority-based control ensures the robot diverts from its path to avoid collisions.\n\n- **Multimodal Control**  \n  - **Automatic Mode:** Robot autonomously moves between waypoints, using PID corrections and sensor feedback.  \n  - **Manual (WASD) Mode:** Users can override autonomy and steer the robot via keyboard inputs sent through the Node.js server.\n\n- **Real-time Monitoring \u0026 Visualization**  \n  - Live 2D graphics in a Streamlit dashboard show robot positions, waypoints, and obstacle triggers.  \n  - TingoDB logs each position update, enabling real-time data tracking and simple analytics.\n\n- **Scalable Networking**  \n  - Node.js server handles multiple robots simultaneously.  \n  - Each robot maintains continuous Wi-Fi connectivity and exchanges UDP messages for minimal overhead.\n\n---\n\n## System Requirements and Architecture\n\n### Hardware Integration\n1. **ESP32 Microcontroller**  \n   - Central controller for motor actuation, sensor readings, and Wi-Fi communication.  \n   - Configured with FreeRTOS tasks to manage concurrency.\n\n2. **Sharp-IR Sensor**  \n   - Analog distance sensor (ADC-based) providing obstacle detection.  \n   - Calibrated to detect objects within a configurable distance threshold.\n\n3. **Optitrack System**  \n   - Provides precise localization of the robot in indoor environments.  \n   - Streamed position/heading data is used for navigation and control.\n\n4. **Motors \u0026 Driver**  \n   - Controlled via PWM (LEDC on the ESP32) for linear and rotational motion.  \n   - Ensures fine-tuned speed adjustments, crucial for PID feedback loops.\n\n5. **Wi-Fi Networking**  \n   - All robots connect to the same local network.  \n   - UDP sockets facilitate efficient real-time messaging between robots and the server.\n\n---\n\n## Solution Design\n\n### Core Application Initialization (app_main)\n- **Wi-Fi Setup:**  \n  Configures SSID, password, and reconnect parameters. Ensures each robot remains online to receive commands and transmit location updates.\n\n- **Motor Control Configuration:**  \n  Initializes PWM channels (LEDC) for forward, backward, turning, and stopping states.\n\n- **Sharp IR Sensor \u0026 ADC:**  \n  Sets up an ADC channel to read distance values. Calibrates the voltage-to-distance curve for obstacle detection.\n\n- **Timers and Tasks Setup:**  \n  Creates periodic timers for tasks like checking sensor readings, computing PID corrections, and sending position requests.\n\n### Key FreeRTOS Tasks\n\n1. **Network Listener Task**  \n   - Listens for UDP messages (e.g., WASD commands, mode toggles, new waypoint definitions).  \n   - Parses incoming data and updates the robot’s operating state (manual vs. autonomous).  \n   - In autonomous mode, processes next waypoint instructions and speed/direction updates.\n\n2. **Request Location Task (request_location)**  \n   - Periodically sends requests to the Node.js server to obtain the robot’s latest position from Optitrack.  \n   - Updates internal state with (x, z, θ) data for use in PID navigation.  \n   - In autonomous mode, computes the heading/distance to the target waypoint.\n\n3. **Motor Control Task**  \n   - Implements a finite state machine (FSM) for movement: `STATE_MOVE_FORWARD`, `STATE_GO_LEFT`, `STATE_GO_RIGHT`, `STATE_STOP`, etc.  \n   - Adjusts PWM duty cycle based on commands from manual input or PID output.  \n   - Manages turning maneuvers and speed scaling for smooth directional changes.\n\n4. **Obstacle Detection Task**  \n   - Continuously reads Sharp-IR sensor values.  \n   - Triggers immediate avoidance behavior if an obstacle is within the critical threshold.  \n   - Temporarily overrides PID path corrections, prioritizing collision prevention.\n\n5. **Autonomous Navigation \u0026 PID**  \n   - Uses proportional, integral, and derivative terms to stabilize heading toward each waypoint.  \n   - Computes heading error (difference between current angle and target angle).  \n   - Dynamically adjusts motor outputs to minimize error while respecting obstacle avoidance triggers.\n\n---\n\n## Network Communication\n\n### Node.js Server\n- **Command Dispatch:**  \n  Receives manual drive commands (WASD) or mode-change signals from a user interface.  \n  Broadcasts these instructions to the specified robot via UDP.\n\n- **Location Management \u0026 TingoDB:**  \n  Aggregates position reports from each robot.  \n  Stores each robot’s (x, z, θ) data in TingoDB for real-time updates and historical lookback.\n\n- **Streamlit Dashboard:**  \n  Polls the database, displaying a 2D map of robots, waypoints, and obstacles.  \n  Allows users to observe multiple robots’ positions and statuses simultaneously.\n\n### UDP Protocol\n- Minimal overhead ensures fast, near-real-time communication for multi-robot scenarios.  \n- Periodic acknowledgment or keep-alive checks maintain consistent connectivity.\n\n---\n\n## Results\n\n- **Consistent Waypoint Navigation:**  \n  Achieved ±10cm accuracy in autonomous mode, leveraging PID corrections and accurate Optitrack data.\n\n- **Effective Obstacle Avoidance:**  \n  Sharp-IR sensor integration prevented collisions, with priority-based logic overriding normal path following as needed.\n\n- **User-Friendly Remote Control:**  \n  Seamless toggling between manual (WASD) commands and full autonomy.  \n  Real-time feedback through the Node.js server and the Streamlit interface.\n\n- **Scalable Multi-Robot Setup:**  \n  Multiple robot assistants operate in parallel, each with independent control loops but centralized data coordination.\n\n---\n\n## Challenges\n\n- **Real-Time Communication \u0026 Coordination:**  \n  Managing concurrent UDP messages for multiple robots without packet collisions or data delays.\n\n- **PID Tuning:**  \n  Ensuring smooth path tracking without oscillations required iterative parameter tuning under varying speeds and load conditions.\n\n- **Sensor Calibration:**  \n  The Sharp-IR sensor’s accuracy can fluctuate based on environment and lighting, necessitating consistent recalibration.\n\n---\n\n## Potential Improvements\n\n- **Interrupt-Driven Sensor Reads:**  \n  Using hardware interrupts instead of polling for sharper real-time responsiveness.\n\n- **Path Planning Algorithms:**  \n  Incorporate more advanced planning (e.g., A*, RRT*) for complex obstacle layouts.\n\n- **3D Visualization or SLAM:**  \n  Extend the system to build a richer map of the environment for real-time 3D tracking.\n\n- **Security Enhancements:**  \n  Implement encryption for UDP messages or advanced authentication methods for sensitive deployments.\n\n---\n\n## Demonstrations\n\n- [**Functionality Demo Video**](https://drive.google.com/file/d/1VPvRS4MaWk1iu6lj2RG2DcL4Mfvxja_7/view?usp=sharing)  \n- [**Design Walkthrough Video**](https://drive.google.com/file/d/1IIHNn9ovCAJhkweRPx5khYDsRs2hRVlT/view?usp=sharing)\n\n## Appendix\nCircuit diagram:\n\n![circuit-diagram](public/Quest5-circuit-diagram.jpg)\n\nThis personal indoor robot assistant project brings together embedded systems design, real-time networking, and automated control to achieve robust waypoint navigation and obstacle avoidance. Its flexible architecture, modular codebase, and user-friendly interface make it a compelling foundation for further robotic exploration and innovation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhathout%2Fpira","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnhathout%2Fpira","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhathout%2Fpira/lists"}