Programmatic Interface

Use the Programmatic Interface menu to show, set, and command configurations. The programmatic interface allows simple HTTP scripting for browser use or for integration into other web-capable platforms. You can find below additional information on supported commands and command structure.

How to use programmatic commands

To use the programmatic interface commands, the following must be available:

• A GNSS receiver on a TCP/IP link. This could be either an Ethernet connection or a PPP connection over a serial port.

• A computer that can send HTTP requests over the TCP/IP link to the GNSS receiver. This is assured if a web-browser can communicate using the GNSS receiver web interface.

• A programming tool that allows sending CGI requests, and receives the responses. On most Unix/Linux systems this can be satisfied with the command-line utilities perl or curl.

Programmatic commands have to be encoded as URL or CGI requests. This requires assembling several pieces of information.

• The required protocol (http or https).

• The DNS name or IP address of the target system.

• The Verb, Object, and Parameters forming the command.

The URL will be of the form:

http://SystemName/prog/Verb?Object&param=value&param=value...

If any parameter values have special characters in them, like spaces or ampersands, these must be encoded using %hex formatting. For example, each space must be replaced with the sequence %20.

Once the URL is determined, the CGI transmission tool is used to send a "GET" request, containing the encoded command, to the target GNSS receiver. The GNSS receiver will respond by sending back a document in one of the five response types. Almost all responses are simple ASCII text which can then be displayed or parsed as the application requires.

One exception to the previous paragraph is the case of uploading a file to the GNSS receiver. Upload commands use a "POST" request instead of a "GET" request.

Using Curl

A simple method of testing programmatic commands is to manually feed the URLs into curl, a commonly available command line tool. Here is a sample Unix session that shows the usage.

$ curl 'http://receiver-name.Trimble.com/prog/show?serialNumber'
SerialNumber sn=60350239BF

$ curl 'http://receiver-name.Trimble.com/prog/show?gpstime'
GpsTime gpsweek=1244 weekseconds=437597

$ curl 'http://receiver-name.Trimble.com/prog/badcommand?abc'
ERROR: invalid verb 'badcommand'

$ curl 'http://receiver-name.Trimble.com/prog/set?elevationmask&mask=10'
OK: ElevationMask mask=10

$ curl 'http://receiver-name.Trimble.com/prog/show?position'
<Show Position>
GpsWeek 1244
WeekSeconds 498154.0
Latitude 37.3891271874 deg
Longitude -122.0368443968 deg
Altitude -4.898 meters

....

<end of Show Position>

Multiple curl commands could be assembled into a shell script to implement a basic form of remote control.

If the GNSS receiver has security enabled, an account name and password is required to use the programmatic interface commands. Curl accepts these in a '-u' command line argument. For example:

$ curl -u admin:adminpw 'http://receiver-name.trimble.com/prog/show?serialNumber'
SerialNumber sn=60350239BF

That submits the request, using account name 'admin' and password 'adminpw'.

Binary file downloads with Curl simply require directing the output to a file.

$ path=/Internal
$ name=60350239BF200906181935.T01
$ curl "http://receiver-name/prog/download?file&path=$path/$name" > $name
$

Note that there is no command line response in this case. If an error occurred (for instance, if the file did not exist in the GNSS receiver) the message would end up in the file.

File upload commands require curl to format a POST request, with a binary attachment. Curl implements this with a -F option:

$ f=/tmp/fina_V401.timg
$ curl 'http://Alloy/prog/upload?firmwareFile' -F firmwareFile=@$f

That command would upload a new firmware image file to the GNSS receiver, and trigger an installation of the new firmware.

Using Perl

Perl is a powerful scripting language. The language comes with numerous library packages, which enables it to be used to automate many complex tasks. It is also available on most operating systems, which makes it good for cross-platform applications.

Perl can easily be used to control a GNSS receiver using the programmatic interface commands. A simple method uses LWP; a library for WWW access in Perl. On Linux, use man LWP for overview documentation. This is a powerful and complex package, which cannot be documented here. Some sample programs show the basic techniques needed. The first shows how to encode basic URL requests:

