Synopsis

This document contains information on the operation and administration of the wx/net server-daemon component.

Table of Contents

• Supported Devices
• System Files and Directories
• The .wxpasswd File
• The wxserver.cfg File
• The products/ Directory
• The wxrttmpl.html and wxhisttmpl.html files
• The perswxtmpl.pl file
• Operation
• Starting Up the wxnetd Server
• Stand-alone Mode
• Via wxnet-server-start
• As a Daemon at Boot Time
• Shutting Down the wxnetd Server
• SIGINT (Ctrl-C)
• Via wxnet-server-stop
• Via the sdadmin Tool
• Weather Data Collection
• Event Drivers
• Session Control
• Lightning Detection
• Supported Measurements
• Internally Computed Measurements
• Logging of Data
• The Product Catalog
• The fido.pl script
• HTML/ASCII File Generation
• Enabling HTML/ASCII Generation
• Input Templates and Output Files
• Template Keywords
• Integrating with The Weather Underground's Personal Weather Station Project
• Other Functions
• The Chat Facility
• Security, Passwords, and Permissions
• Initial .wxpasswd setup
• Userid
• Password
• Maximum Login Limit
• Class of Service (COS)
• Administering the Server
• Appendix A: wxserver.cfg Fields
•  General Server Parameters
•  General Weather Device Parameters
•  Maximum WeatherMAX Device-Specific Parameters
•  Appendix B: Administrative Commands
•  General Client-Side Commands
•  General Server-Side Commands
•  wx/net-specific Server-Side Commands

Supported Devices

The following external weather devices are supported by wx/net:
 
• Maximum Instruments WeatherMAX
• Stormwise Lightning Detectors (via LED/photoreceptor serial interface)

System Files and Directories

The wx/net server uses one main directory for storage of dynamic/configurable data.  This directory is $HOME/.wxnet/ on the account from which it is run, and all non-program run-time files needed by the server can be found here (except for logfiles, which can be read or written from anywhere the config file specifies).

The following files and directories are all found under the $HOME/.wxnet/ directory.

The .wxpasswd file

If password checking is to be enabled, a .wxpasswd file must be present in $HOME/.wxnet/.  This file contains the userid, encrypted password, maximum number of logins, and class of service for each user permitted on the system.  For more details, see Security, Passwords, and Permissions.

NOTE: It is highly recommended that the .wxpasswd file permissions be set such that only the account owner may read/write it.  This translates to a chmod of 600.

The wxserver.cfg file

The wx/net server relies on a configuration file to tell it information about the location of the weather device it is connected to, where to log information, and all sorts of other user-configurable parameters.  Upon initially installing the wx/net package, a default wxserver.cfg file will be placed in the etc/ directory under the wxnet/ application hierarchy. This file must be copied to $HOME/.wxnet/ of the account which will be running the wxnetd server program.  Once copied over, the file should be edited to set the parameters as desired.

Upon startup, the wxnetd server program will automatically look for wxserver.cfg in the $HOME/.wxnet/ directory of the account that it is running under.  If this file is not found or cannot be parsed correctly, wxnetd will not be able to start up properly.

The wxserver.cfg file contains instructions and examples of what its various settings are and how to provision your wxnetd server.  This information is also contained in Appendix A at the end of this manual.

The products/ directory

wx/net uses a subdirectory called products/ to contain text and image items for use with the Catalog function.  Within the products/ directory are two subdirectories, image/ and text/.  The image/ directory contains .gif or .ppm image files, while the text/ directory contains ASCII files.  The server expects these rules to be followed, and while putting an image item in the text/ directory won't crash the server, it may crash a client that is expecting to receive a text item from the server.

The remaining files and directories may be located in various places depending on configuration.

The wxrttmpl.html and wxhisttmpl.html files

These are two sample HTML templates that are provided for use with the HTML/ASCII file generation function of the wx/net server.  The wxrttmpl.html file is an HTML template for displaying current readings as well as highs and lows for the current day.  wxhisttmpl.html is much more complex, and shows real-time readings from the past 12 hours as well as highs and lows from the past 7 days.  Both of these files may be copied and modified to suit personal tastes.  HTML/ASCII file generation is discussed in more detail later in this document.

The perswxtmpl.pl file

Located in the etc/ directory, this is a Perl script template for use with the Weather Underground's (www.wunderground.com) personal weather station project.  By using this template in conjunction with HTML/ASCII file generation and TASK spawning, data from the wx/net server can be uploaded to Weather Underground's site at regular intervals.  The template contains keywords for sustitution in the correct places to build a properly formatted upload message.  The $$wugstnid$$ and $$wugpasswd$$ keywords are derived from the WUGSTNID and WUGPASSWD configuration options discussed in Appendix A.  This file may be copied and modified to suit personal tastes.  The script required the LWP package from CPAN to do web uploads.  Note that the perswxtmpl.pl file is not a valid Perl script but merely a template.  HTML/ASCII file generation will use this template to generate a valid Perl script which may then be run as a TASK.  HTML/ASCII file generation is discussed in more detail later in this document.

Operation

Starting Up the wxnetd Server

Stand-alone Mode

The simplest way to start the wxnetd server is to run the server program itself directly.  This is very useful if you are setting things up for the first time and want to make sure that your config file settings are all correct, or perhaps you only want a quick monitoring session of the weather device.  wxnetd is found in the sbin/ directory of the wxnet/ file hierarchy, and may be run directly from there or via a fully qualified path on the command line.  There are two main drawbacks to taking this approach, however.  It requires explicit human interaction for the server to start and stop, and there is no fail-safe mechanism to keep the server alive once started.  Should the server crash when run in this fashion, it must be restarted manually.

Via wxnet-server-start

A startup script is provided to assist with automated execution of the wxnetd process and also to provide some fail-safe capability.  This script, wxnet-server-start,  is also found in the sbin/ directory of the wxnet/ file hierarchy.  The startup script will start the server-daemon process as a child and will remain running in the background.  If it detects an abnormal shutdown from the wxnetd process, it will automatically restart the server.  Because of this ability, the server should be able to be kept up continuously even if fatal errors do occasionally occur.

Upon execution, wxnet-server-start forks off a copy of itself which will execute the main functionality and immediately returns.  This ensures that it always runs as a background task, even if invoked in the foreground.

As a Daemon at Boot Time

The wx/net server program can be made to automatically start when the OS is booted up.  By using the init.d system for starting up system services, the wxnet-server-start script can be run when the system is first booted.  The server will then run in the background, collecting data and ready to service any client requests.  Implementation specifics may vary from system to system, so it is up to the user to figure out how to use the init.d system for invoking the wxnetd server automatically at boot time.  Shutdown may be accomplished in a similar fashion with the corresponding stop script.  See Via wxnet-server-stop  below for further details.

An example file is provided for use with the init.d system.  initwxnetd can be found in the etc/ directory of the wxnet/ hierarchy.  It is a plain shell script and accepts a single parameter indicating "start" or "stop", which the init.d process should pass to it as needed.  To use this file, copy it to the location where init.d scripts are kept.  On a Red Hat system, this could be /etc/rc.d/init.d/.  Once there, edit the file and modify it so it matches the particulars of your system, such as touching/erasing lock files.  You should also modify the $UID variable to contain the userid of the account under which it is to run.  This account must of course contain a $HOME/.wxnet/ directory complete with wxserver.cfg file so the daemon can start up properly.

