homechevron_rightDocschevron_rightTools & SDKschevron_rightFirmware Librarieschevron_rightZephyr Library

Zephyr Library

note-zephyr is the official Zephyr library for communicating with the Notecard over serial or I2C, packaged as a west module. In this article, you'll learn how to use note-zephyr to upgrade the Zephyr RTOS "blinky" example with Notecard communication!

See note-zephyr in action in these accelerator projects.

Overview

This example is designed to illustrate the ease of adding Notecard functionality to an existing application, by building on the original Zephyr sample, samples/basic/blinky.

Functionally, the modification slows down the processing loop from 1s to 10s, and submits a Note to Notehub indicating the current state of the onboard LED.

Requirements

Hardware

Software

Cloudware

Getting Set Up

Notehub.io

Before you can utilize this example, you must set up a free account (no credit card required) on Notehub.io . Once you have created your account, then you need to create a project to serve as an endpoint for the Notes that are tracking the state of the LED.

Once you have a project, you will need to update the define named PROJECT_UID in main.c with the UID of the project you have just created.

After the Notecard has connected to Notehub, you can look inside the project and see a device named zephyr-blink. The Notecard will be running in continuous mode, which will allow it to maintain a constant cellular connection. continuous mode offers the lowest latency possible for sending messages to Notehub, but it comes at the cost of battery life. Fortunately, this is typically not a concern while bench testing, because you are plugged into USB power.

To learn more about the Notecard modes and API, please visit our Essential Requests Walkthrough.

Cloning the Repository

This repository contains the note-c library as a submodule. Use the following command to clone both repositories simultaneously.

git clone https://github.com/blues/note-zephyr.git --recursive

If you cloned without the --recursive flag, then you can update the note-c submodule separately, using the following two commands:

git submodule init
git submodule update

Building the Dev Container

warning

This step is critical to ensure you correctly build the Dev Container image.

Linux:

To enable flashing and debugging from the container on Linux, you will need to provide access to the USB controller of the host machine.

Perform the following steps, in order to provide USB access:

  1. Open ./.devcontainer/devcontainer.json.

  2. Uncomment the runArgs section:

    // Uncomment the following section if your host machine is running Linux
"runArgs": [
    "--device=/dev/bus/usb/"
],
    note

    At the time of writing, it is not possible to share the host USB from Windows and Mac computers.

Windows/Mac:

Ensure Docker Desktop is running.

note

If you failed to properly update devcontainer.json before opening the Dev Container, you may need to purge your docker build cache before trying again.

$ 
docker system prune
WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all dangling images
  - all dangling build cache

Are you sure you want to continue? [y/N] y

Building and Running

Compiling

  1. Open this folder in VS Code.
  2. Reopen the folder in the Dev Container.
    1. Press the hotkey combination, Ctrl+Shift+P (Mac: Cmd+Shift+P).
    2. Select Dev Containers: Rebuild and Reopen in Container from the command palette drop-down menu.
  3. Build the binary using one of the following options:
    • Press the hotkey combination, Ctrl+Shift+B (Mac: Cmd+Shift+B).
    • Use the menu system:
      1. Select Terminal > Run Task... from the application menu.
      2. Select Zephyr: Build Application from the drop-down menu.
      3. When prompted, type examples/blinky and press enter.
note

If you see the following message, then you have failed to update the product UID in the sources, and the Notecard will not be linked with your Notehub project.

/workspaces/note-zephyr/src/main.c:26:9: note: '#pragma message: PRODUCT_UID is not defined in this example. Please ensure your Notecard has a product identifier set before running this example or define it in code here. More details at https://bit.ly/product-uid'
   26 | #pragma message "PRODUCT_UID is not defined in this example. Please ensure your Notecard has a product identifier set before running this example or define it in code here. More details at https://bit.ly/product-uid"
      |         ^~~~~~~

Flashing

Linux:

From the Dev Container, use the menu system:

  1. Select Terminal > Run Task... from the application menu.
  2. Select Zephyr: Flash Firmware (Container) from the drop-down menu.

Windows/Mac:

  1. Launch Debug Server (OpenOCD)

    A debugging server opens a port to receive both debug and program instructions. Then, it forwards those instructions to the target device via an in-circuit debugger and programmer, such as the STLINK-V3MINI.

    Execute the following command on your host machine, OUTSIDE the container:

    openocd --search /usr/share/openocd/scripts --file interface/stlink.cfg --command "transport select hla_swd" --file target/stm32l4x.cfg

  2. From the Dev Container, use the menu system:

    1. Select Terminal > Run Task... from the application menu.
    2. Select Zephyr: Flash Firmware (External) from the drop-down menu.
note

You must flash your device using the STLINK-V3MINI ; DFU is not supported.

Debugging

