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).

handle = rpc.connect( transport_identifiers )

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.