LCDproc client/server protocol --------------------------------------------- QUICKSTART ---------- - Open a socket to the LCDproc port (usually 13666). - say "hello" - the server will notify you of a good connection, and some info on the type of display available. - Identify yourself. "client_set name some_sort_of_name" - Add a new screen. "screen_add my_screen" - Put a widget on the screen. "screen_add_widget my_screen my_widget string" - Now, update the widget whenever your status info changes... "screen_set_widget my_screen my_widget 1 1 Booger!" - When you're done, just close the socket. - You probably want to read on for more information, once you've gotten the LCDproc server to display something. :) DETAILS ------- There are two parts to the spec: A language for client/server to interact with. A protocol guiding interactions. =================== The protocol ================================== The protocol is context-free. So, no commands require responses; and responses are simply commands. The client may send updated info at any time, and the server decides whether to display it. An ideal communication may flow like this: client->server server->client ------------------ ------------------- (idle) (nothing) (idle) "I'm listening" new stats... (nothing; displays updated stats) new stats... (nothing...) new stats... (nothing...) new stats... "Okay, be quiet" (idle) (nothing; displays new screen) ... ... (idle) "Your slider moved up" Set slider value: 43 (nothing; displays updated slider) (idle) (nothing) ... ... But the client could safely continue to send new stats, knowing that the server isn't listening and won't display it. Also, the client could ignore the slider change, and the slider onscreen simply wouldn't move. =================== The syntax ================================== The language is ascii-based, so a human can telnet to a port and talk to the server. This helps with development and debugging. With that in mind, a commandline-like syntax seems good: function arg1 arg2 arg3 ... The syntax dictates that the first word is a function name, and the rest of the line is passed to that function as an argument. String-type arguments should always come last. So, for example: set_label 23 3 2 Hey, booger. What's up? The first argument is a label id number, the 2nd and 3rd are x,y coordinates onscreen, and the rest of the line is a string. =================== The command set ================================== The naming convention dictates that function names are lower-case, with underscores ("_"'s) between words. The naming convention also requires that function-name words go in descending order. So, "screen_set_priority" would be okay, but "set_screen_priority" would not. Id's are strings. (the "#id" things) In general, we're trying to keep the command set small. Especially the server->client functions, so that clients won't have to handle a lot of different types of input. Now, the function list: client->server functions ------------------------- hello Client init. You must send this before the server will pay any attention to you. You'll get some info about the server in return... (a "connect" string) client_set [name #id] Set client's name and other info client_add_key #id Tells the server the client can handle keypresses of type #id. #id is probably just "A", "B", and so on... All keypresses are disabled by default, so you'll have to tell the server which ones you want to accept... client_del_key #id Tells the server to never send that keypress. All keypresses are disabled by default. screen_add #id Add a new screen screen_del #id Remove a screen screen_set #id [priority integer] [name "my_name"] [duration integer] [wid width] [hgt height] Initialize a screen, or reset its data. Priority values are as follows: 0 You feel like getting kicked off the server, don't you? 1 The world is about to explode 16 Emergency priority 32 Very high priority (important) 64 High priority (normal) 128 Normal (recommended) 192 Low priority (normal) 224 Very low priority (very unimportant) 240 Boring as hell 255 This screen won't show up very much even if there are no other screens queued... An example of using priorities is as follows. Imagine you're making an mp3 player for LCDproc. When the song changes, it's nice to display the new name immediately. So, you could set your screen's priority to 64, wait for the server to display (or ignore) your screen, then set the screen back to 128. This would cause the mp3 screen to show up as soon as the one onscreen was finished, then return to normal priority afterward. Or, let's say your client monitors the health of hospital patients. If one of the patients has a heart attack, you could set the screen priority to 16 (emergency), and it would be displayed immediately. It wouldn't even wait for the previous screen to finish. ... And it would stay there most of the time until the user did something about it. A priority of 1 would stay onscreen permanently, with flashing lights and other visual cues if possible. ... Please *don't* use this priority. :) The duration can be either a positive number, or -1. A positive number indicates how many display frames the screen should last for. A 0 or -1 means that the server should use "auto" duration, which is probably a good idea. This will be whatever the user wants. It defaults to 4 seconds (32 frames), or will be calculated for things such as scrollers. widget_add #screen #id type [-in #id] Add something onscreen Widget types can be any of the following: "string", "hbar", "vbar", "title", "icon", "scroller", "frame", ... more later? Widgets are drawn in the order you create them. You can put a widget inside a frame by adding "-in #id", where #id is the name of a frame. widget_del #screen #id Kill something onscreen widget_set #screen #id data Set (reset) widget's data Note that the "string" type should be used for frame buffers. Strings should not be bigger than the screen. The widgets take these arguments for data: string x y text hbar x y length_in_pixels vbar x y length_in_pixels icon x y binary_data title text scroller left top right bottom direction speed text A scroller is a string which scrolls. This is useful for things such as the disk usage screen, which may be very tall. The speed is how many display frames to delay between scrolling. Each display frame is 1/8th of a second, by default. Direction must be "h" or "v". Positive speeds indicate frames per movement. Negative speeds indicate movements per frame. frame left top right bottom wid hgt dir speed Frames occupy the area (left, top)-(right,bottom) onscreen, and the inside area is wid x hgt. The inside may be bigger than the actual size, so that the frame will scroll. server->client functions ------------------------- connect args Verifies connection; gives info about the LCD, etc... bye Notifies the client of a server shutdown. huh? [info] Notifies the client of a request error. listen [#screen [#widget [#widgets...]]] Notifies client that "server is listening for data". ignore [#screen [#widget [#widgets...]]] Tells the client "shut up". key #id Sends a keypress to the client. --- Not implemented yet --- The functions below are planned but not completed. client->server functions ------------------------- menu_add #id Add a new menu. menu_del #id Get rid of a menu. menu_set [top] [name my_menu_name] if (top) Gets added to "Client Menus". else Client must insert it into its own menu heirarchy. menu_item_add #menu #id Add a new, blank menu item. menu_item_del #menu #id Delete a menu item. menu_item_set #menu #id type [value] text (re)Set the menu item's data. If type is "checkbox" or "slider" or "menu", [value] should contain appropriate info. (like true, 43, or #menuid) backlight [on] [off] [flash] [toggle] Requests that the backlight be toggled... The backlight command will likely be ignored, but users can enable it if desired. The LCDproc server has [will have] several backlight modes: On Stays on all the time Off Stays off all the time Load Turns off when the load average is low Shell? Controlled by a user-supplied shell script Open Can be controlled by clients driver_add #id? type args Start up a new output driver. Nice if you want to check on your machine remotely with the curses driver. driver_del #id? (or type) Stop a running output driver. Good for reclaiming your joystick when you want to play games... server->client functions ------------------------- menu #menu #item #action Tells the client that a menu item was selected/used/etc... The action can be "click", "up", or "down". The client should handle this according to what type of menu item has been activated, and should probably send the server a new item definition if the item was a checkbox or slider.