In this exercise, we will create a custom driver for the BME280 sensor using the Zephyr sensor API.
In this exercise, we decided to include our device driver as a Zephyr external module. The external module is the source code that could be integrated with Zephyr, but it is located outside of the Zephyr root directory. The idea of Zephyr modules is presented in Modules Documentation. Every Zephyr module shall include a module.yml file in a zephyr/ folder at the root of its location. Thanks to this, we can inform the Zephyr build system where to look for the module files.
As an environmental sensor will be used in this exercise, the device driver needs to have an API that provides measurement data for temperature, pressure, and humidity. We can always design our own API (what will be covered in Exercise 3 of this lesson), but fortunately, in the Zephyr system, we can find an already existing API that matches our needs – sensor API. The sensor driver API provides functionality to uniformly read, configure, and set up event handling for devices that take real-world measurements in meaningful units.
Exercise steps
Open the code base of the exercise by navigating to Create a new application in the nRF Connect for VS Code extension, select Copy a sample, and search for Lesson 7 Exercise 1. Make sure to use the version directory that matches the SDK version you are using.
Alternatively, in the GitHub repository for this course, go to the base code for this exercise, found in l7/l7_e1.
Notice that the exercise code is divided into 2 directories:
app– The target application. It reads sensor data and prints out measurements.custom_driver_module– The Zephyr external module containing the driver. We will focus mostly on this in the driver development lesson
l7_e1/
├─── app/
| ├─── boards/
│ ├─── src/
│ │ └─── main.c
│ ├──prj.conf
| └───CMakeLists.txt
|
└─── custom_driver_module/
├─── drivers/
├── sensor/
│ └─── custom_bme280/
│ └───custom_bme280.c
1. Create a binding file for the custom driver.
As a first step, we need to create the binding file.
Recall
The role of bindings was described in Devicetree in nRF Connect SDK Fundamentals.
Devicetree bindings define the compatible property. It declares requirements on the contents of devicetree nodes, and provides semantic information about the contents of valid nodes.
This time, we are creating a custom driver for the existing API, so there is no need to add any additional fields. We can copy the original binding for the bme280 sensor from <nRF Connect SDK Install Path>/zephyr/dts/bindings/sensor/bosch,bme280-spi.yaml and adjust the file name and content to match our custom driver.
Create the file zephyr,custom-bme280.yaml and input the following lines:
description: BME280 integrated environmental sensor
compatible: "zephyr,custom-bme280"
include: [sensor-device.yaml, spi-device.yaml]
In our external Zephyr module, we must keep a directory structure similar to that of the base Zephyr directory. Let’s save the file in our custom driver module, in dts/bindings/sensor like other sensor bindings in the Zephyr base directory, to follow the Zephyr file structure convention.
The directory structure should look like this:
custom_driver_module/
├─── drivers/
└─── dts/
├── bindings/
│ └─── sensor/
│ ├──zephyr,custom-bme280.yaml2. Implement a custom bme280 driver.
Now that we have a proper binding file in our Zephyr module, we can work on the driver itself. Most of the content has already been prepared, so we will focus only on the driver configuration and align with the binding and sensor API.
2.1 Define the driver compatible with the custom binding.
When using instance-based APIs, such as DEVICE_DT_INST_DEFINE(), we first need to define the driver compatibility as a C macro. This is done by setting DT_DRV_COMPAT to the lowercase-and-underscore version of the compatible that the device driver supports. Since our compatibility is "zephyr,custom-bme280", we will set DT_DRV_COMPAT to zephyr_custom_bme280.
Firstly, we declare the binding compatibility for our driver in the driver source file. (custom_bme280.c).
#define DT_DRV_COMPAT zephyr_custom_bme2802.2 Check if the devicetree contains any devices that are compatible with the driver.
We should also inform the user if the proper binding is missing by including:
#if DT_NUM_INST_STATUS_OKAY(DT_DRV_COMPAT) == 0
#warning "Custom BME280 driver enabled without any devices"
#endif3. Implement the driver-specific structures.
Next, we will define three missing driver-specific elements
- data structure
- configuration structure
- driver API
3.1 Define the data structure to store BME280 data.
Create a driver data structure—it is the same structure we used in Lesson 5. The driver will use the structure to store current sensor data on each sampling. Put the data structure into the driver`s code.
struct custom_bme280_data {
/* Compensation parameters */
uint16_t dig_t1;
int16_t dig_t2;
int16_t dig_t3;
uint16_t dig_p1;
int16_t dig_p2;
int16_t dig_p3;
int16_t dig_p4;
int16_t dig_p5;
int16_t dig_p6;
int16_t dig_p7;
int16_t dig_p8;
int16_t dig_p9;
uint8_t dig_h1;
int16_t dig_h2;
uint8_t dig_h3;
int16_t dig_h4;
int16_t dig_h5;
int8_t dig_h6;
/* Compensated values */
int32_t comp_temp;
uint32_t comp_press;
uint32_t comp_humidity;
/* Carryover between temperature and pressure/humidity compensation */
int32_t t_fine;
uint8_t chip_id;
};3.2 Define the structure to store sensor configuration.
Since our sensor is connected using the SPI bus, we will need to get its configuration to communicate properly with the device. We can define a structure for storing this.
struct custom_bme280_config {
struct spi_dt_spec spi;
};3.3 Define the sensor driver API.
Now it is time to define API for our driver. In this exercise, we decided to use the existing API from the sensor subsystem. In our case, we will use the polling method to get sensor data.
In this exercise we are using Zephyr sensor subsystem. It is well described in: Sensors.
Let’s take a look at the sensor API definition:
__subsystem struct sensor_driver_api {
sensor_attr_set_t attr_set;
sensor_attr_get_t attr_get;
sensor_trigger_set_t trigger_set;
sensor_sample_fetch_t sample_fetch;
sensor_channel_get_t channel_get;
sensor_get_decoder_t get_decoder;
sensor_submit_t submit;
};In our case, we only need the sample_fetch and channel_get functions. Skeletons of these are already prepared in custom_bme280.c (custom_bme280_sample_fetch() and custom_bme280_channel_get()).
We just need to implement the content, define the API structure, and connect them to the proper callbacks in the driver source code.
Add the following lines to custom_bme280.c.
static const struct sensor_driver_api custom_bme280_api = {
.sample_fetch = &custom_bme280_sample_fetch,
.channel_get = &custom_bme280_channel_get,
};4 Implement the API functions.
4.1 Populate the custom_bme280_sample_fetch() function.
This function should take in the device structure struct device and sensor_channel, use bme280_reg_read() to read out sensor measurements from the sensor and store them in custom_bme280_data.
struct custom_bme280_data *data = dev->data;
uint8_t buf[8];
int32_t adc_press, adc_temp, adc_humidity;
int size = 8;
int err;
__ASSERT_NO_MSG(chan == SENSOR_CHAN_ALL);
err = bme280_wait_until_ready(dev);
if (err < 0) {
return err;
}
err = bme280_reg_read(dev, PRESSMSB, buf, size);
if (err < 0) {
return err;
}
adc_press = (buf[0] << 12) | (buf[1] << 4) | (buf[2] >> 4);
adc_temp = (buf[3] << 12) | (buf[4] << 4) | (buf[5] >> 4);
adc_humidity = (buf[6] << 8) | buf[7];
bme280_compensate_temp(data, adc_temp);
bme280_compensate_press(data, adc_press);
bme280_compensate_humidity(data, adc_humidity);
return 0;4.2 Populate the custom_bme280_channel_get() function.
This function should take in the device structure struct device, the sensor_channel and sensor_value, and depending on the given channel (e.g pressure, humidity or temperature), calculate and store the value in sensor_value.
struct custom_bme280_data *data = dev->data;
switch (chan) {
case SENSOR_CHAN_AMBIENT_TEMP:
/*
* data->comp_temp has a resolution of 0.01 degC. So
* 5123 equals 51.23 degC.
*/
val->val1 = data->comp_temp / 100;
val->val2 = data->comp_temp % 100 * 10000;
break;
case SENSOR_CHAN_PRESS:
/*
* data->comp_press has 24 integer bits and 8
* fractional. Output value of 24674867 represents
* 24674867/256 = 96386.2 Pa = 963.862 hPa
*/
val->val1 = (data->comp_press >> 8) / 1000U;
val->val2 = (data->comp_press >> 8) % 1000 * 1000U +
(((data->comp_press & 0xff) * 1000U) >> 8);
break;
case SENSOR_CHAN_HUMIDITY:
/*
* data->comp_humidity has 22 integer bits and 10
* fractional. Output value of 47445 represents
* 47445/1024 = 46.333 %RH
*/
val->val1 = (data->comp_humidity >> 10);
val->val2 = (((data->comp_humidity & 0x3ff) * 1000U * 1000U) >> 10);
break;
default:
return -ENOTSUP;
}
return 0;5 Create the device driver definition
In this step, we need to design the helper macro (CUSTOM_BME280_DEFINE) responsible for device driver definition for a given device tree node. In the next step, we will use this macro for every enabled device tree node that is compatible with our driver. Macro contains three parts:
- Device`s data structure template- It creates a data structure instance for a given device tree node
- Devices`s configuration structure template- It creates a configuration structure instance for a given device tree node
- Devices`s definition macro (instance-based) -Create a device object from a given device tree node.
5.1 Prepare helper macro and add structures for each device driver instance.
This step defines data and configuration structure instances for a given device tree node. We are using default values for the data structure instance, which will change during driver operation. For the configuration structure instance, we need to get SPI from the given device tree node, using SPI_DT_SPEC_INST_GET, you can learn more about this macro in SPI interface documentation.
#define CUSTOM_BME280_DEFINE(inst) \
static struct custom_bme280_data custom_bme280_data_##inst; \
static const struct custom_bme280_config custom_bme280_config_##inst = { \
.spi = SPI_DT_SPEC_INST_GET(inst, SPIOP, 0 ), \
};5.2. Extend the macro by adding a definition using existing functions and structures.
Here we put all the parameters needed for DEVICE_DT_INST_DEFINE (this was covered in device model topic Device driver model). Let’s look into them and their role:
inst– instance, which is used to get device tree node id we are defining driver for, we take it from an input parameter of ourCUSTOM_BME280_DEFINEmacro helperinit_fn– Pointer to the device’s initialization function, we use already implemented driver’s initialization function (custom_bme280_init).pm– Pointer to the device’s power management resources. We don’t need it for this exercise.data– Pointer to the device’s data structure instance. We use the instance created by the template from the previous step.config– Pointer to the device’s configuration structure instance. We use the instance created by the template from the previous step.level– The device’s initialization level. We want to have the device initialized after kernel initialization.prio– The device’s priority within its initialization level. We use the default priority level for the sensor subsystem.API-Pointer to the device’s API structure. That is our device API created in step 3. We usecustom_bme280_apifor this parameter.
DEVICE_DT_INST_DEFINE(inst, \
custom_bme280_init, \
NULL, \
&custom_bme280_data_##inst, \
&custom_bme280_config_##inst, \
POST_KERNEL, \
CONFIG_SENSOR_INIT_PRIORITY, \
&custom_bme280_api); 5.3. Create the struct device for every status “okay” node in the devicetree.
DT_INST_FOREACH_STATUS_OKAY() expands to code that calls CUSTOM_BME280_DEFINE once for each enabled node with the compatible binding file determined by DT_DRV_COMPAT.
DT_INST_FOREACH_STATUS_OKAY(CUSTOM_BME280_DEFINE)6. Create the build system for the driver.
Kconfig and CMake are necessary parts of the Zephyr build system. We need to include them at each level of the drivers directory.
6.1. Populate the CMakeLists.txt file for the custom driver.
Create drivers/sensor/custom_bme280/CMakeLists.txt and add the following lines.
zephyr_library()
zephyr_library_sources(custom_bme280.c)zephyr_library() adds a library named after the folder it’s called in; in this case custom_bme280.
zephyr_library_sources() adds the file given as a parameter to the library.
6.2. Populate the Kconfig file for the custom driver.
Create drivers/sensor/custom_bme280/Kconfig and add the following lines
config CUSTOM_BME280
bool "Custom BME280 sensor"
default y
depends on DT_HAS_ZEPHYR_CUSTOM_BME280_ENABLED
select SPI
help
Enable custom BME280 driverHere, we define the Kconfig symbol CUSTOM_BME280_DRIVER , which, when enabled, will add the custom driver to the build (as we will do in the next step). The Kconfig symbol depends on DT_HAS_ZEPHYR_CUSTOM_BME280_ENABLED which just checks if the build devicetree has enabled this compatibility.
6.3. Add the custom_bme280 directory as a subdirectory in the sensor driver.
The custom_bme280 directory must be added as a subdirectory in drivers/sensor.
Create drivers/sensor/CMakeLists.txt and add the following line
add_subdirectory_ifdef(CONFIG_CUSTOM_BME280 custom_bme280)6.4 Add the custom driver as a subdirectory of the sensor driver.
Create drivers/sensor/Kconfig and add the following code snippet
if SENSOR
rsource "custom_bme280/Kconfig"
endif # SENSOR 6.5 Add the sensor directory to the build system structure.
Create drivers/CMakeLists.txt and add the following code snippet
add_subdirectory_ifdef(CONFIG_SENSOR sensor)6.6 Add the sensor submenu.
Create drivers/Kconfig and replace the code with the following code snippet
menu "Drivers"
rsource "sensor/Kconfig"
endmenu7. Create the Zephyr module definition.
7.1 Create a zephyr/module.yml file in the custom_driver_module folder and input the necessary configuration. Please notice that we put our dts directory into the Zephyr configuration by dts_root: .
build:
kconfig: Kconfig
cmake: .
settings:
dts_root: .7.2 Create CMakeLists.txt for our module in the root directory, l7_e1/customer_driver_module.
Include our module source directories
# Subdirectories
add_subdirectory(drivers)
# Include headers
zephyr_include_directories(drivers)7.3 Create the Kconfig file for our module in the root directory as well
rsource "drivers/Kconfig"Now, our custom driver module file structure should look like this
custom_driver_module/
├─── drivers/
├── sensor/
│ └─── custom_bme280/
│ | | ├──custom_bme280.c
│ | | ├──CMakeLists.txt
│ | | ├──Kconfig
│ | ├──CMakeLists.txt
│ | ├──Kconfig
│ ├──CMakeLists.txt
│ ├──Kconfig
├──CMakeLists.txt
├──Kconfig
└─── dts/
├── bindings/
│ └─── sensor/
│ ├──zephyr,custom-bme280.yaml
├─── zephyr/
| ├──module.yml
├──CMakeLists.txt
├──Kconfig8. Configure the project to use a custom driver.
Now that our Zephyr module containing a custom driver is ready, it is time to use it in the application.
8.1 Include the Zephyr module in the target application.
First, we need to tell Zephyr where to find our external module. We include it in the Zephyr modules list by modifying the CMakeLists.txt file in the app directory.
- EXTRA_ZEPHYR_MODULES – is a CMake list of absolute paths to the directories containing Zephyr modules. We can add our module by using list(APPEND …) command.
list(APPEND EXTRA_ZEPHYR_MODULES ${CMAKE_CURRENT_SOURCE_DIR}/../custom_driver_module )8.2 Next, we need to enable our custom driver in prj.conf. We will use the configuration parameters created in step 6.
CONFIG_SENSOR=y
CONFIG_CUSTOM_BME280=y8.3 Create a proper node definition in the overlay file corresponding to the board you are using. This time, our node should be compatible with our zephyr,custom-bme280 binding.
bme280: bme280@0 {
compatible = "zephyr,custom-bme280";
reg = <0>;
spi-max-frequency = <1000000>; // 1MHz
};
9. Use the custom driver implementation in the application.
In these steps, we will modify the main.c file in the target application, app/src, to use the custom driver implementation.
9.1 Get the device structure from the node label.
Add the following line to retrieve the device structure from the node label: bme280.
const struct device * dev = DEVICE_DT_GET(DT_NODELABEL(bme280));9.2 Define the structures to store the temperature, pressure, and humidity.
struct sensor_value temp_val, press_val, hum_val;9.3 Continuously read out sensor data using the sensor API calls.
In the while-loop, add the following code to continuously read the sensor data, using the sensor APIs sensor_sample_fetch() and sensor_channel_get().
err = sensor_sample_fetch(dev);
if (err < 0) {
LOG_ERR("Could not fetch sample (%d)", err);
return 0;
}
if (sensor_channel_get(dev, SENSOR_CHAN_AMBIENT_TEMP, &temp_val)) {
LOG_ERR("Could not get sample");
return 0;
}
if (sensor_channel_get(dev, SENSOR_CHAN_PRESS, &press_val)) {
LOG_ERR("Could not get sample");
return 0;
}
if (sensor_channel_get(dev, SENSOR_CHAN_HUMIDITY, &hum_val)) {
LOG_ERR("Could not get sample");
return 0;
}
LOG_INF("Compensated temperature value: %d", temp_val.val1);
LOG_INF("Compensated pressure value: %d", press_val.val1);
LOG_INF("Compensated humidity value: %d", hum_val.val1); 10. Build and flash the application to your board.
10.1 Connect BME280 sensor using Lesson5 – Exercise1 instructions.
Important
To build the project properly, make sure to create a build configuration for the app directory, not the root of the exercise directory.
When building from the command line, the command should look like this: west build app -b <board>
10.2 Build and flash the application. You should see the following terminal output:
[00:00:00.291,290] <dbg> custom_bme280: custom_bme280_init: ID OK
[00:00:00.303,253] <dbg> custom_bme280: custom_bme280_init: "bme280@0" OK
*** Booting nRF Connect SDK ***
*** Using Zephyr OS ***
[00:00:00.303,314] <inf> Lesson7_Exercise1: Lesson 7 - Exercise 1 started
[00:00:00.404,052] <inf> Lesson7_Exercise1: Compensated temperature value: 25
[00:00:00.404,052] <inf> Lesson7_Exercise1: Compensated pressure value: 98
[00:00:00.404,052] <inf> Lesson7_Exercise1: Compensated humidity value: 37
[00:00:01.608,184] <inf> Lesson7_Exercise1: Compensated temperature value: 25
[00:00:01.608,215] <inf> Lesson7_Exercise1: Compensated pressure value: 98
[00:00:01.608,215] <inf> Lesson7_Exercise1: Compensated humidity value: 37