elua/doc/en/using.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Language" content="en-us"><title>Using eLua</title>

<link rel="stylesheet" type="text/css" href="../style.css"></head>
<body style="background-color: rgb(255, 255, 255);">
<h3>Using eLua</h3><p> So, you already <a href="building.html">built</a> and <a href="installing.html">installed</a> <b>eLua</b>, and now it is time to (finally) have some fun with it :) 
  You can compile <b>eLua</b> with either console over UART (by far the most popular) and console over TCP/IP (still experimental, but working quite well), so there are two different usage 
  scenarios for this (see <a href="building.html">building eLua</a> for details on how to select serial or TCP/IP console).
<h3>Using eLua over serial connections</h3>
<p>All you need to use <b>eLua</b> over a serial connection is your <b>eLua</b>
board connected to a PC running a terminal emulator program.<br>If
you're using Windows, I strongly recommend <a target="_blank"  href="http://www.ayera.com/teraterm/">TeraTerm</a>.
It's a freeware, it's very powerful and also easy to use. The native Hyper Terminal progam can do too, but give TeraTerm a chance, it's much better than HyperTerm IMO.<br>On
Linux,
you'll probably be stucked with minicom. It is not exactly intuitive
and it runs in text mode, but it's still very powerful. If you
google for "minicom tutorial" you'll get the hang of it in no time. You
can try any other terminal emulator, as long as you set it up
properly and it gives you the option of transferring files
via XMODEM, which is what <b>eLua</b> uses at the moment. These are the main
settings you need to look at:</p>

<ul><li>port setup: 115200 baud (38400 for <a href="installing_str7.html">STR7)</a>, 8N1(8 data bits, no parity, one stop bit). </li><li>hardware flow control: none</li><li>newline handling: "CR" on receive, "CR+LF" on send (some terminal programs won't give you a choice here).  </li></ul>


<p>Also, depending on the type of your board, you'll need some way to
connect the board to a serial port on your PC or to USB if you're
using an USB to serial converter. For example, as already explained <a href="installing_lm3s.html">here</a>,
the USB port on the LM3Sxxxx boards is dual, so you can use it as an USB
to serial converter after downloading your firmware, thus you don't
need any other type of connection. The same is true for the
STR9-comStick board. On the other hand, for the SAM7-EX256 board you'll
need to connect a serial cable to the "RS232" connector, provided that
the jumpers are already set as explained <a href="installing_at91sam7x.html">here</a> and on the MOD711 you will need to add an RS232 converter chip.
There's no universal rule here, it all depends on your board.
</p>
<h3>Using eLua over TCP/IP connections</h3>
<p>Things are even easier if you decide to enable console over TCP/IP:
<ul>
  <li>make sure you know the address of your board. If you enabled static IPs (see <a href="building.html">building</a>) remember what you chose for the static IP; if DHCP is used instead, your
      DHCP server should've added the address of the <b>eLua</b> board to your DNS. The board name is always "elua", so if you execute "ping elua" from a shell you should see that the board is
      alive.</li>
  <li>telnet to the address of the board (or simply "telnet elua" if DHCP is used), and you'll be greeted with the shell prompt (if the shell is enabled, see the next paragraph for details). 
  Note that you can only have an active telnet session to the <b>eLua</b> board at a given time.</li>
</ul>
</p>
<p>If you're under Windows, make sure you're using a proper telnet client, which basically means "just about everything <b>but</b> the build-in telnet client".
   <a target="_blank" href="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</a> is a very good and popular choice.</p>
<h3><a name="shell"></a>The eLua shell</h3>
<p>No matter what's your physical connection (serial or TCP/IP), after you setup the PC-eLua board connection (and press the "RESET" button on your board or simply press ENTER if you're using 
  the serial connection), you should see the <b>eLua</b> shell prompt (if you enabled the shell in your build, as described <a href="building.html">here</a>). The shell is a simple
  interactive command interpreter that allows you to:
