eLua consoles and terminals

In eLua, a console and a terminal serve two related, but different purposes:

Both components can be enabled and disabled as needed (they don't rely on each other). See building eLua for details on how to enable and disable components.

Serial consoles

The serial console input/output is handled by a generic layer (src/newlib/genstd.c) that can be used to easily adapt the console subsystem to a variety of input/output devices. It needs just two functions, one for displaying characters and another one for receiving input with timeout:

// Send/receive function types
typedef void ( *p_std_send_char )( int fd, char c );
typedef int ( *p_std_get_char )( s32 to );

(the send faction gets an additional fd parameter that you can use to differentiate between the standard C stdout and stderr output streams).

To set them, use std_set_send_func and std_set_get_func, both defined in inc/newlib/getstd.h. Usually they are called from src/common.c and configured to work over UART by default:

// *****************************************************************************
// std functions and platform initialization

static void uart_send( int fd, char c )
  fd = fd;
  platform_uart_send( CON_UART_ID, c );

static int uart_recv( s32 to )
  return platform_uart_recv( CON_UART_ID, TERM_TIMER_ID, to );

void cmn_platform_init()
  // Set the send/recv functions                          
  std_set_send_func( uart_send );
  std_set_get_func( uart_recv );  

If you need another type of serial console device (for example a dedicated console running over a SPI connection) just call std_set_send_func/std_set_get_func with the appropriate function pointers.

To enable serial consoles, define the BUILD_CON_GENERIC macro in your platform's platform_conf.h file.

TCP/IP consoles

TCP/IP consoles have the same functionality as serial consoles, but they work over a TCP/IP connection using the telnet protocol. As they integrate directly with the TCP/IP subsystem, they don't have the same generic function based mechanism as serial consoles. To enable TCP/IP consoles, define the BUILD_CON_TCP macro in your platform's platform_conf.h file.


Besides standard stdio/stdout/stderr support provided by consoles, eLua uses the "term" module to access ANSI compatible terminal emulators. It is designed to be as flexible as possible, thus allowing a large number of terminal emulators to be used. To enable terminal support, add BUILD_TERM in your platform's platform_conf.h file. To use it, initialize it with a call to term_init:

// Terminal output function
typedef void ( *p_term_out )( u8 );
// Terminal input function
typedef int ( *p_term_in )( int );
// Terminal translate input function
typedef int ( *p_term_translate )( u8 );
// Terminal initialization
void term_init( unsigned lines, unsigned cols, p_term_out term_out_func, 
                p_term_in term_in_func, p_term_translate term_translate_func );

The initialization function takes the physical size of the terminal emulator window (usually 80 lines and 25 cols) and three function pointers:

For an example, see src/main.c, where these functions are implemented for an UART connection with a terminal emulator program running on PC.

eLua also provides a Lua module (called term) that can be used to access ANSI terminal. See the term module API for a full description of this module.