Once the script has been moved to init.d/, you can specify how it is to be invoked by making symbolic links from it to the run level directories (rc0.d/, rc1.d/, etc).  Within each run level directory, name the link S<nn>wxnetd or K<nn>wxnetd where S signifies a startup script, K signifies a shutdown script, and <nn> is a two digit number indicating the order in which the script will be executed.  This ordering is relative to other scripts in the run level according to the customs of your system.  On a Red Hat system, a typical installation would have /etc/rc.d/init.d/initwxnetd linked to rc0.d/ and rc6.d/ as K17wxnetd, and rc2.d/ and rc3.d/ as S82wxnetd.  These values will start wxnetd just before gpm mouse services, and shut it down just after gpm mouse services. Verify operation on your system, as the init.d "standards" may vary across platforms.

IMPORTANT NOTE:

If the init.d system is to be used, it is imperative the wxnet-server-start be run in the background, as it will not return until the wxnetd script has shutdown, and this will block the boot up process indefinitely.   The script is designed so it always runs in the background because of this.

On the other hand, the wxnet-server-stop script (see  via wxnet-server-stop  below) must NOT be backgrounded, as it necessarily blocks until the wxnetd script has been successfully shut down.  This process can take up to a minute, and the system shutdown process must be paused while this is happening.  Incorrectly backgrounding the stop script will allow shutdown to proceed immediately and the wxnetd server script may not be able to finish all of its processing.

Shutting Down the wxnetd Server

SIGINT (Ctrl-C)

The wxnetd server may be shutdown by sending an interrupt signal (SIGINT) directly to the server process.  This can be accomplished via the kill command, or by hitting Ctrl-C if the server is running in the foreground of a terminal.  This is a perfectly safe and acceptable way to shutdown the server manually, and can be used as a convenient keyboard shortcut when running in the foreground.  Be careful if using the kill command, however, not to send a SIGTERM or SIGKILL, both of which will kill the server immediately without any cleanup being performed.

Via wxnet-server-stop

A stop script is included for shutting down the wxnetd server from the command line without resorting to signals.  The script is called wxnet-server-stop and is located in the sbin/ directory of the wxnet/ file hierarchy.  The stop script will block until the server is successfully shut down.  Thus it is important NOT to background this script if being run from init.d at shutdown time, to allow the server to completely shutdown before proceeding with system shutdown.

Via the sdadmin Tool

The sdadmin tool may also be used to shut down the wxnetd server.  The shutdown command will immediately begin the shutdown process at the server just as the stop script or a SIGINT would.  Once this action is initiated, it is irreversible and the server will have to be manually restarted.  The sdadmin tool does allow for this shutdown to be initiated remotely, but once requested, the tool will lose contact with the defunct server and there is no way to remotely restart it.  Be absolutely sure that you want the server to go down and stay down if this command is going to be issued remotely.

Weather data collection

Event Drivers

Each digital weather station supported by wx/net requires the presence of an event driver specific to that device.  This event driver implements all states, events, constants, and functions required to support the specifics of the particular platform being interfaced with.  This includes real-time as well as historical data functions, serial communications, timings, and any other variable attributes specific to the external weather device's serial protocol.  Each event driver is typically implemented within a single perl *.pl file which will be loaded as needed depending on the value of the MODEL attribute in wxserver.cfg.  By binding in appropriate function callbacks, the event driver tells the wx/net  base software how to set up serial communications, initiate a data collection session, and so forth for the supported device.

Session Control

wx/net uses the concept of a "session" when communicating with offboard devices.  The server can run without a weather device session being active, during which time it will field client requests and perform scheduled functions, but will not communicate with the weather device.  Once a session is activated, communication is established with the external weather device and data is collected according to the state machine implemented in that device's installed event driver.  This may include downloading logged data, collecting real-time or historical data, setting the device clock, and many other functions.  The session may also be shut down, in which case communications are shut down gracefully and any cleanup events such as logging start-up can be performed.  Again, these functions are determined by the installed event driver.

A session can be started automatically through the use of the AUTOSTART parameter in wxserver.cfg.  Otherwise it must be started and stopped using the wxsession command in the sdadmin tool.   When a session is active, it collects R/T weather data from the attached device at fixed intervals, specified by INTERVAL in the wxserver.cfg file.

Lightning Detection

In addition to interfacing with digital weather stations, wx/net also supports interfacing with a separate offboard lightning detector.  The program was developed using a home-built detection circuit hooked up to a Stormwise LSU-2001 lightning detection antenna.  The interface between the detection circuit and the PC is very simple, and any number of lightning detectors can be made to make use of it.

The lightning detection process merely polls the DCD (carrier detect) flag on the lightning detector's serial port to determine if any lightning is being detected.  With the Stormwise setup, a special serial port adapter is needed which accepts a super bright LED and converts the photons to voltage, which is applied to the DCD pin.  This electrically isolates the computer from the lightning detector circuit, although there is no reason why the connection could not be direct.

To interface your own device with wx/net for lightning detection, all that is needed is a serial port interface which toggles voltage to the DCD pin as fast as possible when lightning strokes are detected.  If a given digital weather station handles lightning detection itself, the "driver" for the device within the wx/net software can be programmed to get the lightning information from the device like all the other weather data.

Lightning detection, if enabled, starts and stops in sync with data collection sessions for the digital weather station, despite being hosted off an independent serial port.

Supported Measurements

The wx/net application supports the measurements enumerated below.  The offboard weather device may only actually be able to populate a portion of these fields.  Some of these fields can be populated by wx/net itself if they are derivable from other data.  See  Internally-Computed Measurements  for details.

Real-Time Data

• Wind Speed and Direction
• Wind Chill
• Indoor Temperature
• Outdoor Temperature
• Barometric Pressure
• Barometric Rate of Change
• Indoor Humidity
• Outdoor Humidity
• Dew Point
• Rain Counters (3)
• Date/Time/Time Zone/DST Flag
• Rainfall Rate
• Heat Index
• Lightning Intensity

Historical (Extreme) Data

All measurements include date and time of record.
 
• High/Average Wind Speed and (Prevailing) Direction
• Low Wind Chill
• High/Low Indoor Temp
• High/Low Outdoor Temp
• High/Low Barometric Pressure
• High/Low Barometric Rate of Change
• High/Low Indoor Humidity
• High/Low Outdoor Humidity
• High/Low Dew Point
• High Rainfall Rate
• High Heat Index
• High Lightning Intensity

Internally Computed Measurements

Some measurements which wx/net supports may be calculated internally if the offboard weather device does not handle this calculation on its own (or if specifically requested via the config file).  Currently, Rainfall Rate, Heat Index, Wind Chill, and Dew Point are supported as internal computations, provided that the appropriate readings are present from the weather device.  If the device supplies these measurements on its own and the config file does not force use of the internal computation, the internal computation will be bypassed.  This applies to both real-time and historical records.
 
 

Available Internal Computations

Internally Computed Measurement	Required External Measurement(s)
Rainfall Rate	Rainfall Counter
Heat Index	Outdoor Temp, Outdoor Humidity
Wind Chill	Outdoor Temp, Wind Speed
Dew Point	Outdoor Temp, Outdoor Humidity

In addition to computing these values as needed, wx/net will also track their daily high and low values internally if the offboard weather device does not support it.  When logging the min/max data, these values will be added in with the other values obtained from the weather device.

Logging of Data

wx/net provides facilities for logging of data to disk as it is collected, and later retrieval of this data for plotting or other queries.  The config file may specify one or more directories which can be used to log data.  The "0th" directory is the one which new records will be written to, while it and all others (if any) will be searched for matching records when data is to be read.  A possible usage scenario for this functionality is writing new records to hard disk, but reading old records from both the "new record" hard disk and a CD-ROM containing archives of the last few years' data. The logfile format itself is flat and binary packed with ASCII record separators.  Logfiles are delineated on a monthly basis, and real-time data logfiles are kept separate from extreme data (daily highs and lows) logfiles.

In addition to monthly R/T and extreme logfiles, there may also exists a "partial daily history" logfile (indicated by a .pdh extension) which wx/net uses to hold on to min/max readings until the midnight historical update.  wx/net only logs historical extremes on a daily basis.  However, some offboard logging devices such as the Maximum WeatherLogger grab extreme data along with every R/T collection. wx/net downloads and stores these values until it can perform a midnight collection, at which point it will compare the previous values with the latest to determine the actual extremes for the day.  If wx/net  is shut down before that can happen, the .pdh file is written out so the values may be recovered upon restarting.  The .pdh file is also updated every 5 minutes to combat lost data in the event of a server crash.
 

The Product Catalog

wx/net possesses the ability to transmit external files from directories on the server to a requesting client.  The intent of this feature is to allow the server to keep up-to-date radar images and forecasts as a service to its clients.  There is, however, no restriction on the actual nature of files which may be stored and sent. The clients may then request these external documents in addition to the real-time data stream collected from the offboard weather device.

The directory where these products are stored is $HOME/.wxnet/products/ in the account from which the server is being run.  Within this directory are two subdirectories, image/ and text/ which contain the actual products which may be sent out to clients.  The image/ directory should contain only .gif and .ppm images, while the text/ directory should contain only printable ASCII files.  Failure to follow this guideline may result in a client crash.

The fido.pl script

A reference Perl script called fido.pl (so named because it fetches products from the internet) is provided with the wx/net suite in the misc/ directory.  This script is suitable for downloading NWS text products (forecasts, warnings, etc.) and various image items from the Weather Channel and other sources.  This file may be copied and modified to suit the product catalog population needs of any server.  See comments in the file itself for further details.

HTML/ASCII File Generation

A powerful feature of wx/net is the ability to generate HTML and other ASCII files containing weather data from the server.  This generation function is based on a template/keyword-substitution paradigm.  This means that the user supplies to wx/net various templates which define the layout and structure of the output file which wx/net is to generate.  Within these templates are keywords: special sentinel strings which can be parsed and substituted with real weather data.  In other words, if a user wished to have an HTML web page showing various weather data for a location, the user is not bound to whatever page designs wx/net generates.  Instead, the user designs the web page in any style and using whatever tools desired, and where the data would normally go, keywords describing that data are inserted instead.  When wx/net goes to generate the eventual output file, this user-supplied template is read in, the keywords are scanned for and substituted with real data, and the finished product is written out to a different file.
 

Enabling HTML/ASCII Generation

To enable HTML/ASCII file generation, the HTMLGEN option in wxserver.cfg must be set to Y.  The time interval at which the files will be generated is specified with the HTMLINTERVAL option.  All output files are generated at the same time according to this interval.  For more information on configuring these options see Appendix A.

Input Templates and Output Files

The templates to be used for input and the subsequent output files are specified in the wxserver.cfg file with the HTMLIFILES and HTMLOFILES options.  The input template can be any plain ASCII files.  As long as the wx/net server can find keywords within it to substitute, it will do so and write out a corresponding output file.  For more information one how to specify input templates and output files, see Appendix A.

Template Keywords

The keyword syntax is simple but fairly flexible, allowing for a wide range of data to be represented.  A template keyword consists of four basic parts:
 
• A sentinel wrapper of "$$" at each end of the keyword.
• A string describing which data value is desired.
• An optional data timeframe, enclosed in [ ] characters.
• An optional units specifier, enclosed in ( ) characters.

Sentinel Wrapper Characters

The sentinel wrapper characters are needed to identify keywords to the server so they can be parsed and substituted.  The sentinel string is two dollar signs ($$) and they appear at each end of the keyword, enclosing it.  Example: $$<keyword data>$$

Data Field String

The data field string should be the first item inside the opening $$ sentinel.  This string tells the server what particular datum is to be substituted for this keyword, such as wind speed, outdoor humidity, lightning, etc.  The data field string can indicate that a measurement is a real-time value or that it is a min/max value calculated over the course of a day.  Buth real-time and min/max values can be used in conjunction with an optional data timeframe, which lets the server know when you want the data from.

The following fields are supported for real-time data:
 

Real-Time Measurements

Data Field Strings	Substituted R/T Measurement
winds	wind speed
windd	wind direction
outtmp	outside temperature
outrh	outside humidity
barp	barometric pressure
barroc	barometric rate of change
dewp	dew point
windc	wind chill
hidx	heat index
intmp	inside temperature
inrh	inside humidity
r1	rain counter #1
r2	rain counter #2
r3	rain counter #3
rrate	rainfall rate
time, time12, time24	current time, in 12 or 24 hour format default is 24 hour format
hour, hour12, hour24	current hour, in 12 or 24 hour format default is 24 hour format
minute	current minute
date, dateshort, datelong	current date, with short or long year format default is long year format
year, yearshort, yearlong	current year, in short (YY) or long (YYYY) format default is long format
month	current month
mday	current day of the month
location	station name/location
coords	station lat/lon coordinates
wugstnid	station identifier for wunderground.com's personal wx station project
wugpasswd	password for wunderground.com's personal wx station project
software	"wx/net"
version	current version of wx/net software

Note: All options from "location" down are neither real-time nor min/max specific.
 

The data field can also used to specify min/max data from historical records.  Typically these field names are the same as for r/t data except there is a "high", "low", or "avg" prefix, and an optional "time" suffix (in one of its various incarnations) if the time of the min/max is desired.  For example, "lowouttmp" indicates the value of the low outside temperature, whereas "lowouttmptime" will cause the server to substitute in the time of day when the low outside temp was recorded.  "lowouttmptime12" will render the time in 12 hour format, and "lowouttmpminute" will give just the minutes field of the low temperature time.  The date for which a min/max measurement should be retrieved is requested through an optional data timeframe, discussed below.  Shown in the next table are the possible prefix, data field, and suffix combinations available for use in keywords.
 

Minimum/Maximum/Average Measurements

