So, you already built and installed eLua, now it is time to (finally) have some fun with it :) You can compile eLua with either console over UART (the default and by far the most popular) or console over TCP/IP (still experimental, but working quite well). See building eLua for details on how to choose between serial and 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, we recommend TeraTerm. It’s a freeware, it’s very powerful and also easy to use. The native Hyper Terminal progam can do too, as well as any most other terminal emulator programs.

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:

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. Feel free to ask if you need help in our discussion list.

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

If you’re under Windows, make sure you’re using a proper telnet client, which basically means "just about everything but the built-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 code examples and games, which makes it a nice demo :) Follow this link for specific informations about the i386 port.

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 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:

eLua has two different versions of the shell (check here for information about how to enable each of them):

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 ona PC for your eLua board). 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:

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 these 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):

You should get a file called luac in the same directory as a result. 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):

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:

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 multiple ways:

Remote procedure calls (RPC) allow one program to communicate with another and call functions or subroutines within the second program. For example one might want to programmatically control an array of LEDs connected to an eLua embedded device from a desktop Lua state. A simple implementation might be a protocol that would allow one to send numeric or text-based commands that would cause code to be executed in eLua that would change the state of the LEDs. As one needs new commands to change these LEDs, one would need to upload a new Lua program to handle changing functionality. In contrast to this ad-hoc method for remote calls, LuaRPC provides a more general way to manipulate the state and execution of a remote Lua environment.

When a client is connected to a LuaRPC server, it can interact with it in the following ways:

You should get a file called luarpc in the same directory which, when started, should give you a normal Lua interpreter with a built-in rpc module.

See building for details and requirements for the building process. In order to boot into RPC mode, the RPC component will need to be enabled, and appropriate static configuration data needs to be set. To build eLua to boot into RPC mode, include boot=luarpc in the build options.

In terms of the LED example from the beginning of this section, one could directly call pio module functions from the desktop side, experimenting with responses. If the experimentation developed into a program this could be tested both on the desktop side and on the microcontroller by making aliases to eLua modules in local Lua state. Such aliasing can be done as follows:

When we run this locally, calling and indexing helpers are translated into appropriate actions on the server. If we were done with modifications to the above function and wanted it to execute in eLua rather than using local aliases, which will result in a great deal of RPC traffic every time the function is called, we can send the function to the remote side:

In addition to functions, we can also copy most other Lua types from client to server using simple assignment. Due to Lua’s internal workings the opposite operation of copying Lua types from server to client requires an additional metamethod:

While these examples are trivial, they serve to illustrate a compelling development paradigm that gives one a great deal of flexibility for development and testing with an embedded target.

Most Lua types can be transferred between the client and server states. The following list indicates which ones can be transferred, and where there are known exceptions: