nRF Connect SDK Fundamentals

Feedback
Feedback

If you are having issues with the exercises, please create a ticket on DevZone: devzone.nordicsemi.com
Click or drag files to this area to upload. You can upload up to 2 files.
Register

Exercise 1

v2.x.x

Controlling LEDs through UART

In the exercise, you will learn how to control the LEDs on your development kit through UART. We will utilize the UART controller that is connected by default to the interface MCU on your Nordic development kit to provide UART over USB.

We will set up the UART in asynchronous mode so that a callback function is called every time there is new data. We will set up the receive buffer size to 10 bytes and the receive timeout to 100 microseconds. This means when a byte is received and there is inactivity (no new data) after 100 microseconds, or 10 bytes is received, a UART_RX_RDY event is generated.

In this exercise, we will simply practice the steps covered in the UART Driver section to interact with the UART hardware in an asynchronous manner.

Exercise steps

Note

This exercise is not supported with the Thingy:53.

1. In the GitHub repository for this course, open the base code for this exercise, found in lesson5/fund_less5_exer1 of whichever version directory you are using (v2.x.x or v1.6.0-v1.9.1).

This code is based on the blinky sample.

2. Enable the serial driver (UART driver) by adding the following two lines in prj.conf.

As we mentioned before, the first line is usually enabled by default through the board’s devicetree, and you should therefore see it in gray (only when a build configuration has been added to the project). However, the second line is important to enable the asynchronous API of the serial driver.

Hover your mouse over the Kconfig symbol that is greyed out, to see the configuration conflict, see the image below.

3. Include the header file of the UART driver in main.c.

#include <zephyr/drivers/uart.h>

4. Get the device pointer of the UART hardware and verify that it is ready.

4.1 Get the device pointer of the UART hardware.

Remember, in nRF Connect SDK, any peripheral is accessed as a pointer of type struct device. 

const struct device *uart= DEVICE_DT_GET(DT_NODELABEL(uart0));

4.2 Verify that the UART device is ready.

	if (!device_is_ready(uart)){
		printk("UART device not ready\r\n");
		return 1 ;
	}

5. Get the device pointers of the LEDs through gpio_dt_spec and verify that it is ready.

5.1 Get the device pointer of the LEDs

Since we are using UART to control the LEDs (1-3) on the development kit, we need to get the device pointer for these as well. As we saw in Lesson 2, this is encapsulated in the API-specific structure gpio_dt_spec and can be retrieved using GPIO_DT_SPEC_GET().

Keep in mind that the nRF7002DK has only 2 LEDs. Therefore, we must include a compile-time if-condition which automatically checks the the DK you are building for. If it finds you are building for the nRF7002DK, it will run a slightly different code for this step, excluding the 3rd LED (LED2), to mitigate this issue.

#if defined (CONFIG_BOARD_NRF7002DK_NRF5340_CPUAPP)|| defined (CONFIG_BOARD_NRF7002DK_NRF5340_CPUAPP_NS)
static const struct gpio_dt_spec led0 = GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios);
static const struct gpio_dt_spec led1 = GPIO_DT_SPEC_GET(DT_ALIAS(led1), gpios);
#else
static const struct gpio_dt_spec led0 = GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios);
static const struct gpio_dt_spec led1 = GPIO_DT_SPEC_GET(DT_ALIAS(led1), gpios);
static const struct gpio_dt_spec led2 = GPIO_DT_SPEC_GET(DT_ALIAS(led2), gpios);
#endif

5.2 Verify that the LED devices are ready.

Since all the LEDs are associated with the same port, &gpio0, we only need to check one of the devices. 

	if (!device_is_ready(led0.port)){
		printk("GPIO device is not ready\r\n");
		return 1;
	}

6. Configure the GPIOs of the LEDs

As previously explained in step 5.1, there will be a compile-time if-condition added to make sure the code builds when using the nRF7002DK. 

#if defined (CONFIG_BOARD_NRF7002DK_NRF5340_CPUAPP)|| defined (CONFIG_BOARD_NRF7002DK_NRF5340_CPUAPP_NS)
	ret = gpio_pin_configure_dt(&led0, GPIO_OUTPUT_ACTIVE);
	if (ret < 0) {
		return 1 ; 
	}
	ret = gpio_pin_configure_dt(&led1, GPIO_OUTPUT_ACTIVE);
	if (ret < 0) {
		return 1 ;
	}