Base Data Field Strings	Allowable Prefixes (must use one)	Allowable Suffixes (can use zero or one)
winds	high, avg	time, time12, time24, hour, hour12, hour24, minute  (all w/ high prefix only)
windd	high, avg (prevailing)	time, time12, time24, hour, hour12, hour24, minute  (all w/ high prefix only)
outtmp	high, low	time, time12, time24, hour, hour12, hour24, minute
outrh	high, low	time, time12, time24, hour, hour12, hour24, minute
barp	high, low	time, time12, time24, hour, hour12, hour24, minute
barroc	high, low	time, time12, time24, hour, hour12, hour24, minute
dewp	high, low	time, time12, time24, hour, hour12, hour24, minute
windc	low	time, time12, time24, hour, hour12, hour24, minute
hidx	high	time, time12, time24, hour, hour12, hour24, minute
intmp	high, low	time, time12, time24, hour, hour12, hour24, minute
inrh	high, low	time, time12, time24, hour, hour12, hour24, minute
rrate	high	time, time12, time24, hour, hour12, hour24, minute
lightning	high	time, time12, time24, hour, hour12, hour24, minute
time, time12, time24, hour, hour12, hour24, minute	minmax	{none}
date, dateshort, datelong, year, yearshort, yearlong, month, mday	minmax	{none}

Data Timeframe Specifier [ ]

With each real-time and min/max data field string, there may be used an optional data timeframe specifier.  This is a value enclosed in square brackets [ ] which tells the server to substitute in data from a particular time.  If no timeframe specifier is used (or a specifier of [0]), the server uses current values.  For min/max fields, this is the running min/max for the current day.  Otherwise, the server calculates the time/date for which data is desired from the specifier and retrieves that data out of logs.

Note: there must be data logs present for the timeframe feature to work.  If no logging is being done, the server will not have any historical data to retrieve.

The data timeframe specifier is a negative number, and it indicates an offset from the time/date at which the substitution is done.  For real-time measurements, this offset is in minutes.  For min/max measurements, the offset is in days.  To get the wind speed from (approximately) 45 minutes ago, one would use $$winds[-45]$$ in the input template.  To get the low outdoor temperature and the time at which it occured from 6 days ago, use $$lowouttemp[-6]$$ and $$lowouttmptime[-6]$$ in the input template.

In the case of real-time data, the timeframe specifier indicates to the wx/net server an approximate timeframe to retrieve data for.  This is because logging is done at a specified interval, say every 7 minutes, and there is no guarantee that an observation will be recorded at the exact minute specified by the timeframe indicator.  wx/net will try to find the closest recorded observation and will use that.  This convention carries over to the time and date related data fields also. When using, for example, $$time[-300]$$ and $$date[-300]$$, these will indicate the time and date of the closest measurement taken approximately 300 minutes ago.

The wx/net server can tell whether a data field is real-time or historical by the presence of a high/low/avg prefix, and will interpret the data timeframe value accordingly.  However, time and date are slightly different because there is no "high" or "low" time that is not associated with a particular min/max measurement.  These two fields are assumed to be real-time (i.e. timeframe is interpreted as minutes) unless it is preceded with the special prefix, "minmax".  Use "minmaxdate" to indicate that the data timeframe specifier for the date should be interpretted as days instead of minutes.  For example: $$minmaxdate[-3]$$ will print the date associated with all min/max measurements from 3 days ago.  This will work for time too, but will always yield a value near midnight and so is much less useful.

Note: although the table above indicates that only "time" and its derivatives are allowable suffixes for min/max measurements, in truth "date" can also be used.  However, the date for any min/max measurement on a given day will always be the same as $$minmaxdate[]$$ for the same timeframe.  If the date of a min/max measurement is desired, just use "minmaxdate" with the appropriate timeframe.

Units Specifier ( )

The last item in an HTML/ASCII template keyword is a units specifier.  This is a string enclosed in parentheses ( ) which tells the wx/net server what units the specified measurement should be displayed in.  The unit specified must be valid for the data field with which it is associated.  If the units specifier is omitted, wx/net uses its default units when writing out the data.  The table below shows the allowable units with each data field (and its related min/max/avg variants), with the default units in bold.  For time and date fields, the units also apply when the time/date used as a suffix (e.g. "lowbarptime12") instead of the base data field.
 

Units available for each data field

Data Field(s)	Allowable Units (default in bold)
winds	mph, knots, kmh (kilometers/hr),  mps (meters/sec), beaufort
windd	rawwind (1 = N, 9 = S), compass, degrees
outtmp, intmp	celsius, fahrenheit, kelvin, rankine
outrh, inrh	%
barp, barroc	in, mm, mb (millibars), kPa (kilopascals),  psi (pounds/sq. in.), atm (atmospheres)
dewp, windc, hidx	celsius, fahrenheit, kelvin, rankine
r1, r2, r3, rrate	in, mm
lightning	generic
time, time12, time24, hour12, hour24, minute, date, dateshort, datelong, year, yearshort, yearlong, month, mday	ldt (local time with DST), lst (local standard time),  utc (universal/GMT time)

To indicate that the current outside temperature should be output in degrees fahrenheit, the string would be $$outtmp(fahrenheit)$$.  To indicate that the value to be substituted is the high barometric pressure from three days ago in millibars, the appropriate keyword is $$highbarp[-3](mb)$$.

Note: the output of date, datelong, and dateshort fields is is North American (mm/dd/yy[yy]) format.  If European style formatting is desired (dd/mm/yy[yy]), then the date must be pieced together by its sub-fields.  E.g.: "$$mday$$/$$month$$/$$yearlong$$" would yield the Euorpean format version of the string that "$$datelong$$" returns in North American format.  The units specifier cannot be used for formatting; it must be saved for ldt/lst/utc specification because these can affect the value of the date fields.

Integrating with Weather Underground's Personal Weather Station Project

wx/net may be used in conjunction with the Weather Underground's (www.wunderground.com) personal weather station project.  This is a program in which weather enthusiasts may register their home weather stations with Weather Underground and gain the ability to upload their local weather observations to the wunderground.com site.  The local weather stations appear on the official forecast pages of proximate locations.

The data upload function is not performed directly by the wx/net server itself, but rather through a support script in conjuction with HTML/ASCII file generation and TASK execution on ther server.  If you wish to integrate your wx/net server and the weather station it serves with Weather Underground's personal weather station project, follow these steps:

1. Obtain a station ID and password from the Weather Underground for your station.  Visit http://www.wunderground.com/weatherstation/index.asp and click on Signup or Modify your Account.  Provide all information asked for, including a password, and you shall receive a station identifier in return.  An example station ID would be KMAOAKBL1.
2. Take file perswxtmpl.pl from the etc/ directory of the wxnet/ application hierarchy and place it in the $HOME/ directory of the account from which you will run the server.  To use this script template, you will need to install the Bundle::LWP package from CPAN.  As root, run "perl -MCPAN -e 'install Bundle::LWP'" to install if you don't have it already.  Alternately you may use the "cpan" command interactively.  The perswxtmpl.pl file should not need to be modified to work properly as long as all instructions here are followed properly and you have an always-on connection to the Internet (LAN, DSL, Cable Modem, etc.).
3. The template file will be used to generate a real Perl script which will do the actual data uploading.  How often you plan to upload data will determine how often you need to run the HTML/ASCII file generation function to create the upload script with current data.  Make sure that the HTMLINTERVAL option in wxserver.cfg is set at or below your planned upload threshold.
4. Add $HOME/perswxtmpl.pl to the list of HTMLIFILES and $HOME/perswxul.pl at the corresponding entry of HTMLOFILES in wxserver.cfg.  The perswxtmpl.pl template will be used to create the perswxul.pl output file which is a runnable Perl script.
5. Enable HTML generation by setting the HTMLGEN switch to 'Y' in wxserver.cfg if not already enabled.
6. The finished Perl script should be executed at regular intervals as a server TASK.  The "repeat <interval>[+<offset>]" frequency specifier is useful for this.  Bear in mind that the creation of the upload script via HTML/ASCII generation is independent of the execution of the script via a TASK, and so the times uploaded to wunderground.com may lag as much as HTMLINTERVAL minutes.  You can compensate for this with the [+<offset>] feature of TASK time specification.
   
   For example, to run the upload script every 15 minutes, add the following TASK line to wxserver.cfg.  Provide a suitable TASK number based upon whatever other TASKs you have configured:
    
           TASK1:repeat 15:~/perlwxul.pl
   
   If you wish to offset the upload schedule by one minute to compensate (for example) for an HTMLINTERVAL of 1 minute, add a +1 offset to the repeat interval.  Otherwise, the data uploaded to wunderground.com will appear to be a minute behind the even 15 minute upload intervals.  Example:
   
           TASK1:repeat 15+1:~perlwxul.pl
   
   
