# gps_neo_6m

Library for the GPS NEO-6M receiver.

Author | Rob Jansen, Copyright © 2021..2023, all rights reserved.
Adapted-by |
Compiler | 2.5r8

Description

    JAL library for use of the GPS NEO-6M receiver.
                 This library provides the functionality to obtain the GPS time,
                 the GPS date and the GPS location from the GPS NEO-6M receiver.
                 The information is received and decoded on an interrupt basis.

Sources

    The NMEA 0183 Protocol. Klaus Betke, May 2000. Revised August 2001.
             Also see RMC at: https://gpsd.gitlab.io/gpsd/NMEA.html

Notes

    The default serial interface of the NEO-6M GPS receiver is 9600 baud,
           1 stopbit, no parity and no flow control.
           At least one of the JAL serial hardware libraries must be included
           and initialized by the main program with the above settings.

Dependencies

No dependency found

## Summary

### Global variables/contants

- `var byte _gps_neo_6m_rx_data_array[_GPS_NEO_6M_MAX_DATA_ARRAY]`
- `const byte _GPS_NEO_6M_RMC_STATUS = 3`
- `const byte _GPS_NEO_6M_RMC_GGA = 1`
- `const byte _GPS_GGA_STRING[] = "$GPGGA"`
- `const byte _GPS_NEO_6M_GGA_FIX = 9`
- `const byte _GPS_NEO_6M_GGA_SATELLITES = 11`
- `var float _gps_neo_6m_rx_lattitude, _gps_neo_6m_rx_longitude`
- `const byte _GPS_NEO_6M_CHECKSUM = 14`
- `var byte _gps_neo_6m_rx_state, _gps_neo_6m_rx_following_state`
- `const byte _GPS_NEO_6M_NORTH_SOUTH = 5`
- `const byte _GPS_NEO_6M_LONGITUDE = 6`
- `var bit _gps_neo_6m_rx_string_ok, _gps_neo_6m_rx_rmc_string`
- `var byte _gps_neo_6m_rx_hour, _gps_neo_6m_rx_minute, _gps_neo_6m_rx_second`
- `var byte _gps_neo_6m_rx_lattitude_direction, _gps_neo_6m_rx_longtitude_direction`
- `const byte _GPS_NEO_6M_RMC_DATE = 12`
- `const byte _GPS_NEO_6M_TIME = 2`
- `var byte _gps_neo_6m_rx_index, _gps_neo_6m_rx_checksum`
- `var byte _gps_neo_6m_rx_satellites`
- `const byte _GPS_NEO_6M_RMC_TRACK = 10`
- `const byte _GPS_NEO_6M_END = 13`
- `const byte _GPS_RMC_STRING[] = "$GPRMC"`
- `var bit _gps_neo_6m_rx_calculate_checksum`
- `const byte _GPS_NEO_6M_RMC_SPEED = 8`
- `const byte _GPS_NEO_6M_LATITUDE = 4`
- `const byte _GPS_NEO_6M_MAX_DATA_ARRAY = 12`
- `var byte _gps_neo_6m_rx_checksum_1, _gps_neo_6m_rx_checksum_2`
- `const byte _GPS_NEO_6M_SEPARATOR = 15`
- `var bit _gps_neo_6m_rx_data_received, _gps_neo_6m_rx_status_active`
- `const byte _GPS_NEO_6M_EAST_WEST = 7`
- `var byte _gps_neo_6m_rx_date, _gps_neo_6m_rx_month, _gps_neo_6m_rx_year`
- `const byte _GPS_NEO_6M_IDLE = 0`

### Procedures

- `gps_neo_6m_init()`

Private

- `_gps_neo_6m_serial_interrupt()`

### Functions

- `gps_neo_6m_get_longtitude() return float`
- `gps_neo_6m_get_lattitude_direction() return byte`
- `gps_neo_6m_get_longtitude_direction() return byte`
- `gps_neo_6m_data_available() return bit`
- `gps_neo_6m_get_nr_of_statellites() return byte`
- `gps_neo_6m_status_active() return bit`
- `gps_neo_6m_get_lattitude() return float`

Private

- `_gps_neo_6m_is_ascii_number(byte in character) return bit`
- `_gps_neo_6m_convert_gps(byte in nr_of_characters) return float`
- `_gps_neo_6m_ascii_to_binary(byte in ascii) return byte`

## API details

### Global variables/contants

- `var byte _gps_neo_6m_rx_data_array[_GPS_NEO_6M_MAX_DATA_ARRAY]`

      This array is used to store the ASCII data of the GPS coordinates.

- `const byte _GPS_NEO_6M_RMC_STATUS = 3`

  No documentation found

- `const byte _GPS_NEO_6M_RMC_GGA = 1`

  No documentation found

- `const byte _GPS_GGA_STRING[] = "$GPGGA"`

      Definition of the NEO-6M Global positioning FIX data (GGA).

- `const byte _GPS_NEO_6M_GGA_FIX = 9`

  No documentation found

- `const byte _GPS_NEO_6M_GGA_SATELLITES = 11`

  No documentation found

