diff --git a/docs/tellstick-protocol.dox b/docs/tellstick-protocol.dox new file mode 100644 index 00000000..99ec0f7f --- /dev/null +++ b/docs/tellstick-protocol.dox @@ -0,0 +1,126 @@ +/** + * @page TellStick TellStick protocol + * + * \section Introduction + * + * Telldus TellStick protocol looks like:
+ * [prefix[prefix parameters]][command][parameter 1]..[parameter n]['+'] + * + * Each value in [ and ] is representing one byte. + * + * Command is one ascii character. Not all commands have parameters which + * makes it optional. Prefix is always optional. + * Note: Due to memory limitations, the parameters is limited in length to 79 + * bytes. + * + * An example command to turn on a ArcTech codeswitch A1 may look like: + * S$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$k$kk$$kk$$kk$$}+ + * + * TellStick returns to a known command like this:
+ * ['+'][command][parameters][13][10] + * + * [13] and [10] are the ascii characters 10 and 13. + * + * An example to query a TellStick on its firmware version:
+ * Command:
+ * V+
+ * Response:
+ * +V2
+ * The TellStick in the example has the firmware version 2. + * + * \section Commands + * + * \subsection sec_bootloader B - Bootloader + * This command makes the TellStick go into the bootloader. + * Not all devices supports this. + * + * \subsection sec_send S - Send command + * This command tells TellStick to send a command. The parameters to this + * command is the data-packet to send. + * + * Each of the characters in the parameters makes the antenna alternate + * high/low/high etc. The time before the alternation is 10 us timer the ASCII + * value. For example, $ has the ascii-value 36 and k has 107. The command: + * ['S']['$']['k']['$']['k']['$']['+'] makes the following wavepattern on the antenna: + * 
+ *  _____                 _____                 _____
+ * |     |               |     |               |     |
+ * |     |               |     |               |     |
+ * |     |_______________|     |_______________|     |
+ *
+ * |<===>|<=============>|<===>|<=============>|<===>|
+ *  360us      1070us     360us      1070us     360us
+ *
+ * + * + * \subsection sec_send_extended T - Send command, extended + * + * The extended command was developed to overcome the limitations och the + * length of the data to 79 bytes. + * The idea is to have four fixed times on the pulses so the information about + * what to send only needs 2 bits instead of 8 in the command S + * + * The parameters to the command is:
+ * [t0][t1][t2][t3][length][d1]..[dn] + * + * t0-t3: Times 1 to 4. The times are in the same form as S. + * Each time is multiplied with the factor of 10. + * + * length: How many pulses to send. Since the data sent to TellStick + * is sent in groups of four pulses (one byte) and the actual data might not + * have pulses even divided with four. + * + * d1..dn: Each byte is the description for four pulses. + * + * Example:
+ * ['T'][127][255][24][1][6][98][80]['+'] + * + * T: Send extended. + * + * 127,255,24,1: Times 1270 us, 2550 us, 24 us and 10 us + * + * 6: Six pulses to send. + * + * 98,80: The data in binary is 10011000,10000000. If + * we group it in groups of two bits we get 10 01 10 00 10 00 00 00. + * Since the length is only six pulses the last two pulses is discarded, giving: + * 10 01 10 00 10 00. + * + * Matching those bits to the times gives the following times:
+ * 10 => 2 => t2 => 240 us
+ * 01 => 1 => t1 => 2550 us
+ * 10 => 2 => t2 => 240 us
+ * 00 => 0 => t0 => 1270 us
+ * 10 => 2 => t2 => 240 us
+ * 00 => 0 => t0 => 1270 us
+ * + * This is equal if you used S:
+ * ['S'][24][255][24][127][24][127]['+'] + * + * \subsection sec_version V - Firmware version + * This command queries the TellStick on its firmware version. + * + * Example:
+ * » V+
+ * « +V2
+ * \section Prefixes + * The prefixes are commands that can be prepended before some of the commands + * and cannot be used standalone. They are used to alter the behavior of the + * command. + * + * \subsection sec_debug D - Debug + * \subsection sec_pause P - Pause + * The pause is how low TellStick will wait between two packets. The value is + * in ms. + * + * Example, % has the ascii-value 37. The following packet will be sent with a + * pause of 37 ms between the packets:
+ * » P\%S$k$k$+ + * + * \subsection sec_repeat R - Repeat + * This tells TellStick how many times to send the packet. + * + * Example, ! has the ascii-value 33. The following packet will be sent 33 + * times:
+ * » R!S$k$k$+ + */