So, you already built and installed eLua, but now you don't know what to do with it. It's actually quite easy: all you need is your board connected to the computer and a terminal emulation program. If you're using Windows, I strongly recommend TeraTerm. It's a freeware, it's very powerful and also easy to use. On Linux, you'll probably be stucked with minicom. It's not exactly intuitive, and it runs in text mode, but it's still very powerful, and if you google for "minicom tutorial" you'll get the hang of it in no time. Or you can try any other terminal emulator, as long as you set it up properly (and as long as 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).
- 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 LM3S7862 board 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.
After you press the "RESET" button on your board, you should see the eLua shell prompt. Up to date documentation of how to use the shell is always included in the distribution (docs/the_elua_shell.txt). For your convenience, the shell documentation is also provided on this page.
The eLua shell
After you burn eLua to your board and you connect the board to your terminal emulator running on the PC, you'll be greeted with the eLua shell prompt, which allows you to:
- run 'lua' as you would run it from the Linux or Windows command prompt
- upload a Lua source file via XMODEM and execute in on board
- query the eLua version
- get help on shell usage
To enable the shell, define BUILD_SHELL in your build.h file, and also BUILD_XMODEM if you want to use the "recv" command (see below). See docs/elua_components.txt for more details about enabling the shell.
You'll need to configure your terminal emulation program to connect to your eLua board. These are the parameters you'll need to set for your serial connection:
- speed 115200, 8N1 (8 data bits, no parity, one stop bit)
- no flow control
- newline handling (if available): CR on receive, CR+LF on send
After you setup your terminal program, press the RESET button on the bord. When you see the "eLua# " prompt, just enter "help" to see the on-line shell help:
eLua# help
Shell commands:
help - print this help
lua [args] - run Lua with the given arguments
recv - receive a file (XMODEM) and execute it
ver - print eLua version
exit - exit from this shelll
More details about some of the shell commands are presented below.
The "recv" command
To use this, your eLua taret image must be built with support for XMODEM (see docs/elua_components.txt for details). Also, your terminal emulation program must support sending files via the XMODEM protocol. Both XMODEM with checksum (the original version) 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.
The "lua" command
This allows you to start the Lua interpreter with command line parameters, just as you would do from a Linux or Windows command prompt. This 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 ' 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 '' and "" for string quoting, 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
