lcdproc/docs/netstuff.txt

LCDproc client/server protocol, V0.2
---------------------------------------------

fixme: most of this stuff is described better in
       ./docs/lcdproc-dev/language.docbook so this file should
       probably be removed after extracting the information that is
       not anywhere else; see also ./docs/menustuff.txt (Volker)

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.  
   "widget_add my_screen my_widget string"
 - Now, update the widget whenever your status info changes...
   "widget_set 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


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] [-heartbeat type]
	Initialize a screen, or reset its data.
	Heartbeat types can be:
		on, heart				"Heart" icon
		normal, default				User's choice
		off, none				None
		slash					Rotating slash
	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", "num"  "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

		num		x number_between_0_and_9

		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" for horizontal, "m" for
			marquee style horizontal or "v" for vertical
			scrolling..
			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.


client->server functions
-------------------------
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.


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] [blink] [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 all clients
	    Vis	    Controlled by the currently visible client


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
-------------------------
menuevent #menu #item #action
	Tells the client that a menu item was selected/used/etc...
	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.