#!/usr/bin/perl -w
use strict;
use LWP::Simple;

print get( "http://fbtc/prog/show?systemname" ) ;
print get( "http://fbtc/prog/show?gpstime" ) ;
print get( "http://fbtc/prog/badCommand?abc" ) ;
print get( "http://fbtc/prog/set?elevationMask&mask=10" ) ;
print get( "http://fbtc/prog/show?position" ) ;

Running that program produces the following output:

SystemName name=NewName
GpsTime gpsweek=1244 weekseconds=498371
ERROR: Invalid verb 'badCommand'
OK: ElevationMask mask=10
<Show Position>
GpsWeek 1244
WeekSeconds 498373.2
Latitude 37.3891241306 deg
Longitude -122.0368464236 deg
Altitude -4.078 meters
....
<end of Show Position>

File downloads are a bit more complex than just redirecting a get() request to a file, mainly due to the fact that the files can be arbitrarily large. A more complex syntax allows Perl to download and put the results directly into a file.

#!/usr/bin/perl -w

use LWP::UserAgent;

my $f = '60350239BF200906181935.T01' ;
my $path = '/Internal' ;

my $ua = LWP::UserAgent->new ;

my $req = HTTP::Request->new(GET=>
       "http://Alloy/prog/download?file&path=$path/$f" ) ;

my $res = $ua->request( $req, $f ) ;

When this is run, the logged file on the GNSS receiver is copied to an identically named file in the local computer. Note that no text comes to standard output.

File uploads use a similar technique.

#!/usr/bin/perl -w

use strict ;
use HTTP::Request::Common qw(POST) ;
use LWP::UserAgent ;

print "OKAY\n" ;
my $fname = '/tmp/fina_V401.timg' ;
my $ua = LWP::UserAgent->new ;
my $command = 'http://fbtc/prog/Upload?FirmwareFile' ;
my $response = $ua->request( POST( $command ,

Content_Type => 'form-data',
Content => [ 'firmwareFile'
                 => [ $fname ]
          ]

      )
) ;

print $response->content ;

Running that program produces:

OK: Failsafe Firmware Installation Started.

Other techniques

It is feasible to use other methods to transmit the programmatic commands to the target system. For example, C or C++ programs directly open socket connections to the GNSS receiver and directly transmit the requests over those channels. This is moderately advanced programming and the details are beyond the scope of this topic.

List of programmatic commands

Below is a complete list of the Action-Object commands accepted by the programmatic interface. Clicking an individual command takes you to the specific information on that command.

• Status commands

• Satellite commands

• Configuration commands

• Input/Output commands

• Firmware commands

• Network commands

Status commands

All of these commands display some information from the GNSS receiver. The information can be a static item, like a serial number, or something dynamic like the current time or receiver position.

Command	Description
Show SerialNumber	Returns the serial number of this GNSS receiver.
Show UtcTime	Returns the current UTC date and time.
Show GpsTime	Returns the current GPS week number and time.
Show Position	Returns the currently measured position and associated values.
Show Voltages	Returns the voltages on all power or battery inputs.
Show PowerControls	Returns the power control settings.
Show ChargingControls	Returns the charging control settings.
Show Temperature	Returns the internal temperature of the GNSS receiver.
Show Commands	Returns a list of all supported commands.

Satellite commands

These commands are associated with satellite tracking and data.

