phocheck t1 windows software specification€¦ · web view6.2 usage case 1: agent updates...

PhoCheck T1 Windows Software Specification

Reference: T1Version: v1.00

Date: 25 October 2008

Document history:v1.00, 25 Oct 2008 First release

PhoCheck T1 Windows Software Specification v1.00v1.00v1.00, 25 October 2008

Contents

1. Introduction 4

2. General Information 52.1 Overview 52.1 Target Platform 52.2 Program Name and Icon 52.3 Automatic Start-Up 52.4 Multiple Instruments Are Not Supported 5

3. Communication 63.1 USB Communication 63.2 Data Signing 63.3 Communication Protocol 63.4 Typical Messages 73.5 Initial Connection 73.6 Communication DLL 7

4. User Interface 84.1 Windows 84.2 Menus 84.3 Buttons 104.4 Real-time Measurement 104.5 Instrument Setup Window 114.6 Data Logs Directory 124.7 Data Logs 124.8 Graph Functions 134.9 Gas Tables 144.10 Calibration 154.11 Firmware Update 164.12 Feature Update 164.13 Recovery File 16

5. T1 Program Options 185.1 Data Log Options 185.2 Graph Options 185.3 General Options 18

6. Web Based Update 196.1 Introduction 196.2 Usage Case 1: Agent Updates Features Before Sale 196.3 Usage Case 2: Agent Updates Instrument After Sale 206.4 Usage Case 3: Ion Science Updates 206.5 Usage Case 4: Ion Science Month-End Invoicing 206.6 T1 Software 216.7 Feature Update File 216.8 Instrument Software 226.9 Server Software 226.10 Web Browser Compatibility 226.11 Security and Backups 236.12 Benefits 23

2


Appendix A File Extensions 25

Appendix B Instrument Data Items 26B.1 Instrument Identification and Status 26B.2 Instrument Calibration 27B.3 Data Log 28B.4 Gas Table 29

Appendix C Future Options (and Other Non-Deliverables) 30C.1 General 30C.2 Email Alerts 30C.3 SMS Text Message Alerts 30C.4 Foreign Language Options 31C.5 T1 Software Updates 31

Appendix D Outstanding Issues 32

3


1. IntroductionIon 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 Science PhoCheck 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 below.

4


2. General Information

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

2.1 Target PlatformThe 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.2 Program Name and IconThe software name shall be T1 and it shall use the following program icons:

16x16Logo.bmp

32x32logo.bmp

2.3 Automatic Start-UpWhen 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.4 Multiple Instruments Are Not SupportedOnly 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).

5


3. Communication

3.1 USB CommunicationThe 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.2 Data SigningAll 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.3 Communication ProtocolA 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 tag This specifies the message type4-byte length This specifies the length in bytes (n) of the data that

followsn bytes of data The 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

6


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.4 Typical MessagesTypical 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.5 Initial ConnectionWhen 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.6 Communication DLLAll 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.

7


4. User Interface

4.1 WindowsWhen the T1 software is started a single window will appear with a menu bar at the top (see section 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.2 MenusThe T1 software shall provide the following menu items, in a menu bar at the top of the T1 Window:

Top menu Sub-menu DescriptionFile 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.

8


Top menu Sub-menu DescriptionOpen 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 fileSend to instrument Send gas table to instrumentRead 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 below.

Instrument Setup Open instrument setup window (see below)

Instrument upgrade Upgrade instrument functionality/features using an .iup file supplied by Ion Science.

9


Top menu Sub-menu DescriptionFirmware upgrade Upgrade instrument firmware using a .isf

file supplied by Ion Science. See section below for details).

Restore instrument Restore the instrument using its saved recovery file (if there is one). See section below.

Window Arrange all Show all windowsTile 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 displayStatus 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.3 ButtonsOn-screen buttons will be provided for the following functions:

Open Save Cut Copy Paste Print Real-time Measurement Help

4.4 Real-time MeasurementThe Real-time Reading window will display:

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

10


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.5 Instrument Setup WindowThe 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.

11


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 below).

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

4.6 Data Logs DirectoryWhen 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.7 Data LogsData Logs can 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.

12


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 graph plotting 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.8 Graph FunctionsThe 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).

The y-axis scale will be scaled automatically to suit the data being displayed.

Right-clicking on a graph will produce a menu with the following options:

Remove the cursor Modify the graph options (section 5.2) Copy the graph to the clipboard (as an Enhanced metafile) Show Elapsed time or real time. Y axis labelling: from zero or automatically scaled for the minimum

reading (false zero). Show individual readings as markers (circles or crosses – to be

decided). Zoom to expand a particular time region. Save Graph as an EMF file.

An option will be provided to hide the numerical data (and possibly the header) so the graph can expand to fill the window.

A Graph menu offering these functions may also be provided in the menu bar.

13


If the Data Log from the instrument specifies an upper or lower threshold for the gas concentration then these thresholds will be shown as horizontal lines on the graph.

Support for GIF or PNG export may also be provided (if, as expected, it requires no additional software effort)

4.9 Gas TablesGas Tables can be read from the instrument, edited and sent back to the instrument. They can also be saved to a file for later use.

Gas tables can be shared between instruments so it will be easy to produce a custom gas table and send it to multiple instruments, to avoid customers with multiple instruments needing to setup each one manually.

Gas tables will be displayed in the T1 software in a spreadsheet-type window, showing one gas per line with the following gas table items shown in separate columns for each gas:

Gas table item Default Instrument

dependantSelect Y NGas name Y NAbbreviation N NFormula N NAr 11.7 lamp N YKr 10.6 lamp N YD2 10.2 lamp N YXe 8.4 lamp N YHigh alarm Y NLow alarm Y NEH40 ppm STEL N YEH40 ppm TWA N YEH40 mg/m3 STEL N YEH40 mg/m3 TWA N YOSHA ppm STEL N YOSHA ppm TWA N YOSHA mg/m3 STEL N YOSHA mg/m3 TWA N YNIOSH ppm STEL N YNIOSH ppm TWA N YNIOSH mg/m3 STEL N YNIOSH mg/m3 TWA N YISL Y N

A menu option should allow the user to select whether each column is displayed or hidden. The table above indicates which of the columns are displayed by default.

If an instrument is connected then some of the instrument dependant options can also be displayed. The precise behaviour needs to be clarified by Ion Science.

14


The user will not be able to edit any gas table entries supplied by Ion Science but will be able to add upper and lower thresholds for each gas and also add new gases.

A check box will be provided alongside each gas to allow the user to select which gases are available for selection within the instrument. This allows the instrument to be customise to only show the gases which each customer is likely to need.

4.10 CalibrationCalibration data can be read from the instrument, saved in a file or sent back to the instrument.

The T1 software will not allow calibration data for one instrument to be used by another instrument. A unique instrument serial number shall be stored within the calibration file to prevent this.

4.11 Firmware UpdateInstrument firmware may be updated using a .isf file supplied by Ion Science, which would typically be emailed to the customer. This option will send the firmware update to the instrument which will respond to indicate whether the firmware update is acceptable (e.g. for the correct instrument and serial number). If the instrument responds with an error an error message will be displayed on the PC screen.

When the instrument successfully receives a valid firmware update file it should shut-down and restart using the new firmware.

4.12 Feature UpdateA .iup feature upgrade file provided by Ion Science can be used to update an instrument connected via RS232. The upgrade file can be double-clicked in an explorer window to start the upgrade or loaded via the Instrument menu. In either case, the T1 software will automatically transmit the file to the instrument.

It is expected that Ion Science will distribute upgrade files via email or via a web download.

The instrument will automatically shut down but will gain it's additional functionality when restarted.

Note: It is recommended that Ion Science provide a mechanism for the T1 software to determine whether the file is suitable for the instrument (e.g. correct model and serial number) to enable the T1 software to report an error. This could be defined within the protocol, so the instrument could check and send an OK/ Fail response back.

4.13 Recovery FileThe T1 instrument has a serial number chip which supplies a 16 digit number making them identifiable even after a firmware change. 12 digits

15


within this number are unique and will be used as the instruments serial number.

When a T1 instrument is first connected to the T1 PC software a 'Recovery file' or ‘footprint’ (with an isr extension) for that instrument is automatically saved in a file. The Recovery file contains the Instrument Setup, Gas Tables, Calibration and possibly the Data Logs, all read from the instrument. The serial number of the instrument is used to create the file name, e.g. 456789ABCDEF.isr

