elua/doc/pt/using.html

$$HEADER$$
<h3>Usando eLua</h3><p> Bem, você já <a href="building.html">compilou</a> e <a href="installing.html">instalou</a>
<b>eLua</b>. Agora está (finalmente!) na hora da curtir os resultados :) 
  Você pode desenvolver em <b>eLua</b> utilizando tanto uma conexão serial (UART, de longe a mais comum) como uma conexão TCP/IP (neste caso, ainda em testes, mas funcionando muito bem), logo existem dois cenários para esta situação (veja também <a href="building.html">building eLua</a> para mais detalhes de como escolher entre console serial ou TCP/IP).</p>
<a name="uart"><h3>Usando eLua com uma conexão serial</h3></a>
<p>Tudo o que você precisa para usar <b>eLua</b> com uma conexão serial é de sua placa <b>eLua</b> conectada a um PC rodando um programa emulador de terminal.<br>Se
você está usando o Windows, recomendamos o <a href="http://www.ayera.com/teraterm/">TeraTerm</a>.
É gratuito, possui muitos recursos e é fácil de usar. O pré-instalado Hyper Terminal também pode ser usado, porém dê uma chance ao TeraTerm
e compare as diferenças.<br>Se você usa Linux,
irá provavelmente se deparar com o Minicom a qualque momento. Ele não é muito intuitivo e roda em modo texto, mas possui bastante recursos. Se você
pesquisar no google por "minicom tutorial", poderá aprender rapidamente como instalá-lo e utilizá-lo. Você
pode tentar outros emuladores, desde que configure-os
adequadamente e que eles permitam que você faça transferência de arquivos 
via XMODEM, que no momento é o processo que <b>eLua</b> utiliza. Estes sáo os principais 
parâmetros a serem configurados:</p>

<ul>
<li>configuraçáo da porta: 115200 baud (38400 para o <a href="installing_str7.html">STR7)</a>, 8N1(8 bits de dados, sem paridade, um stop bit).</li>
<li>controle de fluxo do hardware: nenhum</li>
<li>como interpretar uma nova linha: "CR" na recepção, "CR+LF" no envio (alguns emuladores não permitem essa opção).  </li>
</ul>

<p>
Além disso, dependendo do seu kit, você irá precisar conectá-lo a uma porta serial do seu PC ou a uma porta USB, caso esteja usando um conversor USB/Serial. Por exemplo, como já foi explicado <a href="installing_lm3s.html">aqui</a>,
a porta USB nas placas LM3Sxxxx possui duas conexões, portanto você pode usá-la como um conversor de USB para serial depois de atualizar o
firmware, dispensando qualquer outro tipo de conexão. O mesmo acontece com a placa STR9-comStick. Entretanto, para a placa SAM7-EX256 você precisará conectar um cabo serial ao conector "RS232", desde que
os jumpers já estejam configurados como explicado <a href="installing_at91sam7x.html">aqui</a>. Para a placa MOD711 você precisará acrescentar um chip conversor RS232.
Não existe uma única regra, tudo depende do modêlo da sua placa.
</p>

<a name="tcpip"><h3>Usando eLua com uma conexão TCP/IP</h3></a>
<p>As coisas ficam bem mais fáceis se você decidir usar uma conexão TCP/IP:
<ul>
  <li>Certifique-se que você conhece o endereço IP de sua placa. Se você habilitou IP estático (veja <a href="building.html">construindo</a>)
  e lembre-se qual o IP escolhido durante o build. Caso tenha optado pelo
  modo DHCP (IP fornecido por um servidor na sua rede local), seu servidor DHCP deve ter
  incluído o endereço de sua placa <b>eLua</b> como seu DNS. O nome da placa sempre é "elua", logo caso você execute um "ping elua" a partir do
  shell, poderá verificar se a placa está ativa.</li>
  <li>Uma conexão Telnet para o endereço da placa (ou simplesmente "telnet elua" com DHCP ativo) e você será recebido pelo shell prompt da placa (se o shell estiver ativo, leia o próximo parágrafo para mais detalhes). 
  É importante salientar que uma placa <b>eLua</b> só poderá estar conectada a uma
  única sessão Telnet ativa a cada instante.</li>
</ul>

