btnut/btnode/include/terminal/btn-terminal.h File Reference


Detailed Description

Easy use for user input/output and execute commands.

Author:
Martin Hinz <btnode@hinz.ch>
There are some predefined commands to control nut-os, btnode and bluetooth.

See also:
bt-cmds.h
acl-com-cmds.h
nut-cmds.h
btn-cmds.h

#include <stdio.h>
#include <io.h>
#include <stdbool.h>

DEBUG with mutex support provided by a lock function

following function write directly to uart without mutex!
use btn_terminal_get_writing_lock() for unique debug uart access and btn_terminal_free_writing_lock() to free the lock again
Advantage: Unique output of one thread also with several DEBUG calls.
Disadvantage: Lock and unlock the unique uart access.

#define DEBUGB_M(text)   fputs(text,debug_uart);
#define DEBUGL_M(buf, len)   _write(_fileno(debug_uart), buf, len)
#define DEBUGT_M(text,...)   fprintf_P(debug_uart,PSTR(text),## __VA_ARGS__)
void btn_terminal_free_writing_lock (void)
void btn_terminal_get_writing_lock (void)
char term_register_thread (void)
 Register the calling thread.
char term_start_capture (void)
 Start the recording of terminal output.
char * term_stop_capture (void)
 Stop the recording of terminal output.
int tprintf (CONST char *text,...)
 use this function to capture terminal output.

DEBUG with mutex support provided in each DEBUG call

following function write with mutex to the debug uart!
Advantage: No output-mix due to different threads writing to same uart.
Disadvantage: Still mix of single DEBUG calls of different threads.

#define DEBUGT(text,...)   DEBUGT_I(PSTR(text),## __VA_ARGS__)
void DEBUGB (char *text)
void DEBUGL (char *buf, u_char len)
int DEBUGT_I (PGM_P fmt,...)

Defines

#define BTN_TERMINAL_FORK   0
#define BTN_TERMINAL_NOFORK   1
#define HISTORY_DEPTH   5
#define INPUT_LENGTH   180
#define LEN_CMD_NAME   10
#define MAX_CMDS   50
#define TERMINAL_MAX_LOGGED_THREADS   2
#define TERMINAL_THREADBUFFER_SIZE   1023

Functions

void btn_set_error (u_char errorno, char *lasterror)
void btn_show_error (void)
void btn_terminal_init (FILE *uart, char *a_prompt)
u_char btn_terminal_process_cmd (char *cmd)
void btn_terminal_refresh (void)
void btn_terminal_register_cmd (char *name, void(*fkt)(char *))
void btn_terminal_run (u_char type, u_short thread_size)
void btn_terminal_set_prompt (char *a_prompt)
void btn_terminal_set_verbosity (bool val)

Variables

FILEdebug_uart


Define Documentation

#define BTN_TERMINAL_FORK   0

Passing argument to start (fork) a new terminal thread.

Examples:
sensor-app/senso.c.

#define BTN_TERMINAL_NOFORK   1

Passing argument to use main thread for terminal input (no new thread).

Examples:
bt-lego/bt-lego.c, ccc-cmd/ccc-cmd.c, l2cap-cmd/l2cap-cmd.c, mhop_blink/mhop_blink.c, and rfcomm-cmd/rfcomm-cmd.c.

#define DEBUGB_M ( text   )     fputs(text,debug_uart);

To print a buffer string ending with '\0'.
This call does not use mutex. Use btn_terminal_get_writing_lock() and btn_terminal_free_writing_lock() if mutex access is demanded

#define DEBUGL_M ( buf,
len   )     _write(_fileno(debug_uart), buf, len)

to print buffer with length len.
This call does not use mutex. Use btn_terminal_get_writing_lock() and btn_terminal_free_writing_lock() if mutex access is demanded

