Hbusout

Syntax

Hbusout Control, { Address }, [ Variable {, Variable…} ]

or

Hbusout Variable

Overview

Transmit a value to the I2C bus using the microcontroller's on-board MSSP module, by first sending the control and optional address out of the clock pin (SCL), and data pin (SDA). Or alternatively, if only one parameter is included after the Hbusout command, a single value will be transmitted, along with an Ack reception.

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, variable, or expression.

The Hbusout command operates as an I2C master 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 0b10100000 or $A0. 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 clear to signify that we wish to write to the EEPROM. Note that this bit is automatically cleared by the Hbusout command, regardless of its initial value.

Example

' Send a byte to the I2C bus.
  Dim bVar1 as Byte
                                       ' We'll only read 8-bits
  Dim wAddress as Word
                                       ' 16-bit address required
  Symbol cControl = 0b10100000
                                       ' Target an EEPROM
  wAddress = 20
                                       ' Write to address 20
  bVar1 = 200
                                       ' The value place into address 20
  Hbusout cControl, wAddress, [bVar1] ' Send the byte to the EEPROM
  DelayMs 10
                                       ' Allow time for allocation of byte

Address, 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 above 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 sent to the bus depends on the size of the variables used. For example: -

Dim wWrd as Word
                           ' Create a Word size variable
Hbusout cControl, wAddress, [wWrd]

Will send a 16-bit value to the bus. While: -

Dim bVar1 as Byte
                           ' Create a Byte size variable
Hbusout cControl, wAddress, [bVar1]

Will send an 8-bit value to the bus.

Using more than one variable within the brackets allows differing variable sizes to be sent. For example: -

Dim bVar1 as Byte
Dim wWrd as Word
Hbusout cControl, wAddress, [bVar1, wWrd]

Will send two values to 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.

A string of characters can also be transmitted, by enclosing them in quotes: -

Hbusout cControl, wAddress, [ "Hello World", bVar1, wWrd ]

Using the second variation of the Hbusout command, necessitates using the low level commands i.e. HbStart, HbRestart, HbusAck, or HbStop.

Using the Hbusout command with only one value after it, sends a byte of data to the I2C bus, and returns holding the Acknowledge reception. This acknowledge indicates whether the data has been received by the slave device.

The Ack reception is returned in the PICmicro's CARRY flag, which is STATUS.0, and also System variable PP4.0. A value of zero indicates that the data was received correctly, while a one indicates that the data was not received, or that the slave device has sent a NAck return. You must read and understand the datasheet for the device being interfacing to, before the Ack return can be used successfully. An code snippet is shown below: -

' Transmit a byte to a 24LC32 serial EEPROM
  Dim PP4 as Byte System
  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
  Hbusout "A"
                           ' Send the value 65 to the bus
  If PP4.0 = 1 Then GoTo Not_Received ' Has Ack been received OK ?
  HbStop
                           ' Send a Stop condition
  DelayMs 10
                           ' Wait for the data to be entered into EEPROM matrix

Str modifier with Hbusout.

The Str modifier is used for transmitting a string of bytes from a byte array variable. A string is a set of bytes sized values that are arranged or accessed in a certain order. The values 1, 2, 3 would be stored in a string with the value 1 first, followed by 2 then followed by the value 3. A byte array is a similar concept to a string; it contains data that is arranged in a certain order. Each of the elements in an array is the same size. The string 1,2,3 would be stored in a byte array containing three bytes (elements).

Below is an example that sends four bytes from an array: -

Dim bMyArray[10] as Byte = "ABCD"  ' Create a 10 element byte array, pre-load it.
Hbusout 0b10100000, Address, [Str bMyArray \4]  ' Send 4-byte string.

Note that we use the optional \n argument of Str. If we didn't specify this, the program would try to keep sending characters until all 10 bytes of the array were transmitted. Since we do not wish all 10 bytes to be transmitted, we chose to tell it explicitly to only send the first 4 bytes.

The above example may also be written as: -

Dim bMyArray [10] as Byte
                             ' Create a 10 element byte array.
Str bMyArray = "ABCD"
                             ' Load the first 4 bytes of the array
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
Hbusout Str bMyArray\4
                             ' Send 4-byte string.
HbStop
                             ' Send a Stop condition

The above example, has exactly the same function as the previous one. The only differences are that the string is now constructed using the Str as a command instead of a modifier, and the low-level Hbus commands have been used.

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.

Hbusout 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 Hbusout 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.

See also : HbusAck, HbRestart, HbStop, Hbusin, HbStart.

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.