Busin
Syntax
Assignment Variable = Busin Control, { Address }
or
Variable = Busin
or
Busin Control, { Address }, [ Variable {, Variable…} ]
or
Busin Variable
Overview
Receives a value from the I2C bus, and places it into variable/s. If versions two or four (see above) are used, then No Acknowledge, or Stop is sent after the data. Versions one and three first send the control and optional address out of the clock pin (SCL), and data pin (SDA).
Parameters
Control may be a constant value or a Byte sized variable expression. Address may be a constant value or a variable expression. Assignment Variable is a user defined variable or constant.
The four variations of the Busin command may be used in the same BASIC program. The second and fourth types are useful for simply receiving a single byte from the bus, and must be used in conjunction with one of the low level commands. i.e. Bstart, Brestart, BusAck, or Bstop. The first, and third types may be used to receive several values and designate each to a separate variable, or variable type.
The Busin command is a software implementation (bit-bashed) and operates as an I2C master, without using the microcontroller's MSSP peripheral, and may be used to interface with any device that complies with the 2-wire I2C protocol.
The most significant 7-bits of control byte contain the control code and the slave address of the device being interfaced with. Bit-0 is the flag that indicates whether a read or write command is being implemented.
For example, if we were interfacing to an external EEPROM such as the 24LC32, the control code would be %10100001 or $A1. The most significant 4-bits (1010) are the EEPROM's unique slave address. Bits 1 to 3 reflect the three address pins of the EEPROM. And bit-0 is set to signify that we wish to read from the EEPROM. Note that this bit is automatically set by the Busin command, regardless of its initial setting.
Example
' Receive a byte from the I2C bus and place it into variable MyByte.
Device = 24FJ64GA002 ' Select the device to compile for
Declare Xtal = 8
Declare SCL_Pin = PORTB.3 ' Select the pin for I2C SCL
Declare SDA_Pin = PORTB.4 ' Select the pin for I2C SDA
Dim MyByte as Byte ' We'll only read 8-bits
Dim Address as Word ' 16-bit address required
Symbol cControl %10100001 ' Target an EEPROM
Address = 20 ' Read the value at address 20
MyByte = Busin cControl, Address ' Read the byte from the EEPROMor
Busin cControl, Address, [MyByte]' Read the byte from the EEPROMAddress, is an optional parameter that may be an 8-bit or 16-bit value. If a variable is used in this position, the size of address is dictated by the size of the variable used (Byte, Word, or Dword). In the case of the previous EEPROM interfacing, the 24LC32 EEPROM requires a 16bit address. While the smaller types require an 8-bit address. Make sure you assign the right size address for the device interfaced with, or you may not achieve the results you intended.
The value received from the bus depends on the size of the variables used, except for variation three, which only receives a Byte (8-bits). For example: -
Dim MyWord as Word ' Create a Word size variable
MyWord = Busin cControl, AddressWill receive a 16-bit value from the bus. While: -
Dim MyByte as Byte ' Create a Byte size variable
MyByte = Busin cControl, AddressWill receive an 8-bit value from the bus.
Using the third variation of the Busin command allows differing variable assignments. For example: -
Dim MyByte as Byte
Dim MyWord as Word
Busin cControl, Address, [MyByte, MyWord]Will receive two values from the bus, the first being an 8-bit value dictated by the size of variable Var1 which has been declared as a byte. And a 16-bit value, this time dictated by the size of the variable MyWord which has been declared as a word. Of course, Bit type variables may also be used, but in most cases these are not of any practical use as they still take up a byte (8-bits) within the EEPROM.
The second and fourth variations allow all the subtleties of the I2C protocol to be exploited, as each operation may be broken down into its constituent parts. It is advisable to refer to the datasheet of the device being interfaced to fully understand its requirements. See section on Bstart, Brestart, BusAck, or Bstop, for example code.
Declares See Busout for declare explanations.
Notes.
When the Busout command is used, the appropriate SDA and SCL Port and Pin are automatically setup as inputs, and outputs.
Because the I2C protocol calls for an open-collector interface, pull-up resistors are required on both the SDA and SCL lines. Values of 1KΩ to 4.7KΩ will suffice.
You may imagine that it's limiting having a fixed set of pins for the I2C interface, but you should remember that several different devices may be attached to a single bus, each having a unique slave address. Which means there is usually no need to use up more than two pins on the microcontroller in order to interface to many devices.
Str modifier with Busin
Using the Str modifier allows variations three and four of the Busin command to transfer the bytes received from the I2C bus directly into a byte array. If the amount of received characters is not enough to fill the entire array, then a formatter may be placed after the array's name, which will only receive characters until the specified length is reached. An example of each is shown below: -
Device = 24FJ64GA002 ' Select the device to compile for
Declare Xtal = 8
Declare SCL_Pin = PORTB.3 ' Select the pin for I2C SCL
Declare SDA_Pin = PORTB.4 ' Select the pin for I2C SDA
Dim bArray[10] as Byte ' Create an array of 10 bytes
Dim Address as Byte ' Create a byte sized variable
Busin %10100000, Address, [Str bArray] ' Load data into all the array
'
' Load data into only the first 5 elements of the array
'
Busin %10100000, Address, [Str bArray\5]
Bstart ' Send a Start condition
Busout %10100000 ' Target an EEPROM, and send a WRITE command
Busout 0 ' Send the HighByte of the address
Busout 0 ' Send the LowByte of the address
Brestart ' Send a Restart condition
Busout %10100001 ' Target an EEPROM, and send a Read command
Busin Str bArray ' Load all the array with bytes received
Bstop ' Send a Stop conditionAn alternative ending to the above example is: -
Busin Str bArray\5 ' Load data into only the first 5 elements of the array
Bstop ' Send a Stop conditionSee also : BusAck, Bstart, Brestart, Bstop, Busout, HbStart, HbRestart, HbusAck, Hbusin, Hbusout.
