LED SETTTING/QUERYING PROTOCOL ============================== $Id: led-protocol.text,v 1.10 2002/06/13 10:17:55 ian Exp $ Client behaviour ================ Client must first do an allocation request for all wanted LEDs ie a SET request with ALLOCATE special code for each LED. Reply will (hopefully) have cookie for each LED which can be used in SET requests with Value records. If client gets unexpected BADCOOKIE reply, it means another client is fighting it for the LED(s). Either: - This is Not Supposed To Happen and the client should scream, die, etc. - This might be OK (eg a command-line set-to-these-values program) in which case the client *must* wait a random time before issuing a SET request with ALLOCATE special code. The mean time must be >= 50ms * 2^(number of retries). Overall packet format ===================== All packets, data, etc., in most significant byte first, most significant bit shown first in each bit. UDP packet 7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ | VERSION | 0 for this version of the protocol +--+--+--+--+--+--+--+--+ |RP| OPCODE | +--+--+--+--+--+--+--+--+ | SECURITY MECH | 1 for this version of the protocol +--+--+--+--+--+--+--+--+ | | +- -+ Should be invented randomly by client | REQUESTOR ID | Copied into replies by server +- -+ | | +- -+ | | +--+--+--+--+--+--+--+--+ | | +- PASSWORD -+ Zero is default in requests for client | | +-(if SECURITY MECH!=1 -+ Server should allow configured list | this might be | of valid passwords (maybe qualified +- anything, even of -+ by LEDs, networks, etc), by default | a different length) | allow read-only access with zero pw +--+--+--+--+--+--+--+--+ | ... | Body, depends on opcode RP==1 indicates packet is a Reply. Opcode space for replies and requests are different. Servers should ignore all replies and send only replies in response to requests; clients should ignore all requests and send only requests. In replies the password field is reused: | | +--+--+--+--+--+--+--+--+ Changes when the server restarts | | (invalidating existing cookies and +- SERVER INSTANCE ID -+ perhaps forgetting LED states). | | May be random, start time, or whatever. +-----------------------+ | MAX VERSION SUPPORTED | Currently, 0. Client may ignore. +-----------------------+ | RESERVED | Server sends 0. Client must ignore. +--+--+--+--+--+--+--+--+ | | Opcodes and body formats ======================== Request 1 - SET (allocate or set LEDs) Each server supports n LEDs 0..n-1 Body is table of LED records (see below) for LEDs 0..i <= i If header OK, and security passes, each LED record is processed in turn and separately into the VALUES reply (unless error happens). Reply 1 - VALUES (allocations and LED values) Body is table of LED records corresponding to LED records in SET request. Reply 2 - ERROR Body: +--+--+--+--+--+--+--+--+ | CODE | +--+--+--+--+--+--+--+--+ | OFFSET | +--+--+--+--+--+--+--+--+ | ... | Extra err info, ignore if present when not expected Sent by server in response to any request that didn't work. If an error occurs, request may have been partially done ! Body may _always_ be truncated, even code may be truncated ! (Truncating code is rather unhelpful, so not recommended.) If the message was truncated, OFFSET may point to the missing byte after the end of the reply packet. Codes (none currently have defined extra error info): 0 service has failed 1 wrong VERSION 2 unknown OPCODE 3 unknown SECURITY MECH 4 access denied 5 message too long (includes too many LEDs in SET request) 6 unknown value/settings special code in LED record 7 malformed message (known to be wrong - ie too short, missing 2nd byte of LED record, etc.) 8 flashing not supported 9 monochrome only supported but green or blue requested 10 bi-colour only supported but blue requested 11 nonzero cookie where zero cookie expected LED Records =========== Found in SET requests and VALUES replies. For each LED, we have a two-byte record like one of these: Special request: +--+--+--+--+--+--+--+--+ | 1 1 | SPECIAL CODE | +--+--+--+--+--+--+--+--+ | COOKIE | +--+--+--+--+--+--+--+--+ Steady colour/value: +--+--+--+--+--+--+--+--+ | 0 0 | ANY | B G R| +--+--+--+--+--+--+--+--+ | COOKIE | +--+--+--+--+--+--+--+--+ Flashing: +--+--+--+--+--+--+--+--+ | DUTY| MARK | SPACE | DUTY == 01 or 10 +--+--+--+--+--+--+--+--+ | COOKIE | +--+--+--+--+--+--+--+--+ Requests are as follows: SPECIAL CODE 0 ALLOCATE In a request: Cookie must be 0 (otherwise error 11) Server allocates new cookie (eg by incrementing current value) and makes ALLOCATE reply record In a reply: Is reply to ALLOCATE, cookie is new valid cookie SPECIAL CODE 1 NOOP In a request: Cookie must be 0 Nothing is done to the relevant LED, reply is either - Value with COOKIE==0 if client is allowed to see value - NOOP if client is not allowed to see value In a reply: Cookie must be 0 SPECIAL CODE 2 BADCOOKIE Not allowed in requests In a reply: Reply to a value setting Indiciates that cookie in request was wrong, see Cookies below Cookie must be 0 Value (steady/flashing): In a request: Cookie must be equal to currently valid cookie as returned in most recent ALLOCATE (to any client). If cookie is wrong, reply is BADCOOKIE. Otherwise reply is Value. In a reply: Cookie is equal to that in reply. Value is that currently being displayed on LED (in case of valid Value record in SET request, this will be semantically equivalent to request). See below for interpretation of DUTY, MARK/SPACE, R/G/B, etc. Value records, rendering, etc. ============================== The three bits R, G, B in LED values have meanings defined by the server. The person configuring the client should be allowed to specify them using the syntax below, and may be assumed to know what the meanings of these bits are. R, G, B conventionally refer to Red, Green, Blue of 3-junction LEDs that can do white. Monochrome displays must always implement only the least significant bit (R, red), regardless of actual colour. Bi-colour displays are generally only red/green/yellow and should use only the R and G bits. LEDs supporting variable brightness may use the three bits as an unsigned brightness number (B=4, G=2, R=1) regardless of the LED's colour. Unused bits must be set to 0 in requests and replies. The value 0 must always be supported and means `completely off'. Flashing -------- When DUTY is nonzero, the LED flashes between the colours or values implied by the RGB values for MARK and SPACE. DUTY==00 is steady colour SPACE. MARK is ignored. DUTY==10 means 50% duty cycle: 50% MARK, 50% SPACE. DUTY==01 means approximately 25% duty cycle - mainly SPACE, with short bursts of MARK. DUTY==11 is reserved for SPECIAL CODE and not used for values. Suggested waveforms: ..| |.. mark DUTY==00 | : : : : : : : | ..|===============================|.. space ..| ========= |.. mark DUTY==01 | : : | : | : : | ..|============ ============|.. space ..| ================= |.. mark DUTY==10 | : : : : : : : | ..|======== ========|.. space ^ ^ t=0 t = 1 cycle Configuration of clients ======================== Clients should configure each `set' of LEDs in two stages: * LED group, configured textually (see grammar for LED-Group below) * Values for LEDs in each group, specified either - as a sequence of Value bytes, as above - as a textual list of values (grammar for Value-List, below) LED-Group := Server-Group [ "/" LED-Group ] Server-Group := Hostname ":" Port ":" Number-List Number-List := Number-Range [ "," Number-List ] Number-Range := Number [ "-" Number ] # start-end range, where end!=start, but end where is matched according to fnmatch (with flags==0) against the specified Server-Group (see above) and consists of the right number (8 for security mechanism 1) hex digits. These hex digits are in network byte order, top nybble first. Any whitespace may be used to separate the two fields. Leading and trailing whitespace are ignored. Empty lines, or lines containing only whitespace, or whose first whitespace character is #, are ignored. Lines whose first whitespace character is ! are reserved for future extensions, and should be ignored. Copyright and legal information =============================== /* * This file is part of ledclient, tools for controlling LEDs remotely. * ledclient is Copyright 2002 Ian Jackson. * * ledclient is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published * by the Free Software Foundation; either version 2 of the License, * or (at your option) any later version. * * This program and documentation is distributed in the hope that it * will be useful, but without any warranty; without even the implied * warranty of merchantability or fitness for a particular * purpose. See the GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with ledclient; if not, write to the Free Software * Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, * USA, or email grond-maint@chiark.greenend.org.uk. */ /* * This file is dual-licensed, as an alternative to distribution under the * GPL v2 or later as above: * * This file is Copyright 2002 Ian Jackson. * * You may redistribute and use this file in source and binary forms, * with or without modification, provided that the following * conditions are met: * * 1. Redistributions of source code must retain this copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above * copyright notice, this list of conditions and the following * disclaimer in the documentation and/or other materials provided * with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */