NMEA0183 Wi-Fi Programmer's API

Programmer's API

The device has an API to make it easier for app users to connect to the Wi-Fi gateway, so improving the overall user experience and also reducing support calls. This is done by communicating with the device using proprietary NMEA sentences, with three key aspects:

  • Device discovery: let the app detect the device and its settings, to let the app configure itself and connect to the device with no user input
  • Device configuration: query and change the configuration of the device
  • TCP timeouts: avoid TCP connections getting locked up due to an app not closing the TCP connection properly, or the phone or table going out of Wi-Fi range

An overview of each of these aspects is given below, with full details being contained in the API documented downloadable from this page.

Device Discovery

To relieve the app user of the burden of matching the connection settings in the app and in the gateway, the device broadcasts its presence and settings over UDP every 10 seconds on  port 10110. On starting, the app can listen for this transmission and, if found, configure itself and connect to the Wi-Fi gateway with no input from the user.

An example sentence that may be broadcast is:

$PTSV,TCPUDP,R,TCP,A,S,192.168.4.1,10110,0,UDP,A,B,255.255.255.255,10110*21

$PTSV,TCPUDP,R, indicates that the sentence is a TeamSurv one, for TCP and UDP settings, and it is being output with the current settings

TCP,A,S,192.168.4.1,10110,0, has the TCP settings. Here, TCP is enabled with a static IP address of 192.168.4.1 on port 10110, and the timeout facility is disabled

UDP,A,B,255.255.255.255,10110 shows that UDP is enabled, and is broadcasting on IP address 255.255.255.255, port 10110.

Device Querying and Configuration

This is performed using a number of sentences over TCP. Note that this works even if TCP is disabled for normal NMEA data. For each sentence, it can be sent as a Query to enquire the settings of the gateway; a Response sent by the gateway to the app, containing the current settings, and a Change command to change the settings.

NMEA Settings

$PTSV,NMEA,Q,,,,,,,,*57 is a query from the app to the gateway for the data rates of each NMEA port. Although the gateway only uses one port, the sentence is designed for use with devices with multiple ports, for future compatibility.

$PTSV,NMEA,R,4800,,,,,,,*58 is the response from the gateway, indicating that a data rate of 4800bps is set.

$PTSV,NMEA,C,38400,,,,,,,*7A is a command from the app to the gateway, to set the date rate at 38400bps. The setting is applied, with a short pause as the gateway restarts.

TCP and UDP Settings

A similar set of 3 sentences are used, to support the TCP and UDP settings of the gateway. Again, after applying a change the device restarts and, depending on the changes made, it may be necessary to change the settings in the app to continue communicating with it. The sentence used is the same as the discovery broadcasts over UDP, as described above.

TCP Timeouts

As the TCP connection is point to point, if it is not closed down properly then one end will probably remain open as a "phantom connection". If all of the TCP connections available on a device are blocked in this way, no more connections will be able to be made until the device is rebooted. They may arise for a number of reasons, such as an app not closing the connection properly when it closes down, or the user going out of range with their phone or tablet. A specific issue with iPhones and iPads is that if the user switches to another app, the operating system forcibly disconnects the old app's connection, and if this isn't handled properly by the app then it leaves a phantom connection.

To avoid these problems, if the timeout parameter in the TCP and UDP sentence is set to a non zero period, the gateway broadcasts a keep alive message at half the time-out period - the app doesn't need to process the message, its purpose is just to indicate that the gateway is still up and running, if no other messages have been received. Also, the gateway expects to receive a keep-alive sentence or other data with a gap no longer than the timeout period. If this time is exceeded, the gateway will close the connection.

The keep alive sentence is of the form: $PTSV,ALIVE*7A