Latest revision as of 13:31, 28 October 2024

Main page: Weather

Note: This page describes the development of Weather addons for Kodi. If you're interested in them from a user's perspective (where to get them, how to configure them, etc.), please use the link above.

addon.xml

Weather addons use the 'xbmc.python.weather' extension point. The basic layout of the addon.xml of a weather addon will look like:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="weather.name" name="My Weather" version="1.2.3" provider-name="me">
	<requires>
		<import addon="xbmc.python" version="3.0.0" />
	</requires>
	<extension point="xbmc.python.weather" library="" />
	<extension point="xbmc.addon.metadata">
		<summary lang="en_GB"></summary>
		<description lang="en_GB"></description>
		<language></language>
		<platform></platform>
		<license></license>
		<forum></forum>
		<website></website>
		<email></email>
		<source></source>
	</extension>
</addon>

Things to know

There are a few things (quirks) you need to be aware of when creating a weather addon...

A weather addon will be run automatically when the skins asks to display one of these weather-specific infolabels:
- Weather.Conditions
- Weather.Temperature
- Weather.Location
The weather addon will run at 30 minute intervals (as long the current skin window displays one of the above-mentioned infolabels)
In the weather window, Kodi will automatically try to translate all the weather strings
Kodi will also handle transformations between units (for instance, Celsius to Fahrenheit, km/h to mph)

Theory of operation

Kodi can run a weather addon in two modes:

Weather location configuration

In order to set up a weather addon, you need to include a settings.xml file for your weather addon. It needs to have this structure:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings version="1">
  <section id="weather.name">
    <category id="locations" label="">
      <group id="1">
        <setting id="location1" type="string" label="" help="">
          <level>0</level>
          <default/>
          <constraints>
              <allowempty>true</allowempty>
          </constraints>
          <control type="button" format="action">
              <data>RunScript(weather.name,location1)</data>
          </control>
        </setting>
        <setting id="location2" type="string" label="32003" help="">
          <level>0</level>
          <default/>
          <constraints>
              <allowempty>true</allowempty>
          </constraints>
          <control type="button" format="action">
              <data>RunScript(weather.name,location2)</data>
          </control>
          <dependencies>
            <dependency type="enable" operator="!is" setting="location1" />
          </dependencies>
        </setting>
        <setting id="location3" type="string" label="32004" help="">
          <level>0</level>
          <default/>
          <constraints>
              <allowempty>true</allowempty>
          </constraints>
          <control type="button" format="action">
              <data>RunScript(weather.name,location3)</data>
          </control>
          <dependencies>
            <dependency type="enable" operator="!is" setting="location2" />
          </dependencies>
        </setting>
      </group>
    </category>
  </section>
</settings>

You can define as many weather locations as you want in your settings.xml file. Additional location parameters, like longitude and latitude, can be saved as invisible settings.

When you're going to set up a location in the weather addon settings, Kodi will pass the argument(s) you've defined in the RunScript() action above to your addon. For instance, if you set the 'Location 2' entry active in the Weather settings, Kodi will pass 'Loc2' to your addon.

Retrieving weather data

When weather information needs to be retrieved, Kodi will pass the location number to your addon. For instance, if the weather for Location 4 is requested, Kodi will pass '4' to the weather addon.

Required output

When a weather addon is asked to retrieve weather information, it needs to return this info to Kodi. This is done by making the various pieces of information available as window properties of the weather window.

The basic python code needed to provide a window property:

WINDOW = xbmcgui.Window(12600)
WINDOW.setProperty(name, value)

Kodi expects a weather addon to populate these properties:

Current Weather

Current.Condition: the weather condition as a string
Current.Temperature: temperature in degrees Celsius
Current.Wind: windspeed in km/h
Current.WindDirection: wind direction, NNE
Current.Humidity: relative humidity as a percentage
Current.FeelsLike: feels-like temperature in degrees Celsius
Current.UVIndex: the UV-index as an integer
Current.DewPoint: dewpoint in degrees Celsius
Current.Precipitation: precipitation probability in %
Current.Cloudiness: cloud cover in %
Current.OutlookIcon: weather icon, as a filename (e.g. 34.png)
Current.FanartCode: condition code, as an integer (see Weather Codes section below)

Kodi will read those window properties and do unit conversions if needed, depending on the regional settings in Kodi.

Hourly Weather

Hourly.%i.Time: hour time
Hourly.%i.LongDate: long date and time
Hourly.%i.ShortDate: short date and time
Hourly.%i.Outlook: weather forecast as a string
Hourly.%i.OutlookIcon: weather icon as a filename (e.g. 34.png)
Hourly.%i.FanartCode: condition code, as an integer (see Weather Codes section below)
Hourly.%i.WindSpeed: wind speed with a unit
Hourly.%i.WindDirection: wind direction as a label, e.g. NW
Hourly.%i.Humidity: humidity in %
Hourly.%i.Temperature: temperature with a unit
Hourly.%i.DewPoint: dew point as temperature with a unit
Hourly.%i.FeelsLike: apparent temperature with a unit
Hourly.%i.Pressure: pressure with a unit
Hourly.%i.Precipitation: precipitation probability in %

Note that those parameters are not localized autmatically so it's addon's responsibility to localize them properly. Hourly items are 1-indexed, that is, they start from 1.

Daily Weather

Daily.%i.ShortDate

short date

Daily.%i.ShortDay

short day label, e.g. Mon

Daily.%i.HighTemperature

high temperature with a unit

Daily.%i.LowTemperature

low temperature with a unit

Daily.%i.Outlook

weather forecast as a string

Daily.%i.OutlookIcon

weather icon as a filename (e.g. 34.png)

Daily.%i.FanartCode

condition code, as an integer (see Weather Codes section below)

Daily.%i.WindSpeed

wind speed with a unit

Daily.%i.WindDirection

wind direction as a label, e.g. NW

Daily.%i.Precipitation

precipitation probability in %

Note that those parameters are not localized autmatically so it's addon's responsibility to localize them properly. Daily items are 1-indexed, that is, they start from 1.

Additional Weather Properties

Some skins, e.g. aeon.nox.silvo, may use the following properties (up to 7 days):

Day%i.Title: day of the week
Day%i.HighTemp: high temperature for the day, in degrees Celsius
Day%i.LowTemp: low temperature of the day, in degrees Celsius
Day%i.Outlook: the weather forecast
Day%i.OutlookIcon: weather icon, as a filename
Day%i.FanartCode: weather forecast as a string

Note that those properties are 0-indexed.

General Properties

Location: location name
Current.Location: location name
WeatherProvider: weather addon name
WeatherProviderLogo: path to the addon logo file, preferrabely in a banner format
Weather.IsFetched: true if weather info is fetched
Current.IsFetched: true if current weather info is fetched
Hourly.IsFetched: true if hourly weather info is fetched
Daily.IsFetched: true if daily weather info is fetched

The name of the window property set by the weather addon and the resulting window property for the skin will differ in a few scenarios:

Current.OutlookIcon (addon) -> Current.ConditionIcon (skin)
Current.Wind (addon) -> Current.WindSpeed (skin)
Current.Wind / Current.WindDirection (addon) -> Current.Wind (skin)

Kodi combines the Wind and WindDirection properties into a Wind property with this format: 'From <wind dir> at <speed> <unit>'

In addition, several window properties set by the addon will be made available to the skin as infolabels:

Current.Condition (addon) -> Weather.Conditions (skin)
Current.Temperature (addon) -> Weather.Temperature (skin)
Current.FanartCode (addon) -> Weather.FanartCode (skin)

Finally, at the end of your script, you need to set the following window properties:

* Location%i (the name of each weather location that has been configured by the user. for locations that are not configured, set an empty property.)
* Locations (the total number of locations that have been set up by the user. don't count the ones that have not been configured!)

Once the addon has finished, Kodi will make one additional infolabel available to the skin:

* Weather.Location (the name of the current weather location)

The name of the weather addon, can be displayed by the skin using:

* Weather.Plugin (the name of the weather addon)

Advanced weather info (optional)

Besides the weather infolabels mentioned above, your addon can return many more, basically there are no limits. Keep in mind though, that it requires skin support to display this additional information in Kodi.

If you want to go this route, have a look at the infolabels provided by the Openweathermap and Wunderground addons:

The infolabels provided by those addons are reasonably well supported by a number of skins already, so try if you can use the same infolabel names in your addon.

Weather Codes

Kodi ships with an icon pack that includes an icon for each weather condition.
(https://github.com/xbmc/xbmc/tree/master/addons/resource.images.weathericons.default)
Several additional weather icon packs are available through the official Kodi repository.

The following condition-code table is used for the icon names:

0 	tornado
1 	tropical storm
2 	hurricane
3 	severe thunderstorms
4 	thunderstorms
5 	mixed rain and snow
6 	mixed rain and sleet
7 	mixed snow and sleet
8 	freezing drizzle
9 	drizzle
10 	freezing rain
11 	showers
12 	showers
13 	snow flurries
14 	light snow showers
15 	blowing snow
16 	snow
17 	hail
18 	sleet
19 	dust
20 	foggy
21 	haze
22 	smoky
23 	blustery
24 	windy
25 	cold
26 	cloudy
27 	mostly cloudy (night)
28 	mostly cloudy (day)
29 	partly cloudy (night)
30 	partly cloudy (day)
31 	clear (night)
32 	sunny
33 	fair (night)
34 	fair (day)
35 	mixed rain and hail
36 	hot
37 	isolated thunderstorms
38 	scattered thunderstorms
39 	scattered thunderstorms
40 	scattered showers
41 	heavy snow
42 	scattered snow showers
43 	heavy snow
44 	partly cloudy
45 	thundershowers
46 	snow showers
47 	isolated thundershowers
na 	not available