94 lines
4.1 KiB
Text
94 lines
4.1 KiB
Text
/**
|
|
* @page TellStickNet TellStick Net protocol
|
|
*
|
|
* \section 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.
|
|
*
|
|
* <em>This interface is still under development and is not ready for
|
|
* production.</em>
|
|
*
|
|
* \section autodiscovery 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:
|
|
* <tt>product:mac address:activation code:firmware</tt>
|
|
*
|
|
* Example:<br>
|
|
* <tt>TellStickNet:ABCDEFGHIJKL:ABDCEFGHIJ:2</tt><br>
|
|
* Product: <tt>TellStick Net (TSNET)</tt><br>
|
|
* Mac address: <tt>AB:CD:EF:GH:IJ:KL</tt><br>
|
|
* Code for activation: <tt>ABCDEFGHIJ</tt><br>
|
|
* Firmware version: <tt>2</tt>
|
|
*
|
|
* Use the source ip-address to determine the address to the device.
|
|
*
|
|
* \section messageformat 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.
|
|
* \code
|
|
* from socket import *
|
|
* UDPSock = socket(AF_INET,SOCK_DGRAM)
|
|
* UDPSock.sendto("A:disconnect", ("192.168.0.155",42314))
|
|
* \endcode
|
|
* \section tellstick_net_command_send 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 \ref sec_send 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:<br>
|
|
* <tt>{'S': '$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$kk$$kk$$kk$$k'}</tt>
|
|
* The string sent will be encoded like this:<br>
|
|
* <tt>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</tt>
|
|
*
|
|
* The same example as above but with a 20 ms pause between the 15 packages:<br>
|
|
* <tt>{'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}</tt>
|
|
*
|
|
* The command \ref sec_send_extended "\"Send extended\" (T)" is not implemented
|
|
* since a TellStick Net can handle packages over 255 pulses.
|
|
*/
|