{"id":13613360,"url":"https://github.com/inmcm/micropyGPS","last_synced_at":"2025-04-13T15:33:04.191Z","repository":{"id":2056069,"uuid":"27653299","full_name":"inmcm/micropyGPS","owner":"inmcm","description":"A Full Featured GPS NMEA-0183  sentence parser for use with Micropython and the PyBoard embedded platform","archived":false,"fork":false,"pushed_at":"2023-02-18T17:59:57.000Z","size":98,"stargazers_count":367,"open_issues_count":15,"forks_count":119,"subscribers_count":48,"default_branch":"master","last_synced_at":"2025-04-05T09:08:46.225Z","etag":null,"topics":["gps","gps-library","micropython","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inmcm.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}},"created_at":"2014-12-06T23:49:08.000Z","updated_at":"2025-03-28T01:32:24.000Z","dependencies_parsed_at":"2023-07-07T14:16:18.757Z","dependency_job_id":null,"html_url":"https://github.com/inmcm/micropyGPS","commit_stats":{"total_commits":68,"total_committers":12,"mean_commits":5.666666666666667,"dds":0.2647058823529411,"last_synced_commit":"f6c2b76a3bedf7d85e77fc6d52e0346b68361ce2"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inmcm%2FmicropyGPS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inmcm%2FmicropyGPS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inmcm%2FmicropyGPS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inmcm%2FmicropyGPS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inmcm","download_url":"https://codeload.github.com/inmcm/micropyGPS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248736123,"owners_count":21153537,"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":["gps","gps-library","micropython","python","python3"],"created_at":"2024-08-01T20:00:45.074Z","updated_at":"2025-04-13T15:33:03.883Z","avatar_url":"https://github.com/inmcm.png","language":"Python","readme":"# micropyGPS\n\n## Overview\n\nmicropyGPS is a full featured GPS NMEA sentence parser for use with [MicroPython] and the PyBoard embedded\nplatform. It's also fully compatible with Python 3.x\n\nFeatures:\n\n - Parses and verifies most of the important [NMEA-0183] output messages into easily handled data structures\n - Provides helper methods to interpret, present, log, and manipulate the GPS data\n - Written in pure Python 3.x using only the standard libraries available in Micropython\n - Implemented as a single class within a single file for easy integration into an embedded project\n - Parser written with a serial UART data source in mind; works on a single character at a time with\n   robust error handling for noisy embedded environments\n - Modeled after the great [TinyGPS] Arduino library\n\n## Install / uninstall\n\nInstall by cloning from git and running install via setuptools.\n\n```sh\ngit clone https://github.com/inmcm/micropyGPS.git\npython setup.py install\n```\n\nOr install directly from github using pip.\n\n```sh\npip install git+https://github.com/inmcm/micropyGPS.git\n```\n\nTo uninstall use the following pip command.\n\n```sh\npip uninstall micropyGPS\n```\n   \n   \n## Basic Usage\n\nmicropyGPS is easy to use: copy micropyGPS.py into your project directory and import the MicropyGPS class into your script. From\nthere, just create a new GPS object and start feeding it data using the ```update()``` method. After you've feed it an entire valid sentence, it will return the sentence type and the internal GPS attributes will be updated. The example below shows the parsing of an RMC sentence and the object returns a tuple with the current latitude data\n\n```sh\n\u003e\u003e\u003e from micropyGPS import MicropyGPS\n\u003e\u003e\u003e my_gps = MicropyGPS()\n\u003e\u003e\u003e my_sentence = '$GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62'\n\u003e\u003e\u003e for x in my_sentence:\n...     my_gps.update(x)\n...\n'GPRMC'\n\u003e\u003e\u003e my_gps.latitude\n(37, 51.65, 'S')\n```\nThe object will continue to accept new characters and parse sentences for as long as it exists. Each type of sentence parsed can update different internal attributes in your GPS object.\n\nIf you have `pytest` installed, running it with the ```test_micropyGPS.py``` script will parse a number of example sentences of various types and test the various parsing, logging, and printing mechanics.\n\n```sh\n$ pytest -svvv test_micropyGPS.py\n```\n\n### Currently Supported Sentences \n\n* GPRMC\n* GLRMC\n* GNRMC\n* GPGLL\n* GLGLL\n* GNGLL\n* GPGGA\n* GLGGA\n* GNGGA\n* GPVTG\n* GLVTG\n* GNVTG\n* GPGSA\n* GLGSA\n* GNGSA\n* GPGSV\n* GLGSV\n\n\n### Position Data\nData successfully parsed from valid sentences is stored in easily accessible object variables. Data with multiple components (like latitude and longitude) is stored in tuples.\n```sh\n## Latitude is 37° 51.65' S\n\u003e\u003e\u003e my_gps.latitude\n(37, 51.65, 'S')\n# Longitude is 145° 7.36' E\n\u003e\u003e\u003e my_gps.longitude\n(145, 7.36, 'E')\n# Course is 54.7°\n\u003e\u003e\u003e my_gps.course\n54.7\n# Altitude is 280.2 meters\n\u003e\u003e\u003e my_gps.altitude\n280.2\n# Distance from ideal geoid is -34 meters\n\u003e\u003e\u003e my_gps.geoid_height\n-34.0\n```\nCurrent speed is stored in a tuple of values representing knots, miles per hours and kilometers per hour\n```sh\n\u003e\u003e\u003e my_gps.speed\n(5.5, 6.3305, 10.186)\n```\n\n### Time and Date\nThe current UTC time is stored (hours,minutes,seconds)\n```sh\n\u003e\u003e\u003e my_gps.timestamp\n(8, 18, 36.0)\n\u003e\u003e\u003e my_gps.date\n(22, 9, 05)\n```\nThe timezone can be automatically adjusted for using the by setting the ```local_offset``` when you create the object or anytime after. Setting it to ```-5``` means you are on Eastern Standard time in the United States.\n```sh\n\u003e\u003e\u003e my_gps = MicropyGPS(-5)\n\u003e\u003e\u003e my_gps.local_offset\n-5\n# Update With Timestamp Sentence Data...\n\u003e\u003e\u003e my_gps.timestamp\n(3, 18, 36.0)\n```\n\nThe current UTC date is stored (day,month,year). **NOTE:** The date is not currently adjusted to match the timezone set in ```local_offset```. \n```sh\n\u003e\u003e\u003e my_gps.date\n(22, 9, 05)\n```\n\n### Satellite Data\nSignal quality and individual satellite information is collected from GSV, GSA, and GGA sentences and made available in the following variables.\n```sh\n\u003e\u003e\u003e my_gps.satellites_in_use\n7\n\u003e\u003e\u003e my_gps.satellites_used\n[7, 2, 26, 27, 9, 4, 15]\n# Fix types can be: 1 = no fix, 2 = 2D fix, 3 = 3D fix\n\u003e\u003e\u003e my_gps.fix_type\n3\n# Dilution of Precision (DOP) values close to 1.0 indicate excellent quality position data\n\u003e\u003e\u003e my_gps.hdop  \n1.0\n\u003e\u003e\u003e my_gps.vdop\n1.5\n\u003e\u003e\u003e my_gps.pdop\n1.8\n```\n The ```satellite_data_updated()``` method should be check to be ```True``` before trying to read out individual satellite data. This ensures all related GSV sentences are parsed and satellite info is complete\n```sh\n\u003e\u003e\u003e my_gps.satellite_data_updated()\nTrue\n# Satellite data is a dict where the key is the satellite number and the value pair is a tuple containing (Elevation, Azimuth, SNR (if available))\n\u003e\u003e\u003e my_gps.satellite_data \n{19: (5, 273, None), 32: (5, 303, None), 4: (22, 312, 26), 11: (9, 315, 16), 12: (19, 88, 23), 14: (64, 296, 22), 15: (2, 73, None), 18: (54, 114, 21), 51: (40, 212, None), 21: (16, 175, None), 22: (81, 349, 25), 24: (30, 47, 22), 25: (17, 127, 18), 31: (22, 204, None)}\n# Returns just the satellite PRNs visible\n\u003e\u003e\u003e my_gps.satellites_visible()\n[19, 32, 4, 11, 12, 14, 15, 18, 51, 21, 22, 24, 25, 31]\n```\n\n### GPS Statistics\nWhile parsing sentences, the MicropyGPS object tracks the number of number of parsed sentences as well as the number of CRC failures. ```parsed_sentences``` are those sentences that passed the base sentence catcher with clean CRCs. ```clean_sentences``` refers to the number of sentences parsed by their specific function successfully.\n```sh\n\u003e\u003e\u003e my_gps.parsed_sentences\n14\n\u003e\u003e\u003e my_gps.clean_sentences\n14\n\u003e\u003e\u003e my_gps.crc_fails\n0\n```\nThe amount of real time passed since the last sentence with valid fix data was parse is also made available. **NOTE:** On the pyBoard, this value is returned in milliseconds while on Unix/Windows it is returned in seconds.\n```sh\n# Assume running on pyBoard\n\u003e\u003e\u003e my_gps.time_since_fix()\n3456\n```\n\n### Logging\nmicropyGPS currently can do very basic automatic logging of raw NMEA sentence data to a file. Any valid ASCII character passed into the parser, while the logging is enabled, is logged to a target file.  This is useful if processing GPS sentences, but want to save the collected data for archive or further analysis. Due to the relative size of the log files, it's highly recommended to use an SD card as your storage medium as opposed to the emulated memory on the STM32 micro. All logging methods return a boolean if the operation succeeded or not.\n```sh\n# Logging can be started at any time with the start_logging()\n\u003e\u003e\u003e my_gps.start_logging('log.txt')\nTrue\n# Arbitrary strings can be written into the log file with write_log() method\n\u003e\u003e\u003e my_gps.write_log('Some note for the log file')\nTrue\n# Stop logging and close the log file with stop_logging()\n\u003e\u003e\u003e my_gps.stop_logging()\nTrue\n```\n\n### Prettier Printing\nSeveral functions are included that allow for GPS data to be expressed in nicer formats than tuples and ints.\n```sh\n\u003e\u003e\u003e my_gps.latitude_string()\n\"41° 24.8963' N\"\n\u003e\u003e\u003e my_gps.longitude_string()\n\"81° 51.6838' W\"\n\u003e\u003e\u003e my_gps.speed_string('kph')\n'10.186 km/h'\n\u003e\u003e\u003e my_gps.speed_string('mph')\n'6.3305 mph'\nmy_gps.speed_string('knot')\n'5.5 knots'\n# Nearest compass point based on current course\nmy_gps.compass_direction()\n'NE'\n\u003e\u003e\u003e my_gps.date_string('long')\n'September 13th, 2098'\n# Note the correct century should be provided for GPS data taken in the 1900s\n\u003e\u003e\u003e my_gps.date_string('long','19')\n'September 13th, 1998'\n\u003e\u003e\u003e my_gps.date_string('s_mdy')\n'09/13/98'\n\u003e\u003e\u003e my_gps.date_string('s_dmy')\n'13/09/98'\n```\n## Pyboard Usage\n\nTest scripts are included to help get started with using micropyGPS on the [pyboard] platform. These scripts can be copied over to the pyboards internal memory or placed on the SD Card. Make sure, when running them on the pyboard, to rename script you're using to **main.py** or update **boot.py** with the name of script you wish to run.\n\n - **uart_test.py** is a simple UART echo program to test if both your GPS is hooked up and UART is configured correctly. Some of the standard NMEA sentences should print out once a second (or faster depending on your GPS update rate) if everything is OK\n - **sentence_test.py** will try and parse all incoming characters from the UART. This script requires micropyGPS.py be present in the same area of storage (SD Card or internal). Whenever a set of characters comprising a valid sentence is received and parsed, the script will print the type of sentence.\n - **GPIO_interrupt_updater.py** is an example of how to use external interrupt to trigger an update of GPS data. In this case, a periodic signal (1Hz GPS output) is attached to pin X8 causing a mass parsing event every second.\n\nAdjusting the baud rate and update rate of the receiver can be easily accomplished with my companion [MTK_command] script\n\nAn example of how to hookup the pyboard to the Adafruit [Ultimate GPS Breakout] (minus the PPS signal needed in the external interrupt example) is shown below.\n\n![hookup](http://i.imgur.com/yd4Mjka.jpg?1)\n\n## ESP32\nYou can follow the setup instructions for the pyboard. The only difference is, that you shoud use micropyGPS as a [frozen module]. Otherwise there will be exceptions, because there is not enough heap space available.\n\n## Other Platforms\nAs mentioned above, micropyGPS also runs on Python3.x (that's where most of the development was done!). This is useful for testing code or just parsing existing log files. \n\nBeyond the pyBoard and ESP32, micropyGPS should run on other embedded platforms that have an Python3 interpreter such as the Raspberry Pi and BeagleBone boards. These other devices are currently untested.\n\n[Micropython]:https://micropython.org/\n[frozen module]:https://learn.adafruit.com/micropython-basics-loading-modules/frozen-modules\n[NMEA-0183]:http://aprs.gids.nl/nmea/\n[TinyGPS]:http://arduiniana.org/libraries/tinygps/ \n[pyboard]:http://docs.micropython.org/en/latest/pyboard/pyboard/quickref.html\n[MTK_command]:https://github.com/inmcm/MTK_commands\n[Ultimate GPS Breakout]:http://www.adafruit.com/product/746\n","funding_links":[],"categories":["Libraries","精选驱动库"],"sub_categories":["Communications","通讯类"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finmcm%2FmicropyGPS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finmcm%2FmicropyGPS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finmcm%2FmicropyGPS/lists"}