elua/doc/en/examples.html

$$HEADER$$
<h3>Lua Code Examples</h3>
<p><b>eLua</b> distros come bundled with nice and fun
(yes! we have games too! :) Lua programs examples in the File System. They are also included in the <b>eLua</b>
source code distribution, under the <i>/romfs</i> subdirectory. As previously explained, you can run them directly from <b>eLua</b>'s file
system or you can use the eLua shell and send them via XMODEM, as
described <a href="using.html#shell">here</a>.</p>
<br />

<a name="hello" />
<h3>hello.lua: the ubiquitous "Hello, World!"</h3>
<p><strong>Runs on: </strong>all targets</p>
<p><strong>Description: </strong>to call this a "program" is a gross overstatement, but it's a
tradition, so we respect it :) It just prints "Hello, World!" on the terminal and
returns to the shell. Run it from the file system only if you feel too lazy to fire up
the lua interpreter inside eLua and write it yourself :)</p>
<br />

<a name="info" />
<h3>info.lua: getting the platform data</h3>
<p><strong>Runs on: </strong>all targets</p>
<p><strong>Description: </strong>this isn't really more advanced than "Hello, World!", but it does show
an <b>eLua</b> specific module: the platform data module (<b>pd</b>). You can read
more about the platform modules <a href="refman_gen_pd.html">here</a>. The program will display the platform
name, the CPU name, the board name and the CPU clock and then will exit
to the shell.</p>
<br />

<a name="led" />
<h3>led.lua: the old LED blinker, the new eLua way</h3>
<p><strong>Runs on: </strong> all targets except i386</p>
<p><strong>Description: </strong> now we get to do something "more embedded": blink a LED. The code illustrates a few interesting <b>eLua</b> features:</p>
<ul><li><b>cross platform code</b>: the code assigns a different pin
to the LED starting from the board name. You can see how the platform
data module makes it very easy to write such portable code.</li>
<li><b>uart, pio, tmr, pd modules</b>: they are all used here.</li></ul>
<p>Watch it blink, then press any key to return to the eLua shell.</p>
<br />

<a name="hangman=" />
<h3>hangman.lua: taking advantage of your terminal</h3>
<p><strong>Runs on: </strong>all targets</p>
<p><strong>Description: </strong>the geekiest example from the <b>eLua</b> distribution (or would it be morse.lua? :), it makes use of
the <a href="refman_gen_term.html">term module</a> to let the user play a BSD-like "hangman" directly in his terminal emulator. Run the example
and enjoy. Currently it has a very small list of words, as this was
written mainly as a proof of eLua's capabilities, but it's very easy to
add new words/replace the existing ones.</p>
<br />

<a name="pwmled=" />
<h3>pwmled.lua: LED blinker, advanced class</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965</p>
<p><strong>Description: </strong>this uses the PWM module to fade the on-board LED in and out, in an
infinite loop. Not much to say here, the code is very simple, yet the
results are quite spectacular. Press any key to end the sample and
return to the shell.</p>
<br />

<a name="dualpwm=" />
<h3>dualpwm.lua: because a single LED is just not enough</h3>
<p><strong>Runs on: </strong>MOD711, ET-STM32</p>
<p><strong>Description: </strong>My <a href="http://www.sctec.com.br/content/view/101/30/">MOD711 board</a> needed a
"motherboard" for a few components (mainly the RS232-TTL level converter and a reset button) so I also added two LEDs to it, connected
to two different PWM channels. With this program, the two LEDs fade at the same type, but in different directions.</p>
<br />

