elua/doc/en/overview.txt

// $$HEADER$$
[[overview]]
What is eLua?
-------------

eLua stands for *Embedded Lua* and the project aims to offer the full
implementation of the http://www.lua.org[Lua Programming Language] to
the embedded world.

eLua is not a stripped down set of Lua to fit in the embedded
environment. Much on the contrary, it strives to offer the same
features as the desktop version of Lua, complementing them with
specific features for embedded use and discarting the need of an
operating system running on the microcontrollers.  Besides offering
different flavors of the full Lua implementation (like the possibility
of choosing between an integer-only and a floating point numbers
implementation), a lot of work was and will be done in the direction
of making Lua more "embedded-friendly" by augmenting the core language
with features that allow lower memory requirements and faster embedded
performance.

Why Lua? Extremely well crafted, Lua is the perfect example of a
minimal, yet fully functional language.  Although generally advertised
as a "scripting language" (and used accordingly especially in the game
industry), it is also fully capable of running stand-alone programs
and web services (ex: Adobe Lightroom, World of Warcraft, ...). Its
limited resource requirements make it suitable to a lot of
microcontroller families. The intrinsic high portability of the
original Lua code (which is ANSI C and runs virtually on every
platform), combined with the highly portable software architecture of
eLua, allow for easy porting of the project to a large variety of
architectures. The peripheral access libraries/modules exported by
eLua are also portable by design, so one could run a Lua program
(without or with very few modifications) on every eLua supported
platform.  This brings an unprecedent level of portability to the
embedded aplications world. eLua inherits the minimalistic and
functional design of Lua, staying in line with the well known *KISS*,
_Keep It Small and Simple_ philosophy.

The aim of the project is to have a fully functional Lua development
environment *on the microcontroller itself*, without the need to
install a specific development environment on the PC side, other than
a serial or ehternet console/terminal emulator.

We can't end this short presentation without presenting our project
motto: No matter what you do with eLua, always remember to have Fun
with it :)

[[features]]
General Features
----------------

As already stated, eLua allows you to run Lua completely on the target
microcontroller. A fast-growing set of complementary modules is also
provided, for programming eLua microcontroller's peripherals.


The following important features are ready or being implemented:

* a flexible, configurable build system and a web build service under
  development.

* access to the Lua interpreter on the target MCU via a variety of
  physical transports (RS-232, Ethernet, ...).

* a (mostly) platform independent MCU peripheral library (PIO, UART,
  PWM, SPI, TMR, ADC, NET, CAN, DAC, I2C...)

* a very low footprint embedded ROM file system, easy to port to
  different types of memory chips and other storage devices

* a small FAT R/W file system layer for SD/MMC cards

* a minimal command "shell", for file operations, environment
  configuration and other facilities

* tcp/ip network support

* remote procedure calls support. Distributed processing in the
  embedded world

* an embedded http server

* extended (romable) Lua types, optimized for embedded performance

* terminal/console over Serial and Ethernet protocols

* debugging (directly on the MCU or remotely with the PC)

* rfs support. Remote file sharing on the embedded world

* full and stand alone implementation on all MCUs. No dependency on
  embedded operating systems

* online and offline access to (same format) documentation and tutorials


For more information about the functionality (implemented and planned)
in eLua check link:status.html[our status page].

Porting eLua to another compatible platform should be as easy and
painless as possible. Currently this is restricted to platforms for
which the gcc+newlib combo is available. This restriction will
disappear in the near future, as eLua will have its own libc and thus
it will be available on a much broader range of MCUs.

The Lua implementation is the full desktop Lua version and comes in
two flavors: "regular Lua" (using floating point as the number type)
and "integer Lua" (using integers). "Regular Lua" will be able to
perform floating point operations (slower because the floating point
operations will be emulated in software on the MCU), while "integer
Lua" will only be able to perform operations with integer numbers (but
support for fixed and even floating point can be added with separate
modules) and thus will be faster.

[[audience]]
Audience
--------

eLua has a wide and varied audience, starting from newcomers to the
embedded world who want an easy and powerful environment for
prototyping, rapid application development and quick production, and
ranging towards highly skilled developers that want to extend their
programs with the Lua library facilities and portable features.