#else
ret = gpio_pin_configure_dt(&led0, GPIO_OUTPUT_ACTIVE);
	if (ret < 0) {
		return 1 ; 
	}
	ret = gpio_pin_configure_dt(&led1, GPIO_OUTPUT_ACTIVE);
	if (ret < 0) {
		return 1 ;
	}
	ret = gpio_pin_configure_dt(&led2, GPIO_OUTPUT_ACTIVE);
	if (ret < 0) {
		return 1 ;
	}
#endif

7. Define the application callback function for UART. For our simple LED application, we are only interested in the UART_RX_RDY and the UART_RX_DISABLED events related to receiving data over UART. For your own application, this might differ as we discussed in the UART driver section.

As previously explained in step 5.1, there will be a compile-time if-condition added to make sure the code builds when using the nRF7002DK. 

static void uart_cb(const struct device *dev, struct uart_event *evt, void *user_data)
{
	switch (evt->type) {

	case UART_RX_RDY:
	#if defined (CONFIG_BOARD_NRF7002DK_NRF5340_CPUAPP)|| defined (CONFIG_BOARD_NRF7002DK_NRF5340_CPUAPP_NS)
		if((evt->data.rx.len) == 1){

		if(evt->data.rx.buf[evt->data.rx.offset] == '1')
			gpio_pin_toggle_dt(&led0);
		else if (evt->data.rx.buf[evt->data.rx.offset] == '2')
			gpio_pin_toggle_dt(&led1);	
		}
	#else
	if((evt->data.rx.len) == 1){

		if(evt->data.rx.buf[evt->data.rx.offset] == '1')
			gpio_pin_toggle_dt(&led0);
		else if (evt->data.rx.buf[evt->data.rx.offset] == '2')
			gpio_pin_toggle_dt(&led1);
		else if (evt->data.rx.buf[evt->data.rx.offset] == '3')
			gpio_pin_toggle_dt(&led2);					
		}
#endif
	break;
	case UART_RX_DISABLED:
		uart_rx_enable(dev ,rx_buf,sizeof rx_buf,RECEIVE_TIMEOUT);
		break;
		
	default:
		break;
	}
}

Note

With if((evt->data.rx.len) == 1), we are assuming a terminal in char mode, which is the default terminal in nRF Connect for VS Code (nRF Terminal) and PuTTY. These two terminal by default, does not require you to press enter to send the date, hence do not send extra bytes.
On the other hand,  if you are using a serial terminal in “line mode”, you need to press enter to send the data, which typically sends two extra bytes “/r/n” (Depending on the terminal configuration). Therefore you need to change the condition to match the length of the data you are sending.

8. Register the UART callback function by calling the function uart_callback_set(). 

	ret = uart_callback_set(uart, uart_cb, NULL);
		if (ret) {
			return 1;
		}

9. Now let’s send some data over UART.

9.1 Define the transmission buffer, which is a buffer to hold the data to be sent over UART.

static uint8_t tx_buf[] =   {"nRF Connect SDK Fundamentals Course\n\r"
                             "Press 1-3 on your keyboard to toggle LEDS 1-3 on your development kit\n\r"};

9.2 Send the data over UART by calling uart_tx(). Since we are not using flow control, pass SYS_FOREVER_US to disable transmission timeout. This is not related to receiving timeout. 

	ret = uart_tx(uart, tx_buf, sizeof(tx_buf), SYS_FOREVER_US);
	if (ret) {
		return 1;
	}

10. Let’s start receiving data!

10.1 Define the receive buffer. For this simple exercise of controlling LEDs through UART, we will define a small buffer of size 10 of type uint8_t.

10.1.1 Define the size of the receive buffer. 

#define RECEIVE_BUFF_SIZE 10

10.1.2 Define the receive buffer and initialize its members to zeros. 

static uint8_t rx_buf[RECEIVE_BUFF_SIZE] = {0};

