hal package¶
Note
Dealing with HAL is an advanced topic, and the documentation isn’t as good as it could be. Be prepared to read the code directly!
Generally, RobotPy users don’t need to interact much with the HAL package except in simulation.
hal_data¶
When running the robot code in simulation or in unit tests, anytime something needs to interact with the hardware, typically functions in the HAL are called. The simulated version of the HAL functions either set or get data to/from a giant dictionary that we call the ‘hal_data’.
To learn about the contents of the data in the dictionary, go to
hal-sim/hal_impl/data.py
and read the reset_hal_data
function.
I2C/SPI Simulation Helpers¶
Interacting with custom I2C and SPI devices requires custom code. Because we can’t predict what kind of data your device will return when you ask for it, the default simulation interfaces will discard all data written to the device, and raise an exception when you try to read from the device. If you don’t want to receive these errors, then you need to do the following:
- Create a simulation class that inherits from either
I2CSimBase
orSPISimBase
, and override the needed functions. - Create an instance of the class, and pass it as the
simPort
argument of the I2C or SPI object constructor
For a working example of how to do this, look at the constructor of the
ADXRS450_Gyro
, and its corresponding simulation interface
ADXRS450_Gyro_Sim found at hal-sim/hal_impl/spi_helpers.py
.
Note
The sim helper objects aren’t installed on the roborio, so you
should only import them if a simulated hal is running. You can use
the hal.isSimulation
function to determine this.
-
class
hal_impl.i2c_helpers.
I2CSimBase
[source]¶ Base class to use for i2c protocol simulators.
Has all functions that need to be implemented, but throws exceptions when data is asked of it. Will throw away set* function data, as most low-fidelity simulation will probably not care about such things.
-
readI2C
(port, deviceAddress, buffer, count)[source]¶ Reads data from the I2C device. To return data to your code, you need to write bytes to the
buffer
parameter. A simple example of returning 3 bytes might be:def readI2C(self, port, deviceAddress, buffer, count): buffer[:] = b'123' return len(buffer)
Returns: number of bytes read
-
transactionI2C
(port, deviceAddress, dataToSend, sendSize, dataReceived, receiveSize)[source]¶ Writes data to the I2C device and then reads from it. You can read bytes from the
dataToSend
parameter. To return data, you need to write bytes to thedata_received
parameter. object.A simple example of returning 3 bytes might be:
def transactionI2C(self, port, deviceAddress, dataToSend, sendSize, dataReceived, receiveSize): dataReceived[:] = b'123' return len(dataReceived)
Returns: number of bytes returned
-
-
class
hal_impl.spi_helpers.
SPISimBase
[source]¶ Base class to use for SPI protocol simulators.
Has all functions that need to be implemented, but throws exceptions when data is asked of it. Will throw away set* function data, as most low-fidelity simulation will probably not care about such things.
-
readSPI
(port, buffer, count)[source]¶ Reads data from the SPI device. To return data to your code, you need to write bytes to the
buffer
parameter. A simple example of returning 3 bytes might be:def readSPI(self, port, buffer, count): buffer[:] = b'123' return len(buffer)
Returns: number of bytes read
-
readSPIAutoReceivedData
(port, buffer, numToRead, timeout, status)[source]¶ Returns: number of bytes read
-
startSPIAutoTrigger
(port, digitalSourceHandle, analogTriggerType, triggerRising, triggerFalling, status)[source]¶
-
transactionSPI
(port, dataToSend, dataReceived, size)[source]¶ Writes data to the I2C device and then reads from it. You can read bytes from the
dataToSend
parameter. To return data, you need to write bytes to thedata_received
parameter. object.A simple example of returning 3 bytes might be:
def transactionSPI(self, port, dataToSend, dataReceived, size): dataReceived[:] = b'123' return len(dataReceived)
Returns: number of bytes returned
-