#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass book
\begin_preamble
\usepackage[plainpages=false,pdfpagelabels,colorlinks=true,linkcolor=blue]{hyperref}
\end_preamble
\language english
\inputencoding default
\fontscheme bookman
\graphics default
\float_placement !htbp
\paperfontsize default
\spacing single 
\papersize letterpaper
\paperpackage a4
\use_geometry 1
\use_amsmath 1
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 1in
\topmargin 1in
\rightmargin 0.8in
\bottommargin 0.8in
\secnumdepth 1
\tocdepth 5
\paragraph_separation skip
\defskip smallskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Chapter

Virtual Control Panels
\layout Section

Introduction
\layout Standard

Traditional machine control panels are large sheets of steel with push buttons,
 knobs, lights and sometimes meters mounted on them.
 They have many advantages - the buttons are far more rugged than a computer
 keyboard, and large enough that you can usually operate the correct one
 by feel while looking elsewhere, for example at the tool.
 However, they also have disadvantages.
 The occupy a lot of panel space, they are expensive, and wiring them into
 the PC can use up a lot of I/O pins.
 That is where Virtual Control Panels come in.
\layout Standard

A Virtual Control Panel (VCP) is a window on the computer screen with buttons,
 meters, switches, etc.
 When you click on a VCP button, it changes the state of a HAL pin, exactly
 as if you had pressed a physical button wired to an input pin on an I/O
 card.
 Likewise, a VCP LED lights up when a HAL pin goes true, just like a physical
 indicator lamp wired to an output pin on an I/O card.
 Virtual control panels are not intended to replace physical panels - sometimes
 there is just no substitute for a big rugged oil-tight push button.
 But virtual panels can be used for testing or monitoring things that don't
 require physical buttons and lights, to temporarily replace real I/O devices
 while debugging ladder logic, or perhaps to simulate a physical panel before
 you build it and wire it to an I/O board.
\layout Section

pyVCP
\layout Standard

The layout of a pyVCP panel is specified with an XML file that contains
 widget tags between <pyvcp> and </pyvcp>.
 For example:
\layout LyX-Code

<pyvcp>
\newline 
    <label text="This is a LED indicator"/>
\newline 
    <led/>
\newline 
</pyvcp>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_mypanel.png

\end_inset 


\layout Standard

If you place this text in a file called tiny.xml, and run 
\layout LyX-Code

pyvcp -c mypanel tiny.xml
\layout Standard

pyVCP will create the panel for you, which includes two widgets, a Label
 with the text 
\begin_inset Quotes eld
\end_inset 

This is a LED indicator
\begin_inset Quotes erd
\end_inset 

, and a LED, used for displaying the state of a HAL BIT signal.
 It will also create a HAL component named 
\begin_inset Quotes eld
\end_inset 

mypanel
\begin_inset Quotes erd
\end_inset 

 (all widgets in this panel are connected to pins that start with 
\begin_inset Quotes eld
\end_inset 

mypanel.
\begin_inset Quotes erd
\end_inset 

).
 Since no <halpin> tag was present inside the <led> tag, pyVCP will automaticall
y name the HAL pin for the LED widget mypanel.led.0
\layout Standard

For a list of widgets and their tags and options, see the widget reference
 below.
\layout Standard

Once you have created your panel, connecting HAL signals to and from the
 pyVCP pins is done with 'halcmd linksp' as usual.
 If you are new to HAL, the HAL Tutorial
\begin_inset LatexCommand \ref{cha:HAL-Tutorial}

\end_inset 

 is recommended.
\layout Section

Security of pyVCP
\layout Standard

Parts of pyVCP files are evaluated as Python code, and can take any action
 available to Python programs.
 Only use pyVCP .xml files from a source that you trust.
\layout Section

Using pyVCP with AXIS
\begin_inset LatexCommand \label{sec:pyvcp-with-axis}

\end_inset 


\layout Standard

Since AXIS uses the same GUI toolkit (Tkinter) as pyVCP, it is possible
 to include a pyVCP panel on the right side of the normal AXIS user interface.
 A typical example is explained below.
\layout Standard

Place your pyVCP XML file describing the panel in the same directory where
 your .ini file is.
 Say we we want to display the current spindle speed using a Bar widget.
 Place the following in a file called spindle.xml:
\layout LyX-Code

<pyvcp>
\newline 
    <label>
\newline 
        <text>"Spindle speed:"</text>
\newline 
    </label>
\newline 
    <bar>
\newline 
        <halpin>"spindle-speed"</halpin>
\newline 
        <max_>5000</max_>
\newline 
    </bar>
\newline 
</pyvcp>
\layout Standard

Here we've made a panel with a Label and a Bar widget, specified that the
 HAL pin connected to the Bar should be named 
\begin_inset Quotes eld
\end_inset 

