eLua has two different versions of the shell (check link:building.html[here] for information about how to enable each of them):
- the basic version is small (to keep the eLua image small), but functional. The documentation for the basic shell can be found link:simple_shell.html[here].
- the advanced shell (new in *0.9*) adds file masks, file operations and other goodies to the basic shell. If you have enough flash on your
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:
- write it to link:arch_romfs.html[the ROM file system] and execute it from there.
- use the _recv_ command from link:using.html#shell[the shell] to upload it to the board using a serial connection.
- write it to an sd/mmc card and, if your board supports it, execute it from there.
[[rpc]]
Controlling eLua with LuaRPC
----------------------------
_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:
- assign values to new or existing variables in the server state
- get values from variables in the server state
- call functions to be executed on the server side using parameters of serializable types, with return values being sent back to the client
- create local userdata helpers (aliases) which provide short-hand access to remote state
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.
Building eLua with RPC Boot
~~~~~~~~~~~~~~~~~~~~~~~~~~~
See link:building.html[building] for details and requirements for the building process. In order to boot into RPC mode, the RPC
link:building.html#components[component] will need to be enabled, and appropriate link:building.html#static[static configuration data] needs to be set.
To build eLua to boot into RPC mode, include *boot=luarpc* in the link:building.html#buildoptions[build options].
LuaRPC Basics
~~~~~~~~~~~~~
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:
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:
--------------------------------------
-- make table on remote server
slave.remote_table = {}
-- put data in table
slave.remote_table.rval = 42
-- get data back from server, print
local_table = slave.remote_table:get()
print(local_table.rval)
--------------------------------------
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.
Serializable Lua Types
~~~~~~~~~~~~~~~~~~~~~~
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:
