Hbusin
Syntax
Assignment Variable = Hbusin Control, { Address }
or
Assignment Variable = Hbusin
or
Hbusin Control, { Address }, [ Variable {, Variable…} ]
or
Hbusin Variable
Overview
Receives a value from the I2C bus using the MSSP1 module, and places it into variable/s. If syntax structures Two or Four (see above) are used, then No Acknowledge, or Stop is sent after the data. Syntax structures One and Three first send the control and optional address out of the clock pin (SCL), and data pin (SDA).
Parameters
Variable is a user defined variable or constant. 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.
The four variations of the Hbusin command may be used in the same BASIC program. The Second and Fourth syntax 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. HbStart, HbRestart, HbusAck, or HbStop. The First, and Third syntax types may be used to receive several values and designate each to a separate variable, or variable type.
The Hbusin command operates as an I2C master, using the microcontroller's MSSP1 module, 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 2 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 Hbusin command, regardless of its initial setting.
Example
' Receive a byte from the I2C bus and place it into variable Var1.
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 = Hbusin cControl, Address ' Read the byte from the EEPROMor
Hbusin 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 or Word). 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 MyWord as Word ' Create a Word size variable
MyWord = Hbusin cControl, AddressWill receive a 16-bit value from the bus. While: -
Dim MyByte as Byte ' Create a Byte size variable
MyByte = Hbusin cControl, AddressWill receive an 8-bit value from the bus.
Using the Third variation of the Hbusin command allows differing variable assignments. For example: -
Dim MyByte as Byte
Dim MyWord as Word
Hbusin cControl, Address, [MyByte, MyWord]Will receive two values from the bus, the first being an 8-bit value dictated by the size of variable MyByte 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 within the EEPROM.
The Second and Fourth syntax 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 HbStart, HbRestart, HbusAck, or HbStop, for example code.
Hbusin Declares
Declare HSDA_Pin Port.Pin Declares the port and pin used for the MSSP1 module’s data line (SDA). If the declare is not used in the program, it may not always default to the standard pin configuration, so make sure they are in the BASIC listing.
Declare HSCL_Pin Port.Pin Declares the port and pin used for the MSSP1 module’s clock line (SCL). If the declare is not used in the program, it may not always default to the standard pin configuration, so make sure they are in the BASIC listing.
Declare Hbus_Bitrate Constant 100, 400, 1000 etc. The standard speed for the I2C bus is 100KHz. Some devices use a higher bus speed of 400KHz. The above Declare allows the I2C bus speed to be increased or decreased. Use this Declare with caution, as too high a bit rate may exceed the device's specs, which will result in intermittent transactions, or in some cases, no transactions at all. The datasheet for the device used will inform you of its bus speed. The default bit rate is the standard 100KHz.
Notes.
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.
Str modifier with Hbusin
Using the Str modifier allows variations Three and Four of the Hbusin 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: -
Dim MyArray[10] as Byte ' Create an array of 10 bytes
Dim Address as Byte ' Create a word sized variable
Hbusin %10100000, Address, [Str MyArray] ' Load data into all the array
'
' Load data into only the first 5 elements of the array
'
Hbusin %10100000, Address, [Str MyArray\5]
HbStart ' Send a Start condition
Hbusout %10100000 ' Target an EEPROM, and send a WRITE command
Hbusout 0 ' Send the HighByte of the address
Hbusout 0 ' Send the LowByte of the address
HbRestart ' Send a Restart condition
Hbusout %10100001 ' Target an EEPROM, and send a Read command
Hbusin Str MyArray ' Load all the array with bytes received
HbStop ' Send a Stop conditionAn alternative ending to the above example is: -
Hbusin Str MyArray\5 ' Load data into only the first 5 elements of array
HbStop ' Send a Stop conditionSee also : HbusAck, HbRestart, HbStop, HbStart, Hbusout, HbusAck2, HbRestart2, HbStop2, HbStart2, Hbusout2.
