WeatherLink

This is an unofficial implementation of the Davis Instruments WeatherLink API, including both the Local API (v1) and the web API (v2).

Installation

Add this line to your application's Gemfile:

gem 'weatherlink'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install weatherlink

Usage

Local API

To read the data from a local WeatherLink Live device via the "local API" (there is no authentication):

require 'weatherlink'

> wl = WeatherLink::LocalClient.new(host: '<local ip address>')

The current_conditions method returns a SensorData object for each sensors:

> cc = wl.current_conditions
=> #<WeatherLink::SensorDataCollection (3 sensors)>

> cc.to_a
=> [#<WeatherLink::SensorData lsid=1 (Local API - ISS Record, 1 records)>,
    #<WeatherLink::SensorData lsid=2 (Local API - LSS Temperature/Humidity Record, 1 records)>, 
    #<WeatherLink::SensorData lsid=3 (Local API - LSS Barometric Pressure Record, 1 records)>]

Each SensorData is a wrapper for a hash containing the underlying data. Each of its keys can also be used as a method to get the data itself.

> pp cc[0].to_h
{"ts"=>1609130694,
  "temp"=>24.2 tempF,
  "hum"=>84.9 %,
  "dew_point"=>20.3 tempF,
  "wet_bulb"=>22.6 tempF,
  "heat_index"=>24.2 tempF,
  "wind_chill"=>24.2 tempF,
  "thw_index"=>24.2 tempF,
  "thsw_index"=>22.2 tempF,
  "wind_speed_last"=>0 mph,
  "wind_dir_last"=>0 deg,
  "wind_speed_avg_last_1_min"=>0 mph,
  "wind_dir_scalar_avg_last_1_min"=>149 deg,
  "wind_speed_avg_last_2_min"=>0 mph,
  "wind_dir_scalar_avg_last_2_min"=>149 deg,
  "wind_speed_hi_last_2_min"=>1 mph,
  "wind_dir_at_hi_speed_last_2_min"=>149 deg,
  "wind_speed_avg_last_10_min"=>0 mph,
  "wind_dir_scalar_avg_last_10_min"=>149 deg,
  "wind_speed_hi_last_10_min"=>1 mph,
  "wind_dir_at_hi_speed_last_10_min"=>149 deg,
  "rain_size"=>1,
  "rain_rate_last"=>0 in/h,
  "rain_rate_hi"=>0 in/h,
  "rainfall_last_15_min"=>0 in,
  "rain_rate_hi_last_15_min"=>0 in/h,
  "rainfall_last_60_min"=>0 in,
  "rainfall_last_24_hr"=>0 in,
  "rain_storm"=>0 in,
  "rain_storm_start_at"=>nil,
  "solar_rad"=>0 W/m^2,
  "uv_index"=>0.0,
  "rx_state"=>0,
  "trans_battery_flag"=>0,
  "rainfall_daily"=>0 in,
  "rainfall_monthly"=>18 in,
  "rainfall_year"=>128 in,
  "rain_storm_last"=>5 in,
  "rain_storm_last_start_at"=>1608224100,
  "rain_storm_last_end_at"=>1608318061}

Note that the unit support uses ruby-units which uses Rational, so some of the results can be... interesting:

> cc[0].temp
=> -3342515348439043/791648371998720 tempC

Use scalar.to_f to get a Float most of the time:

> cc[0].temp.scalar.to_f
=> -4.222222222222226

Web API

Obtain API credentials form your WeatherLink account and initialize the API:

require 'weatherlink'

> wl = WeatherLink::Client.new(api_key: '<api key>', api_secret: '<api secret>')

Various aspects of the API and devices can be interrogated:

> wl.stations
=> [#<WeatherLink::Station station_id=1 gateway_id_hex=a (Jackalope)>]

> wl.sensors
=> [#<WeatherLink::Sensor lsid=1 (Davis Instruments - WeatherLink LIVE Health)>,
    #<WeatherLink::Sensor lsid=2 (Davis Instruments - Barometer)>,
    #<WeatherLink::Sensor lsid=3 (Davis Instruments - Inside Temp/Hum)>,
    #<WeatherLink::Sensor lsid=4 (Davis Instruments - Vantage Pro2 Plus /w 24-hr-Fan-Aspirated Radiation shield, UV & Solar Radiation Sensors)>,
    #<WeatherLink::Sensor lsid=5 (Davis Instruments - AQS Health)>,
    #<WeatherLink::Sensor lsid=6 (Davis Instruments - AirLink)>,
    #<WeatherLink::Sensor lsid=7 (Davis Instruments - AQS Health)>,
    #<WeatherLink::Sensor lsid=8 (Davis Instruments - AirLink)>,
    #<WeatherLink::Sensor lsid=9 (Davis Instruments - AQS Health)>,
    #<WeatherLink::Sensor lsid=10 (Davis Instruments - AirLink)>]

> wl.nodes
=> [#<WeatherLink::Node device_id_hex=a (Station - Barn)>,
    #<WeatherLink::Node device_id_hex=b (Station - Living Room)>,
    #<WeatherLink::Node device_id_hex=c (Station - Office)>]

Since most users will probably only have one station, a station method returns the first station for convenience:

wl.station
=> #<WeatherLink::Station station_id=1 gateway_id_hex=a (Station)>

To collect current weather data from all sensor of the first/primary station:

> wl.station.current
=> #<WeatherLink::SensorDataCollection (10 sensors)>

At this point accessing the underlying data is exactly the same as using the Local API above.

Since the station knows the IP addresses of each sensor, if you're on the local network you can also access these sensors directly through the local_sensors method (which uses the same WeatherLink::LocalClient API above, but automatically configures it for each known sensor):

> wl.station.local_sensors
=> [#<struct WeatherLink::Station::LocalSensor device=#<WeatherLink::Station station_id=1 gateway_id_hex=a (Station)>, host="1.2.3.4">,
    #<struct WeatherLink::Station::LocalSensor device=#<WeatherLink::Node device_id_hex=b (Station - Living Room)>, host="1.2.3.5">,
    #<struct WeatherLink::Station::LocalSensor device=#<WeatherLink::Node device_id_hex=c (Station - Office)>, host="1.2.3.6">,
    #<struct WeatherLink::Station::LocalSensor device=#<WeatherLink::Node device_id_hex=d (Station - Barn)>, host="1.2.3.7">]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jeremycole/weatherlink.

License

The gem is available as open source under the terms of the MIT License.