</p>
<p>Se você está desenvolvendo em Windows, certifique-se que esteja utilizando um
cliente Telnet adequado, o que significa na prática "qualquer coisa menos o cliente Telnet nativo".

<a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</a> é muito popular e uma boa opção.</p>

<a name="pc"><h3>Usando eLua "standalone" em seu PC</h3></a>
<p>Se fez um build de <b>eLua</b> para a plataforma i386, poderá dar boot direto
em <b>eLua</b>(!!!), sem Sistema Operacional controlando o seu computador, somente <b>eLua</b>
e mais nada. Não haverá nenhum periférico disponível para acesso mas podemos usar o módulo term para executar
jogos como o <i>hangman.lua</i> , o <i>life.lua</i>, assim como outros exemplos, o que o torna uma boa demonstração :) 
Siga <a href="installing_i386.html">este link</a> para obter informações específicas sobre a plataforma i386. </p>

<a name="shell"><h3><a name="shell"></a>O shell eLua</h3></a>
<p>Não importa como você está conectado fisicamente (serial, TCP/IP ou pelo seu monitor de vídeo do PC após o boot com <b>eLua</b>), 
depois que você configurar a conexão PC-placa <b>elua</b> (se aplicável) e pressionar o botão "RESET" de sua placa ou simplesmente pressionar
ENTER, você deve ver o shell prompt de <b>eLua</b> (o shell prompt deve ter
sido habilitado no build, como descrito <a href="building.html">aqui</a>). 
O shell de <b>eLua</b> é um simples interpretador de comandos interativo que permite:
<ul>
  <li>fornecer uma ajuda para o uso do interpretador com o comando help</li>
  <li>rodar o interpretador Lua original, no modo interativo, da mesma forma que fazemos em
  um desktop</li>
  <li>rodar programas Lua que se encontream no File System de <b>eLua</b></li>
  <li>transferir arquivos com programas fonte Lua via XMODEM e executa-los</li>
  <li>mostrar a versão corrente de <b>eLua</b></li>
  <li>listar arquivos do File System de <b>eLua</b></li>
</ul></p>
<p>Segue abaixo uma descrição detalhada de todos os comandos.</p>

<h2>help</h2>
<p>Mostra uma lista de todos os comandos disponíveis no shell de <b>eLua</b></p>
<h2>ver</h2>
<p>Mostra a versão da imagem de <b>eLua</b> instalada na placa. Atualmente, a versão é somente incrementada por atualizações oficiais, 
logo se é liberada uma versão intermediária, esta não interfere no número da versão.</p>
<h2>recv</h2>

<p>Permite que você receba um arquivo eLua (tanto arquivos fontes quanto compilados) via protocolo 
XMODEM e execute-o em sua placa. Para usar este comando é necessário que sua imagem de <b>eLua</b> tenha sido configurada para suportar XMODEM 
(veja <a href="building.html">build de eLua</a> para mais detalhes). Além disso, o seu programa emulador de terminal deve suportar o envio de arquivos via protocolo XMODEM. 
Ambos XMODEM com checksum e XMODEM com CRC são suportados. No entanto só é aceito o XMODEM com pacotes de 128 bytes 
(não há suporte para XMODEM com pacotes de 1K).
Para usar esse recurso, digite "recv" no prompt do shell. <b>eLua</b> responderá com 
"Waiting for file ...". Neste momento, você poderá enviar o arquivo para a placa eLua 
via XMODEM. <b>eLua</b> receberá e executará o arquivo. Não se preocupe quando ver o 
caracter 'C' aparecendo em seu terminal depois de entrar como esse comando, pois essa é a forma como o XMODEM é inicializado.<br>
Como o XMODEM é um protocolo que se utiliza de comunicação serial, este comando não está disponível caso você esteja usando uma conexão TCP/IP.<br>
Caso você esteja querendo enviar arquivos binários já compilados ao invés de código fonte para <b>eLua</b>, 
veja antes <a href="using.html#cross">essa sessão</a>.
</p>

<h2>lua</h2>

<p>Esse comando inicia a interpretador Lua, aceitando opcionalmente parâmetros na linha de comando, exatamente 
como se você estivesse em seu computador desktop. O comando possui algumas restrições:</p>

