WeatherCat Rich Client Protocol (RCP) Help
The RCP provides an interface to fetch various objects from WeatherCat.
This interface runs over http and supports the following logical sections, or domains:
discovery
webtag
data
image
All replies are in the form of an NSDictionary (or plist). The protocol runs over http on port 49255 and advertises itself on Bonjour as 'WeatherCat Rich Client Protocol Data Server' - _wcrcps._tcp.
A typical request might be (these can be run in any web browser for testing):
http://localhost:49255/webtag/STAT$TEMPERATURE:CURRENT$
(replace 'localhost' with the address of the machine running WeatherCat)
Replies are typically of the form:
<plist version="1.0">
<dict><
<key>result</key>
<string>5.8</string>
<key>error</key>
<integer>0</integer>
<key>errorDescription</key>
<string>OK</string>
<key>serverTime</key>
<string>2017-03-27 22:17:00 +0000</string>
<key>processTime</key>
<string>0.00217700</string>
</dict>
</plist>
The returned dictionary will contain the following keys:
result - the result of the query (as a string)
error - a negative error number or 0 if no error. If there is an error, the result value will be set to "0".
errorDescription - a human readable english language description of the error, or 'OK' if no error.
serverTime - the time on the server in UTC
processTime - how long the request took to process in seconds.
Programmatically an RCP call can be made with the following code: (Objective-C, in this example a call to process a webtag):
NSDictionary* myDict=[NSDictionary dictionaryWithContentsOfURL:[NSURL URLWithString:@"http://address of machine running WeatherCat:49255/webtag/stat$TEMPERATURE:CURRENT$"]];
myDict will then contain the keys and values as described above.
Domain: discovery
channelList
Returns an array of dictionaries as the result which contains all active channels. Each dictionary contains the following keys:
channelName - the name of the channel (string).
channelNumber - the channel number (integer)
channelType - enumeration, station_channel_type (integer)
channelBasicType - base channel type (integer) - for example temperature, wind speed, pressure etc
channelValid - 1 if valid (integer)
The channel types are as defined in the 'station_channel_type' enumeration found in the WeatherCat SDK header 'StationPlugInProtocol.h'
channelBasicType is defined as:
NONE 0 //Not applicable or not known.
TEMPERATURE 1 //External temperature
PRESSURE 2 //Barometric pressure
WINDSPEED 3 //Wind speed
WINDDIRECTION 4 //Wind direction
PRECIPITATION 5 //Rain
RH 6 //Relative humidity
CLOUDBASE 7 //Coud base
SOLAR_RAD 8 //Solar radiation
UV 9 //U.V. Index
LEAF_WETNESS 10 //Leaf Wetness
SOIL_MOISTURE 11 //Soil moisture
CO2 12 //CO2
NO_UNITS 20 //Synthetic channels with no units
NO_UNITS_1DP 21 //Synthetic channels with no units, display to 1 decimal point
NO_UNITS_2DP 22 //Synthetic channels with no units, display to 2 decimal points
NO_UNITS_3DP 23 //Synthetic channels with no units, display to 3 decimal points
getChannelOfType
Given a channel type, returns the channel number of the found channel (as an integer). If the channel type is not found, -1
will be returned as the channel number and the error will be set to -3.
e.g. http://address of machine running WeatherCat:49255/discovery/getChannelOfType/4
(get the pressure type channel - see the 'station_channel_type' enumeration found in the WeatherCat SDK header 'StationPlugInProtocol.h'
for the channel types).
customGraphList
Returns an array of dictionaries describing the custom graphs available.
Each dictionary contains the following keys:
name - the name of the custom graph (string)
UID - the unique identifier for the graph (integer). Used for retrieving the image of the custom graph
customTextWindowsList
Returns an array of dictionaries describing the custom text windows available.
Each dictionary contains the following keys:
name - the name of the custom text window (string)
UID - the unique identifier for the custom text window (integer). Used for retrieving the image of the custom graph
alertsList
Returns an array of dictionaries describing the alerts and their status.
Each dictionary contains the following keys:
name - the name of the alert (string)
triggered - the alert triggered status (bool)
systemData
Returns a dictionary of useful data such as sampling period, comms data, version information etc.
Domain: data
getChannelValue
Returns the value of the given channel.
Example:
http://address of machine running WeatherCat:49255/data/getChannelValue/0
If the channel is not found the error will be -3 (otherwise 0).
Note - as it is possible for the user to quit WeatherCat, change the station to that of a different type/manufacturer, then relaunch WeatherCat,
channel numbers should not be cached in clients. To get at the live value of a channel use the getChannelOfType to get the channel number
then use that channel number for getChannelValue.
getData
This command takes three parameters:
param1 = the channel type (as per the enum found in the SDK header StationPlugInProtocol.h).
param2 = the number of samples to return (first sample in the array is the latest in the database)
param3 = the period between samples in minutes.
Returns an array of values.
Example:
http://address of machine running WeatherCat:49255/data/getData/1/288/5
Returns an array of 288 external temperature values (channel type 1) at 5 minute intervals (i.e. the last 24 hours at 5 minute resolution). The first entry in the array of returned values represents the latest sample (i.e. now), the second entry in the array will be the temperature 5 minutes before that and so on.
Note: This command is limited to returning a maximum of 10000 data items.
Possible errors for this command:
-5 = Too much data requested - maximum is 10000 values.
-4 = Wrong number of parameters
-3 = Channel not found
Domain: image
getCustomGraph
Given a custom graph UID (see customGraphList), return the image of the graph with the dimensions as set in the custom graph web width and height.
Example:
http://address of machine running WeatherCat:49255/image/getCustomGraph/1490220331
Possible errors for this command:
-5 = Custom graph not found, check UID.
getBasicGraph
Returns a basic graph with the given ID - for example:
http://address of machine running WeatherCat:49255/image/getBasicGraph/ID
where ID is one of:
TEMPERATURE 1
DEWPOINT 2
WINDCHILL 3
PRESSURE 4
WINDSPEED 5
WINDDIRECTION 6
PRECIPITATION_RATE 7
PRECIPITATION_DAILY 8
RH 9
INT_RH 10
INT_TEMPERATURE 11
SOLAR_RAD 17
UV 18
Possible errors for this command:
-8 = Basic graph not found, check ID.
getCustomTextWindow
Given a custom text window UID (see customTextWindowsList), return the image of the custom text window with the dimensions as set by the current custom text window size.
Example:
http://address of machine running WeatherCat:49255/image/getCustomTextWindow/1507983243
Possible errors for this command:
-5 = Custom text window not found, check UID.
getWebCam
Returns the current camera image.
Example:
http://address of machine running WeatherCat:49255/image/getWebCam
Possible errors for this command:
-2 = camera not enabled or operational.
-3 = camera off-line for the night.
-6 = image not ready. Try again later.
image domain notes:
1. All images are returned as a string of hex-chars and can be converted to an NSImage object with the following Objective-C code:
myDict=[NSDictionary dictionaryWithContentsOfURL:[NSURL URLWithString:@"http://address of machine running WeatherCat:49255/image/getCustomGraph/1490220331"]];
NSString* hexchar_data=[myDict objectForKey:@"result"];
NSMutableData *imageData= [[NSMutableData alloc] init];
unsigned char the_byte;
char byte_chars[3] = {'\0','\0','\0'};
for (int i=0; i < [hexchar_data length]/2; i++)
{
byte_chars[0] = [hexchar_data characterAtIndex:i*2];
byte_chars[1] = [hexchar_data characterAtIndex:i*2+1];
the_byte = strtol(byte_chars, NULL, 16);
[imageData appendBytes:&the_byte length:1];
}
NSImage *image = [[NSImage alloc] initWithData:imageData];
2. Images can be scaled before transmission by appending integer width and height parameters - for example:
http://localhost:49255/image/getBasicGraph/ID/width/height
Note that the aspect ratio of the image will be maintained during scaling; the dimensions you get back may not match the dimensions you requested.
Domain: webtag
Processes the given tag and returns a string with the result.
Example:
http://address of machine running WeatherCat:49255/webtag/STAT$TEMPERATURE:CURRENT$
Webtag return values are always strings.
The following webtags are currently supported:
STAT$ tags, so current and statistical data can be retrieved.
JOURNT$ - return the journal text
SUNRISELOCAL$ - local sunrise time
SUNSETLOCAL$ - local sunset time
SUNRISEUTC$ - UTC time of sunrise
SUNSETUTC - UTC time of sunset
DAYLIGHTTIME$ - day light time today
SUNRISELOCAL1$ - sun rise time tomorrow
SUNSETLOCAL1 - sun set time tomorrow
SUNRISEUTC1 - sun rise time tomorrow in UTC
SUNSETUTC1$ - sun set time tomorrow in UTC
DAYLIGHTTIME1$ - daylight time tomorrow
STRECORDS$ - Records stats (formatted text)
STRECENT$ - recent stats (formatted text)
STMONTHLY1$ - monthly stats part 1 (formatted text)
STMONTHLY2$ - monthly stats part 2 (formatted text)
STMONTHLY$ - monthly stats in total (formatted text)
STYEAROVERYEAR - year over year stats (formatted text)
STDAILY$ - daily stats (formatted text)
STTHISMONTHOV$ - this month overview (formatted text)
STLASTMONTHOV$ - last month overview (formatted text)
STNOAAMO$ - this month NOAA report (formatted text)
STNOAAPRMO$ - last month NOAA report (formatted text)
STNOAAYR$ - this year NOAA report (formatted text)
STNOAAPRYR$ - last year NOAA report (formatted text)
BTTEXT$ - baro trend as text
DOMWDTEXT$ - dominant wind direction as text
WINDBEARINGFROM10$ - last 10 mins lowest clockwise bearing
WINDBEARINGTO10$ - last 10 mins highest clockwise bearing
DOMWDDEGREES - dominant wind direction as degrees today
WEATHERFACT$ - return the current weather fact
AT_Aus$ - current Australian apparent temperature.
AT_US$ - current US apparent temperature
HUMIDEX$ - current humidex
WINDROSE8 - wind rose as 8 sectors
WINDROSE45 - wind rose as 45 sectors
CP$ - current potential solar radiation
CC$ - current conditions string
CF$ - current forecast string
CSF$ - current short forecast
CU$ - time of last sample
CD$ - current dew point
CG$ - current wind gust
CP$ - current pressure
CR$ - current rain
CT$ - current temperature
CW$ - current wind speed
CWC$ - current wind chill
CX$ - current wind direction
BD$ - build string
BDL$ - build string, localised
t12s$ - 12 hour time with seconds
t12$ - 12 hour time, no seconds
t24s$ - 24 hour time with seconds
t24$ - 24 hour time, no seconds
da$ - date in the format of month/day/year
de$ - date in the format of day/month/year
UT$ - WeatherCat uptime as a string
RS$ - rain storm value
RSD$ - date of rain storm start
RLD$ - last rain date
RLDi$ - last rain date (ISO format)
Llat$ - latitude of station
Llong$ - longitude of station
Lelevf$ - station elevation in feet
Lelevm$ - station elevation in metres
L$ - station name
DUTC$ - date and time in UTC - yyyy,m,d,h,m,s
D$ - date and time
HEIGHTUNITS$ - string describing the height units - one of Metres of Feet
TEMPUNITS$ - string describing the temperature units - one of °C or °F
RAINUNITS$ - string describing the rain units - one of mm or in
WINDRUNUNITS - string describing the wind run units - one of km, miles, NM's or metres
HEIGHTUNITS$ - string describing the height units - one of Feet or Metres
PRESSUREUNIT$ - string describing the pressure units - one of mb, inHg, hPa
WINDSPEEDUNITS$ - string describing the wind speed units - one of km/h, MPH, Knots, m/s
COMMSFAILFLAG$ - set to 1 if comms to station have failed