Remote file system (RFS)

eLua remote file system

(v0.8 and above) The RFS (Remote File System) is a file system that allows the user to "share" a directory on a PC with eLua over a serial connection. eLua will be able to access files on the shared PC directory just as they were local files; they can be opened, read, written, closed and so on. Developing in eLua becomes much easier with this file system: one can simply edit the source file on the desktop machine, using his favourite text editor, and run the file on the eLua board using lua /rfs/<file>.lua. The file can also be copied to (or from) the SD/MMC file system using the cp command in the eLua shell.

Enabling RFS in eLua

This is the easy part, just follow the instruction in the building page. You need to define the following macros for RFS:

Option Meaning

BUILD_RFS

Enable RFS support in eLua

RFS_BUFFER_SIZE

Size of the RFS buffer. Needs to be one of the BUF_SIZE_xxx constants defined in inc/buf.h

RFS_UART_ID

The ID of the UART that will be used by RFS. This is the physical connection over which the PC directory will be shared.

RFS_UART_SPEED

Communication speed of the RFS UART interface.

RFS_TIMER_ID

The ID of a timer that will be used by RFS for internal operations

RFS_FLOW_TYPE

Flow control type on the serial RFS interface, see here for details. If not specified it defaults to 'no flow control'.

RFS_TIMEOUT

RFS operations timeout (in microseconds). If during a RFS operation no data is received from the PC side for the specified timeout, the RFS operation terminates with error.

RFS server on the PC side

RFS needs a program running on the PC side, the RFS server. This is the program that implements the actual directory sharing (eLua connects to this program via the RFS_UART_ID UART). The RFS server was succesfully built and tested under Windows 7 (32 bit) and Linux (Ubuntu 10.10 64 bit). To build it you need:

  • a build environment. This means gcc under Linux (see for example here for instruction on how to install a toolchain in Ubuntu Linux) and a gcc-based development environment under Windows. How to install a gcc-based development environment under Windows is beyond the scope of this tutorial, but check here and here for possible solution (RFS server was compiled and tested under Win32 using the second soluation, the tdm gcc compiler).

  • scons. See here for details on how to install scons on Windows, or here for details on how to install scons on Linux.

If the above requirements are met, building the RFS server is a simple matter of invoking this command from the eLua source tree base directory:

scons -f rfs_server.py

After this you should end up with a rfs_server.exe file in Windows or a rfs_server file in Linux. Running it without arguments prints the usage help:

Usage: rfs_server <transport> <dirname> [-v]
  Serial transport: 'ser:<sername>,<serspeed>,<flow> ('flow' defines the flow control and can be either 'none' or 'rtscts')
  UDP transport: 'udp:<port>'
Use -v for verbose output.

Note that currently the UDP transport is only implemented in the RFS server, not in eLua, so you can only use the serial transport.
<dirname> is the name of the directory that will be shared with eLua. In Win32, a proper server invocation can look like this:

rfs_server ser:com5,115200 c:\elua\fs

This shares the c:\elua\fs directory on COM5 at baud 115200 (note that the baud must match the RFS_UART_SPEED configuration macro).
In Linux:

./rfs_server ser:/dev/ttyUSB0,115200,rtscts /home/user/work/fs

This shares the /home/user/work/fs directory on port /dev/ttyUSB0 at baud 115200.
Once the RFS server is in place, you can use it from eLua just like you’d use any other file system. For the previous example, if you have a file named /home/user/work/fs/test.lua and you want to run in eLua, you just need to do this from the eLua shell:

elua# lua /rfs/test.lua

Notes

Some things you should consider when using the RFS:

  • the code is still in beta. It works well most of the time, but sometimes it simply crashes. If this happens, please consider submitting a bug report.

  • using hardware flow control is strongly encouraged. To do this:

    1. make sure that your eLua board has support for hardware flow control (see here for details).

    2. specify the correct RFS_FLOW_TYPE value at build time (it should be PLATFORM_UART_FLOW_RTS | PLATFORM_UART_FLOW_CTS).

    3. make sure that the serial cable connecting the PC and the eLua board also supports flow control. Some simple serial connection cables have only the RX, TX and GND wires. RTS/CTS flow control requires at least RX, TX, RTS, CTS and GND wires arranged in a null-modem configuration.

    4. start rfs_server specifying rtscts as part of the <transport> parameter (see above).

  • eLua has a global filename size limit of 30 characters, so don’t put files with longer names in the shared directory, it might lead to unexpected behaviour.

  • the file sharing "protocol" is an extremely simple one, it doesn’t make provisions for error correction and has only very basic error detection. So, if there are serial communication problems on the connection used by RFS, you might encounter RFS errors (timeouts, invalid operations and so on). If the errors persist, simply restart rfs_server and reset the eLua board.

  • try not to share directories on devices that might go to sleep unexpectedly, such as an USB HDD attached to the PC, or a network storage device with a HDD that might also go to sleep. If you try to make an operation on such a shared directory and the device is asleep, it will take a while until it wakes up and during this time RFS will most likely time out (see RFS_TIMEOUT macro above). This, in turn, might confuse RFS completely and give strange errors, like being unable to list the contents of the directory on the eLua board. If this happens, restart rfs_server, reset the eLua board and try again.

  • for reasons similar to the above, if you’re running your server on a hosted virtual machine (ex: Virtualbox, VMWare, …), make sure the VM host has a steady clock and does not keep entering and leaving some energy-saving mode that changes the clock speed. If you work on this configuration (usually on laptops), just go to your energy-savings preferences and chose one that will not change the clock during the serial transfers. This is not mandatory for all scenarios. Just keep this in mind if you have some issues and change it only if needed.

  • the larger RFS_BUFFER_SIZE is, the better the performance, but obviously RAM consumption also increases.

  • some serial ports built around USB to RS232 adapters seem to confuse rfs_server sometimes. If RFS won’t work after you tried all the above instructions, or if rfs_server terminates unexpectedly, unplugging and plugging the USB cable of the RS232 adapter and restarting rfs_server will most likely solve your problem.

  • if you find a bug in the RFS server and wish to report it, try to reproduce the problem again, but this time run rfs_server with -v (verbose). The resulting logs may help us identify the problem.

Important If you like the RFS, but dislike the idea of having to connect your eLua board to the PC with two serial connections (one for the console and another one for the RFS) check here for a possible solution to this.