10.2 Define the receiving timeout period to be 100 microseconds. This means when a byte is received and there is inactivity (no new data) for 100 microseconds, a UART_RX_RDY event is generated. If you are going to use receive timeout in your application, pick a value that matches your application requirements. 

#define RECEIVE_TIMEOUT 100

10.3 Start receiving by calling uart_rx_enable() and pass it the address of the receive buffer.

	ret = uart_rx_enable(uart ,rx_buf,sizeof rx_buf,RECEIVE_TIMEOUT);
	if (ret) {
		return 1;
	}

11. Build the application and flash it on your development kit.

Testing

12. You should observe that the three LEDs on your development kit are all switched on. Using a serial terminal such as the integrated nRF Terminal or PuTTY, you should see the below output:

We are using the default baud rate (115200) and UART settings set in the devicetree. If you want to change that, you can do it using the UART API as explained earlier.

Writing a number from 1 to 3 in the serial emulator will toggle the corresponding LED on your development kit.

Important (Thingy:91)

If you are using a Thingy:91, LED1 is the red LED, LED2 is the green LED and LED3 is the blue LED.

The solution for this exercise can be found in the GitHub repository, lesson5/fund_less5_exer1_solution of whichever version directory you are using (v2.x.x or v1.6.0-v1.9.1).

v1.6.0 – v1.9.1

Controlling LEDs through UART

In the exercise, you will learn how to control the LEDs on your development kit through UART. We will utilize the UART controller that is connected by default to the interface MCU on your Nordic development kit to provide UART over USB.

We will set up the UART in asynchronous mode so that a callback function is called every time there is new data. We will set up the receive buffer size to 10 bytes and the receive timeout to 100 microseconds. This means when a byte is received and there is inactivity (no new data) after 100 microseconds, or 10 bytes is received, a UART_RX_RDY event is generated.

In this exercise, we will simply practice the steps covered in the UART Driver section to interact with the UART hardware in an asynchronous manner.

Exercise steps

1. In the GitHub repository for this course, open the base code for this exercise, found in lesson5/fund_less5_exer1 of whichever version directory you are using (v2.x.x or v1.6.0-v1.9.1).

This code is based on the blinky sample.

2. Enable the serial driver (UART driver) by adding the following two lines in prj.conf.

As we mentioned before, the first line is usually enabled by default through the board’s devicetree, and you should therefore see it in gray (only when a build configuration has been added to the project). However, the second line is important to enable the asynchronous API of the serial driver.

3. Include the header file of the UART driver in main.c.

#include <drivers/uart.h>

4. Get the device struct of the UART hardware. Remember, in nRF Connect SDK any peripheral is accessed as a pointer of type struct device. 

const struct device *uart = device_get_binding(DT_LABEL(DT_NODELABEL(uart0)));
if (uart== NULL) {
	printk("Could not find %s!\n\r",DT_LABEL(DT_NODELABEL(uart0)));
	return;
}

5. Since we are using UART to control the LEDs (1-3) on the development kit, we need to configure the GPIOs of these LEDs like we learned in Lesson 2.

5.1 Get C identifiers for the devicetree labels and properties’ values related to LEDs. 

#define LED0_NODE	DT_ALIAS(led0)
#define LED0		DT_GPIO_LABEL(LED0_NODE, gpios)
#define PIN0		DT_GPIO_PIN(LED0_NODE, gpios)
#define FLAG0		DT_GPIO_FLAGS(LED0_NODE, gpios)

#define LED1_NODE	DT_ALIAS(led1)
#define LED1		DT_GPIO_LABEL(LED1_NODE, gpios)
#define PIN1		DT_GPIO_PIN(LED1_NODE, gpios)
#define FLAG1		DT_GPIO_FLAGS(LED1_NODE, gpios)

#define LED2_NODE	DT_ALIAS(led2)
#define LED2		DT_GPIO_LABEL(LED2_NODE, gpios)
#define PIN2		DT_GPIO_PIN(LED2_NODE, gpios)
#define FLAG2		DT_GPIO_FLAGS(LED2_NODE, gpios)

