FANDOM


Input/Output Commands (Set 2) Intro Edit

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 2)
    • Serin
    • Serout
    • Serdetect
    • I2Cin
    • I2Cout
    • Owin, Owout
    • Shiftin
    • Shiftout


Conventions Used in this Chapter Edit

{ ... } 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 Edit

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.


SERIN Edit

This command receives serial input (i.e. asynchronous RS-232 data) through a specified I/O pin.

Syntax

serin rpin{\fpin},baudmode,{plabel,}{timeout,tlabel,}[InputData]
rpin is a variable or constant that specifies the I/O pin through which the serial data will be received. This pin will switch to input mode and remain in that state after the end of the instruction.
\fpin is an optional variable or constant that specifies the I/O pin that will be used for flow control (the "\" is required). This pin will switch to output mode and remain in that state after the end of the instruction.

Note: Flow control is provided for use primarily with PCs and conforms to PC serial port standards.

baudmode is a 16 bit variable or constant that specifies serial timing and configuration. See the description under Notes.
plabel is an optional label. The program will jump to plabel if there is a parity error.
timeout is an optional 32 bit variable or constant that specifies the time to wait for incoming data in milliseconds. If data does not arrive within this time, the program will jump to tlabel.

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

InputData is a list of variables and modifiers that tells SERIN what to do with incoming data. See the examples under HSERIN (page 101) for a detailed description of this list.

Notes - Baudmode

The baudmode value is built as follows:

bit 15 14 13 12-0
function not used for SERIN polarity

0 = normal
1 = inverted

data/parity

0 = 8 bits, no parity
1 = 7 bits, even parity

bit period

Note: "polarity" applies to both data and flow control.

Programmers will not normally "build" this value themselves. The two preferred methods are:

  • Use a predefined constant from the list below, or
  • Use the SERDETECT command to automatically produce the required value as a variable.

Baudmode predefined constants

Note: You may equally well use the baudmode constant described under SEROUT for the SERIN command. The extra letter (O) will be ignored for SERIN.

The constants consist of 1 or 2 letters, in the order shown below, followed by the baud rate:

N indicates "normal" data and flow control ("normal" data for RS232 uses LOW (negative) for 1 and HIGH (positive) for 0.)
I indicates "inverted" data and flow control
E indicates "even parity, 7 bits", else "no parity, 8 bits"
Baud rate may be any one of 300, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 33600, 38400 or 57600

Either N or I (not both) must be used as the first letter of the constant. E is optional. If E is not used, baudmode defaults to no parity, 8 bit data.

For example, the constant "NE2400" indicates non-inverted data, 7 bits even parity, 2400 baud. The constant "I19200" indicates inverted data, 8 bits no parity, 19,200 baud.

Note: You can confirm the syntax of your constant by checking the List of Reserved Words on page 191.

Important: At least "N" or "I" must precede the baud rate or the constant will simply be taken as a number, which is invalid for this application.

Examples

This example is modified from the example given in HSERIN. See that example for detailed explanation of the data list.

ant var word
bat var word
cat var word
dog var word
serin P3\P4,NE2400,5000,expd,[dec ant,bat,cat,hex dog]
   ;program continues here
...
expd ; jumps here if timeout
   ;timeout processing

Serial input is on I/O pin 3, with pin 4 used for flow control. Data format is non-inverted, even parity, 7 bits, 2400 baud. Input will wait for 5 seconds (5000 ms) between bytes, and jump to "expd" if that time is exceeded with no data available.

SEROUT Edit

This command sends serial output (i.e. RS232 asynchronous data) through a specified I/O pin. SEROUT can be used in two modes: with flow control or with timed intervals between bytes.

Note: Flow control is provided for use primarily with PCs and conforms to PC serial port standards.

Syntax

With timed intervals:

serout tpin,baudmode,{pace,}[OutputData]

With flow control:

serout tpin\fpin,baudmode,{timeout,tlabel,}[OutputData]
rpin is a variable or constant that specifies the I/O pin through which the serial data will be sent. This pin will switch to output mode and remain in that state after the end of the instruction.
\fpin is an optional variable or constant that specifies the I/O pin that will be used for flow control (the "\" is required). This pin will switch to input mode and remain in that state after the end of the instruction.
baudmode is a 16 bit variable or constant that specifies serial timing and configuration. See the description under Notes.
pace is an optional variable or constant (0 - 65535) that tells SEROUT how many milliseconds to wait between transmitting bytes. If pace is omitted, there will be no delay between bytes. Flow control is preferable to fixed output timing: pace is provided for use with peripherals that don't support flow control. Normally either flow control or delay is used, not both.
timeout is an optional 16 bit variable or constant that specifies flow control timeout in milliseconds. If data is halted by the receiving device for longer than this time, the program will jump to tlabel.
OutputData is a list of variables and modifiers that tells SEROUT what to do with outgoing data. See the examples under HSEROUT (page 106) for a detailed description of this list.

Notes - Baudmode

Baudmode for SEROUT is the same as baudmode for SERIN with the exception of bit 15. The baudmode value is built as follows:

bit 15 14 13 12-0
function output state polarity

0 = normal
1 = inverted

data/parity

0 = 8 bits, no parity
1 = 7 bits, even parity

bit period

Note: If the value of "output state" is 0, the output pin will be driven for both high and low states. If the value is 1, the output pin will be driven for low, and open drain for high (requires external pullup).

Note: "polarity" applies to both data and flow control.

Programmers will not normally "build" this value themselves. The two preferred methods are:

  • Use a predefined constant from the list below, or
  • Use the SERDETECT command to automatically produce the required value as a variable (this only works with bi-directional peripherals that can send as well as receive serial data).

Baudmode predefined constants

Note: The SEROUT baudmode constants may also be used for SERIN. The "O", which sets bit 15, will simply be ignored for SERIN.

The constants consist of 1, 2 or 3 letters, in the order shown below, followed by the baud rate:

N indicates "normal" data and flow control ("normal" data for RS232 uses LOW (negative) for 1 and HIGH (positive) for 0."
I indicates "inverted" data and flow control
E indicates "even parity, 7 bits", else "no parity, 8 bits".
O indicates open drain, else both high and low are driven.

Either N or I (not both) must be used as the first letter of the constant. E is optional. If E is not used, baudmode defaults to no parity, 8 bit data. O is also optional, if not used both high and low states are driven.

Baud rate may be any one of 300, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 33600, 38400 or 57600

For example, the constant "NE2400" indicates non-inverted data, 7 bits even parity, 2400 baud. The constant "IO19200" indicates inverted data, 8 bits no parity, 19,200 baud, with open drain for the high state (which is data "1" in this case).

Note: You can confirm the syntax of your constant by checking the List of Reserved Words on page 191.

Important: At least "N" or "I" must begin the constant or it will simply be taken as a number, which is invalid for this application.

Examples

This example is modified from the example given in HSEROUT. See that example for detailed explanation of the data list.

ant var byte
bat var byte
cat var byte
ant=65 ; hex 41
bat=99 ; hex 63
cat=66 ; hex 42
serout P5\P6,NEO2400,5000,expd,[dec ant,bat,hex4 cat\4]
   ;program continues here
...
expd ; jumps here if timeout
   ;timeout processing

Serial output is on I/O pin 5, with pin 6 used for flow control. Data format is non-inverted, even parity, 7 bits, 2400 baud, open drain on high bits. The ATOM PRO will wait for a maximum of 5 seconds between bytes; if the receiving device is not ready (as determined by the flow control pin) after that time program execution will jump to "expd".


SERDETECT Edit

Used to auto-detect baud rates and build the "baudmode" value used with SERIN and SEROUT

Syntax

serdetect pin,mode,var
pin is a variable or constant that specifies the I/O pin that will be used to receive the sync character. This pin will switch to input mode and remain in that state after the end of the instruction.
var is a word variable used to store the resulting baudmode value.
mode determines the setting for bits 15, 14 and 13 of the baudmode variable (see SERIN and SEROUT for details of these bits). For convenience, mode may use one of the following predefined constants:
bit 15 bit 14 bit 13 constant description
0 0 0 NMODE both driven, normal, 8 bit no par
0 0 1 NEMODE both driven, normal, 7 bit even
0 1 0 IMODE both driven, inverted, 8 bit no par
0 1 1 IEMODE both driven, inverted, 7 bit even
1 0 0 NOMODE open drain, normal, 8 bit no par
1 0 1 NEOMODE open drain, normal, 7 bit even
1 1 0 IOMODE open drain, inverted, 8 bit no par
1 1 1 IEOMODE open drain, inverted, 7 bit even

Notes

SERDETECT is used to auto detect an incoming baud rate. This is ideal for applications or peripherals that can be used at different baud rates since it allows software switching of the Atom Pro. SERDETECT eliminates the need for switches or jumpers to select baud rates.

Note: For bi-directional devices, such as a PC serial port, the value may also be used for sending data after the detection is made.

SERDETECT works by measuring the length of one bit in the first received character. The sending device must send one of the following characters (X = don't care):

Normal data %XXXXX101 (binary)
Inverted data %XXXXXX01 (binary)

A short delay (or suitable flow control) after this byte will allow the SERDETECT command to be processed.

Once the time has been calculated, SERDETECT combines this with bits 15 - 13 as specified by the mode value to generate the correct value for use in baudmode with SERIN and SEROUT.

Examples

This example is the same as that given under SERIN except that SERDETECT is used to set baud rate.

ant var word
bat var word
cat var word
dog var word
baudset var word
serdetect P3,nemode,baudset
serin P3\P4,baudset,5000,expd,[dec ant,bat,cat,hex dog]
   ;program continues here
...
expd ; jumps here if timeout
   ;timeout processing

The SERDETECT command will "build" the correct value for baud rate and parameters, and save it as "baudset", which is then used in SERIN in place of a pre-determined baudmode parameter.


I2CIN Edit

Receives data from an I2C device such as an EEPROM, external A/D converter, etc.

Syntax

i2cin DataPin,ClockPin,{ErrLabel,}Control,{Address,}[varlist]
DataPin is a variable or constant that specifies the I/O pin to use for SDA (serial data). This pin will switch to input mode and remain in that state after the end of the instruction.
ClockPin is a variable or constant that specifies the I/O pin to use for SCL (serial clock). This clock is generated by the BasicATOM Pro. This pin will switch to output mode and remain in that state after the end of the instruction.
ErrLabel is a label that the program will jump to if the I2CIN command fails (e.g. the device is disconnected, turned off, etc.)
Control is a variable or constant that specifies the I2C device's control byte. This byte is defined as follows:
bits 7-4 Device type. For serial EEPROMs this should be %1010. For other I2C peripherals, refer to the

documentation of the peripheral.

bits 3-1 Device ID. You can address up to 8 devices on the same I2C bus simultaneously. For example, if the address lines (A0 - A2) of a serial EEPROM are grounded, these bits should be %000.
bit 0 Addressing format.

0 = 8 bit addressing
1 = 16 bit addressing

Address is an optional variable or constant that specifies the starting address to read from (default is 0). This value should be 8 or 16 bits as set by bit 0 of the Control byte (see above).
Varlist is a list of modifiers and variables that tells I2CIN what to do with incoming data. See the examples under HSERIN (page 101) for a detailed description of this list.

Note: An EEPROM read address is automatically incremented with each byte read.

Notes

Important: This manual does not attempt to document or describe the I2C protocol in any detail. Users are advised to consult available sources for that information.

I2C is a two-wire synchronous serial protocol used to communicate with a variety of peripherals such as EEPROMs, A/D converters, etc. I2C is similar to SMBus and the two may normally be used interchangeably.

I2C is a master/slave protocol with the master being able to address the various slave devices. This allows multiple slaves to share the same bus. Each slave must have a unique address.

Note: In I2C applications the BasicATOM Pro is always a Master.

Example

ant var byte
bat var byte
cat var byte
dog var byte
control var byte
address var byte
control=%10100000
address=$100
i2cin P3,P4,fail,control,address,[ant,bat,cat,hex dog]
   ;program continues here
...
fail ; jumps here if error
   ;error processing

This program will read 4 bytes from an EEPROM, starting at address $100, and assign them to variables ant, bat, cat and dog. The fourth byte is assumed to be in ASCII hex format, and will be converted to numeric format. The other bytes are assumed to already be in numeric format.

The serial EEPROM has a device address of %000 (this is important if there are multiple serial EEPROMS on the same I2C bus).

If communications fails for any reason (usually device not connected or powered on) program execution will jump to the label "fail".


I2COUT Edit

Sends data to an I2C device such as an EEPROM, external A/D converter, etc.

Syntax

i2cout DataPin,ClockPin,{ErrLabel,}Control,{Address,}[varlist]
DataPin is a variable or constant that specifies the I/O pin to use for SDA (serial data). This pin will switch to output mode and remain in that state after the end of the instruction.
ClockPin is a variable or constant that specifies the I/O pin to use for SCL (serial clock). This clock is generated by the BasicATOM Pro. This pin will switch to output mode and remain in that state after the end of the instruction.
ErrLabel is a label that the program will jump to if the I2COUT command fails (e.g. the device is disconnected, turned off, etc.)
Control is a variable or constant that specifies the I2C device's control byte. This byte is defined as follows:
bits 7-4 Device type. For serial EEPROMs this should be %1010. For other I2C peripherals, refer to the documentation of the peripheral.
bits 3-1 Device ID. You can address up to 8 devices on the same I2C bus simultaneously. For example, if the address lines (A0 - A2) of a serial EEPROM are grounded, these bits should be %000.
bit 0 Addressing format.

0 = 8 bit addressing
1 = 16 bit addressing

Address is an optional variable or constant that specifies the starting address to write to (default is 0). This value should be 8 or 16 bits as set by bit 0 of the Control byte (see above).
Varlist is a list of modifiers and variables that tells I2COUT what data to output. See the example under HSEROUT (page 106) for a more detailed description of this list.

Note: An EEPROM write address is automatically incremented with each byte sent.

Notes

The I2C protocol is briefly described under Notes on page 117.

Note: In I2C applications the BasicATOM Pro is always a Master.

Serial EEPROMs use an input buffer to store data before it is written, since the writing process is typically slower than the I2C data transfer. The size of this input buffer is specified on the EEPROM data sheet. You must not exceed the buffer size in a single I2COUT command or data will be lost.

Once you have output one buffer's worth of data, you must wait the appropriate time for the data to be written before issuing another I2COUT command. This time is specified on the EEPROM data sheet.

Note: Refer to the EEPROM data sheet to determine buffer size and writing time.

See the examples below for one possible implementation of this procedure.

Example

a var byte(128)
control con %10100000
count1 var byte
count2 var byte
temp var byte
temp=0
code to populate a(0) to a(127)
for count1 = 1 to 8
   for count2 = temp to temp+16
      i2cout P3,P4,failed,control,[a(temp)]
   next
   pause 1600 ; delay to allow writing
   temp = count2
next
   ;program continues here
failed
   ;executed if connection fails

This program first populates an array with 128 bytes of data, then writes the data to an external serial EEPROM.

The I2C uses P3 for data, P4 for clock, and sends to an EEPROM with device number 0, using 8 bit data. The EEPROM has a 16 byte buffer and requires 100 ms to write each byte, or 1600 ms to empty the buffer.

The nested for... next loops output the array 16 bytes at a time, pausing for 1600 ms between each 16 bytes. If the connection fails program execution continues with the label "failed".


OWIN, OWOUT Edit

OWIN receives data from a device using the 1-wire protocol.

OWOUT sends data to a device using the 1-wire protocol.

Syntax

owin pin,mode,{NCLabel,}[varlist]
owout pin,mode,{NCLabel,}[varlist]
pin is a variable or constant that specifies the I/O pin to be used for 1-wire data transfer. This pin will switch to the appropriate direction and remain in that state after the end of the instruction.
mode is a variable, constant or expression the specifies the data transfer mode as described in the table below.
Mode Reset Byte/bit Speed
0 none byte low
1 before data byte low
2 after data byte low
3 before and after byte low
4 none bit low
5 before data bit low

Note: Refer to your device data sheet to determine the required settings. Data sheets can usually be found online using a search engine.

NCLabel is a label the program will jump to if communications fails (No Chip present).
varlist is a list of modifiers and variables that tells OWIN where to assign received data, or OWOUT what data to output. See the examples under HSERIN (page 101) and HSEROUT (page 106) for more detailed descriptions of this list.

Notes

The 1-wire protocol was developed by Dallas Semiconductor. It is a 1 wire asynchronous serial protocol that does not require a clock lead (as is the case with I2C).

1-wire uses CMOS/TTL logic levels, open collector output. The data line requires an external pullup to the +5V supply of the Atom Pro. A value of 10K is suitable for short distances, 4.7K is better for longer runs. The master initiates and controls all activities on the 1-wire bus.

Note: In 1-wire applications the BasicATOM Pro is always a Master.

Example:

This example shows a sample program for reading a temperature sensor (Dallas DS1820):

Note: See the DS1820 data sheet for further details on the commands used in this program and for the use of the 1-wire protocol.

temp var word
convert var long
counter var byte
main
   owout P0,1,main,[$cc,$44] ;note 1
Wait
   owin P0,0,[temp] ;note 2
   if temp = 0 then wait ;note 3
   owout P0,1,main,[$cc,$be] ;note 4
   owin P0,0,[temp.byte0,temp.byte1] ;note 5
   convert = float temp fdiv 2.0 ;note 6
   debug ["Temperature = ",real convert," C",13] ;note 7
goto main
Note 1 Output is via I/O pin 0, byte mode, low speed, reset before data. $cc (Skip ROM) sets the DS1820 to accept commands regardless of its unique ID code, thus eliminating the need for the programmer to know that code. $44 (Convert T) initiates the temperature conversion and stores the result in the DS1820's scratchpad

memory.

Note 2 Input is via I/O pin 0, byte mode, low speed, no reset. Input data will be 0 while conversion is in progress, 1 when data is ready in the scratchpad.
Note 3 Loop waiting for input data to be ready (i.e. data = 1).
Note 4 $cc is Skip ROM, as before. $be (Read Scratchpad) tells the DS1820 to send the two bytes from its scratchpad to the Atom Pro.
Note 5 Reads the two bytes from the DS1820's scratchpad and stores them in temp. Note the use of the variable modifiers byte0 and byte1 to "build" the word variable temp.
Note 6 Converts the temperature to floating point format. The division by 2 is required because the DS1820's output is in 0.5°C steps.
Note 7 Outputs the temperature to the debug watch window. Display is in the form "Temperature = 35 C" followed by a new line (13).


SHIFTIN Edit

Reads data from a synchronous serial device (also knows as shifting in data). Unlike the previously described input commands (HSEROUT, SEROUT, I2COUT, OWOUT), SHIFTOUT operates on a bit, rather than a byte, basis.

Syntax

shiftin dpin,cpin,mode,[result{\bits}{result{\bits}...}]
dpin is a variable or constant that specifies the Data input pin. This pin will switch to input mode and remain in that state after the end of the instruction.
cpin is a variable or constant that specifies the Clock output pin. This pin will switch to output mode and remain in that state after the end of the instruction.
mode is a value (0 to 7) or a predefined constant that sets the incoming data conditions according to the following table:
Constant value speed data order** sampling
msbpre or msbfirst* 0 normal msb first before clock
lsbpre or lsbfirst* 1 normal lsb first before clock
msbpost 2 normal msb first after clock
lsbpost 3 normal lsb first after clock
fastmsbpre 4 fast msb first before clock
fastlsbpre 5 fast lsb first before clock
fastmsbpost 6 fast msb first after clock
fastlsbpost 7 fast lsb first after clock
* provided for backwards compatibility with previous versions.
** MSB means "Most Significant Bit", i.e. the highest order or leftmost bit of a nibble,

byte, word or long number. LSB means "Least Significant Bit", i.e. the lowest order or rightmost bit of a nibble, byte, word or long number.

Fast mode runs at the highest possible speed, normal is limited to 100 kb/s.
result is a variable where incoming data is stored. There can be multiple variables in a list, as shown in the examples.
bits is an optional entry (1 - 32) defining the number of bits that will be stored in each variable in the list. Default is 8 bits.

Note: Refer to the data sheet for the peripheral device to determine the proper settings.

Notes

In synchronous serial communication, a clock signal (running at the bit rate) is provided by the master (the Atom Pro is configured automatically as the master) on a pin separate from the data signal. The remote device uses this clock signal to set the timing for transmitting bits to the Atom Pro.

When receiving bits, the Atom Pro expects one bit per clock pulse. The timing (set by the remote device) sends the bits either at the start (before) or end (after) each clock pulse.

When connecting the peripheral device, use the following pins:

Atom Pro Peripheral
Data output Data input
Data input Data output
Clock Clock

This form of communications is used by analog-digital converters, digital-analog converters, clocks, memory devices and other peripherals. Trade names include SPI and Microwire.

Example

ant var byte
bat var word
cat var long
shiftin P3,P4,msbpre,[ant,bat\16,cat\32]

This program will input 8 bits and store them in "ant", 16 bits and store them in "bat", and 32 bits and store them in "cat". Input will be at "normal" speed, msb first, and bits are expected at the start of clock pulses.


SHIFTOUT Edit

Writes data to a synchronous serial device (also knows as shifting in data). Unlike the previously described input commands (HSEROUT, SEROUT, I2COUT, OWOUT), SHIFTOUT operates on a bit, rather than a byte, basis.

Syntax

shiftout dpin,cpin,mode,[var{\bits}{var{\bits}...}]
dpin is a variable or constant that specifies the Data output pin. This pin will switch to output mode and remain in that state after the end of the instruction.
cpin is a variable or constant that specifies the Clock output pin. This pin will switch to output mode and remain in that state after the end of the instruction.

Note: Since the Atom Pro is always the master device, the clock pin will always be an output for both SHIFTIN and SHIFTOUT.

mode is a value (0 to 7) or a predefined constant that sets the incoming data conditions. See the table under SHIFTIN.
var is a variable where incoming data is stored. There can be multiple variables in a list, as shown in the example.
bits is an optional entry (1 - 32) defining the number of bits that will be written from each variable in the list. Default is 8 bits.

Note: Refer to the data sheet for the peripheral device to determine the proper settings.

Notes

See the Notes under SHIFTIN.

Examples

ant var byte
bat var word
cat var long
code setting values for ant, bat, cat
shiftout P2,P4,msbpre,[ant,bat\16,cat\32]

This program will output 8 bits from variable "ant", 16 bits from variable "bat", and 32 bits from variable "cat". Output will be at "normal" speed, msb first, and bits are sent at the start of clock pulses.

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.