<ul>
  <li>get help on shell usage with the help command</li>
  <li>run the Lua interpreter in interactive mode just like you'd do on a desktop machine</li>
  <li>run a Lua program from the eLua File System</li>
  <li>upload a Lua source file via XMODEM and execute in on board</li>
  <li>query the eLua version</li>
  <li>list files on eLua file systems</li>
</ul></p>
<p>A detailed description of all the shell commands is given below.</p>

<h2>help</h2>
<p>Show a list of all shell commands.</p>
<h2>ver</h2>
<p>Print the version of the <b>eLua</b> image installed on the board. Currently, the version only increments for official releases, so if there's inter-release code in the
development tree, this isn't reflected in the version number.</p>
<h2>recv</h2>

<p>Allows you to receive a Lua file (either source or compiled bytecode) via
XMODEM and execute it on your board. To use this, your <b>eLua</b> taret image must be built with support for XMODEM 
(see <a href="building.html">building</a> for details).Also, your terminal emulation program must 
support sending files via the XMODEM protocol. Both XMODEM with checksum and XMODEM with CRC are supported, but only XMODEM with 128 
byte packets is allowed (XMODEM with 1K packets won't work).
To use this feature, enter "recv" at the shell prompt. eLua will respond with 
"Waiting for file ...". At this point you can send the file to the eLua board 
via XMODEM. eLua will receive and execute the file. Don't worry when you see 'C'
characters suddenly appearing on your terminal after you enter this command, 
this is how the XMODEM transfer is initiated.<br>
Since XMODEM is a protocol that uses serial lines, this command is not available if you're using terminal over TCP/IP.
</p>

<h2>lua</h2>

<p>This allows you to start the Lua interpreter, optionally passing command line parameters, just 
as you would do from a desktop machine. The command has some
restrictions:</p>

<ul><li>the command line can't be longer than 50 chars</li>
<li>character escaping is not implemented. For example, the next command won't work
    because of the ' escape sequences:</li>

<p><pre><code>eLua# lua -e 'print('Hello, World!')' -i<br>
Press CTRL+Z to exit Lua<br>
lua: (command line):1: unexpected symbol near ''</code></pre></p>

<p>However, if you use both '' and "" for string quoting, it will work:</p>

<p><pre><code>eLua# lua -e 'print("Hello, World")' -i<br>
Press CTRL+Z to exit Lua<br>
Lua 5.1.4  Copyright (C) 1994-2008 Lua.org, PUC-Rio
Hello,World</code></pre></p></ul>
<p>If you want to execute a file from the <a href="">##ROM file system</a>, remember to prefix it with <i>/rom</i>. For example, to execute <b>hello.lua</b>, do this:</p>
<p><pre><code>$ lua /rom/hello.lua</code></pre></p>
<h2>ls or dir</h2>
<p>Shows a list of all the files in the filesystems used by <b>eLua</b> (currently only the ROM file system), as well as their size and the total size of the given file system.</p>
<h2>exit</h2>
<p>Exits the shell. This only makes sense if <b>eLua</b> is compiled with terminal support over TCP/IP , as it closes the telnet session to the <b>eLua</b> board. Otherwise it just
  terminates the shell and blocks forever until you reset your board.
</body></html>
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00			`<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">`
			`<html><head>`
			`<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">`
working on the docs 2009-03-05 12:46:04 +00:00			`<meta http-equiv="Content-Language" content="en-us"><title>Using eLua</title>`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00
			`<link rel="stylesheet" type="text/css" href="../style.css"></head>`
			`<body style="background-color: rgb(255, 255, 255);">`
working on the docs 2009-03-05 12:46:04 +00:00			`<h3>Using eLua</h3><p> So, you already <a href="building.html">built</a> and <a href="installing.html">installed</a> <b>eLua</b>, and now it is time to (finally) have some fun with it :)`
			`You can compile <b>eLua</b> with either console over UART (by far the most popular) and console over TCP/IP (still experimental, but working quite well), so there are two different usage`
			`scenarios for this (see <a href="building.html">building eLua</a> for details on how to select serial or TCP/IP console).`
			`<h3>Using eLua over serial connections</h3>`
			`<p>All you need to use <b>eLua</b> over a serial connection is your <b>eLua</b>`
			`board connected to a PC running a terminal emulator program.<br>If`
			`you're using Windows, I strongly recommend <a target="_blank" href="http://www.ayera.com/teraterm/">TeraTerm</a>.`
			`It's a freeware, it's very powerful and also easy to use. The native Hyper Terminal progam can do too, but give TeraTerm a chance, it's much better than HyperTerm IMO.<br>On`
Enhancing doc for v0.6 2009-02-20 14:48:13 +00:00			`Linux,`
			`you'll probably be stucked with minicom. It is not exactly intuitive`
			`and it runs in text mode, but it's still very powerful. If you`
			`google for "minicom tutorial" you'll get the hang of it in no time. You`
			`can try any other terminal emulator, as long as you set it up`
			`properly and it gives you the option of transferring files`
working on the docs 2009-03-05 12:46:04 +00:00			`via XMODEM, which is what <b>eLua</b> uses at the moment. These are the main`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00			`settings you need to look at:</p>`

working on the docs 2009-03-05 12:46:04 +00:00			`<ul><li>port setup: 115200 baud (38400 for <a href="installing_str7.html">STR7)</a>, 8N1(8 data bits, no parity, one stop bit). </li><li>hardware flow control: none</li><li>newline handling: "CR" on receive, "CR+LF" on send (some terminal programs won't give you a choice here). </li></ul>`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00

			`<p>Also, depending on the type of your board, you'll need some way to`
Enhancing doc for v0.6 2009-02-20 14:48:13 +00:00			`connect the board to a serial port on your PC or to USB if you're`
working on the docs 2009-03-05 12:46:04 +00:00			`using an USB to serial converter. For example, as already explained <a href="installing_lm3s.html">here</a>,`
Enhancing doc for v0.6 2009-02-20 14:48:13 +00:00			`the USB port on the LM3Sxxxx boards is dual, so you can use it as an USB`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00			`to serial converter after downloading your firmware, thus you don't`
			`need any other type of connection. The same is true for the`
			`STR9-comStick board. On the other hand, for the SAM7-EX256 board you'll`
			`need to connect a serial cable to the "RS232" connector, provided that`
working on the docs 2009-03-05 12:46:04 +00:00			`the jumpers are already set as explained <a href="installing_at91sam7x.html">here</a> and on the MOD711 you will need to add an RS232 converter chip.`
			`There's no universal rule here, it all depends on your board.`
			`</p>`
			`<h3>Using eLua over TCP/IP connections</h3>`
			`<p>Things are even easier if you decide to enable console over TCP/IP:`
			`<ul>`
			`<li>make sure you know the address of your board. If you enabled static IPs (see <a href="building.html">building</a>) remember what you chose for the static IP; if DHCP is used instead, your`
			`DHCP server should've added the address of the <b>eLua</b> board to your DNS. The board name is always "elua", so if you execute "ping elua" from a shell you should see that the board is`
			`alive.</li>`
			`<li>telnet to the address of the board (or simply "telnet elua" if DHCP is used), and you'll be greeted with the shell prompt (if the shell is enabled, see the next paragraph for details).`
			`Note that you can only have an active telnet session to the <b>eLua</b> board at a given time.</li>`
			`</ul>`
			`</p>`
			`<p>If you're under Windows, make sure you're using a proper telnet client, which basically means "just about everything <b>but</b> the build-in telnet client".`
			`<a target="_blank" href="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</a> is a very good and popular choice.</p>`
			`<h3><a name="shell"></a>The eLua shell</h3>`
			`<p>No matter what's your physical connection (serial or TCP/IP), after you setup the PC-eLua board connection (and press the "RESET" button on your board or simply press ENTER if you're using`
			`the serial connection), you should see the <b>eLua</b> shell prompt (if you enabled the shell in your build, as described <a href="building.html">here</a>). The shell is a simple`
			`interactive command interpreter that allows you to:`
			`<ul>`
			`<li>get help on shell usage with the help command</li>`
			`<li>run the Lua interpreter in interactive mode just like you'd do on a desktop machine</li>`
			`<li>run a Lua program from the eLua File System</li>`
			`<li>upload a Lua source file via XMODEM and execute in on board</li>`
			`<li>query the eLua version</li>`
			`<li>list files on eLua file systems</li>`
			`</ul></p>`
			`<p>A detailed description of all the shell commands is given below.</p>`

			`<h2>help</h2>`
			`<p>Show a list of all shell commands.</p>`
			`<h2>ver</h2>`
			`<p>Print the version of the <b>eLua</b> image installed on the board. Currently, the version only increments for official releases, so if there's inter-release code in the`
			`development tree, this isn't reflected in the version number.</p>`
			`<h2>recv</h2>`

			`<p>Allows you to receive a Lua file (either source or compiled bytecode) via`
			`XMODEM and execute it on your board. To use this, your <b>eLua</b> taret image must be built with support for XMODEM`
			`(see <a href="building.html">building</a> for details).Also, your terminal emulation program must`
			`support sending files via the XMODEM protocol. Both XMODEM with checksum and XMODEM with CRC are supported, but only XMODEM with 128`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00			`byte packets is allowed (XMODEM with 1K packets won't work).`
			`To use this feature, enter "recv" at the shell prompt. eLua will respond with`
			`"Waiting for file ...". At this point you can send the file to the eLua board`
			`via XMODEM. eLua will receive and execute the file. Don't worry when you see 'C'`
			`characters suddenly appearing on your terminal after you enter this command,`
working on the docs 2009-03-05 12:46:04 +00:00			`this is how the XMODEM transfer is initiated.<br>`
			`Since XMODEM is a protocol that uses serial lines, this command is not available if you're using terminal over TCP/IP.`
			`</p>`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00
working on the docs 2009-03-05 12:46:04 +00:00			`<h2>lua</h2>`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00
working on the docs 2009-03-05 12:46:04 +00:00			`<p>This allows you to start the Lua interpreter, optionally passing command line parameters, just`
			`as you would do from a desktop machine. The command has some`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00			`restrictions:</p>`

working on the docs 2009-03-05 12:46:04 +00:00			`<ul><li>the command line can't be longer than 50 chars</li>`
			`<li>character escaping is not implemented. For example, the next command won't work`
			`because of the ' escape sequences:</li>`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00
working on the docs 2009-03-05 12:46:04 +00:00			`<p><pre><code>eLua# lua -e 'print('Hello, World!')' -i<br>`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00			`Press CTRL+Z to exit Lua<br>`
working on the docs 2009-03-05 12:46:04 +00:00			`lua: (command line):1: unexpected symbol near ''</code></pre></p>`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00
			`<p>However, if you use both '' and "" for string quoting, it will work:</p>`

working on the docs 2009-03-05 12:46:04 +00:00			`<p><pre><code>eLua# lua -e 'print("Hello, World")' -i<br>`
Some initial site content migrated Ongoing work 2009-02-12 05:16:01 +00:00			`Press CTRL+Z to exit Lua<br>`
			`Lua 5.1.4 Copyright (C) 1994-2008 Lua.org, PUC-Rio`
working on the docs 2009-03-05 12:46:04 +00:00			`Hello,World</code></pre></p></ul>`
			`<p>If you want to execute a file from the <a href="">##ROM file system</a>, remember to prefix it with <i>/rom</i>. For example, to execute <b>hello.lua</b>, do this:</p>`
			`<p><pre><code>$ lua /rom/hello.lua</code></pre></p>`
			`<h2>ls or dir</h2>`
			`<p>Shows a list of all the files in the filesystems used by <b>eLua</b> (currently only the ROM file system), as well as their size and the total size of the given file system.</p>`
			`<h2>exit</h2>`
			`<p>Exits the shell. This only makes sense if <b>eLua</b> is compiled with terminal support over TCP/IP , as it closes the telnet session to the <b>eLua</b> board. Otherwise it just`
			`terminates the shell and blocks forever until you reset your board.`
			`</body></html>`