px-fwlib 0.10.0
Cross-platform embedded library and documentation for 8/16/32-bit microcontrollers generated with Doxygen 1.9.2
Enumerations | Functions
px_vt100.h : VT100/ANSI Terminal module
/comms [Communication related modules]

Description

Parses VT100 / ANSI escape sequences to interface with a terminal emulator.

File(s):

See also

Example:

#include <string.h>
#include "px_defs.h"
#include "px_board.h"
#include "px_uart.h"
#include "px_uart_stdio.h"
#include "px_pgm_P.h"
#include "px_cli.h"
// LED command handlers
static const char * px_cli_cmd_led_on_fn(uint8_t argc, char * argv[])
{
PX_LED_ON();
return NULL;
}
static const char * px_cli_cmd_led_off_fn(uint8_t argc, char * argv[])
{
PX_LED_OFF();
return NULL;
}
// Buzzer command handler
static const char * px_cli_cmd_buzzer_fn(uint8_t argc, char * argv[])
{
uint16_t delay_ms;
// <on time ms>
if(px_cli_util_argv_to_u16(0, 0, 1000))
{
delay_ms = px_cli_argv_val.u16;
}
else
{
return PX_PGM_STR("Error: <on time ms> must be from 0 to 1000 ms");
}
BUZZER_ON();
px_board_delay_ms(delay_ms);
BUZZER_OFF();
return NULL;
}
/// [CLI cmd tree declaration]
// Create CLI LED command structures
PX_CLI_CMD_CREATE(px_cli_cmd_led_on, "on", 0, 0, "", "Switch LED on")
PX_CLI_CMD_CREATE(px_cli_cmd_led_off, "off", 0, 0, "", "Switch LED off")
// Create CLI LED group and add commands
PX_CLI_GROUP_CREATE(px_cli_group_led, "led")
PX_CLI_CMD_ADD(px_cli_cmd_led_on, px_cli_cmd_led_on_fn)
PX_CLI_CMD_ADD(px_cli_cmd_led_off, px_cli_cmd_led_off_fn)
PX_CLI_GROUP_END()
// Create CLI command structures
PX_CLI_CMD_CREATE(px_cli_cmd_buzzer, "buzzer", 1, 1, "<on time ms>", "Switch buzzer on for specified number of milliseconds")
PX_CLI_CMD_CREATE(px_cli_cmd_help, "help", 0, 1, "[cmd(s) starts with...]", "Display list of commands with help. Optionally the list can be reduced.")
// Declare CLI command list and add commands and groups
PX_CLI_CMD_LIST_CREATE(px_cli_cmd_list)
PX_CLI_CMD_ADD (px_cli_cmd_buzzer, px_cli_cmd_buzzer_fn)
PX_CLI_GROUP_ADD(px_cli_group_led)
PX_CLI_CMD_ADD (px_cli_cmd_help, px_cli_cmd_help_fn)
PX_CLI_CMD_LIST_END()
/// [CLI cmd tree declaration]
// UART handle
static px_uart_handle_t px_uart_handle;
int main(void)
{
uint8_t data;
// Initialise modules
px_board_init();
px_uart_init();
// Open UART0 @ 115200 BAUD, 8 data bits, no parity, 1 stop bit
px_uart_open2(&px_uart_handle,
PX_UART_NR_0,
115200,
PX_UART_DATA_BITS_8,
PX_UART_PARITY_NONE,
PX_UART_STOP_BITS_1);
// Direct stdio to UART0
px_uart_stdio_init(&px_uart_handle);
// Enable interrupts
px_interrupts_enable();
// Initialise CLI (after STDIO is ready)
px_cli_init(px_cli_cmd_list, PX_PGM_STR("CLI Example\n\n"));
// Loop forever
while(true)
{
// Byte received?
if(px_uart_rd_u8(&px_uart_handle, &data))
{
// Pass received byte on to CLI
px_cli_on_rx_char((char)data);
}
}
}
PX_LED_ON
#define PX_LED_ON()
Enable LED (shared with SPI clock)
Definition: px_board.h:117
PX_LED_OFF
#define PX_LED_OFF()
Disable LED (shared with SPI clock)
Definition: px_board.h:119
px_board_init
void px_board_init(void)
Initialise the board hardware.
Definition: px_board.c:168
px_board_delay_ms
void px_board_delay_ms(uint16_t delay_ms)
Blocking delay for specified number of milliseconds.
Definition: px_board.c:234
px_cli_init
void px_cli_init(const px_cli_cmd_list_item_t *cli_cmd_list, const char *startup_str)
Initialise command line module.
Definition: px_cli.c:694
px_cli_argv_val
px_cli_argv_val_t px_cli_argv_val
Converted argument value using px_cli_util_argv_to_...() conversion function.
Definition: px_cli.c:39
px_cli_util_argv_to_u16
bool px_cli_util_argv_to_u16(uint8_t argv_index, uint16_t min, uint16_t max)
Utility function to convert an ARGV string to a number.
Definition: px_cli.c:1065
PX_CLI_CMD_LIST_END
#define PX_CLI_CMD_LIST_END()
Macro to end a command list declaration.
Definition: px_cli.h:568
PX_CLI_GROUP_CREATE
#define PX_CLI_GROUP_CREATE(cli_group, name_str)
Macro to create a new CLI group.
Definition: px_cli.h:513
PX_CLI_GROUP_END
#define PX_CLI_GROUP_END()
Macro to end a group list array.
Definition: px_cli.h:525
PX_CLI_CMD_CREATE
#define PX_CLI_CMD_CREATE(cli_cmd, name_str, nr_arg_min, nr_arg_max, param_str, help_str)
Macro to create a new CLI command.
Definition: px_cli.h:489
PX_CLI_CMD_ADD
#define PX_CLI_CMD_ADD(cli_cmd, handler_fn)
Macro to add a created command to the list.
Definition: px_cli.h:550
PX_CLI_CMD_LIST_CREATE
#define PX_CLI_CMD_LIST_CREATE(cli_cmd_list)
Macro to start a command list declaration.
Definition: px_cli.h:538
px_cli_on_rx_char
void px_cli_on_rx_char(char data)
Function called to handle a received character.
Definition: px_cli.c:753
PX_CLI_GROUP_ADD
#define PX_CLI_GROUP_ADD(cli_group)
Macro to add a created group to the list.
Definition: px_cli.h:561
px_cli_cmd_help_fn
const char * px_cli_cmd_help_fn(uint8_t argc, char *argv[])
Handler function to call when "help" command is invoked.
Definition: px_cli.c:862
NULL
#define NULL
NULL pointer.
Definition: px_defs.h:49
px_uart_stdio_init
void px_uart_stdio_init(px_uart_handle_t *handle)
Initialise stdio stream to use a UART driver.
Definition: px_uart_stdio.c:94
px_uart_open2
bool px_uart_open2(px_uart_handle_t *handle, px_uart_nr_t uart_nr, uint32_t baud, px_uart_data_bits_t data_bits, px_uart_parity_t parity, px_uart_stop_bits_t stop_bits)
Open UART peripheral using specified parameters.
Definition: px_uart.c:483
px_uart_rd_u8
bool px_uart_rd_u8(px_uart_handle_t *handle, uint8_t *data)
See if a received byte is available and store it in the specified location.
Definition: px_uart.c:726
px_uart_init
void px_uart_init(void)
Initialise UART driver.
Definition: px_uart.c:452
px_uart_handle_t
Define UART handle.
Definition: px_uart.h:141

