Using eLua

So, you already built and installed eLua, and now it is time to (finally) have some fun with it :) You can compile eLua 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 building eLua for details on how to select serial or TCP/IP console).

All you need to use eLua over a serial connection is your eLua board connected to a PC running a terminal emulator program.
If you're using Windows, I strongly recommend TeraTerm. 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.
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 eLua uses at the moment. These are the main settings you need to look at:

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

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 here, 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 here 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.

Things are even easier if you decide to enable console over TCP/IP:

• make sure you know the address of your board. If you enabled static IPs (see building) remember what you chose for the static IP; if DHCP is used instead, your DHCP server should've added the address of the eLua 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.
• 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 eLua board at a given time.

If you're under Windows, make sure you're using a proper telnet client, which basically means "just about everything but the build-in telnet client". PuTTY is a very good and popular choice.

If you build eLua for the i386 platform, you can boot your PC directly in eLua! No underlying OS, nothing but plain eLua. It won't have any actual peripherals to access, but it can use the term module to run hangman.lua and life.lua, as well as other samples, which makes it a nice demo :) Follow this link for specific informations about the i386 port.

The eLua shell

No matter what's your physical connection (serial, TCP/IP or you PC's monitor after booting eLua), after you setup the PC-eLua board connection (if applicable) and press the "RESET" button on your board or simply press ENTER if you're using the serial connection, you should see the eLua shell prompt (if you enabled the shell in your build, as described here). The shell is a simple interactive command interpreter that allows you to:

• get help on shell usage with the help command
• run the Lua interpreter in interactive mode just like you'd do on a desktop machine
• run a Lua program from the eLua File System
• upload a Lua source file via XMODEM and execute in on board
• query the eLua version
• list files on eLua file systems

A detailed description of all the shell commands is given below.

help

Show a list of all shell commands.

ver

Print the version of the eLua 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.

recv

Allows you to receive a Lua file (either source or compiled bytecode) via XMODEM and execute it on your board. To use this, your eLua taret image must be built with support for XMODEM (see building 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.
Since XMODEM is a protocol that uses serial lines, this command is not available if you're using terminal over TCP/IP.
If you'd like to send compiled bytecode to eLua instead of source code, please check this section first.

lua

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:

• the command line can't be longer than 50 chars
• character escaping is not implemented. For example, the next command won't work because of the ' (simple quotes) escape sequences:

  eLua# lua -e 'print(\'Hello, World!\')' -i
  
  Press CTRL+Z to exit Lua
  
  lua: (command line):1: unexpected symbol near ''

  However, if you use both '' (simple quotes) and "" (double quotes) for string quotin , it will work:

  eLua# lua -e 'print("Hello, World")' -i
  Press CTRL+Z to exit Lua
  Lua 5.1.4  Copyright (C) 1994-2008 Lua.org, PUC-Rio
  Hello,World

If you want to execute a file from the ##ROM file system, remember to prefix it with /rom. For example, to execute hello.lua, do this:

$ lua /rom/hello.lua

ls or dir

Shows a list of all the files in the filesystems used by eLua (currently only the ROM file system), as well as their size and the total size of the given file system.

exit

Exits the shell. This only makes sense if eLua is compiled with terminal support over TCP/IP , as it closes the telnet session to the eLua board. Otherwise it just terminates the shell and blocks forever until you reset your board.

Cross-compilation is the process of compiling a program on one hardware platform for a different hardware platform. For example, the process of compiling the eLua binary image on a PC for your eLua board is cross-compiling. Lua can be cross-compiled, too. By cross-compiling Lua to bytecode on a PC and executing the resulting bytecode directly on your eLua board you have some important advantages:

• speed: the Lua compiler on the eLua board doesn't have to compile your Lua source code, it just executes the compiled bytecode.
• memory: f you're executing bytecode directly, no more memory is "wasted" on the eLua board for compiling the Lua code to bytecode. Many times this could be a "life saver". If you're trying to run Lua code directly on your board and you're getting "not enough memory" errors, you might be able to overcome this by compiling the Lua program on the PC and running the bytecode instead. Also, compiling large Lua programs on your eLua board can lead to stack overflows, which in turn leads to very hard to find errors.

In order to use cross-compilation, the two Lua targets (in this case your desktop PC and your eLua board) must be compatible (they should have the same data types, with the same size and the same memory representation). This isn't true all the time. For example, some gcc toolchains for ARM targets use a very specific representation for double precision numbers (called FPA format) by default, which makes bytecode files generated on the PC with the regular Lua compiler useless on ARM boards. Other toolchains don't have this problem. Other targets (like AVR32) are big endian, as opposed to Intel PCs that are little endian.
To overcome this kind of problems, a "Lua cross-compilation patch" was posted on the Lua mailing list a while ago, and it was further modified as part of the eLua project to work with ARM targets. This is how to use it (the following instructions were tested on Linux, not Windows, but they should work on Windows too with little or no tweaking):

• first, make sure that your PC has already a build system intalled (gcc, binutils, libc, headers...). You'll also need scons. The good news is that you should have it already installed, since otherwise you won't be able to build even regular eLua (see building for more in-depth instructions).
• from the eLua base directory, issue this command:

$ scons -f cross-lua.py

You should get a file called luac in the same directory after this. It's almost the same as the regular Lua compiler, but it has a few arguments that deal with differences between different targets (shown below in bold):

usage: ./luac [options] [filenames].
Available options are:
-        process stdin
-l       list
-o name  output to file 'name' (default is "luac.out")
-p       parse only
-s       strip debug information
-v       show version information
-cci bits       cross-compile with given integer size
-ccn type bits  cross-compile with given lua_Number type and size
-cce endian     cross-compile with given endianness ('big' or 'little')
--       stop handling options

All it's left to do now is to use the table below to figure out what are the right parameters for using the cross-compiler:

(note that if for some reason you want to cross-compile eLua for the x86 target you can use the regular Lua compiler).
You can omit the -s (strip) parameter from compilation, but this will result in larger bytecode files (as the debug information is not stripped if you don't use -s).

You can use your bytecode file in two ways:

• write it to the ROM file system and execute it from there.
• use the recv command from the shell to upload it to the board using a serial connection.