- `var float _gps_neo_6m_rx_lattitude, _gps_neo_6m_rx_longitude`

  No documentation found

- `const byte _GPS_NEO_6M_CHECKSUM = 14`

  No documentation found

- `var byte _gps_neo_6m_rx_state, _gps_neo_6m_rx_following_state`

  No documentation found

- `const byte _GPS_NEO_6M_NORTH_SOUTH = 5`

  No documentation found

- `const byte _GPS_NEO_6M_LONGITUDE = 6`

  No documentation found

- `var bit _gps_neo_6m_rx_string_ok, _gps_neo_6m_rx_rmc_string`

  No documentation found

- `var byte _gps_neo_6m_rx_hour, _gps_neo_6m_rx_minute, _gps_neo_6m_rx_second`

  No documentation found

- `var byte _gps_neo_6m_rx_lattitude_direction, _gps_neo_6m_rx_longtitude_direction`

  No documentation found

- `const byte _GPS_NEO_6M_RMC_DATE = 12`

  No documentation found

- `const byte _GPS_NEO_6M_TIME = 2`

  No documentation found

- `var byte _gps_neo_6m_rx_index, _gps_neo_6m_rx_checksum`

  No documentation found

- `var byte _gps_neo_6m_rx_satellites`

  No documentation found

- `const byte _GPS_NEO_6M_RMC_TRACK = 10`

  No documentation found

- `const byte _GPS_NEO_6M_END = 13`

  No documentation found

- `const byte _GPS_RMC_STRING[] = "$GPRMC"`

      The library looks for two strings and extracts the relevant data from them.
      Definition of the NEO-6M Recommended Minimum Navigation String (RMC).

- `var bit _gps_neo_6m_rx_calculate_checksum`

  No documentation found

- `const byte _GPS_NEO_6M_RMC_SPEED = 8`

  No documentation found

- `const byte _GPS_NEO_6M_LATITUDE = 4`

  No documentation found

- `const byte _GPS_NEO_6M_MAX_DATA_ARRAY = 12`

      We need an internal data array to store the received GPS coordinates before
      it can be converted to a float value.

- `var byte _gps_neo_6m_rx_checksum_1, _gps_neo_6m_rx_checksum_2`

  No documentation found

- `const byte _GPS_NEO_6M_SEPARATOR = 15`

  No documentation found

- `var bit _gps_neo_6m_rx_data_received, _gps_neo_6m_rx_status_active`

  No documentation found

- `const byte _GPS_NEO_6M_EAST_WEST = 7`

  No documentation found

- `var byte _gps_neo_6m_rx_date, _gps_neo_6m_rx_month, _gps_neo_6m_rx_year`

  No documentation found

- `const byte _GPS_NEO_6M_IDLE = 0`

      States of the library for decoding the received data. Some are used for the
      RMC and GGA strings and some are specific to only RMC or GGA.

### Procedures

- `gps_neo_6m_init()`

      Initialize the GPS NEO 6M library. The peripheral interrupt and global
      interrupt are enabled.

Private

- `_gps_neo_6m_serial_interrupt()`

      Process the serial interrupt and get the incoming GPS data.

### Functions

- `gps_neo_6m_get_longtitude() return float`

      Return the received GPS longtitude coordinates. Only valid when
      gps_neo_6m_status_active() returns TRUE.

- `gps_neo_6m_get_lattitude_direction() return byte`

      Return the received GPS lattitude direction. Only valid when
      gps_neo_6m_status_active() returns TRUE.

- `gps_neo_6m_get_longtitude_direction() return byte`

      Return the received GPS longtitude direction. Only valid when
      gps_neo_6m_status_active() returns TRUE.

- `gps_neo_6m_data_available() return bit`

      Return TRUE if data is available. This call will reset this flag.
      Initially this will be time and date data.
      For GPS presence of location data check gps_neo_6m_status_active().

- `gps_neo_6m_get_nr_of_statellites() return byte`

      Return the number of satellites. Only valid when
      gps_neo_6m_status_active() returns TRUE.

- `gps_neo_6m_status_active() return bit`

      Return TRUE if the GPS data is active, that means that GPS coordinates
      are available.

- `gps_neo_6m_get_lattitude() return float`

      Return the received GPS lattitude coordinates. Only valid when
      gps_neo_6m_status_active() returns TRUE.

Private

- `_gps_neo_6m_is_ascii_number(byte in character) return bit`

      Check if the given character is an ASCII number and return TRUE if valid.

- `_gps_neo_6m_convert_gps(byte in nr_of_characters) return float`

      Convert the GPS location in ASCII to a float. If the value is incorrect
      then 0.0 is returned.

- `_gps_neo_6m_ascii_to_binary(byte in ascii) return byte`

      Convert an ascii hexadecimal nibble to a binary number.

## Related samples

Here are the list of samples which use this library:

16f1825 | 16f1825_gps_neo_6m_ssd1306_clock.jal
16f1825 | 16f1825_gps_neo_6m_serial.jal