Quantcast FAQ - eLua Wiki
Locked History Attachments

FAQ

eLua Frequently Asked Questions

  • It is assumed that you already know what eLua is, so here's a list of questions and answers that you might find useful.

General aspects

Use

Advanced

Still unanswered questions

Please feel free to answer or comment these questions, as well as to add your own questions to be answered too.

  • What do you mean by "eLua transforms hardware in commodities"?


What are the minimum requirements for eLua?

It's hard to give a precise answer to this, because this is not only dependable on the footprint of eLua or it's resource requirements but on the final user applications as well. As a general rule, for a 32-bit CPU, we recommend at least 256k of Flash and at least 64k of RAM. However, this isn't a strict requirement. A stripped down, integer-only version of eLua can definitely fit in 128k of Flash and depending on your type of application, 32k of RAM might prove just fine. We have built eLua for targets with less than 10K RAM but you can't do much than blinking an LED with them. It really largely depends on your needs.

How can I learn Lua? Is it hard?

Lua is a minimalistic language (yet incredibly powerful!) which is quite easy to learn. Once you understand the basic concepts you'll find yourself writing Lua programs in notime. The main resource is the Lua homepage. In the documentation page you'll find the reference manual and the first version of the excellent "Programming in Lua" book. We recommend purchasing the second version of this book, since it's likely that this is all you'll ever need to learn Lua. Another very good resource is the Lua wiki. If you need more help, check the community page. Lua has a very friendly and active community. Most of all, Lua is FUN to learn and use :)

How can I help eLua?

eLua has many ambitious goals, so it would be great to have more people working on it. Take a look at the roadmap page and if you see something there that you'd like to work on, don't hesitate to contact us. Also, if you'd like to make a donation to the project (money, or maybe a development board) rest assured that we won't say no :) It also helps a lot if you test eLua on your own board and you find a bug or an incomplete feature. Or if you just thought about a cool feature that you'd like to see in eLua. If so, feel free to contact us.

Can I use eLua in my comercial, not-open source project?

Starting with version 0.6, eLua is distributed under a MIT license, so you can use it in your closed source projects. Prior to this, it was distributed under GPL, which restricted its usage to open source applications. Be careful though, because eLua includes some (few) 3rd party libraries, each with its own licensing terms that might be more restrictive than MIT. See the eLua license for details.

Is eLua fast enough?

This pretty much depends on what you expect. If you expect your Lua code to run as fast as your compiled C code, this won't happen, simply because C is a compiled language, while Lua is an interpreted language. That said, you'll be happy to know that Lua is one of the fastest interpreted languages out there and also compiles it's programs to bytecodes for it's own virtual machine to execute. If you really need both high speed and Lua, you can (very easily in eLua) write your speed critical code sections in C and export them as a Lua module. This way you get the best of both worlds.

We don't have any official benchmarks about Lua speed on embedded devices but you might want to check the TV-B-Gone example on the [examples.html examples page]. TV-B-Gone is a "software remote control" application coded directly in eLua. If you're familiar with the remote control protocols, you'll know that this kind of application is quite "real time" and delays in the order of milliseconds or even less can make your software remote control fail. Yet this sample runs without problems on a 50MHz Cortex-M3 in Thumb2 mode CPU. This should give you a fairly intuitive view on the speed of eLua. Of course, the project benefits from the incredible speed and performance of Lua. [portability ]

Since I'm using the eLua generic modules (uart, spi, pwm, tmr...), can I trust my aplications code to run the same on all my platforms?