5.2 Configure the LEDs.

	ret = gpio_pin_configure(leds, PIN0, GPIO_OUTPUT_ACTIVE | FLAG0);
	if (ret < 0) {
		return 1 ; 
	}
	ret = gpio_pin_configure(leds, PIN1, GPIO_OUTPUT_ACTIVE | FLAG1);
	if (ret < 0) {
		return 1 ;
	}
	ret = gpio_pin_configure(leds, PIN2, GPIO_OUTPUT_ACTIVE | FLAG2);
	if (ret < 0) {
		return 1 ;
	}

6. Define the application callback function for UART. For our simple LED application, we are only interested in the UART_RX_RDY and the UART_RX_DISABLED events related to receiving data over UART. For your own application, this might differ as we discussed in the UART driver section.

static void uart_cb(const struct device *dev, struct uart_event *evt, void *user_data)
{
	switch (evt->type) {

	case UART_RX_RDY:
		if((evt->data.rx.len) == 1){

		if(evt->data.rx.buf[evt->data.rx.offset] == '1')
			gpio_pin_toggle(leds,PIN0);
		else if (evt->data.rx.buf[evt->data.rx.offset] == '2')
			gpio_pin_toggle(leds,PIN1);
		else if (evt->data.rx.buf[evt->data.rx.offset] == '3')
			gpio_pin_toggle(leds,PIN2);					

}
		break;		
	case UART_RX_DISABLED:
		uart_rx_enable(dev ,rx_buf,sizeof rx_buf,RECEIVE_TIMEOUT);
		break;
		
	default:
		break;
	}
}

7. Register the UART callback function by calling the function uart_callback_set(). 

	ret = uart_callback_set(uart, uart_cb, NULL);
	if (ret) {
		return 1;
	}

8. Now let’s send some data over UART.

8.1 Define the transmission buffer, which is a buffer to hold the data to be sent over UART.

static uint8_t tx_buf[] =   {"nRF Connect SDK Fundamentals Course\n\r"
                             "Press 1-3 on your keyboard to toggle LEDS 1-3 on your development kit\n\r"};

8.2 Send the data over UART by calling uart_tx(). Since we are not using flow control, pass SYS_FOREVER_US to disable transmission timeout. This is not related to receiving timeout. 

	ret = uart_tx(uart, tx_buf, sizeof(tx_buf), SYS_FOREVER_US);
	if (ret) {
		return 1;
	}

9. Let’s start receiving data!

9.1 Define the receive buffer. For this simple exercise of controlling LEDs through UART, we will define a small buffer of size 10 of type uint8_t.

9.1.1 Define the size of the receive buffer. 

#define RECEIVE_BUFF_SIZE 10

9.1.2 Define the receive buffer and initialize its members to 0s. 

static uint8_t rx_buf[RECEIVE_BUFF_SIZE] = {0};

9.2 Define the receiving timeout period to be 100 ms. This means when a byte is received and there is inactivity (no new data) for 100 microseconds, a UART_RX_RDY event is generated. If you are going to use receive timeout in your application, pick a value that matches your application requirements. 

#define RECEIVE_TIMEOUT 100

9.3 Start receiving by calling uart_rx_enable() and pass it the address of the receive buffer.

ret = uart_rx_enable(uart, rx_buf, sizeof rx_buf, RECEIVE_TIMEOUT);
if (ret) {
    return 1;
}

10. Build the application and flash it on your development kit.

Testing

11. You should observe that the three LEDs on your development kit are all switched on. Using a serial terminal such as the integrated nRF Terminal or PuTTY, you should see the below output:

We are using the default baud rate (115200) and UART settings set in the devicetree. If you want to change that, you can do it using the UART API as explained earlier.

Writing a number from 1 to 3 in the serial emulator will toggle the corresponding LED on your development kit.

Important

If you are using a Thingy:91, LED1 is the red LED, LED2 is the green LED and LED3 is the blue LED.

The solution for this exercise can be found in the GitHub repository, lesson5/fund_less5_exer1_solution of whichever version directory you are using (v2.x.x or v1.6.0-v1.9.1).

Make sure to Log in or Register to save your progress

Back
Next
Register an account
Already have an account? Log in
(All fields are required unless specified optional)

  • 8 or more characters
  • Upper and lower case letters
  • At least one number or special character

Forgot your password?
Enter the email associated with your account, and we will send you a link to reset your password.