Input / Output
| input
|
opencom closecom defport() |
inp() inpput() inpstr$() inpbuf$() |
key?()
Key() out out$ |
BASIC offers the input and print statements but these are a bit too restrictive for microcontroller use. All of the input and output (excluding files) is done through a UART (Universal Asynchronous Receiver and Transmitter). Usually there is more than one. The two UARTS are fully software buffered, each 128 bytes. If the buffer becomes full or there is an overrun error this can be checked with the 'error()' statement see user interface for a list of error numbers.
| input |
| input [<prompt
string>] v,v,... input “Name “ a$ input “Name & age “ a$,age input num |
This is the classic BASIC input command that is used for obtaining input from the user. It is worth noting here that automatic conversion will take place based on the variable names supplied. As an example input a$ If the response to this was say 12.6, then the variable a$ would contain the string “12.6”. If more than 1 variable is supplied, input is not passed onto the next variable until <enter> is pressed. The prompt must be a literal string, i.e. not a variable.
| print <value>[,][;] print “fred” print “a$=”;a$ print a,b,c print |
Print is used to output characters to the default port. Print on its own will output a line feed, by default a linefeed is output at the end of a print statement. To suppress this behavior a semicolon ‘;’ can be used:
print “ Fred”
This will output ‘Hello Fred’ as the ‘;’ will stop the default linefeed at the end of the first print statement. A comma is used to ‘tab’ 4 spaces which can be used for rudimentary formatting.
| opencom |
| opencom
<port><baud><mode>[,CTS,RTS] opencom 1 9600 0 opencom 1 9600 0,"d2" opencom 1 9600 0,"d0","e4" opencom 1 9600 1,,"b12" |
The following commands all require a com port to be open before they can be used. The default com port is always open so this can be used without using this command. The default com port can also be changed with this command to say alter the baud rate or handshaking.
To change the Baud rate to 115200 of the default com port
and to retain the default settings use the following command
opencom 2 115200 0,,"b14"
The above is the default setting which gives partial hardware handshaking via
port B14, the RTS is an output that will go high if BV513 is busy thus
temporarily stopping the host from transmitting. To implement full handshaking,
and for this the host needs to have its RTS low, then the following would be
needed:
opencom 2 115200 0,"b8","b14"
NOTE that the effect is immediate.
If a semi-permanent Baud rate other than the default is required then put this
into an auto function and either save it to Flash or to an SD Card, for
example.
function auto
opencom 2 115200 0,,"b14"
endf
A port number is assigned physically to a UART and in most microcontrollers there are two UART'S. The default UART, the one used for loading programs and communication can be found using the 'defport' keyword. Version 1.472 introduced a software buffer and an interrupt handler to manage serial input.
The command has 5 parts, the last two being optional. The first specifies the com port, the second specifies the baud rate, which must be a whole number the third specifies the mode and the optional parts specify hardware handshaking.
| Mode | Description |
| 0 | 8 data bits, no parity, 1 stop bit |
| 1 | 8 data bits, no parity, 2 stop bits |
| 2 | 8 data bits, even parity, 1 stop bit |
| 3 | 8 data bits, even parity, 2 stop bits |
| 4 | 8 data bits, odd parity, 1 stop bit |
| 5 | 8 data bits, odd parity, 2 stop bits |
| 6 | 9 data bits, no parity, 1 stop bit |
| 7 | 9 data bits, no parity, 2 stop bits |
CTS, RTS
If nothing is specified after the mode number then there is no handshaking. To implement hardware handshaking a port is specified which will be used for that purpose. As shown in the examples, just CTS, RTS or both can be specified. The first character of the string is the port name 'b' through 'g' and the second is the bit within the port to be used.
CTS
Clear to Send (CTS) is an input and must be held low for the port to operate. If it is taken high by the connected device then output will be suspended. This will normally be connected to RTS on the other device.
RTS
RTS is an output that will be held low by the BV5xx when it is
ready to receive characters form the connected device. It will put this
line high if it is busy.
| closecom |
| closecom <port> closecom 1 |
The only reason to close a com port is to free up the port bit lines that are used for this service, no extra resources are taken by leaving the port open.
| defport() |
| a=defport() print defport |
Returns the current default port, in most cases this will be '2' which refers to a physical UART that all BASIC communications use.
| key?() |
| key?(port) a=key?(2) |
This returns a value of 1 if there is a key waiting in the key buffer. The key (without the ?) statement will wait until a key is available before returning to the program so it is useful when not wanting to halt the program. The values returned by this function are as follows:
0 = no key waiting in buffer
1 = key available to collect by key() **
-1 = overrun error **
** From version 1.472 key?() returns the number of keys in the buffer, errors such as overrun or buffer full are trapped by Basic and reported to the consol.
some code..
wend
In the above code snippet, assuming that 2 is the default com port, the code inside the while loop will execute until the user presses a key.
| key() |
| key(port) a=key(2) |
This will return the key that has been received from the UART. It will wait for a key and so it may be wise to use key? first otherwise the program will lock until some information has been received.
| inpput() |
| inpput(<port>)=value inpput(1)='a' |
This will place a character in the input buffer. This can be useful for looking or checking a character in the buffer and then putting it back if it is not required or the one needed. See also inpbuf$() which can also be used for similar purposes.
| out |
| out <port><int
value> out 1 13 |
This will send a byte to the designated com port (UART), values are anded with 0xff before sending. In the above example the byte 13 is sent to UART 1.
| out$ |
| out$
<port><string> out$ 1 “fred” out$ 1, "fred" |
This will send a string to the designated UART (port). The first value id the port number and the second is the string. An optional comma can be used. When sending character constants for example:
out$ 1, *27+"2J"
The comma is necessary otherwise an error will occur.
| inp() |
| inp(port,var$,timeout
ms,terminate&) a=inp$(1,b$,0,13) b=inp$(1,ip$,20,’>’) |
This is a general purpose input from the selected UART. It returns the number of characters that have been received.
a=inp(1,a$,20,13)
In the above, a will receive the number of characters that have been input from the UART. a$ is the variable that the characters will be put into, 20 is the time out in ms and 13 is the terminating character. This keyword will wait for 20ms in this case for the terminating character to be received. If the character is not received it will return 0 and a$ will be blank. If the terminating character is received before 20ms then it will return as soon as the terminating character is received.
Zero is a valid time to enter for the time out. In this case the keyword will simply look for the string in the buffer, terminating with the given character and either return the length of the string (including the terminating character) and a$ filled or return 0. If the length of the string is shorter then the number of characters received only those characters that will fit into the sting will be returned.
The terminating character is used to tell the statement when to terminate the input (return back to the program). This is most likely to be 10 (LF) or 13(CR) but could be any valid character with a value between 0 and 255.
Notes:
- The maximum number of characters that can be received is set by the size of the variable minus 1.
- The data received in the variable always has a 0 appended to the end of it.
- The statement does not echo characters back to the UART.
- If this statement called by a process then the timeout value should be less than the process period, ideally it should be set to 0.
| inpstr$() |
| a$=inpstr$(port,
<wait>) a$=inpstr$(1,0) |
This is almost functionally equivalent to inp(1,a$,0,13). It differs in that if there is a LF (10) following the CR (13) it will get that and append it to the string. There is also the option of waiting for the CR. If wait is set to 1 [a$=inpstr$(1,1)] then the program will say in this statement until a CR is received. If wait is set to 0 then the statement will return immediately with a$ containing the full string, up to the CR or LF or it will return with a length of 0.
NOTE: Using the wait option it is not guaranteed that the following LF will be captured, if this is required then use the inp() statement with a long time delay. The maximum length of string returned is set by the string length default. A memory error may occur if the sting variable is smaller then the number of characters received.
| inpbuf$() |
| a$=inpbuf$(port) a$=inpbuf$(1) |
This will get the UNREAD contents of the buffer and place it in the string variable. The difference between this and the other input keywords is that this does not consume the buffer contents. This takes a snapshot of the characters in the buffer that are waiting to be read.