MBasic: Input/Output Commands (Set 1)

Input/Output Commands (Set 1) Intro

This chapter includes the "normal" BASIC commands that are included with most versions of BASIC, as well as commands specific to Atom BASIC. Read it carefully: some familiar commands may be defined somewhat differently in Atom BASIC.

This chapter contains the following sections:

• Input/Output Commands (Set 1)
  • Debug
  • Debugin
  • Hserin
  • Hserin2*
  • Hserout
  • Hserout2
  • EnableHserial
  • EnableHserial2*
  • SetHserial
  • SetHserial2*

* Atom Pro Plus only.

Conventions Used in this Chapter

{ ... }	represent optional components in a command. The { } are not to be included.
[ ... ]	used for lists - the [ ] are required.
( ... )	used for some arguments. The ( ) are required.

Input/Output Commands

Since the BasicATOM Pro is not normally used with a computer display, the input/output commands are highly specialized and do not duplicate those of conventional BASICs. In place of the usual PRINT, LPRINT, PRINT#, etc. commands, Atom BASIC provides a range of input/output commands for various devices commonly used with microcontrollers.

Note: Many of the I/O commands in this section accept the use of command modifiers. See Chapter 8 - Command Modifiers on page 69 for more information.

DEBUG

Sends output to the Debug Watch Window in the IDE.

Syntax

debug [{mod}expr1,{mod}expr2, ... (mod)exprN]

mod is any valid output modifier (only dec, hex, bin and real)

expr is a variable, constant or expression generating data to be sent. The length of this list is limited only by available memory.

Notes

The debug command is useful only when your program is run in "debug" mode from the IDE. It provides an easy way to output the values of variables during program execution.

The debug watch window expects all output to be in ASCII characters. If variables are output directly without modifiers, their values will be interpreted as ASCII, which may give unexpected results. Word and long variables will output only the low order 8 bits unless a suitable modifier is used to convert to decimal, hex or binary.

The debug watch window accepts certain terminal commands including (but not limited to) the following:

Character	decimal value	function
NUL	0	clear screen
BEL	7	ring bell
BS	8	backspace
LF	10	new line
CR	13	new line

A more complete list will be found in the IDE documentation.

Example

We'll use the following program to test the debug command.

counter var word
cr con 13
for counter = 300 to 306
debug [dec counter,cr]
next

We first type in the program using the IDE (which must be connected to the BasicATOM Pro). Then click the DEBUG button. The program should compile with no errors, and the Atom Pro will be programmed. After this process you'll see a screen like this one:

Now click on the RUN button:

Your program should run and produce the following output:

After it runs, the Atom Pro will go to sleep and stop responding. To run your program again, simply press the RESET button on the Atom development board.

DEBUGIN

Accepts keyboard input from the Debug Watch Window. See the example under DEBUG which shows how to invoke this window.

Syntax

debugin [{mod}var1,{mod}var2, ... (mod)varN]

var is a variable that tells DEBUGIN what to do with incoming data. A comma delimited list or variables is supported.

The list is of the form [{mod} var1, {mod} var2... {mod} varN] where mod is an optional input modifier (only dec, hex, bin and real) and var is a variable of the appropriate size.

Notes

In the absence of modifiers DEBUGIN assigns each keystroke to a single variable. Program execution will wait until all variables have input; there is no timeout with the DEBUGIN command.

See the example under HSERIN, below, for details about the use of input modifiers, delimiting characters, etc.

Example

counter var word
start var word
temp var byte
cr con 13
start=300
loop
   debugin [temp] ; wait for any keystroke
   for counter = start to start+6
      debug [dec counter,cr]
   next
   start=counter
go to loop

In this example the DEBUGIN command is used simply to pause program execution. The temp value is echoed to the screen, but is otherwise ignored.

The program will output six numbers in sequence, starting with 300. Then it will wait for any key to be pressed before displaying the next six numbers.

Of course, DEBUGIN can be used to assign values to variables in exactly the same way as other input commands, such as HSERIN, SERIN, etc. The rest of this section has several helpful input examples.

HSERIN

This command accepts input via the hardware serial port. Before using this command the ENABLEHSERIAL compiler directive must be in the program, and you must use the SETHSERIAL command (see page 107) to set the correct baud rate, data bits, parity and stop bits. HSERIN is similar in operation to SERIN (see page 109) except that it uses the hardware serial input pin RXD (see pinouts on page 187) and the baudrate is set by the SETHSERIAL command.

Syntax

hserin {timeout,tlabel,}[{mod}var1,{mod}var2, ... (mod)varN]

timeout is an optional expression which specifies the time in milliseconds to wait for data to be received.

Important: The timeout value has changed to .5 microsecond increments with the current versions of Basic Micro Studio.

tlabel is the target label where program execution continues if timeout is exceeded. tlabel must be specified if a timeout value is set.

mod is any valid input modifier (optional).

var is a variable or list of variables (comma delimited) where data will be stored.

Example

In the following example, "illegal" characters are used as delimiters in the input data stream.

ant var word
bat var word
cat var word
dog var word
sethserial h2400,h8databits,hnoparity,h1stopbits
hserin 10000,nomore,[dec ant,bat,cat,hex dog]
   ;continues here once all data is received
nomore
   ;continues here if no data is received for 10 seconds

The port is set to 2400 baud, 8 bit, no parity, with 1 stop bit.

Input data will be converted from ASCII decimal to numeric form and assigned to "ant" until a non-numeric character is received. That character will be discarded.

The next two input bytes will be assigned to "bat" and "cat" respectively. (Each unmodified input byte is assigned to one variable.)

Following data will be converted from ASCII hex to numeric form and assigned to "dog" until a non-hex character is received. That character will be discarded.

If 10 seconds elapses with no new data, program execution will jump to the label nomore.

