Skip navigation links
1-Wire Weather Service for Java -- Server API

1-Wire Weather Service for Java -- Server API

This document describes the operation of the Weather Service component of the 1-Wire Weather Service for Java.

See: Description

Packages 
Package Description
wxservice
Main engine classes for the 1-Wire Weather Service for Java.
wxservice.formatter.task
Formatters receive data from IDataExchange.
wxservice.logging
Logging classes for WxService.
wxservice.sensor.data
Sensor data objects collect and process data received from sensor tasks via IDataExchange.
wxservice.sensor.task
Sensor tasks collect data from devices on the 1-Wire MicroLan and post it to the sensor data objects via IDataExchange.

This document describes the operation of the Weather Service component of the 1-Wire Weather Service for Java.

The 1-Wire Weather Service for Java consists of a service engine (Service) that collects data from sensors connected to a Dallas 1-Wire MicroLan. This software is built on the Dallas 1-Wire API for Java SDK, which runs on top of the Dallas 1-Wire Drivers. The core sensor tasks are built around the Dallas 1-Wire Weather Instrument Kit V3.0 instrument cluster.

The service runs under Windows Service Control Manager as a service, or as a daemon on Linux, Unix, Solaris, etc. You can access the service in real-time, locally or remotely using a graphical user interface such as the Weather Monitor, in-process as a stand-alone application, or on a local area network via web services.

In addition to real-time access, the service also has tasks that will post weather data to comma-delimited (CSV) files, Weather Underground Data Exchange, WeatherBug and APRS Citizen Weather Observer Program (CWOP) on independent, user-defined schedules.

You can dynamically add tasks to the service that read new sensor types, or post data to new weather database types without the need to recompile the core libraries, and without access to the 1-Wire Weather Service for Java source code.

Installation

Copy the WxService directory to a convenient location, such as Program Files in Windows. WxService contains the following files and subdirectories:
        wxservice <dir>: WxService install directory.
            bin <dir>: Files for installing Service as a service under Windows Service Control Manager.
            doc <dir>: Documentation.
                WxMonitor <dir>: JavaDocs
                WxService <dir>: JavaDocs
            dist <dir>: Distribution directory for 1-Wire Weather Service for Java.
                lib <dir>: library JAR files.
    

Prerequisites

Depending on the setup options you select below, you may need one or more of the following:

Web Service Setup

Running Service as a web service is optional. The Java Runtime Environment (JRE) 1.7 or higher and the Dallas 1-Wire Drivers must already be installed.

To install Service as a web service under the Windows Service Control Manager, run wxservice/bin/install.WxService.cmd The command file will prompt you for the full path to the directory where the Java Runtime Environment (JRE) is installed, the name of the computer (and optional port -- port 80 is the default) that the web service will be running on, and the WxService install directory, the full path to the directory where WxService is installed. For example:

        C:\PROGRA~1\wxservice\bin>install.wxservice.cmd

        C:\PROGRA~1\wxservice\bin>echo off
        Java install directory:C:\Progra~1\Java\jre6
        Computer name[:port]:MyServer:8080
        WxService install directory:C:\Progra~1\WxService
        The WxService automatic service was successfully installed
        Press any key to continue . . .
        The WxService service is starting.
        The WxService service was started successfully.

        Press any key to continue . . .

        C:\PROGRA~1\wxservice\bin>
    
Notes:
  1. Due to the dynamic way JAX-WS generates the web service WSDL, if you enter localhost as your computer name, the web service will only be accessible from the local machine. You should enter the computer's network DNS name.
  2. By default, Windows services run under system authority, which is much higher than the authority required by WxService. It is recommended that you modify the WxService properties to log on using a limited user account. As an added benefit, WxService will write the log files to the Documents and Settings directory for that user.
  3. To run WxService on a 64-bit machine, follow the instructions above, but make sure you install and use Java 64-bit edition, and install the 64-bit 1-Wire drivers. Use install.WxService64.cmd instead of install.WxService.cmd to install the service.
  4. For installation in Linux, extract the files to a suitable directory. You will need to follow the procedures for your operating system to run as a daemon. You will probably need to write a shell script to make it start automatically. WxService does not require root authority.

Configuration

The Default 1-Wire Net utility included with the Dallas 1-Wire Drivers allows you to discover and specify the default 1-Wire adapter and port. WxService will automatically use the configured device. Alternatively, you can create the file onewire.properties in the WxService directory, and add the lines
    onewire.adapter.default={DS9490}
    onewire.port.default=USB1
    
for the 1-Wire USB adapter on USB port 1, or
    onewire.adapter.default={DS9097U}
    onewire.port.default=COM1
    
for the 1-Wire COM adapter on COM port 1, etc.

You configure the WxService software by editing the property file wxservice.properties. More configuration details are included with the Service documentation, and in the Configuration Quick Reference. On Windows systems, the properties are located in the Local System account home directory, \Documents and Settings\Default User\wxservice.

Event Logging

The service writes logs to daily log files named yyyy-MM-dd.txt. There are seven logging "severity" levels: FINEST, FINER, FINE, CONFIG, INFO, WARNING and SEVERE. A special level, ALL, enables all logging levels. On Windows systems, the logs are written to the Local System account home directory, \Documents and Settings\Default User\wxservice\log.

As you might expect, FINEST, FINER, and FINE are for detailed tracing and debugging, and may be very verbose. CONFIG is for tracking configuration changes. The service uses INFO to log informational events, such as starting and stopping the service and its tasks. WARNING is used to track events that might result in data loss or failure to post to a weather logging service. 1-Wire CRC errors, value errors, connection refused to a URL are all WARNINGs. SEVERE is reserved for situations that would result in termination of the service, such as out of memory, stack overflow, division by zero or null pointer errors. These are either unexpected or unrecoverable errors. Please refer to the Error Messages Reference for descriptions and troubleshooting information about errors that may appear in the logs.

The 1-Wire Weather Service for Java uses the extremely flexible java.util.logging.Logger package.

You can set logging levels individually for any class in the 1-Wire Weather Service for Java; each class has its own logger name associated with it. The following example configures the entire service:

        # Logging class path for the wxservice logger.
        wxservice.logging.path=wxservice
    
The following example configures just the APRS formatter:
        # Logging class path for the wxservice logger.
        wxservice.logging.path=wxservice.formatter.task.APRS
    

You can select an individual class, or an entire package, by specifying all or part of the class path. Refer to the package and class names elsewhere in these docs.

The default logging verbosity is INFO. To log everything (highest verbosity), specify ALL, as in the following example:

        # Logging level for the wxservice logger.
        wxservice.logging.level=ALL
    

The service logs failures to initialize 1-Wire device tasks and formatter tasks at the SEVERE logging level, on the assumption that you require all configured tasks to start. If that is not the case, you can remove unused tasks from their respective lists, wxservice.sensor.task.names and wxservice.formatter.task.names, by editing wxservice.properties or by using the WxMonitor configuration panel.

Skip navigation links
Copyright © 2005-2013 Karl Uppiano