somfy_rts Documentation

Introduction

The somfy_rts package has been developed to provide an API for communication with the Somfy RS485 RTS Transmitter(s) to control devices such as blinds, shutters, awnings or lights. Multiple transmitters may be connected on a single RS485 multi-drop network.

Connectivity is either via a TCP socket or a serial port.

API Reference

class somfy_rts.RTSProtocol(connection='socket')

Somfy RS485 RTS Transmitter protocol class

This is the class for communication with a multi-drop network of Somfy RS485 RTS Transmitters.

General usage flow:

  • Use enable_logger() to enable logging

  • Use connect() to connect to a RS485 network

  • Use get_nodes() to obtain a dictionary of all RTS Transmitter nodes on the RS485 network

  • Use control_position() to control the end device

  • Use disconnect() to disconnect from the RS485 network

Class Constants

UP

Constant for the UP command

DOWN

Constant for the DOWN command

STOP

Constant for the STOP command

MY

Constant for the MY command
__init__(connection='socket')

Class constructor.

Obtains connection type and initialises private attributes.

Parameters

connection (str) – Type of connection to use. Must be one of “socket” or “serial”.

Raises

ValueError – If connection is not one of “socket” or “serial”.

connect(host, port=4660, keepalive=60)

Connect to a RTS Transmitter network

Makes a TCP connection to a RTS Transmitter network and discovers all nodes on the network.

Parameters

  • host – the hostname or IP address.

  • port (int) – the network port. Defaults to 4660.

  • keepalive (int) – Maximum period in seconds between communications with the RTS Transmitter. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the RTS Transmitter.

Returns

True for success, False for failure.

Return type

bool

Raises

ValueError – if any of the parameters are invalid.

control_position(node_addr, command, channel=<class 'int'>)

Issue a control position command.

Parameters

  • node_addr (int) – the node address.

  • command (constant) – the position command. One of UP, DOWN, STOP or MY.

  • channel (int) – the channel to use. Must be in the range 0-15.

Returns

True for success, False for failure.

An explanatory ERROR is logged and a value of False is returned if an invalid parameter is supplied or a protocol error is experienced.

disable_logger()

Disables the logger.

disconnect()

Disconnect from a RTS Transmitter network

enable_logger(logger=None)

Enables a logger.

Enable logging using the standard python logging package (See PEP 282).

Parameters

logger – If logger is specified, then that logging.Logger object will be used, otherwise one will be created automatically.

get_channel_mode(node_addr, channel=<class 'int'>)

Get the mode used for the selected channel.

The mode is returned as a tuple with the followng structure:

  • US/CE mode: 0x00 = CE Mode, 0x01 = US Mode (default)

  • Rolling/Tilting mode: 0x00 = Rolling mode (default), 0x01 = Tilting mode

  • Modulis mode: 0x00 = Normal mode, 0x01 = Modulis mode (default)

Parameters

  • node_addr (int) – The node address for which the information is required.

  • channel (int) – The channel to get the mode for. Must be in the range 0-15.

Returns

The mode used for the selected channel as a tuple.

An explanatory ERROR is logged and a value of None is returned if an invalid node_addr or channel is supplied.

An explanatory ERROR is logged and a value of None is returned if a protocol error is experienced.

get_dct_lock(node_addr)

Get the lock status of the Dry Contacts (DCT) for the node.

Format of tuple is (DCT1, DCT2, DCT3, DCT4, DCT5).

  • A value of 0 indicates Unlocked.

  • A value of 1 indicates Locked.

Parameters

node_addr (int) – The node address for which the information is required.

Returns

Returns the lock status of the Dry Contacts (DCT) for the node as a tuple.

An explanatory ERROR is logged and a value of None is returned if a protocol error is experienced.

Raises

ValueError – If an invalvid node_addr is passed.

get_dim_framecount(node_addr, channel=<class 'int'>)

Returns the number of RTS frames the product should send on a CTRL_DIM order.

Parameters

  • node_addr (int) – The node address for which the information is required.

  • channel (int) – The channel to get the mode for. Must be in the range 0-15.

Returns

Returns the number of RTS frames the product should send on a CTRL_DIM order as an int. The minimum value is 4, maximum is 255, default is 5.

An explanatory ERROR is logged and a value of None is returned if an invalid node_addr or channel is supplied.

An explanatory ERROR is logged and a value of None is returned if a protocol error is experienced.

get_network_error_stat(node_addr)

Returns the error counter of the stack.

Encoding structure of the data frame is unknown due to inability to find documentation.

Parameters

node_addr (int) – The node address for which the information is required.

Returns

The data returned by the RTS Transmitter. Format and encoding structure is unknown.

An explanatory ERROR is logged and value of None returned if a protocol error is experienced.

Raises

ValueError – If invalid node_addr is passed

get_network_stat(node_addr)