7. Once these configuration tasks are complete, you should be able to start up the server and have your data automatically uploaded at intervals specified.  If you encounter any difficulty, check to see that $HOME/perswxul.pl is being generated and keyword-substituted properly.  If it is, try running the script manually and seeing if it updates the data on wunderground.com's site.  If so, then you may have a configuration issue with your TASKs.  If you do not have an always-on Internet connection, you will need to modify the template file to either establish a connection for you, or find some other means of connecting such as diald (dialer daemon).

Other Functions

There are many more features to wx/net that are not described in detail here.  However, it is highly recommended that you review the wxserver.cfg file details and see what each parameter in the config file controls.  Items such as rainfall rate calculation and offboard device logging intervals are described there in detail along with the parameters that control them.

The Chat Facility

A lightweight facility is provided as part of the base server platform for exchanging messages between admitted clients.  The mechanisms for sending and receiving these messages will vary from client to client, but the basic functionality is the same.  Chat is a privileged function, meaning that a particular class of service flag needs to be set to enable its usage.  A client merely needs to login to become part of the server-wide chat "community", assuming the class of service enables this function.  Once there, the client can send and receive messages to/from other clients at will.

The client may also choose to modify his or her "alias" after login, which is the name by which the client is identified to other users within the chat service.  The alias selected may not conflict with any other in-use aliases, nor any userids on the server (logged in or not).  The admin userid is not allowed to change alias like other clients. admin must always remain visible as such to other connected users, and so cannot "hide" by changing alias.

A user without the proper class of service for chat cannot see any other connected clients, nor can they be seen by others.  The only exception to this is the admin userid, who can see ALL connected clients, and even send messages to them regardless of class of service.

Security, Passwords, and Permissions

A moderate level of security is available for the wx/net server.  The administrator has the option of enabling password usage via the USEPASSWDS option in the config file.  When the server is started with this option enabled, the $HOME/.wxnet/.wxpasswd file is referenced when clients attempt to login.  The .wxpasswd file contains an entry for each userid allowed on the system, along with the user's encrypted password, maximum number of allowed logins, and class of service (COS).  Note that unlike the server config file which is only read once upon server startup, the .wxpasswd file is referenced each time a user tries to login.  This means that changes made to the file while the server is running will be visible to the system the next time a user logs in.

The format of each .wxpasswd entry is:

<userid>:<encrypted password>:<maxlogins>:<class of service>

NOTE: It is highly recommended that the .wxpasswd file permissions be set such that only the account owner may read/write it.  This translates to a chmod of 600.

Initial .wxpasswd Setup

Before being able to use password checking with the server, the .wxpasswd file must be created and populated.  The simplest way to do this is to put in an entry for the admin userid, and then create subsequent accounts via the sdadmin tool. admin is a special userid that has superuser permissions on the system and is limited to one login on a server regardless of its .wxpasswd entry.

Create a .wxpasswd file in $HOME/.wxnet/ of the account from which the server will be run.  Populate it with the following line:

admin:pexzg3FUZAk:1:65535

This will allow user admin to login to the server with the password "admin".  It is imperative that this password be reset quickly to a more secure password if there is any real concern about security of the server.  Using the sdadmin tool to login with the "admin" password, you should be able to create new userids with the adduser command.  Along with each userid, a password, maxlogin number, and COS must be specified.  The password is whatever the administrator deems a good default password for the user, and is entered "in the clear" through the sdadmin tool.  sdadmin will take care of encrypting the password and the server will properly write it out to the .wxpasswd file.  The user is then free to reset this password on his/her own later on.  Full descriptions of all four .wxpasswd field values are provided below.

Userid

The userid should be a simple alphanumeric string to identify a user.  If modifying .wxpasswd directly, there is technically no limitation on what characters can go into a userid.  However, the admin script will only let you use alphanumeric userids.  It is recommended that you only use alphanumeric characters for userids, and doing otherwise may cause unpredictable results.

Password

Like the userid, the password should be a simple alphanumeric string that a user can specify to authenticate him/herself to the server.  In the .wxpasswd file, the password is encrypted against itself using the Unix crypt() system call.  This encryption is generally irreversible, and so the server account owner will not know what passwords users on the system have.  Although admin can reset a password to any value desired, once set by a user, a password should be unknowable to all but the user who set it.

Maximum Login Limit

Each userid may be restricted to a maximum number of logins.  If this value is set to 1, then only one client may connect to the server using that userid and password.  If the value is 5, then up to five different clients may be connected with that userid/password combo.  Note that the admin userid is always restricted to 1 login regardless of the value provisioned in the .wxpasswd file.  Both the wx/net GUI client and the sdadmin script are clients that are restricted by this limit.

Class of Service (COS)

A user's class of service determines which functions he/she has access to on the server.  The COS is implemented as a 16 bit flag array, allowing for 65535 different permissions combinations.  At the present, only 6 of the possible 16 flags are in use.  Three of these: BASIC, CHAT, and ADMIN, are base server abilities, while RTDATA, HISTDATA, and CATALOG are implemented at the wx/net application level.  Flags 5 through 14 are reserved for future expandability.

The table below shows the 16 flags and what they are used to control.  By adding up the Value entries for each flag you wish to enable, you arrive with the COS number, which should be between 0 and 65535.  Please note that flag 15, ADMIN, is reserved for the admin login.  If it is set for a non-admin user in .wxpasswd, it will be removed by the server.  Conversely, if it is omitted for the admin userid, the server automatically adds it.
 

Class of Service Mappings

Flag #	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
Value	32768	16384	8192	4096	2048	1024	512	256	128	64	32	16	8	4	2	1
Name	ADMIN	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	CATALOG	HISTDATA	RTDATA	CHAT	BASIC
Controls Access to:	All admin superuser functions. Reserved for admin userid only.	--	--	--	--	--	--	--	--	--	--	Catalog items in the products/ directory.	Historical data archives (logfiles).	Real-time data collected from the offboard weather device.	Server chat facility.	Login, and any other default capabilities.

