Weather addons: Difference between revisions
RogueScholar (talk | contribs) (Create Glossary section for property names and add link to Weather in case someone is looking for user-targeted information, not developer stuff) |
|||
(2 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{Main|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. | Weather addons use the 'xbmc.python.weather' extension point. | ||
The basic layout of the addon.xml of a weather addon will look like: | The basic layout of the addon.xml of a weather addon will look like: | ||
<syntaxhighlight lang="xml"> | <syntaxhighlight lang="xml" line highlight="6" style="white-space: pre-wrap;"> | ||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> | <?xml version="1.0" encoding="UTF-8" standalone="yes"?> | ||
<addon id="weather.name" name="My Weather" version="1.2.3" provider-name="me"> | <addon id="weather.name" name="My Weather" version="1.2.3" provider-name="me"> | ||
<requires> | <requires> | ||
<import addon="xbmc.python" version=""/> | <import addon="xbmc.python" version="" /> | ||
</requires> | </requires> | ||
<extension point="xbmc.python.weather" library=""/> | <extension point="xbmc.python.weather" library="" /> | ||
<extension point="xbmc.addon.metadata"> | <extension point="xbmc.addon.metadata"> | ||
<summary lang="en"></summary> | <summary lang="en"></summary> | ||
Line 25: | Line 29: | ||
=Things | == Things to know == | ||
There | 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: | ||
< | ** <code>Weather.Conditions</code> | ||
** <code>Weather.Temperature</code> | |||
** <code>Weather.Location</code> | |||
* 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 | ||
* | |||
* In the weather window, | |||
* Kodi will also handle transformations between units (for instance, Celsius to Fahrenheit, km/h to mph) | * 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: | Kodi can run a weather addon in two modes: | ||
== | |||
In order to set up a weather addon, you need to include a settings.xml file for your weather addon. | === Weather location configuration === | ||
It needs to have this structure: | 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: | ||
<syntaxhighlight lang="xml"> | <syntaxhighlight lang="xml" style="white-space: pre-wrap;"> | ||
<?xml version="1.0" encoding="utf-8" standalone="yes"?> | <?xml version="1.0" encoding="utf-8" standalone="yes"?> | ||
<settings> | <settings> | ||
<category> | <category> | ||
<setting id="Location1" label="Location 1" type="action" action="RunScript($ID,Loc1)" default=""/> | <setting id="Location1" label="Location 1" type="action" action="RunScript($ID,Loc1)" default=""/> | ||
<setting id="Location2" label="Location 2" type="action" action="RunScript($ID,Loc2)" enable="!eq(-1,)" default=""/> | <setting id="Location2" label="Location 2" type="action" action="RunScript($ID,Loc2)" enable="!eq(-1,)" default="" /> | ||
<setting id="Location3" label="Location 3" type="action" action="RunScript($ID,Loc3)" enable="!eq(-1,)" default=""/> | <setting id="Location3" label="Location 3" type="action" action="RunScript($ID,Loc3)" enable="!eq(-1,)" default="" /> | ||
<setting id="Location4" label="Location 4" type="action" action="RunScript($ID,Loc4)" enable="!eq(-1,)" default=""/> | <setting id="Location4" label="Location 4" type="action" action="RunScript($ID,Loc4)" enable="!eq(-1,)" default="" /> | ||
<setting id="Location5" label="Location 5" type="action" action="RunScript($ID,Loc5)" enable="!eq(-1,)" default=""/> | <setting id="Location5" label="Location 5" type="action" action="RunScript($ID,Loc5)" enable="!eq(-1,)" default="" /> | ||
</category> | </category> | ||
</settings> | </settings> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
You can define as many weather locations as you want in your settings.xml file. | |||
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. | |||
For instance, if the | |||
=== 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. | 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. | ||
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: | The basic python code needed to provide a window property: | ||
Line 74: | Line 73: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Kodi expects a weather addon to return these properties: | |||
{{Glossary}} | |||
{{Term|1=Current.Condition|2=<code>Current.Condition</code>}} | |||
{{Defn|1=the weather forecast|style=margin-left: 4em;}} | |||
{{Term|1=Current.Temperature|2=<code>Current.Temperature</code>}} | |||
{{Defn|1=temperature in degrees Celsius|style=margin-left: 4em;}} | |||
{{Term|1=Current.Wind|2=<code>Current.Wind</code>}} | |||
{{Defn|1=windspeed in km/h|style=margin-left: 4em;}} | |||
{{Term|1=Current.WindDirection|2=<code>Current.WindDirection</code>}} | |||
{{Defn|1=wind direction, NNE|style=margin-left: 4em;}} | |||
{{Term|1=Current.Humidity|2=<code>Current.Humidity</code>}} | |||
{{Defn|1=relative humidity as a percentage|style=margin-left: 4em;}} | |||
{{Term|1=Current.FeelsLike|2=<code>Current.FeelsLike</code>}} | |||
{{Defn|1=feels-like temperature in degrees Celsius|style=margin-left: 4em;}} | |||
{{Term|1=Current.UVIndex|2=<code>Current.UVIndex</code>}} | |||
{{Defn|1=the UV-index as an integer|style=margin-left: 4em;}} | |||
{{Term|1=Current.DewPoint|2=<code>Current.DewPoint</code>}} | |||
{{Defn|1=dewpoint in degrees Celsius|style=margin-left: 4em;}} | |||
{{Term|1=Current.OutlookIcon|2=<code>Current.OutlookIcon</code>}} | |||
{{Defn|1=weather icon, as a filename (e.g. 34.png)|style=margin-left: 4em;}} | |||
{{Term|1=Current.FanartCode|2=<code>Current.FanartCode</code>}} | |||
{{Defn|1=condition code, as an integer (see Weather Codes section below)|style=margin-left: 4em;}} | |||
{{Term|1=Day%i.Title|2=<code>Day%i.Title</code>}} | |||
{{Defn|1=day of the week|style=margin-left: 4em;}} | |||
{{Term|1=Day%i.HighTemp|2=<code>Day%i.HighTemp</code>}} | |||
{{Defn|1=high temperature for the day, in degrees Celsius|style=margin-left: 4em;}} | |||
{{Term|1=Day%i.LowTemp|2=<code>Day%i.LowTemp</code>}} | |||
{{Defn|1=low temperature of the day, in degrees Celsius|style=margin-left: 4em;}} | |||
{{Term|1=Day%i.Outlook|2=<code>Day%i.Outlook</code>}} | |||
{{Defn|1=the weather forecast|style=margin-left: 4em;}} | |||
{{Term|1=Day%i.OutlookIcon|2=<code>Day%i.OutlookIcon</code>}} | |||
{{Defn|1=weather icon, as a filename|style=margin-left: 4em;}} | |||
{{Term|1=Day%i.FanartCode|2=<code>Day%i.FanartCode</code>}} | |||
{{Defn|1=condition code, as an integer|style=margin-left: 4em;}} | |||
{{Glossary end}} | |||
Kodi will read those window properties and do unit conversions if needed, depending on the regional settings in Kodi.<br /> | Kodi will read those window properties and do unit conversions if needed, depending on the regional settings in Kodi.<br /> | ||
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: | |||
The name of the window property set by the weather addon and the resulting window property for the skin will differ in a few | |||
* Current.OutlookIcon (addon) -> Current.ConditionIcon (skin) | * Current.OutlookIcon (addon) -> Current.ConditionIcon (skin) | ||
* Current.Wind (addon) -> Current.WindSpeed (skin) | * Current.Wind (addon) -> Current.WindSpeed (skin) | ||
* Current.Wind / Current.WindDirection (addon) -> Current.Wind (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>'<br /> | Kodi combines the Wind and WindDirection properties into a Wind property with this format: 'From <wind dir> at <speed> <unit>'<br /> | ||
In addition, several window properties set by the addon | 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.Condition (addon) -> Weather.Conditions (skin) | ||
* Current.Temperature (addon) -> Weather.Temperature (skin) | * Current.Temperature (addon) -> Weather.Temperature (skin) | ||
* Current.FanartCode (addon) -> Weather.FanartCode (skin) | * Current.FanartCode (addon) -> Weather.FanartCode (skin) | ||
Finally, at the end of your script, you need to set the following window properties: | Finally, at the end of your script, you need to set the following window properties: | ||
<pre> | <pre> | ||
* Location%i (the name of each weather location that has been configured by the user. | * 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!) | * Locations (the total number of locations that have been set up by the user. don't count the ones that have not been configured!) | ||
</pre><br /> | </pre><br /> | ||
Line 197: | Line 207: | ||
na not available | na not available | ||
</pre> | </pre> | ||
[[Category:Add-on_development]] |
Latest revision as of 07:51, 10 September 2021
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="" /> </requires> <extension point="xbmc.python.weather" library="" /> <extension point="xbmc.addon.metadata"> <summary lang="en"></summary> <description lang="en"></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> <category> <setting id="Location1" label="Location 1" type="action" action="RunScript($ID,Loc1)" default=""/> <setting id="Location2" label="Location 2" type="action" action="RunScript($ID,Loc2)" enable="!eq(-1,)" default="" /> <setting id="Location3" label="Location 3" type="action" action="RunScript($ID,Loc3)" enable="!eq(-1,)" default="" /> <setting id="Location4" label="Location 4" type="action" action="RunScript($ID,Loc4)" enable="!eq(-1,)" default="" /> <setting id="Location5" label="Location 5" type="action" action="RunScript($ID,Loc5)" enable="!eq(-1,)" default="" /> </category> </settings>
You can define as many weather locations as you want in your settings.xml file.
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 return these properties:
Current.Condition
- the weather forecast
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.OutlookIcon
- weather icon, as a filename (e.g. 34.png)
Current.FanartCode
- condition code, as an integer (see Weather Codes section below)
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
- condition code, as an integer
Kodi will read those window properties and do unit conversions if needed, depending on the regional settings in Kodi.
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:
- https://github.com/xbmc/repo-scripts/blob/krypton/weather.openweathermap.extended/README.txt
- https://github.com/xbmc/repo-scripts/blob/jarvis/weather.wunderground/README.txt
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