mirror of
https://github.com/elua/elua.git
synced 2025-01-08 20:56:17 +08:00
124 lines
8.3 KiB
Plaintext
124 lines
8.3 KiB
Plaintext
// $$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$$
|