Latest Version: 2.0.2
This library provides a driver for the ST Micro HTS221, an ultra-compact sensor for relative humidity and temperature.
The HTS221 can interface over I²C or SPI. This library current addresses only I²C communications.
You can view the latest version of the library’s source code on GitHub. Click here to see information on other versions of this library.
To include this library in your project, add #require "HTS221.device.lib.nut:2.0.2" at the top of your device code
The constructor requires two entities to instantiate the class: an imp I²C bus object and the sensor’s I²C address in 8-bit form. The I²C bus must be already configured. The I²C address is optional.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| impI2cBus | Object | Yes | An imp I²C bus object. It must be configured before passing into the constructor |
| i2cAddress | Integer | No | The sensor’s I²C address in 8-bit form. Default: 0xBE |
#require "HTS221.device.lib.nut:2.0.2"
hardware.i2c89.configure(CLOCK_SPEED_400_KHZ);
tempHumid <- HTS221(hardware.i2c89);
The HTS221 can be configured in three different reading modes:
This method applies the mode you have chosen.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| mode | Integer | Yes | One of the following mode constants: HTS221_MODE.POWER_DOWN, HTS221_MODE.ONE_SHOT or HTS221_MODE.CONTINUOUS |
| dataRate | Integer | No | The requested output data rate (ODR) of the sensor in Hertz. Supported data rates are 0 (one-shot configuration), 1, 7 and 12.5Hz. Only required when HTS221_MODE.CONTINUOUS is selected. Default: 0 |
Integer — The applied ODR in Hertz.
// Configure sensor in one shot mode
tempHumid.setMode(HTS221_MODE.ONE_SHOT);
// Configure sensor in continuous mode
local dataRate = tempHumid.setMode(HTS221_MODE.CONTINUOUS, 7);
server.log(dataRate);
This method indicates which mode the sensor has been set to: HTS221_MODE.POWER_DOWN, HTS221_MODE.ONE_SHOT or HTS221_MODE.CONTINUOUS.
Integer — The sensor’s current mode.
local mode = tempHumid.getMode();
if (mode == HTS221_MODE.ONE_SHOT) {
server.log("In one shot mode");
}
if (mode == HTS221_MODE.CONTINUOUS) {
server.log("In continuous mode with a data rate of " + tempHumid.getDataRate() + "Hz");
}
if (mode == HTS221_MODE.POWER_DOWN) {
server.log("In power down mode");
}
This method indicates the sensor’s current output data rate (ODR) in Hertz.
Integer — The sensor’s current ODR.
local dataRate = tempHumid.getDataRate();
server.log(dataRate);
This method sets the sensor’s temperature and humidity resolution in terms of the number of samples of each value that are taken and then averaged when a reading is requested.
Setting each resolution is a request: the actual values applied are returned by the method.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| numTempSamples | Integer | Yes | The number of averaged temperature samples. Supported temperature sample rates are 2, 4, 8, 16, 32, 64, 128 and 256 |
| numHumidSamples | Integer | Yes | The number of averaged humidity samples. Supported humidity sample rates are 4, 8, 16, 32, 64, 128, 256 and 512 |
Table — the applied resolutions, accessed via the keys temperatureResolution and humidityResolution.
tempHumid.setResolution(8, 16);
This method retrieves the sensor’s current temperature and humidity resolution in terms of the number of samples of each value that are taken and then averaged when a reading is requested.
Table — the applied resolutions, accessed via the keys temperatureResolution and humidityResolution.
local res = tempHumid.getResolution();
server.log("Number of temperature samples: " + res.temperatureResolution);
server.log(" Number of humidity samples: " + res.humidityResolution);
This method configures the interrupt pin driver for a data-ready interrupt. The device starts with this disabled by default.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| enable | Boolean | Yes | Set true to enable the interrupt pin, or false to disable it again |
| options | Bitfield | No | Configuration options combined with the bitwise OR operator. See Options, below, for available values. Default: 0x00 |
| Option Constant | Description |
|---|---|
| HTS221_INT_PIN_ACTIVELOW | Interrupt pin is active-high by default. Use to set interrupt to active-low |
| HTS221_INT_PIN_OPENDRAIN | Interrupt pin driver push-pull by default. Use to set interrupt to open-drain |
Nothing.
// Enable interrupt, configure as push-pull, active-high.
tempHumid.configureDataReadyInterrupt(true);
// Enable interrupt, configure as open drain, active-low.
tempHumid.configureDataReadyInterrupt(true, HTS221_INT_PIN_ACTIVELOW | HTS221_INT_PIN_OPENDRAIN);
Use this method to determine what caused an interrupt: it returns a table that provides information about which interrupts are active. The content of this table is updated every one-shot reading, and after completion of every ODR cycle.
Table — Interrupt information via the following keys:
| Key | Description |
|---|---|
| humidity_data_available | true if new humidity data is available |
| temp_data_available | true if new humidity data is available |
// Check the interrupt source and clear the latched interrupt
local intSrc = tempHumid.getInterruptStatus();
// Log if new data is available
if (intSrc.humidity_data_available) server.log("New humidity data available");
if (intSrc.temp_data_available) server.log("New temperature data available");
This method executes a temperature and humidity reading operation. If a callback function is provided, the reading executes asynchronously and a results table is passed to the callback, otherwise the reading blocks until completed and the results table is returned.
The results table will contain either an error slot, which holds a description of the error if an error occurred during the reading process, or humidity and temperature slots, which contain the relative humidity and temperature in degrees Celsius if the reading was successful.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| callback | Function | No | A function that will be called when the reading has been taken. It is passed a reading results table (see above) |
Table — the reading result table (see above), or null if the result is to be delivered asynchronously.
tempHumid.read(function(result) {
if ("error" in result) {
server.error("An Error Occurred: " + result.error);
} else {
server.log(format("Current Humidity: %0.2f %s, Current Temperature: %0.2f °C", result.humidity, "%", result.temperature));
}
});
local result = tempHumid.read();
if ("error" in result) {
server.error("An Error Occurred: " + result.error);
} else {
server.log(format("Current Humidity: %0.2f %s, Current Temperature: %0.2f °C", result.humidity, "%", result.temperature));
}
This method provides you with the value of the sensor’s device ID register. This will be 0xBC for the HTS221.
Integer — The sensor’s device ID.
The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.
| Version | Source Code | Notes |
|---|---|---|
| 1.0.0 | GitHub | Initial release |
| 1.0.1 | GitHub | Fix error bug in read(); correctly structure table returned by read(); code tidy |
| 2.0.0 | GitHub | Fix bug in configureDataReadyInterrupt(); added tests; renamed library file to match new naming conventions |
| 2.0.1 | GitHub | Force reset before reading calibration data; more elegant sign extension |
| 2.0.1 | GitHub | Limit humidity readings to values between 0-100; fixed bug in read() one shot mode; moved static variables to constants |
This library is licensed under the MIT License.