This Plugin is not part of the current lcd4linux. This wiki entry was created for discussion about a plugin prototype.

Lacking the privilege to modify/delete incorrect attachments it's strongly recommended to only make use of attachments which are linked from the text.

<code>
#!html
<h1 style="text-align: left; color: red">
This Plugin is not part of the current lcd4linux. This wiki entry was created for discussion about a plugin prototype.
<br><br>
Lacking the privilege to modify/delete incorrect attachments it's strongly recommended to <u>only make use of attachments which are linked from the text.<u>
<br><br>
</h1>
</code>


====== Plugin Control ======
\\\

====== 1. Description ======
The Plugin Control makes it possible to use inputs (buttons, FIFOs, ...) and outputs (LED, ...) of different resources (usb mouse, serial port, ...) within LCD4Linux.\\\
External executables (controllers) are started to control these resources.  
\\\

\\\

====== 2. Configuration ======
===== 2.1. Basic structure
=====

The structure in the config-file looks like this example which configures a usb mouse controller to navigate within a [[:plugin_menu|menu]]:

<code>
Plugin Control {

    active 1

    Controller1 {

        name 'usbmouse'

        prog '/usr/bin/ctrl_usbmouse'
        arg1 '-i'
	arg2 '046d:c050'

	Key0 {
	   name 'button_none'
	   #do nothing, this key was only configured to illustrate index range of keys
	}

	Key1 {
	   name 'button_left'
	   action menu::confirm()
	}

	Key2 {
	    name 'button_right'
	    action menu::cancel()
	}

	Key64 {
	    name 'scroll_down'
	    action menu::right()
	}

	Key128 {
	    name 'scroll_up'
	    action menu::left()
	}

	Key255 {
	   name 'button_none2'
	   #do nothing, this key was only configured to illustrate index range of keys
	}

    }


    Controller2 {

        ...
    }
}
</code>


===== 2.2. Section Plugin Control
=====

**Parameters:**

|**active**|Set to 1 to activates plugin, otherwise the plugin won't work and all of its functions return -1. |

**Subsections**
|**Controllers**|see [[:#controller|Subsection Controller]], at least 1 controller has to be set|

===== [[:======#controller]]2.3. Subsection Controller


For each controller with a //prog// attribute the main process will be forked and the child will be replaced (exec) by the executable. So the controller process will run in parallel to LCD4linux. (All of these processes will be terminated when LCD4Linux is closed.) 

Controllers may send bytes to their standard output (stdout) and may read bytes from the standard input (stdin). The standard error (stderr) of the controller will be closed if LCD4Linux isn't running in foreground. 

The Plugin reads the bytes written by the controller. Each byte is interpreted as (virtual) key ( byte 0x00 ==> Key0, byte 0x01 ==> Key1, ..., byte 0xff ==> Key255).
Which byte values (keys) are sent and what a specific value stands for will vary depending on the started executable.

A key event can also be simulated by the functions //control::key(...)// and //control::byte(...)//. So a virtual controller without a //prog// attribute (==> no external process) can be used to set a keypad or timer as controller and take advantage of the plugin functions (e.g. (de)activate, read last key, ...).

The function //control::send(...)// can be used to write bytes to the controllers stdin. Again it's  depending on the started executable if and how these bytes are interpreted. 


**Parameters:**

|**name***|Unique name of the controller. Default 'Controller1' for Controller1, ...|
|**update***|Interval between two checks for bytes to read in milliseconds. Default: 100|
|**anybyte***|Expression that will be evaluated everytime the plugin receives a byte from the controller before evaluation of key action or default action.|
|**default***|Expression that will be evaluated everytime the plugin receives a byte from the controller and no matching key was configured.|
|**prog***|Full path to external program to be started.|
|**arg1..100***|Optional arguments of //prog//|
| |* //optional//|

**Subsections**

|**Keys**|Keys of Controller, index == byte value [[:0..255]], see [[:#key|Subsection Key]]|

===== [[:======#key]]2.4. Subsection Key

**Parameters:**

|**name***|Unique name of the key. Default 'Key1' for Key1, ...|
|**action***|Expression that will be evaluated everytime the plugin receives a matching byte (index == byte value).|
| |* //optional//|

\\\

====== [[:======#functions]]3. Functions =
\\\

All functions return -1 on error (e.g. plugin not active, wrong config, wrong indexes, name not found).
\\\


|**Function**|**args**|**Description**|
|**control::send(** //ctrl*, val// **)**|  2  |Send a byte with value //val// to external process linked to controller //ctrl//|
|**control::key(** //ctrl*, key*// **)**|  2  |Simulates the receiving of a byte with value = key index from the controller //ctrl//|
|**control::byte(** //ctrl*, [[:val]]// **)**|  1-2  |Get last received byte or simulate byte with value //val//|
|**control::active(** //ctrl*, [[:val]]// **)**|  1-2  |Get or set active state of controller //ctrl//. not active == 0 |
|**control::running(** //ctrl*// **)**|  1  |returns 0 if external process isn't running|
| ||* Controllers and keys may be referenced by name or index. e.g. control::active(1) == control::active('usbmouse')|

\\\

====== 4. Controller programs ======

Controller programs can be written in any programming language. Scripts can be used to. The program should write relevant data to stdout or (not xor) read them from stdin. 

===== 4.1. ctrl_usbmouse
=====

The program [[:plugin_control_ctrl_usbmouse|ctrl_usbmouse]] (written in C) identifies a USB mouse (may be a second one) by its id, detaches it from the kernel (=> mouse won't effect other processes) and write its button and mouse wheel events. 

It may be used for a first testing of the plugin (since a USB mouse will often be available) or mods by soldering own buttons on the board of a disassembled mouse.

===== 4.2. ctrl_serial
=====

The program [[:plugin_control_ctrl_serial|ctrl_serial]] (written in C) writes the state of buttons soldered to a serial port to stdout and switches LEDs depending on bytes read from stdin.

===== 4.3. ctrl_fifo
=====

The program [[:plugin_control_ctrl_fifo|ctrl_fifo]] (written in C) reads bytes form a FIFO and writes these bytes to stdout. This may be used to control LCD4Linux from several external scripts.

\\\

====== 5. Examples ======
\\\

===== 5.1. Simple Controller Test =====

Download: [[::raw-attachment:wiki:plugin_control:sample_control.2.conf|sample_control.2.conf]] 
[[:BR]][[:BR]]
This example is written for the Curses driver. So no real LCD is needed for testing. 
Use [[:Manual#USAGE|option -f]] to activate these configuration files.

It allows to test the controllers mentioned in chapter 4.

Five controllers are configured:

1. A timer triggered controller that resets the last byte information. 
1. A keypad triggered controller which reacts on the arrow keys. Left = prev, right = next, up = confirm, down = cancel.
1. ctrl_usbmouse: **Program path, mouse id and privileges need to be configured first.** Wheel up/down = prev/next, left/right button = confirm/cancel
1. ctrl_fifo: **Program and FIFO path need to be configured first.** "echo -n CHARACTER > /tmp/ctrl.fifo", "o" = ok, "c" = cancel, "p" = prev, "n" = next  
1. ctrl_serial: **Program path, path to serial port and privileges need to be configured first.** 4 Buttons switch through LED modes.

The //prog// attribute of controllers that shouldn't be used should be commented out.


\\\

===== 5.2. Menu Control =====

The [[:plugin_menu#a4.Example|example config of the Menu plugin]] contains a preconfigured //Plugin Control// section.
This can be configured and activated to test a simple menu control with or without a keyboard.