Enumerations

enum  px_vt100_state_t {
  PX_VT100_CHAR_NORMAL , PX_VT100_CHAR_INVALID , PX_VT100_ESC_SEQ_BUSY , PX_VT100_ESC_SEQ_ARROW_UP ,
  PX_VT100_ESC_SEQ_ARROW_DN , PX_VT100_ESC_SEQ_ARROW_LEFT , PX_VT100_ESC_SEQ_ARROW_RIGHT
}
 VT100 Terminal receive state. More...
 

Functions

void px_vt100_init (void)
 Initialise module. More...
 
px_vt100_state_t px_vt100_on_rx_char (char data)
 Process a received character byte. More...
 
void px_vt100_clr_display (void)
 Send 'clear screen' command to terminal. More...
 
void px_vt100_erase_line (void)
 Send 'erase line' command to terminal. More...
 
void px_vt100_del_chars (uint8_t nr_of_chars)
 Delete specified number of characters. More...
 

Special ASCII values

#define PX_VT100_CHAR_BEL   0x07
 
#define PX_VT100_CHAR_BS   0x08
 
#define PX_VT100_CHAR_TAB   0x09
 
#define PX_VT100_CHAR_CR   0x0D
 
#define PX_VT100_CHAR_LF   0x0A
 
#define PX_VT100_CHAR_ESC   0x1B
 
#define PX_VT100_CHAR_DEL   0x7F
 

VT100 escape sequences

#define PX_VT100_CURSOR_HOME   "\x1B[H"
 
#define PX_VT100_CURSOR_UP   "\x1B[1A"
 
#define PX_VT100_CURSOR_DOWN   "\x1B[1B"
 
#define PX_VT100_CURSOR_FORWARD   "\x1B[1C"
 
#define PX_VT100_CURSOR_BACKWARD   "\x1B[1D"
 
#define PX_VT100_SAVE_CURSOR   "\x1B[s"
 
#define PX_VT100_UNSAVE_CURSOR   "\x1B[u"
 
#define PX_VT100_SAVE_CURSOR_AND_ATTRS   "\x1B7"
 
#define PX_VT100_RESTORE_CURSOR_AND_ATTRS   "\x1B8"
 
#define PX_VT100_SCROLL_SCREEN   "\x1B[r"
 
#define PX_VT100_SCROLL_DOWN   "\x1BD"
 
