In this exercise, we will create a custom driver for the BME280 sensor using the Zephyr sensor API.

For this exercise, we will not be using the GitHub repository for this course but rather a different GitHub repository that is an example of a production-level nRF Connect SDK-based application: ncs-example-application.

We will be creating a west workspace using this example application.

Exercise steps

1. Set up the application as a west workspace.

1.1 In Visual Studio Code, go to the nRF Connect for VS Code extension window. Select Create a new application then select Browse nRF Connect SDK Add-on Index.

1.2 Select the nRF Connect SDK example application

1.3 Select whichever nRF Connect SDK version you are using

1.4 Select a location for the West workspace

Input the full path of where you want your application to be stored. Then press ‘Enter’

Note that the last operation will take several minutes to complete.

Alternatively, you can issue the following terminal commands which does the same thing as in step 1.

Issue the following commands, <version> should reflect which nRF Connect SDK version you are using

west init -m https://github.com/nrfconnect/ncs-example-application/ --mr <version> academy_workspace
cd academy_workspace
west update

Note that the last step, west update, will take several minutes to complete.

When the operation is finished, you should have the following file structure:

academy_workspace/
├─── .west/
│    └─── config
├─── bootloader/
├─── modules/
├─── ncs-example-application
     └── app/
         ├── CMakeLists.txt
         ├── prj.conf
         └── src/
             └── main.c  
     └── boards/
     └── drivers/                  
     └── dts/     
     └── include/      
     └── ...
├─── nrf/
├─── nrfxlib/
├─── test/
├─── tools/
├─── zephyr/ 

As you can see, we have pulled in nRF Connect SDK <version>, as well as the ncs-example-application repository, which is where we will be adding our code.

2. Create a custom binding for the sensor.

In academy_workspace/ncs-example-application/dts/bindings/sensor, we need to create a custom binding for our sensor.

Note: Since we are working in ncs-example-application, we will be omitting the <academy_workspace/ncs-example-application> of the full path going forward.

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]

3. Create the files for the custom driver

In drivers/sensor, create a directory and call it custom_bme280. This is for our custom driver, and will be populated in the following steps.

Create the following three files

• CMakeLists.txt
• Kconfig
• custom_bme280.c

Copy and paste the contents of the file custom_bme280_template.c found in l7/l7_e1 into custom_bme280.c, to serve as a template for the next steps.

4. Define the driver compatible from the custom binding.

custom_bme280.c is where we will reuse most of the code from Lesson 5.

When using instance-based APIs, such as DEVICE_DT_INST_DEFINE(), we first need to define the driver compatible as a C macro. This is done by setting DT_DRV_COMPAT to the lowercase-and-underscores version of the compatible that the device driver supports. Since our compatible is "custom,bme280", we will define DT_DRV_COMPAT to custom_bme280 in our driver C file.

#define DT_DRV_COMPAT zephyr_custom_bme280

5. Check if the devicetree contains any devices with the driver compatible.

#if DT_NUM_INST_STATUS_OKAY(DT_DRV_COMPAT) == 0
#warning "Custom BME280 driver enabled without any devices"
#endif

6. Define the data structures for data and config.

The sensor API requires the following structures, custom_bme280_config and custom_bme280_data respectively.

6.1 Define data structure to store BME280 data.

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;
};

6.2 Define data structure to store sensor configuration data.

This is where we will store the SPI bus used for communication with the sensor.

struct custom_bme280_config {
	struct spi_dt_spec spi;
};

7. Define the sensor driver API.

Define the sensor driver API custom_bme280_api, of type struct sensor_driver_api.

struct sensor_driver_api has the following members, and we will be using sample_fetch and channel_get.

__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;
};

7.1 Populate the custom_bme280_sample_fetch() function.

This function should take in the device structurestruct 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);

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

7.3 Define custom_bme280_api and configure the relevant members.

static const struct sensor_driver_api custom_bme280_api = {
	.sample_fetch = &custom_bme280_sample_fetch,
	.channel_get = &custom_bme280_channel_get,
};

8. Define a macro for the device driver instance.

Define a macro CUSTOM_BME280_DEFINE to create a device driver instance for the input parameter inst.

#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),							\
	};  																		\
	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);

The most important thing here is to understand in detail the contents and use of DEVICE_DT_INST_DEFINE(), which has the following signature

• inst – This is the instance number passed as a parameter to CUSTOM_BME280_DEFINE(inst).
• init_fn – This is the initializing function, called before the main() in the application is called. The other arguments level and prio can be used to manage the actual initialization order and priority of calling this init_fn at the time of the Zephyr boot up. In this exercise, we have defined custom_bme280_init() function as the initializing function where we configure the pins and initialize the SPI interface and the BME280 sensor.
• pm – This token is used to plug our device driver into the overall Zephyr power management system. You can use PM_DEVICE_DT_DEFINE to define a pm instance and implement the pm action events that are sent to your driver at the time of system power events. In this exercise, we do not implement this, so we set this to NULL.
• data – This token is used to pass a pointer to any additional mutable data that you want to pass between the driver and the app. In this exercise, we are passing &custom_bme280_data_##inst.
• config – This token is used to pass the device private constant config data, in this exercise &custom_bme280_config_##inst.
• level – This is the device’s initialization level, which can be PRE_KERNEL_1, PRE_KERNEL_2 or POST_KERNEL. We are passing POST_KERNEL, which is the same level as the SPIM device driver.
• prio – This is the device’s priority within its initialization level, which needs to be of lower priority than the SPIM driver to ensure it is initialized first. We are passing CONFIG_SENSOR_INIT_PRIORITY, which is the predefined sensor initialization priority.
• api – Pointer to the device’s API structure, which we defined ascustom_bme280_api.

