Modules</h2>A Generic eLua Module is a module that can be used by a Lua program running on any of the <ahref="status.html#platforms">supported eLua platforms</a>.<br>Write your code once and it is already automatically ported to the main platforms of the embedded world.<br><br><br><br><br><br><br><br><br><br><h3><aname="bitmodule"></a>bit</h3>
[cpu.enableinterrupts()] <fontface="Bitstream Vera Sans Mono, sans-serif">sei(): enable
CPU interrupts</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;">
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><br>
</font></p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="cpu_clockfrequency"></a>[cpu.clockfrequency()]
Clock = clock(): returns the CPU frequency</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">Also, you can
expose as many CPU constants (for example memory mapped registers)</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">as you want to
this module. You might want to use this feature to access some </font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">CPU memory areas
(as defined in the CPU header files from the CPU support </font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">package)
directly from Lua. To do this, you'll need to define the </font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">PLATFORM_CPU_CONSTANTS
macro in the platform's platform_conf.h file </font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">(src/platform/<platform
name>/platform_conf.h). Include all your constants in a </font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">_C(
<constant name> ) definition, and then build your project.</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">For example,
let's suppose that your CPU's interrupt controler has 3 memory</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">mapped
registers: INT_REG_ENABLE, INT_REG_DISABLE and INT_REG_MASK. If you want</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">to access them
from Lua, locate the header that defines the values of these</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">registers (I'll
assume its name is "cpu.h") and add these lines to the</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">platform_conf.h:</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">#include "cpu.h"</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">#define
PLATFORM_CPU_CONSTANTS\</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">_C(
INT_REG_ENABLE ),\</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">_C(
INT_REG_DISABLE ),\</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">_C( INT_REG_MASK
)</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">After this
you'll be able to access the regs directly from Lua, like this:</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">data = cpu.r32(
cpu.INT_REG_ENABLE )</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">cpu.w32(
cpu.INT_REG_ENABLE, data )</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">For a
"real-life" example, see the src/platform/lm3s/platform_conf.h file.</font>
</p>
<pstyle="margin-bottom: 0in;">
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">[uart.sendstring]
uart.sendstr( id, str1, str2, ... ): this is similar to "uart.send",
<b>pio</b></p><pclass="MsoNormal"style="font-family: Verdana;">Programable Input Output Module</p><pclass="MsoNormal"style="font-family: Verdana;">Some notes on PIO:</p><ul><li>pio: only
some platform have internal pullups for the pio pins, while Cortex is
the only platform that also provides pulldowns for its pios. However,
in this case you're safe, as eLua will signal an error if you try to
execute a pullup operatin on a platform that does not support it.</li></ul><pclass="MsoNormal"style="font-family: Verdana;">
pio.nopull( Pin1, Pin2, ... ): disable the pullups/pulldowns on the
specifiedpins. Note that some CPUs might not provide this feature.
</p>
<br>
<h3><aname="netmodule"></a>net</h3>
<br>
<h3><aname="pwmmodule"></a>pwm</h3>
<spanstyle="font-weight: bold;"></span><br>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">It allows Lua to
use the PWM blocks on the target CPU.</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><strike><aname="pwm_setup"></a>[pwm.setup]</strike>(</font><fontface="Bitstream Vera Sans Mono, sans-serif">pwm.setup( id,
frequency, Active Cycle ) </font><fontface="Bitstream Vera Sans Mono, sans-serif">
Data = pwm.setup( id, frequency, duty ): sets the PWM block 'id' to
generate the specified frequency with the specified duty cycle (duty is
an integer number from 0 to 100, specifying the duty cycle in
percents). It returns the actual frequency set on the PWM block.</font>
</p>
<pstyle="margin-bottom: 0in;">
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"> Here there is a bigger
change on the proposal.
</p>
<pstyle="margin-bottom: 0in;"> The Timer Clock and the
PWM "frame" frequency would be set up in the same function (.setup)
</p>
<pstyle="margin-bottom: 0in;"> The normal control
function would only set the active cicle (.setcycle)
</p>
<pstyle="margin-bottom: 0in;"> The original .setup
function would then be replaced by:
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">[pwm.setup( id,
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="pwm_start"></a>[pwm.start()]
pwm.start( id ): start the PWM block 'id'.</font>
</p>
<pstyle="margin-bottom: 0in;">
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="pwm_stop"></a>[</font><fontface="Bitstream Vera Sans Mono, sans-serif">pwm.stop()]
</font><fontface="Bitstream Vera Sans Mono, sans-serif">pwm.stop(
id ): stop the PWM block 'id'.</font>
</p>
<br>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="pwm_setclock"></a>Data = pwm.setclock( id, clock ):
set the base clock of the PWM block 'id' to</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">the given clock.
In returns the actual clock set on the PWM block.</font>
</p>
<pstyle="margin-bottom: 0in;"><br>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">[</font><fontface="Bitstream Vera Sans Mono, sans-serif"><strike>pwm.getclock</strike>]
</font><fontface="Bitstream Vera Sans Mono, sans-serif">Data
= pwm.getclock( id ): returns the base clock of the PWM block 'id'.</font>
<fontstyle="font-family: Helvetica,Arial,sans-serif;"size="2"><big>Sending multiple data/chars in a single
call and not in
a table argument does not allow the data to be built in run time
(without some string massage, of course :)</big></font><br>
<br>
<br>
<br>
</big>
<h3><aname="sysmodule"></a>sys</h3>
<br>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="sys_platform"></a>[sys.platform()]
pd.platform(): returns the platform name (f.e. LM3S)</font>
</p>
<pstyle="margin-bottom: 0in;">
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="sys_mcu"></a>[sys.mcu()]
pd.cpu(): returns the CPU name (f.e. LM3S8962)</font>
</p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="sys_cpu"></a>[sys.cpu()]
would return ARM Cortex M3 in this case.....</font></p>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><br>
</font></p>
<fontface="Bitstream Vera Sans Mono, sans-serif"> <aname="sys_board"></a>[sys.board()]</font><fontface="Bitstream Vera Sans Mono, sans-serif">
pd.board(): returns the CPU board (f.e. EK-LM3S8962)</font>
<pstyle="margin-bottom: 0in;"><br>
</p>
<h3><aname="term_termmodule">term</a></h3>
Terminal support
<p><aname="term_clear"></a>[term.clear]
term.clrscr(): clear the screen </p>
<p> <br>
<aname="term_cleareol"></a>[term.cleareol]
term.clreol(): clear from the current cursor position to the end of the
line </p>
<p> </p>
<p><aname="term_moveto"></a> [term.moveto]
term.gotoxy( x, y ): position the cursor at the given coordinates<br>
</p>
<br>
<p><aname="term_moveup"></a> [term.moveup]
term.up( delta ): move the cursor up "delta" lines </p>
<p> </p>
<p><aname="term_movedown"></a> [term.movedown]
term.down( delta ): move the cursor down "delta" lines </p>
<p> </p>
<p><aname="term_moveleft"></a> [term.moveleft]
term.left( delta ): move the cursor left "delta" lines </p>
time difference).</font></p><pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif">Some notes on timers:</font></p><ul><li>timers: from all the platforms on which eLua runs, only
the Luminary Cortex CPUs has rock solid 32-bit timers. You can do
pretty much everything you need with them. All the other platforms have
16-bit timers, which imposes some limits on the range of delays you can
achieve with them. Make sure to use tmr.mindelay(id) and
tmr.maxdelay(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 tmr.setclock(id)</li><li>also, when using timers,
remember that if you're using XMODEM and/or the "term" module, TMR0 is
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
shell. You can change this static timer assignment by modifying
src/main.c. It might also be possible to change it dynamically in the
future, although I see little use for this.</li><li>PWM: the
Cortex 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.</li></ul><pstyle="margin-bottom: 0in;">
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="uart_setup"></a><spanstyle="font-weight: bold;">uart.setup(</span></font><fontstyle="font-weight: bold;"face="Bitstream Vera Sans Mono, sans-serif"> id, baud,
</p><pstyle="margin-bottom: 0in; font-weight: bold;"><fontface="Bitstream Vera Sans Mono, sans-serif">uart.PARITY_EVEN
| uart.</font><fontface="Bitstream Vera Sans Mono, sans-serif">PARITY</font><fontface="Bitstream Vera Sans Mono, sans-serif">_ODD | uart.</font><fontface="Bitstream Vera Sans Mono, sans-serif">PARITY</font><fontface="Bitstream Vera Sans Mono, sans-serif">_NONE, </font>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><spanstyle="font-weight: bold;"></span> Set the UART interface with the given
parameters.</font></p><pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"> Returns the actual baud rate that was set for the UART.</font>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="uart_send"></a></font><fontface="Bitstream Vera Sans Mono, sans-serif"><spanstyle="font-weight: bold;">uart.send( id,
Data1, Data2, ... )</span></font></p><pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><spanstyle="font-weight: bold;"></span> Send all the data to the specified UART interface.</font>
<pstyle="margin-bottom: 0in;"><fontface="Bitstream Vera Sans Mono, sans-serif"><aname="uart_recv"></a></font><fontface="Bitstream Vera Sans Mono, sans-serif">uart.recv(</font><fontface="Bitstream Vera Sans Mono, sans-serif"> id,
Modules</h2>A Platform Dependent eLua Module is a module that runs only on one or on a few <ahref="status.html#platforms">supported eLua platforms</a>.<br>These
modules make use of specifical devices and features offered by some
kits and allow eLua aplications to make the best use of the external
hardware on your platforms.<br><h3><aname="adcmodule"></a>adc - Analog to Digital Conversion Module</h3><spanstyle="font-weight: bold;">Currently runs on:</span> LM3Sxxxx<br><br> The ADC module handles the Analog to Digital Conversion Peripherals.<br><br><br><aname="adc_sample"></a><spanstyle="font-weight: bold;">adc.sample(channel_id)</span><br> Generate one processed sample.<br><br><br><aname="adc_getsamples"></a><spanstyle="font-weight: bold;">adc.getsamples(channel_id,
[count])</span><br> Request <spanstyle="font-style: italic;">count</span> samples from the buffer.<br> if singular, an
<spanstyle="font-style: italic;">count</span> is either zero or omitted, all available samples are returned.<br><br><br><aname="adc_maxval"></a><spanstyle="font-weight: bold;">adc.maxval(channel_id)</span><br> Returns the largest integer one can expect fromr this channel on a given platform (based on bit depth).<br><br><br><aname="adc_samplesready"></a><spanstyle="font-weight: bold;">adc.samplesready(channel_id)<br></span> Returns the number of samples waiting in the buffer.<br><br><br><aname="adc_dataready"></a><spanstyle="font-weight: bold;">adc.dataready(channel_id)<br></span> If running in non-blocking mode, this will indicate if all of the
requested samples to be captured before returning.<br> <spanstyle="font-style: italic;">mode</span> 1 sets non-blocking mode<br><br><br><aname="adc_setsmoothing"></a><spanstyle="font-weight: bold;">adc.setsmoothing(channel_id, length)<br></span> Set the length of the smoothing filter.<br> This must be a power of 2 (maximum = 128)<br><br><br><aname="adc_getsmoothing"></a><spanstyle="font-weight: bold;">adc.getsmoothing(channel_id)<br></span> Get the current smoothing length in use.<br><br><br><aname="adc_burst"></a><spanstyle="font-weight: bold;">adc.burst(
channel_id, count, timer_id, frequency)<br></span> Request that <spanstyle="font-style: italic;">count</span> samples be converted from <spanstyle="font-style: italic;">channel_id</span>, using <spanstyle="font-style: italic;">timer_id</span> at <spanstyle="font-style: italic;">frequency.<br></span> <spanstyle="font-style: italic;">count </span>must be greater than zero and a power of 2<br><br><br>
<spanstyle="font-weight: bold;">Currently runs on:</span> LM3Sxxxx<br><br> The disp module handles the RIT OLED display usage on Luminary Micro Cortex-M3 boards<br>
disp.init( freq )</span></p><pclass="MsoNormal">freq specifies the SSI Clock Frequency to be used.<br><br>This function initializes the SSI interface to the OLED display and configures the SSD1329 controller on the panel.<br></p><br><pclass="MsoNormal"><aname="disp_enable"></a>
<pclass="MsoNormal">Enable the SSI component of the OLED display driver.<br></p><pclass="MsoNormal">freq specifies the SSI Clock Frequency to be used.<br>This function initializes the SSI interface to the OLED display.</p><pclass="MsoNormal">
<pclass="MsoNormal"> Turns on the OLED display.<br> This function will turn on the OLED display, causing it to display the contents of its internal frame buffer.<br><br>
<spanstyle="font-weight: bold;">disp.off</span>()</p><pclass="MsoNormal">Turns off the OLED display<br>This
function will turn off the OLED display. This will stop the
scanning of the panel and turn off the on-chip DC-DC converter,
preventing damage to the panel due to burn-in (it has similar
characters to a CRT in this respect).<br><br></p>
<pclass="MsoNormal"><aname="disp_clear"></a>
<spanstyle="font-weight: bold;">disp.clear()</span></p><pclass="MsoNormal">Clears the OLED display.<br>This function will clear the display RAM. All pixels in the display will be turned off.<br></p>
<aname="disp_print"></a><spanstyle="font-weight: bold;">disp.print( str, x, y, gray )</span><br><br>Displays a string on the OLED display.<br><br>Calling Arguments:<br>str is a string to be displayed.<br>x is the horizontal position to display the string, specified in columns from the left edge of the display.<br>y is the vertical position to display the string, specified in rows from the top edge of the display.<br>gray is the 4-bit gray scale (intensity) value to be used for displayed text. <br><br>This
function will draw a string on the display. Only the ASCII
characters between 32 (space) and 126 (tilde) are supported;
other characters will result in random data being draw on the
display (based on whatever appears before/after the font in
memory). The font is mono-spaced, so characters such as ``i'' and
``l'' have more white space around them than characters such as ``m''
or ``w''.<br>If the drawing of the string reaches the right edge of the
display, no more characters will be drawn. Therefore, special
care is not required to avoid supplying a string that is ``too long''
to display.<br><br>Because the OLED display packs 2 pixels of data in a single byte, the<br>parameter \e ulX must be an even column number (for example, 0, 2, 4, and<br>so on).<br><br>
<spanstyle="font-weight: bold;">disp.draw( img, x, y, withd, height, gray )</span></p><pclass="MsoNormal">Displays an image on the OLED display.<br><br>img a pointer to the string data representing a rit format image to display.<br>x is the horizontal position to display the string, specified in columns from the left edge of the display.<br>y is the vertical position to display the string, specified in rows from the top edge of the display.<br>width is the width of the image, specified in columns.<br>height is the height of the image, specified in rows.<br><br>This
function will display a bitmap graphic on the display. Because of
the format of the display RAM, the starting column x and the number of
columns y must be an integer multiple of two.<br>The image data is
organized with the first row of image data appearing left to
right, followed immediately by the second row of image data. Each
byte contains the data for two columns in the current row, with
the leftmost column being contained in bits 7:4 and the rightmost
column being contained in bits 3:0.<br>For example, an image six
columns wide and seven scan lines tall would be arranged as
follows (showing how the twenty one bytes of the image would appear on
the display):<br><br>Because the OLED display packs 2 pixels of data in
a single byte, the parameter x must be an even column number (for
example, 0, 2, 4, and so on).<spanstyle="font-weight: bold;"></span></p><pclass="MsoNormal"><spanstyle="font-family: Courier New;"> +-------------------+-------------------+-------------------+</span><brstyle="font-family: Courier New;"><spanstyle="font-family: Courier New;">
