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).