<a name="tvbgone" />
<h3>tvbgone.lua: yes, eLua can do real time!</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965</p>
<p><strong>Description: </strong>this is more complex, but also very important for <b>eLua</b>, because it
proves that real time applications (with relatively strict timing
requirements) can run from <b>eLua</b> directly. It's the famous TV-B-Gone
project adapted from <a href="http://www.ladyada.net/make/tvbgone/">LadyAda's kit</a>.
If you're not familiar with TV-B-Gone, it knows how to do one thing
very well: power off your TV :) Basically it contains a lot of remote
control codes (for a lot of TVs) that are continuously sent via an IR
LED. This code uses the PWM module (new in <b>eLua</b> 0.4) and it also does
file I/O from Lua, since the remote control codes are kept in a
separate file (which is also part of the ROM file system). To read the
binary file, the "pack" module (also new in 0.4) is used. To ensure
that we don't get any unexpected delays, the Lua garbage collector is
turned off. Take a look at this sample, it's both a very good proof of
the capabilities of eLua and a good learning resource.<br>
To use it on EK-LM3S8962 or EK-LM3S6965 connect an IR LED
with a resistor between the "PWM2" and "GND" pins of the extension
connector. Get close to your TV and press the "select" button on your
board to start sending the IR codes. The on-board LED stays lit while
the codes are transmitted and shuts off afterwards. Press the "down"
button on your board to exit the application and return to the shell.</p>
<br />

<a name="piano" />
<h3>piano.lua: because PWM is great</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965, SAM7-EX256</p>
<p><strong>Description: </strong>yet another use for the PWM module, this sample can be used to "play"
notes via the on-board speaker using the PC keyboard. The on-screen
keyboard shows what keys you must press for different notes, and you
can set your octave and inter-note delay. Press ESC to end your <b>eLua</b>
musical session :)</p>
<br />

<a name="bisect" />
<h3>bisect.lua: floating point at its best</h3>
<p><strong>Runs on: </strong>all targets</p>
<p><strong>Description: </strong>this is taken directly from the official Lua distribution, and it's
here to show that <b>eLua</b> can do floating point just like on a desktop
machine, albeit slower. Run it on your target, then run it again, but
this time on the PC, and compare the results. Yes, they are identical.</p>
<br />

<a name="life" />
<h3>life.lua: the game of life</h3>
<p><strong>Runs on: </strong>i386</p>
<p><strong>Description: </strong>another example taken directly from the Lua distribution, this time
the well known <a href="http://en.wikipedia.org/wiki/Conway%27s_Game_of_Life">game of life</a>.
Start it and enjoy. Only included on i386 by default because it's faster on i386, but it can run on other
platform too (although it requires quite a bit of memory, which is not a problem for boards with external
memory). </p>
<br />

<a name="morse" />
<h3>morse.lua: because PWM is great, part II</h3>
<p><strong>Runs on: </strong> EK-LM3S8962, EK-LM3S6965, SAM7-EX256</p>
<p><strong>Description: </strong>this uses the same PWM module for Morse code generation. Just enter a
text, and listen to it getting Morsed on your board's speaker and on a blinking Led. The
letters and Morse codes are also shown on the terminal. Use '+' and
'-'' to change the frequency, up and down arrows to change the speed,
's' to mute/unmute, and ESC to exit.</p>
<br />

<a name="lhttpd" />
<h3>lhttpd.lua: only with (e)Lua ...</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965, EAGLE-100, EK-LM3S9B92</p>
<p><strong>Description: </strong>this is one of those things that can show the real potential of a
language (and hopefully the real potential of <b>eLua</b> in this case). As
you have probably guessed by now, it's a web server&nbsp;written in Lua.
Except that it is much more than this: it's a <b>scripting web server!</b> That's
right, you can embed parts of Lua code into your pages, and the server
will parse them and replace the Lua code with its output. To output
something from Lua code embedded in a web page, simply use "print" in
your Lua code. You can also write your pages completely in Lua (again,
using "print"), the server knows how to handle this too. When is the
last time you heard about a scripting web server in 256k of Flash/64k
of RAM?&nbsp;</p><p>The full list of features is given below:</p>
<ul>
<li>completely written&nbsp;in Lua</li>
<li>can handle a single connection at a time (for now)</li>
<li>can serve text and images (so far)</li>
<li>gets its files from the ROM file system (this will be extended when more
 filesystems are added)</li>
