Programmatic Interface - Firmware Commands

These commands allow control over Input and Output streams over Serial ports, TCP or UDP connections.



List of all commands
Programmatic Overview


Show FirmwareVersion

This command returns the version number and release date of the currently installed firmware. The Version value is a three-digit code consisting of a

This will be encoded as 'Major.Minor-Release'. For example, a version might show '1.2-3'. In some data file formats, the version will be encoded as a single three digit number by simply concatentating the three digits.


Parameters:

No parameters are available.


Response:
FirmwareVersion version=1.2-3 date=2003/10/31

Show FirmwareWarranty

This command displays the current Firmware Warranty date. This date is compared to the release date in a firmware file to determine if that firmware version can be installed in your system.


Parameters:

No parameters are available.


Response:
FirmwareWarranty date=2055/05/05

Set FirmwareWarranty

This command enters a Firmware Warranty Code, which encodes a new warranty date. Warranty codes are uniquely generated for a date and NetRS serial number.


Parameters:
code=b957c46872ea70c7 This is the 16 character warranty code.


Response:
OK: FirmwareWarranty date=2003/12/31

Upload FirmwareFile

This command is used to transfer a firmware file from the remote computer into the firmware file directory in the NetRS file system. This is refered to as an Upload. The uploaded file becomes available for installation using Install FirmwareFile.

The upload URL-CGI command is submitted as with other commands, but uses an http POST request instead of a GET request. This process is a bit complicated. See these links for sample code using Curl and Perl. Regardless of the programming technique, the process must attach a multipart/form-data document to the POST request. The document will contain the raw binary data to be uploaded. The "section" of the multipart document that contains a firmware upload file must be given a name "firmwareFile", and may include a suggested name for the file once it arrives in the NetRS. For example, in the curl sample, there is an option "-F firmwareFile=@fname". This tells curl to attach the file named 'fname' in a section named 'firmwareFile', and to use 'fname' as the default name for the file in the NetRS.

Optionally the CGI request can overrule the default name for the file when it reaches the target system, by using the parameter name=fname.


Parameters:
name=filename This parameter is optional. If specified, then the file that is uploaded will be renamed to the given name. Otherwise, the name will be derived from the filename supplied in the multipart document containing the uploaded file.


Response:
OK:  FirmwareFile NetRS-1.0-2.ppc.rpm was successfully uploaded.

Show FirmwareFiles

This command lists all firmware files that have been uploaded to the NetRS. These represent the firmware versions that can be installed in your system.


Parameters:

No parameters are available.


Response:
<Show FirmwareFiles>
NetRS-0.6-4.ppc.rpm  10423379 bytes
NetRS-1.0-1.ppc.rpm  10268188 bytes
<end of Show FirmwareFiles>

Show FirmwareFile

This command returns a detailed description of a particular firmware file. The description includes the version numbers, creation date, size, release notes, installation procedure, etc.


Parameters:

name=fileName This is the complete name of the file to be listed.
The value is case sensitive.


Response:
<Show FirmwareFile name=NetRS-1.0-1.ppc.rpm>
This file is installable under the terms of your warranty.
Details:

Name        : NetRS
Summary     : Trimble NetRS Full Firmware Package, version 1.0-1
Version     : 1.0-1
Build Date  : Wed Oct 22 17:20:17 2003
License     : (c)2003 Trimble Navigation Limited
Size        : 10268188 bytes

This is a full release RPM package for a Trimble NetRS GPS receiver:

    Firmware Version 1.0-1
    Firmware Date    2003/10/06
....
....
<end of Show FirmwareFile name=NetRS-1.0-1.ppc.rpm>

Verify FirmwareFile

This command performs a verification that the contents of a named firmware file are uncorrupted. This verifies that the file was uploaded intact and uncorrupted. It also checks the file against the current Warranty Date to ensure that the file can be installed under the terms of your warranty.

Firmware verification can take up to 30 seconds. No response will occur until the process is completed.


Parameters:

name=fileName This is the complete name of the file to be verified.
The value is case sensitive.


Response:
OK: FirmwareFile NetRS-1.0-1.ppc.rpm can be installed.

Install FirmwareFile

This command triggers the installation of a firmware file. The process first verifies the firmware file, as is done with Verify FirmwareFile. If no errors are detected then the OK response is returned, indicating that the final installation phase is starting and showing how many seconds the installation is expected to take. Five seconds after that message is sent, the NetRS will go off-line while it implements the installation. No communications will be possible during this time. When the installation is completed, the system should restart and resume normal operations using the new firmware.


Parameters:

name=fileName This is the complete name of the file to be installed.
The value is case sensitive.


Response:
OK: Installing FirmwareFile fileName 
    Expect at least 400 seconds to complete.

Delete FirmwareFile

This command removes a specified firmware file from storage in the NetRS. This reclaims the space used by the file, which can then be used for other firmware uploads or for data logging.

An alternate form of the command allows deleting ALL previously uploaded firmware files without the need to explicitly specify their names.


Parameters:

name=fileName This is the complete name of the file to be deleted.
The value is case sensitive.
all=yes Delete ALL previously uploaded firmware files.


Responses:
OK: FirmwareFile fileName is deleted.

OK: All firmware files deleted.