If password checking is turned on, the COS field of the .wxpasswd file is referenced when any protected functions are requested by a logged in userid.  The operation is allowed to proceed if the COS has enabled it, or a denial notice is returned to the client if it lacks the proper permissions.  Note that the COS for a userid is read in once at login time and saved for the duration of a client's session.  Therefore, any changes to the client's COS while it is logged in will not take effect until the client logs out and then back in again to pick up the new COS.

Administering the Server

wx/net allows the server to be administered remotely for a number of functions by the sdadmin administrative control script.  Each instance of the server allows exactly one login by a special userid called admin.  The admin userid has superuser control over the server and possesses the ability to issue it any of the administrative commands that are available to it.  Some of these functions include starting and stopping data collection sessions, shutting down the server, adding or deleting users, chatting with admitted clients, forcing users off the system, and monitoring the attached weather device directly.

The sdadmin tool can be found in the bin/ directory under the wxnet/ application hierarchy. To begin an administrative session with a wx/net server, simply start up the sdadmin tool and point it to the IP and port that the server is running on.  The address information may be provided on the command line in the format <host>:<port>, or else it will be prompted for once the script starts.  The script will automatically supply a userid of admin, and you simply need to provide the password.  Once logged in, all administrative commands are at your disposal.  To get a list of commands available, type "commands".  To get help on a particular topic, type "help" for a list of topics and then "help <topic>" to find out about the one you want.  A full list of these commands and their descriptions can be found in Appendix B: Administrative Commands.

The admin userid will always be allowed one login, even if the server is already at the provisioned number of logins from wxserver.cfg.  There may only be one login at a time for admin regardless of how many connections are available, because the admin userid can modify files and issue executive commands.

All administrative commands are typed on a single line, and there is no confirmation stage for any function.  This means that if you enter in a command, the server will try to execute it immediately without prompting you if you really want to do it or not.  Therefore, it is very important that commands not be entered carelessly, especially if they cannot be undone (like shutdown).

As a side note, the sdadmin script itself implements no application-specific behaviors.  The utility relies on the server to provide any and all non-base behaviors.  This means that the same sdadmin program can be used to control any number of different applications built upon the sdbase API.  All weather related functions within wx/net are provided direct from the server with sdadmin acting as a pass-through client.

Appendix A: wxserver.cfg Fields

Listed here are the various fields found in the wxserver.cfg file and descriptions of what they control.

General Server Parameters

PORT

Possible values: {1025 - 9999}

Indicate here what port you want the server to "listen" for incoming connections on.  Clients wanting to talk to the server will need to specify this port when making the connection.
 

PORTSCAN

Possible values: {Y, N}

If set to 'Y', the server will perform a linear search of up to 25 alternate ports if the port specified by the PORT parameter is busy or otherwise unavailable.  If the server cannot find an available port in 25 tries, it will give up and shut down the server.  If set to 'N", the server just tries the one PORT and proceeds or shuts down based upon its availability.  Searching for a port that has been found via PORTSCAN is simple.  It is always within the range PORT <-> PORT+25, and will most likely be found toward the lower end of that range.
 

MAXCONNS

Possible values: {0 - SOMAXCONN}

Tells the server how many client connections it should allow before rejecting further attempts.  Note that there is always one extra connection reserved for admin logins, so even if the value is set to 0 the sdadmin script should still be able to connect.  SOMAXCONN varies from system to system, but should be in the neighborhood of 128.
 

MAXPROCESSES

Possible values: {0 - 16}

Used to limit the number of child processes the server is allowed to spawn off to fulfill time intensive client requests.  If the number is exceeded, a "server is busy" indication is sent back to the requesting client.  If lightning detection is enabled (LDEVICE != NONE) it will use up one of these processes.
 

USEPASSWDS

Possible values: {Y, N}

Indicates whether password checking should be enabled.  If set to Y, a .wxpasswd file should be present in the $HOME/.wxnet/ directory of the user executing the server.
 

TASK<N>

Possible <N> values: {various}
Possible values: {various}

The server gives you the ability to spawn off separate system tasks at fixed points or periodic intervals every day.  To achieve this, an arbitrary number of TASK<N> entries may be placed in the config file.  <N> must be a unique number for each task that is to be run, and task is defined as a command line complete with arguments that is to be passed to the shell via system() call.

Each task may have an arbitrary number of fixed times in HHMM 24 hour format OR a repeat inteval in minutes with optional offset associated with it.  A full absolute pathname should be supplied as the system call.

The following example will cause /usr/bin/foo to be executed with arguments arg1 and arg2 at 4am and 3pm every day, while /usr/bin/bar will be executed with argument arg3 every 45 minutes based upon a cycle start time of 12:06 AM (specified with the +6 offset):

TASK1:0400,1500:/usr/bin/foo arg1 arg2
TASK2:repeat 45+6:/usr/bin/bar arg3
 

DEBUG

Possible values: {Y, N}

Turn debugging output on or off.  The output for the server will go to STDOUT for all messages, as well as STDERR for error (level 0) messages and $HOME/.wxnet/server.debuglog if debug logging is enabled via DEBUGLOG.  Priority 0 (error) messages always get output, regardless of the setting of this option.

DEBUGLEVEL

Possible values: {0 - 5}

Indicates which debug messages should be seen and which should be suppressed.  0 is reserved for error messages, and these will be output regardless of whether DEBUG is enabled or not.  1 indicates the most important non-critical debug messages, while 5 represents that most trivial.

DEBUGINCLUSIVE

Possible values: {Y, N}

For a given debug level, this setting determines whether all debug messages at or above the set level should get printed, or if only messages exactly matching that debug level get printed.  If DEBUGLEVEL = 3 and DEBUGINCLUSIVE = Y, then priority 0, 1, 2, and 3 messages get printed.  If DEBUGINCLUSIVE = N, then only 0 and 3 messages get printed.  0-priority messages always get printed regardless of debug settings.

SHOWPROCLEVEL

Possible values: {NONE, MAJOR, ALL}

This setting determines if procedure calls should be included in debug output.  NONE suppresses all procedure calls from being printed.  MAJOR will cause all but the smallest/most frequent procedure calls to be indicated, and ALL shows all procedure calls.

DEBUGLOG

Possible values: {Y, N}

Determines whether debug output should be sent to a file as well as STDOUT/STDERR.  This is a "tee" function and does not suppress output to the terminal.  If you would like debug output to go only to a file, then redirect the terminal output with a ">" operator.
 

General Weather Device Parameters

MODEL

Possible values: {WEATHERMAX, SIMULATOR}

Indicates the type of external digital weather station the wx/net server is connected to.  The value specified here determines what protocol gets used for communicating with the offboard device, along with any special functions that may be performed.

If SIMULATOR is used, wx/net will generate fake values as if a real device were connected.  Logging will be disabled, however the lightning device operation will remain unaffected.

DEVICE

Possible values: {NONE, and various others depending on system}

Specifies the location of the serial device to which the digital weather station is connected.  Examples of this are /dev/cua0, /dev/ttyS1, etc.  The exact value will depend upon the individual system setup.  If set to NONE, the server will assumes no device is connected and a data session cannot be started up.

DIALUP

Possible values: {DIRECT}

This is for a future capability where the server can dial up a remote weather station, if the server's computer cannot be physically located with the external weather device.  Leave as DIRECT for now.
 