<li>can execute embedded Lua code and replace it with its output (via "print" statements). Embed Lua
 code in your HTML files between tags, make sure
your HTML file extension is ".pht", and the server will preprocess it
and replace the Lua code with its output</li>
<li>if a file with ".lua" extension is requested, it doesn't send the file, but
 executes it and sends its output (via "print" statements)</li></ul>
<p>This is still work in progress, but it already works quite well.
Take a look at <i>romfs/index.pht</i> and <i>romfs/test.lua</i> from the source
distribution for an example of how to include Lua code in your HTML
files.</p>
<br />

<a name="adcscope" />
<h3>adcscope.lua: ADCs and eLua, part I</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965, ET-STM32</p>
<p><strong>Description: </strong>This uses the ADC module to acquire samples as quickly as possible on available ADC channels, and display them using the term module.  Additionally, for different channels, different length moving average filters are used to smooth the data being acquired (see the adcchannels and adcsmoothing variables).  While running the script also provides the average length of time required to get conversion results from each channel and the amount of memory used by garbage collectable objects in the running Lua environment.
</p>
<br />

<a name="adcpoll" />
<h3>adcpoll.lua: ADCs and eLua, part II</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965, ET-STM32</p>
<p><strong>Description: </strong>This is another example of the ADC and term modules.  This version uses hardware timers to acquire samples deterministically at a rate of 4 samples per second.  When run, note that data from some channels appear before that of others.  This is due to the moving average (smoothing) filter being enabled.  This filter will only return conversion results after enough samples are acquired to fill the filter length.  In addition, this example utilizes a polling mechanism.  When adc.getsample or adc.getsamples return nil, no samples were available to be returned.  Values for each channel, in this example, are only displayed when there is a non-nil value returned by adc.getsample.
</p>
<br />

<a name="logo" />
<h3>logo.lua: graphics and eLua</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965</p>
<p><b>Description: </b>a complex example, proving that <b>eLua</b> can do even animations! The <b>eLua</b> logo is shown
on the on-board OLED display and then <b>rotated in realtime</b>. You can get about 3fps with this example. Not bad for a bitmap
rotation application that uses quite a lot of emulated floating point computations at 50MHz. Optimizations are still
possible, but are left (for now) as an exercise for the <b>eLua</b> apprentice. Take a look at the code to discover
how a highly optimized eLua program looks like, but don't spend too much time with it if your math feels rusty :)
</p>
<br />


<a name="pong" />
<h3>pong.lua: eLua meets a classic</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965</p>
<p><b>Description: </b>a tribute to the classics, as well as an addictive way of spending your time, this examples proves
without any doubt that you can write games with <strong>eLua</strong>. This variant of the well known "pong" games plays on 
the OLED display of your LM3S board, using the on-board switches to control your paddle. Hit the ball, collect or avoid the 
"bonuses", a keep on trying to beat that highscore :) The code is just complex enough to give you a fair idea about the
possibilities of <b>eLua</b>.
</p>
<br />

<a name="spaceship" />
<h3>spaceship.lua: even more fun</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965</p>
<p><b>Description: </b>tired of hitting a ball? What about hitting a spaceship instead? Or, even better, more spaceships? Defend
your base with this little game that also plays on the OLED display of your LM3S board and uses the on-board switches as
paddles. Once again, take a look at the code to get a feeling of <b>eLua</b>.
</p>
<br />

<a name="tetrives" />
<h3>tetrives.lua: don't let it get too addictive</h3>
<p><strong>Runs on: </strong>EK-LM3S8962, EK-LM3S6965</p>
<p><b>Description: </b>tetris doesn't need any introduction at all, so just start the game, grab the on-board switches and start
making lines after lines on your OLED display. Once you're done playing, you might want to take a look at the code. This example 
is fairly complex, large, uses <b>eLua</b> specific techniques (explicit memory management with calls to the garbage collector) and might 
serve as a good base for your own code.
</p>

$$FOOTER$$