Positron Compiler Documentation

Hbusout2

Positron16 · Revision 1.1.3.5 · PDF pages 168–171

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

or

Hbusout2 Variable

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

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 Hbusout2 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 %10100000 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 Hbusout2 command, regardless of its initial value.

' Send a byte to the I2C bus.

  Dim MyByte as Byte                  ' We'll only read 8-bits
  Dim Address as Word                  ' 16-bit address required
  Symbol Control = %10100000           ' Target an EEPROM

  Address = 20                        ' Write to address 20
  MyByte = 200                        ' The value place into address 20
  Hbusout2 Control, Address, [MyByte] ' 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.

View original PDF page 168Open page in PDFOriginal PDF page 168

The value sent to the bus depends on the size of the variables used. For example: -

Dim MyWord as Word        ' Create a Word size variable
Hbusout2 Control, Address, [MyWord]

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

Dim MyByte as Byte        ' Create a Byte size variable
Hbusout2 Control, Address, [MyByte]

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 MyByte as Byte
Dim MyWord as Word
Hbusout2 Control, Address, [MyByte, MyWord]

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

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

Hbusout2 Control, Address, ["Hello World", MyByte, MyWord]

Using the second variation of the Hbusout2 command, necessitates using the low level commands i.e. HbStart2, HbRestart2, HbusAck2, or HbStop2.

Using the Hbusout2 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 microcontroller's CARRY flag, which is SR.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
  HbStart 2                    ' Send a Start condition
  Hbusout2 %10100000           ' Target an EEPROM, and send a Write command
  Hbusout2 0                  ' Send the HighByte of the address
  Hbusout2 0                  ' Send the LowByte of the address
  Hbusout2 "A"                 ' Send the value 65 to the bus
  If SRbits_C = 1 Then GoTo Not_Received   ' Has Ack been received OK?
  HbStop2                       ' Send a Stop condition
  DelayMs 10                  ' Wait for the data to be entered into EEPROM matrix
View original PDF page 169Open page in PDFOriginal PDF page 169

Hbusout2 Declares

Declare HSDA2_Pin Port.Pin Declares the port and pin used for the MSSP2 module’s data line (SDA). If the declare is not used in the program, it does not have a default to the pin and will give an error message, so make sure they are in the BASIC listing.

Declare HSCL2_Pin Port.Pin Declares the port and pin used for the MSSP2 module’s clock line (SCL). If the declare is not used in the program, it does not have a default to the pin and will give an error message, so make sure they are in the BASIC listing.

Declare Hbus2_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.

When the Hbusout2 command is used, the appropriate SDA and SCL Port and Pin are automatically setup as inputs if they have been previously declared. 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.

View original PDF page 170Open page in PDFOriginal PDF page 170

Str modifier with Hbusout2.

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 MyArray[10] as Byte      ' Create a 10 element byte array.
MyArray [0] = "A"           ' Load the first 4 bytes of the array
MyArray [1] = "B"           ' With the data to send
MyArray [2] = "C"
MyArray [3] = "D"
Hbusout2 %10100000, Address, [Str MyArray \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 MyArray[10] as Byte        ' Create a 10 element byte array.
Str MyArray = "ABCD"           ' Load the first 4 bytes of the array

HbStart2                       ' Send a Start condition
Hbusout2 %10100000             ' Target an EEPROM, and send a Write command
Hbusout2 0                    ' Send the HighByte of the address
Hbusout2 0                    ' Send the LowByte of the address
Hbusout2 Str MyArray\4         ' Send 4-byte string.
HbStop2                         ' 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.

See also : HbusAck2, HbRestart2, HbStop2, Hbusin2, HbStart2, HbusAck, HbRestart, HbStop, Hbusin, Hbusout, HbStart.

View original PDF page 171Open page in PDFOriginal PDF page 171