Personal tools
You are here: Home → Members → eric → SOS Version 1.0 PERL Cookbook
Navigation
Log in


Forgot your password?
New user?
 
Document Actions

SOS Version 1.0 PERL Cookbook

by Eric Bridger — last modified 2008-05-09 09:36

Steps for installing and seting up an SOS server.

Table of Contents

  1. File List
  2. System Requirements
  3. Installation Steps

File List

  • oostethys  -  the CGI script
  • sos_config.xml - local configuration file.
  • sosGetCapabilities.xml - template
  • sosGetObservation.xml - template
  • sosDescribeSystem.xml - template
  • observation text files
    • E.g. A01_SEA_WATER_SALINITY.TXT

All the files can be downloaded here

System Requirements

  • Perl 5
  • Web service capable of running CGI scripts
  • CGI perl module
  • XML::LibXML  perl module
  • Salinity data to serve.

Installation Steps

  1. Put the oostethys_sos CGI script into your cgi-bin directory and make sure it has execute permission.  Typically this in  the /cgi-bin/ directory of you Web server.  At GoMOOS I installed it in a subdirectory  /cgi-bin/sos/
  2. Put the three XML template files in the same directory
    1. sosGetCapabilities.xml
    2. sosGetObservation.xml
    3. sosDescribeSystem.xml
  3. Put the sos_config.xml file in the same directory.
  4. Edit the sos_config.xml . See Editing the sos_config.xml file below.
  5. Create some data files. See  Creating Data Files below.

Editing the sos_config.xml file


The sos_config.xml is a simple XML configuration file which contains the local information necessary to generate the SOS responses to the three SOS requests:
  • GetCapabiliites
  • GetObservation
  • DescribeSensor
The DataProvider/Publisher section contains self-explanatory fields for information about your organization.  A crucial element is the SOSURL section.  This must contaion the URL for the cgi-bin SOS script, e.g. http://hostname/cgi-bin/oostethys_sos  Unless you  have installed the script in some other location or renamed the oostethys_sos script it should always look like this.

The next section is the DataProvider/ObservationList section.  The ObservationList is made up a one or more Observation sections. Each Observation section contains information about the platform or sensor and a particular data type, in this version, salinity measurments in PSU's.

localPlatformName the identifier by which you refer to the plaform locally.
platformURI a urn prefix to the localPlatformName which assures that the name is unique across the internet. Typically this will urn:hostname:source.mooring#local platform name.  E.g. at GoMOOS we have a localPlatformName of A01.  The platformURI is urn:gomoos.org:source.morring#A01

z is the depth of the observation
latitude, longitude are required and should be in decimal degrees.
startTime, endTime should cover the period for which readings are available and should be in an ISO8601 format in UTC, e.g. 2006-06-28T10:00:00Z.  endTime may be left empty and implies that data is available up until now and into the future.

observedProperty In V0.1 this should always be sea_water_salinity. Support does exist in the script  for sea_water_temperature.

SOSDataFile this should be the  full path to a local file which contains data points for this sensor and datatype combination.  It can be left blank, in which case some sample data within the script will be served. This can be useful for testing purposes.  See Creating Data Files below.

If you have more than one platform / sensor the Observation section must be repeated for each one.

 See the GoMOOS sample configuration file for an example which handles three platforms serving up salinity data.  GoMOOS SOS Configuration XML Example

Required Fields

Not all of the elements in the sos_config.xml file are required. Here is a list of the required elements.
  • OrganizationName
  • OrganizationAcronym
  • ContactPersonName
  • ContactPersonEmail
  • OrganizationURL
  • SOSURL
  • localPlatformName
  • platformURI
  • platformLongName
  • latitude
  • longitude
  • startTime
  • observedProperty
  • SOSDataFile


Creating Data Files


Each sensor and data type has a field called: SOSDataFile  which should contain the full path of the file containing the data for that sensor and data type. 

Note:   Typically a Web Server will not allow writing to the cgi-bin directory, otherwise the files could be placed in the same directory as the oostethys_sos CGI script.  In that case you do not need a full path for the observation file name.  At GoMOOS we run a cron job which queries the GoMOOS database every hour and writes salinity data to a temporary data directory. We use the platform name followed by the data type with a txt extension but any name will work. 

Format of the observation file

The observation file is made up of tuples with 5 fields separated by commas.   The 5 fields are:
  1. Time.  This must be in an accepted ISO8601 format.  E.g. 2006-09-27T10:00:00Z
  2. Latitude: in decimal degress  E.g. 43.7985  This in not degrees, minutes, seconds format.
  3. Longitude: in decimal degrees E.g. -70.3459
  4. Depth:  in meters. E.g. 2
  5. Datum value.  E.g. 38.78

In the data file each record should be separated by a newline.  There would be separate records for different times and depths but each file should represent observations for a single sensor and data type.

Sample GoMOOS Data file

 

2006-09-28T15:00:00Z,42.5277,-70.5665,-1,31.28
2006-09-28T15:00:00Z,42.5277,-70.5665,-20,32.07
2006-09-28T15:00:00Z,42.5277,-70.5665,-50,32.46

This represents the latest salinity readings for Buoy A01 at three different depths.

At GoMOOS we create a new file each hour with the latest readings, but since each record has a time stamp on it, readings for different times could be contained within one file.

Note: You can test your service without creating any data text files by leaving the SOSDataFile element empty in the sos_config.xml file.  In this case the script will return a sample data record.

Testing the SOS Service


The service is designed to be accessible in a web browser and will default to the GetCapabilities request.
E.g. http://www.gomoos.org/cgi-bin/sos/oostethys_sos

Sample requests:

GetCapabilities
DescribeSensor
GetObservation
OOSTethys.org: hosted by GoMOOS | powered by Plone