$$HEADER$$

Usando eLua

Bem, você já compilou e instalou eLua. Agora está (finalmente!) na hora da curtir os resultados :) Você pode desenvolver em eLua 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 building eLua para mais detalhes de como escolher entre console serial ou TCP/IP).

Usando eLua com uma conexão serial

Tudo o que você precisa para usar eLua com uma conexão serial é de sua placa eLua conectada a um PC rodando um programa emulador de terminal.
Se você está usando o Windows, recomendamos o TeraTerm. É 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.
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 eLua utiliza. Estes sáo os principais parâmetros a serem configurados:

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

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 aqui, 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 aqui. 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.

Usando eLua com uma conexão TCP/IP

As coisas ficam bem mais fáceis se você decidir usar uma conexão TCP/IP:

Certifique-se que você conhece o endereço IP de sua placa. Se você habilitou IP estático (veja construindo) 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 eLua 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.
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 eLua só poderá estar conectada a uma única sessão Telnet ativa a cada instante.

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". PuTTY é muito popular e uma boa opção.

Usando eLua "standalone" em seu PC

Se fez um build de eLua para a plataforma i386, poderá dar boot direto em eLua(!!!), sem Sistema Operacional controlando o seu computador, somente eLua 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 hangman.lua , o life.lua, assim como outros exemplos, o que o torna uma boa demonstração :) Siga este link para obter informações específicas sobre a plataforma i386.

O shell eLua

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 eLua), depois que você configurar a conexão PC-placa elua (se aplicável) e pressionar o botão "RESET" de sua placa ou simplesmente pressionar ENTER, você deve ver o shell prompt de eLua (o shell prompt deve ter sido habilitado no build, como descrito aqui). O shell de eLua é um simples interpretador de comandos interativo que permite:

fornecer uma ajuda para o uso do interpretador com o comando help
rodar o interpretador Lua original, no modo interativo, da mesma forma que fazemos em um desktop
rodar programas Lua que se encontream no File System de eLua
transferir arquivos com programas fonte Lua via XMODEM e executa-los
mostrar a versão corrente de eLua
listar arquivos do File System de eLua

Segue abaixo uma descrição detalhada de todos os comandos.

help

Mostra uma lista de todos os comandos disponíveis no shell de eLua

ver

Mostra a versão da imagem de eLua 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.

recv

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 eLua tenha sido configurada para suportar XMODEM (veja build de eLua 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. eLua responderá com "Waiting for file ...". Neste momento, você poderá enviar o arquivo para a placa eLua via XMODEM. eLua 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.
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.
Caso você esteja querendo enviar arquivos binários já compilados ao invés de código fonte para eLua, veja antes essa sessão.

lua

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:

Máximo de 50 caracteres na linha de comando
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:
```
eLua# lua -e 'print(\'Hello, World!\')' -i

Press CTRL+Z to exit Lua

lua: (command line):1: unexpected symbol near ''
```
Entretanto, se você usar ambas ' ('aspas simples') e " ("aspas duplas"), o comando então funcionará:
```
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
```

Caso você queira executar um arquivo a partir do ROM File System, não se esqueça de colocar antes do nome do arquivo o prefixo /rom. Por exemplo, para executar o arquivo hello.lua, digite o seguinte:

$ lua /rom/hello.lua

ls or dir

Lista todos os arquivos do File System de eLua (atualmente armazenado em ROM), bem como o total ocupado por cada um e o espaço total do sistema de arquivos.

exit

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

Cross-compilation: compilando seus programas eLua para uma plataforma diferente

Cross-compilation é 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 eLua em seu PC para uso na sua placa eLua é 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:

velocidade: O compilador Lua na placa eLua não precisa compilar o código fonte Lua. Ele simplesmente executa o código binário (bytecodes Lua).
memória: 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 eLua pode (raramente) acarretar estouro de pilha (stack overflow), o que normalmente nos leva a erros difíceis de serem encontrados.

Para usar "cross-compilation", as duas plataformas Lua (neste caso seu PC e sua placa eLua) 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".
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 eLua 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):

Primeiro, certifique-se que seu PC já esteja com todos os arquivos necessários para o build de eLua (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 eLua (veja construindo para instruções mais detalhadas).
a partir do diretório base de eLua, digite o seguinte comando:

$ scons -f cross-lua.py

Esse comando gera um arquivo chamado luac 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):

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
-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')
--       stop handling options

Tudo que deve ser feito agora é usar a tabela abaixo para identificar qual os parâmetros certos para serem utilizados no cross-compiler:

tipo da imagem de eLua	Arquitetura	Compilador	Comando
Ponto Flutuante (lua)	ARM7TDMI Cortex-M3 ARM966E-S	arm-gcc	`./luac -ccn float_arm 64 -cce little -o -s`
Ponto Flutuante (lua)	ARM7TDMI Cortex-M3 ARM966E-S	codesourcery	`./luac -ccn float 64 -cce little -o -s`
Inteiro (lualong)	ARM7TDMI Cortex-M3 ARM966E-S	arm-gcc codesourcery	`./luac -ccn int 32 -cce little -o -s`
Ponto Flutuante (lua)	AVR32	avr32-gcc	`./luac -ccn float 64 -cce big -o -s`
Inteiro (lualong)	AVR32	avr32-gcc	`./luac -ccn int 32 -cce big -o -s`

(observe que, se por alguma razão você precisar, de um cross-compile eLua para x86, poderá usar o próprio compilador Lua).
Você pode omitir o parâmetro -s (de strip) da compilação, mas isso resultará em arquivos binários maiores (quando não se usa o parâmetro -s, a informação de debug não é removida do arquivo gerado).

Você pode usar o arquivo gerado de duas formas:

gravá-lo no ROM File System de sua placa durante um build e executá-lo a partir daí.
usar o comando recv a partir do shell, para enviá-lo para a placa usando uma conexão serial.

$$FOOTER$$