Returns the network communication diagnostics.

Encoding structure of the data frame is unknown due to inability to find appropriate documentation.

Parameters

node_addr (int) – The node address for which the information is required.

Returns

The data returned by the RTS Transmitter. Format and encoding structure is unknown.

An explanatory ERROR is logged and value of None returned if a protocol error is experienced.

Raises

ValueError – If invalid node_addr is passed

get_node_app_version(node_addr)

Returns a tuple containing the application software information.

The tuple structure is:

  • App Reference: 24-bit number

  • App Index Letter: 8-bit ASCII character

  • App Index Number: 8-bit number

  • App Profile: 8-bit number

Parameters

node_addr (int) – The node address for which the information is required.

Returns

A tuple containing the application software information.

An explanatory ERROR is logged and a value of None is returned if a protocol error is experienced.

Raises

ValueError – If invalid node_addr is passed

get_node_label(node_addr)

Get the node label

Parameters

node_addr – the node address as an int for which the label is sought.

Returns

The node label as a string.

An explanatory ERROR will be logged an a value of None returned if a protocol error is experienced.

get_node_serial_number(node_addr)

Get the serial number for the node.

The serial number is a 12-byte ASCII string. The structure is:

  • Product NodeID: Six characters in hexadecimal representation

  • Manufacturer ID: Two letters

  • Year: Two digits

  • Week: Julian Week

Parameters

node_addr (int) – The node address for which the information is required.

Returns

The serial number as a 12-byte ASCII string.

An explanatory ERROR is logged and a value of None is returned if a protocol error is experienced.

Raises

ValueError – If invalid node_addr is passed

get_node_stack_version(node_addr)

Get the node stack version information.

The node stack information is returned as a tuple with the follwing structure:

  • Stack Reference: 24-bit number

  • Stack Index Letter: 8-bit ASCII character

  • Stack Index Number: 8-bit number

  • Stack Standard: 8-bit number

Parameters

node_addr (int) – The node address for which the information is required.

Returns

The protocol software information as a tuple.

An explanatory ERROR is logged and a value of None is returned if a protocol error is experienced.

Raises

ValueError – If invalid node_addr is passed

get_nodes()

Returns a dictionary of all RTS nodes on the RS485 Network

They will be discovered if not already known.

Returns

A dict containing node_address as the key, and node_label as the value.

get_tilt_framecount(node_addr, channel=<class 'int'>)

Get the number of RTS frames the product should send on a CTRL_TILT order.

The information is returned as a tuple consisting of two values:

  • US mode: The number of frames to send for US mode. Range is 4-255. Default is 5.

  • CE mode: The number of frames to send for CE mode. Range is 2-13. Default is 2.

Parameters

  • node_addr (int) – The node address for which the information is required.

  • channel (int) – The channel to get the mode for. Must be in the range 0-15.

Returns

Returns the number of RTS frames the product should send on a CTRL_TILT order as a tuple.

An explanatory ERROR is logged and a value of None is returned if an invalid node_addr or channel is supplied.

An explanatory ERROR is logged and a value of None is returned if a protocol error is experienced.

loop_misc()

Handles general ongoing housekeeping duties for the RTS connections.

At this stage, the only housekeeping task is to ping() the nodes of the socket at a time period no less than the keepalive period specified in the connect() call.

Returns

Always returns None.

ping()

Ping each node on the RS485 network.

Returns

Always returns True.

set_channel(node_addr, channel=<class 'int'>)

Issue a set channel command.

Parameters

  • node_addr (int) – the node address.

  • channel (int) – the channel to use. Must be in the range 0-15.

Returns

True for success, False for failure.

An explanatory ERROR is logged and a value of False is returned if an invalid parameter is supplied or a protocol error is experienced.

set_node_label(node_addr, label)

Set the user-defined text label for the node.

Parameters

  • node_addr (int) – Node address to set the label for.

  • label (str) – The new label to be applied. Must be alphanumeric ASCII with a maximum length of 16 characters.

Returns

True for success and False for failure.

An ERROR will be logged and False returned if an invalid node_addr or label is supplied.

An explanatory ERROR will be logged and False returned if the label is not able to be set.

set_open_prog(node_addr, channel=<class 'int'>)

Send RTS Prog frames to a receiver.

Parameters

  • node_addr (int) – the node address.

  • channel (int) – the channel to use. Must be in the range 0-15.

Returns

True for success, False for failure.

An explanatory ERROR is logged and a value of False is returned if an invalid parameter is supplied or a protocol error is experienced.

socket()

Return the socket for this client.

Developer documentation

The package has currently only been tested and used for the control of blinds using a socket connection. Feel free to test it for other configurations and provide feedback to the author. Bugs can be reported here.

To obtain the full code, you can clone the git repository:

git clone https://github.com/bradkeifer/somfy-rts

Indices and tables