{"id":46133751,"url":"https://github.com/renatobo/bonogps","last_synced_at":"2026-03-02T04:20:43.242Z","repository":{"id":48207510,"uuid":"314080302","full_name":"renatobo/bonogps","owner":"renatobo","description":"A GPS setup to log your track lap times, based on ESP32, with the ability to interface with several mobile phone apps that log your speed and position via Bluetooth Low Energy, Bluetooth or WiFi","archived":false,"fork":false,"pushed_at":"2025-11-12T17:47:16.000Z","size":34614,"stargazers_count":91,"open_issues_count":3,"forks_count":24,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-11-12T18:24:08.855Z","etag":null,"topics":["car","esp32","gps","harry-lap-timer","motorcycle","trackdays","ublox-gps"],"latest_commit_sha":null,"homepage":"","language":"C++","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/renatobo.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":"2020-11-18T23:07:05.000Z","updated_at":"2025-11-07T10:59:48.000Z","dependencies_parsed_at":"2025-10-26T00:06:59.636Z","dependency_job_id":"660da163-7eab-4c92-8818-a00eaa151e59","html_url":"https://github.com/renatobo/bonogps","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/renatobo/bonogps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatobo%2Fbonogps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatobo%2Fbonogps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatobo%2Fbonogps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatobo%2Fbonogps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/renatobo","download_url":"https://codeload.github.com/renatobo/bonogps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatobo%2Fbonogps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29992287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"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":["car","esp32","gps","harry-lap-timer","motorcycle","trackdays","ublox-gps"],"created_at":"2026-03-02T04:20:42.627Z","updated_at":"2026-03-02T04:20:43.232Z","avatar_url":"https://github.com/renatobo.png","language":"C++","funding_links":[],"categories":["DIY Hardware"],"sub_categories":["GPS Timer"],"readme":"# What is BonoGPS?\n\n- [What is BonoGPS?](#what-is-bonogps)\n  - [For the track day enthusiast](#for-the-track-day-enthusiast)\n  - [For the SW Engineer / maker](#for-the-sw-engineer--maker)\n    - [Diagram of project components](#diagram-of-project-components)\n  - [Quick Start Guide](#quick-start-guide)\n  - [Known Good Configurations](#known-good-configurations)\n  - [Complete Bill of Materials (BOM)](#complete-bill-of-materials-bom)\n  - [How to Verify Everything is Working](#how-to-verify-everything-is-working)\n  - [Common Mistakes to Avoid](#common-mistakes-to-avoid)\n  - [HowTo](#howto)\n    - [Daily Usage](#daily-usage)\n      - [Save a configuration](#save-a-configuration)\n    - [Connecting to an app](#connecting-to-an-app)\n  - [Hardware build instructions](#hardware-build-instructions)\n    - [GPS Choice and setup preconfiguration](#gps-choice-and-setup-preconfiguration)\n  - [Software build instructions](#software-build-instructions)\n  - [Technical Specifications](#technical-specifications)\n  - [Troubleshooting and FAQ](#troubleshooting-and-faq)\n  - [Possible enhancements and ideas](#possible-enhancements-and-ideas)\n  - [Glossary](#glossary)\n  - [Credits and tools](#credits-and-tools)\n\n## For the track day enthusiast\n\nThe main goal of this device is to **make GPS data (speed, location) available to mobile apps that can record data up to 25 Hz, for example for track riding**. While there are many good (and not even too expensive) solutions out there, building one for yourself is a great experience.\n\n![Map of Buttonwillow lateral acceleration](software/using/buttonwillow_map.png)\n\nCurrently these apps are supported\n\n1. [Harry's Lap Timer](https://www.gps-laptimer.de) \u003e\u003e details [here](software/connecting/harrylaptimer)\n2. [TrackAddict](https://www.hptuners.com/product/trackaddict-app/) \u003e\u003e details [here](software/connecting/trackaddict)\n3. [RaceChrono](https://racechrono.com/) \u003e\u003e details [here](software/connecting/racechrono)\n4. [RaceTime](https://www.racetimeapp.com/en/) \u003e\u003e details [here](software/connecting/racetime)\n\nIf you are not into the maker thing or if you don't know anyone who might be, [look into RaceBox products like mini/miniS](https://www.racebox.pro/) and even [a 25Hz kit](https://www.racebox.pro/products/racebox-micro), or [a XGPS160](https://gps.dualav.com/explore-by-product/xgps160).\n\n## For the SW Engineer / maker\n\nThis repo contains software, a list of hardware, and (simple) schematics to build an ESP32 device that reads NMEA sentences from a GPS receiver compatible with u-blox M10 and M8 series, for example:\n\n| GPS Module | Chipset | Max Refresh | Antenna Type | Recommended | Link |\n| ---------- | ------- | ----------- | ------------ | ----------- | ---- |\n| **BK880** | M10 | **25 Hz** | Active | ✓ Best | [Store](https://store.beitian.com/products/beitian-compass-qmc5883l-amp2-6-pix4-pixhawk-gnss-gps-glonass-dual-flight-control-gps-module-bn-880q?variant=44977758011679) |\n| **BK280** | M10 | **25 Hz** | Passive | ✓ Best | [Store](https://store.beitian.com/collections/gps-module/products/beitian-gps-module-with-antenna-ubx-m10050-gnss-chip-ultra-low-power-gnss-receiver-for-track-be-180?variant=44859232420127) |\n| BN880 | M8 | 10 Hz | Active | Good | [Store](https://store.beitian.com/products/beitian-ubx-m8030-g-mouse-supports-gps-qzss-and-sbas-fixed-wing-traversing-aircraft-gps-module-antenna-bn-180-220-280-357-880-880q?variant=46725104730399\u0026_pos=1\u0026_sid=fe8b2c602\u0026_ss=r) |\n| BN220 | M8 | 10 Hz | Passive | Budget | [Store](https://store.beitian.com/products/beitian-ubx-m8030-g-mouse-supports-gps-qzss-and-sbas-fixed-wing-traversing-aircraft-gps-module-antenna-bn-180-220-280-357-880-880q?variant=46694929989919\u0026_pos=1\u0026_sid=fe8b2c602\u0026_ss=r) |\n| DIYmall NEO-M8N | M8N | 10 Hz | Active | Compatible | [Amazon](https://www.amazon.com/DIYmall-NEO-M8N-Module-HMC5983-Antenna/dp/B012RNLG0K) |\n\n**Note:** Active antennas provide better signal quality. M10 modules (BK880/BK280) offer 25Hz refresh rate which is ideal for track use. See [GPS setup guide](hardware/GPS) for detailed configuration.\n\nand repeats them back to a logger device, either\n\n1. a Bluetooth Low Energy (BLE) service\n2. a BT Classic (BT-SPP) stream\n3. a TCP-IP socket\n\nThe logger device is likely going to be one of the *Track Lap time apps* listed above running on your phone.\n\nExamples of actual devices are in [hardware/assembled](hardware/assembled), at a cost of 25$ and 40$ (GPS receivers with active antennas are a little bit more expensive but worth it, and a larger battery helps as well)\n\n![Prototype picture](hardware/assembled/bonogps_bn220_side.jpg)\n\nA web configuration (basic responsive HTML) panel allows changing configuration and selecting GPS parameters on the fly: access it via [http://bonogps.local](http://bonogps.local) (when in WiFi AP mode, this becomes [http://10.0.0.1](http://10.0.0.1) on Android without mDNS resolution).\n\nThe settings required by each app are available as presets that you can load for your device (iOS, Android). More information on what version, features, and connections of each app are in [software/connecting](software/connecting).\n\nYou can also interface your GPS to [uBlox u-center](https://www.u-blox.com/en/product/u-center) via TCP-IP. In this case, be aware that the UART speed is fixed.\n\n### Diagram of project components\n\n![Project diagram](software/bonogps_project_diagram.png)\n\n## Quick Start Guide\n\n**New to BonoGPS? Get started in 5 steps:**\n\n### Step 1: Get the Hardware (Budget: $30-60)\n\n**Minimum setup (~$30):**\n- ESP32 DevKit board (~$8-12) - [Amazon](https://www.amazon.com/s?k=esp32+devkit)\n- BN220 GPS module (~$15-20) - [Beitian Store](https://store.beitian.com/)\n- USB cable for programming/power\n- Basic jumper wires\n\n**Recommended setup (~$45):**\n- ESP32 DevKit or LOLIN D32 PRO (~$12-20)\n- BN880 GPS with active antenna (~$25) - [Beitian Store](https://store.beitian.com/)\n- Li-Ion battery (650-2000mAh, ~$5-10)\n- Case or 3D printed enclosure\n\n**Best performance (~$60):**\n- LOLIN D32 PRO with built-in battery charger (~$15-20)\n- BK880 or BK280 GPS (M10, 25Hz) (~$35-45) - [Beitian Store](https://store.beitian.com/)\n- 2000mAh Li-Ion battery (~$8-12)\n- Custom 3D printed mount\n\n### Step 2: Wire It Up (15 minutes)\n\nConnect GPS to ESP32 - only 4 wires needed:\n- GPS **VCC** → ESP32 **3.3V** (power)\n- GPS **GND** → ESP32 **GND** (ground)\n- GPS **TX** → ESP32 **RX** (GPIO 16 on DevKit, GPIO 4 on LOLIN D32 PRO)\n- GPS **RX** → ESP32 **TX** (GPIO 17 on DevKit, GPIO 2 on LOLIN D32 PRO)\n\nSee detailed wiring diagrams: [Generic ESP32](hardware/esp32) | [LOLIN D32 PRO](hardware/esp32/lolin_d32_pro.md)\n\n### Step 3: Configure GPS Module (30 minutes)\n\n**Critical:** GPS must be configured before first use.\n\n1. Download [u-blox u-center](https://www.u-blox.com/en/product/u-center)\n2. Connect GPS to computer via USB-to-serial adapter\n3. Follow the [GPS configuration guide](hardware/GPS)\n4. Set baudrate to **115200**\n5. Enable required NMEA messages\n6. Save configuration to GPS flash memory\n\n### Step 4: Build and Upload Software (20-45 minutes)\n\n**Option A: Arduino IDE (easier for beginners)**\n1. Install [Arduino IDE 2.x](https://www.arduino.cc/en/software)\n2. Add ESP32 board support\n3. Install required libraries (see [library list](software/building#external-libraries))\n4. Open `bonogps.ino`\n5. Select \"ESP32 Dev Module\" or \"LOLIN D32 PRO\"\n6. Select \"Minimal SPIFFS (1.9MB)\" partition scheme\n7. Upload to ESP32\n\n**Option B: PlatformIO (recommended for developers)**\n1. Install [VS Code + PlatformIO](https://platformio.org/install/ide?install=vscode)\n2. Clone this repository: `git clone https://github.com/renatobo/bonogps.git`\n3. Open project folder in VS Code\n4. Select build target for your board\n5. Build and upload\n\nSee detailed instructions: [Software build guide](software/building)\n\n### Step 5: Connect to Your App (10 minutes)\n\n1. Power on BonoGPS - wait for GPS fix (LED blinks once/second)\n2. Connect phone to **BonoGPS-XXXX** WiFi network\n3. Open browser to [http://10.0.0.1](http://10.0.0.1)\n4. Go to **Device \u003e Load Preset** - select your app and platform\n5. Enable appropriate connection (BLE/BT-SPP/TCP-IP)\n6. Open your lap timer app and connect\n\n**Supported apps:** [Harry's Lap Timer](software/connecting/harrylaptimer) | [TrackAddict](software/connecting/trackaddict) | [RaceChrono](software/connecting/racechrono) | [RaceTime](software/connecting/racetime)\n\n**Need help?** See [Troubleshooting FAQ](#troubleshooting-and-faq) below.\n\n---\n\n## Known Good Configurations\n\nThese hardware and app combinations have been tested and confirmed working. Use these as reference if you want a guaranteed-to-work setup.\n\n### Budget Build - iOS ($45)\n**Hardware:**\n- ESP32 DevKit (~$10)\n- BN880 GPS with active antenna (~$25)\n- 1000mAh Li-Ion battery (~$6)\n- Micro USB cable for programming\n- Basic transparent case\n\n**Software \u0026 Connection:**\n- Harry's Lap Timer (iOS)\n- Connection: BLE\n- Preset: \"Harry's Lap Timer iOS BLE\"\n- Expected performance: 10Hz, good accuracy (2-3m)\n\n**Why this works:** BN880 active antenna provides reliable signal, BLE is native to iOS, Harry's Lap Timer has best BLE support.\n\n### Best Performance - iOS ($65)\n**Hardware:**\n- LOLIN D32 PRO (~$18)\n- BK880 GPS M10 with active antenna (~$40)\n- 2000mAh Li-Ion battery (~$10)\n- Custom 3D printed mount\n\n**Software \u0026 Connection:**\n- Harry's Lap Timer (iOS)\n- Connection: BLE\n- Preset: \"Harry's Lap Timer iOS BLE\"\n- Expected performance: 20Hz over BLE, excellent accuracy (\u003c2m)\n\n**Why this works:** M10 chipset supports 25Hz, LOLIN has battery management, BLE optimized for iOS. Best overall iOS solution.\n\n### Budget Build - Android ($35)\n**Hardware:**\n- ESP32 DevKit (~$8)\n- BN220 GPS with passive antenna (~$18)\n- Powered via USB (no battery)\n- Velcro mounting\n\n**Software \u0026 Connection:**\n- RaceChrono (Android)\n- Connection: BT-SPP\n- Preset: \"RaceChrono Android BT-SPP\"\n- Expected performance: 10Hz, good accuracy in open areas\n\n**Why this works:** BT-SPP is most reliable on Android, RaceChrono is free and widely used, no battery needed for testing.\n\n### Recommended - Android ($50)\n**Hardware:**\n- ESP32 DevKit or LOLIN D32 PRO (~$12-18)\n- BN880 GPS with active antenna (~$25)\n- 1500mAh Li-Ion battery (~$8)\n- Basic enclosure\n\n**Software \u0026 Connection:**\n- RaceChrono or TrackAddict (Android)\n- Connection: BT-SPP\n- Preset: App-specific BT-SPP preset\n- Expected performance: 10Hz, excellent accuracy (2-3m)\n\n**Why this works:** Active antenna ensures good signal, BT-SPP handles full NMEA messages reliably, proven battery life for track days.\n\n### Advanced - Android with High Refresh ($65)\n**Hardware:**\n- LOLIN D32 PRO (~$18)\n- BK880 M10 GPS with active antenna (~$40)\n- 2000mAh Li-Ion battery (~$10)\n- Professional mounting solution\n\n**Software \u0026 Connection:**\n- Harry's Lap Timer (Android)\n- Connection: BT-SPP or TCP-IP\n- Preset: \"Harry's Lap Timer Android BT-SPP\"\n- Expected performance: 10Hz over BT-SPP (25Hz requires TCP-IP)\n\n**Why this works:** M10 chipset provides maximum performance, larger battery for full track day, LOLIN handles power management. **Note:** 25Hz requires TCP-IP connection which has less range than Bluetooth.\n\n### Universal WiFi Setup - iOS \u0026 Android ($45)\n**Hardware:**\n- ESP32 DevKit (~$10)\n- BN880 GPS (~$25)\n- 2000mAh Li-Ion battery (~$10) - important for WiFi power draw\n\n**Software \u0026 Connection:**\n- RaceChrono (iOS or Android)\n- Connection: TCP-IP over WiFi\n- IP: 10.0.0.1, Port: 1818\n- Expected performance: 10Hz, works on any platform\n\n**Why this works:** TCP-IP works universally, no Bluetooth pairing needed, RaceChrono supports custom TCP devices. Larger battery compensates for WiFi power consumption.\n\n### What About TrackAddict?\n**Hardware:** Any ESP32 + BN220/BN880\n**Platform:** Android only (not available on iOS)\n**Connection:** BT-SPP only\n**Important:** Must use **GP Talker ID** (not GN). Load \"TrackAddict Android BT-SPP\" preset.\n\n### Testing Configuration (Cheapest, $30)\nFor initial testing before investing in batteries/cases:\n- ESP32 DevKit (~$8)\n- BN220 GPS (~$18)\n- USB power from laptop\n- Any supported app\n- Test app connection indoors via WiFi, then test GPS outdoors\n\n---\n\n## Complete Bill of Materials (BOM)\n\nUse this comprehensive shopping list to gather all components for your BonoGPS build. Choose components based on your budget and performance requirements.\n\n### Core Components (Required)\n\n| Component | Options | Qty | Est. Cost | Purpose | Where to Buy | Notes |\n|-----------|---------|-----|-----------|---------|--------------|-------|\n| **ESP32 Board** | ESP32 DevKit (generic) | 1 | $8-12 | Main controller | [Amazon](https://www.amazon.com/s?k=esp32+devkit), AliExpress | Most common, cheapest |\n| | LOLIN D32 PRO | 1 | $15-20 | Main controller + extras | [WEMOS/LOLIN Store](https://www.wemos.cc/) | Battery charger, PSRAM, TF card |\n| **GPS Module** | BN220 (M8, passive) | 1 | $15-20 | Budget GPS | [Beitian Store](https://store.beitian.com/) | 10Hz max, passive antenna |\n| | BN880 (M8, active) | 1 | $23-27 | Good GPS | [Beitian Store](https://store.beitian.com/) | 10Hz max, active antenna (recommended) |\n| | BK280 (M10, passive) | 1 | $35-40 | Best GPS | [Beitian Store](https://store.beitian.com/) | 25Hz capable, passive antenna |\n| | BK880 (M10, active) | 1 | $38-45 | Best GPS | [Beitian Store](https://store.beitian.com/) | 25Hz capable, active antenna (best performance) |\n| | NEO-M8N | 1 | $25-30 | Compatible GPS | [Amazon](https://www.amazon.com/s?k=neo-m8n+gps) | Alternative M8 module |\n| **USB Cable** | Micro USB cable | 1 | $3-5 | Programming \u0026 power | Amazon, any electronics store | For ESP32 DevKit |\n| | USB-C cable | 1 | $5-8 | Programming \u0026 power | Amazon, any electronics store | For LOLIN D32 PRO |\n| **Jumper Wires** | Male-to-female, 10cm | 4+ | $2-5 | GPS wiring | Amazon, AliExpress | Only needed if not soldering |\n\n**Core components subtotal:** $30-60 depending on choices\n\n### Power Components (Recommended for portable use)\n\n| Component | Options | Qty | Est. Cost | Purpose | Where to Buy | Notes |\n|-----------|---------|-----|-----------|---------|--------------|-------|\n| **Battery** | 650mAh Li-Ion 3.7V | 1 | $5-7 | ~2-2.5 hrs runtime | Amazon, hobby stores | JST connector |\n| | 1000mAh Li-Ion 3.7V | 1 | $6-8 | ~3-4 hrs runtime | Amazon, hobby stores | JST connector |\n| | 1500mAh Li-Ion 3.7V | 1 | $8-10 | ~5-6 hrs runtime | Amazon, hobby stores | JST connector |\n| | 2000mAh Li-Ion 3.7V | 1 | $8-12 | ~6-8 hrs runtime | Amazon, hobby stores | JST connector, best for track day |\n| **Battery Charger** | USB Li-Ion charger | 1 | $3-6 | Battery charging | Amazon, AliExpress | Not needed for LOLIN D32 PRO (built-in) |\n| | LiPo balance charger | 1 | $15-25 | Multi-battery charging | Amazon, hobby stores | Optional, for multiple batteries |\n\n**Power components subtotal:** $5-40 depending on battery size and charger\n\n### Assembly Components (Optional but recommended)\n\n| Component | Options | Qty | Est. Cost | Purpose | Where to Buy | Notes |\n|-----------|---------|-----|-----------|---------|--------------|-------|\n| **Enclosure** | Transparent plastic case | 1 | $3-8 | Basic protection | Amazon, electronics stores | Various sizes available |\n| | Custom 3D printed case | 1 | $5-15 | Perfect fit | Local makerspace, online 3D print services | STL files in [hardware/assembled](hardware/assembled) |\n| | Weatherproof box | 1 | $10-20 | Professional protection | Amazon | For permanent motorcycle installations |\n| **Mounting** | Velcro strips | 1 set | $3-5 | Removable mounting | Amazon, hardware stores | Easy attachment/removal |\n| | Double-sided tape (3M VHB) | 1 roll | $5-10 | Semi-permanent | Amazon, hardware stores | Strong, vibration-resistant |\n| | Zip ties | 10+ | $2-5 | Cable management | Amazon, hardware stores | Various sizes |\n| **Wiring** | Heat shrink tubing | 1 set | $5-8 | Wire insulation | Amazon | Professional finish |\n| | 22-24 AWG stranded wire | 1m | $3-5 | Custom wiring | Amazon, electronics stores | If making custom cables |\n| | JST connectors | 5 sets | $5-10 | Battery connectors | Amazon, hobby stores | For custom battery connections |\n| **Soldering** | Soldering iron kit | 1 | $15-40 | Permanent connections | Amazon | If you don't have one |\n| | Solder (lead-free) | 1 roll | $8-15 | Soldering | Amazon, electronics stores | 60/40 or lead-free |\n| | Flux pen | 1 | $5-8 | Better solder joints | Amazon | Makes soldering easier |\n\n**Assembly components subtotal:** $0-80+ depending on tools and quality\n\n### Configuration Tools (One-time purchase)\n\n| Component | Options | Qty | Est. Cost | Purpose | Where to Buy | Notes |\n|-----------|---------|-----|-----------|---------|--------------|-------|\n| **USB-to-Serial Adapter** | CP2102 or FTDI adapter | 1 | $5-10 | GPS configuration | Amazon, AliExpress | Required for GPS setup with u-center |\n| | USB-to-TTL with 3.3V/5V switch | 1 | $8-12 | GPS configuration (better) | Amazon | More versatile, safer |\n\n**Configuration tools subtotal:** $5-12 (one-time, reusable)\n\n### Software (Free)\n\n| Software | Cost | Purpose | Where to Get |\n|----------|------|---------|--------------|\n| Arduino IDE 2.x | Free | Firmware compilation (beginner) | [arduino.cc](https://www.arduino.cc/en/software) |\n| VS Code + PlatformIO | Free | Firmware compilation (advanced) | [platformio.org](https://platformio.org/) |\n| u-blox u-center | Free | GPS configuration | [u-blox.com](https://www.u-blox.com/en/product/u-center) |\n| Harry's Lap Timer | $0-100 | iOS/Android lap timing | App Store / Play Store |\n| RaceChrono | Free-$20 | iOS/Android lap timing | App Store / Play Store |\n| TrackAddict | Free-$25 | Android lap timing | Play Store |\n| RaceTime | Free | Android lap timing | Play Store |\n\n### Shopping List Templates\n\n**Minimum viable build ($30-35):**\n- [ ] ESP32 DevKit ($8-12)\n- [ ] BN220 GPS ($15-20)\n- [ ] Micro USB cable ($3-5)\n- [ ] 4x jumper wires ($2-5) OR soldering supplies\n- [ ] USB-to-serial adapter ($5-10) for GPS config\n- **Total: ~$33-52**\n\n**Recommended portable build ($50-65):**\n- [ ] ESP32 DevKit or LOLIN D32 PRO ($10-18)\n- [ ] BN880 GPS ($25)\n- [ ] 1000-1500mAh battery ($6-10)\n- [ ] USB cable ($3-8)\n- [ ] Plastic case ($3-8)\n- [ ] Velcro or double-sided tape ($3-5)\n- [ ] USB-to-serial adapter ($5-10)\n- **Total: ~$55-84**\n\n**Best performance build ($70-90):**\n- [ ] LOLIN D32 PRO ($15-20)\n- [ ] BK880 M10 GPS ($38-45)\n- [ ] 2000mAh battery ($8-12)\n- [ ] USB-C cable ($5-8)\n- [ ] 3D printed custom case ($5-15)\n- [ ] Mounting solution ($3-10)\n- [ ] USB-to-serial adapter ($5-10)\n- [ ] Soldering supplies if needed ($15-40)\n- **Total: ~$79-160**\n\n### Notes on Purchasing\n\n**GPS Modules:**\n- Buy directly from Beitian Store for authentic modules\n- Beware of clones on AliExpress/eBay (may have older firmware or fake chipsets)\n- Active antennas significantly improve performance in difficult conditions\n\n**Batteries:**\n- Match voltage: 3.7V Li-Ion or LiPo only\n- Check connector: JST 2-pin is most common\n- Capacity = runtime: 650mAh → 2hrs, 2000mAh → 8hrs\n- Never charge Li-Ion batteries below 0°C (32°F)\n\n**ESP32 Boards:**\n- DevKit: Universal compatibility, cheapest\n- LOLIN D32 PRO: Built-in battery management worth the extra cost for portable use\n\n**Where to save money:**\n- Skip the case initially (test on desk)\n- Use USB power instead of battery for testing\n- Use jumper wires instead of soldering initially\n- BN220 instead of BN880 (passive vs active antenna)\n\n**Where NOT to save money:**\n- GPS module quality (buy from reputable source)\n- USB cable quality (cheap cables cause upload/power issues)\n- Battery quality (cheap batteries fail quickly)\n\n---\n\n## How to Verify Everything is Working\n\nAfter completing the Quick Start, use this checklist to confirm your BonoGPS is functioning correctly:\n\n### Hardware \u0026 Boot Checks\n- ✅ **ESP32 powers on:** Device responds when plugged in via USB or battery\n- ✅ **Built-in LED indicates WiFi mode:**\n  - Slow blink (500ms cycle) = Access Point mode active\n  - Fast blink (250ms cycle) = Client mode active\n  - Off = WiFi disabled\n- ✅ **GPS module powers on:** GPS module LED is visible (if module has one)\n\n### GPS Functionality\n- ✅ **GPS acquires satellite fix:**\n  - BN/BK modules: Red LED blinks once per second after fix\n  - First time: Allow 5-15 minutes outdoors with clear sky view\n  - Subsequent times: Should get fix in 1-5 seconds\n- ✅ **Satellite count adequate:** At least 4 satellites visible for accurate positioning\n  - Check in web interface under \"Status\" or \"GPS Info\"\n  - 8+ satellites = excellent signal\n  - 4-7 satellites = good signal\n  - \u003c4 satellites = insufficient for accurate position\n\n### Connectivity \u0026 Web Interface\n- ✅ **Can access web interface:**\n  - Connect to BonoGPS-XXXX WiFi network\n  - Navigate to http://10.0.0.1 (Android) or http://bonogps.local (iOS/desktop)\n  - Configuration page loads successfully\n- ✅ **Web interface shows correct device info:**\n  - Device name displays (BonoGPS-XXXX)\n  - Battery voltage shown (if using LOLIN D32 PRO with battery)\n  - Firmware version visible\n\n### App Connection\n- ✅ **Mobile app discovers device:**\n  - BLE: Device appears as \"BonoGPS-XXXX\" in Bluetooth settings\n  - BT-SPP: Device pairs successfully via Bluetooth\n  - TCP-IP: App connects to 10.0.0.1:1818\n- ✅ **App receives GPS data:**\n  - Speed readings update in real-time\n  - Position shows on map (if app has map view)\n  - Satellite count matches GPS module readings\n- ✅ **Data update rate is correct:**\n  - 10Hz modules: ~10 updates per second\n  - 25Hz modules: ~25 updates per second (M10 chipset only)\n\n### Track Day Ready\n- ✅ **Battery runtime adequate:** Full charge provides expected runtime based on capacity\n- ✅ **GPS maintains fix while moving:** No dropouts during test drive\n- ✅ **Mounting secure:** Device stays in place under vibration\n- ✅ **App records session successfully:** Can complete and save a test session\n\n**If any check fails**, see the [Troubleshooting FAQ](#troubleshooting-and-faq) section below.\n\n---\n\n## Common Mistakes to Avoid\n\n### Critical Mistakes (Will prevent device from working)\n\n**❌ Forgetting to configure GPS before first use**\n- **Why it matters:** GPS modules ship with default settings that may not work with BonoGPS or your app\n- **Solution:** Follow the [GPS configuration guide](hardware/GPS) before connecting GPS to ESP32\n- **Time cost:** 30-45 minutes to configure correctly\n\n**❌ Wrong partition scheme during upload**\n- **Why it matters:** Default partition is too small for BonoGPS firmware with Bluetooth\n- **Solution:** Select \"Minimal SPIFFS (1.9MB)\" in Arduino IDE or PlatformIO\n- **Error:** Build fails with \"not enough space\" or upload fails\n\n**❌ Swapped TX/RX pins**\n- **Why it matters:** UART communication requires TX→RX and RX→TX crossover\n- **Solution:** Connect GPS TX to ESP32 RX, and GPS RX to ESP32 TX\n- **Symptom:** No GPS data received, web interface shows \"No GPS fix\"\n\n**❌ Testing GPS indoors**\n- **Why it matters:** GPS requires direct line of sight to satellites\n- **Solution:** Test outdoors with clear sky view, away from buildings and trees\n- **First fix:** Allow 5-15 minutes for initial satellite almanac download\n\n### App Compatibility Mistakes\n\n**❌ Using GN Talker ID with RaceChrono or TrackAddict**\n- **Why it matters:** These apps require GP Talker ID specifically\n- **Solution:** Load the app-specific preset from web interface (sets Main Talker ID = GP)\n- **Symptom:** App shows \"no data\" or \"invalid GPS\"\n\n**❌ Wrong connection method for platform**\n- **Why it matters:** iOS doesn't support BT-SPP, Android BLE has limitations\n- **Solution:**\n  - **iOS:** Use BLE (Harry's Lap Timer) or TCP-IP (RaceChrono)\n  - **Android:** Use BT-SPP (most reliable) or TCP-IP as backup\n- **Symptom:** Device not found or connection drops\n\n**❌ Too high refresh rate with satellite messages enabled**\n- **Why it matters:** Bluetooth bandwidth is limited\n- **Solution:**\n  - For BLE: Use 20Hz or lower, disable GSA/GSV or poll at 5-second intervals\n  - For BT-SPP: 10Hz is safe with full messages\n- **Symptom:** Connection drops, data corruption, app crashes\n\n### Build and Upload Mistakes\n\n**❌ Wrong NimBLE library version**\n- **Why it matters:** Breaking changes between versions 1.x, 2.x, and 3.x\n- **Solution:** Use NimBLE-Arduino version **2.x** specifically\n- **Error:** Compilation fails with \"class NimBLEDevice has no member...\"\n\n**❌ Not cloning from Git (downloading ZIP instead)**\n- **Why it matters:** Build script uses Git to determine version info\n- **Solution:** Use `git clone https://github.com/renatobo/bonogps.git`\n- **Error:** \"git_rev_macro.py\" errors during PlatformIO build\n\n**❌ Insufficient USB power**\n- **Why it matters:** ESP32 + GPS + WiFi can draw up to 500mA\n- **Solution:** Use quality USB cable and powered USB port (not USB hub)\n- **Symptom:** Random resets, brownouts, WiFi disconnections\n\n### Hardware Assembly Mistakes\n\n**❌ Using 5V instead of 3.3V for GPS power**\n- **Why it matters:** Most GPS modules are 3.3V only, 5V will damage them\n- **Solution:** Connect GPS VCC to ESP32 **3.3V pin**, never 5V\n- **Result:** Permanent GPS module damage\n\n**❌ Weak solder connections for motorcycle use**\n- **Why it matters:** Vibration will eventually break cold solder joints\n- **Solution:** Use proper soldering technique or crimped connectors\n- **Symptom:** Intermittent GPS connection, random disconnections\n\n**❌ GPS antenna placement under metal or carbon fiber**\n- **Why it matters:** Metal and carbon fiber block GPS signals completely\n- **Solution:** Place antenna under plastic fairings/seat cowls only\n- **Symptom:** Never gets satellite fix, satellite count always 0\n\n### Configuration Mistakes\n\n**❌ Not saving GPS configuration to flash**\n- **Why it matters:** Configuration is lost when GPS powers off\n- **Solution:** In u-center, send UBX-CFG-CFG command to save to flash\n- **Symptom:** GPS works after configuration but reverts on next power-on\n\n**❌ Mismatched baudrate between GPS and ESP32**\n- **Why it matters:** Serial communication requires matching speeds\n- **Solution:** Set GPS to 115200 baud, matches `GPS_STANDARD_BAUD_RATE` in code\n- **Symptom:** Garbled data, no GPS messages received\n\n**❌ Forgetting to enable required NMEA messages**\n- **Why it matters:** Apps need specific messages (GGA, RMC minimum)\n- **Solution:** Load app preset or manually enable messages in u-center\n- **Symptom:** App connects but shows \"no GPS data\"\n\n**Pro tip:** Follow the Quick Start Guide step-by-step and verify each stage before moving to the next. Most issues are caught early this way.\n\n---\n\n## HowTo\n\n### Daily Usage\n\n1. Turn on the ESP32 and wait a few minutes for the GPS to get a fix on position (on BN devices, the red led will blink every second)\n2. Open your preferred mobile app and connect it to your BonoGPS-*ABCD* device (ABCD is a combination of 4 letters and numbers unique to your ESP32 device)\n3. Enjoy your ride!\n\nMost runtime configurations are managed via its web-based interface: you can use your phone or any device with a web browser which is able to connect to either the built-in Access Point the BonoGPS provides or (if you are home and you have configured the WiFi Client credentials) [http://bonogps.local](http://bonogps.local)\n\nThe local built-in access point will be named BonoGPS-*ABCD* device (ABCD is a combination of 4 letters and numbers unique to your ESP32 device) and the password to it is in the source code (you can change it to your discretion - it's simply meant to avoid anyone connecting by mistake)\n\n![Main page of web configuration panel from mobile device](software/using/webinterface_root_mobile.png)\n\n![Main page of web configuration panel from laptop](software/using/webinterface_root_laptop.png)\n\n- **GPS runtime settings:** GPS messages, rate of updates, serial port speed\n- **Connections:** List clients, enable BLE/BT-SPP connectivity, enable/disable the builtin TCP-IP messages repeater, switch between WiFi client to a well-known WiFi network or built-in Access Point\n- **Device:** Put GPS in powersaving for some time, Disable WiFi, load preset configurations, save current configuration, collect information about current status of the device, save WiFi credentials for client mode restart the ESP32\n\nThe BOOT button (or another button of your choice) allows you to loop between WiFi modes on the fly:\n\n- short press: toggle between WiFi Access Point (built in led, usually blue, slowly blinking 500 ms cycle) and no WiFi (built in led off)\n- long press (at least 2 seconds): enable WiFi Client so that you can reach the unit from your preferred WiFi network (internal led/blue led light flashes rapidly with a 250 ms cycle)\n\n#### Save a configuration\n\nIf you load a preset or if you change a runtime settings, you can preserve it across restart of the device.\n\nGo to *Device \u003e Save Config* and you'll find these options\n\n![Save Config page](software/using/webinterface_saveconfig.png)\n\nFor convenience, the WiFi status (Start its own AP, or connect to a local WiFi) can be excluded or saved separately.\n\n### Connecting to an app\n\nThere are many mobile apps to log lap times, few accept custom devices, in particular on iOS. The ones below are tested.\n\n| App | Platform | Connection | Max Refresh | Tested Version | Setup Guide |\n| --- | -------- | ---------- | ----------- | -------------- | ----------- |\n| [Harry's Lap Timer](https://www.gps-laptimer.de) | iOS | **BLE** (recommended), TCP-IP | 20Hz (BLE) | v24.9.1 | [Guide](software/connecting/harrylaptimer) |\n| [Harry's Lap Timer](https://www.gps-laptimer.de) | Android | **BT-SPP** (recommended), TCP-IP | 10Hz | v24.9.1 | [Guide](software/connecting/harrylaptimer) |\n| [TrackAddict](https://www.hptuners.com/product/trackaddict-app/) | Android | BT-SPP | 10Hz | v4.6.0 | [Guide](software/connecting/trackaddict) |\n| [RaceChrono](https://racechrono.com/) | iOS | TCP-IP | 10Hz | v7.0.10 | [Guide](software/connecting/racechrono) |\n| [RaceChrono](https://racechrono.com/) | Android | BT-SPP | 10Hz | v7.0.10 | [Guide](software/connecting/racechrono) |\n| [RaceTime](https://www.racetimeapp.com/en/) | Android | BT-SPP | 10Hz | v3.3.8 lite | [Guide](software/connecting/racetime) |\n\n**Note:** Recommended connection methods are shown in **bold**. See detailed setup instructions in each guide.\n\nYou can load a preset configuration from the configuration page selecting *Device \u003e Load Preset* and then choosing your mobile phone device and app combination (when there are alternatives, the recommended option is in bold)\n\n![Loading presets](software/using/webinterface_loadpreset.png)\n\n## Hardware build instructions\n\n**⏱️ Time:** 30-60 minutes | **🎯 Difficulty:** Beginner (basic soldering skills helpful)\n\nThe minimum build is a ublox M8 series GPS receiver module connected to an ESP32:\n\n- TX/RX from the GPS to a serial port (default in the code is UART2/Serial2) on ESP32. Remember: you need to connect RX on one device to TX on the other and viceversa\n- the GPS power pins to ESP32: VCC to 3v3, GND to GND\n\nBN220 comes with a 4 pin adapter cable for GND TX RX VCC, while BN880 includes 2 additionals pins for SDA and SCL of the IMU which are not used so you should leave them unconnected.\n\nSchematics are relatively simple\n\n- power the GPS module (3.3V on ESP32 to VCC on GPS receiver, GND on ESP32 to GND on GPS receiver)\n- connect GPS RX to ESP32 UART2 TX and GPS TX to ESP32 UART2 RX (RX and TX are switched: GPS transmits, ESP32 receives)\n\n![Schematics](hardware/esp32/esp32_to_gps_schem.png)\n\nExamples are in [hardware/assembled](hardware/assembled) including an example with more options using an ESP32 device type Lolin D32 Pro which has an internal battery charger [hardware/esp32/lolin_d32_pro.md](hardware/esp32/lolin_d32_pro.md)\n\n**See also:**\n- [GPS Configuration Guide](hardware/GPS) - Configure GPS before use\n- [Assembly Troubleshooting](hardware/assembled#hardware-assembly-troubleshooting) - Common wiring issues\n- [LOLIN D32 PRO Specific Guide](hardware/esp32/lolin_d32_pro.md) - Battery charging setup\n\n### GPS Choice and setup preconfiguration\n\n**⏱️ Time:** 30-45 minutes | **🎯 Difficulty:** Intermediate | **Prerequisites:** USB-to-serial adapter, u-center software\n\nThanks to needs of a very active drone community, there are a lot of inexpensive GPS receivers: some considerations on performance/accuracy/cost are reported [in the hardware/GPS folder](hardware/GPS).\n\nWhat you need to configure is documented [in the hardware/GPS folder](hardware/GPS): this is **important**, the performances of your GPS won't be optimal until you do, or the whole setup will not work at all.\n\n**See also:**\n- [GPS Module Comparison](hardware/GPS#performance-comparison) - Detailed specs for each module\n- [GPS Troubleshooting](hardware/GPS#gps-hardware-troubleshooting) - Module-specific issues\n- [u-blox u-center Guide](hardware/GPS) - Configuration software instructions\n\n## Software build instructions\n\n**⏱️ Time:** 20-45 minutes (Arduino IDE: 20-30 min, PlatformIO: 30-45 min first time) | **🎯 Difficulty:** Beginner to Intermediate | **Prerequisites:** Arduino IDE or VS Code with PlatformIO, USB cable\n\nThis code is developed specifically for ESP32, and tested with [PlatformIO](https://platformio.org/) (main development platform) and the [Arduino IDE version 2 (2.3.4)](https://www.arduino.cc/en/software). More information on what libraries are needed and software organization [in the software/building folder](software/building).\n\n**See also:**\n- [Build Troubleshooting](software/building#build-troubleshooting) - Library versions, compilation errors\n- [Board Settings](include/README.md) - Pin definitions and configurations\n- [Connecting to Apps](software/connecting) - After successful build\n\n## Technical Specifications\n\n### Performance Expectations\n\n**GPS Accuracy:**\n- **Horizontal position:** 2-3 meters (6-10 feet) typical with M8/M10 chipsets\n- **Speed accuracy:** ±0.1 km/h at constant velocity\n- **Update rates:** 10Hz (M8 modules), 25Hz (M10 modules)\n- **Cold start time:** 5-15 minutes (first power-on)\n- **Hot start time:** 1-5 seconds (after recent fix)\n- **Signal quality:** C/N0 values typically 30-40 dBHz (higher is better)\n\n**Power Consumption:**\n- **ESP32:** 80-160mA (varies with WiFi/Bluetooth activity)\n- **GPS module:** 30-80mA (depends on module and fix status)\n- **LED indicators:** 10-40mA\n- **Total typical:** 250-350mA average during operation\n- **Peak consumption:** Up to 500mA when WiFi and GPS are both active\n\n**Battery Life Examples:**\n- 650mAh battery: ~2-2.5 hours runtime\n- 1000mAh battery: ~3-4 hours runtime\n- 2000mAh battery: ~6-8 hours runtime (full track day)\n\n**Note:** Actual battery life depends on WiFi/Bluetooth usage, GPS update rate, and environmental conditions.\n\n### Connectivity Specifications\n\n**WiFi:**\n- **Standard:** 802.11 b/g/n (2.4 GHz only)\n- **Range:** ~30-50 meters open air (depends on environment)\n- **Access Point mode:** Supports up to 4 simultaneous clients\n- **TCP server port:** 1818 (configurable)\n- **mDNS hostname:** bonogps.local\n\n**Bluetooth Low Energy (BLE):**\n- **Standard:** Bluetooth 4.2 / 5.0 (depends on ESP32 module)\n- **Range:** ~10-30 meters typical\n- **Service UUID:** 1819 (Location and Navigation Service)\n- **Max throughput:** ~20Hz GPS data with minimal satellite info\n- **iOS support:** Full (recommended connection method)\n\n**Bluetooth Classic (BT-SPP):**\n- **Standard:** Bluetooth 2.0 SPP (Serial Port Profile)\n- **Range:** ~10-30 meters typical\n- **Baudrate:** 115200 (matches GPS UART)\n- **Max throughput:** ~10Hz GPS data with satellite info\n- **Android support:** Full (recommended connection method)\n\n### Build Size and Memory\n\n**Flash Memory Usage:**\n- **With BLE + BT-SPP:** ~1.5-1.7 MB (requires Minimal SPIFFS partition)\n- **With BLE only:** ~1.3-1.4 MB\n- **With BT-SPP only:** ~1.2-1.3 MB\n- **Minimum partition:** 1.9 MB app space required\n\n**RAM Usage:**\n- **ESP32 SRAM:** ~120-180 KB used (out of 320 KB available)\n- **PSRAM:** Optional, helps with stability if available (LOLIN D32 PRO has 4MB)\n\n**SPIFFS Storage:**\n- **Configuration files:** ~2-4 KB\n- **Reserved space:** 190 KB (with Minimal SPIFFS partition)\n\n### Supported NMEA Messages\n\n**Standard output messages:**\n- `GxGGA` - Global Positioning System Fix Data\n- `GxRMC` - Recommended Minimum Specific GPS Data\n- `GxGBS` - GNSS Satellite Fault Detection (accuracy estimates)\n- `GxGSA` - GPS DOP and Active Satellites (optional, polled)\n- `GxGSV` - GPS Satellites in View (optional, polled)\n- `GxVTG` - Track Made Good and Ground Speed\n- `GxZDA` - Time and Date\n\n**Talker ID support:**\n- `GN` - Multi-constellation GNSS (GPS+GLONASS+Galileo+BeiDou)\n- `GP` - GPS only (required by some apps like RaceChrono)\n\n**Message rates:** Configurable from 1Hz to 25Hz (hardware dependent)\n\n### Environmental Specifications\n\n**Operating conditions:**\n- **Temperature:** -20°C to +70°C (-4°F to 158°F) typical\n- **Note:** Li-Ion batteries should not be charged below 0°C (32°F)\n- **Humidity:** Most ESP32 boards are not waterproof without enclosure\n- **Vibration:** Solder connections recommended for motorcycle use\n- **Mounting:** GPS antenna requires clear sky view (metal/carbon blocks signal)\n\n**GPS antenna considerations:**\n- **Active antennas:** Better signal quality, require 3.3V power, ~50mA draw\n- **Passive antennas:** Lower signal quality, no extra power required\n- **Placement:** Best under plastic fairings/seat cowls, avoid metal/carbon\n\n### Limitations and Known Issues\n\n**Connection limitations:**\n- **BT-SPP reconnection:** Android may require device restart or re-pairing\n- **BLE throughput:** Limited to ~20Hz with full NMEA messages\n- **WiFi TCP:** Single client at a time for GPS data stream\n- **Memory pressure:** Running BLE + BT-SPP + WiFi simultaneously may cause instability\n\n**GPS limitations:**\n- **Indoor use:** GPS will not work indoors or under metal roofs\n- **Urban canyons:** Tall buildings can degrade accuracy\n- **Tree cover:** Dense foliage can reduce satellite visibility\n- **First fix:** Takes 5-15 minutes on first power-on to download almanac\n\n**Software limitations:**\n- **OTA updates:** Disabled by default to save flash space\n- **Web interface:** Basic HTML/CSS, optimized for mobile browsers\n- **Configuration backup:** Manual export/import via web interface\n\nSee [Troubleshooting FAQ](#troubleshooting-and-faq) for solutions to common problems.\n\n## Troubleshooting and FAQ\n\n### Common Issues and Solutions\n\n#### GPS and Hardware Issues\n\n**Q: My GPS is not getting a fix / takes very long to acquire satellites**\n\n**A:** Several factors can affect GPS acquisition time:\n- **First time setup:** Cold start can take 5-15 minutes to download almanac data\n- **Antenna placement:** Ensure the GPS antenna has clear view of the sky. The BN-880 LED should blink once per second when it has a fix\n- **Antenna orientation:** For BN-880/BK-880, the antenna should face upward (skyward)\n- **Indoor use:** GPS will not work indoors or in areas with obstructed sky view\n- **Configuration:** Verify your GPS is properly configured with the correct baudrate (115200) and messages enabled. See [GPS configuration guide](hardware/GPS)\n\n**Q: No GPS data is reaching my mobile app**\n\n**A:** Troubleshooting steps:\n1. Check that the GPS has a fix (BN devices: red LED blinking every second)\n2. Verify the baudrate matches: GPS port should be 115200 (check `GPS_STANDARD_BAUD_RATE` in code)\n3. Confirm correct NMEA messages are enabled for your app (load the appropriate preset)\n4. Check TX/RX wiring: GPS TX → ESP32 RX, GPS RX → ESP32 TX\n5. Open an [issue](https://github.com/renatobo/bonogps/issues) with details if problem persists\n\n**Q: Which GPS module should I buy?**\n\n**A:** See the [GPS comparison table](#for-the-sw-engineer--maker) in this README. Quick recommendations:\n- **Best performance:** BK880 or BK280 (M10 chipset, 25Hz, ~$35-45)\n- **Good balance:** BN880 (M8 chipset with active antenna, 10Hz, ~$25)\n- **Budget option:** BN220 (M8 chipset with passive antenna, 10Hz, ~$15-20)\n\nActive antennas provide significantly better signal quality. Avoid NEO-M8N if you need multiple GNSS constellations.\n\n#### Bluetooth and Connection Issues\n\n**Q: ESP32 reboots when I change Bluetooth settings / No Bluetooth available**\n\n**A:** This is typically caused by:\n- **Insufficient partition space:** Ensure you're using the \"Minimal SPIFFS\" partition scheme (1.9MB app space)\n- **Memory issues:** Both BLE and BT-SPP enabled simultaneously can cause memory pressure. Try disabling one if not needed\n- **Library conflicts:** Ensure you're using NimBLE-Arduino version 2.x (not 1.x)\n- Check the [closed issue #60](https://github.com/renatobo/bonogps/issues/60) for resolution details\n\n**Q: Can't reconnect to RaceChrono via BT-SPP after first disconnect**\n\n**A:** Known issue with Android BT-SPP. Workarounds:\n- Restart the ESP32 device\n- \"Forget\" the Bluetooth device on Android and re-pair\n- Restart the RaceChrono app\n- See [issue #30](https://github.com/renatobo/bonogps/issues/30) for ongoing discussion\n\n**Q: BLE connection issues with Harry's Lap Timer on iOS**\n\n**A:** Common solutions:\n- Ensure BLE is enabled in the web configuration\n- Verify the service UUID is **1819** and characteristic UUID is **2A67**\n- Device name should be `BonoGPS-XXXX` (check web interface header)\n- iOS may cache old Bluetooth data - try restarting your iPhone\n- BLE works best at 20Hz or lower with GSA/GSV polling disabled or at low frequency (every 5 seconds)\n\n#### WiFi and Web Interface Issues\n\n**Q: Can't access the web interface at bonogps.local**\n\n**A:** Troubleshooting:\n- **Android users:** Use [http://10.0.0.1](http://10.0.0.1) instead (Android doesn't support mDNS by default)\n- **Access Point mode:** Connect to the BonoGPS-XXXX WiFi network first (password is in the source code)\n- **Client mode:** Ensure your device is on the same WiFi network as BonoGPS\n- Check the built-in LED: Slow blink (500ms) = AP mode, Fast blink (250ms) = Client mode\n- Use the BOOT button to cycle between WiFi modes (short press for AP/off, long press for Client)\n\n**Q: How do I change WiFi modes?**\n\n**A:** Use the BOOT button (or external button on LOLIN D32 PRO):\n- **Short press:** Toggle between Access Point mode and WiFi off\n- **Long press (2+ seconds):** Switch to Client mode (connects to your saved WiFi network)\n\nThe built-in blue LED indicates the mode:\n- Slow blinking (500ms cycle): Access Point active\n- Fast blinking (250ms cycle): Client mode active\n- Off: WiFi disabled\n\n#### Build and Compilation Issues\n\n**Q: Arduino IDE compilation fails with NimBLE errors**\n\n**A:** Solutions:\n- Use NimBLE-Arduino version **2.x** (not 1.x or 3.x)\n- Install the exact library versions from `platform.ini` `lib_deps` section\n- Use EasyButton version **2.0.1** specifically (newer versions have breaking changes)\n- Ensure you selected \"Minimal SPIFFS (1.9MB)\" partition scheme\n- See [issue #50](https://github.com/renatobo/bonogps/issues/50) for NimBLE-specific solutions\n\n**Q: Build fails with \"not enough space\" or partition errors**\n\n**A:** The compiled binary is large due to Bluetooth stacks:\n- Select `Tools \u003e Partition Scheme \u003e Minimal SPIFFS (1.9MB APP)`\n- In PlatformIO: use `board_build.partitions = min_spiffs.csv`\n- Disable unused features (BLE or BT-SPP) if you only need one connection type\n\n**Q: Git revision macro errors during PlatformIO build**\n\n**A:** The build uses `git_rev_macro.py` to get version info:\n- Clone the repository with git (don't download as ZIP)\n- If issues persist, comment out the script invocation in `platformio.ini`\n- Manually define `GIT_REV` and `GIT_REPO` macros if needed\n\n### App-Specific Issues\n\n**Q: RaceChrono shows weird/incorrect data**\n\n**A:** Check these settings:\n- Main Talker ID must be **GP** (not GN) for RaceChrono\n- Enable only `GPGGA`, `GPRMC`, optionally `GPGSA`/`GPGSV`\n- Load the RaceChrono preset from *Device \u003e Load Preset*\n- See [RaceChrono setup guide](software/connecting/racechrono)\n\n**Q: TrackAddict not receiving data**\n\n**A:** TrackAddict requirements:\n- Requires Main Talker ID = **GP**\n- Must have `GPRMC`, `GPGGA`, and `GPGLL` enabled\n- Only works via BT-SPP on Android\n- Load the TrackAddict preset from the web interface\n\n### Getting Help\n\nIf your issue isn't covered here:\n\n1. Check the [GitHub Discussions](https://github.com/renatobo/bonogps/discussions) - many questions already answered\n2. Review [closed issues](https://github.com/renatobo/bonogps/issues?q=is%3Aissue+is%3Aclosed) for similar problems\n3. Check app-specific guides in [software/connecting](software/connecting)\n4. Open a new [issue](https://github.com/renatobo/bonogps/issues) with:\n   - Your hardware (ESP32 model, GPS model)\n   - Software version and how you built it\n   - What app you're connecting to\n   - Detailed description of the problem\n   - Any error messages or logs\n\n## Possible enhancements and ideas\n\nSee [issues with label enhancement](https://github.com/renatobo/bonogps/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) on the github project\n\n## Glossary\n\n**GPS \u0026 Navigation Terms:**\n\n- **GPS Fix:** When the GPS receiver has locked onto enough satellites (minimum 4) to calculate position. Indicated by LED blinking once per second on BN/BK modules.\n- **Cold Start:** First power-on when GPS has no recent satellite data. Takes 5-15 minutes to download almanac and ephemeris data.\n- **Hot Start:** GPS restart when recent satellite data is still valid. Typically achieves fix in 1-5 seconds.\n- **Warm Start:** GPS restart after some time, when almanac is still valid but ephemeris is outdated. Takes 30-60 seconds.\n- **Satellite Almanac:** Coarse orbital data for all satellites, valid for months. Required for cold start.\n- **Ephemeris:** Precise orbital data for specific satellites, valid for 2-4 hours. Required for accurate positioning.\n- **GNSS (Global Navigation Satellite System):** Umbrella term for all satellite navigation systems (GPS, GLONASS, Galileo, BeiDou).\n- **GPS (Global Positioning System):** US satellite navigation system, one type of GNSS.\n- **M8 / M10:** u-blox GPS chipset generations. M8 supports 10Hz max, M10 supports 25Hz max.\n- **C/N0 (Carrier-to-Noise Ratio):** Signal quality measurement in dBHz. Higher is better (30-40 dBHz typical, 45+ excellent).\n- **HDOP (Horizontal Dilution of Precision):** Geometric accuracy indicator. Lower is better (\u003c1.0 excellent, 1-2 good, \u003e5 poor).\n- **DOP (Dilution of Precision):** Measure of satellite geometry effect on position accuracy.\n\n**GPS Antenna Terms:**\n\n- **Active Antenna:** Has built-in amplifier (LNA), requires power, better signal quality. Typical for BN880/BK880.\n- **Passive Antenna:** No amplifier, cheaper, lower signal quality. Typical for BN220/BK280.\n- **LNA (Low Noise Amplifier):** Built-in amplifier in active antennas that boosts weak GPS signals.\n\n**GPS Message Formats:**\n\n- **NMEA (National Marine Electronics Association):** Standard text format for GPS data (e.g., $GPGGA,123456...).\n- **UBX:** u-blox binary protocol, more compact than NMEA but requires parsing library.\n- **Talker ID:** Two-letter prefix indicating satellite system source:\n  - **GP:** GPS only (US satellites)\n  - **GN:** Multi-constellation GNSS (GPS + GLONASS + Galileo + BeiDou)\n- **NMEA Messages:**\n  - **GGA:** Global Positioning System Fix Data (position, altitude, fix quality)\n  - **RMC:** Recommended Minimum Specific GPS Data (position, speed, course, time)\n  - **GSA:** GPS DOP and Active Satellites (satellite IDs, dilution of precision)\n  - **GSV:** GPS Satellites in View (satellite count, signal strength per satellite)\n  - **GBS:** GNSS Satellite Fault Detection (accuracy estimates)\n  - **VTG:** Track Made Good and Ground Speed (course and speed)\n  - **ZDA:** Time and Date (UTC time and date)\n\n**Connectivity Terms:**\n\n- **BLE (Bluetooth Low Energy):** Low-power Bluetooth standard (Bluetooth 4.0+). Recommended for iOS with Harry's Lap Timer. Max ~20Hz GPS data.\n- **BT-SPP (Bluetooth Serial Port Profile):** Classic Bluetooth serial connection. Recommended for Android. Max ~10Hz with full messages.\n- **TCP-IP:** Network connection over WiFi. Works on both iOS and Android. Single client at a time for GPS stream.\n- **UART (Universal Asynchronous Receiver-Transmitter):** Serial communication protocol between GPS and ESP32.\n- **Baudrate:** Speed of serial communication in bits per second. BonoGPS uses 115200 baud.\n- **mDNS (Multicast DNS):** Network protocol that resolves bonogps.local to IP address. Doesn't work on Android by default.\n\n**ESP32 Terms:**\n\n- **ESP32:** Microcontroller with built-in WiFi and Bluetooth. Brain of BonoGPS device.\n- **Flash Memory:** Non-volatile storage on ESP32 where firmware is stored (~4MB total).\n- **RAM/SRAM:** Volatile memory for program execution (~320KB on standard ESP32).\n- **PSRAM:** Optional extra RAM (4MB on LOLIN D32 PRO) for improved stability.\n- **Partition Scheme:** How flash memory is divided. BonoGPS requires \"Minimal SPIFFS (1.9MB)\" for app space.\n- **SPIFFS:** File system on ESP32 for storing configuration files (~190KB with minimal partition).\n- **OTA (Over-The-Air):** Wireless firmware updates. Disabled by default in BonoGPS to save flash space.\n- **GPIO (General Purpose Input/Output):** Programmable pins on ESP32 for connecting peripherals.\n- **UART2/Serial2:** Second serial port on ESP32, used for GPS communication (TX=GPIO17, RX=GPIO16 on DevKit).\n\n**Build \u0026 Development Terms:**\n\n- **Arduino IDE:** Beginner-friendly development environment for programming ESP32.\n- **PlatformIO:** Professional IDE extension for VS Code, preferred for BonoGPS development.\n- **Library:** Pre-written code package that adds functionality (e.g., NimBLE-Arduino for Bluetooth).\n- **NimBLE:** Lightweight Bluetooth Low Energy library for ESP32. BonoGPS requires version 2.x.\n- **Preset:** Pre-configured settings for specific apps, loaded via web interface (Device \u003e Load Preset).\n\n**u-blox Configuration Terms:**\n\n- **u-center:** Windows software from u-blox for configuring GPS modules.\n- **UBX-CFG-xxx:** Configuration commands for u-blox GPS modules (e.g., UBX-CFG-PRT for port settings).\n- **Save to Flash:** Persist GPS configuration so it survives power cycles. Critical step often forgotten!\n\n**Hardware Terms:**\n\n- **DevKit:** Generic ESP32 development board, most common and cheapest option (~$8-12).\n- **LOLIN D32 PRO:** Premium ESP32 board with battery charger, PSRAM, and TF card slot (~$15-20).\n- **Li-Ion / LiPo:** Rechargeable lithium battery types. 3.7V nominal, charge to 4.2V, discharge to 3.0V minimum.\n- **JST Connector:** Small 2-pin connector commonly used for batteries.\n- **VCC:** Power supply voltage pin (3.3V for GPS modules).\n- **GND:** Ground / 0V reference voltage pin.\n- **TX (Transmit):** Data output pin. GPS TX connects to ESP32 RX.\n- **RX (Receive):** Data input pin. GPS RX connects to ESP32 TX.\n\n**App-Specific Terms:**\n\n- **Harry's Lap Timer (HLT):** Most feature-rich lap timer app, only iOS app supporting BLE GPS.\n- **RaceChrono:** Lap timer with cleanest UX, requires GP Talker ID.\n- **TrackAddict:** Android-only lap timer, requires GP Talker ID.\n- **Hz (Hertz):** Updates per second. 10Hz = 10 position updates per second. 25Hz = 25 updates per second (M10 modules only).\n\n## Credits and tools\n\n- Very valuable information from the mobile apps developers: [Harry's Lap Timer forum](http://forum.gps-laptimer.de/viewforum.php?f=2), [HP Tuner Track Adict forum](https://forum.hptuners.com/forumdisplay.php?74-TrackAddict), [RaceChrono forum](https://racechrono.com/forum/categories/diy-builds)\n- Email conversations with Harald Schlangmann (Harry's Lap Timer) and Roberto Morini (Racetime) who I thank for the time and effort in developing and supporting their apps\n- There are several other similar projects on github, a few from which I learned a lot: [RaceChronoDYI-TBeam](https://github.com/0x8008135/RaceChronoDYI-TBeam) [RaceChrono BLE DIY device (GPS and CAN-Bus)](https://github.com/aollin/racechrono-ble-diy-device) [DAWA](https://github.com/quichedood/DAWA-6.x)\n- Screenshot framing by [Mockuphone](https://mockuphone.com/) and [Android developers marketing tools\n](https://developer.android.com/distribute/marketing-tools/device-art-generator)\n- [The GPS Dictionary](https://www.u-blox.com/sites/default/files/the_gps_dictionary.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenatobo%2Fbonogps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frenatobo%2Fbonogps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenatobo%2Fbonogps/lists"}