LDEVICE

Possible values: {NONE, and various others depending on system}

If a separate lightning detection device is to be monitored, this specifies the serial port to which it is connected.  The possible values are identical to those for DEVICE.  If NONE is specified, then lightning detection is bypassed altogether.
 

AUTOSTART

Possible values: {Y, N}

If set to Y, the server will immediately try to initiate a data collection session with the offboard device upon startup.  If set to N, the server will start but not initiate contact with the weather device until instructed to do so via the sdadmin script with a wxsession start command.
 

INTERVAL

Possible values: {1 - up}

Indicates how frequently in seconds the server should attempt to sample data from the offboard weather device.  This value should be set realistically to whatever the device can handle without a high error rate.
 
 

LINTERVAL

Possible values: {1 - up}

The value here indicates in seconds how often the lightning polling process returns a value to the server.  It can be as frequent as once per second.
 

LRATIO

Possible values: {0 - 100}

This value allows some control to be exercised over the CPU utilization of the lightning detection process.  The number specifies the percentage of a given sampling period that continuous polling takes place.  Since the polling will raise CPU usage by a single load bar if performed constantly, lowering this value allows reasonably accurate samples to be taken without bogging down the server machine.

RAINRATEINTERVAL

This option had been deprecated as of version 1.07 of the server, and should be removed from the wxserver.cfg file.

USEINTERNAL<FIELD>

Possible <FIELD> values: {WINDC, HIDX, RRATE, DEWP}
Possible values: {Y, N}

For each of the four possible fields, specify if you want to force the computation of the value internally by the server, bypassing the value (if any) provided by the offboard weather device.  If set to "Y" for any measurement, that measurement will be calculated by the server regardless of its presence or absence from the offboard device's data stream.  If set to "N", then measurements will only be computed internally if not explicitly supplied by the offboard device.

LOGDATA

Possible values: {Y, N}

If set to Y, R/T and historical data (if any) will be logged to disk at regular intervals.  If set to N, no logging is performed.

LOGINTERVAL

Possible values: {60 - 9999}

The value here tells the server that it should log data every N seconds  The lower bound of 60 seconds on LOGINTERVAL is because the wx/net logfile format has a granularity down to the minute level, but not the second level.  When the interval expires, whatever R/T data is current in the server (if any) is logged to disk.  The next logging event is then rescheduled in LOGINTERVAL seconds.
 

LOGFILEDIR<N>

Possible <N> values: {various}
Possible values: {various, in filename format}

An arbitrary number of LOGFILEDIR<N> entries may be placed in the server config file.  These entries indicate which directories wx/net should write and read logged data.  The actual names of the logfiles are generated by the program itself according to a formula using the Station Name, logfile month, and record type (R/T vs. hist).  If logging is enabled, there must be a LOGFILEDIR0 entry.  An <N> value of 0 is special because this is the directory which new records will be written to.  LOGFILEDIR0 and any other directories will all be searched for reading.  The first directory that contains records matching the search criteria will be used to fulfill the request.

In this example, /home/weather/logs/ is used for writing new records, while it, /mnt/dos/c/wxlogs/, and /dev/cdrom/wxlogs/ are searched when trying to read records:

LOGFILEDIR0:/home/weather/logs
LOGFILEDIR1:/mnt/dos/c/wxlogs
LOGFILEDIR2:/dev/cdrom/wxlogs

HTMLGEN

Possible values: {Y, N}
If set to Y, HTML/ASCII files will be generated from user-supplied templates at regular intervals.  If set to N, no HTML/ASCII file generation is performed.

HTMLIFILES

Possible values: {various}

This field specifies to the server a list of comma-separated input "templates" for HTML/ASCII file generation.  At specified intervals, these files are read in, modified, and then written back out to a user-specified output file.  This field is only relevant when HTMLGEN is set to Y.

HTMLOFILES

Possible values: {various}

A comma-separated list of output filenames for HTML/ASCII file generation.  Each filename specified here corresponds sequentiall to each filename specified in HTMLIFILES.  There must be at least as many filenames specified here as there are in HTMLIFILES.  Any extra filenames get ignored.  Do not use the same filenames in HTMLIFILES and HTMLOFILES, as the input template will get overwritten, causing loss of the keywords which the server looks for when substituting in values.  This field is only relevant when HTMLGEN is set to Y.

HTMLINTERVAL

Possible values: {1 - 9999}

The value here tells the server that it should generate HTML/ASCII files every N minutes.  This field is only relevant when HTMLGEN is set to Y.

SETWXDEVTIME

Possible values: {Y, N}

This indicates that you wish to have the server set the local time on the offboard weather device upon startup.  Implementation of this functionality will depend on the event driver for the offboard device.  The "standard" implementation would have the server set the time upon startup, once per hour thereafter, and upon detecting a daylight savings time change if applicable to the area.  A value of N performs no synching between the server and the offboard device.

SYNCSECONDS

Possible values: {Y, N}

If supported by the event driver for the offboard device, this setting indicates that upon performing a time set, the server will wait for the top of the minute before issuing the command.  This may introduce a startup delay of up to a minute depending on the exact time that server execution started.  This option is dependent upon SETWXDEVTIME equaling Y in order to have any effect.

STANDARDTZ

Possible values: {Y, N}

When used with SETWXDEVTIME, this parameter lets you control whether the offboard device should always be set to standard time, or if it should be set with Daylight Savings Time times.  This has no implications for logging, which records times in a serial format and is unaffected by DST.

USESERVERTIME

Possible values: {Y, N}

Setting this to Y will cause the timestamp obtained from the offboard device to be discarded when collecting real-time data.  In its place, the server will substitute its own internal time.  This may be desirable if for instance the offboard device is set to GMT time, but you wish for connected clients to see the data with a local timestamp.

If the time from the offboard device is used instead of the server's time (via an N value), then the connected clients have no way of knowing if the time they are receiving is Daylight Savings or not.  This can be remedied by synching up the server and device clocks with WXDEVSETTIME, so that the server knows they have the identical time and hence the same DST flag value.

WXDEVTIMEZONE

Possible values: {SERVER, -12 - +12}

If USESERVERTIME is set to N, this setting allows you to specify the time zone the the offboard weather device is set to.  If set to SERVER, it indicates that the offboard device and server are set to the same time zone.  Otherwise, a value between -12 and +12 can be specified to indicate how far behind/ahead of GMT the device is set.  Decimal values are allowed for time zones with a half-hour differential.

STNNAME

Possible values: {any}

Specify a name for the weather station.  This name will be communicated to the connected GUI client to indicate which station it is "listening" to.  This name typically indicates a very specific location, such as "Edwards Mountain" rather than a city or other general location.

STNZONE

Possible values: {any, up to 3 letters}

The zone parameter should contain a 3 letter city/airport code for identifying the general region in which STNNAME lives.  A Boston area weather station would put BOS in here, whereas a Raleigh-Durham area station would put in RDU.  There is no restriction on what can be put in here, except that it will be truncated to 3 characters if it is longer.

STNNAME and STNZONE must be specified, as they are used to generate logfile names for the server.  Therefore it is important that each NAME/ZONE combo be unique for different servers so their files don't get mixed up.

STNLAT

