C&H Technologies EM405-8 User Manual
SCRIPTING MANUAL
ETHERNET
M-MODULE
CARRIER/
BRIDGE
MODEL
EM405-8
Manual Part No: 11030574A
COPYRIGHT
C&H Technologies, Inc. (C&H) provides this manual "as is" without warranty of any kind,
either expressed or implied, including but not limited to the implied warranties of
merchantability and fitness for a particular purpose. C&H may make improvements and/or
changes in the product(s) and/or program(s) described in this manual at any time and without
notice.
This publication could contain technical inaccuracies or typographical errors. Changes are
periodically made to the information herein; these changes will be incorporated in new editions
of this publication.
Copyright © 2009, 2012 by C&H Technologies, Inc.
The information and/or drawings set forth in this document and all rights in and to inventions
disclosed herein which might be granted thereon disclosing or employing the materials, methods,
techniques, or apparatus described herein, are the exclusive property of C&H Technologies, Inc.
A Reader's Comment Form is provided at the back of this publication. If this form has been
removed address comments to:
C&H Technologies, Inc.
Technical Publications
800 Paloma Drive, Suite 150
Round Rock, Texas 78665
C&H may use or distribute any of the information you supply in any way that it believes
appropriate without incurring any obligations whatever.
ii
DOCUMENT REVISION NOTICE
C&H Technologies, Inc. makes every attempt to provide up-to-date manuals with the associated
equipment. Occasionally, throughout the life of an instrument, changes are deemed necessary to
equipment related documentation. The latest revision of our documentation is available for
download from our web site at http://www.chtech.com.
NOTE
The contents of any amendment may affect operation,
maintenance, or calibration of the equipment.
iii
INTRODUCTION
This manual describes the operation and use of the scripting features of the EM405-8 Ethernet
M-Module Carrier/Bridge (Part Number 11029380). The scripting features described throughout
this manual are available on all EM405-8’s containing firmware version 3.0 and later. Contained
within this manual are the functional details and the programmatic guidelines to adequately
develop and deploy script-based applications for the EM405-8.
The EM405-8 is one of many test, data acquisition and control modules provided by C&H
Technology and is one of a number of M-Module carriers in C&H Technologies’ product line.
All manufacturing options of the EM405-8 include the scripting features; however, only options
that include an internal mass storage device provide non-volatile storage of scripts and
autonomous operation using the startup script feature.
The part numbers of the EM405-8’s that are covered by this manual are:
Part Number Description
11029380-0001 EM405-8 with external triggers
11029380-0002 EM405-8 without external triggers
11029380-0003 EM405-8 with external triggers and 16GB mass storage
11029380-0004 EM405-8 without external triggers, but with 16GB mass storage
EM405-8’s that contain a firmw are revision prior to 3.0 can be updated in the field to the most recent firmware
revision containing the scripting support. Please contact C&H Technologies Technical Support for update files and
detailed instructions.
iv
TABLE OF CONTENTS
1.0 GENERAL DESCRIPTION ............................................................................................1
1.1 PURPOSE OF EQUIPMENT.............................................................................................2
1.2 THE LUA SCRIPTING LANGUAGE ...............................................................................2
1.3 KEY FEATURES OF EM405-8 SCRIPTING ................................................................... 2
1.4 APPLICABLE REFERENCES..........................................................................................3
2.0 USING AND MANAGING SCRIP TS............................................................................4
2.1 COMMANDS..................................................................................................................... 4
2.1.1 ? | Help .........................................................................................................................4
2.1.2 Data..............................................................................................................................5
2.1.3 Halt...............................................................................................................................5
2.1.4 List...............................................................................................................................5
2.1.5 Read .............................................................................................................................6
2.1.6 Remove ........................................................................................................................ 6
2.1.7 Retrieve........................................................................................................................ 6
2.1.8 Run...............................................................................................................................7
2.1.9 Socket?.........................................................................................................................8
2.1.10 Upload.......................................................................................................................... 8
2.1.11 Ver................................................................................................................................ 9
2.2 STORING SCRIPTS AND SUPPORTING FILES............................................................ 9
2.3 SCRIPTING SOCKET INTERFACE...............................................................................10
2.3.1 Configuring the Scripting Socket Interface............................................................... 10
2.3.2 Connecting to the S cripting Socket Interface............................................................ 11
2.3.3 Interactive Mode........................................................................................................ 11
3.0 DEVELOPING SCRIPTS.............................................................................................. 13
3.1 DEVELOPMENT SOFTWARE – EM405-8 IVI DRIVER SOFT FRONT PANEL...... 13
3.2 EM405-8 EXTENSIONS LIBRARY............................................................................... 13
3.3 PASSING DATA ..............................................................................................................20
3.4 CALLING M-MODU LE DRIVERS................................................................................ 22
3.4.1 Using Alien to Call M-Module Drivers..................................................................... 22
3.4.2 Dealing with data.......................................................................................................25
3.4.2.1 Buffers................................................................................................................25
3.4.2.2 Arrays................................................................................................................. 26
3.4.2.3 Pointer Unpacking..............................................................................................27
3.4.2.4 Callback Functions.............................................................................................27
3.4.3 Building M-Module Drivers into a Linux S hared Library......................................... 28
3.5 SHARING DATA BETWEEN SCRIPTS........................................................................ 28
3.6 STARTUP SCRIPT ..........................................................................................................28
3.7 USING THE MASS STORAGE DEVICE.......................................................................29
4.0 USING LUA TO WRITE CUSTOM WEB PAGES.................................................... 30
4.1 URL OF SCRIPT BASED PAGES..................................................................................30
4.2 ADDING A LINK TO THE C&H NAVIGATION MENU.............................................31
4.3 URL OF PICTURES AND OTHER SUPPORTING FILES........................................... 32
4.4 PASSING ARGUMENTS TO THE SCRIPT................................................................... 32
4.5 DEVELOPING THE PAGE CONTENT..........................................................................33
v
LIST OF FIGURES
Figure 1 EM405-8 Scripting Utilities Architecture Diagram.........................................................1
Figure 2 Retrieve Script Download Format....................................................................................7
Figure 3 Script Upload Format.......................................................................................................9
Figure 4 Network Configuration Webpage ..................................................................................10
Figure 5 EM405-8 IVI Driver Scripting Panel Screenshot...........................................................13
Figure 6 Data Passing Example....................................................................................................21
Figure 7 M-Module Driver Example Code...................................................................................25
Figure 8 M-Module Driver Example Using Buffers ....................................................................26
Figure 9 M-Module Driver Example Using Arrays......................................................................27
Figure 10 Simple Lua Based Web Page .......................................................................................30
Figure 11 Example Adding Link to the Navigation Menu...........................................................31
Figure 12 Example Linking to a User Image.................................................................................32
Figure 13 Example Retrieving Arguments from the URL ............................................................33
Figure 14 Example Using “l_em405web.lua” Library..................................................................35
LIST OF TABLES
Table I Use and Management Commands......................................................................................4
Table II. Functions in the EM405-8 Extensions Library..............................................................14
Table III. Alien Data Types ..........................................................................................................23
Table IV l_em405web.lua Library Functions................................................................................33
vi
PART OF SCRIPTING EN
VIRONMENT FURNISHED
BY C&H
APPLICATION SPECIF IC
CUSTOMER DEVELOPMEN
T HARDWARE
STANDARD AVAILABLE S
OFTWARE FROM C&H OR
THIRD PA R TY
EM405
-
8 UTILITIES
EM405
-
8 LUA EXTENSIONS
M-
MODULE ANSI
-
C DRIVERS
LUA STD LIBRARIES
ALIEN LIB
MASS STORAGE
EM405
-
8 SCRIPT MANAGEMENT
EM405
-
8 IVI DRIVER
USER
WEB BROWSER
HOST
EM405
-8
RUN-TIME ENVIRONMENT
STANDARD TOOLS
ETHERNET
1.0 GENERAL DESCRIPTION
The scripting utilities of the EM405-8 M-Module Bridge provide enhanced programming
capabilities allowin g the user to easily embed software on the bridge to improve performance
and further integrate a set of M-modules. The scripting utilities are based off of the Lua
programming language and include extensions and customizations designed specifically for the
EM405-8. An architecture diagram of the scripting utilities is shown in Figure 1. Since Lua is
an interpretive language, EM405-8 users can easily develop scripts without the need for an
expensive development environment.
By embedding a script or a set of scripts on the EM405-8, the burden for monitoring, configuring
and controlling the M-modules is taken off the network and placed onto the EM405-8’s embedded
processor. This provides significant performance improvements and allows the EM405-8 and
associated M-modules to be customized and configured. It can also act independently for a long
period of time without the need for a network client to monitor the device(s).
DEVELOP SCRIPTS
MANAGE SCRIPTS
RUN S CRIPTS
VIEW SCRIPT OUTPUT
TELNET – RAW SOCKET I/F
TERMINAL EMULATOR
TEXT-BASED DEV ELOPMENT
COMMANDS
AND DATA
SCRIPTS
APPLICATION
CONT ROL SCRIPTS
SEND COMMANDS
RETRIEVE DATA
CUSTOM S CRIPT-BASED
WEB PAGES
EMBEDDED ON EM405-8
ARM PROCESSOR
(TRIGGERS, FANS, ETC.)
M-MODULES
Figure 1 EM405-8 Scripting Utilities Architecture Diagram
1
1.1 PURPOSE OF EQUIPMENT
The EM405-8 was designed for measurement, automation and control applications. The EM405
easily interfaces a VITA 12-1996 standard M-Module to a typical Ethernet network. The carrier
allows the numerous functions available in the M-Module mezzanine format to be remotely
located near the unit-under-test, easing many system integration issues. Over 100 M-Modules
are available from numerous manufacturers.
The scripting utilities were added to the EM405-8 to allow users to fully ut ilize the embedded
processor of the EM405-8 and to allow for easy customization of the integrated unit.
1.2 THE LUA SCRIPTING LANGUAGE
Lua (pronounced LOO-ah) is a powerful, fast, lightweight embeddable scripting language. It is
important to note that the name Lua is not an acronym. Lua was written in ANSI-C and is
designed to easily integrate with other software written in C and other conventional
programming languages. Thus, one of Lua’s primary strengths is its extensibility. Lua’s
extensibility is two-fold. Lua can be used to extend an application by embedding Lua scripting
into the application. Also, Lua itself is extendible allowing Lua scripts to utilize libraries and
components written in other programming languages.
Lua is an interpreted language in that Lua programs are stored as text that is interpreted at runtime. In reality, Lua code is compiled at runtime into an intermediate form; however, the fact
that compilation is performed at runtime allows scripts to be run directly from text and allows
Lua to retain the designation of an interpreted language.
Lua is free software distributed under the terms of the MIT license. The MIT license is short and
very liberal, allowing the user unrestricted use the software.
Further details, including documentation and references can be found at www.lua.org.
1.3 KEY FEATURES OF EM405-8 SC RIPTING
The EM405-8 implementation of scripting includes the basics of Lua including all standard
libraries, as well as EM405-8 specific extensions and EM405-8 specific script development
tools. Key features include:
Lua 5.1 programming language interpreter
Lua 5.1 standard libraries (math, table, string, i/o, operating system, etc.)
EM405-8 extensions to control M-modules and EM405-8 utilities
Call high-level M-module drivers and other libraries
TCP/IP based interactive interpreter for development
Develop scripts using any text editor. No compilation required
Store and retrieve data to/from mass storage device (mass storage is an EM405-8 option)
Receive commands and pass data over the Ethernet interface
Network based commands to use and manage scripts (store, retrieve, run, halt, etc.)
Create custom web pages to control the instrument
2
1.4 APPLICABLE REFERENCES
In addition to this reference manual there are several sources of further information on both the
EM405-8 and the Lua programming language. These documents should be referenced for details
of topics not covered or not elaborated on by this manual. The most applicable references are:
- EM405-8 User’s Manual, C&H Technologies, Inc., C&H part No: 11029384.
- Programming in Lua – 2nd Edition, Ierusalimschy, Roberto, Rio de Janeiro, 2006
- Lua Reference Manual, Ierusalimschy, Roberto, De Figueiredo Luiz Henrique, Celes
Waldemar, Lua.org, 2006
- Lua.org, http://www.lua.org
- Alien, http://alien.luaforge.net/, http://luaforge.net/projects/alien/
3
2.0 USING AND MANAGING SCRIPTS
The scripting utilities are accessible via the standard EM405-8 command interfaces (VXI-11 and
raw socket). In addition, a special scripting socket interface is available to help develop and
debug scripts. A set of use and management commands are defined and any of th ese commands
can be sent via any of the available interfaces with a few exceptions.
2.1 COMMANDS
The scripting commands allow the user to develop, use and manage scripts. These commands
are the primary interface to the scripting utilities and are used during both development and
deployment of scripts. They are available, with a few exceptions, via any of the EM405-8’s
command interfaces including the special scripting socket interface. A complete list of use and
management commands is shown in Table I. Details of each command can be found in the
subsequent sections.
Table I Use and Management Commands
?|help list command help
data <data>
halt <script> halt the script of the specified name
-l <script> halt last script started of specified name
-a [script] halt all running scripts
list list all scripts
-l [script] list details (script name optional)
-r [script] list if running (script name optional)
read <script> read the specified script
remove <script> remove the script
retrieve <script><port> retrieve the script using the specified port
-d delete the file upon retrieval
run <script> run specified script
-e <command> execute command
-i
socket? returns 1 if scripting socket running, 0 if not
-p returns the port of the scripting socket
upload <script><port> upload the script using the specified port
-x execute script after upload
-o overwrite script if file exists
ver returns versions of Lua and EM405-8 extensions
Note: An asterisk (*) is required before the command if sent via the VXI-11 or raw socket interface. The
EM405-8 contains a binary command protocol. An asterisk (*) character denotes that the remaining
command consists of ASCII characters. If the first byte i s anything other that an asterisk (*) the EM405-8
perceives it as a binary command. The binary commands are not available via the scripting socket therefore
the asterisk (*) is not required nor recognized.
-nx <script>
send up to 16Kbytes to a script (VXI-11 only)
halt script number x of specified name
enter interactive mode (scripting socket only)
2.1.1 ? | Help
The help command or simply ‘?’ will return a list of commands along with argument options
and descriptions similar to Table I. The result will be output via the same interface from which
the command was received.
help or ?
4
2.1.2 Data
The data command allows the user to transfer up to 16 kilobytes of data to a running script.
This command is only available over the VXI-11 or raw socket interface. It has no effect if sent
over the scripting socket interface.
data <up to 16K of data>
The command requires a running script that is expecting or polling for data. If such a script is
not running then this command will result in an I/O Error. For details on transferring data
to/from a running script refer to section 3.3.
2.1.3 Halt
The halt command is used to stop running scripts. Scripts always run in their own thread
allowing multip le scripts to be run at the same time. The halt command has the followin g
syntax:
halt <options>
options:
<script> halt the first script started of the specified name
-l <script> halt the last script started of the specified name
-nX <script> halt script number x of specified name
-a [script] halt all scripts or all scripts of the specified name
In addition to running more that one script at a time, the same script can be concurrently run
multiple times, each in its own thread. The system maintains a sequence list indicating the order
in which each instance of a running script was started. Using the halt command, the user can
specify the specific instance to halt, based on this start sequence. The system does not maintain
any further details other that the start order. It is up to the user to understand the details of a
specific instance, such as the responsibilities of that instance, and the order in which that instance
was started.
With the –a option the user can halt all running scripts of a specified name, by passing the script
name argument or all running scripts within the system by not specifying a script name.
2.1.4 List
The list command will return a list of all scripts stored on the system. The result will be output
via the same interface from which the command was sent.
list [options]
options:
-l show details of each file
-r show only scripts that are currently running
[script] if the optional [script] is specified only that script
will be shown
5
Arguments of the list command are optional. If no arguments are provided, all scripts will be
listed without details. Use the –l option to show the details of the scripts. Details include the
file size, date, the system/user designation and a run/idle status indication. The –r option shows
only those scripts that are currently running. Both options may be included in a single list
command. If the optional [script] argument is passed only scripts of the specified name will
be listed.
In the output of the list command, each script listing is terminated with a “new line” character
(‘\n’ or 0xA). The entire list is terminated with a carriage return (‘\r’ or 0xD).
2.1.5 Read
The read command will return the source code of the specified script via the interface from
which the command was sent. For example, if in the scripting socket interface you type read
myscript.lua the source code of myscript.lua will appear in the terminal window. If you
send the same command via the VXI-11 interface, the next VXI-11 read will return the source
code of the script. Note that the VXI-11 interface has a 16 kilobyte limit therefore any script
greater than 16 kilobytes will not be returned properly. An alternative to the read command is
the retrieve command detailed in section 2.1.7.
read <script>
2.1.6 Remove
The remove command will delete the specified script from both volatile and non-volatile
memory. A removed script is not recoverable therefore care must be taken to ensure a script is
saved on a host computer before sending the remove command.
remove <script>
2.1.7 Retrieve
The retrieve command is used to download a script from the EM405-8 to the host computer.
A download port must be specified.
retrieve [options] <script> <port>
options:
-d delete the file upon retrieval
Upon receiving the retrieve command, the EM405-8 will search for the specified script and
return a 4-byte acknowledge (“ack\n” if found or “nck\n” if not found) via the same interface
from which the command was received. If the script was found, the EM405-8 will launch a
small TCP/IP server at the specified port. The host application must then connect to this server
to download the script. The TCP/IP server will automatically ex it once the script has been
downloaded. Therefore, a new retrieve command must be used for each script to be
downloaded.
6
4
The script is sent over the TCP/IP server by the EM405-8 in a raw format preceded by 4 bytes
specifying the size of the file as shown in Figure 2. Figure 2 also shows the simple procedure to
download the file.
FILE SIZE (4 BYTES)
FILE DATA
0
4 + FILE SIZE
Download Procedure
1. Send the download command
2. Read the 4-byte Acknowledge
3. If “nck\n” then exit else if “ack\n” continue
4. Connect to the download port via raw socket
5. Read 4-bytes to determine size. Byte 0 is
the least significant byte.
6. Read size bytes to buffer
7. Write buffer to file on host computer
Figure 2 Retrieve Script Download Format
If the –d option is found, the script will be deleted at the completion of the download. A deleted
script is not recoverable therefore care must be taken before sending the -d option
2.1.8 Run
The run command starts the specified script, launches interactive mode or executes the specified
Lua command. One of the three arguments is required for the run command. Only one
argument can be passed in a single run command.
run <argument>
arguments:
<script> run the specified script
-i enter interactive mode (scripting socket only)
-e <command> executes the specified command
Running a specific scri pt will launch the script in its own process so that it may run
independently and so that the user may launch more that one script. In reality, the run command
is optional. Scripts can be run by simply sending the name of the script to the EM405-8 as a
command itself. Further, if the file extension of the script is .lua than the extension may be
omitted. For example, if the script file is myscript.lua then the followin g three commands
perform the same action of launching the script
run myscript.lua
myscript.lua
myscript
Interactive mode is a special mode of the scripting socket in which the user can type Lua source
code directly to the interpreter to be run immediately. Details on interactive mode can be found
in section 2.3.3. The –i option is only valid from the scripting socket interface and does not
return until the socket is closed.
7
The –e argument allows the user to input Lua source to be run immediately. It is different than
interactive mode in that it does not give the user a different command prompt in the scripting
socket and more importantly once the command(s) is complete the Lua state is lost. In other
words, variables, loaded libraries and other constructs that are normally valid from one command
to the next are only available durin g that one command.
2.1.9 Socket?
The socket? command will return an ASCII ‘1’ if the scriptin g socket interface is available and
an ASCII ‘0’ if not. Further passing the –p argument will return the TCP/IP port of the scripting
socket interface. Note that the –p argument will return a port number regardless of whether or
not the scripting socket is available.
socket? [options]
options:
-p returns the port number of the raw socket interface
It is useful to send the socket? command via the VXI-11 or raw socket interface to determine if
the scripting socket interface is available and to determine at which TCP/IP port to connect to it.
2.1.10 Upload
The upload command is used to upload a script from a host computer to the EM405-8. An
upload port must be specified.
upload [options] <script> <port>
options:
-x execute the script after upload
-o overwrite the script if the file exists
Upon receiving the upload command, the EM405-8 will first determine if a script of the same
name already exists. If the EM405-8 finds a script of the same name and the –o is not provided a
4-byte negative acknowledge (“nck\n”) is returned. If it does not find a script of the same name
or if the –o option is provided, a 4-byte positive acknowledge (“ack\n”) is returned. The
acknowledge, whether it is positive or negative, is sent via the same interface from which the
command was received.
If a positive acknowledge is returned the, EM405-8 will launch a small TCP/IP server at the
specified port. The host application must then connect to this server to upload the script. The
TCP/IP server will automatically exit once the script has been uploaded. Therefore, a new
upload command must be used for each script to be uploaded.
The host computer must send the script in a raw format preceded with 4 bytes specifying the size
of the file as shown in Figure 3. Figure 3 also shows the simple procedure to upload the file.
8
Loading...