PhoCheck T1 Windows Software Specificationv1.00, 25 October 2008

PhoCheck T1 Windows Software Specification

Reference:T1

Version:v1.00

Date:25 October 2008

Document history:

v1.00,25 Oct 2008First release

Contents

1.Introduction

2.General Information

2.1 Overview

2.1 Target Platform

2.2 Program Name and Icon

2.3 Automatic Start-Up

2.4 Multiple Instruments Are Not Supported

3.Communication

3.1 USB Communication

3.2 Data Signing

3.3 Communication Protocol

3.4 Typical Messages

3.5 Initial Connection

3.6 Communication DLL

4.User Interface

4.1 Windows

4.2 Menus

4.3 Buttons

4.4 Real-time Measurement

4.5 Instrument Setup Window

4.6 Data Logs Directory

4.7 Data Logs

4.8 Graph Functions

4.9 Gas Tables

4.10 Calibration

4.11 Firmware Update

4.12 Feature Update

4.13 Recovery File

5.T1 Program Options

5.1 Data Log Options

5.2 Graph Options

5.3 General Options

6.Web Based Update

6.1 Introduction

6.2 Usage Case 1: Agent Updates Features Before Sale

6.3 Usage Case 2: Agent Updates Instrument After Sale

6.4 Usage Case 3: Ion Science Updates

6.5 Usage Case 4: Ion Science Month-End Invoicing

6.6 T1 Software

6.7 Feature Update File

6.8 Instrument Software

6.9 Server Software

6.10 Web Browser Compatibility

6.11 Security and Backups

6.12 Benefits

Appendix A File Extensions

Appendix B Instrument Data Items

B.1 Instrument Identification and Status

B.2 Instrument Calibration

B.3 Data Log

B.4 Gas Table

Appendix C Future Options (and Other Non-Deliverables)

C.1 General

C.2 Email Alerts

C.3 SMS Text Message Alerts

C.4 Foreign Language Options

C.5 T1 Software Updates

Appendix D Outstanding Issues

1.Introduction

Ion Science are developing a new PhoCheck T1 handheld gas detector, also known as the T1. This new design shall provide similar functionality to existing Ion SciencePhoCheck instrument, but with the addition of a USB port, better battery life, improved keyboard and larger display. It features 2MB Flash memory for storing data logs etc. and 512MB flash memory to hold the instrument’s firmware.

New PC software, described in this document, is required to enable the PhoCheck T1 to be connected to a PC for a variety of purposes, including:

  • Reading and setting the configuration of the PhoCheck T1
  • Retrieving logged data (gas concentration against time)
  • Displaying a graph of the gas concentration
  • Transferring gas tables to and from the PhoCheck T1
  • Installing feature updates
  • Installing firmware updates

The PC software shall be suitable for a PC running the Windows XP or Windows Vista operating system.

In addition, a new, web-based update system has been proposed to enable individual instruments to be remotely updated. The customer places the upgrade order with Ion Science or a customer who enter the details via a web site. The customer can then update their instrument in less than 10 seconds by selecting a single menu item. This optional feature is described fully in section 6 below.

2.General Information

2.1Overview

The Windows software shall run within a window and provide the common menus and buttons found in most Windows applications, such asa File menu, Window menu, Help menu, Save button, Print button etc.

2.1Target Platform

The Windows software shall be suitable for a PC with:

  • Windows XP or Windows Vista (32-bit version)
  • Visual Studio .Net Framework
  • Spare USB port (USB 1 or USB 2)
  • 512Mbytes of RAM or more
  • 128Mbytes of free hard disc space.

The software shall be written using Microsoft Visual C++ version 9 (as supplied with Microsoft Visual Studio 2008). It shall use the Microsoft .Net Framework 3.5 which should be installed on the PC by the installation system.

2.2Program Name and Icon

The software name shall be T1 and it shall use the following program icons:

16x16Logo.bmp

32x32logo.bmp

2.3Automatic Start-Up