#define PX_VT100_SCROLL_UP   "\x1BM"
 
#define PX_VT100_SET_TAB   "\x1BH"
 
#define PX_VT100_CLR_TAB   "\x1B[g"
 
#define PX_VT100_CLR_ALL_TABS   "\x1B[3g"
 
#define PX_VT100_ERASE_END_OF_LINE   "\x1B[K"
 
#define PX_VT100_ERASE_START_OF_LINE   "\x1B[1K"
 
#define PX_VT100_ERASE_LINE   "\x1B[2K"
 
#define PX_VT100_ERASE_DOWN   "\x1B[J"
 
#define PX_VT100_ERASE_UP   "\x1B[1J"
 
#define PX_VT100_ERASE_SCREEN   "\x1B[2J"
 
#define PX_VT100_ATTR_RST   "\x1B[0m"
 
#define PX_VT100_ATTR_BRIGHT   "\x1B[1m"
 
#define PX_VT100_ATTR_DIM   "\x1B[2m"
 
#define PX_VT100_ATTR_UNDERSCORE   "\x1B[4m"
 
#define PX_VT100_ATTR_BLINK   "\x1B[5m"
 
#define PX_VT100_ATTR_REVERSE   "\x1B[7m"
 
#define PX_VT100_ATTR_HIDDEN   "\x1B[8m"
 
#define PX_VT100_FG_BLACK   "\x1B[30m"
 
#define PX_VT100_FG_RED   "\x1B[31m"
 
#define PX_VT100_FG_GREEN   "\x1B[32m"
 
#define PX_VT100_FG_YELLOW   "\x1B[33m"
 
#define PX_VT100_FG_BLUE   "\x1B[34m"
 
#define PX_VT100_FG_MAGENTA   "\x1B[35m"
 
#define PX_VT100_FG_CYAN   "\x1B[36m"
 
#define PX_VT100_FG_WHITE   "\x1B[37m"
 
#define PX_VT100_BG_BLACK   "\x1B[40m"
 
#define PX_VT100_BG_RED   "\x1B[41m"
 
#define PX_VT100_BG_GREEN   "\x1B[42m"
 
#define PX_VT100_BG_YELLOW   "\x1B[43m"
 
#define PX_VT100_BG_BLUE   "\x1B[44m"
 
#define PX_VT100_BG_MAGENTA   "\x1B[45m"
 
#define PX_VT100_BG_CYAN   "\x1B[46m"
 
#define PX_VT100_BG_WHITE   "\x1B[47m"
 

Enumeration Type Documentation

◆ px_vt100_state_t

enum px_vt100_state_t

VT100 Terminal receive state.

Enumerator
PX_VT100_CHAR_NORMAL 

A normal key has been pressed and must be used.

PX_VT100_CHAR_INVALID 

An invalid key code has been sent and must be discarded.

PX_VT100_ESC_SEQ_BUSY 

Busy with escape sequence; data must be discarded.

PX_VT100_ESC_SEQ_ARROW_UP 

Up Arrow has been pressed.

PX_VT100_ESC_SEQ_ARROW_DN 

Down Arrow has been pressed.

PX_VT100_ESC_SEQ_ARROW_LEFT 

Left Arrow has been pressed.

PX_VT100_ESC_SEQ_ARROW_RIGHT 

Right Arrow has been pressed.

Definition at line 118 of file px_vt100.h.

Function Documentation

◆ px_vt100_init()

void px_vt100_init ( void  )

Initialise module.

Definition at line 43 of file px_vt100.c.

◆ px_vt100_on_rx_char()

px_vt100_state_t px_vt100_on_rx_char ( char  data)

Process a received character byte.

If an ANSI escape sequence is detected, PX_VT100_ESC_SEQ_BUSY will be returned to indicate that received character should be ignored, otherwise PX_VT100_CHAR_NORMAL is returned to indicate that the character must be used.

If an ANSI escape sequence is decoded it is indicated with a PX_VT100_ESC_SEQ... state.

Parameters
dataReceived character to be process for ANSI Escape Sequences
Returns
px_vt100_state_t PX_VT100_CHAR_NORMAL if the character must be used as normal; PX_VT100_CHAR_INVALID or PX_VT100_ESC_SEQ_BUSY if character should be ignored; otherwise the decoded ANSI Escape Sequence.

Definition at line 57 of file px_vt100.c.

◆ px_vt100_clr_display()

void px_vt100_clr_display ( void  )

Send 'clear screen' command to terminal.

Definition at line 111 of file px_vt100.c.

◆ px_vt100_erase_line()

void px_vt100_erase_line ( void  )

Send 'erase line' command to terminal.

Definition at line 119 of file px_vt100.c.

◆ px_vt100_del_chars()

void px_vt100_del_chars ( uint8_t  nr_of_chars)

Delete specified number of characters.

Parameters
nr_of_charsNumber of characters to delete

Definition at line 127 of file px_vt100.c.