Kodi specific services to call Kodi API methods

[azogue]

Description:

New Kodi-specific services for accessing the Kodi JSONRPC API through Home Assistant, in order to simply (and asynchronously) access the full potential of the Kodi API.

Calls to the Kodi API that return results are redirected by triggering events with the information of the call parameters and the results obtained:

event_data = {
  'result': api_call_results,
  'result_ok': boolean,
  'input': api_call_parameters,
  'entity_id': 'media_player.kodi'}

The new services are:

• kodi_execute_addon to run a Kodi Addon with optional parameters. Results of the Kodi API call, if any, are redirected in a Home Assistant event: kodi_execute_addon_result.
• kodi_call_method to run a Kodi JSONRPC API method with optional parameters. Results of the Kodi API call are redirected in a Home Assistant event: kodi_call_method_result.

Also, expose the timeout parameter in the Kodi platform yaml config, to be able to make slow queries to the JSONRPC API (default timeout is set to 5s).

The documentation PR includes two examples of using these new services, including a simple example of using a Kodi Addon to turn on the TV, and a more complex one with scripts and a small AppDaemon App to form a dynamic input_select with choices of media playback in Kodi.

Pull request in home-assistant.github.io with documentation (if applicable): home-assistant/home-assistant.io#2635

Checklist:

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated in home-assistant.github.io

[mention-bot]

@azogue, thanks for your PR! By analyzing the history of the files in this pull request, we identified @fabaff, @armills and @ettisan to be potential reviewers.

[emlove]

I like this idea overall. Should reduce the need to keep adding services.

1. Is there a reason Addons.ExecuteAddon couldn't just be called with the new kodi_run_method service?

2. What was the problem with the ordered dicts? If the jsonrpc lib is rejecting them it's likely better to fix it upstream.

[azogue]

Hi, @armills

1. Not really, the reason for its inclusion has been because I think it's an API function that can be heavily used from HA (like direct commands for Kodi beyond the usual for media playback), and it usually does not produce results to be processed later, as opposed to a general call to the API with the generic service kodi_run_method.
   But the truth is that it is there because it was the first use I needed! (for a switch custom component that runs the CEC Addon to turn on the TV)

   The equivalence would be:

   script:
     activate_tv:
       alias: Turn on TV
       sequence:
         - alias: TV on
           service: media_player.kodi_execute_addon
           data:
             entity_id: media_player.kodi
             addonid: script.json-cec
             params:
               command: activate
   # is equivalent to:
     activate_tv_gen:
       alias: Turn on TV
       sequence:
         - alias: TV on
           service: media_player.kodi_run_method
           data:
             entity_id: media_player.kodi
             method: Addons.ExecuteAddon
             addonid: script.json-cec
             params:
               command: activate

   (Now that I see them together, it seems obvious to me!)

   So, yes, I suppose the kodi_execute_addon service is not necessary.
   Do I only include the kodi_run_method service in the PR?
   Are the service and event names convenient?

2. The need to 'clean' the OrderedDicts is because the arguments arrive like this: kwargs={'addonid': 'script.json-cec', 'params': OrderedDict([('command', 'activate’)])} And the jsonrpc_base was failing. I would have sworn that the call failed with OrderedDicts (which does not make much sense, since the JSON produced must be the same), but now that I have tested it without cleaning, it does not pose any problems ...
   I do not know what happened here, my apologies, I will remove that function.

[houndci-bot]

'collections.OrderedDict' imported but unused

[emlove]

Should this be (**kwargs) instead of (kwargs)?

[azogue]

It works both ways, now that I check it, I'll leave it simpler, without the if condition.

And I'll change the names.

[emlove]

No problem. I know how code tends to evolve over time and what makes sense starts to change. This will be a great addition, since it will pretty much expose everything Kodi can do. 👍

I suppose instead of kodi_run_method, I would prefer kodi_call_method, since the protocol is Remote Procedure Call. Same for the result event name. Just a nitpick though.

[emlove]

LGTM. Great work!

[cmsimike]

This is so awesome! Thank you very much!