When a PhoCheck T1 is connected to the PC the T1 software should automatically start and open a window showing the data logs available in the instrument.

The T1 software can also be started manually, without an instrument being connected, to view saved data log for example.

2.4Multiple Instruments Are Not Supported

Only one instrument may be connected to the PC at any one time – connecting multiple instruments simultaneously shall not be supported. (If multiple instruments are connected, the software may only communicate with one of them).

3.Communication

3.1USB Communication

The PhoCheck T1 shall use USB1.1, and may be connected to a USB 1.1 or USB 2.0 port on a PC. All USB functionality shall be implemented using the IAR PowerPac USB library.

The PhoCheck T1 shall support the USB Full Speed data rate of 12Mbit/s (1.5Mbyte/s).

3.2Data Signing

All sensitive data created by the instrument will be electronically signed by the instrument to validate its authenticity. The digital signature will be checked by the T1 software and an error will be displayed if the signature is invalid, as this would indicate that the data has been corrupted or tampered with.

3.3Communication Protocol

A communication protocol will be developed to enable data logs, gas tables, setup information, firmware updates and feature updates to be transferred between the T1 software and the instrument.

The protocol will use a binary format as this will be more compact and therefore faster than an ASCII based protocol.

It is expected that the data will be sent as messages, each comprising an 8-byte header and a variable length message body:

4-byte tagThis specifies the message type

4-byte lengthThis specifies the length in bytes (n)of the data that

follows

n bytes of dataThe actual data (may be empty)

The T1 software will send one message to the instrument at a time and shall expect a response to each message before sending a further message.

It is expected that the protocol will allow message to contain other messages. For example, a Data Log Request message from the T1 software should produce a Data Log Response message from the instrument. The latter could comprise several messages, such as: Data Log Header, Instrument Serial Number, Data Log Items, Data log Signature.

Unknown messages should be ignored to enable interoperability between old software and new firmware (or vice versa). For example, future firmware releases might provide extra messages within the Data Log Response Message which would only be processed by software which recognized those messages.

The message protocol should be suitable for use over a single communication channel such as a serial communication link or TCP/IP stream, and should not rely on specific USB features or use multiple data streams.

The message protocol should be consistent to simplify the implementation in both the T1 software and the instrument firmware.

Time limits shall be defined for sending and responding to messages to ensure that the communication failures can be detected and reported (without the software freezing).

3.4Typical Messages

Typical messages from the PC to the instrument, each defined by a 4-byte tag, are likely to include:

  1. Read status.
  2. Read Instrument Information.
  3. Read real-time Measurement.
  4. Read/Write Data Log directory.
  5. Read a specific Data Log.
  6. Send/receive Gas Table.
  7. Send/receive Calibration Information.

Typical messages from the instrument to the PC are likely to include:

  1. Instrument status (OK or error code and error message). This could include messages such as ‘message not known’ etc.
  2. Send Instrument information.
  3. Send real-time measurement.
  4. Send Data Log directory.
  5. Send a specific Data Log.
  6. Send/receive Gas Table.
  7. Send/receive Calibration Information.

3.5Initial Connection

When an instrument is connected to the PC’s USB port the T1 software will send a Read Instrument Information message to it. The instrument should respond with an Instrument Information message providing the model number, serial number, firmware version etc.

The Instrument Information message should also indicate any faults detected by the instrument, such as memory failure, self-test failure, hardware faults etc. Any problems will be immediately reported in an alert window with the option to abort or continue.

3.6Communication DLL

All of the communication protocols and routines will be implemented in an IonScienceComms DLL. This DLL will provide a documented API to enable other software applications to communicate with PhoCheck T1.

4.User Interface

4.1Windows

When the T1 software is started a single window will appear with a menu bar at the top (see section 4.2 below).

By default all other windows will open within the main window. These will include the Setup window, Gas Table window and one or more Data Log windows etc. Optionally, the software may allow windows to be used outside of the main window – to be decided.