spindle-speed
\begin_inset Quotes erd
\end_inset 

, and set the maximum value of the bar to 5000 (see widget reference below
 for all options).
 To make AXIS aware of this file, and call it at start up, we need to specify
 the following in the [DISPLAY] section of the .ini file:
\layout LyX-Code

PYVCP = spindle.xml
\layout Standard

To make our widget actually display the spindle-speed it needs to be hooked
 up to the appropriate HAL signal.
 A .hal file that will be run once AXIS and pyVCP have started can be specified
 in the [HAL] section of the .ini file:
\layout LyX-Code

POSTGUI_HALFILE = spindle_to_pyvcp.hal
\layout Standard

This change will run the HAL commands specified in 
\begin_inset Quotes eld
\end_inset 

spindle_to_pyvcp.hal
\begin_inset Quotes erd
\end_inset 

.
 In our example the contents could look like this:
\layout LyX-Code

linksp spindle-rpm-filtered  pyvcp.spindle-speed
\layout Standard

assuming that a signal called 
\begin_inset Quotes eld
\end_inset 

spindle-rpm-filtered
\begin_inset Quotes erd
\end_inset 

 already exists.
 Note that when running together with AXIS, all pyVCP widget HAL pins have
 names that start with 
\begin_inset Quotes eld
\end_inset 

pyvcp.
\begin_inset Quotes erd
\end_inset 

.
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_AXIS.png
	lyxscale 50
	scale 50

\end_inset 


\layout Standard

This is what the newly created pyVCP panel should look like in AXIS.
 The 
\family typewriter 
sim/lathe
\family default 
 configuration is already configured this way.
\layout Section

pyVCP Widget reference
\layout Standard

HAL signals come in two variants, BIT and FLOAT.
 pyVCP can either display the value of the signal with an indicator widget,
 or modify the signal value with a control widget.
 Thus there are four classes of pyVCP widgets that you can connect to a
 HAL signal.
 A fifth class of helper widgets allow you to organize and label your panel.
\layout List
\labelwidthstring 00.00.0000

1.
 Widgets for indicating BIT signals: LED
\layout List
\labelwidthstring 00.00.0000

2.
 Widgets for controlling BIT signals: Button, Checkbutton, Radiobutton
\layout List
\labelwidthstring 00.00.0000

3.
 Widgets for indicating FLOAT signals: Number, Bar, Meter
\layout List
\labelwidthstring 00.00.0000

4.
 Widgets for controlling FLOAT signals: Spinbox, Scale, Jogwheel
\layout List
\labelwidthstring 00.00.0000

5.
 Helper widgets: Hbox, Vbox, Tabel, Label, Labelframe
\layout Subsubsection

Syntax
\layout Standard

Each widget is described briefly, followed by the markup used, and a screen
 shot.
 All tags inside the main widget tag are optional.
\layout Subsubsection

General Notes
\layout Standard

At the present time, both a tag-based and an attribute-based syntax are
 supported.
 For instance, the following XML fragments are treated identically:
\layout LyX-Code

<led halpin="my-led"/>
\layout Standard

and
\layout LyX-Code

<led><halpin>"my-led"</halpin></led>
\layout Standard

When the attribute-based syntax is used, the following rules are used to
 turn the attributes value into a Python value:
\layout Enumerate

If the first character of the attribute is one of the following, it is evaluated
 as a Python expression: 