#define DEBUGT ( text,
...   )     DEBUGT_I(PSTR(text),## __VA_ARGS__)

to print a formated string with arguments or just plain text use only DEBUGT to put the text into ROM memory!
The DEBUGT_I() is an internal function.
This call uses mutex to access the uart!

Examples:
bt-lego/bt-lego.c, ccc-cmd/ccc-cmd.c, l2cap-cmd/l2cap-cmd.c, and sensor-app/senso.c.

#define DEBUGT_M ( text,
...   )     fprintf_P(debug_uart,PSTR(text),## __VA_ARGS__)

To print a formated string with arguments or just plain text.
This call does not use mutex. Use btn_terminal_get_writing_lock() and btn_terminal_free_writing_lock() if mutex access is demanded

#define HISTORY_DEPTH   5

Maximal history depth. This number can be ajusted.

#define INPUT_LENGTH   180

Maximal length of terminal input. This number can be ajusted.

#define LEN_CMD_NAME   10

Maximal length of command name. This number can be ajusted.

#define MAX_CMDS   50

Maximal cmds that can be registered. This number can be ajusted.


Function Documentation

void btn_terminal_free_writing_lock ( void   ) 

function to free the explicit access lock on debug uart

void btn_terminal_get_writing_lock ( void   ) 

use this function to get explicit access to the debug uart and write output with: DEBUGB_M(), DEBUGT_M() and DEBUGL_M() call btn_terminal_free_writing_lock to free lock again

void btn_terminal_init ( FILE uart,
char *  a_prompt 
)

The terminal will read and write to the file pointer passed with the uart argument. An initial prompt can be set. To change the prompt use the function: btn_terminal_set_prompt().

Parameters:
uart Pointer to device for in- and output
a_prompt Prompt to be displayed
Examples:
bt-lego/bt-lego.c, ccc-cmd/ccc-cmd.c, l2cap-cmd/l2cap-cmd.c, mhop_blink/mhop_blink.c, rfcomm-cmd/rfcomm-cmd.c, and sensor-app/senso.c.

u_char btn_terminal_process_cmd ( char *  cmd  ) 

This function provides the processing of a cmd not typed in by the terminal.
Make sure cmd is terminated by '\0'

Parameters:
cmd The command string same as typed in with terminal
Returns:
0 on success, 1 if cmd was not found

void btn_terminal_refresh ( void   ) 

to refresh the command line

void btn_terminal_register_cmd ( char *  name,
void(*)(char *)  fkt 
)

register the cmds with a command name and a function pointer. the function will be called with a char pointer argument passing the arguments AFTER the command name.

Parameters:
name Name of the command
fkt Pointer to the command function
Examples:
bt-lego/bt-lego.c, ccc-cmd/ccc-cmd.c, and mhop_blink/mhop_blink.c.

void btn_terminal_run ( u_char  type,
u_short  thread_size 
)

To start the terminal use this function.
Pass the type BTN_TERMINAL_FORK to start an own terminal thread or use BTN_TERMINAL_NOFORK to use the main thread for the terminal thread (in the later case, function call will never return)
pass thread_size in case of BTN_TERMINAL_FORK

Parameters:
type BTN_TERMINAL_FORK or BTN_TERMINAL_NOFORK
thread_size In case of BTN_TERMINAL_FORK the size of the terminal thread.
Examples:
bt-lego/bt-lego.c, ccc-cmd/ccc-cmd.c, l2cap-cmd/l2cap-cmd.c, mhop_blink/mhop_blink.c, rfcomm-cmd/rfcomm-cmd.c, and sensor-app/senso.c.

void btn_terminal_set_prompt ( char *  a_prompt  ) 

to set a new prompt

Parameters:
a_prompt New prompt to be displayed.

void btn_terminal_set_verbosity ( bool  val  ) 

Use this function to enable/disable terminal verbosity.

Parameters:
val - TRUE: echo input characters & display prompt,
  • FALSE: do not echo input characters & hide prompt

void DEBUGB ( char *  text  ) 

to print a buffer string ending with '\0'.
This call uses mutex to access the uart!

Examples:
sensor-app/senso.c.

void DEBUGL ( char *  buf,
u_char  len 
)

to print buffer with length len.
This call uses mutex to access the uart!

int DEBUGT_I ( PGM_P  fmt,
  ... 
)

internal function used by DEBUGT.

char term_register_thread ( void   ) 

Register the calling thread.

Register the calling thread.

Returns:
0 on success, 1 otherwise.

char term_start_capture ( void   ) 

Start the recording of terminal output.

Starts the recording of terminal output. After this call, all data written to the terminal using tprintf() is stored in a dedicated thread buffer. To get the buffer of the running thread, use term_stop_capture().

Returns:
0 on success, 1 otherwise.

char* term_stop_capture ( void   ) 

Stop the recording of terminal output.

Returns:
Pointer to buffer on success, NULL otherwise.

int tprintf ( CONST char *  text,
  ... 
)

use this function to capture terminal output.

Prints the formatted string passed to the terminal and captures the printed string using dedicated thread buffers.

Note: The terminal output is also written to the log buffer using class 1, log level LOG_INFO. Thus, to enable terminal output logging, call either log_set_logmask or use the corresponding terminal command.

See also:
term_register_thread

term_start_capture

term_stop_capture

log_cmds_init

Examples:
mhop_blink/mhop_blink.c.


Variable Documentation

FILE* debug_uart

file pointer to debug device.


Generated on Wed Apr 29 11:12:30 2009 for BTnut System Software by doxygen 1.5.1