Busin
Syntax
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.
Parameters
Variable is a user defined variable or constant. Control may be a constant value or a Byte sized variable, or an expression. Address may be a constant value or a variable, or an expression.
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 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 0b10100001 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 Var1.
Dim bVar1 as Byte
' We'll only read 8-bits
Dim wAddress as Word
' 16-bit address required
Symbol cControl = 0b10100001 ' Target an EEPROM
wAddress = 20
' Read the value at address 20
bVar1 = Busin control, wAddress ' Read the byte from the EEPROMor
Busin cControl, wAddress, [ bVar1 ] ' 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, Long, or Dword). In the case of the previous EEPROM interfacing, the 24LC32 EEPROM requires a 16-bit 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 wWrd as Word
' Create a Word size variable
wWrd = Busin cControl, wAddressWill receive a 16-bit value from the bus. While: -
Dim bVar1 as Byte
' Create a Byte size variable
bVar1 = Busin cControl, wAddressWill receive an 8-bit value from the bus.
Using the third variation of the Busin command allows differing variable assignments. For example: -
Dim bVar1 as Byte
Dim wWrd as Word
Busin cControl, wAddress, [bVar1, wWrd]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 Wrd 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 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 must 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 PICmicro™, 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 = 16F1829
' Select the device to compile for
Declare Xtal = 16 ' Tell the compiler the device will be operating at 16MHz Dim bArray[10] as Byte
' Define an array of 10 bytes
Dim bAddress as Byte
' Create a byte sized variable
Busin 0b10100000, bAddress, [Str bArray] ' Load data into all the array
'
' Load data into only the first 5 elements of the array
'
Busin 0b10100000, bAddress, [Str bArray\5]
Bstart
' Send a Start condition
Busout 0b10100000
' 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 0b10100001
' 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 :