<ul>
<li>Máximo de 50 caracteres na linha de comando</li>
<li>A sequência 'ESC` não foi implemantada. Por exemplo, o seguinte comando não funcionará
    devido a sequência 'ESC' com ' ('aspas simples') somente:
<p>
<pre><code>eLua# lua -e 'print(\'Hello, World!\')' -i<br>
Press CTRL+Z to exit Lua<br>
lua: (command line):1: unexpected symbol near ''</code></pre>
</p>

<p>Entretanto, se você usar ambas ' ('aspas simples') e " ("aspas duplas"), o comando então funcionará:</p>

<p><pre><code>eLua# lua -e 'print("Hello, World")' -i
Press CTRL+Z to exit Lua
Lua 5.1.4  Copyright (C) 1994-2008 Lua.org, PUC-Rio
Hello,World</code></pre></p></li>
</ul>

<p>Caso você queira executar um arquivo a partir do <a href="arch_romfs.html">ROM File System</a>, não se esqueça de colocar antes do nome do arquivo o prefixo
<b>/rom</b>. 
Por exemplo, para executar o arquivo hello.lua, digite o seguinte:
</p>
<p>
<pre><code>$ lua /rom/hello.lua</code></pre>
</p>

<h2>ls or dir</h2>
<p>Lista todos os arquivos do File System de <b>eLua</b> (atualmente armazenado em ROM), bem como o total ocupado
por cada um e o espaço total do sistema de arquivos.
</p>

<h2>exit</h2>
<p>Sai do shell. Esse comando só faz sentido, caso você tenha compilado <b>eLua</b> para conexão sobre TCP/IP, já que a sessão telnet
é encerrada com a placa <b>eLua</b>. Caso contrário o comando simplesmente encerra o shell e trava até você resetar sua placa.
</p>

<a name="cross"><h3>Cross-compilation: compilando seus programas eLua para uma plataforma diferente</h3></a>
<p><i>Cross-compilation</i> é o processo de compilação de um programa em uma platforma com obejtivo de ser 
utilzado em uma outra plataforma. Por exemplo, o processo de compilação para gerar uma imagem binária de <b>eLua</b> em
seu PC para uso na sua placa <b>eLua</b> é o que chamamos de "cross-compiling". 
Lua pode ser compilada dessa forma também. Ao compilar Lua usando esse procedimento você tem algumas vantagens importantes:
<ul>
<li><b>velocidade</b>: O compilador Lua na placa <b>eLua</b> não precisa compilar o código fonte
Lua. Ele simplesmente executa o código binário (bytecodes Lua).</li>
<li><b>memória</b>: caso você esteja executando diretamente um código binário, nenhuma memória
adicional é usada na placa para compilação do código Lua para bytecode. Muitas vezes isso é a
"salvação", quando você já está no limite de uso dos seus recursos de
memória. Caso você esteja tentando executar código Lua direto de sua placa e recebendo a mensagem de erro "not enough memory", 
pode mudar esse resultado compilando o programa Lua em seu PC e depois executando o arquivo
binário (bytecodes Lua) gerado. Além disso, compilar programas Lua muito grandes em sua placa 
<b>eLua</b> pode (raramente) acarretar estouro de pilha (stack overflow), o que normalmente nos leva a erros difíceis de serem encontrados.</li>
</ul>
</p>

<p>Para usar "cross-compilation", as duas plataformas Lua (neste caso seu PC e sua placa <b>eLua</b>) devem ser compatíveis
(mesmo tamanho de palavra, mesmo alinhamento etc...). 
Isto não é verdadeiro sempre. Por exemplo, alguns toolchains gcc para arquitetura ARM usam como padrão uma representação muito específica 
para números com dupla precisão (conhecida como formato FPA), tornando dessa forma, os arquivos bytecode gerados no PC com um compilador Lua inúteis 
para as placas ARM. Outros toolchains não possuem esse problema. Outras arquiteturas (como a AVR32) são "big endian", ao contrário da plataforma 
Intel para PCs que é "little endian".<br>
Para resolver esses tipos de problemas, um patch para "Lua cross-compilation" foi enviado para a lista de e-mails de Lua e foi bastante modificado 
como parte do projeto <b>eLua</b> para funcionar com a arquitetura ARM. 
Aqui está como usá-lo (as instruções abaixo foram testadas em Linux, não em Windows, mesmo assim, elas devem funcionar também no Windows com 
pouco ou quase nenhum esforço):
<ul>
<li>Primeiro, certifique-se que seu PC já esteja com todos os arquivos necessários para o build de <b>eLua</b> (gcc, binutils, libc, headers...). 
Você precisará também do scons. A boa notícia é que você já deve ter o scons instalado em seu sistema, 
já que, caso contrário você não seria capaz nem mesmo de construir <b>eLua</b> (veja <a href="building.html">construindo</a> para
instruções mais detalhadas).</li>
<li>a partir do diretório base de <b>eLua</b>, digite o seguinte comando:</li>
  <p><pre><code>$ scons -f cross-lua.py</code></pre></p>