Possible values: {(0+0 - 90+0)+{N, S}}

Indicate the latitude of the station at STNNAME.  The format of the parameter is <degrees>+<minutes>+<direction>.  For a latitude of 35 degrees 51 minutes north, the specifier would be 35+51+N.

STNLON

Possible values: {(0+0 - 180+0)+{E, W}}

Indicate the longitude of the station at STNNAME.  The format of the parameter is <degrees>+<minutes>+<direction>.  For a latitude of 79 degrees 2 minutes west, the specifier would be 79+02+W.  The "02" may also be written as "2".

WUGSTNID

Possible values: {any}

The station ID assigned to this weather station by The Weather Underground's personal weather station project.  Putting a sting here will allow it to be keyword sustituted for $$wugstnid$$ during HTML/ASCII generation.  When used in conjuntion with the perswxtmpl.pl script, data from the wx/net server can be uploaded to Weather Underground's site.

WUGPASSWD

Possible values: {any}

The password needed to upload data from this weather station to the Weather Underground's personal weather station project site.  Putting a sting here will allow it to be keyword sustituted for $$wugpasswd$$ during HTML/ASCII generation.  When used in conjuntion with the perswxtmpl.pl script, data from the wx/net server can be uploaded to Weather Underground's site.

Maximum WeatherMAX Device-Specific Parameters

WLOG

Possible values: {Y, N}

Indicates whether a WeatherLogger offboard logging device is hooked up to the WeatherMAX computer.  If set to N, the server will try to establish communications as if one isn't there.  If set to Y, the server will try to establish communication as if one is there, and if that fails, will revert back to WeatherMAX-only mode.

WLOGBAUD

Possible values: {2400, 4800, 9600, AUTO}

To save time at startup, the baud rate of your WeatherLogger may be specified here if known.  The baud rate specified will be the first one tried upon startup.  If AUTO is set, the server will try to establish communications using all the possible baud rates until it finds one that works.  This option only valid if WLOG = Y.

WLOGINTERVAL

Possible values: {1 - 1440}

Set the logging interval (in minutes) of the WeatherLogger device.  When wx/net shuts down and the WeatherLogger begins offboard logging, this is the rate at which R/T and historical data will be collected.  This parameter only applicable if WLOG = Y.

XMODEM

Possible values: {Y, N}

Indicate whether you want WeatherLogger records to be downloaded via XModem CRC upon establishing a communications session.  If set to N, any records collected at the WeatherLogger will not be retrieved.  If set to Y, the records will be downloaded, erased from WeatherLogger, and written out to wx/net's log files, if logging is active.

WLOGMODE

Possible values: {1, 0}

WeatherLogger has a limit of 300 records.  WLOGMODE tells WeatherLogger how to handle memory overflows.  If WLOGMODE is set to 0, the oldest records get overwritten with the newest.  If set to 1, WeatherLogger will stop logging once the 300 record limit has been reached.

AUTORAIN

Possible values: {Y, N}

WeatherLogger possesses the ability to automatically reset WeatherMAX's three rain counters to correspond to daily, monthly, and yearly rainfall amounts.  This reset occurs at midnight when enabled.  Set AUTORAIN to Y to enable this feature, or N if you do not want it.
 

Appendix B: Administrative Commands

General Client-Side Commands

COMMANDS

Usage: commands

Print out a list of all available commands.  The list is separated into those implemented at the client, and those implemented at the server.

CONNECT

Usage: connect [<host>[:<port>]]

Login to the server running at IP address <host> on port <port>.  If <host> or <port> are omitted, they will be subsequently prompted for.  Synonymous with login.

EXIT

Usage: exit

Logout of any active server connection and quit the sdadmin application.  Synonymous with quit.

HELP

Usage: help [<topic>]

Prints out help on a given topic, or if <topic> is omitted, a list of topics for which help is available.

LOGIN

Usage: login [<host>[:<port>]]
 

Login to the server running at IP address <host> on port <port>.  If <host> or <port> are omitted, they will be subsequently prompted for.  Synonymous with connect.

LOGOUT

Usage: logout

Logout of the currently connected server without exiting the sdadmin script.

QUIT

Usage: quit

Logout of any active server connection and quit the sdadmin application.  Synonymous with exit.

General Server-Side Commands

ADDUSER

Usage: adduser <userid> <password> <maxlogins> <class of service>

Adds a user to the current server's password file with the specified password, maximum number of logins, and class of service.

DELUSER

Usage: deluser <userid>

Removes a user from the current server's password file.

DEPERMIT

Usage: depermit <userid|socket|alias>

Removes a userid or socket from the server.  If a userid is specified, all connections associated with that userid will be closed and the userid will be prevented from any further logins to the server.  They will remain depermitted until 'permit <userid>' is used to repermit them.  If a socket is specified, that single connection will be closed but the user associated with that socket can log back in at will.  If password checking is not turned on, the userid functionality is moot and only socket depermissions will have any effect.  Aliases may not be used as depermit arguments.  Depermitted users will be flagged with "(d)" in the users command output.

MSG

Usage: msg <userid|socket|alias>[,<userid|socket|alias>[, ... ]] <message text>

Sends a message to one or more userids, aliases, or sockets via the chat utility.  If using a userid or alias to identify a client, the complete identifier must be typed out and is case-sensitive.  All matching users will be sent the message.  If userid "JoJo" has 5 logins and "JoJo" is used as the identifier to send the message to, then all 5 instances of login for "JoJo" will receive the message.  If specifying a comma-separated list of recipients, there must be NO spaces in the list, as the whitespace will indicate that the next characters are part of the message text.

PERMIT

Usage: permit <userid>

Permits a userid that had previously been depermitted from the server.  This command has no effect on socket identifiers, only userids known to the system, listable with 'users' command.

PING

Usage: ping

Tests to see if the connected server is alive and responding to requests.

SET

Usage: set <userid> [password|numlogins|cos] <value>

Set various passwd file attributes.  A given user's password, maxlogins, and COS may be changed with set.

SHUTDOWN

Usage: shutdown

Shutdown causes the server to immediately shut down, performing any cleanup actions necessary before doing so.  Once the server is shut down, it must me manually started up again.  A SIGINT on the console where the server is running will have the same effect.

STATUS

Usage: status

Displays information about the current status of the server.

TIME

Usage: time

Displays the server time.

USERS

Usage: users

List all users with entries in the server's passwd file.  Users that are currently depermitted from the server are flagged with "(d)".

WHO

Usage: who

List all users currently logged into the server and their sockets.

wx/net-Specific Server-Side Commands

WXDATA

Usage: wxdata

Grabs a snapshot of the current set of real-time data at the server and displays it at the admin terminal.  The data is presented in wx/net internal units and no conversion may be performed upon it.

WXMONITOR

Usage: wxmonitor <baud rate>

Open up a raw communications session with the connected weather device.  The baud rate must be specified as a parameter and there cannot be an active data collection session in progress in order to use monitor mode.  Once in the monitor, keystrokes are communicated directly to the attached weather device and any response is conveyed back.  To exit monitor mode, hit Ctrl-D.

WXSESSION

Usage: wxsession [query|start|stop]

Initiate, terminate, or display particulars about the current communication session with the external weather device.  If no argument is specified, the default behavior is a query.