Since only one instrument can be connected at any one time, it will only be possible to open one Setup window.

It should be possible to open multiple Data Log windows to view data logs from a file or read from the instrument and compare them side by side. Each Data Log window will show the text and graph, side by side.

The Windows menu will provide options to tile or stack the windows.

4.2Menus

The T1 software shall provide the following menu items, in a menu bar at the top of the T1 Window:

Top menu / Sub-menu / Description
File / Print setup… / Configure font, font size and margins
Print preview… / Show on-screen what would be printed. Note this option may not be needed if the the information is printed in the same format as is displayed
Print... / Print the contents of the currently selected window (Ctrl-P can also be used)
Exit / Close the program. A warning will appear in a dialog box if any data is unsaved.
Edit / Copy / Copy data from selected window to clipboard in plain text and CSV formats. If a graph is selected it will be copied to the clipboard as an Enhanced Metafile (EMF) file, suitable for pasting into Microsoft Word etc. Note this is a vector graphic format which can be scaled and zoomed without loss of quality.
Cut / Cut selected text (e.g. in dialogue box) to clipboard
Paste / Past text from clipboard to selected region (e.g. a dialogue box)
Calibration / Read from instrument / Reads calibration information from the instrument.
Open / Opens previously saved calibration data file (.isc)
Save / Updates already saved open files (.isc))
Save as / Saves open files.
Export / Exports calibration as a CSV file allowing the data to be used in Microsoft Excel.
Erase calibration data… / To be clarified with Ion Science.
Data Log / Erase all data… / Erase all data from the connected instrument
Read from instrument / Reads a data log from the instrument: A list of logs in the instrument will be displayed to the user to enable one to be selected. An option to read all logs may also be provided.
Open / Load saved data log from a .isd file.
Save / Save the data log to a .isd file. A standard save dialog box will appear enabling the directory to be chosen.
Export / Save the data as a .csv (Comma Separated Value) file, suitable for loading into a spreadsheet such as Excel.
Gas Table / Open / Open a previously saved gas table file
Save / Save gas table to file it was previously saved to (or prompt for new file name).
Save as… / Save gas table to a new file
Send to instrument / Send gas table to instrument
Read from instrument / Read gas table from the connected instrument.
Export as CSV… / Save gas table as a CSV file (note copy and paste can also be used to transfer the data in CSV format to a spreadsheet).
Choose columns… / Choose which gas table columns are displayed.
Instrument / Instrument Info / Read and display information about the connected instrument, such as model number, serial number, firmware version, feature details etc. See section 4.4
Real-time Measurement / Open a window showing a real-time display of the gas concentration being measured by the instrument – see section 4.4 below.
Instrument Setup / Open instrument setup window (see below)
Instrument upgrade / Upgrade instrument functionality/features using an .iup file supplied by Ion Science.
Firmware upgrade / Upgrade instrument firmware using a .isf file supplied by Ion Science. See section 4.11 below for details).
Restore instrument / Restore the instrument using its saved recovery file (if there is one). See section 4.13 below.
Window / Arrange all / Show all windows
Tile / Arrange windows by tiling them so they are all visible (options for arranging vertically and horizontally may also be provided)
Cascade / Show windows stacked behind each other
View / Toolbar / Toggle toolbar display
Status bar / Toggle status bar
Help / About / Display information about the T1 software including the publisher, author, version, etc.
Help / Opens a PDF copy of the user manual, this contains the information regarding this software package and instrument functionality. (A PDF reader must be installed on the PC for this to work).

Notes:

  1. A ‘Data Log - Save as’ menu option shouldn’t be needed as the Save menu will always open a file dialog box. Note that the data cannot be changed without reading new data from the instrument, so saving without entering a filename won’t be possible.

4.3Buttons

On-screen buttons will be provided for the following functions:

  • Open
  • Save
  • Cut
  • Copy
  • Paste
  • Print
  • Real-time Measurement
  • Help

4.4Real-time Measurement

