Added decoding of 'PGTOP' to get the status of the antenna extension …

[PierreDeQuebec]

Added decoding of 'PGTOP' to get the status of the antenna extension (if any).

The antenna status is made accessible via the new 'self.antenna' property.
A tuple (current status, last status). Possible values are:
1: Antenna shorted.
2: Internal antenna.
3: Active (extending) antenna.

So self.antenna[0] gives the current status and self.antenna[1] gives the
last status. User is responsible to acknowledge change in the antenna
status by making self.antenna[1] same as item 0.

[dhalbert]

Thanks for the PR! I noted a couple of things in separate comments.

[dhalbert]

Suggestion for clarity:

Suggested change

	return True if data_type[:5] != b"PGTOP" else self._parse_pgtop(args)
	return True if data_type.endswith(b"PGTOP") else self._parse_pgtop(args)

[PierreDeQuebec]

Use of the 'antenna' attribute requires the user to send the appropriate NMEA command. The following code is an example. It should probably be added somewhere in the documentation.

Check if antenna extension is present. To do this, send the following command:

        _command = b"PGCMD,33,1*6C"
        self.gps.send_command(_command)`

GPS chips will emits PGTOP sentence (antenna status) at each 'FIX'. You could use the antenna attribute of your GPS instance to interpret the status as following. If no antenna status was detected, the attribute antenna return False else attribute antenna return a tuple with two items (actual status, last status). Status is an integer with the following meaning.

1: Problem with the antenna (shorted).
2: internal antenna on chip is used.
3: active antenna (extension) is used.

You can do two simple things with the attribute. 1. Simply linked the attribute to an indicator light (LED). In this case, only antenna[0] will interest you. 2. Detect any change in antenna status in real time. In this case, you must compare antenna[0] to antenna[1] and then acknowledge the state change by setting the antenna[1] attribute equal to antenna[0]. The acknowledgment is necessary to allow the detection of a future status change.

[FoamyGuy]

With regards to documenting the mentioned commands.

Could we make antenna into a declared @property? then it will have a spot for docstrings within which the necessary commands can be included.

I would also be in favor of a new script in the examples/ directory to show usage of the new behavior.

[PierreDeQuebec]

Yes. Since the last commit I have defined an 'antenna' property and added an antenna_acknowledge_receipt(delay=5) method. I have inserted the docstrings with the text that seems appropriate to me. But before publishing a new commit, I have to test the whole thing. Here is the docstring for the new method antenna_acknowledge_receipt to basically explain the acknowledgment logic that is implemented.

The change of state of the antenna is governed by an acknowledgment with a locking mechanism giving the user time to become aware of any change (for example: forgetting to connect the active antenna, untimely disconnection of the micro connector on-board ufl or intermittent problem). The user must acknowledge an antenna status change if they want to be notified of any future problems with the active antenna. Anyway, an automatic acknowledgment is performed after a delay which can be modified by the user.

The delay in question is in seconds (0, 1, 2, 3, 4 or 5). 0 means no latching is done.

[PierreDeQuebec]

By the way, the reason why I need to track the status of the active antenna has to do with a little connection issue on the Ultimate GPS Logging Shield board. The micro ufl connector is on the front edge of the card. Mounting in a box forces me to run the cable through the back with the SD reader obstructing it. In the end, the connector clips a bit at the corner which makes the connection unsafe.

[PierreDeQuebec]

Antenna acknowledgment mecanism

Implementation Variables:

    __antenna_actual = None  # Actual status acknowledge of the external antenna.
    __antenna_last = None  # Last status acknowledge of the external antenna.
    __antenna_change = False
    __antenna_instant_status = None  # Status of antenna as currently read.
    __antenna_ack_delay = 5  # Time (sec.) to wait between automatic acknowledge.
    __antenna_ack_time = time.monotonic()
    __antenna_ack = False  # False: initialize a new delay. True: delay is in way.

The acknowledgment mechanism is implemented as soon as the status of the antenna changes. This status change corresponds to the instantaneous value (__antenna_instant_status). The program then behaves as follows.

If the acknowledgment delay is 0 seconds (__antenna_ack_delay)
The past value (__antenna_last) becomes the current value (__antenna_actual) and the current value of the antenna status is immediately updated with the instantaneous value.

If the acknowledgment delay is 1, 2, 3, 4 or 5 seconds.
The program adopts the following behavior:
A timer is started with the programmed delay. During the delay, the current antenna status value is maintained unless an acknowledgment command is received. On acknowledgment or on expiry of the delay ('automatic' acknowledgement), the values are updated as explained in the case of the delay at 0 seconds.

The __antenna_ack state variable tracks the state of the antenna.

• False: The current value does not match the instantaneous value. An acknowledgment is required for a current value update.
• True: Current value and instantaneous value are the same.

[PierreDeQuebec]

@FoamyGuy

I would also be in favor of a new script in the examples/ directory to show usage of the new behavior.

I would like to write a script as an example for the implementation of the monitoring of the status of the active antenna. How should I submit it? By adding a .py file to the directory in question?

[FoamyGuy]

I would like to write a script as an example for the implementation of the monitoring of the status of the active antenna. How should I submit it? By adding a .py file to the directory in question?

Sorry that I did not notice this and reply sooner.

Yes examples can be submitted with a PR by adding a new .py file into examples/ directory. The name of the file does need to follow a specific pattern for some of our infrastructure to use. For this library the file should be named gps_something.py where "something" is descriptive of what the script does or illustrates.

[PierreDeQuebec]

OK. I'm working on it.