{"id":28350940,"url":"https://github.com/seeed-solution/solution_indoorpositioning_h5","last_synced_at":"2026-02-15T22:32:41.356Z","repository":{"id":291935166,"uuid":"979187439","full_name":"Seeed-Solution/Solution_IndoorPositioning_H5","owner":"Seeed-Solution","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-29T07:39:30.000Z","size":13761,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-11T22:19:09.145Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Vue","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/Seeed-Solution.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,"zenodo":null}},"created_at":"2025-05-07T06:11:59.000Z","updated_at":"2025-06-20T09:02:26.000Z","dependencies_parsed_at":"2025-05-19T04:39:53.964Z","dependency_job_id":null,"html_url":"https://github.com/Seeed-Solution/Solution_IndoorPositioning_H5","commit_stats":null,"previous_names":["suharvest/beacon_posistion_with_tracker","seeed-solution/solution_indoorpositioning_h5"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Seeed-Solution/Solution_IndoorPositioning_H5","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seeed-Solution%2FSolution_IndoorPositioning_H5","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seeed-Solution%2FSolution_IndoorPositioning_H5/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seeed-Solution%2FSolution_IndoorPositioning_H5/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seeed-Solution%2FSolution_IndoorPositioning_H5/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Seeed-Solution","download_url":"https://codeload.github.com/Seeed-Solution/Solution_IndoorPositioning_H5/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seeed-Solution%2FSolution_IndoorPositioning_H5/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29490897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T19:29:10.908Z","status":"ssl_error","status_checked_at":"2026-02-15T19:29:10.419Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2025-05-27T22:08:47.053Z","updated_at":"2026-02-15T22:32:41.335Z","avatar_url":"https://github.com/Seeed-Solution.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beacon Positioning System\n\nThis system tracks devices using BLE beacon signals, visualizing their positions on a web-based map. It supports iBeacon-compatible devices and SenseCAP T1000 trackers. It offers two main modes:\n1.  **Tracker Mode:** Server-side positioning of multiple dedicated tracker devices via MQTT.\n2.  **Personal Mode:** Local device positioning on a user's machine using a dedicated local Bluetooth scanning service.\n\n## Core Components\n\n1.  **Backend Server (`server/`):** Python (FastAPI). Handles MQTT, calculates tracker positions, manages state, and serves the API/WebSockets for Tracker Mode.\n2.  **Web Frontend (`web/`):** Vue 3 (Vite). Provides the UI for configuration, map display, and visualization for both modes.\n3.  **Local Beacon Service (`local-beacon-service/`):** Node.js. Runs on the user's machine, scans local BLE beacons, and sends data to the Web Frontend via WebSocket for Personal Mode.\n\n## Key Features\n\n*   Real-time tracking (Tracker Mode) \u0026 local device positioning (Personal Mode).\n*   Web UI for map/beacon configuration and live visualization.\n*   Trilateration with Kalman filter smoothing.\n*   MQTT integration for Tracker Mode.\n*   WebSocket communication for live data.\n\n## Architecture\n\n```\nWeb UI (Vue 3) \u003c--- WebSocket (Tracker Mode) --- Backend Server (FastAPI) --- MQTT --- Tracker Devices\n   ^                                                  |\n   |                                                  | (Serves Web UI files)\n   +--- WebSocket (Personal Mode, to localhost:8081) -- Local Beacon Service (Node.js on User Machine)\n```\n\n## User Guide \u0026 Simplified Startup\n\nThis guide helps you get the system running, especially using the provided start script for a streamlined experience. For \"Personal Mode\" (tracking your own device), you will also need to run the Local Beacon Service.\n\n**Prerequisites:**\n\n*   **Node.js:** LTS version (e.g., 18.x, 20.x). Download from [nodejs.org](https://nodejs.org/). (Needed for the web frontend and Local Beacon Service)\n*   **Python:** 3.10+. Download from [python.org](https://www.python.org/).\n*   **uv:** A fast Python package installer. Installation: `curl -LsSf https://astral.sh/uv/install.sh | sh` or see [uv documentation](https://github.com/astral-sh/uv#installation).\n*   **Bluetooth Adapter:** On your computer (for Personal Mode).\n\n**1. One-Click Start (`start.sh` - Recommended for most users):**\n\n   The `start.sh` script (located in the project root) is designed to automate the setup and startup of the Backend Server and Web Frontend.\n\n   ```bash\n   # Navigate to the project root directory\n   cd /path/to/beacon_posistion_r1000\n\n   # Make the script executable (if needed)\n   chmod +x start.sh\n\n   # Run the script\n   ./start.sh\n   ```\n   This script typically:\n   *   Sets up a Python virtual environment and installs dependencies using `uv` or `pip`.\n   *   Starts the backend server (e.g., `uvicorn server.main:app`).\n   *   Installs frontend dependencies (`npm install`) and starts the frontend development server (`npm run dev`).\n   *   May attempt to open a browser to the web application.\n   *   Press `Ctrl+C` in the terminal where `start.sh` is running to stop all services managed by it.\n\n**2. Run the Local Beacon Service (Required for Personal Mode):**\n\n   This service uses your computer's Bluetooth. It needs to be run separately if you intend to use Personal Mode.\n\n   ```bash\n   # Navigate to the local-beacon-service directory\n   cd /path/to/beacon_posistion_r1000/local-beacon-service\n\n   # Run the start script (installs dependencies if needed)\n   # On Linux/macOS:\n   chmod +x start_service.sh\n   ./start_service.sh\n   # On Windows (using Git Bash):\n   # ./start_service.sh\n   # For native Windows CMD/PowerShell (follow script instructions or):\n   # npm install # Run once\n   # node service.js\n   ```\n   The service will be available at `ws://localhost:8081`.\n\n**3. Using the Web Application:**\n\n   *   Access the main web application (this might be hosted, or run locally by a developer).\n   *   **Map \u0026 Beacon Configuration:**\n         *   Create/Import a map and beacon setup (JSON). Define map, place beacons, ensure MAC addresses \u0026 TxPower are correct. Export this \"master configuration\" JSON.\n   *   **Personal Mode Configuration:**\n         *   Import the master configuration JSON.\n         *   Ensure the Local Beacon Service (Step 2) is running.\n         *   Click \"Start Local Positioning\". Your device's position should appear on the map.\n   *   **Tracker Mode Configuration (for locating tracker devices):**\n         *   Import a master configuration JSON (updates the central server).\n         *   Configure server/MQTT settings if necessary. Trackers will appear on the map if publishing data.\n\n## Developer Guide\n\nThis guide is for setting up the development environment.\n\n**Prerequisites:**\n\n*   **Node.js:** LTS version (e.g., 18.x, 20.x).\n*   **npm:** (Included with Node.js).\n*   **Python:** 3.10+\n*   **uv (Recommended) or pip:** For Python packages.\n\n**1. Backend Server Setup (`server/`):**\n\n   ```bash\n   cd /path/to/beacon_posistion_r1000\n   python -m venv .venv\n   source .venv/bin/activate # On Linux/macOS. For Windows: .venv\\Scripts\\activate\n   uv pip install -r server/requirements.txt # Or: pip install -r server/requirements.txt\n   ```\n\n**2. Web Frontend Setup (`web/`):**\n\n```bash\ncd /path/to/beacon_posistion_r1000/web\nnpm install\n```\n\n**3. Local Beacon Service Setup (`local-beacon-service/`):**\n\n```bash\ncd /path/to/beacon_posistion_r1000/local-beacon-service\nnpm install\n```\n\n**4. Configuration Files (Backend - Tracker Mode):**\n\nLocated in `server/`:\n*   `web_config.json`: Map/beacon layout for server-side positioning. Updated via UI import in \"Tracker Mode\".\n*   `server_runtime_config.json`: MQTT, server port, Kalman parameters. Managed via UI or manual edit.\n\n**5. Running the System (Development):**\n\nRun each component in a separate terminal.\n\n**a. Backend Server (Recommended: `uv run`):**\n\n```bash\n# In project root. Assumes 'uv' is installed and Python environment is set up\n# (e.g., by running start.sh once, or by manual venv activation).\n# Replace \u003cport\u003e with port from server_runtime_config.json (e.g., 8022, 8000).\n# 'uv run' will manage the execution within the project's environment.\nuv run uvicorn server.main:app --host 0.0.0.0 --port \u003cport\u003e\n# Note: Avoid Uvicorn's --reload for stable MQTT/WebSocket. Restart manually if needed.\n```\n\n**b. Frontend Development Server:**\n   ```bash\n   cd web\n   npm run dev \n   # Access at http://localhost:5173 (or as shown by Vite)\n   ```\n\n**c. Local Beacon Service (for testing Personal Mode):**\n   ```bash\n   cd local-beacon-service\n   node service.js # Or ./start_service.sh\n   ```\n\n**d. Initial Setup via Web UI (Development):**\n   *   Open the Web Frontend (e.g., `http://localhost:5173`).\n   *   **Tracker Mode Configuration**: Configure server runtime settings, import map/beacon JSON.\n   *   **Map \u0026 Beacon Configuration**: Create/edit/export master JSON configurations.\n   *   **Personal Mode Configuration**: Import master JSON, start local positioning (ensure local service is running).\n\n## Key Files \u0026 Logic (for Developers)\n\n*   **MQTT Parsing:** `server/main.py` (`parse_sensecap_payload`)\n*   **Positioning:** `server/positioning.py`\n*   **Kalman Filter:** `server/positioning.py` (`KalmanFilter2D`)\n*   **Config Management:** `server/config_manager.py`\n*   **WebSockets (Tracker Mode):** `server/main.py`\n*   **Local Beacon Scanning (Personal Mode):** `local-beacon-service/service.js`\n*   **UI Views:** `web/src/views/` (MasterConfigView, PersonalModeConfigView, TrackerModeConfigView)\n*   **Map Component:** `web/src/components/MapView.vue`\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseeed-solution%2Fsolution_indoorpositioning_h5","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseeed-solution%2Fsolution_indoorpositioning_h5","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseeed-solution%2Fsolution_indoorpositioning_h5/lists"}