Write about the client language.

docs/pictogram-spec.rst

@@ -15,7 +15,7 @@ In addition to alphanumeric characters represented by segments or pixels,
 LCD/VFD displays are often capable to show additional pictograms, mostly
 arranged around the alphanumeric display part.
 
-These pictograms can be switched on or off, or by changing their appearance
+These pictograms can be switched on or off, or can change their appearance
 as seen for volume settings.
 
 LCDproc comes with icons that are integrated into the alphanumeric display
@@ -27,7 +27,7 @@ application which wants to make use of these pictograms need to know the
 exact type of display driver used and how that drivers handles values to the
 output() function.
 
-This document aims to specify client language and driver API extensions
+This document aims to specify client language and driver API extensions to
 address pictograms in a manner not specific to certain drivers.
 
 .. note::
@@ -40,7 +40,87 @@ address pictograms in a manner not specific to certain drivers.
 Client language
 ===============
 
-This section should talk about the client language.
+The LCDproc client language will be extended with two new functions that can
+be called by a client.
+
+pictogram_list
+--------------
+
+.. code::
+
+   pictogram_list
+
+If this function is called the server will respond with a list of supported
+pictograms.
+
+Clients are required to call this command first to retrieve the list of
+supported pictograms. If the server does not support the pictogram feature,
+it will respond with "huh? unknown command". Clients must not use
+pictogram_set then.
+
+If the server does support pictograms, it will respond with a list of
+pictograms that are currently understood by at least one driver.
+
+This means the list changes accordingly to the loaded drivers and may even
+be empty if no loaded driver uses pictograms!
+
+The response will look like:
+
+.. code::
+
+   pictograms [name:type[:group_id:group_type]]*
+
+List entries are separated by a space character. Each list entry does consist
+of 2 or 4 fields, separated by colon:
+
+Name:
+  The name by which the pictogram is known to the server. It is an US-ASCII
+  string not containing any spaces.
+Type:
+  The type of the pictogram. This will be the string 'bool' for boolean-type
+  or 'num' for numeric-type pictograms.
+Group_id:
+  This optional part contains a group identifier. The group_id is a number
+  in the range 1-(2^32-1). It is used by the driver to inform the client
+  that certain pictograms have a relation.
+Group_type:
+  The group_type must be present if a group_id is set. It describes how
+  pictograms in the same group behave. It will be either the string 'alt'
+  (alternate) for groups in which only one pictogram can be active at any
+  time or 'mul' (multiple) for groups which can have several pictograms
+  active at the same time.
+
+Client shall process the strings case-insensitive.
+
+
+pictogram_set
+-------------
+
+.. code::
+
+   pictogram_set pictogram_name:value
+
+By calling this command a single pictogram is changed. The pictogram is
+referenced by its name and a value, according to the given type. The reserved
+name 'all' can be used to turn off all pictograms at the same time.
+
+.. note:: It has not yet been defined if 'all' can be used to turn on all
+   pictograms at the same time.
+
+For boolean-type pictograms the following values are recognized:
+
+* String 'on' (case-insensitive) or value 1:
+
+  This will turn the pictogram on.
+
+* String 'off' (case-insensitive) or value 0:
+
+  This will turn the pictogram off.
+
+.. note:: Strings are to be used without the quotes.
+
+For numeric-type pictograms value is a number between 0-1000 (inclusive).
+The value 0 shall turn the pictogram off.
 
 
 Driver API
@@ -59,15 +139,13 @@ and the second parameter will be its value. The function will return 0
 (zero) if the pictogram is understood by the driver and -1 (minus one) if it
 is not supported.
 
-.. note::
+There will be no alternative implementation in LCDd core if a driver does
-
-   Their will be no alternative implementation in LCDd core if a driver does
 not understand a pictogram (like it is done for icons).
 
-   This function will never be called with multiple pictogram IDs combined
+This function will never be called with multiple pictogram IDs combined into
-   into one. It will be called for each pictogram to be set / cleared. If a
+one. It will be called for each pictogram to be set / cleared. If a driver
-   driver wishes to reduce communication with the hardware it may implement
+wishes to reduce communication with the hardware it may implement some kind
-   some kind of cache and write the changes on a call to flush().
+of cache and write the changes on a call to flush().
 
 The pictogram ID is defined in the file called lcd_pictograms.h as an
 enumerated type. It will have a symbolic name prefixed with [Definition:
@@ -103,9 +181,6 @@ shall be turned off or on.
    * Drivers may define their local set of pictogram ID and assorted client
      language names.
 
-   * Pictograms may be implemented as widgets. In this case LCDd core will
-     keep track of its value.
-
 
 Internal implementation
 =======================