#!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>
\
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.1. Basic structure
The structure in the config-file looks like this example which configures a usb mouse controller to navigate within a menu:
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 {
...
}
}
===== 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 Subsection Controller, at least 1 controller has to be set |
===== controller2.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 Subsection Key |
===== key2.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 |
\
====== functions3. 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') | ||
\
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 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 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 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.
\
\
Download: sample_control.2.conf BRBR This example is written for the Curses driver. So no real LCD is needed for testing. Use 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.
\
The 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.