eLua reference manual - LuaRPC module
Overview
LuaRPC allows one to remotely control a lua state running on another machine or microcontroller.
It works by providing a handle to the client session which allows control over remote state. Functions can be called in the remote environment and variables can be manipulated by treating the handle (representing the remote global table) as if it were a local table.
In order to open a connection, it is necessary to specify the interface through wich the connection is made. Currently the connections are limited to serial ports on the desktop side, and uart devices on the eLua side. For a number of the connections below, a parameter labeled transport_identifiers is used to specify the port to be used in a platform specific manner.:
- eLua: transport_identifiers = uart_id, timer_id
- uart_id - the ID of the serial port (as in the uart module). This uart must already be configured using uart.setup before being used in this module.
- timer_id - the ID of the timer for send/receive timeouts (as with send/receive functions in the uart module)
- Linux/Mac OS X luarpc: transport_identifiers = uart_path
- uart_path - the path to the serial port to use (e.g.: "/dev/ttyS0")
See Using eLua for a basic tutorial on getting started with the RPC module.
NOTE: This module is considered experimental. It currently works over a serial port with eLua targets and on desktop systems implementing POSIX serial communications (Linux, Mac OS X, etc).
Functions
handle = rpc.connect( transport_identifiers )
Initiate connection from client to server.
Arguments: transport_identifiers - platform-specific serial port identification (see overview)
Returns: handle - handle used to interact with the remote Lua state. Usage styles are as follows:
| Usage Style | Meaning |
|---|---|
| handle.remote_var = local_var | send contents of local_var to remote host and assign to remote_var (registered on global table). This also works where the destination variable is nested within tables. |
| local_var = handle.remote_var:get() | get contents of remote_var from remote global table and assign to local_var. |
| val1, val2, valn = handle.remote_func() | call remote_func on the server side, and return values to local state |
| helper = handle.remote_var | create a helper which points to remote_var, and can be used as shorthand later (e.g.: helper:get() would get the contents of the remote variable. If remote_var were a table with functions on it: helper.funcname() would call funcname, on table remote_var on the server, and return any results.) |
rpc.close( handle )
Close an active RPC session.
Arguments: handle - handle associated with the connection.
Returns: nothing.
rpc.server( transport_identifiers )
Start a blocking/captive RPC server, which will wait for incoming connections.
Arguments: transport_identifiers - platform-specific serial port identification (see overview)
Returns: nothing.
rpc.on_error( err_handler )
Define client-side error handler to deal with server-side error responses.
Arguments: err_handler - function to handle error messages. string error messages may be passed to this function.
Returns: nothing.
server_handle = rpc.listen( transport_identifiers )
Open a listener on transport and await incoming connections.
Arguments: transport_identifiers - platform-specific serial port identification (see overview)
Returns: server handle to use with rpc.peek and rpc.dispatch
data_available = rpc.peek( server_handle )
Check if data are available to read on transport.
Arguments: server_handle - handle to refer to server session, created by rpc.listen
Returns: data_available - 1 if data are available, 0 if data are unavailable
rpc.dispatch( server_handle )
Read transport and handle incoming command.
Arguments: server_handle - handle to refer to server session, created by rpc.listen
Returns: nothing.