=====
Usage
=====

To use Gearthonic in a project::

	from gearthonic import GearClient
	# Initialise the client with the host and port of your homegear server
	gc = GearClient('192.168.1.100', 2001, secure=True)
	# Now you can make your requests
	gc.device.list_methods()
	gc.device.get_value(1, 4, 'ACTUAL_TEMPERATURE')


The default port of the Homegear XML RPC server is ``2001``.

All methods are already implemented within the client to make it easy to use. You don't have to lookup all methods and
their parameters, just look at the code or see :doc:`api/methods`.

Instead of using the already implemented pythonic functions you can use the generic ``call`` method to call any
method yo want::

    gc.call('listDevices')

You can also provide parameters to the ``call`` method::

    gc.call('getValue', 1, 4, 'ACTUAL_TEMPERATURE')

A full list of all available methods provided by the XML RPC server can be found in the `wiki of the Homegear project`_.

Security
========

If you set ``secure=True`` while initialising the GearClient, the client tries to establish a secure connection to the
server via SSL. It's highly recommended to use SSL for the network traffic. Otherwise the communication is not
encrypted.


.. _wiki of the Homegear project: https://www.homegear.eu/index.php/XML_RPC_Method_Reference