tellcore.telldus (module)

This module provides a high level Python interface to Telldus’ C API.

Since most functions are Python-ified wrappers around the C API, please also refer to the Telldus Core documentation for further information.

The classes in this module all use the library.Library class under the hood, and thus also has e.g. automatic memory manangement, exceptions (library.TelldusError) and transparent string conversion with full Python 3 support.

Some example programs are included in the documentation to help understand how to use the different classes:

TelldusCore

class tellcore.telldus.TelldusCore(library_path=None, callback_dispatcher=None)[source]

The main class for tellcore-py.

Has methods for adding devices and for enumerating controllers, devices and sensors. Also handles callbacks; both registration and making sure the callbacks are processed in the main thread instead of the callback thread.

__init__(library_path=None, callback_dispatcher=None)[source]

Create a new TelldusCore instance.

Only one instance should be used per program.

Parameters:
callback_dispatcher

The callback dispatcher used. Set when constructing the instance and should not be changed.

add_device(name, protocol, model=None, **parameters)[source]

Add a new device.

Returns:a Device or DeviceGroup instance.
add_group(name, devices)[source]

Add a new device group.

Returns:a DeviceGroup instance.
connect_controller(vid, pid, serial)[source]

Connect a controller.

controllers()[source]

Return all known controllers.

Requires Telldus core library version >= 2.1.2.

Returns:list of Controller instances.
devices()[source]

Return all known devices.

Returns:list of Device or DeviceGroup instances.
disconnect_controller(vid, pid, serial)[source]

Disconnect a controller.

register_controller_event(callback)[source]

Register a new controller event callback handler.

See Event handling (example) for more information.

Returns:the callback id
register_device_change_event(callback)[source]

Register a new device change event callback handler.

See Event handling (example) for more information.

Returns:the callback id
register_device_event(callback)[source]

Register a new device event callback handler.

See Event handling (example) for more information.

Returns:the callback id
register_raw_device_event(callback)[source]

Register a new raw device event callback handler.

See Event handling (example) for more information.

Returns:the callback id
register_sensor_event(callback)[source]

Register a new sensor event callback handler.

See Event handling (example) for more information.

Returns:the callback id
send_raw_command(command, reserved=0)[source]

Send a raw command.

sensors()[source]

Return all known sensors.

Returns:list of Sensor instances.
unregister_callback(cid)[source]

Unregister a callback handler.

Parameters:id (int) – the callback id as returned from one of the register_*_event methods.

DeviceFactory

tellcore.telldus.DeviceFactory(id, lib=None)[source]

Create the correct device instance based on device type and return it.

Returns:a Device or DeviceGroup instance.

Device

class tellcore.telldus.Device(id, lib=None)[source]

A device that can be controlled by Telldus Core.

Can be instantiated directly if the id is known, but using DeviceFactory() is recommended. Otherwise returned from TelldusCore.add_device() or TelldusCore.devices().

name

The name of the device (read/write).

protocol

The protocol used for the device (read/write).

model

The device’s model (read/write).

type

The device type (read only). One of the device type constants from tellcore.constants.

bell()[source]

Send “bell” command to the device.

dim(level)[source]

Dim the device.

Parameters:level (int) – The level to dim to in the range [0, 255].
down()[source]

Send “down” command to the device.

execute()[source]

Send “execute” command to the device.

get_parameter(name)[source]

Get a parameter.

last_sent_command(methods_supported)[source]

Get the last sent (or seen) command.

last_sent_value()[source]

Get the last sent (or seen) value.

learn()[source]

Send “learn” command to the device.

methods(methods_supported)[source]

Query the device for supported methods.

parameters()[source]

Get dict with all set parameters.

remove()[source]

Remove the device from Telldus Core.

set_parameter(name, value)[source]

Set a parameter.

stop()[source]

Send “stop” command to the device.

turn_off()[source]

Turn off the device.

turn_on()[source]

Turn on the device.

up()[source]

Send “up” command to the device.

DeviceGroup

class tellcore.telldus.DeviceGroup(id, lib=None)[source]

Extends Device with methods for managing a group

E.g. when a group is turned on, all devices in that group are turned on.

add_to_group(devices)[source]

Add device(s) to the group.

devices_in_group()[source]

Fetch list of devices in group.

remove_from_group(devices)[source]

Remove device(s) from the group.

Sensor

class tellcore.telldus.Sensor(protocol, model, id, datatypes, lib=None)[source]

Represents a sensor.

Returned from TelldusCore.sensors()

has_value(datatype)[source]

Return True if the sensor supports the given data type.

sensor.has_value(TELLSTICK_TEMPERATURE) is identical to calling sensor.has_temperature().

value(datatype)[source]

Return the SensorValue for the given data type.

sensor.value(TELLSTICK_TEMPERATURE) is identical to calling sensor.temperature().

SensorValue

class tellcore.telldus.SensorValue(datatype, value, timestamp)[source]

Represents a single sensor value.

Returned from Sensor.value().

datatype

One of the sensor value type constants from tellcore.constants.

value

The sensor value.

timestamp

The time the sensor value was registered (in seconds since epoch).

Controller

class tellcore.telldus.Controller(id, type, lib=None)[source]

Represents a Telldus controller.

Returned from TelldusCore.controllers()

id
type

One of the controller type constants from tellcore.constants.

QueuedCallbackDispatcher

class tellcore.telldus.QueuedCallbackDispatcher[source]

The default callback dispatcher used by TelldusCore.

Queues callbacks that arrive from Telldus Core. Then calls them in the main thread (or more precise: the thread calling process_callback()) instead of the callback thread used by Telldus Core. This way the application using TelldusCore don’t have to do any thread synchronization. Only make sure process_pending_callbacks() is called regularly.

process_callback(block=True)[source]

Dispatch a single callback in the current thread.

Parameters:block (boolean) – If True, blocks waiting for a callback to come.
Returns:True if a callback was processed; otherwise False.
process_pending_callbacks()[source]

Dispatch all pending callbacks in the current thread.

AsyncioCallbackDispatcher

class tellcore.telldus.AsyncioCallbackDispatcher(loop)[source]

Dispatcher for use with the event loop available in Python 3.4+.

Callbacks will be dispatched on the thread running the event loop. The loop argument should be a BaseEventLoop instance, e.g. the one returned from asyncio.get_event_loop().