When the instrument is subsequently reconnected to that same PC the T1 software checks to see if a recovery file is already saved. Assuming there is already a file saved on the hard drive the date of calibration is compared with that in the pre-saved file. If the date of the calibration in the instrument is later than that in the pre-saved recovery file it is over written.

If the instrument is connected to a different PC running the T1 software it will store its own copy of the Recovery File.

The aim is to keep the recovery file reasonably up to date particularly regarding the calibration. The recovery file is not saved every time the instrument is connected as this could potentially result in a corrupted recovery file being created.

The Restore Instrument menu item can be used to restore the instrument using the Recovery File. The T1 software will send the Recovery File to the instrument and display the instruments’ response.

If no recovery file exists an error message will be displayed.

The Recovery File will not contain details of any Feature Updates that have been applied (otherwise there is a risk that customers could add new features by modifying the Recovery File which is unencrypted).

16


5. T1 Program OptionsThe T1 software should provide several configuration options to enable the user to control how the software operates.

5.1 Data Log OptionsData Log options should include:

Automatically start when instrument connected Automatically open Data Log Selection window when instrument

connected Automatically save Data Logs to disc when read (using filename

generate from the date and time of the first log reading) Automatically delete Data Logs within the instrument when read.

5.2 Graph OptionsGraph options should include:

Line colour Grid colour Line thickness Grid thickness Label font and font size Grid lines on/off Grid line density (to display just a few or a lot of grid lines –

probably three levels). Graph background colour

5.3 General OptionsGeneral options should include:

Units for the T1 software to use: parts per million (ppm), parts per billion (ppb) or mg per cubic metre (mg/m3). These units will be used for the real-time display.

Alarm action: sound via Windows sound system/via computer’s internal speaker.

17


6. Web Based Update

6.1 IntroductionIon Science currently allows agents to create feature update files which are then emailed to customers to enable instruments to be upgraded. While some checking is performed agents are trusted to accurately report the updates that they sell.

There are several problems with this approach:

1. Ion Science do not know which features are enabled in which instrument and need to maintain this information manually.

2. Agents could abuse the system and sell feature updates without paying Ion Science.

3. Ion Science rely on agents accurately reporting the Feature Updates theyhave sold and the process is prone to errors.

4. The process is cumbersome and time consuming for Ion Science, their agents and end customers.

This system could be improved by using a central database running on a web server. Ion Science and their agents would be able to log-in to the database using their unique username and password. Once logged in, the database would allow users to view or modify the features available on a particular instrument by entering its serial number.

The T1 software would communicate directly with the database to update individual instruments.

6.2 Usage Case 1: Agent Updates Features Before SaleAn agent needs to update an instrument before it has been shipped to a customer:

1. The agent connects the instrument to a PC running the T1 software.

2. The agent uses the Feature Setup menu which is only available to Ion Science and agents. The T1 software reads the serial number and existing feature set from the instrument. A list of features is displayed with existing features already selected. The agent selects the additional features required and clicks on the Update button.

3. The T1 software communicates with the Ion Science web server via the Internet and provides the agent user name and password (stored in a file on the agent’s PC) and the serial number of the instrument. The server records the details and responds with a Feature Update file which the T1 software sends to the instrument.

4. The T1 software displays a suitable message to indicate that the instrument has been upgraded or it displays an error message if the instrument rejects the file.

Note the amount of data being transferred is very small and the server transaction should take less than 5 seconds and the whole process including

18


the entry of the serial number and selection of the features should take no more than 30 seconds.

6.3 Usage Case 2: Agent Updates Instrument After SaleAn agent needs to update an instrument that has been shipped to a customer:

1. The agent asks the customer for the serial number and takes payment for the update (or raises an invoice).

2. The agent logs-in to the web-based server using their unique log-in name and password. They enter the serial number of the instrument and see the existing features in the instrument. The agent selects the additional features required and clicks on a Submit button.

3. The server immediately records the transaction and updates the record for that instrument.

4. The agent instructs the user to select the Feature Update menu.

5. The user connects the instrument to a PC running the T1 software via a USB cable and selects the Feature Update option. The T1 software reads the serial number from the instrument and sends this to the server via the Internet. The server responds with a Feature Update file which the T1 software sends to the instrument.

6. The T1 software displays a suitable message to indicate that the instrument has been upgraded or it displays an error message if the instrument rejected the file.