\family typewriter 
{(["'
\layout Enumerate

If the string is accepted by int(), the value is treated as an integer
\layout Enumerate

If the string is accepted by float(), the value is treated as floating-point
\layout Enumerate

Otherwise, the string is accepted as a string.
\layout Standard

When the tag-based syntax is used, the text within the tag is always evaluated
 as a Python expression.
\layout Standard

The examples below show a mix of formats.
\layout Subsection

LED
\layout Standard

A LED is used to indicate the status of a BIT signal.
 The LED color will be on_color when the BIT signal is true, and off_color
 otherwise.
\layout LyX-Code

<led>
\newline 
    <halpin>"my-led"</halpin> 
\newline 
    <size>50</size> 
\newline 
    <on_color>"blue"</on_color>
\newline 
    <off_color>"black"</off_color>
\newline 
</led>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_led.png

\end_inset 


\layout Standard

<halpin> sets the name of the pin, default is 
\begin_inset Quotes eld
\end_inset 

led.n
\begin_inset Quotes erd
\end_inset 

, where n is an integer
\newline 
<size> sets the size of the led, default is 20
\newline 
<on_color> sets the color of the LED when the pin is true.
 default is 
\begin_inset Quotes eld
\end_inset 

green
\begin_inset Quotes erd
\end_inset 


\newline 
<off_color> sets the color of the LED when the pin is false.
 default is 
\begin_inset Quotes eld
\end_inset 

ref
\begin_inset Quotes erd
\end_inset 


\layout Subsection

Button
\layout Standard

A button is used to control a BIT pin.
 The pin will be set True when the button is pressed and held down, and
 will be set False when the button is released.
\layout LyX-Code

<button>
\newline 
    <halpin>"my-button"</halpin>
\newline 
    <text>"ON"</text> 
\newline 
</button>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_button.png

\end_inset 


\layout Subsection

Checkbutton
\layout Standard

A checkbutton controls a BIT pin.
 The pin will be set True when the button is checked, and false when the
 button is unchecked.
\layout LyX-Code

<checkbutton>
\newline 
    <halpin>"my-checkbutton"</halpin>
\newline 
</checkbutton>
\layout Standard

An unchecked checkbutton: 
\begin_inset Graphics
	filename pyvcp_checkbutton1.png

\end_inset 

 , and a checked one: 
\begin_inset Graphics
	filename pyvcp_checkbutton2.png

\end_inset 


\layout Subsection

Radiobutton
\layout Standard

A radiobutton will set one of a number of BIT pins true.
 The other pins are set false.
\layout LyX-Code

<radiobutton>
\newline 
    <choices>["one","two","three"]</choices> 
\newline 
    <halpin>"my-radio"</halpin> 
\newline 
</radiobutton>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_radiobutton.png

\end_inset 


\layout Standard

Note that the HAL pins in the example above will me named my-radio.one, my-radio.t
wo, and my-radio.three.
 In the image above, 
\begin_inset Quotes eld
\end_inset 

three
\begin_inset Quotes erd
\end_inset 

 is the selected value.
\layout Subsection

Number
\layout Standard

The number widget displays the value of a FLOAT signal.
\layout LyX-Code

<number>
\newline 
    <halpin>"my-number"</halpin>
\newline 
    <font>('Helvetica',50)</font>
\newline 
    <format>"+4.3f"</format>
\newline 
</number>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_number.png

\end_inset 


\layout Standard

<font> is a Tkinter font type and size specification.
 Note that on Ubuntu 6.06 'Helvetica' is not available in sizes above ca
 40 or 50.
 One font that will show up to at least size 200 is 'courier 10 pitch',
 so for a really big Number widget you could specify:
\layout LyX-Code

<font>('courier 10 pitch',100)</font>
\layout Standard

<format> is a 'C-style' format specified that determines how the number
 is displayed.
\layout Subsection

Bar
\layout Standard

A bar widget displays the value of a FLOAT signal both graphically using
 a bar display and numerically.
\layout LyX-Code

<bar>
\newline 
    <halpin>"my-bar"</halpin>
\newline 
    <min_>0</min_>
\newline 
    <max_>123</max_>
\newline 
    <bgcolor>"grey"</bgcolor>
\newline 
    <fillcolor>"red"</fillcolor>
\newline 
</bar>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_bar.png

\end_inset 


\layout Subsection

Meter
\layout Standard

Meter displays the value of a FLOAT signal using a traditional dial indicator.
\layout LyX-Code

<meter>
\newline 
    <halpin>"my-meter"</halpin>
\newline 
    <text>"Voltage"</text>
\newline 
    <size>300</size>
\newline 
    <min_>-12</min_>
\newline 
    <max_>33</max_>
\newline 
</meter> 
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_meter.png
	lyxscale 50
	scale 50

\end_inset 


\layout Subsection

Spinbox
\layout Standard

Spinbox controls a FLOAT pin.
 You increase or decrease the value of the pin by 'resolution' by either
 pressing on the arrows, or pointing at the spinbox and rolling your mouse-wheel.
\layout LyX-Code

<spinbox>
\newline 
    <halpin>"my-spinbox"</halpin>
\newline 
    <min_>-12</min_>
\newline 
    <max_>33</max_>
\newline 
    <resolution>0.1</resolution>
\newline 
    <format>"2.3f"</format>
\newline 
    <font>('Arial',30)</font>
\newline 
</spinbox>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_spinbox.png

\end_inset 


\layout Subsection

Scale
\layout Standard

Scale controls a FLOAT pin.
 You increase or decrease the value of the pin be either dragging the slider,
 or pointing at the scale and rolling your mouse-wheel.
\layout LyX-Code

<scale>
\newline 
    <halpin>"my-scale"</halpin>
\newline 
    <resolution>0.1</resolution>
\newline 
    <orient>HORIZONTAL</orient>
\newline 
    <min_>-33</min_>
\newline 
    <max_>26</max_>
\newline 
</scale>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_scale.png

\end_inset 


\layout Subsection

Jogwheel
\layout Standard

Jogwheel mimics a real jogwheel by outputting a FLOAT pin which counts up
 or down as the wheel is turned, either by dragging in a circular motion,
 or by rolling the mouse-wheel.
\layout LyX-Code

<jogwheel>
\newline 
    <halpin>"my-wheel"</halpin>
\newline 
    <cpr>45</cpr>
\newline 
    <size>250</size>
\newline 
</jogwheel>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_jogwheel.png
	lyxscale 50
	scale 50

\end_inset 


\layout Section

pyVCP Container reference
\layout Standard

Containers are widgets that contain other widgets.
\layout Subsection

Hbox
\layout Standard

Use a Hbox when you want to stack widgets horizontally next to each other.
\layout LyX-Code

<hbox>
\newline 
    <label><text>"a vbox:"</text></label>
\newline 
    <led></led>
\newline 
    <number></number>
\newline 
    <bar></bar>
\newline 
</hbox>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_hbox.png

\end_inset 


\layout Standard

Inside a Hbox, you can use the 
\family typewriter 
<boxfill fill=""/>
\family default 
, 
\family typewriter 
<boxanchor anchor=""/>
\family default 
, and 
\family typewriter 
<boxexpand expand=""/>
\family default 
 tags to choose how items in the box behave when the window is re-sized.
 For details of how fill, anchor, and expand behave, refer to the Tk 
\family typewriter 
pack
\family default 
 manual page, 
\family typewriter 
pack(3tk)
\family default 
.
 By default, 
\family typewriter 
fill='y'
\family default 
, 
\family typewriter 
anchor='center'
\family default 
, 
\family typewriter 
expand='yes'
\family default 
.
\layout Subsection

Vbox
\layout Standard

Use a Vbox when you want to stack widgets vertically on top of each other.
\layout LyX-Code

<vbox>
\newline 
    <label><text>"a vbox:"</text></label>
\newline 
    <led></led>
\newline 
    <number></number>
\newline 
    <bar></bar>
\newline 
</vbox>
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_vbox.png

\end_inset 


\layout Standard

Inside a Hbox, you can use the 
\family typewriter 
<boxfill fill=""/>
\family default 
, 
\family typewriter 
<boxanchor anchor=""/>
\family default 
, and 
\family typewriter 
<boxexpand expand=""/>
\family default 
 tags to choose how items in the box behave when the window is re-sized.
 For details of how fill, anchor, and expand behave, refer to the Tk 
\family typewriter 
pack
\family default 
 manual page, 
\family typewriter 
pack(3tk)
\family default 
.
 By default, 
\family typewriter 
fill='x'
\family default 
, 
\family typewriter 
anchor='center'
\family default 
, 
\family typewriter 
expand='yes'
\family default 
.
\layout Subsection

Label
\layout Standard

A label is a piece of text on your panel.
\layout LyX-Code

<label>
\newline 
    <text>"This is a Label:"</text>
\newline 
    <font>('Helvetica',20)</font>
\newline 
</label> 
\layout Standard
\align center 

\begin_inset Graphics
	filename pyvcp_label.png

\end_inset 


\layout Subsection

Labelframe
\layout Standard

A labelframe is a frame with a groove and a label at the upper-left corner.
\layout LyX-Code

<labelframe text="Group Title">
\newline 
  <hbox>
\newline 
    <led/> <led/>
\newline 
  </hbox>
\newline 
</labelframe>
\layout Subsection

Table
\layout Standard

A table is a container that allows layout in a grid of rows and columns.
 Each row is started by a 
\family typewriter 
<tablerow/>
\family default 
 tag.
 A contained widget may span rows or columns through the use of the 
\family typewriter 
<tablespan rows= cols=/>
\family default 
 tag.
 The sides of the cells to which the contained widgets 
\begin_inset Quotes eld
\end_inset 

stick
\begin_inset Quotes erd
\end_inset 

 may be set through the use of the 
\family typewriter 
<tablesticky sticky=/>
\family default 
 tag.
 A table expands on its flexible rows and columns.
\layout Standard

Example:
\layout LyX-Code

<table flexible_rows="[2]" flexible_columns="[1,4]">
\newline 
   <tablesticky sticky="new"/>
\newline 
   <tablerow/>
\newline 
    <label text="A (cell 1,1)"/>
\newline 
    <label text="B (cell 1,2)"/>
\newline 
    <tablespan columns="2"/><label text="C, D (cells 1,3 and 1,4)"> 
\newline 
   <tablerow/>
\newline 
    <label text="E (cell 2,1)"/>
\newline 
    <tablesticky sticky="nsew"/><tablespan rows="2"/>
\newline 
        <label text="'spans
\backslash 
n2 rows'"/>
\newline 
    <tablesticky sticky="new"/><label text="G (cell 2,3)"/>
\newline 
    <label text="H (cell 2,4)"/>
\newline 
   <tablerow/> 
\newline 
    <label text="J (cell 3,1)"/>
\newline 
    <label text="K (cell 3,2)"/>
\newline 
    <label text="M (cell 3,4)"/>
\newline 
</table> 
\the_end