The Real-time Reading window will display:

  • Gas details
  • Real-time measurement (large display)
  • Threshold levels

The gas level shall be displayed numerically (not graphically).

If upper and lower threshold limits are defined then an alarm will sound while the limit is exceeded (via the default Windows sound system).

The display will continue to be updated until the window is closed or the instrument is disconnected.

Other communication with the instrument while the real-time measurement is operating may not be allowed (to be decided).

4.5Instrument Setup Window

The Instrument Setup window allows the instrument to be configured:

The instrument Setup includes:

  1. Backlight: on, off or timed.
  2. Audible beep: at key-click and alarm when threshold exceeded.
  3. Units for the instrument to use: parts per million (ppm), parts per billion (ppb) or mg per cubic metre (mg/m3).
  4. Lock?
  5. Time and date format, with an option to set the instrument clock from the PC’s clock whenever the instrument is connected to a PC.
  6. Zone names for up to 20 zones (only 7-bit ASCII characters allowed).
  7. User calibration for each gas (a single set of R.H., temperature and pressure values may be entered too).
  8. A/B function button allocation.
  9. Automatic zeroing (to prevent negative readings).
  10. Lamp selection.
  11. Behaviour when log memory is full: alarm or overwrite oldest data.
  12. Vibration: on/off.
  13. Instrument name to appear on start-up screen.
  14. Instrument logo to appear on start-up screen (a black and white bitmap of fixed resolution– to be defined).
  15. Signal averaging to smooth readings.
  16. Use factory or user calibration (not shown above).

On-screen buttons should be provided to Read the Setup from the instrument, Send the Setup to the instrument, Save the Setup to a file, or Open a previously saved Setup file. It should be possible to send a Setup file created for one instrument to another instrument so users can quickly configure multiple instruments with the same settings.

The settings in the Instrument Setup window only affect the behaviour of the instrument – they do not affect the T1 software behaviour (but see the T1 Program Options described in section 5 below).

Note: The firmware update icon shown above may be moved to a different menu or 1dialogue box.

4.6Data Logs Directory

When an instrument is initially connected to the PC the directory of Data Logs within the instrument will normally be displayed (unless the relevant T1 program option has been turned off – see section 5.1).

The directory will show a list of Data Logs in the instruments, including the file number, start date and time, number of readings and log duration.

The software will allow one or more data logs to be selected. The normal windows convention will be used to select multiple logs – Ctrl-Click will toggle a particular log while Shift-Click will select all logs up to that point. An option to read all Data Logs may also be provided.

4.7Data Logs

Data Logscan be read from the instrument, saved to a file for future reference or loaded from a file. They cannot be sent back to the instrument.

The instrument will generate a hash key when the Data Log is read from it. The T1 software will save this key with the Data Log when saving to a file, and validate it when loading Data Logs to ensure that the data is valid and unmodified.

A check box will be provided to determine whether the data is deleted within the instrument when it is read by the T1 software. A configuration option will be provided to set the default state of this check box.

When a Data Log is read from the instrument or loaded from a previously saved file it should be displayed in a window, in three sections:

  1. The header will show the instrument serial number, file number, download data and time, file integrity, zone, log start date and time, and log duration.
  2. The date, time and concentration as a 3-column table (with column headings showing the gas and units, e.g. ppm).
  3. A graphplotting the concentration against time.

A scroll bar will allow the table to be scrolled.

Clicking in the graph region of the Data Log Display will cause a vertical cursor to be plotted on the graph and a time and measurement for that time should be displayed. The relevant measurement in the numerical table will also be highlighted.

Conversely, selecting a numerical measurement will highlight that value on the graph.

The maximum recorded concentration will also be displayed beside (or on) the graph.

4.8Graph Functions

The graph x axis should show real-time (date and time) or elapsed time (in hours, minutes and seconds, starting from 0).

The y axis should be labelled in ppm, ppb or g/m3 as defined by the units specified in the Data Log received from the instrument (it shall not be possible to change the units as they are specified by the instrument configuration).