eLua allows embedded-oriented programmers to use the simplicity and
power of the Lua programming language and to hide the low-level
complexities and platform/architecture-dependent features. With eLua,
the programmer can focus on the actual implementation of his program,
without having to worry about accessing the low-level peripheral
configuration and data registers, as the platform libraries already
take care of this. This increases productivity and eliminates the
often frustrating task of dealing with platform-specific drivers.


The list below summarizes eLua's target audience:

* Embedded developers that are looking for a fast, easy to use and
  powerful way of coding.

* First-time embedded programmers (or simply first time programmers)
  who are looking for an easy way to "dive" into the embedded
  programming world. eLua is a great learning tool.

* People that aren't really developers, but still want to be able to
  prototype an embedded system fast and painless, without having to
  learn C for that.  Embedded developers who need powerful
  meta-language mechanisms for complex code algorithms and data
  description.

* Field engineers that can go to their customer site and debug an eLua
  module on site, without any preparation at all, since the whole
  development environment resides on chip already.

* Final clients and decision makers, who benefits from the fact that
  eLua portability transforms hardware into comodities. In systems
  using eLua, replacing field sensor and actuator controllers by
  diferent models, brands and architectures have no impact on the main
  application software.

[[authors]]
Authors
-------

eLua is a joint project of link:overview.html#contacts[Bogdan Marinescu], a
software developer from Bucharest, Romania and
link:overview.html#contacts[Dado Sutter], head of the Led Lab at PUC-Rio
University, in Rio de Janeiro, Brazil.

Its origins come from the
http://www.circuitcellar.com/renesas2005m16c/winners/1685.htm[ReVaLuaTe]
project, also developed by Bogdan Marinescu (as a contest entry for
the 2005 Renesas M16C Design Contest), and the Volta Project, managed
by Dado Sutter at PUC-Rio from 2005 to 2007.

eLua is developed in an fully open, distributed and colaborative
model. An always growing list of collaborators, from all over the
planet, can be found in our link:comunity.html#credits[Credits Page].

[width="70%", align="center", cols="^,^", options="header"]
|====================================================================================================================
| *ReVaLuaTe Project*                                           | *Volta Project*
| image:images/terminalreneseas.jpg[ReVaLuaTe project picture] | image:images/volta-small.jpg[Volta project picture]
|====================================================================================================================

[[contacts]]
Contacts
--------

eLua authors can be contacted at:

Bogdan Marinescu: bogdan.marinescu -at- eluaproject -dot- net

Dado Sutter: dadosutter -at- eluaproject -dot- net

James Snyder: jbsnyder -at- eluaproject -dot- net

You are also welcomed to share your questions and suggestions on our
link:comunity.html#lists[Mail Discussion List]

[[license]]
License
-------

eLua is Open Source and is freely distributed under the MIT license.

The Lua code (with all the eLua specific changes) is included in the
source tree and is, of course, licensed under the same 
http://en.wikipedia.org/wiki/MIT_License:[MIT license that Lua uses].

Other (few) components have different licenses. Please see the file
LICENSE in the source distribution for details.

The Lua part of eLua is licensed under the Lua licensing terms, which 
you can find at http://www.lua.org/license.html.

The XMODEM code is adapted from the FreeBSD at91 library, which was
written by M. Warner Losh and is released under the BSD license.

The "pack" module is adapted from the "lpack" module by Luiz Henrique
de Figueiredo and it's placed in the public domain.

The "bit" module is adapted from the "bitlib" library by Reuben
Thomas, distributed under a MIT license.

The "integer only lua" is based on the "Go Long Lua!" patch by
John D. Ramsdell (from the Lua Power Patches page) and is placed in
the public domain.

The multiple memory allocator (dlmalloc) is written by Doug Lea and is
placed on the public domain.

The TCP/IP stack is adapted from uIP, written by Adam Dunkels and
released under a BSD license.

The FAT file sistem is based on FatFs, written by 
http://elm-chan.org/[Elm Chan]. A copy of the FatFs license can be
found in the LICENSE.fatfs file.

The RPC implementation is based on Russell Smith's
http://q12.org/lua/index.html[Lua-RPC] A copy of the Lua-RPC license 
can be found in the LICENSE.luarpc file.

Manufacturer provided CPU support libraries are licensed under their
own terms. Check src/platform/*platform-name* for details of each
license.

https://github.com/antirez/linenoise[linenoise] (eLua's readline replacement) 
is released under a BSD license. 

The rest of the eLua code is licensed under MIT.

// $$FOOTER$$