Collecting Serial Logs

LPUART has been assigned as the default console output of the Swan. Furthermore, the LPUART of the Swan is exposed via the JTAG connector. This means that all strings provided to printk() will surface through the serial port assigned to the STLINK-V3MINI. As long as the Swan has power (e.g. battery, VIN, etc.), then there is no need for an additional USB cable.

The serial port is configured at 115200 baud, 8-bits, no parity bit, and one (1) stop bit (i.e. 8-N-1 ).

Using Linux as an example, and assuming the STLINK is the only USB peripheral plugged into your machine. Then you can expect to find the serial port listed as /dev/ttyACM0.

GDB (OpenOCD via STLINK)

Linux:

  1. Select the appropriate debug configuation.
    • From the Run and Debug panel.
      1. Open the activity bar using one of the following options:
        • Press the hotkey combination, Ctrl+Shift+D (Mac: Cmd+Shift+D).
        • Select the bug and triangle icon.
      2. Expand the drop-down with the green triangle at the top of the Run and Debug panel.
        • Use the drop-down to confirm Swan Debug (Container) is selected.
  2. Launch the debugger using one of the following options:
    • Press green triangle at the top of the Run and Debug panel.
    • Select Run > Start Debugging from the application menu.
    • Press the function key, F5.

Windows/Mac:

  1. Launch Debug Server (OpenOCD)

    A debugging server opens a port to receive both debug and program instructions. Then, it forwards those instructions to the target device via an in-circuit debugger and programmer, such as the STLINK-V3MINI.

    Execute the following command on your host machine, OUTSIDE the container:

    openocd --search /usr/share/openocd/scripts --file interface/stlink.cfg --command "transport select hla_swd" --file target/stm32l4x.cfg

  2. Launch Debugger (GDB)

    A debugger is a piece of software that allows you to step through a binary on a line-by-line basis. When debugging an embedded device, the binary does not reside on the same machine as the debugger, so we need a server (e.g. OpenOCD) to relay the instructions to the remote binary.

    1. Select the appropriate debug configuation.
      • From the Run and Debug panel.
        1. Open the activity bar using one of the following options:
          • Press the hotkey combination, Ctrl+Shift+D (Mac: Cmd+Shift+D).
          • Select the bug and triangle icon.
        2. Expand the drop-down with the green triangle at the top of the Run and Debug panel.
          • Use the drop-down to confirm Swan Debug (External) is selected.
    2. Launch the debugger using one of the following options:
      • Press green triangle at the top of the Run and Debug panel.
      • Select Run > Start Debugging from the application menu.
      • Press the function key, F5.

Update Existing Zephyr App

Below are the minimum changes required to add the Notecard functionality to a pre-existing Zephyr application.

  1. Add the note-zephyr module to your application manifest. Below is an example of a west.yml file that adds the note-zephyr module to the application.
manifest:
  projects:
    - name: zephyr
      revision: main
      url: https://github.com/zephyrproject-rtos/zephyr
      import:
       name-allowlist:
          - hal_stm32
          - cmsis
    - name: note-zephyr
      path: modules/note-zephyr
      revision: main
      submodules: true
      url: https://github.com/blues/note-zephyr
    # your other modules here ...
note

It is required that submodules: true is present in the module's west.yml entry, as it depends on note-c.

  1. Run west update to fetch the note-zephyr module.

  2. In your application's prj.conf file, add the following:

# Required by `note-c`
CONFIG_NEWLIB_LIBC=y

CONFIG_BLUES_NOTECARD=y
# Optional: Enable logging
CONFIG_BLUES_NOTECARD_LOGGING=y
  1. You'll then need to ensure that your application's target device can communicate with the Notecard. This is done by adding the appropriate device tree overlay to your target.

I2C - overlay for a Feather MCU connected to a Notecarrier-F

&feather_i2c {
	status = "okay";

	notecard@17 {
		compatible = "blues,notecard";
		reg = <0x17>;
		status = "okay";
	};
};

Serial (UART) - overlay for a Feather MCU connected to a Notecarrier-F

&feather_serial {
	status = "okay";
	current-speed = <115200>;

	notecard {
		compatible = "blues,notecard";
		status = "okay";
	};
};
note

UART is not physically connected between the Notecard and the feather MCU, when using the Notecarrier-F . In order to use UART (serial), the following steps are required:

  • Set DFU switch to OFF, to isolate AUX_TX/AUX_RX from F_RX/F_TX, respectively.
  • Connect the following lines together with a jumper wire:
    • N_TX to F_RX.
    • N_RX to F_TX.
  1. Build and flash your application as usual. E.g. west build -b swan_r5 your_application && west flash

And with that, you're all set up and ready to utilize the Notecard in your existing Zephyr application.

Links