uploaded 8 months ago
PA1010D I2C GPS driver


# PA1010D I2C GPS driver

[![Component Registry](https://components.espressif.com/components/igrr/pa1010d/badge.svg)](https://components.espressif.com/components/igrr/pa1010d) [![Example build](https://github.com/igrr/pa1010d/actions/workflows/build_example.yml/badge.svg)](https://github.com/igrr/pa1010d/actions/workflows/build_example.yml)

This repository contains an ESP-IDF driver for a PA1010D GPS receiver connected over I2C.

It is used for demonstration purposes in the talk ["Developing, Publishing, and Maintaining Components for ESP-IDF"](https://igrr.github.io/edc23/) at Espressif DevCon23.

## Using the component

Run the following command in your ESP-IDF project to install this component:
idf.py add-dependency "igrr/pa1010d"

## Example

To run the provided example, create it as follows:

idf.py create-project-from-example "igrr/pa1010d:pa1010d-example"

Then build as usual:
cd pa1010d-example
idf.py build

And flash it to the board:
idf.py -p PORT flash monitor

The example uses GPIOs 4 and 5 for SDA and SCL, respectively.

## License

This component is provided under Apache 2.0 license, see [LICENSE](LICENSE.md) file for details.

## Contributing

Please check [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.


# API Reference

## Header files

- [include/pa1010d.h](#file-includepa1010dh)

## File include/pa1010d.h

## Structures and Types

| Type | Name |
| ---: | :--- |
| struct | [**pa1010d\_config\_t**](#struct-pa1010d_config_t) <br>_PA1010D driver configuration._ |
| typedef struct pa1010d\_t \* | [**pa1010d\_handle\_t**](#typedef-pa1010d_handle_t)  <br>_PA1010D driver handle._ |

## Functions

| Type | Name |
| ---: | :--- |
|  esp\_err\_t | [**pa1010d\_deinit**](#function-pa1010d_deinit) (pa1010d\_handle\_t handle) <br>_Deinitialize the PA1010D driver._ |
|  esp\_err\_t | [**pa1010d\_get\_nmea\_msg**](#function-pa1010d_get_nmea_msg) (pa1010d\_handle\_t handle, char \* out\_buf, size\_t out\_buf\_len, unsigned timeout\_ms) <br>_Get the NMEA message from the GPS._ |
|  esp\_err\_t | [**pa1010d\_init**](#function-pa1010d_init) (const [**pa1010d\_config\_t**](#struct-pa1010d_config_t)\* config, pa1010d\_handle\_t \* out\_handle) <br>_Initialize the PA1010D driver._ |

## Structures and Types Documentation

### struct `pa1010d_config_t`

_PA1010D driver configuration._

-  uint8\_t i2c_dev_addr  <br>I2C device address of the GPS. Typically 0x10.

-  i2c\_port\_t i2c_port  <br>I2C bus number to which the GPS is connected

### typedef `pa1010d_handle_t`

_PA1010D driver handle._
typedef struct pa1010d_t* pa1010d_handle_t;

## Functions Documentation

### function `pa1010d_deinit`

_Deinitialize the PA1010D driver._
esp_err_t pa1010d_deinit (
    pa1010d_handle_t handle


* `handle` Driver handle obtained from pa1010d\_init(), or NULL 


esp\_err\_t ESP\_OK on success.
### function `pa1010d_get_nmea_msg`

_Get the NMEA message from the GPS._
esp_err_t pa1010d_get_nmea_msg (
    pa1010d_handle_t handle,
    char * out_buf,
    size_t out_buf_len,
    unsigned timeout_ms

Reads the NMEA message from the GPS. The resulting string is stripped of CR, LF and is null-terminated.


* `handle` Driver handle obtained from pa1010d\_init() 
* `out_buf` Destination buffer for the NMEA message, has to be at least 4 bytes long 
* `out_buf_len` Length of the destination buffer in bytes 
* `timeout_ms` Timeout in milliseconds for receiving a single character 


* ESP\_OK on success
* ESP\_ERR\_TIMEOUT if no message was received within the timeout
* ESP\_ERR\_INVALID\_ARG if the buffer too short
### function `pa1010d_init`

_Initialize the PA1010D driver._
esp_err_t pa1010d_init (
    const pa1010d_config_t * config,
    pa1010d_handle_t * out_handle


* `config` Pointer to the configuration struct. The driver makes a copy, so can point to a local variable. 
* `out_handle` Pointer to a variable to receive the driver handle. 


esp\_err\_t ESP\_OK on success, ESP\_ERR\_NO\_MEM if out of memory.


# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2023-09-10

- Added pre-commit hooks
- Added CI workflow
- Added contributing and changelog pages

## [0.0.3] - 2023-07-27

- Added API reference

## [0.0.2] - 2023-07-27

- Initial release


Supports all targets


  • Ivan Grokhotkov <ivan@espressif.com>

License: Apache-2.0

To add this component to your project, run:

idf.py add-dependency "igrr/pa1010d^1.0.0"

or download archive


  • ESP-IDF >=4.4.0
  • Examples:


    To create a project from this example, run:

    idf.py create-project-from-example "igrr/pa1010d^1.0.0:pa1010d-example"

    or download archive


    • Downloaded in total
      Downloaded in total 13 times
    • Downloaded this version
      This version: 9 times


    igrr/pa1010d version: 1.0.0