9. Create the struct device for every status “okay” node in the devicetree.

DT_INST_FOREACH_STATUS_OKAY() expands to code which calls CUSTOM_BME280_DEFINE once for each enabled node with the compatible determined by DT_DRV_COMPAT.

DT_INST_FOREACH_STATUS_OKAY(CUSTOM_BME280_DEFINE)

10. Populate the CMakeLists.txt file for the custom driver.

In drivers/sensor/custom_bme280/CMakeLists.txt, 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 files given as parameter to the library.

11. Populate the Kconfig file for the custom driver.

In drivers/sensor/custom_bme280/Kconfig, 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 driver

Here we define the Kconfig symbol CUSTOM_BME280_DRIVER which, when enabled, will add the custom driver to the build. The Kconfig symbol depends on DT_HAS_ZEPHYR_CUSTOM_BME280_ENABLED which just checks if the build devicetree has enabled this compatible.

Now that we have created a custom driver, let’s test it out by adding it to our application. The application is found in the directory called app.

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

12.1 Add the custom driver as a subdirectory of the sensor driver.

Open drivers/sensor/CMakeLists.txt and replace the code with the following code snippet

add_subdirectory_ifdef(CONFIG_EXAMPLESENSOR example_sensor)
add_subdirectory_ifdef(CONFIG_CUSTOM_BME280 custom_bme280)

12.2 Add the custom driver as a subdirectory of the sensor driver.

Open drivers/sensor/Kconfig and replace the code with the following code snippet

if SENSOR
rsource "example_sensor/Kconfig"
rsource "custom_bme280/Kconfig"
endif # SENSOR 

13. Change the compatible property in the devicetree.

13.1 Add a boards directory to the application.

Create a directory called boards in app.

13.2 In the boards directory, app/boards, add the .overlay file corresponding to the board you are using.

&i2c0 {	status = "disabled";};
&spi0 {	status = "disabled";};
&i2c1 {	status = "disabled";};
	
&spi1 {
    compatible = "nordic,nrf-spim";
	status = "okay";
	pinctrl-0 = <&spi1_default>;
	pinctrl-1 = <&spi1_sleep>;
	pinctrl-names = "default", "sleep";
	cs-gpios = <&gpio0 25 GPIO_ACTIVE_LOW>;
	bme280: bme280@0 {
		compatible = "zephyr,custom-bme280";
		reg = <0>;
		spi-max-frequency = <125000>;
	};
};

&pinctrl {
	spi1_default: spi1_default {
		group1 {
				psels = <NRF_PSEL(SPIM_SCK, 0, 6)>,
						<NRF_PSEL(SPIM_MOSI, 0, 7)>,
						<NRF_PSEL(SPIM_MISO, 0, 26)>;
		};
	};

	spi1_sleep: spi1_sleep {
		group1 {
				psels = <NRF_PSEL(SPIM_SCK, 0, 6)>,
						<NRF_PSEL(SPIM_MOSI, 0, 7)>,
						<NRF_PSEL(SPIM_MISO, 0, 26)>;
				low-power-enable;
		};
	};
};

13.3 If you are using a board with a dual-core (nRF7002 DK, nRF5340 DK, nRF916x DK), add the .conf file corresponding to the board you are using

#UART1 is used for TF-M logging should be disabled
CONFIG_TFM_SECURE_UART=n
CONFIG_TFM_LOG_LEVEL_SILENCE=y

14. Enable the sensor API

Notice that in the prj.conf file, the sensor API is enabled through the Kconfig CONFIG_SENSOR

CONFIG_SENSOR=y

This will automatically bring in the custom_bme280 driver, if CONFIG_CUSTOM_BME280 is enabled, which depends on DT_HAS_CUSTOM_BME280_ENABLED, i.e if the device tree has a node with the custom, bme280 compatible with the status okay.

15. Clear the contents of main.c

In app/src/main.c, clear the contents of the file.

Copy and paste the contents of the file main_template.c found in l7/l7_e1 into main.c, to serve as a template for the next steps.

16. 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));

17. Continuously read out sensor data using the sensor API calls.

17.1 Define the structures to store the temperature, pressure and humidity.

struct sensor_value temp_val, press_val, hum_val;

17.2 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_chanel_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);

18. Build and flash the application to your board.

Add a build configuration for the board you are using.

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 v2.7.99-0ecb6f1ad487 ***
*** Using Zephyr OS v3.6.99-4f64a3afb9fd ***
[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