The whole process should take just a few seconds so it would be quite feasible for the agent to enable the new features and confirm that the customer has updated the instrument during a phone call.

6.4 Usage Case 3: Ion Science UpdatesIon Science would update instruments in exactly the same way as agents, either before or after the instrument has been shipped.

In addition, the T1 software could be allowed to update units without connecting to the web server, to ensure that updates can still be generated even if the web server fails.

6.5 Usage Case 4: Ion Science Month-End InvoicingIon Science would display a sales report grouped by agent showing the number and type of each update in a specified month. This would include updates performed by Ion Science as well as their agents. The report could also include the customer’s name (if entered) or instrument serial number. The web page could be printed as a permanent record.

Note: In future software releases, this could be extended to calculate the invoice total for each agent, but that feature is NOT included in this proposal.

19


6.6 T1 SoftwareThe T1 software would provide two menu options:

Feature Update would be available to all users as a menu option. It would cause the T1 software to communicate with the Ion Science server to request a Feature Update file for the connected instrument (using the instrument’s serial number). If the web server provides a Feature Update file the T1 software would send it to the instrument and check the response. If no updates are available the T1 software could display a web page showing the features which are available to purchase (typically by contacting Ion Science or an agent).

Feature Setup would only be available when a special Agent file is installed on the PC. The Agent file contains the username and password needed to access the server and is not encrypted. If the Agent file is present the Feature Setup option displays a list of available updates for to the user and allows them to be selected individually. The T1 software will then send the update request to the server, together with the username, password and instrument serial number. The server should then respond with a Feature Update file for the instrument and the T1 software would send this to the instrument, as above. Alternatively, an error message would be displayed if the server could not be contacted or if the username/password combination was invalid.

The T1 software would not attempt to decrypt or process the Feature Update file at all – it would merely send it to the instrument in a message.

6.7 Feature Update File The Feature Update file would contain the unit serial number and a Feature Table containing a series of Feature Bytes, for example:

16-bytes Serial number16-bytes Date and time file was created1-byte Sensivity configuration1-byte Data logging feature1-byte Health and safety feature13-bytes Reserved for other featuresn-bytes Padding to ensure file is multiple of 64-bits