</ul>

<p>Esse comando gera um arquivo chamado <i>luac</i> no mesmo. 
É quase a mesma coisa que no compilador comum, mas possui alguns poucos argumentos para lidar com as diferenças entre as diversas arquiteturas 
(mostradas abaixo em negrito):</p>
<p><pre><code>usage: ./luac [options] [filenames].
Available options are:
-        process stdin
-l       list
-o name  output to file 'name' (default is "luac.out")
-p       parse only
-s       strip debug information
-v       show version information
<b>-cci bits       cross-compile with given integer size
-ccn type bits  cross-compile with given lua_Number type and size
-cce endian     cross-compile with given endianness ('big' or 'little')</b>
--       stop handling options</code></pre></p>
<p>Tudo que deve ser feito agora é usar a tabela abaixo para identificar qual os parâmetros certos para serem utilizados no cross-compiler:</p>
</p><table style="text-align: left;" class="table_center">
<tbody>
<tr>
  <th style="text-align: left;">tipo da imagem de eLua</th>
  <th style="text-align: center;">Arquitetura</th>
  <th style="text-align: center;">Compilador</th>
  <th style="text-align: center;">Comando</th>
</tr>
<tr>
  <td>Ponto Flutuante (lua)</td>
  <td>ARM7TDMI<br>Cortex-M3<br>ARM966E-S</td>
  <td><a href="toolchains.html">arm-gcc</a>
  <td><code>./luac -ccn float_arm 64 -cce little -o <script.luac> -s <script.lua></code></td>
</tr>
<tr>
  <td>Ponto Flutuante (lua)</td>
  <td>ARM7TDMI<br>Cortex-M3<br>ARM966E-S</td>
  <td><a href="toolchains.html">codesourcery</a>
  <td><code>./luac -ccn float 64 -cce little -o <script.luac> -s <script.lua></code></td>
</tr>
<tr>
  <td>Inteiro (lualong)</td>
  <td>ARM7TDMI<br>Cortex-M3<br>ARM966E-S</td>
  <td><a href="toolchains.html">arm-gcc<br>codesourcery</a>
  <td><code>./luac -ccn int 32 -cce little -o <script.luac> -s <script.lua></code></td>
</tr>
<tr>
  <td>Ponto Flutuante (lua)</td>
  <td>AVR32</td>
  <td><a href="toolchains.html">avr32-gcc</a>
  <td><code>./luac -ccn float 64 -cce big -o <script.luac> -s <script.lua></code></td>
</tr>
<tr>
  <td>Inteiro (lualong)</td>
  <td>AVR32</td>
  <td><a href="toolchains.html">avr32-gcc</a>
  <td><code>./luac -ccn int 32 -cce big -o <script.luac> -s <script.lua></code></td>
</tr>
</tbody>
</table>
<p>(observe que, se por alguma razão você precisar, de um cross-compile <b>eLua</b> para x86, poderá usar o próprio compilador Lua).<br>
Você pode omitir o parâmetro <i>-s</i> (de strip) da compilação, mas isso resultará em arquivos binários maiores 
(quando não se usa o parâmetro <i>-s</i>, a informação de debug não é removida do arquivo gerado).</p>
<p>Você pode usar o arquivo gerado de duas formas:</p>
<ul>
  <li>gravá-lo no <a href="arch_romfs.html">ROM File System</a> de sua placa
  durante um build e executá-lo a partir daí.</li>
  <li>usar o comando <i>recv</i> a partir <a href="using.html#shell">do
  shell</a>, para enviá-lo para a placa usando uma conexão serial.</li>
</ul>
<p>
</p>
$$FOOTER$$