For example, if the input data stream contains the following bytes starting at the left (shown in hex and ASCII format):

hex	31	38	2C	61	62	32	44	39	2C
ASCII	1	8	,	a	b	2	D	9	,

• "ant" will be assigned the numeric value 18
• the "," will terminate input for "ant" and be discarded
• "bat" will be assigned the numeric value 97 (i.e. 61 hex)
• "cat" will be assigned the numeric value 98 (i.e. 62 hex)
• "dog" will be assigned the numeric value 729 (i.e. 2D0 hex)
• the "," will terminate input for "dog" and be discarded

Example

In the following example, the input data stream must be pre-formatted into the correct number of bytes for each variable.

ant var word
bat var word
cat var word
sethserial h2400,h8databits,hnoparity,h1stopbits
hserin [dec4 ant\4, bat, hex3 cat\3]

This format expects exactly 4 ASCII decimal digits (which will be converted to a number and assigned to "ant"), followed by 1 numeric byte (which will be assigned directly to "bat" with no conversion), followed by exactly 3 ASCII hex digits (which will be converted to a number and assigned to "cat").

HSERIN2 (Atom Pro Plus only)

This command reads data from the second hardware serial port available on the Atom Pro Plus. In operation it is almost identical to the HSERIN command, and shares the same syntax.

Syntax

hserin2 {timeout,tlabel,}[{mod}var1,{mod}var2, ... (mod)varN]

timeout is an optional expression which specifies the time in milliseconds to wait for data to be received

Important: Note: the timeout value has changed to .5 microsecond increments with the current versions of Basic Micro Studio.

tlabel is the target label where program execution continues if timeout is exceeded. tlabel must be specified if a timeout value is set.

mod is any valid input modifier (optional).

var is a variable or list of variables (comma delimited) where data will be stored.

Notes

Before using this command the ENABLEHSERIAL2 compiler directive must be in the program, and you must use the SETHSERIAL2 command (see page 109) to set the correct baud rate, data bits, parity and stop bits. HSERIN2 uses the hardware input pin RXD_2 (see pinouts on page 187).

HSEROUT

This command sends output to the hardware serial port. Before using this command the ENABLEHSERIAL compiler directive must be in the program, and you must use the SETHSERIAL command (see page 107) to set the port parameters. HSEROUT is similar in operation to SEROUT (see page 111).

Syntax

hserout [{mod}exp1,{mod}exp, ...{mod}expN]

mod is any valid output modifier

exp is an expression or list of expressions (comma delimited) generating data to be sent.

Example

ant var byte
bat var byte
cat var byte
ant=65 ; hex 41
bat=99 ; hex 63
cat=66 ; hex 42
sethserial h2400,h8databits,hnoparity,h1stopbits
hserout [dec ant,bat,hex4 cat\4]

The port is set to 2400 baud, 8 bit, no parity, with 1 stop bit.

The output will be the following:

hex	06	06	63	30	30	34	32
ASCII	6	5	c	0	0	4	2

Remember that "hex4 c\4" specifies that the output will be exactly 4 hex digits.

HSEROUT2

This command sends data to the second hardware serial port available on the Atom Pro Plus. In operation it is almost identical to the HSEROUT command, and shares the same syntax.

Syntax

hserout2 [{mod}exp1,{mod}exp, ...{mod}expN]

mod is any valid output modifier

exp is an expression or list of expressions (comma delimited) generating data to be sent.

Notes

Before using this command the ENABLEHSERIAL2 compiler directive must be in the program, and you must use the SETHSERIAL2 command (see page 109) to set the correct baud rate, data bits, parity and stop bits. HSEROUT2 uses the hardware output pin TXD_2 (see pinouts on page 187).

ENABLEHSERIAL

This is a compiler directive that enables the hardware serial port system (SCI3) on the Atom Pro and Atom Pro Plus (RXD/TXD).

Syntax

enablehserial

ENABLEHSERIAL2 (Atom Pro Plus only)

This is a compiler directive that enables the hardware serial port system (SCI3_2) on the Atom Pro Plus (RXD_2/TXD_2)

Syntax

enablehserial2

SETHSERIAL

Sets the baud rate, data bits, parity and stop bits for the hardware serial port (SCI3), initializes the serial buffers and enables the hardware serial port interrupt handler. This command must be executed before hserin or hserout are used.

Important: The ENABLEHSERIAL compiler directive must be in your program for this command to function properly.

Note: When using the hardware serial system the interrupts for the hardware serial port should not be used except by advanced programmers.

Syntax

sethserial baudrate, databits, parity, stopbits

baudrate is any of the following values. (The values in this list are predefined constants having the appropriate numeric values for the respective baud rates.)
H300	H12000	H26400	H57600
H600	H14400	H28800	H62500
H1200	H16800	H31200	H125000
H2400	H19200	H33600	H250000
H4800	H21600	H36000	H312500
H9600	H24000	H38400	H500000
databits can be either of the following constants.
H8DATABITS, H7DATABITS
parity can be any of the following constants.
HNOPARITY, HEVENPARITY, HODDPARITY
stopbits can be either of the following constants.
H1STOPBITS, H2STOPBITS

Examples

See hserin and hserout for examples.

SETHSERIAL2 (Atom Pro Plus only)

Sets the baud rate, data bits, parity and stop bits for the second hardware serial port (SCI3_2), initializes the serial buffers and enables the hardware serial port interrupt handler. This command must be executed before hserin2 or hserout2 are used.

Important: The ENABLEHSERIAL2 directive must be in your program for this command to function properly.

Syntax

Syntax is identical to SETHSERIAL.

Notes

The SETHSERIAL2 command is identical in operation to SETHSERIAL except that it applies to the second hardware serial port (TXD_2, RXD_2).