The file would be encrypted using a simple encryption algorithm such as TEA (see http://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm). This is extremely easy to implement as it comprises less than 10 lines of C code.

6.8 Instrument SoftwareThe Instrument firmware would need to accept the Feature Update file via a message sent over the USB interface. It would decrypt the file (typically using the TEA decryption routine which is just a few lines of code), check the serial number is correct and then write the feature table to Flash memory.

20

http://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm


The private key would be included in the instrument firmware.

6.9 Server SoftwareThe server software would be written in Perl and would be based on Octopus Systems’ existing FlexiData software which is being used by other clients for similar applications.

FlexiData is easy to install and will run on Apache or Microsoft IIS web servers on Linux or Windows servers.

FlexiData provides several access levels. Ion Science would have administrator access to the system which would enable them to create new accounts for agents, in addition to all of the other functionality.

Individual agents would each be allocated their own unique user name and password which would enable them to log-in to the database.

Once logged in the system would prompt for an instrument serial number. It is proposed that the serial number include the model number in some form, for example, all T1 instruments could have a serial number starting from 1,000,000. While T2 instruments could have a serial number starting from 2,000,000 etc. This avoids the need to select an instrument model as well as a serial number, although this step could still be performed as an extra check.

For additional verification the serial number itself could include a check digit which the server could validate to ensure that it had been entered correctly.

Once a serial number has been entered the FlexiData software would display the record for that instrument. This would include the features available in the instrument and optionally the agent or supplier’s name (where appropriate) and the end-user’s contact details.

If the record corresponding to the entered serial number doesn’t already exist then a default record would automatically be created (providing the serial number is valid). The agent’s name would also be associated with the instrument.

6.10 Web Browser CompatibilityFlexiData has been tested with a wide range of web browsers running on different operating systems. It even works on mobile browsers, so an agent could even use a mobile phone (with a web browser) to remotely enable features in an instrument.

6.11 Security and BackupsThe feature update file sent to the T1 software would be encrypted using a simple algorithm and private encryption key. The T1 software would not decrypt the information received from the server but would pass it to the instrument to decrypt. Source code for common encryption algorithms such as TEA is widely available

21


The private encryption key would be stored on the web server and also in the instrument firmware. While it would technically be possible to extract the key by reverse engineering the Flash firmware this would be quite challenging and is not considered a risk for our purposes.

FlexiData records every transaction in a transaction log for extra security and this can be viewed via a web page.

A backup of the main instrument database can also be created on the server automatically every day. For additional security the database file should be backed up periodically.

While it would be quite possible to run the server software on Ion Science’s existing web site, it would be more secure to use a different server with a suitable domain name, e.g. www.ionscience-updates.com. This would ensure that unauthorised users, such as web developers, did not have access to the database, encryption software and encryption key.

The server files would contain the secret encryption key used to encrypt the data, but the server files themselves would not be encrypted so it would be important to restrict the number of people who had FTP access to the server.

A dedicated server would provide the maximum level of security, but for this application a low-cost shared server should be quite acceptable.

6.12 BenefitsThere are several benefits in this approach:

1. The update would be generated and supplied automatically by the web server.

2. Individual files would not need to be manipulated by Ion Science or the customer, making it easier and quicker for both parties.

3. The upgrade process is extremely simple for the user. It requires a single menu item to be selected and the update proceeds automatically in less than 10 seconds.

4. Other parties, such as agents, could be allowed access to the system to provide updates to customers

5. A monthly summary of the updates created by agents would be created for billing purposes.

6. The update option would be provided within the software, thereby encouraging users to upgrade.

7. The database can be viewed or used by anybody with a username and password.

8. The user cannot update multiple instruments with a single update file.

22

http://www.ionscience-updates.com/


9. If your invoicing system permits it, integration between the FlexiData database and your invoicing system could be provided at extra cost.

Octopus Systems have already developed a similar system for distributing encrypted upgrades containing updates marked with a serial number for specific hardware via a web site and have the server database, download functionality and encryption system working already. It is currently being used by other clients to distribute updates and manage web-based databases.

23


Appendix A File ExtensionsThe following file extensions are used by the T1 application:

Extension Description.isr Instrument Recovery File.isg Instrument Gas Table.isc Instrument Calibration Data.isd Data Log.isi Instrument Information .iss Instrument Setup.isu Feature update.isf Firmware upgrade.isg Gas table

Note that existing files with these extensions, created by earlier software, will not be compatible with the T1 software.

24


Appendix B Instrument Data ItemsThe tables below show the data items in the instrument which are readable by the T1 software:

B.1 Instrument Identification and StatusIdentification of the instrument by the PC softwareElement Size (bytes) NotesInternal serial number 8 Unique serial number from IC on the main

PCBInstrument name 20 A name for the instrument assigned by the userVisible serial number 13 Issued at time of manufactureInstrument configuration 9 What functions are preselected on the

InstrumentRun time 2 The amount of hours the instrument has been

running since manufactureCalibration date 4 The date when Factory Calibration was carried

out. A coloured circle should be placed next to the Factory calibration date.Green circles between 0 to 11 months oldAmber circles between 11 and 12 months oldRed circle after 12 months old

Battery capacity (Status) 2 Displayed as a percentage of remaining powerA coloured circle should be placed next to the Factory calibration date.Green circles between 100 and 20 % chargeAmber circles between 20% and 5% chargeRed circle between 5% and 0% charge.

PID lamp status 1 A circle next to the Lamp status indicates its status.Green lamp is workingRed lamp has failed to strike

Filter status 1 The state of the filter can be detected by the instruments flow sensor.A coloured circle should be placed next to the Filter status text.Green circles between down to 200 cc/min flowAmber circles between 200 and 150 cc/min flowRed circle from between 150 to 100 cc/min flow

Pump status 1 Status indicated by flow sensors.A coloured circle should be placed next to the Pump status text.Green circles between down to 100 cc/min flowRed circle from between 100 to 0 cc/min flow

25


B.2 Instrument CalibrationTwo sets of calibration data are held within the instrument. The factory calibration is fixed when the instrument is manufactured and cannot be overwritten by the T1 software. The user calibration can be edited and updated via the T1 software.

Calibration - FactoryElement Size

(bytes)Notes

Serial number 13Instrument name 20 A name for the instrument assigned by the userCalibration date 4 The date when Factory Calibration was carried outDate / time 7

Zero A/D (Part of calibration) 4PID sensor technology doesn't have a linear output. Therefore three points are used to calibrate the instrument. Clean gas is sampled by the instrument to set the ZERO level, then 100ppm of Isobutylene gas is used to set the Span 1 (low level) cal and the 1,000ppm is used to predict Pan 2 (higher) level.

Span 1 A/D (Part of calibration) 4


Gas name 50Lamp type 1

Calibration - UserElement Size (bytes) NotesSerial number 13Instrument name 20 A name for the instrument assigned by the userCalibration date 4 The date when Factory Calibration was carried outDate / time 7

Zero A/D (Part of calibration) 4 PID sensor technology doesn't have a linear output. Therefore three points are used to calibrate the instrument. Clean gas is sampled by the instrument to set the ZERO level, then 100ppm of Isobutylene gas is used to set the Span 1 (low level) cal and the 1,000ppm is used to predict Span 2 (higher) level.



Gas name 50Lamp type 1

26


B.3 Data LogData logs are typically generated automatically by the instrument with samples being taken at fixed intervals.

Data - (Instrument Header)Element Size (bytes) NotesSerial number 13Instrument name 20 A name for the instrument assigned by

the userFactory Cal date 4Date / time 7Zero A/D 4Span 1 A/D 4Span 2 A/D 4Gas name 50Lamp type 1

Data file (Log Details)Element Size (bytes) NotesFile number 1Integrity 1Zone 8Health and Safety 1 Selectable function onlyAlarm 1 2Alarm 2 2Gas 50Lamp 1Units 1Temperature 1Humidity 1Data format 1 Specifies whether the GPS co-ordinates

are provided – to be used for future expansion.

Data file (Actual Measured Data)Element Size (bytes) NotesDate/time 4 Encoded as number of seconds from

reference time.Concentration 2 Gas concentration (units specified

above).GPS co-ordinates (8) Optional longitude and latitude (where

available). Not supported in current software, but reserved as an option for the future.

27


B.4 Gas TableThe Gas Table comprises a header followed by a list of parameters for each gas.

Gas Table (Header)Element Size (bytes) NotesTable name 8Table date 4Gas Table (Content – repeated for each gas)Element Size (bytes) NotesSelected 1 Gases selected on the gas table are

downloaded to the instrument only.Gas name 50Abbreviation 0 Not used at presentFormula 12Molecular weight 2Lamp Ev's 2High alarm ppm 2Low alarm ppm 2STEL alarm ppm 2TWA alarm ppm 2High alarm mg/m3 2Low alarm mg/m3 2STEL alarm mg/m3 2TWA alarm mg/m3 2

28


Appendix C Future Options (and Other Non-Deliverables)

The items described in this section are non-deliverables and shall not be provided by Octopus Systems.

C.1 GeneralFor the avoidance of doubt, the following items shall not be delivered:

1. Support for Windows 2000, Windows ME, Windows 98 or earlier versions.

2. Installation system to install the software (this shall be developed by Ion Science).

3. Installation disc. 4. Help file (PDF format)5. User Guide or end-user documentation.6. PhoCheck T1 firmware.

All of these items could be provided by Octopus Systems at extra cost.

C.2 Email AlertsFuture software versions could provide email alerts when the gas level exceeds the pre-defined alarm threshold (this would apply when real-time monitoring was in operation).

A setup window would enable the user to enter the host name or IP address of the SMTP server, a port number, a destination email address (or a list of addresses, separated by commas), an email title and email message. The port number would default to 25 as this is used almost universally for SMTP email. A default title and message would also be provided.

The email message could also optionally include the actual level and the threshold.

A further option could control how often the email message is sent while the threshold is exceeded (e.g. to send an email alert every hour).

A Test button would be provided to test the configurations by sending a test email via the server. This would immediately report the status, for example: ‘Success’, ‘Server could not be contacted – check details’ or ‘Server not accepting SMTP email’.

Note this feature is NOT included in the current proposal.

C.3 SMS Text Message AlertsFuture software versions could provide SMS text message alerts when the gas level exceeds the pre-defined alarm threshold (this would apply when real-time monitoring was in operation).

Text messages could be sent in two ways:

29


1. Using an SMS Internet gateway. The T1 software would connect to the SMS gateway via the Internet to send a text message. The user would be responsible for opening an account with the SMS gateway provider.

2. Alternatively, text messages could be sent via a GSM modem or mobile phone connected to the PC, plugged in as a PCMCIA card or built-in to some laptops. GSM modems are normally connected via an RS232 serial port, while mobile phones are typically connected via USB cable or Bluetooth. Supporting this diverse range of hardware shouldn’t pose any problem as all of these devices provide a COM port which accepts AT commands for sending SMS text messages.


C.4 Foreign Language OptionsFuture software versions could be made available in foreign languages. This would provide menus and on-screen text messages in a foreign language. The T1 software would use a messages file and it would be relatively simple for a local agent to modify the file, as appropriate.

Since much of the software uses icons, it is likely that there will only be a small number of menu options and text messages to translate.

The messages file, could be structured to include comments, as well as a token indicating the purpose of the message. For example:

# File menu itemsFile:FichierSave:SauverPrint: Imprimer# Edit MenuEdit: ModifierCopy: CopiePaste: Coller

Support for Unicode could easily be included for Chinese and Japanese languages etc.


C.5 T1 Software UpdatesFuture software versions could automatically check for software updates via the Ion Science web site. If new software is available the user could be presented with an option to download it, or if it is chargeable, a link could be provided to the appropriate web page.


30


Appendix D Outstanding Issues1. Should the Data Log be stored in the Recovery file, as originally

suggested by Ion Science? In practice it is likely to be out of date and potentially confusing to the user if old data were to appear in the instrument.

2. Should the Real-Time Measurement function continue to operate while other communication is in progress? It probably isn’t difficult if the T1 software sends a Read command to poll the instrument periodically.

3. How often should the Real-time Measurement be updated? Every second?

4. Can the instrument still be used manually when the Real-Time Measurement is in progress?

5. When plotting graphs should the software automatically interpolate between available readings or simply show them as circles? Should error bars be shown to indicate the accuracy of the measurement?

6. Should the instrument’s Data Log be saved in the Recovery File – this could be very confusing to the user as the Data Log is likely to be several months, if not years, old.

7. Should the Recovery File include the instrument’s Feature Table?

8. Can the instrument detect a Flash memory fault and report it to the T1 software when connected? How should the firmware and feature set be restored following a Flash fault?

9. The Ion Science specification states, in relation to gas tables, ‘If a pre-save table is opened then just the default columns are shown’. What does this mean? What is a pre-save table?

10. How should the Gas Table columns be shown or hidden when an instrument is connected? Will the columns disappear when the instrument is disconnected? This could be confusing for the user. Can the user manually select which columns should be displayed and override the default behaviour of columns which are marked as ‘instrument dependent’. Could columns be greyed out instead to indicate they are not relevant? Should the software remember which instrument was last used or should a configuration be used to select which instruments are likely to be connected? (This could be set automatically when an instrument is detected, with the option of manually removing an instrument).

11. What does Erase Calibration do? Does it erase the user calibration in the instrument?

12. How should the upper/lower thresholds be set when alarms are used in the real-time measurement mode? Should they be entered into the real-time measurement window, read from a gas table (how?), supplied by the instrument or entered as a T1 program configuration?

31


13. Please confirm that the text description of the icons in section 4.5 is correct.

14. How should the user calibration feature work? Can the instrument be calibrated for multiple gases or only one gas at a time? Can the instrument hold multiple calibration sets simultaneously - Should the user be allowed to enter different calibration factors for each gas in the gas table. What happens if a different gas table is selected? Will some calibration values be discarded if they are for a gas which is not in the new gas table? Can seperate RH, Temperature and pressure values be entered for each gas or are they global parameters which are the same for all of the gases?

15. If the calibration is saved in a setup file it may be applied to a different unit. Is that correct behaviour or should the calibration be unique for each instrument?

16. How are instrument firmware updates managed? Are they chargeable? Could the T1 software automatically check for updates via the web server when an instrument is connected?

17. Should the T1 software be able to switch between ppm, ppb and g/m3 units independently of the instrument? i.e. should the T1 program configuration be able to override the instrument configuration. (An option to ‘Use instrument units’ could also be provided). Note that converting to g/m3 will depend on the gas being measured.

32

phocheck t1 windows software specification€¦ · web view6.2 usage case 1: agent updates...

Documents