Unfortunately, no. While eLua brings an unprecedent level of source code portability to the embedded world and makes it possible to have a common code on different platforms using the [arch_platform.html platform interface], it can't possibly provide the same functionality on all platforms, since all MCUs are not created equal. It is very recommended (and many times imperative) to have an understanding of the peripherals on your particular MPU before you start writing your code. This, of course, is not particular to eLua, but it's especially important since the platform interface might give the impression that it offers an uniform functionality over all platforms, when in fact the only thing in common is often just the interface itself (that is, the methods and variables you can access in a given module). eLua tries to help here by giving you an error when you try to access a physical resource that is not available (for example a timer, a PWM channel, or a PIO pin/port), but it doesn't try to cover all the possible platform-related issues, since this would increase the code size and complexity too much. These are some caveats that come to mind (note that these are only a few examples, the complete list is much longer):

  • Timers: some CPUs, like the Luminary Cortex CPUs, have rock solid 32-bit timers. You can do pretty much everything you need with them. Most platforms have only 16-bit timers though, which imposes some limits on the range of delays you can achieve with them. Make sure to use [en_refman_gen_tmr.html#tmr.getmindelay tmr.getmindelay(id)] and [en_refman_gen_tmr.html#tmr.getmindelay tmr.getmaxdelay(id)] to check the actual resolution of your timers and adapt your code accordingly. To 'compensate' for this, it's not possible to change the base timer frequency on the Cortex CPUs, but it is possible on most other platforms :) So be sure to also check the result of [en_refman_gen_tmr.html#tmr.setclock tmr.setclock(id)]. Important: when using timers, remember that if you're using XMODEM and/or the "term" module, one of them (generall TMR0) is also used by both of them. So, if you change the TMR0 base clock in your code, be sure to restore the original setting before returning to the eLua shell.

  • PWM: the Cortex-M3 CPUs have 6 PWM channels, but channels 0/1, 2/3 and 4/5 respectively share the same base clock setting. So, when you're changing the base clock for channel 1, you're also changing the base clock for channel 0; if channel 0 was already running, you won't like what will happen next. This time no eLua function can save you. You simply need you know your CPU architecture.

  • GPIO: only some platforms have internal pullups for the GPIO pins (others might also have pulldowns). However, in this case you're safe, as eLua will signal an error if you try to execute a pull-up/dn operation on a platform that does not support it.

The lesson here is clear: understand your platform first! [luaversions ]

What's the deal with floating-point Lua and integer-only Lua?

Lua is built around a number type. Every number in Lua will have this type. By default, this number type is a double. This means that even if your program only does integer operations, they will still be treated as floating-point doubles. On embedded platforms this can be a problem, since the floating point operations are generally emulated in software and this can be slow. This is why eLua gives you the choice of "integer only Lua": a Lua with the default number type changed to long integer. The advantages are increased speed and smaller code size (since we can force Newlib to "cut" the floating point code from printf/scanf and friends, which has quite a strong impact on the code size) and increased speed. The downside is that you'll loose the ability to do any floating point operations (although a separate module that will partially overcome this limitation will be provided in the future). [wincomp /

Is it possible to compile eLua under Windows?

Starting with version 0.7, compiling eLua under Windows is officialy supported, check [building_win.html here] for details. [windows ]

All your tutorials give instructions on how to compile eLua under Linux, yet you seem to use a lot of Windows tools. How come?

It's true that we do all the eLua development under Linux, since we find Linux an environment much more suited for development. At the same time it's true that most of the tools that come with my development boards run under Windows. So we choose to use the best of both world: Bogdan runs Linux under a [http://www.virtualbox.org VirtualBox] emulator and does everything else under Windows. Dado does everything on Linux and runs Windows under [http://www.vmware.com VMWare]. Both options are nice if you master your environment. To make everything even more flexible, Bogdan keeps his VirtualBox Ubuntu image on an external WD passport disk that he can carry with him wherever he goes, so he can work on eLua whenever he has a bit of spare time :) [cygwin ]

Will you ever post instructions about how to compile toolchains under Cygwin in Windows?

Bogdan: If I ever have way too much spare time on my hands, yes. Otherwise, no. There are many reasons for this. As I already mentioned, I favour Linux over Windows when it comes to developing applications. Also, I noticed that the GNU based toolchains are noticeable slower on Cygwin than on Linux, so experimenting with them can prove frustrating. Also, compiling under Linux and Cygwin should be quite similar, so try starting from my Linux based tutorials, they might work as well on Cygwin. [bytecode ]

I know that Lua can be compiled to bytecode, so I compiled one of the eLua examples with luac and tried to run it on my eLua board, but it didn't work. Is this a bug in eLua?

This is not a bug in eLua, it's a bit more subtle than that. See [using.html#cross the cross-compile section] for a full discussion about this problem and the right way to do it. Starting with v0.7, it is also possible to automatically build your ROM file system with only compiled (bytecode) code. See [en_arch_romfs.html#mode here] for details. [outofmemory ]

I get "out of memory" errors when I run my Lua programs, what should I do?

Although some kits and MCUs still have just the right ammount of ram for eLua, the evolution is fast and this will soon be a problem of the past. If you're having problems to make your application fit in a tight platform, here are some things you can try to overcome this:

  • enable the LTR patch: you can get very significant improvements if you enable the LTR patch in your eLua image. See [arch_ltr.html here] for more details about LTR and [building.html here] for instructions about enabling LTR. The LTR patch is enabled by default for some target platforms.

  • precompile your source to bytecode: if you use bytecode instead of source code Lua won't need to compile your source, so you save some RAM. Starting with v0.7, it is also possible to automatically build your ROM file system with only compiled (bytecode) code. See [en_arch_romfs.html#mode here] for details.

  • try to avoid using too many strings: strings are immutable in Lua. That means that a statement like s = s .. "\n" (where s is a string) will create a new string each time it's called. If this happens a lot (for example in a loop), your memory will quickly run out because of all the strings. If you really need to do frequent string operations, put them in a table and then use [http://www.lua.org/manual/5.1/manual.html#5.5 table.concat] to make a string from your table.

  • control Lua's garbage collection manually: if you're still running out of memory, try calling collectgarbage('collect') from your code, which will force a garbage collection and thus might free some memory.

  • use the emergency garbage collector (EGC): starting with version 0.7, eLua integrates Robert Jakabosky's excellent Emergency Garbage Collector (EGC) patch. It can help a lot with low memory problems. See [elua_egc.html here] for details on how to use the EGC patch in eLua. [rotables ]

I enabled the LTR patch, but now all my module tables (math, io, string, spi and so on) are read only. Do I have to disable LTR if I want write access to these modules?

You don't really have to disable LTR to get write access to your rotables, you can use some simple Lua "tricks" instead. Let's suppose that you need write access to the math module. With LTR enabled, math is a rotable, so you can't change its keys/values. But you can use metatables to overcome this limitation:

local oldmath = math
math = { __index = oldmath }
setmetatable( math, math )

This way you can use math in "write mode" now (since it is a regular table), but you can still access the keys from the original math rotable. Of course, if you need write access to all your modules (or to most of them) it makes more sense to disable LTR instead, but from our observations this doesn't happen in practice.