awesome/lib/lain/wiki/weather.md

Usage

Read here.

Description

Provides current weather status widgets and X-days forecast pop-up notifications.

Powered by OpenWeatherMap. Obtain a free API key here and set it as the APPID argument.

By default, it uses current for current weather data and forecast16 for forecasts.

local myweather = lain.widget.weather()

Input table

Variable	Meaning	Type	Default
APPID	API key	String	nil
timeout	Refresh timeout seconds for current weather status	number	900 (15 min)
current_call	Command to fetch weather status data from the API	string	see default_current_call
forecast_call	Command to fetch forecast data from the API	string	see default_forecast_call
city_id	API city code	number	not set
units	Temperature units system	string	"metric"
lang	API data localization	string	"en"
cnt	Forecast days interval	integer	5
icons_path	Icons path	string	lain/icons/openweathermap
notification_preset	Preset for notifications	table	empty table
notification_text_fun	Function to format forecast notifications	function	see notification_text_fun below
weather_na_markup	Markup to be used when weather textbox is not available	text	" N/A "
followtag	Display the notification on currently focused screen	boolean	false
showpopup	Display popups with mouse hovering	string, possible values: "on", "off"	"on"
settings	User settings	function	empty function
widget	Widget to render	function	wibox.widget.textbox

• default_current_call

  "curl -s 'http://api.openweathermap.org/data/2.5/weather?id=%s&units=%s&lang=%s&APPID=%s'"

  You can rewrite it using any fetcher solution you like, or you can modify it in order to fetch data by city name, instead of ID: just replace id with q:

  "curl -s 'http://api.openweathermap.org/data/2.5/weather?q=%s&units=%s&lang=%s&APPID=%s'"

  and set city_id with your city name, for instance city_id = "London,UK".

• default_forecast_call

  "curl -s 'http://api.openweathermap.org/data/2.5/forecast/daily?id=%s&units=%s&lang=%s&APPID=%s'"

  Like above.

• city_id

  An integer that defines the OpenWeatherMap ID code of your city. To obtain it go to OpenWeatherMap and query for your city in the top search bar. The link will look like this:

    http://openweathermap.org/city/2643743
  

  your city_id is the number at the end.

• units

  • For temperature in Fahrenheit use units = "imperial"
  • For temperature in Celsius use units = "metric" (Lain default)
  • For temperature in Kelvin use units = "standard" (OpenWeatherMap default)

• lang

  See Multilingual Support section here.

• icons_path

  You can set your own icons path if you don't wish to use lain/icons/openweathermap. Just be sure that your icons are PNGs and named exactly like OpenWeatherMap ones.

• notification_preset

  Notifications preset table. See here for the details.

• notification_text_fun

  function (wn)
      local day = os.date("%a %d", wn["dt"])
      local temp = math.floor(wn["main"]["temp"])
      local desc = wn["weather"][1]["description"]
  
      return string.format("<b>%s</b>: %s, %d ", day, desc, temp)
  end
  

• followtag

  With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting followtag to true it will be shown on the currently focused tag screen.

• settings

  In your settings function, you can use widget variable to refer to the textbox, and the dictionary weather_now to refer to data retrieved by current_call. The dictionary is built with dkjson library, and its structure is defined here. For instance, you can retrieve current weather status and temperature in this way:

  descr = weather_now["weather"][1]["description"]:lower()
  units = math.floor(weather_now["main"]["temp"])
  

Output table

Variable	Meaning	Type
widget	The widget	wibox.widget.textbox
icon	The icon	wibox.widget.imagebox
update	Update widget	function
timer	The widget timer	gears.timer
timer_forecast	The forecast notification timer	gears.timer

Functions

You can attach the forecast notification to any widget like this:

myweather.attach(obj)

Hovering over obj will display the notification.

Key bindings

You can create a key binding for the weather pop-up like this:

awful.key( { "Mod1" }, "w", function () myweather.show(5) end )

Where the show argument is an integer defining timeout seconds.