Command	Description
Show TrackingStatus	Returns information on all tracked satellites.
Show Tracking	Returns signal tracking settings.
Set Tracking	Modifies signal tracking settings.
Show BeidouSatControls	Returns the Enable/Disable/Ignore Health settings for all BeiDou satellites.
Set BeidouSatControls	Modifies the Enable/Disable/Ignore Health settings for all BeiDou satellites.
Show GpsSatControls	Returns the Enable/Disable/Ignore Health settings for all GPS satellites values.
Set GpsSatControls	Modifies the Enable/Disable/Ignore Health settings for GPS satellites.
Show GlonassSatControls	Returns the Enable/Disable/Ignore Health settings for all GLONASS satellites values.
Set GlonassSatControls	Modifies the Enable/Disable/Ignore Health settings for GLONASS satellites.
Show QzssSatControls	Returns the Enable/Disable/Ignore Health settings for all QZSS satellites values.
Set QzssSatControls	Modifies the Enable/Disable/Ignore Health settings for QZSS satellites.
Show SbasSatControls	Returns the Enable/Disable/Ignore Health settings for all SBAS satellites.
Set SbasSatControls	Modifies the Enable/Disable/Ignore Health settings for SBAS satellites.
Show GlonassSatControls	Returns the Enable/Disable/Ignore Health settings for all GLONASS satellites.
Set GlonassSatControls	Modifies the Enable/Disable/Ignore Health settings for GLONASS satellites.
Show Ephemeris	Returns ephemeris data for a GNSS satellite.
Show Almanac	Returns the almanac data for a GNSS satellite.
Show GpsHealth	Returns the health status of all GPS satellites.
Show GpsUtcData	Returns the UTC data decoded from GPS satellites.
Show GpsIonoData	Returns the ionospheric model data decoded from GPS satellites.
Reset GnssData	Clears all decoded GNSS ephemeris and almanac data.

Configuration commands

These commands show or modify the state of various of system functions.

Command	Description
Reset System	Restarts (reboots) the GNSS receiver.
Show ReferenceFrequency	Returns the current source for the 10 MHz reference clock.
Set ReferenceFrequency	Modifies the source for the 10 MHz reference clock.
Show ElevationMask	Returns the current elevation mask control setting.
Set ElevationMask	Modifies the elevation mask control setting.
Show PdopMask	Returns the current PDOP mask control setting.
Set PdopMask	Modifies the PDOP mask control setting.
Show ClockSteering	Returns the current clock steering control setting.
Set ClockSteering	Modifies the clock steering control setting.
Set StingerDiag	Forces a given satellite on a channel.
Set Pipe	Enable Pipe between two Ports. Set both inputs to "0" to break pope.
Show PPS	Returns the current settings of the pulse-per-second controls.
Set PPS	Modifies the settings of the pulse-per-second controls.
Show AntennaTypes	Returns a list of supported antenna types.
Show Antenna	Returns the current antenna specifications.
Set Antenna	Modifies the antenna specifications.
Show MultipathReject	Returns the current multipath rejection control setting.
Set MultipathReject	Modifies the multipath rejection control setting.
Show RtkControls	Returns current RTK Control settings.
Set RtkControls	Modifies RTK Control settings.
Show PowerControls	Returns the power control settings.
Set PowerControls	Modifies power control settings.
Show ChargingControls	Returns the charging control settings.
Set ChargingControls	Modifies charging control settings.

Input/Output commands

These sections show how Input/Output ports are configured to stream data, etc.

Command	Description
Show IoPorts	Returns a list of all I/O ports and their settings.
Show IoPort	Returns the settings for a single I/O port.
Set IoPort	Modifies the controls for an I/O port.
Delete IoPort	Removes a TCP/IP port definition.
Show RefStation	Returns the current reference station control settings.
Set RefStation	Modifies the reference station control settings.
PortParameters	Port specification parameters.
StreamParameters	Stream specification parameters.

Firmware commands

These commands are associated with updating firmware in the GNSS receiver.

Command	Description
Show FirmwareVersion	Returns the current running firmware version.
Show FirmwareWarranty	Returns the firmware warranty date set in the receiver.
Set FirmwareWarranty	Sends option code to update firmware warranty date.
Upload FirmwareFile	Loads new firmware file to receiver.

Data Logging commands

These commands are associated with data logging.

Command	Description
Show Sessions	Show all data logging sessions.
Set Sessions	Create or modify a data logging session.
Delete Session	Delete a data logging session.
Set Autodelete	Enable auto delete.

Network commands

These commands are associated with data logging.

Command	Description
Show DnsQuery	Returns the IP addresses of the host.
Show Ping	Returns the ping results of the host.