TellStick Net protocol

Introduction

TellStick Net will eventually support local access through the LAN. This is unsupported by Telldus Technologies but can be useful in some cases. For instance in mobile devices or when the internet is not available. Using TellStick Net through Telldus Live! is still the prefered and supported method.

This interface is still under development and is not ready for production.

Auto discovery

The TellStick Net can be auto discovered on the LAN using UDP broadcast. Sending a package to the broadcast address 255.255.255.255 port 30303 will be responded by any TellStick Net on the network. The packet should only contain the single character 'D' (ascii number 68).

The response from the device will be sent back to the same host and port as the originated packet. So any dynamically port can be assigned by the host implementing the auto discovery. The returning packet is constructed in the following way: product:mac address:activation code:firmware

Example:
TellStickNet:ABCDEFGHIJKL:ABDCEFGHIJ:2
Product: TellStick Net (TSNET)
Mac address: AB:CD:EF:GH:IJ:KL
Code for activation: ABCDEFGHIJ
Firmware version: 2

Use the source ip-address to determine the address to the device.

Message format

The message format used to communicate with TellStick Net is designed to be easily parsed but still be flexible. It can be converted to and from json without losing information.

There exists four datatypes; string, integer, list and dictionary:

  • Strings are length-prefixed base sixteen (upper case) followed by a colon and the string. For example 6:FooBar corresponds to 'FooBar'.
  • Integers are represented by an 'i' followed by the number in base 16 followed by an 's'. For example i3s corresponds to 3 and i-3s corresponds to -3. Integers have no size limitation. i-0s is invalid. All encodings with a leading zero, such as i03s, are invalid, other than i0s, which of course corresponds to 0.
  • Lists are encoded as an 'l' followed by their elements (also encoded) followed by an 's'. For example l3:foo3:bars corresponds to ['foo', 'bar'].
  • Dictionaries are encoded as a 'h' followed by a list of alternating keys and their corresponding values followed by an 's'. For example, h3:foo3:bar5:hello5:worlds corresponds to {'foo': 'bar', 'hello': 'world'} and h3:fool3:bar3:bazss corresponds to {'foo': ['bar', 'baz']}. Keys must be strings.

Communication with TellStick Net is done over UDP on port 42314. The first string sent contains the command to execute. The following python example sends a disconnection command to a TellStick Net. This will reboot the device.

 from socket import *
 UDPSock = socket(AF_INET,SOCK_DGRAM)
 UDPSock.sendto("A:disconnect", ("192.168.0.155",42314))

Send command

For readability the examples will be displayed in json format in this documentation. They must be encoded using the TellStick Net message format before sending to an actual TellStick Net.

Sending RF-data uses the same encoding as TellStick S - Send command with the difference that prefixes should be sent as a parameter and not in the RF-data.

The parameters are sent encoded in a dictionary, with the RF-data in the key 'S'. Example sending Arctech Code switch A1 ON:
{'S': '$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$kk$$kk$$kk$$k'} The string sent will be encoded like this:
4:sendh1:S32:$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$kk$$kk$$k$k$ks

The same example as above but with a 20 ms pause between the 15 packages:
{'S': '$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$kk$$kk$$kk$$k', 'P': 20, 'R': 15}

The command "Send extended" (T) is not implemented since a TellStick Net can handle packages over 255 pulses.