Gearthonic¶

GearClient¶

Client for the APIs provided by Homegear.

class gearthonic.client.GearClient(host, port, protocol=0, **kwargs)[source]¶

Client for the APIs provided by Homegear.

Usage:

>>> gc = GearClient('localhost', 1234)
>>> gc.device.list_devices()

The default communication protocol is XML RPC. Additionally, JSON RPC is supported:

>>> from gearthonic import JSONRPC
>>> GearClient('localhost', 1234, protocol=JSONRPC)

Any protocol can accept additional parameters. Provide them while initialising the client:

>>> GearClient('localhost', 1234, protocol=JSONRPC, secure=False, username='ham')

For a full list of supported parameters, have a look at each protocol class or see the documentation for the protocols. :class:

call(method_name, *args, **kwargs)[source]¶

Call the given method using the instantiated protocol.

Parameters:	method_name – method to be called args – arguments passed through kwargs – keyword arguments passed through
Returns:	return value of the call

device¶

Smart access to all device related API methods.

system¶

Smart access to all system related API methods.

Communication protocols¶

These classes are used to communicate with the different APIs provided by the Homegear server.

class gearthonic.protocols.JsonRpcProtocol(host, port, secure=True, verify=True, username=None, password=None)[source]¶

Communicate with Homegear via JSON RPC.

>>> jp = JsonRpcProtocol('host.example.com', 2003)
>>> jp.call('listDevices')
[...]

Set secure=False to use http instead off https. Set verify=False to skip the verification of the SSL cert.

Provide credentials via username and password if the Homegear server is secured by basic auth. It’s not possible to use authentication with an insecure connection (http)!

call(method_name, *args, **kwargs)[source]¶

Call the given method using the HTTPServer.

Parameters:	method_name – Method to be called args – Arguments passed through kwargs – Keyword arguments passed through
Returns:	Return value of the XML RPC method

class gearthonic.protocols.XmlRpcProtocol(host, port, secure=True, verify=True, username=None, password=None)[source]¶

Communicate with Homegear via XML RPC.

>>> xp = XmlRpcProtocol('host.example.com', 2003)
>>> xp.call('listDevices')
[...]

Set secure=False to use http instead off https. Set verify=False to skip the verification of the SSL cert.

Provide credentials via username and password if the Homegear server is secured by basic auth. It’s not possible to use authentication with an insecure connection (http)!

call(method_name, *args, **kwargs)[source]¶

Call the given method using the ServerProxy.

Parameters:	method_name – Method to be called args – Arguments passed through kwargs – Keyword arguments passed through
Returns:	Return value of the XML RPC method

gearthonic.protocols.initialise_protocol(protocol, host, port, **kwargs)[source]¶

Factory method to initialise a specific protocol.

Parameters:	protocol (int) – ID of the protocol to initialise host (str) – host of the server port (int) – port of the server kwargs – will be used to initialise the protocol
Return type:	_ProtocolInterface

System methods¶

class gearthonic.methods.SystemMethodsCollection(caller)[source]¶

All XML RPC server provide a set of standard methods.

get_capabilities()[source]¶

Lists server’s XML RPC capabilities.

Example output:

{
    'xmlrpc': {'specUrl': 'http://example.com', 'specVersion': 1}
    'faults_interop': {'specUrl': 'http://example2.com', 'specVersion': 101}
    'introspection': {'specUrl': 'http://example3.com', 'specVersion': 42}
}

Returns:	A dict containing all information
Return type:	dict

list_methods()[source]¶

Lists servers’s XML RPC methods.

Returns:	A list of available methods
Return type:	list

method_help(method_name)[source]¶

Returns the description of a method.

Parameters:	method_name (str) – The name of the method
Returns:	The description of the method
Return type:	str

method_signature(method_name)[source]¶

Returns the signature of a method.

Parameters:	method_name (str) – The name of the method
Returns:	The signature of the method
Return type:	list

multicall(methods)[source]¶

Call multiple methods at once.

Example list of methods:

[
    {'methodName': 'getValue', 'params': [13, 4, 'TEMPERATURE']},
    {'methodName': 'getValue', 'params': [3, 3, 'HUMIDITY']}
]

Return value of the multicall:

[22.0, 58]

Parameters:	methods (list) – A list of methods and their parameters
Returns:	A list of method responses.
Return type:	list

Device methods¶

class gearthonic.methods.DeviceMethodsCollection(caller)[source]¶

All device related methods.

activate_link_paramset(peer_id, channel, remote_peer_id, remote_channel, long_pressed=False)[source]¶

Returns:

get_value(peer_id, channel, key, request_from_device=False, asynchronous=False)[source]¶

Return the value of the device, specified by channel and key (parameterName).

Per default the value is read from the local cache of Homegear. If the value should be read from the device, use request_from_device. If the value should be read from the device, this can be done asynchronously. The method returns immediately and doesn’t wait for the current value. The value will be sent as an event as soon as it’s returned by the device.

Error codes:

• Returns -2 when the device or channel is unknown
• Returns -5 when the key (parameter) is unknown

Parameters:	peer_id (int) – ID of the device channel (int) – Channel of the device to get the value for key (str) – Name of the parameter to get the value for request_from_device (bool) – If true value is read from the device asynchronous (bool) – If true value is read asynchronously
Returns:	The value of the parameter or error code
Return type:	unknown

list_devices()[source]¶

Return a list of devices.

Returns:	List of devices
Return type:	list

set_value(peer_id, channel, key, value)[source]¶

Set the value of the device, specified by channel and key (parameterName).

Parameters:	peer_id (int) – ID of the device channel (int) – Channel of the device to set the value for key (str) – Name of the parameter to get the value for value (unknown) – The value to set
Returns:	None on success -2 when the device or channel is unknown -5 when the key (parameter) is unknown -100 when the device did not respond -101 when the device returns an error