Hbusin
Syntax
Variable = Hbusin Control, { Address }
or
Variable = Hbusin
or
Hbusin Control, { Address }, [ Variable {, Variable…} ]
or
Hbusin Variable
Overview
Receives a value from the I2C bus using the MSSP module, and places it into variable/s. If variations two or four (see above) are used, then No Acknowledge, or Stop is sent after the data. Variations 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 expression. Address may be a constant value or a variable expression.
The four variations of the Hbusin command may be used in the same BASIC program. The second and fourth types (see above) 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 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 MSSP 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 0b10100001 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 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 = Hbusin cControl, wAddress ' Read the byte from the EEPROMor
Hbusin 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 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, wAddressWill receive a 16-bit value from the bus. While: -
Dim MyByte as Byte ' Create a Byte size variable
MyByte = Hbusin cControl, wAddressWill 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, wAddress, [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 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 Hbus_Bitrate Constant 100, 400, 1000
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.
Declare HSDA_Pin Port.Pin For devices that have PPS (Peripheral Pin Select), the port and pin used for the data line (SDA) must be given, so that the compiler can setup the PPS SFRs before the program starts. This may be any valid port on the microcontroller, but check the datasheet to see if the Port is valid for the peripheral.
Declare HSCL_Pin Port.Pin For devices that have PPS (Peripheral Pin Select), the port and pin used for the clock line (SCL) must be given, so that the compiler can setup the PPS SFRs before the program starts. This may be any valid port on the microcontroller, but check the datasheet to see if the Port is valid for the peripheral.
Notes
Not all PICmicro™ devices contain an MSSP module, some only contain an SSP type, which only allows I2C slave operations. These types of devices may not be used with any of the HBUS commands. Therefore, always read and understand the datasheet for the PICmicro™ device used.
When the Hbusin command is used, the appropriate SDA and SCL Port and Pin are automatically setup as inputs. On devices without PPS (Peripheral Pin Select), the SDA, and SCL lines are predetermined as hardware pins on the PICmicro™ , however, on devices with PPS, the compiler sets up the appropriate SFRs using the HSDA_Pin and HSCL_Pin declares.
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 bArray[10] as Byte ' Create an array of 10 bytes
Dim bAddress as Byte ' Create a word sized variable
Hbusin 0b10100000, Address, [Str Array] ' Load data into all the array
'
' Load data into only the first 5 elements of the array
'
Hbusin 0b10100000, bAddress, [Str bArray\5]
HbStart ' Send a Start condition
Hbusout 0b10100000 ' 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 0b10100001 ' Target an EEPROM, and send a Read command
Hbusin Str bArray ' Load all the array with bytes received
HbStop ' Send a Stop conditionAn alternative ending to the above example is: -
Hbusin Str bArray\5 ' Load data into only the first 5 elements of the array
HbStop ' Send a Stop conditionSee also : HbusAck, HbRestart, HbStop, HbStart, Hbusout.
Important Note. The Hbus commands are now classed as legacy within the compiler, meaning they will not be supported for newer devices. This is because the new devices have so many different ways of performing I2C with their built-in peripherals, it would be a logistic nightmare to cater for all the differences per device family and still keep it simple for the user. Now that the Positron8 compiler has true procedures, it will be a straightforward case to create a set of libraries to use I2C from the chip’s hardware. The Bus commands and the I2Cin and I2Cout commands work just as good as the Hbus commands, and sometimes better.
