Weather Server
The Weather Server (referred to as the WebSocket server in some places) is now quite an old component with at this stage an uncertain future. It speaks WebSocket, TCP, Telnet and SSH.
Originally was built to perform three tasks:
- Act as the server component of Weather Push receiving ASCII-encoded CSV data via SSH.
- Supply live data updates to the Web Interface via WebSocket
- Supply live data updates to the Desktop Interface via TCP
Since 2015 Weather Push has also supported speaking its own much more efficient binary protocol to its own Weather Push Server alongside the older ASCII-over-SSH to the Weather Server protocol. The Weather Push client should still be able to push data to the Weather Server over SSH but this hasn't been used or tested in a while. At this point probably the only reason to transmit data this way is security: the weather push binary protocol doesn't support encryption (#125) where as the ASCII-over-SSH protocol does.
The TCP endpoint is still used by the Desktop Client for now but it could just as easily be changed to use the same WebSocket endpoint the Web UI uses. So the role the Weather Server currently performs could really be filled by a much simpler application that only speaks Web Sockets.
The Weather Server implements a simple command line which you can use interactively via SSH or Telnet. Operations that modify the database (like streaming data to the server) are only supported via SSH which requires authentication.
These interfaces can be useful for monitoring the server and diagnosing problems
Commands all start with a verb followed by series of parameters and qualifiers. For example:
$ show live "hlz"
where show is the verb, live is a keyword positional parameter and hlz is a string positional parameter. This command shows live data for the station 'hlz'.
Parameters are positional while qualifiers can appear almost anywhere in a command. For example, these two commands are both valid and do the same thing:
$ show station "sb"/json
$ show station/json "sb"
The command $ show /json station "sb"is not valid however. Keyword parameters (like station in the example) can alter the syntax of a command. Here the verb only takes a single parameter - a keyword. The station keyword alters the syntax of the rest of command by introducing a second parameter (the station code) plus a qualifier (/json).
Sets the currently connected clients name and, optionally, version:
$ set client "client name" /version="1.0"
Sets the command prompt for the current session to the specified string:
$ set prompt ">"
Sets the type of terminal in use for the current session:
Qualifiers are:
-
/video- a video terminal (VT100 compatible) -
/basic- a more basic terminal. VT100 escape sequences are avoided -
/echo=- turn server echo on (true) or off (false)
Example:
$ set terminal/video/echo=false
Used for configuring a few interface options for the current session.
Qualifiers are:
-
/json=- turn JSON mode on or off. When on some commands will produce JSON data as output rather than output formatted for display
Example:
$ set interface/json=true
Sets an environment variable for the current session.
Parameters are:
- Variable name
- Variable value
Example: $ set environment "test" 123
Shows details about the system or the current connection.
Shows the client details as set by the set client command:
$ set client "foo"/version="1.0"
$ show client
Client: foo
Version: 1.0
Shows the currently logged in user
$ show user
anonymous
Available to logged in users only (via SSH). Shows session statistics since the server was last restarted.
$ show session
Current sessions: 12
Total sessions: 53566
Shows information about a specific weather station
Parameters:
- Station code
Qualifiers:
-
/json=- outputs more detailed information in JSON format (true) or more limited information formatted for display (false)
$ show station "hlz"
Code: hlz
Name: Hamilton East
Description:
Sample Interval: 300
Live Data Available: True
Hardware Type: DAVIS (Davis Vantage Pro2 or Vantage Vue)
Is Wireless: True
Broadcast ID: 1
Model: PRO2P
Has Solar and UV: True
The JSON output is largely equivalent to the sysconfig.json endpoint provided by the Web UI:
$ show station "sb"/json
{"code": "sb", "name": "Sandy Bay, Port Charles", "hardware_type_name": "Davis Vantage Pro2 or Vantage Vue", "live_data_available": true, "hardware_type_code": "DAVIS", "config": {"is_wireless": false, "hardware_type": "PRO2CP", "has_solar_and_uv": true, "broadcast_id": null}, "sample_interval": 300, "description": "Sandy Bay, Port Charles on the Coromandel Peninsular"}
Shows live data for the specified station formatted for display in a VT100 compatible terminal (pictured in the screenshot at the top of the page).
$ show live "sb"
To exit, hit Ctrl+C
The command takes only a single string parameter: the station code to display. It requires the current terminal to be set to video - an error is produced if it is set to basic.
$ set terminal/basic
$ show live "sb"
Error: This command is only available for VT-style terminals.
Use SET TERMINAL /VIDEO to change terminal type.
Shows the latest timestamp available for each station.
It has the following qualifiers:
-
/json- output as JSON instead of formatted for display
$ show latest
Station: rua2
Timestamp: 2019-02-23 10:20:00+13
Station: sb
Timestamp: 2021-08-07 17:30:00+12
Station: hlz
Timestamp: 2021-08-07 17:25:00+12
Station: rua
Timestamp: 2018-05-20 02:05:28+12
WH1080 Record Number: 3791
Shows environment variables set for the current session.
It supports the following qualifiers
-
/variable=show a specific environment variable
$ show environment
ui_json = False
term_mode = 0
protocol = 'telnet'
term_echo = True
json_mode = False
term_type = 1
$ show environment/variable="protocol"
protocol = 'telnet'
Synonyms: quit
Ends the current session and disconnects the client.
This command takes no parameters and has no qualifiers.
Synonyms: subscribe
This command streams new data for the specified station. Its used by the Web UI and Desktop Client to initiate a feed of live updates.
It takes the following parameters:
- Station Code - the station to stream data for
And it has the following qualifiers:
-
/live- include live updates -
/samples- include new samples -
/images- include data on new images -
/from_timestamp=- Output all samples from the specified date up to now at the start of the subscription. Maximum of 2 hours of data allowed. -
/any_order- Samples are allowed to be delivered out-of-order. May result in delayed delivery if samples arrive in the database out-of-order.
Data is streamed in CSV format:
# This is a comment.
# The next line is image data:
i,{station_code},{source_code},{type_code},{timestamp},{mime_type},{id}
# and Generic/WH1080 live data:
l,{outsideTemperature},{dewPoint},{apparentTemperature},{windChill},{outsideHumidity},{insideTemperature},{insideHumidity},{barometer},{windSpeed},{windDirection}
# Davis Vantage Vue/Pro2 live data:
l,{outsideTemperature},{dewPoint},{apparentTemperature},{windChill},{outsideHumidity},{insideTemperature},{insideHumidity},{barometer},{windSpeed},{windDirection},{barTrend},{rainRate},{stormRain},{startDateOfCurrentStorm},{transmitterBatteryStatus},{consoleBatteryVoltage},{forecastIcons},{forecastRuleNumber},{UV},{solarRadiation}
# Generic/WH1080 sample:
s,{timeStamp},{temperature},{dewPoint},{apparentTemperature},{windChill},{humidity},{indoorTemperature},{indoorHumidity},{pressure},{averageWindSpeed},{gustWindSpeed},{windDirection},{rainfall}
# Davis Vantage Vue/Pro2 sample:
s,{timeStamp},{temperature},{dewPoint},{apparentTemperature},{windChill},{humidity},{indoorTemperature},{indoorHumidity},{pressure},{averageWindSpeed},{gustWindSpeed},{windDirection},{rainfall},{averageUVIndex},{solarRadiation}
To stop streaming, send Ctrl+C. Example:
$ stream/live "sb"
# Streaming live data for station 'sb'. Send ^C to stop.
l,13.83,8.87,12.95,13.83,72,17.67,67,1005.6,0.90,158,60,0,14,2021-08-05,0,4.30,2,121,0.0,0,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None
l,13.83,8.87,12.95,13.83,72,17.67,67,1005.6,0.90,157,60,0,14,2021-08-05,0,4.30,2,121,0.0,0,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None
l,13.83,8.87,13.30,13.83,72,17.67,67,1005.6,0.40,158,60,0,14,2021-08-05,0,4.30,2,121,0.0,0,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None,None
EXIT
# Finished
These commands all list various things.
Lists stations available from the weather server.
Has the following qualifiers:
-
/json=- output as JSON rather than a table
$ list stations
┌────┬───────────────────────┐
│Code│Name │
├────┼───────────────────────┤
│rua2│Ruakura Station │
│sb │Sandy Bay, Port Charles│
│hlz │Hamilton East │
│rua │Old Ruakura Station │
└────┴───────────────────────┘
Available to logged in users only (via SSH). Shows a table of all currently active sessions.
$ list sessions
┌────────────────────────────────────┬─────────┬─────────┬────────────────────────┐
│Session Id │Username │Protocol │Connect time │
├────────────────────────────────────┼─────────┼─────────┼────────────────────────┤
│8fb02a2c-f5e0-11eb-b6de-f23c91ae0a30│anonymous│websocket│1 day, 18:17:19.119519 │
│4d788f16-f732-11eb-b6de-f23c91ae0a30│anonymous│telnet │1:59:40.318984 │
│1116b4ca-bf48-11eb-b6de-f23c91ae0a30│anonymous│websocket│71 days, 5:44:57.811082 │
│a293bf14-f72f-11eb-b6de-f23c91ae0a30│anonymous│raw │2:18:46.024686 │
│0ffce5b4-bf48-11eb-b6de-f23c91ae0a30│anonymous│websocket│71 days, 5:44:59.657945 │
│9e232e76-a2fa-11eb-b6de-f23c91ae0a30│anonymous│websocket│107 days, 6:09:54.473209│
│8f169d8a-f5e0-11eb-b6de-f23c91ae0a30│anonymous│websocket│1 day, 18:17:20.125874 │
│8f6f448a-f5e0-11eb-b6de-f23c91ae0a30│anonymous│websocket│1 day, 18:17:19.544914 │
│70e59a0c-f732-11eb-b6de-f23c91ae0a30│anonymous│websocket│1:58:40.884169 │
│0f7feadc-bf48-11eb-b6de-f23c91ae0a30│anonymous│websocket│71 days, 5:45:00.477064 │
│42ec626e-f73e-11eb-b6de-f23c91ae0a30│admin │ssh │0:34:04.054193 │
└────────────────────────────────────┴─────────┴─────────┴────────────────────────┘
Available to logged in users only (via SSH). This command receives data from the client and stores it in the database. Weather Push is the supported client for this command. The data format it receives is similar to the CSV format the subscribe command supplies.
The continuation character '-' lets you split a command over multiple lines. The shell will prompt for subsequent lines starting with "_". For example:
$ show -
_ station "sb" -
_ /json
{"code": "sb", "name": "Sandy Bay, Port Charles", "hardware_type_name": "Davis Vantage Pro2 or Vantage Vue", "live_data_available": true, "hardware_type_code": "DAVIS", "config": {"is_wireless": false, "hardware_type": "PRO2CP", "has_solar_and_uv": true, "broadcast_id": null}, "sample_interval": 300, "description": "Sandy Bay, Port Charles on the Coromandel Peninsular"}