elua/doc/en/arch_rfs.txt

// $$HEADER$$
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 link:fatfs.html[SD/MMC file system] using the
*cp* command in the link:using.html#shell[eLua shell]. 

Enabling RFS in eLua
~~~~~~~~~~~~~~~~~~~~
This is the easy part, just follow the instruction in the link:building.html[building page]. 
You need to define the following macros for RFS:

[width="90%", cols="<2s,<5", options="header"]
|===================================================================
^|  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 link:arch_platform_uart.html#flow_control_type[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 link:tc_arm.html[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 http://www.mingw.org/[here] and http://tdm-gcc.tdragon.net/[here] for possible solution
  (RFS server was compiled and tested under Win32 using the second soluation, the tdm gcc compiler).
- scons. See link:building_win.html[here] for details on how to install scons on Windows, or link:building_unix.html[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 link:refman_gen_uart.html#platform_uart_set_flow_control[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 link:sermux.html[here] for a possible solution to this. 

// $$FOOTER$$