readme
# PA1010D I2C GPS driver
[](https://components.espressif.com/components/igrr/pa1010d) [](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:
```bash
idf.py add-dependency "igrr/pa1010d"
```
## Example
To run the provided example, create it as follows:
```bash
idf.py create-project-from-example "igrr/pa1010d:pa1010d-example"
```
Then build as usual:
```bash
cd pa1010d-example
idf.py build
```
And flash it to the board:
```bash
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
# 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._
Variables:
- 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._
```c
typedef struct pa1010d_t* pa1010d_handle_t;
```
## Functions Documentation
### function `pa1010d_deinit`
_Deinitialize the PA1010D driver._
```c
esp_err_t pa1010d_deinit (
pa1010d_handle_t handle
)
```
**Parameters:**
* `handle` Driver handle obtained from pa1010d\_init(), or NULL
**Returns:**
esp\_err\_t ESP\_OK on success.
### function `pa1010d_get_nmea_msg`
_Get the NMEA message from the GPS._
```c
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.
**Parameters:**
* `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
**Returns:**
esp\_err\_t
* 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._
```c
esp_err_t pa1010d_init (
const pa1010d_config_t * config,
pa1010d_handle_t * out_handle
)
```
**Parameters:**
* `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.
**Returns:**
esp\_err\_t ESP\_OK on success, ESP\_ERR\_NO\_MEM if out of memory.
changelog
# 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