{"id":25600594,"url":"https://github.com/justin-marian/gps-tracker","last_synced_at":"2026-04-09T08:57:24.945Z","repository":{"id":278620048,"uuid":"931491350","full_name":"justin-marian/gps-tracker","owner":"justin-marian","description":"QEMU-based GPS tracker for Raspberry Pi 3 with real-time processing, Flask web visualization via Buildroot and a custom Linux kernel configurations.","archived":false,"fork":false,"pushed_at":"2025-02-20T18:33:10.000Z","size":55026,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-20T19:34:12.828Z","etag":null,"topics":["buildroot","embedded-systems","flask-webserver","gps-tracker","linux-kernel","raspberry-pi-3"],"latest_commit_sha":null,"homepage":"","language":"Python","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/justin-marian.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":"2025-02-12T11:18:12.000Z","updated_at":"2025-02-20T18:39:30.000Z","dependencies_parsed_at":"2025-02-20T19:44:19.480Z","dependency_job_id":null,"html_url":"https://github.com/justin-marian/gps-tracker","commit_stats":null,"previous_names":["justin-marian/gps-tracker"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fgps-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fgps-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fgps-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justin-marian%2Fgps-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justin-marian","download_url":"https://codeload.github.com/justin-marian/gps-tracker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240038463,"owners_count":19738145,"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":["buildroot","embedded-systems","flask-webserver","gps-tracker","linux-kernel","raspberry-pi-3"],"created_at":"2025-02-21T15:27:05.798Z","updated_at":"2026-04-09T08:57:19.926Z","avatar_url":"https://github.com/justin-marian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"https://www.svgrepo.com/show/354258/raspberry-pi.svg\" alt=\"Raspberry Pi Logo\" width=\"40\" height=\"40\" style=\"vertical-align:middle\" /\u003e **GPS Data Viewer** \u003cimg src=\"https://www.svgrepo.com/show/223049/maps-gps.svg\" alt=\"Maps GPS Logo\" width=\"40\" height=\"40\" style=\"vertical-align:middle\" /\u003e\n\nSetup and configuration of a GPS tracker project running on a Raspberry Pi 3B (`bcm2837-rpi-3-b`) platform.\nIt includes details on how the **RootFS**, **custom Kernel**, **Overlay** structure, and the **App Daemon** for GPS data collection and display were implemented.\n\n\u003e **References**:\n\u003e\n\u003e - [🌱 Buildroot Official Site](https://github.com/buildroot/buildroot) (latest version)\n\u003e - [🐧 Linux Kernel Source](https://github.com/torvalds/linux)  \n\u003e - [🔗 Buildroot Documentation](https://buildroot.org/docs.html)\n\u003e\n\nBelow is the layout of the project’s files and directories, as seen in the screenshot. All **Buildroot** configuration details are found in **`buildroot_config`**, while all **Linux kernel** configuration details reside in **`kernel_config`**.\n\n```bash\n/\n├── bin \n│   ├── bcm2837-rpi-3-b.dtb             # Device Tree Blob for Raspberry Pi 3B\n│   ├── gps-emu.py                      # GPS emulator script\n│   ├── launch-tema2.sh                 # Boot script for launching the OS\n│   ├── tema2.img                       # OS image for Raspberry Pi 3B\n│   └── vmlinuz-tema2                   # Custom Linux kernel image\n│\n├── src\n│   ├── raspberrypi3-64-overlay         # Overlay directory for Buildroot\n│   │   ├── etc                         # System configuration files\n│   │   │   ├── init.d\n│   │   │   │   ├── S68gps-daemon       # Startup script for GPS daemon\n│   │   │   │   └── S70gps-server       # Startup script for GPS web server\n│   │   │   ├── ssh\n│   │   │   │   └── sshd_config         #== SSH server configuration\n│   │   │   ├── udev\n│   │   │   │   └── rules.d\n│   │   │   │       └── mama_mea.rules  #== Rules for Ethernet starting correctly\n│   │   │   ├── passwd                  # Password file for user authentication\n│   │   │   └── shadow                  # Hashed passwords for users\n│   │   │\n│   │   ├── opt\n│   │   │   ├── templates\n│   │   │   │   └── index.html          #== Web interface for GPS data\n│   │   │   ├── gps-daemon.py           #== Script that collects GPS data\n│   │   │   └── gps-server.py           #== Flask server for GPS data visualization\n│   │   │\n│   │   └── tmp\n│   │       └── #== JSON files will be created when OS starts\n│   │\n│   ├── buildroot_config                #== Buildroot configuration file\n│   ├── kernel_config                   #== Linux kernel configuration file\n│   ├── checksum.txt                    #== Checksum bin_archive.tar.xz\n│   ├── Makefile                        #== QEMU Makefile, generates tema2.img, vmlinuz-tema2, bcm2837-rpi-3-b.dtb, ...\n│   ├── requirements.txt                #== Requirements for emulating USB Serial\n│   └── url.txt                         #== URL with bin_archive.tar.xz (\u0026download=1)\n\\\n```\n\n**Explanation:**\n\n1. **`bin/`**: Contains compiled binaries and scripts necessary for system operation.\n2. **`assets/`**: Images for this README and Google Cloud API Key Platform.\n3. **`src/raspberrypi3-64-overlay/`**: The overlay directory for **Buildroot**, containing:\n   - `etc/`: System configuration files.\n   - `opt/`: Python scripts and web-related files.\n   - `tmp/`: Temporary storage.\n4. **`buildroot_config`**: Stores **all Buildroot settings**, including selected packages, toolchain options, and other Buildroot-specific parameters.\n5. **`kernel_config`**: Contains the **Linux kernel configuration**, specifying which drivers, modules, and features are compiled into the custom kernel.\n\n---\n\n## 🌍 GPS Data Viewer - GGA, GSA, GSV, GLL, Map, HDT, RMC, VTG, ZDA\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"/assets/gga_gsa_gsv_gll_map.png\" alt=\"GPS Data Viewer - GGA, GSA, GSV, GLL, and Map\" width=\"900px\"\u003e\n    \u003cbr\u003e\n    \u003cimg src=\"/assets/map_hdt_rmc_vtg_zda.png\" alt=\"GPS Data Viewer - Map, HDT, RMC, VTG, ZDA\" width=\"900px\"\u003e\n\u003c/div\u003e\n\n---\n\n## 1. Root Filesystem (RootFS) 📁\n\n### 1.1. Overview\n\n- The RootFS (`rootfs.ext4`) was generated using **Buildroot** (latest version from GitHub) for the Raspberry Pi 3B (64-bit) platform (`bcm2837-rpi-3-b`).\n- The official `raspberrypi3_64_defconfig` was used as a starting point, then extended with custom settings to satisfy the project requirements.\n- The final RootFS is **256 MB** in size and contains all the essential components for running the GPS and web services.\n\n**Buildroot Configuration Highlights**:\n\n1. **Cross-Compilation**: Buildroot automatically cross-compiles the entire userspace for the ARMv8.\n2. **Filesystem Format**: The output is an EXT4 filesystem image (`rootfs.ext4`), suitable for mounting as the root partition on an SD card.\n3. **Customization**: By selecting or deselecting packages in the Buildroot menuconfig, the final size and capabilities of the image are controlled.\n\n### 1.2. Essential Packages and Settings\n\nSeveral packages were added to fulfill project functionality:\n\n- **Avahi-daemon** 🌐  \n  - Provides mDNS support, allowing network access via the hostname `tema2.local` (with password `tema2`).  \n  - This makes local network discovery simpler, removing the need to track DHCP-assigned IPs manually.\n\n- **Python 3** and **pip** 🐍  \n  - Required for running both the HTTP application (Flask) and the GPS daemon (`gps-daemon.py`).  \n  - Pip helps manage Python dependencies (e.g., installing `pyserial` or other needed libraries).\n\n- **Flask** 🍃  \n  - A micro web framework for implementing the server used to display GPS data in real time.  \n  - Chosen for its ease of setup and lightweight footprint.\n\n- **OpenSSH and AutoSSH** 🔐  \n  - Enables secure remote access (SSH), so you can log into the device for maintenance or debugging.  \n  - AutoSSH can automatically re-establish port forwarding tunnels if the connection is interrupted.\n\n- **DHCP Client** ⚙️  \n  - Configured to obtain an IP address on the `eth0` interface automatically.  \n  - Simplifies networking, especially in dynamic or unknown environments.\n\n**Additional RootFS Details**:\n\n- **Init Scripts**: The overlay includes scripts in `/etc/init.d` (specifically numbered `68` and `70`) to ensure they start in the correct order, avoiding conflicts with other services.\n- **User and Password**: The default user or root credentials can be set. In this case, `tema2` is used as the password, stored as an MD5 hash in `/etc/shadow`.\n- **Backup Config**: A backup of kernel or Buildroot configurations may be stored for reference (e.g., `config_tema2.txt`).\n\n---\n\n## 2. Overlay Structure 🏗️\n\n***(Additional reference for how the custom files are merged into the final RootFS.)***\n\n1. **`/etc`**:  \n   - Initialization scripts (`init.d/`) with unique numbering to avoid collisions.  \n   - `passwd` and `shadow` files store authentication details.  \n   - `ssh` config ensures OpenSSH starts properly.  \n   - `udev/rules.d/mama_mea.rules` enforces consistent naming for `eth0`.\n\n2. **`/opt`**:  \n   - **`gps-daemon`**: Contains the Python script that reads and processes GPS data.  \n   - **`gps-server`**: Contains the Flask-based web server script for displaying real-time GPS info.  \n   - **`templates/index.html`**: The HTML template for the GPS visualization page.\n\n3. **`/tmp`**:  \n   - Used by `gps-daemon.py` to store JSON data, updated every second.  \n   - `gps-server.py` reads from the same JSON file to serve up-to-date info at `http://\u003cdevice-ip\u003e:8888`.\n\n4. **Backup Config File**:  \n   - In `arm/config_tema2.txt`, used to preserve the kernel config relevant to the Raspberry Pi 3B platform.\n\n**The required DTB files** (`Device Tree Blob`) for `bcm2837-rpi-3-b` are generated using:\n\n```bash\nmake dtbs\n```\n\n---\n\n## 3. Custom Kernel ⚙️🐧\n\n### 3.1. Kernel Source and Configuration\n\n- A **v6.12 Linux kernel** was used, fetched from the official [Linux GitHub repository](https://github.com/torvalds/linux/), verified tag for that release.\n- Main adjustments include:\n  - Enabling the custom kernel option and disabling auto versioning (e.g., `-si-justin-marian.popescu`).\n  - Specifying the location of the kernel tar.xz archive.\n  - Including the SHA256 hash of the archive in **`linux.hash`** to ensure download integrity.\n  - Detailed kernel configuration via **`linux-menuconfig`** to meet project needs—particularly **USB** and **FTDI FT232H** sensor support.\n\n### 3.2. Additional Kernel Support\n\n- **Serial Devices**: Enabled for communication with serial-based peripherals, essential for GPS data collection.\n- **Character Devices**: General character device support.\n- **Input Devices**: Activated for peripheral connectivity.\n- **USB Support**:\n  - **USB Networking (USBNET)**: Handles network connections over USB.\n  - **FTDI USB Serial Converter**: Required for USB-connected GPS sensors.\n  - **Driver FTDI for GPS**: Configured to handle NMEA data from the serial port.\n\n### 3.3. Extended Functionality\n\nThrough kernel and system configurations, several extended features have been enabled:\n\n- **Dynamic Device Management** with `udev`: Automatically detects and configures serial and USB interfaces.\n- **Secure Remote Access** (SSH) with port forwarding via **OpenSSH** and **AutoSSH**.\n- **DHCP Client** on `eth0` for automatic IP assignment.\n- **Python/Flask** environment for hosting a lightweight web server to display GPS data.\n- **IPv4/IPv6/TCP/Bluetooth** remain enabled by default for more robust connectivity.\n\n---\n\n## 4. Makefile and `launch-tema2.sh` – Structure and Paths 📜\n\nAfter running:\n\n```bash\nmake -j$(nproc)\n```\n\nThe following files are produced in Buildroot:\n\n- **DTB**: `../buildroot/output/build/linux-custom/arch/arm64/boot/dts/broadcom/`  \n- **Kernel**: `../buildroot/output/build/linux-custom/arch/arm64/boot/`  \n- **RootFS**: `../buildroot/output/images/`  \n\nThese paths are referenced in the project’s **Makefile** and in **`launch-tema2.sh`** to ensure correct deployment and boot.\n\n### `launch-tema2.sh` Changes\n\n**Kernel**: Uses `vmlinuz-tema2` instead of `vmlinuz-test`:\n\n```bash\nKERNEL_FILE=\"vmlinuz-tema2\"\n```\n\n**Console**: Switched from `console=ttyS0` to `console=ttyAMA0` for kernel compatibility:\n\n```bash\n_KERNEL_CONSOLE=\"console=ttyAMA0 console=ttyS1\"\n```\n\n**Root Device**: Changed from `mmcblk0p2` to `mmcblk0` to match the generated SD card image:\n\n```bash\nROOTDEV=\"mmcblk0\"\n```\n\n---\n\n## 5. Python Scripts 🐍\n\n### 5.1. `gps-daemon.py`\n\n- **Data Collection**: Reads raw NMEA data (e.g., `$GPGGA`, `$GPZDA`, `$GPGLL`) from the serial port via the `pyserial` library.  \n- **Data Processing**: Converts NMEA coordinates to decimal format and UTC time to ISO 8601.  \n- **JSON Output**: Writes processed GPS data to `/tmp/gps_data.json` (updated every second).  \n- **Logging**: Writes logs and error messages to `/tmp/gps_daemon.log`.\n\n### 5.2. `gps-server.py`\n\n- **Flask Web Server**: Serves an interface displaying real-time GPS data.\n- **API Endpoints**:  \n  - `GET /api/gps`: Returns JSON with the latest GPS data.  \n  - `GET /`: Serves `index.html`.\n- **File Reading**: Pulls data from the JSON file generated by `gps-daemon.py`.  \n- **Logging**: Writes logs to `/tmp/gps_server.log`.\n\n### 5.3. `index.html`\n\n- **User Interface**: Displays:\n  - Latitude/Longitude, Altitude  \n  - Number of satellites, GPS fix type  \n  - Date/Time (UTC)  \n  - An interactive map (Google Maps) for live location tracking  \n- **Real-Time Updates**: Uses JavaScript to request `/api/gps` every 500 ms for fresh location info.\n\n---\n\n## 6. Additional Observations and Features 🔎\n\nBelow are some extra notes and features included in the project, derived from the extended documentation:\n\n- **MD5 Password**: Use `tema2` as the default password, encrypted in `/etc/passwd` and `/etc/shadow`.\n- **AutoSSH**: Can maintain persistent SSH tunnels or port-forwards, which is helpful for remote management.\n- **Udev Network Rules**: The custom file `mama_mea.rules` ensures that the primary network interface is always recognized as `eth0`, preventing name conflicts (e.g., `eth1`, `enxXXXX`, etc.).\n- **Partitioning**: The final SD card image uses a single root partition (`mmcblk0`), making it simpler to reference in scripts (`ROOTDEV=\"mmcblk0\"`).\n- **Kernel Backup Config**: The file `config_tema2.txt` (in the `arm/` directory) serves as a snapshot of the kernel’s Buildroot configuration. It may also be partially auto-generated during the build process, ensuring that any specialized changes are documented.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustin-marian%2Fgps-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustin-marian%2Fgps-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustin-marian%2Fgps-tracker/lists"}